Moya 自定义插件开发指南:实现 PluginType 协议掌控网络请求全生命周期
Moya 自定义插件开发指南:实现 PluginType 协议掌控网络请求全生命周期
Moya 是一款用 Swift 编写的网络抽象层,其插件系统(Plugin)允许开发者在请求发送前、响应返回后等关键节点注入自定义逻辑,实现日志、鉴权、网络状态指示等横切关注点。本文以"用 UIAlertController 提示用户网络活动"为例,手把手讲解如何从零实现一个遵循 PluginType 协议的自定义插件,并结合源码剖析插件在 Moya 请求管线中的真实调用时机,帮助读者彻底掌握 Moya 的插件扩展机制。
一、认识 Moya 的插件体系
Moya 的插件用于修改请求与响应,或执行副作用。在开始写自定义插件之前,先理解插件在请求生命周期中的四个回调时机,这是 docs/Plugins.md 与 docs_CN/Plugins.md 中明确给出的核心模型:
prepare:Moya 已把TargetType解析成URLRequest之后执行,是发送前修改请求(例如添加 header)的机会;willSend:请求即将发送前执行,是检查请求并执行副作用(如日志)的机会;didReceive:收到响应之后执行,是检查响应并执行副作用的机会;process:在completion被调用之前执行,是对请求Result做最后修改的机会。
这四种能力统一收敛在 PluginType 协议中,源码位于 Sources/Moya/Plugin.swift。该协议定义了四个方法,并在 public extension PluginType 中为每个方法提供了默认空实现,这意味着自定义插件只需覆写自己关心的回调,其余方法自动获得"什么都不做"的默认行为:
public protocol PluginType {
/// Called to modify a request before sending.
func prepare(_ request: URLRequest, target: TargetType) -> URLRequest
/// Called immediately before a request is sent over the network (or stubbed).
func willSend(_ request: RequestType, target: TargetType)
/// Called after a response has been received, but before the MoyaProvider has invoked its completion handler.
func didReceive(_ result: Result<Moya.Response, MoyaError>, target: TargetType)
/// Called to modify a result before completion.
func process(_ result: Result<Moya.Response, MoyaError>, target: TargetType) -> Result<Moya.Response, MoyaError>
}
public extension PluginType {
func prepare(_ request: URLRequest, target: TargetType) -> URLRequest { request }
func willSend(_ request: RequestType, target: TargetType) { }
func didReceive(_ result: Result<Moya.Response, MoyaError>, target: TargetType) { }
func process(_ result: Result<Moya.Response, MoyaError>, target: TargetType) -> Result<Moya.Response, MoyaError> { result }
}
注意 willSend 收到的参数类型是 RequestType 协议而非 Alamofire 的 Request。这是 Moya 刻意的抽象设计——从 Sources/Moya/Plugin.swift 的注释可以看出,Moya 不希望插件感知到 Alamofire 的存在,因此用 RequestType 协议只暴露 request(URLRequest?)、sessionHeaders、authenticate 与 cURLDescription 等有限能力;Moya 内部通过 RequestTypeWrapper(见 Sources/Moya/RequestTypeWrapper.swift)把 Alamofire 的 Request 包装成该协议再传给插件。
二、自定义插件实战:RequestAlertPlugin
下面的示例来自 docs_CN/Examples/CustomPlugin.md,目标是把网络活动通知给用户:请求发送时弹出一个提示框展示请求的基本信息;当响应表明请求失败时,再让用户知道。(为示例简洁起见,我们暂时忽略"频繁弹窗打扰用户"的体验问题。)
2.1 第一步:创建遵循 PluginType 的类
首先创建一个遵循 PluginType 的类,并在初始化时接收一个视图控制器的引用(用于展示 UIAlertController):
final class RequestAlertPlugin: PluginType {
private let viewController: UIViewController
init(viewController: UIViewController) {
self.viewController = viewController
}
func willSend(_ request: RequestType, target: TargetType) {
}
func didReceive(_ result: Result<Moya.Response, MoyaError>, target: TargetType) {
}
}
由于 PluginType 的扩展默认实现了 prepare 与 process,这里只覆写 willSend 和 didReceive 即可满足需求。target: TargetType 参数意味着插件还能拿到当前请求对应的 Target 信息,可据此对不同类型的请求做差异化处理。
2.2 第二步:在 willSend 中展示"请求发送"提示框
当请求即将被发送时,我们向 willSend 添加功能:取出请求的 URL 字符串,创建带单个按钮的 UIAlertController 并弹出:
func willSend(_ request: RequestType, target: TargetType) {
//make sure we have a URL string to display
guard let requestURLString = request.request?.url?.absoluteString else { return }
//create alert view controller with a single action
let alertViewController = UIAlertController(title: "Sending Request", message: requestURLString, preferredStyle: .alert)
alertViewController.addAction(UIAlertAction(title: "OK", style: .default, handler: nil))
//and present using the view controller we created at initialization
viewController.present(viewControllerToPresent: alertViewController, animated: true)
}
这里的关键在于 request.request?.url?.absoluteString:RequestType.request 返回 URLRequest?,因此需要 guard let 解包;拿到 URL 后再转成 absoluteString 作为提示框消息展示给用户。
2.3 第三步:在 didReceive 中对失败响应弹出错误提示
最后,如果请求结果出错,在 didReceive 中实现错误提示框:
func didReceive(_ result: Result<Moya.Response, MoyaError>, target: TargetType) {
//only continue if result is a failure
guard case Result.failure(_) = result else { return }
//create alert view controller with a single action and messing displaying status code
let alertViewController = UIAlertController(title: "Error", message: "Request failed with status code: \(error.response?.statusCode ?? 0)", preferredStyle: .alert)
alertViewController.addAction(UIAlertAction(title: "OK", style: .default, handler: nil))
//and present using the view controller we created at initialization
viewController.present(viewControllerToPresent: alertViewController, animated: true)
}
didReceive 的 result 是 Result<Moya.Response, MoyaError>:Moya.Response 是 Moya 统一的响应封装(见 Sources/Moya/Response.swift),包含 statusCode、data 等字段;MoyaError 是 Moya 的错误类型(见 Sources/Moya/MoyaError.swift),可以携带底层错误与响应对象。这里用 guard case Result.failure(_) = result 只处理失败分支,成功时直接返回。示例中的 error.response?.statusCode 取的是错误携带的响应状态码(若错误不含响应则回退为 0)。
2.4 接入 Provider:让插件生效
自定义插件写好之后,只需在创建 MoyaProvider 时通过 plugins 参数注册即可。这与 Moya 内置插件的使用方式完全一致(参见 docs_CN/Plugins.md 中 NetworkLoggerPlugin 的用法):
let provider = MoyaProvider<GitHub>(plugins: [RequestAlertPlugin(viewController: self)])
MoyaProvider 的初始化器将插件列表保存在 plugins: <a href="https://link.gitcode.com/i/b84605ad6d96a1dca7291ad8f0efbfb7" target="_blank">PluginType] 属性中(见 [Sources/Moya/MoyaProvider.swift),后续每次请求都会按数组顺序遍历调用所有插件。Moya 官方内置了多种可开箱即用的插件,包括基于 URLCredential 的 CredentialsPlugin(Sources/Moya/Plugins/CredentialsPlugin.swift)、自动注入 Authorization 头的 AccessTokenPlugin(Sources/Moya/Plugins/AccessTokenPlugin.swift)、管理网络活动指示器的 NetworkActivityPlugin(Sources/Moya/Plugins/NetworkActivityPlugin.swift)以及日志插件 NetworkLoggerPlugin(Sources/Moya/Plugins/NetworkLoggerPlugin.swift),自定义插件与它们遵循同一套协议,可自由组合使用。
三、源码视角:插件回调究竟在何时被触发
理解了怎么写插件,再深入源码看清这些回调的真实触发时机,能帮助开发者在正确的回调里做正确的事。
3.1 willSend 与 didReceive 的调用链
从 Sources/Moya/MoyaProvider+Internal.swift 可以看到完整的调用链:
- 请求发送前,
sendRequest/sendUploadMultipart/sendDownloadRequest等私有方法会构造MoyaRequestInterceptor,并在其willSend闭包(setup(interceptor:with:and:),L173-L180)中把 Alamofire 的Request包装成RequestTypeWrapper,然后逐个调用所有插件的willSend; - 响应返回后,
sendAlamofireRequest的completionHandler(L277-L295)先把原始响应通过convertResponseToResult转换为Result<Moya.Response, MoyaError>,再plugins.forEach { $0.didReceive(result, target: target) }通知所有插件; - 最终
completion调用前,requestNormal中的pluginsWithCompletion(L28-L31)会用plugins.reduce把每个插件的process串起来,前一个插件的处理结果作为后一个插件的输入,实现对最终Result的链式修改。
值得注意的是,stub(模拟请求)场景下插件同样会被调用:createStubFunction(L114-L150)和 notifyPluginsOfImpendingStub(L153-L163)中都有对 prepare/willSend/didReceive 的调用,说明插件在真机请求与本地 stub 两种模式下行为一致。
3.2 测试用例给出的验证范式
仓库测试 Tests/MoyaTests/TestPlugin.swift 中的 TestingPlugin 是理解插件契约的优秀范本,它同时实现了全部四个回调:
prepare给请求头添加"prepared": "yes",返回修改后的URLRequest;willSend里检查request.request?.allHTTPHeaderFields?["prepared"] == "yes",用于验证prepare一定先于willSend执行;didReceive记录result供断言;process把成功响应的statusCode改写为-1,验证插件能改写最终结果。
这四条断言分别对应了插件协议最重要的时序与数据流约定,编写自定义插件时可以参照此范式设计自己的验证逻辑。
四、进阶:利用 prepare 实现请求级横切逻辑
willSend/didReceive 适合做"观察型"副作用,而 prepare 与 process 则允许插件直接修改请求与结果。上文示例插件未覆写这两个方法,但它们是自定义插件最常用的扩展点。仓库文档 docs_CN/Examples/AuthPlugin.md 给出了一个典型的 prepare 用例——在请求头中注入 JWT:
struct AuthPlugin: PluginType {
let token: String
func prepare(_ request: URLRequest, target: TargetType) -> URLRequest {
var request = request
request.addValue("Bearer " + token, forHTTPHeaderField: "Authorization")
return request
}
}
let provider = MoyaProvider<Target>(plugins: [AuthPlugin(token: "eyeAm.AJsoN.weBTOKen")])
该文档还演示了更复杂的场景:通过扩展 TargetType 定义 AuthorizedTargetType 协议,让插件在 prepare 中结合 tokenClosure 与 target.needsAuth 判断,从而支持"动态获取 token、仅部分请求需要鉴权"的精细化控制。这套模式与 Moya 内置的 AccessTokenPlugin 实现思路一致,可作为自定义请求修饰插件的通用范式。
五、注意事项与最佳实践
原文档在结尾特别注明了一个真实存在的坑:
Please note that this example will usually fail since presenting an alert twice on the same view controller is not allowed.
在同一个视图控制器上连续弹出两个提示框是不被允许的,因此上面这个"每次请求都弹窗"的示例在实际运行中常常会崩溃或表现异常——它更多是教学演示而非生产代码。由此引申出自定义插件的几条实践建议:
- 避免在主线程外操作 UI:
willSend/didReceive的触发线程取决于MoyaProvider的callbackQueue配置,若涉及UIAlertController、UIApplication等 UI 操作,应在DispatchQueue.main.async中执行,或通过callbackQueue: .main指定回调队列; - 副作用要轻量、可组合:插件列表是顺序遍历的,
process还会链式传递结果,因此插件内应避免阻塞耗时操作,且注意多个插件对同一请求/结果的修改顺序; - 用
guard尽早退出:如示例中guard let requestURLString、guard case Result.failure(_)所示,不满足条件时直接return,保持回调逻辑清晰; - 在非 UI 场景优先使用成熟方案:如果只是需要日志、网络活动指示或鉴权,应优先选用 Moya 内置插件,自定义插件用于内置方案覆盖不到的业务横切逻辑。
结语
通过本文,我们从零实现了一个 RequestAlertPlugin,完整经历了"定义 PluginType 类 → 覆写 willSend/didReceive → 注册进 MoyaProvider"的自定义插件开发流程,并从 Sources/Moya/MoyaProvider+Internal.swift 的源码与 Tests/MoyaTests/TestPlugin.swift 的测试中验证了四个回调的真实触发时机与数据流。Moya 的插件体系以极小的协议面提供了极高的扩展自由度,无论是日志、鉴权、统计上报还是 UI 提示,都可以通过实现 PluginType 优雅地融入既有网络层,而不必侵入任何业务请求代码。更多示例可继续阅读 docs_CN/Plugins.md、docs_CN/Examples/AuthPlugin.md 以及 docs_CN/Examples/CustomPlugin.md。