Moya 自定义插件开发指南:实现 PluginType 协议掌控网络请求全生命周期

原创2026-09-21 23:07:571,951 阅读
文章标签:开发工具

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.

在同一个视图控制器上连续弹出两个提示框是不被允许的,因此上面这个"每次请求都弹窗"的示例在实际运行中常常会崩溃或表现异常——它更多是教学演示而非生产代码。由此引申出自定义插件的几条实践建议:

  1. 避免在主线程外操作 UI:willSend/didReceive 的触发线程取决于 MoyaProvider 的 callbackQueue 配置,若涉及 UIAlertController、UIApplication 等 UI 操作,应在 DispatchQueue.main.async 中执行,或通过 callbackQueue: .main 指定回调队列;
  2. 副作用要轻量、可组合:插件列表是顺序遍历的,process 还会链式传递结果,因此插件内应避免阻塞耗时操作,且注意多个插件对同一请求/结果的修改顺序;
  3. 用 guard 尽早退出:如示例中 guard let requestURLString、guard case Result.failure(_) 所示,不满足条件时直接 return,保持回调逻辑清晰;
  4. 在非 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。

登录后查看全文
Moya