Moya 插件机制完全指南:PluginType 协议、内置插件与自定义插件实战
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 中的请求流水线:
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) }- 发送前,
interceptor(target:)使用plugins.reduce依次调用每个插件的prepare编辑URLRequest(见 MoyaProvider+Internal.swift),随后在setup(interceptor:with:and:)中统一触发所有插件的willSend(见 MoyaProvider+Internal.swift)。 - 响应到达后,
sendAlamofireRequest的completionHandler将原始响应转换为Result<Moya.Response, MoyaError>,并遍历所有插件调用didReceive(见 MoyaProvider+Internal.swift)。 - 即便使用 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"
这个进阶版本演示了两个关键点:
- 通过
target as? AuthorizedTargetType做类型判断 +needsAuth属性,实现“按 Target 决定是否签名”; - token 通过闭包延迟获取,登录完成后更新
TokenSource.token即可让后续请求自动带上新令牌,无需重建 provider。
6.3 自定义插件小结
- 何时用
preparevswillSend:需要修改URLRequest(添加 header、body 等)时用prepare;仅需要观察/记录/执行副作用时用willSend。 - 何时用
didReceivevsprocess:仅观察响应结果(如日志、指示器)用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 的网络层统一注入鉴权、日志、监控与错误处理能力。