Moya 插件机制完全指南:PluginType 协议、内置插件与自定义插件实战

原创2026-09-21 20:01:011,349 阅读
文章标签:开发工具

Moya 插件机制完全指南:PluginType 协议、内置插件与自定义插件实战

导读

Moya 的插件(Plugin)体系是其在网络请求生命周期中注入横切逻辑的核心机制:通过实现 PluginType 协议,开发者可以在请求发送前编辑请求、在响应到达前后执行副作用,甚至修改最终返回给调用方的 Result。本文以 Moya 官方文档(docs_CN/Plugins.md)为主体,结合仓库源码与测试用例,系统讲解插件生命周期、三个内置插件(身份认证、网络活动指示器、日志记录)的完整配置,以及如何编写自定义插件实现鉴权、告警、日志接入等真实场景需求。


一、插件生命周期:四个回调点

Moya 的插件被用来编辑请求、响应以及执行副作用。所有插件都遵循 PluginType 协议,该协议定义了四个回调方法,分别对应请求生命周期的不同阶段:

回调方法 触发时机 典型用途
prepare(_:target:) Moya 已经将 TargetType 解析成 URLRequest 之后、请求发送之前执行 编辑请求,例如添加 headers
willSend(_:target:) 请求将要发送前执行(stub 请求同样会触发) 检查请求、执行副作用,例如日志记录
didReceive(_:target:) 接收到响应后、completion 被调用前执行 检查响应、执行副作用,例如隐藏网络活动指示器
process(_:target:) 在 completion 被调用前执行 对 request 的 Result 进行任意编辑(如统一错误处理、重试前的转换)

从源码看,PluginType 协议中的每个方法都带有默认实现(Plugin.swift),因此自定义插件时不必实现全部四个方法,只需覆写需要的回调即可——例如 prepare 默认原样返回 URLRequest,process 默认原样返回 Result。

插件在 Provider 内部的实际调用链

要理解这四个回调的真实执行顺序,可以阅读 MoyaProvider+Internal.swift 中的请求流水线:

  1. requestNormal 先通过 endpointClosure 与 requestClosure 得到 URLRequest,随后在回调链上包装一层 pluginsWithCompletion:所有插件按注册顺序依次调用 process 折叠处理 Result,处理结果再交给真正的 completion(见 MoyaProvider+Internal.swift):
    let pluginsWithCompletion: Moya.Completion = { result in
        let processedResult = self.plugins.reduce(result) { $1.process($0, target: target) }
        completion(processedResult)
    }
    
  2. 发送前,interceptor(target:) 使用 plugins.reduce 依次调用每个插件的 prepare 编辑 URLRequest(见 MoyaProvider+Internal.swift),随后在 setup(interceptor:with:and:) 中统一触发所有插件的 willSend(见 MoyaProvider+Internal.swift)。
  3. 响应到达后,sendAlamofireRequest 的 completionHandler 将原始响应转换为 Result<Moya.Response, MoyaError>,并遍历所有插件调用 didReceive(见 MoyaProvider+Internal.swift)。
  4. 即便使用 stub(模拟)响应,createStubFunction 与 notifyPluginsOfImpendingStub 同样会依次触发 prepare、willSend、didReceive,保证插件在测试环境下行为一致(见 MoyaProvider+Internal.swift)。

另外注意 willSend 收到的参数类型是 RequestType 协议而非 Alamofire 的 Request——Moya 刻意用该协议封装,避免插件层泄漏 Alamofire 抽象(Plugin.swift)。RequestType 暴露了 request(URLRequest?)、sessionHeaders、authenticate(username:password:persistence:)、authenticate(with:) 与 cURLDescription 等能力。


二、在 Provider 中启用插件

插件在构造 MoyaProvider 时通过 plugins 参数声明。MoyaProvider 的初始化方法签名如下(见 MoyaProvider.swift):

public init(endpointClosure: @escaping EndpointClosure = MoyaProvider.defaultEndpointMapping,
            requestClosure: @escaping RequestClosure = MoyaProvider.defaultRequestMapping,
            stubClosure: @escaping StubClosure = MoyaProvider.neverStub,
            callbackQueue: DispatchQueue? = nil,
            session: Session = MoyaProvider<Target>.defaultAlamofireSession(),
            plugins: [PluginType] = [],
            trackInflights: Bool = false)

最小使用示例(对应原文档示例,plugins 参数接受插件数组,可同时注册多个插件):

let provider = MoyaProvider<GitHub>(plugins: [NetworkLoggerPlugin(verbose: true)])

版本说明:NetworkLoggerPlugin(verbose: true) 属于早期 API。当前仓库(Moya 13+)中 NetworkLoggerPlugin 改为通过 configuration 构造(见下文“日志记录插件”小节),等价写法为 NetworkLoggerPlugin(configuration: Configuration(logOptions: .verbose)) 或直接使用类属性 NetworkLoggerPlugin.verbose。以当前仓库 Sources/Moya/Plugins/NetworkLoggerPlugin.swift 的实现为准。


三、内置插件一:身份认证(CredentialsPlugin)

身份认证插件允许用户给每个请求赋值一个可选的 URLCredential。它的实现非常简洁(见 Sources/Moya/Plugins/CredentialsPlugin.swift):初始化时接收一个 (TargetType) -> URLCredential? 闭包,在 willSend 阶段取出凭据并通过 request.authenticate(with:) 附加到请求上;若闭包返回 nil 则不做任何操作:

public final class CredentialsPlugin: PluginType {
    public typealias CredentialClosure = (TargetType) -> URLCredential?
    let credentialsClosure: CredentialClosure

    public init(credentialsClosure: @escaping CredentialClosure) {
        self.credentialsClosure = credentialsClosure
    }

    public func willSend(_ request: RequestType, target: TargetType) {
        if let credentials = credentialsClosure(target) {
            _ = request.authenticate(with: credentials)
        }
    }
}

典型用法:根据 TargetType 动态返回凭据(例如登录后从钥匙串读取用户名密码构造 URLCredential):

let provider = MoyaProvider<GitHub>(plugins: [
    CredentialsPlugin { target in
        switch target {
        case .userProfile: return URLCredential(user: "moya", password: "password", persistence: .forSession)
        default: return nil
        }
    }
])

注意:该插件负责为请求附加 URLCredential,适用于 HTTP Basic/Digest 认证等场景;若你需要的是为请求添加 Authorization header(如 JWT/Bearer Token),请参考下文“自定义插件”中的 AuthPlugin 示例。


四、内置插件二:网络活动指示器(NetworkActivityPlugin)

在 iOS 开发中,一个非常常见的需求是:网络请求进行时显示状态栏网络活动指示器,请求结束时将其移除。Moya 提供的 NetworkActivityPlugin 正是为此设计的——它在请求开始和结束时分别回调,你可以用它维护“进行中的请求数”,并据此显示/隐藏指示器。

该插件的核心是一个 (NetworkActivityChangeType, TargetType) -> Void 闭包(见 Sources/Moya/Plugins/NetworkActivityPlugin.swift):

public enum NetworkActivityChangeType {
    case began, ended
}

public final class NetworkActivityPlugin: PluginType {
    public typealias NetworkActivityClosure = (_ change: NetworkActivityChangeType, _ target: TargetType) -> Void
    let networkActivityClosure: NetworkActivityClosure

    public init(networkActivityClosure: @escaping NetworkActivityClosure) {
        self.networkActivityClosure = networkActivityClosure
    }

    public func willSend(_ request: RequestType, target: TargetType) {
        networkActivityClosure(.began, target)
    }

    public func didReceive(_ result: Result<Moya.Response, MoyaError>, target: TargetType) {
        networkActivityClosure(.ended, target)
    }
}
  • 请求即将开始时触发 willSend,回调 .began;
  • 响应到达时触发 didReceive,回调 .ended——注意源码注释特别指出“即使请求被取消也会触发”(见 NetworkActivityPlugin.swift),这保证了计数不会泄漏。

使用示例:

let networkActivityPlugin = NetworkActivityPlugin { change, _ in
    switch change {
    case .began:
        UIApplication.shared.isNetworkActivityIndicatorVisible = true
    case .ended:
        UIApplication.shared.isNetworkActivityIndicatorVisible = false
    }
}
let provider = MoyaProvider<GitHub>(plugins: [networkActivityPlugin])

若同时发起多个请求,建议在闭包内维护计数器(began 自增、ended 自减),仅在计数归零时隐藏指示器,避免一个请求结束后提前隐藏。


五、内置插件三:日志记录(NetworkLoggerPlugin)

开发期间将网络活动记录到控制台非常有用——可以记录发送和接收的请求 URL,也可以记录每个请求和响应的完整 header、方法、请求体。NetworkLoggerPlugin 是 Moya 内置插件中最复杂的一个,可按需配置日志的详细程度、是否输出 curl 命令、自定义输出函数与数据格式化函数。

5.1 基本使用

// 使用默认配置
let provider = MoyaProvider<GitHub>(plugins: [NetworkLoggerPlugin()])

// 类属性快捷方式:默认级别(仅记录请求方法与请求头)
let logger = NetworkLoggerPlugin.default

// 类属性快捷方式:详尽级别(记录请求方法、请求头、请求体、成功响应体、错误响应体)
let verboseLogger = NetworkLoggerPlugin.verbose

NetworkLoggerPlugin 本身是一个 final class,其行为完全由内部的 configuration: Configuration 控制(见 NetworkLoggerPlugin.swift)。它在 willSend 中记录请求(NetworkLoggerPlugin.swift),在 didReceive 中区分成功与失败分别记录响应(NetworkLoggerPlugin.swift):

  • .success(response) → 记录响应头与响应体;
  • .failure(error) → 若错误仍携带响应(如状态码校验失败),记录该响应(logNetworkResponse(isFromError: true));否则(如网络断开、超时)记录错误信息 Error calling <target> : <error>(见 NetworkLoggerPlugin.swift)。

5.2 Configuration:输出、格式化与日志选项

Configuration 结构体提供三个可定制字段(见 NetworkLoggerPlugin.swift):

public struct Configuration {
    public var formatter: Formatter      // 数据与日志条目的格式化闭包集合
    public var output: OutputType        // 日志输出闭包,默认 print 到调试控制台
    public var logOptions: LogOptions    // 控制记录哪些请求/响应组件的选项集合
}
  • output: OutputType 即 (_ target: TargetType, _ items: [String]) -> Void。默认实现 defaultOutput 逐条 print;如果你想接入自己的日志框架(如 CocoaLumberjack、SwiftyBeaver)而不是 print,覆写此闭包即可。
  • logOptions: LogOptions 是一个 OptionSet,各选项与位值如下(见 NetworkLoggerPlugin.swift):
选项 位值 作用
.requestMethod 1 << 0 记录请求的 HTTP 方法
.requestBody 1 << 1 记录请求体
.requestHeaders 1 << 2 记录请求头
.formatRequestAscURL 1 << 3 以 cURL 格式记录请求(启用后方法、请求头、请求体都会一并记录,无论各自选项是否开启)
.successResponseBody 1 << 4 记录成功响应的响应体
.errorResponseBody 1 << 5 记录错误响应的响应体

预置的组合:

  • .default = [requestMethod, requestHeaders](仅记录基础组件);
  • .verbose = [requestMethod, requestHeaders, requestBody, successResponseBody, errorResponseBody](记录所有组件)。

5.3 Formatter:自定义请求/响应体格式化

Formatter 结构体包含三个闭包(见 NetworkLoggerPlugin.swift):

  • entry:(_ identifier: String, _ message: String, _ target: TargetType) -> String,将一条消息格式化为日志条目,默认输出形如 Moya_Logger: [日期 时间] identifier: message;
  • requestData:(Data) -> String,将请求体数据转为字符串,默认按 String.Encoding.utf8 解码;
  • responseData:(Data) -> String,将响应体数据转为字符串,默认同样按 utf8 解码。

默认格式化器在解码失败时返回 "## Cannot map data to String ##"(见 NetworkLoggerPlugin.swift)。

把 JSON 响应体格式化成 pretty-printed JSON:仓库示例 Examples/_shared/GitHubAPI.swift 提供了官方推荐的 JSONResponseDataFormatter:

private func JSONResponseDataFormatter(_ data: Data) -> String {
    do {
        let dataAsJSON = try JSONSerialization.jsonObject(with: data)
        let prettyData = try JSONSerialization.data(withJSONObject: dataAsJSON, options: .prettyPrinted)
        return String(data: prettyData, encoding: .utf8) ?? String(data: data, encoding: .utf8) ?? ""
    } catch {
        return String(data: data, encoding: .utf8) ?? ""
    }
}

配合 Configuration 使用(同样来自 GitHubAPI.swift):

let gitHubProvider = MoyaProvider<GitHub>(plugins: [
    NetworkLoggerPlugin(configuration: .init(formatter: .init(responseData: JSONResponseDataFormatter),
                                             logOptions: .verbose))
])

5.4 测试用例佐证

仓库测试 Tests/MoyaTests/NetworkLoggerPluginSpec.swift 覆盖了该插件的全部关键行为,可作为配置正确性的验证依据:

  • 请求日志:willSend 后日志包含 Request: https://api.github.com/zen、Request Headers: <a href="https://link.gitcode.com/i/54be77d4c95a3890a41554533ddb3f5c" target="_blank">...]、HTTP Request Method: GET、Request Body: cool body([NetworkLoggerPluginSpec.swift);
  • 响应日志:didReceive 后包含 Response: 与 Response Body: cool body(NetworkLoggerPluginSpec.swift);
  • cURL 输出:启用 .formatRequestAscURL 后输出 $ curl -i、-H "Content-Type: application/json"、-d "cool body" 等(NetworkLoggerPluginSpec.swift);
  • 自定义 formatter:覆写 requestData、responseData、entry 后,日志输出对应自定义内容(NetworkLoggerPluginSpec.swift)。

这些测试展示了如何通过覆写 output 闭包把日志捕获到内存变量中做断言,这对接入自有日志框架的调试也很有参考价值。


六、自定义插件:实现 PluginType

每当你需要在请求发送前和/或响应到达后执行某些代码时,就可以通过实现 PluginType 协议创建自定义插件。由于协议方法均有默认实现,你只需覆写关心的回调。完整示例见 docs_CN/Examples/CustomPlugin.md 与 docs_CN/Examples/AuthPlugin.md。

6.1 示例一:请求告警插件(RequestAlertPlugin)

以下示例来自 docs/Examples/CustomPlugin.md:在请求发送时弹出一个显示 URL 的告警,响应失败时弹出一个显示状态码的告警。首先创建一个遵循 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) {

    }
}

在 willSend 中实现“请求即将发送”的提示:

func willSend(_ request: RequestType, target: TargetType) {
    // 确保有 URL 字符串可展示
    guard let requestURLString = request.request?.url?.absoluteString else { return }

    let alertViewController = UIAlertController(title: "Sending Request", message: requestURLString, preferredStyle: .alert)
    alertViewController.addAction(UIAlertAction(title: "OK", style: .default, handler: nil))

    viewController.present(alertViewController, animated: true)
}

在 didReceive 中实现“响应失败”的提示:

func didReceive(_ result: Result<Moya.Response, MoyaError>, target: TargetType) {
    // 仅在结果为 failure 时继续
    guard case Result.failure(_) = result else { return }

    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))

    viewController.present(alertViewController, animated: true)
}

说明:原文档特别提醒,该示例通常会在“同一个视图控制器上连续弹出两个告警”时失败(UIAlertController 不允许在同一控制器上重复 present),它主要用于演示插件的写法而非生产实践。

6.2 示例二:JWT 鉴权插件(AuthPlugin)

API 请求经常通过 JWT(JSON Web Token)或其它访问令牌完成鉴权。最简单的方式是在 prepare 阶段给请求添加 Authorization header(见 docs/Examples/AuthPlugin.md):

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")])

更复杂的场景是:创建插件时还拿不到 token(比如登录前),且并非所有请求都需要签名。可以通过扩展 TargetType 提供“是否需要鉴权”的信息,并让插件接收一个返回 token 的闭包:

class TokenSource {
  var token: String?
  init() { }
}

protocol AuthorizedTargetType: TargetType {
  var needsAuth: Bool { get }
}

struct AuthPlugin: PluginType {
  let tokenClosure: () -> String?

  func prepare(_ request: URLRequest, target: TargetType) -> URLRequest {
    guard
      let token = tokenClosure(),
      let target = target as? AuthorizedTargetType,
      target.needsAuth
    else {
      return request
    }

    var request = request
    request.addValue("Bearer " + token, forHTTPHeaderField: "Authorization")
    return request
  }
}

let source = TokenSource()
let provider = MoyaProvider<Target>(
  plugins: [
    AuthPlugin(tokenClosure: { source.token })
  ]
)

source.token = "eyeAm.AJsoN.weBTOKen"

这个进阶版本演示了两个关键点:

  1. 通过 target as? AuthorizedTargetType 做类型判断 + needsAuth 属性,实现“按 Target 决定是否签名”;
  2. token 通过闭包延迟获取,登录完成后更新 TokenSource.token 即可让后续请求自动带上新令牌,无需重建 provider。

6.3 自定义插件小结

  • 何时用 prepare vs willSend:需要修改 URLRequest(添加 header、body 等)时用 prepare;仅需要观察/记录/执行副作用时用 willSend。
  • 何时用 didReceive vs process:仅观察响应结果(如日志、指示器)用 didReceive;需要改写返回给调用方的 Result(如统一重映射错误、注入默认值)用 process。
  • 多插件共存:plugins 数组按声明顺序注册;从 MoyaProvider+Internal.swift 的 reduce 调用可以看出,prepare 与 process 会按顺序依次叠加,因此插件顺序会影响最终结果。

七、插件与响应类型:理解 Moya.Response 与 MoyaError

插件的 didReceive 与 process 回调中频繁出现的 Result<Moya.Response, MoyaError> 是 Moya 的核心响应类型:

  • Moya.Response 封装了 statusCode、data、原始 request 与 response,并提供了 mapJSON() 等映射方法;
  • MoyaError 定义了 imageMapping、jsonMapping、stringMapping、objectMapping、encodableMapping、statusCode、underlying、requestMapping、parameterEncoding 等错误类型。

网络请求完成后,MoyaProvider.swift 中的 convertResponseToResult 将原始响应转换为上述 Result,随后依次经过插件 didReceive → process → 用户 completion。理解这条链路,你就能在 process 中实现“全局错误归一化”等高级能力——例如把所有非 2xx 响应统一转换为自定义业务错误,而不必在每个调用点重复处理。


结语

Moya 的插件机制以 PluginType 的四个回调为骨架,把“请求编辑、副作用、结果改写”三类横切关注点优雅地注入到 provider 的请求流水线中。内置的 CredentialsPlugin、NetworkActivityPlugin、NetworkLoggerPlugin 覆盖了鉴权、活动指示器与日志三大高频需求,而自定义插件(如 RequestAlertPlugin、AuthPlugin)则展示了如何灵活扩展。本文涉及的协议定义见 Sources/Moya/Plugin.swift,内置插件源码见 Sources/Moya/Plugins/,相关测试见 Tests/MoyaTests/NetworkLoggerPluginSpec.swift,自定义插件示例见 docs/Examples/CustomPlugin.md 与 docs/Examples/AuthPlugin.md。掌握这套机制,你可以在不改动业务代码的前提下,为整个 App 的网络层统一注入鉴权、日志、监控与错误处理能力。

登录后查看全文
Moya