Moya 端点（Endpoint）深度指南：理解 Target 到 Endpoint 再到 URLRequest 的完整映射链路

Moya 端点Endpoint深度指南理解 Target 到 Endpoint 再到 URLRequest 的完整映射链路【免费下载链接】MoyaNetwork abstraction layer written in Swift.项目地址: https://gitcode.com/gh_mirrors/mo/MoyaEndpoint 是 Moya 中承上启下的半内部数据结构它把面向业务定义的TargetType目标物化为具体的请求描述再由 Moya 交给 Alamofire 执行。本文以 docs_CN/Endpoints.md 为主线结合仓库源码深入讲解 Endpoint 的数据结构、endpointClosure与requestClosure两个映射入口、Sample Response 的三种形态以及它们背后的默认实现与测试验证读完你将能够按需定制请求头、构造非 200 状态的测试桩、甚至在任何请求发出前做最后一刻的请求改写。Endpoint 是什么Moya 的“半内部”请求描述结构Endpoint 是 Moya 用来推演最终网络请求的半内部数据结构它本身不发起任何网络请求只是完整地描述“一个请求应该长什么样”。从源码 Endpoint.swift 可以看到每个Endpoint实例恰好存储五类数据url请求的 URL 字符串String类型非URLHTTP 方法GET、POST等类型为Moya.MethodHTTP 请求头httpHeaderFields一个可空的[String: String]字典Task用于区分upload、download与普通request的任务类型Sample response为单元测试准备的桩响应由sampleResponseClosure闭包按需生成。其中sampleResponseClosure是一个返回EndpointSampleResponse的闭包类型别名为SampleResponseClosure () - EndpointSampleResponse而不是一个固定的值这意味着每次桩请求发生时都可以动态决定返回什么响应。在 Moya 的整体架构中Endpoint 位于中间层Providers把Targets映射成Endpoints再把Endpoints映射成真正的网络请求。因此与 Endpoint 交互只有两种途径创建 provider 时指定一个从Target到Endpoint的映射endpointClosure创建 provider 时指定一个从Endpoint到URLRequest的映射requestClosure。这两种闭包的类型定义都可以在 MoyaProvider.swift 中找到public typealias EndpointClosure (Target) - Endpoint public typealias RequestResultClosure (ResultURLRequest, MoyaError) - Void public typealias RequestClosure (Endpoint, escaping RequestResultClosure) - Void默认映射defaultEndpointMapping源码解读先看第一种映射的“标准答案”。Moya 为Target到Endpoint的转换提供了默认实现定义在 MoyaProviderDefaults.swiftfinal class func defaultEndpointMapping(for target: Target) - Endpoint { Endpoint( url: URL(target: target).absoluteString, sampleResponseClosure: { .networkResponse(200, target.sampleData) }, method: target.method, task: target.task, httpHeaderFields: target.headers ) }这段代码把TargetType的各个属性一一搬进EndpointURL 由URL(target:)生成sample response 固定为“200 状态码 target.sampleData”方法、任务与请求头直接透传。你完全可以手写出等价的闭包let endpointClosure { (target: MyTarget) - Endpoint in let url URL(target: target).absoluteString return Endpoint( url: url, sampleResponseClosure: { .networkResponse(200, target.sampleData) }, method: target.method, task: target.task, httpHeaderFields: target.headers ) }注意其中的URL(target:)初始化器Moya 为TargetType提供了便捷扩展见 URLMoya.swift它把baseURL与path拼接成完整 URL并且对空path做了特殊处理——直接返回baseURL避免appendingPathComponent在多出尾部斜杠的边界情况仓库注释中引用了 Moya 的 issue #1049 / PR #1053。如果你需要定制行为或者想在单元测试中构造一个返回非 200 状态码的测试 providerendpointClosure就是你要动手的地方。从 Target 到 Endpoint自定义endpointClosure在这个闭包里你拥有从Target到Endpoint转换的绝对控制权可以改变task、method、url、headers乃至sampleResponse。官方文档给出的典型场景是把应用程序名称写进 HTTP 请求头用于服务端分析统计。场景一给所有请求附加自定义头字段let endpointClosure { (target: MyTarget) - Endpoint in let defaultEndpoint MoyaProvider.defaultEndpointMapping(for: target) return defaultEndpoint.adding(newHTTPHeaderFields: [APP_NAME: MY_AWESOME_APP]) } let provider MoyaProviderGitHub(endpointClosure: endpointClosure)这里的关键是adding(newHTTPHeaderFields:)。从 Endpoint.swift 的源码可以看到它不是原地修改而是基于当前 Endpoint 的所有属性复制出一份新的 Endpoint再合并新的请求头如果原 Endpoint 已有请求头则逐键覆盖合并如果传入的字典为空则原样返回自身。这种“基于默认行为做增量扩展”而非“整体替换”的设计让你可以放心依赖 Moya 已有的代码逻辑。open func adding(newHTTPHeaderFields: [String: String]) - Endpoint { Endpoint(url: url, sampleResponseClosure: sampleResponseClosure, method: method, task: task, httpHeaderFields: add(httpHeaderFields: newHTTPHeaderFields)) }类似的还有replacing(task:)同样以复制方式返回一个替换了task的新 Endpoint常用于在闭包中把普通请求改成上传或下载任务。注意请求头字段也可以直接作为TargetType协议定义的一部分即target.headersendpointClosure里的追加操作是在此基础上的补充。场景二按 target 分支附加不同参数你还可以为部分或全部 endpoint 提供附加参数。例如假设MyTarget的绝大多数 case 都需要携带身份认证 token唯独真正执行登录认证的.authenticate不需要可以这样构造let endpointClosure { (target: MyTarget) - Endpoint in let defaultEndpoint MoyaProvider.defaultEndpointMapping(for: target) // Sign all non-authenticating requests switch target { case .authenticate: return defaultEndpoint default: return defaultEndpoint.adding(newHTTPHeaderFields: [AUTHENTICATION_TOKEN: GlobalAppStorage.authToken]) } } let provider MoyaProviderGitHub(endpointClosure: endpointClosure)这种模式在仓库测试中同样得到了验证例如 MoyaProviderSpec.swift 中通过自定义endpointClosure构造了返回.response完全自定义的 HTTPURLResponse和.networkError的桩响应。而 EndpointSpec.swift 则专门断言了adding(newHTTPHeaderFields:)会返回一个新 Endpoint、保留原有 url 与 method 不变、仅新增指定的头字段it(returns a new endpoint for adding(newHTTPHeaderFields:)) { let agent Zalbinian let newEndpoint endpoint.adding(newHTTPHeaderFields: [User-Agent: agent]) expect(newEndpoint.httpHeaderFields?[User-Agent]).to(equal(agent)) expect(newEndpoint.url).to(equal(endpoint.url)) expect(newEndpoint.method).to(equal(endpoint.method)) }Sample Responses 详解为单元测试而生的三种形态sampleData是TargetType协议的必备要求默认值为Data()见 TargetType.swift但它只指定了“返回的数据内容”。而 Target 到 Endpoint 的映射闭包才是你指定更多测试细节的地方。Sample response 一共有三种取值定义在 Endpoint.swift 的EndpointSampleResponse枚举中取值参数语义.networkError(NSError)一个NSError网络发送请求失败或未能检索到响应例如超时.networkResponse(Int, Data)状态码Int与返回数据Data网络正常返回了响应包含状态码和数据.response(HTTPURLResponse, Data)完整的HTTPURLResponse与数据Data完全自定义stub一个响应可精确控制状态码之外的响应细节从源码层面看这三种取值在桩请求执行时MoyaProviderInternal.swift 的createStubFunction会走不同的处理分支.networkResponse(statusCode, data)直接用状态码和数据构造Moya.Response交由validationType校验后回调.response(customResponse, data)额外把自定义的HTTPURLResponse附带到Moya.Response上.networkError(error)包装成MoyaError.underlying(error, nil)直接以失败回调结束。这给了单元测试极大的灵活性默认实现固定返回 200但你可以通过自定义endpointClosure返回 400、500 或超时错误来覆盖各种分支例如 MoyaProviderSpec.swift 中构造的 400 状态码桩响应。Request 映射requestClosure的最后修改时机正如文档所强调的Moya 的目标不是提供一个网络访问的编码框架——那是 Alamofire 的职责。Moya 关心的是如何构建网络访问的思考框架并对定义良好的网络目标提供编译时检查。你已经看到了endpointClosure如何把 target 映射成 endpoint但在某个时刻Endpoint必须被解析成真正的URLRequest交给 Alamofire——这正是requestClosure的职责。默认实现与错误处理requestClosure是可选的“最后一刻”修改请求的机会默认值是MoyaProvider.defaultRequestMapping见 MoyaProviderDefaults.swift它只做一件事调用Endpoint的urlRequest()方法并转发结果final class func defaultRequestMapping(for endpoint: Endpoint, closure: RequestResultClosure) { do { let urlRequest try endpoint.urlRequest() closure(.success(urlRequest)) } catch MoyaError.requestMapping(let url) { closure(.failure(MoyaError.requestMapping(url))) } catch MoyaError.parameterEncoding(let error) { closure(.failure(MoyaError.parameterEncoding(error))) } catch { closure(.failure(MoyaError.underlying(error, nil))) } }这里的urlRequest()方法Endpoint.swift会根据task的不同分支进行编码并可能抛出三类错误对应 MoyaError.swift 中的定义MoyaError.requestMapping(String)无法为给定 path 创建URLRequest即 URL 字符串非法MoyaError.parameterEncoding(Swift.Error)参数无法被编码例如编码器对参数类型不支持MoyaError.encodableMapping(Swift.Error)Encodable对象无法被编码成Data。实际上urlRequest()内部对各类task的处理相当完整requestPlain等直接返回、requestData设置httpBody、requestJSONEncodable走 JSON 编码、requestParameters走参数编码、requestCompositeData/Parameters则同时处理 body 与 query 参数。编码过程的错误会被包装为MoyaError.parameterEncoding或MoyaError.encodableMapping见 URLRequestEncoding.swift最终由defaultRequestMapping捕获后以.failure回调。自定义requestClosurerequestClosure接收一个Endpoint实例并负责调用它的RequestResultClosure参数即ResultURLRequest, MoyaError - Void的简写传入代表该 Endpoint 的 request。在这里你可以做 OAuth 签名等操作由于闭包可以被异步调用你可以使用任何喜欢的认证库。也可以不修改请求而只是简单记录日志let requestClosure { (endpoint: Endpoint, done: MoyaProvider.RequestResultClosure) in do { var request try endpoint.urlRequest() // Modify the request however you like. done(.success(request)) } catch { done(.failure(MoyaError.underlying(error))) } } let provider MoyaProviderGitHub(requestClosure: requestClosure)注意endpointClosure不适合做这类针对单个请求的应用级映射requestClosure才是修改URLRequest专属属性、或补充只有请求创建那一刻才知道的信息例如 cookie 设置的正确位置。实战禁用请求 CookieURLRequest有许多可自定义的属性。例如你想禁用所有请求的 cookie{ (endpoint: Endpoint, done: MoyaProvider.RequestResultClosure) in do { var request: URLRequest try endpoint.urlRequest() request.httpShouldHandleCookies false done(.success(request)) } catch { done(.failure(MoyaError.underlying(error))) } }内部调用链闭包在哪里被触发从 MoyaProviderInternal.swift 的requestNormal可以看到完整链路每次请求先通过endpoint(target)内部即endpointClosure(target)得到Endpoint随后requestClosure(endpoint, performNetworking)被调用闭包返回的ResultURLRequest, MoyaError再流入performNetworking——成功则继续走 stub 或真实的 Alamofire 请求失败则直接以错误完成回调。这也解释了为什么requestClosure适合做请求日志它每次在请求发送到网络之前都会被调用而且由于闭包支持异步调用不会阻塞请求线程。小结围绕 Endpoint 的两个闭包构成了 Moya 请求管线的两段可定制环节endpointClosureTarget → Endpoint修改请求头、任务类型、方法、URL 与桩响应适合做跨请求的统一配置与测试桩构造requestClosureEndpoint → URLRequest最后时刻修改URLRequest属性、做签名或日志默认实现defaultRequestMapping已妥善处理requestMapping/parameterEncoding/underlying三类错误。掌握了这两层映射你就能在不触碰 Alamofire 底层的情况下把 Moya 的请求行为精确调校到符合业务与测试需求。相关源码入口可继续参阅 Endpoint.swift、MoyaProviderDefaults.swift、MoyaProviderInternal.swift 以及测试 EndpointSpec.swift 与 EndpointClosureSpec.swift并可与 Targets 指南 和 Providers 指南 配合阅读。【免费下载链接】MoyaNetwork abstraction layer written in Swift.项目地址: https://gitcode.com/gh_mirrors/mo/Moya创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考