【Moya】为什么你的 Alamofire 代码需要再封装一层？

【Moya】为什么你的 Alamofire 代码需要再封装一层？

iOS三方库精读 · 第 14 期

---

一、一句话介绍

Moya 是一个建立在 Alamofire 之上的网络抽象层库 ，它用 TargetType 协议将所有 API 接口声明为 Swift 枚举 case，让网络请求从"散落在各处的字符串 URL"变成"编译器可检查的类型化接口"，同时内置单元测试 Stubbing 和 Plugin 拦截机制。

属性	信息
⭐ GitHub Stars	15k+
最新稳定版	15.0.3
License	MIT
支持平台	iOS 13+
语言	Swift（纯 Swift，无 OC 接口）
依赖	Alamofire 5.x

---

二、为什么选择它

原生痛点

直接使用 Alamofire 或 URLSession 时，常见的问题：

// ❌ 硬编码 URL，散落在各处
AF.request("https://api.example.com/users/\(userId)/profile",
           method: .get,
           parameters: ["include": "avatar"],
           headers: ["Authorization": "Bearer \(token)"])

• URL 字符串：运行时才发现拼写错误
• 参数类型 ：parameters: [String: Any]，传错类型编译器不报错
• 认证 Token：每个请求都要手动加 headers
• Mock 测试：需要替换整个 URLSession，实现复杂
• 接口文档：散落在业务代码里，难以统一维护

Moya 的解决方案：

1. TargetType 协议：将每个 API 的 URL、方法、参数、headers 集中声明
2. 类型安全：枚举 case 关联值确保参数类型正确，编译时报错
3. Plugin 系统：一处注入 Token，所有请求自动携带
4. 内置 Stubbing ：sampleData + StubbingProvider，无需 mock URLSession

---

三、核心功能速览

基础层（新手必读）

环境集成

// SPM
// URL: https://github.com/Moya/Moya.git
// from: "15.0.3"
// Products: Moya（基础）/ RxMoya（RxSwift）/ CombineMoya（Combine）

# CocoaPods
pod 'Moya', '~> 15.0'
pod 'Moya/RxSwift'    # 可选
pod 'Moya/Combine'    # 可选

TargetType 完整示例

import Moya

enum UserAPI {
    case login(email: String, password: String)
    case profile(userId: Int)
    case updateAvatar(data: Data)
    case logout
}

extension UserAPI: TargetType {
    var baseURL: URL { URL(string: "https://api.example.com/v2")! }

    var path: String {
        switch self {
        case .login:              return "/auth/login"
        case .profile(let id):   return "/users/\(id)"
        case .updateAvatar:      return "/users/avatar"
        case .logout:            return "/auth/logout"
        }
    }

    var method: Moya.Method {
        switch self {
        case .login, .updateAvatar: return .post
        case .logout:               return .delete
        case .profile:              return .get
        }
    }

    var task: Task {
        switch self {
        case .login(let email, let pw):
            return .requestParameters(
                parameters: ["email": email, "password": pw],
                encoding: JSONEncoding.default
            )
        case .updateAvatar(let data):
            let formData = MultipartFormData(provider: .data(data),
                                              name: "file",
                                              fileName: "avatar.jpg",
                                              mimeType: "image/jpeg")
            return .uploadMultipart([formData])
        default:
            return .requestPlain
        }
    }

    var headers: [String: String]? { ["Content-Type": "application/json"] }

    // 单元测试用的 Stub 数据
    var sampleData: Data {
        switch self {
        case .login:
            return """{"token":"test_token","userId":1}""".data(using: .utf8)!
        default:
            return Data()
        }
    }
}

发起请求

let provider = MoyaProvider<UserAPI>()

// 回调方式
provider.request(.login(email: "test@example.com", password: "123456")) { result in
    switch result {
    case .success(let response):
        let json = try? response.mapJSON()
        print(json ?? "")
    case .failure(let error):
        print(error)
    }
}

// 直接 map 到 Codable 模型
provider.request(.profile(userId: 42)) { result in
    if case .success(let response) = result {
        let user = try? response.map(User.self)
    }
}

---

进阶层（最佳实践）

Plugin 系统：拦截所有请求

// 统一注入认证 Token
struct TokenPlugin: PluginType {
    func prepare(_ request: URLRequest, target: TargetType) -> URLRequest {
        var req = request
        if let token = AuthManager.shared.token {
            req.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
        }
        return req
    }

    // 401 自动触发 token 刷新
    func didReceive(_ result: Result<Response, MoyaError>, target: TargetType) {
        if case .success(let response) = result, response.statusCode == 401 {
            AuthManager.shared.refreshToken()
        }
    }
}

// 统计 API 耗时
struct MetricsPlugin: PluginType {
    func willSend(_ request: RequestType, target: TargetType) {
        Analytics.trackStart(api: target.path)
    }
    func didReceive(_ result: Result<Response, MoyaError>, target: TargetType) {
        Analytics.trackEnd(api: target.path)
    }
}

// 组合多个 Plugin
let provider = MoyaProvider<UserAPI>(plugins: [
    TokenPlugin(),
    MetricsPlugin(),
    NetworkLoggerPlugin()  // Moya 内置日志插件
])

单元测试：Stubbing

// 无需真实网络，立即返回 sampleData
let testProvider = MoyaProvider<UserAPI>(stubClosure: MoyaProvider.immediatelyStub)

// 延迟返回（模拟网络延迟）
let testProvider2 = MoyaProvider<UserAPI>(
    stubClosure: MoyaProvider.delayedStub(0.5)  // 延迟 0.5s
)

// 测试代码
func testLogin() {
    testProvider.request(.login(email: "test@example.com", password: "123")) { result in
        switch result {
        case .success(let response):
            XCTAssertEqual(response.statusCode, 200)
            let model = try? response.map(LoginResponse.self)
            XCTAssertNotNil(model?.token)
        case .failure:
            XCTFail()
        }
    }
}

Combine 集成

import Combine

class UserViewModel: ObservableObject {
    @Published var user: User?
    @Published var error: String?

    private var cancellables = Set<AnyCancellable>()
    private let provider = MoyaProvider<UserAPI>()

    func loadProfile(userId: Int) {
        provider.requestPublisher(.profile(userId: userId))
            .tryMap { try $0.map(User.self) }
            .receive(on: DispatchQueue.main)
            .sink(
                receiveCompletion: { [weak self] completion in
                    if case .failure(let error) = completion {
                        self?.error = error.localizedDescription
                    }
                },
                receiveValue: { [weak self] user in
                    self?.user = user
                }
            )
            .store(in: &cancellables)
    }
}

RxSwift 集成

import RxSwift

provider.rx.request(.searchRepos(query: "swift"))
    .map(RepoSearchResult.self)
    .observe(on: MainScheduler.instance)
    .subscribe(
        onSuccess: { result in print(result.items) },
        onFailure: { error in print(error) }
    )
    .disposed(by: disposeBag)

---

深入层（源码视角）

MoyaProvider 的请求流程

provider.request(.login(...))
    ↓
MoyaProvider.requestNormal
    ↓
调用所有 Plugin.prepare（修改 URLRequest）
    ↓
调用 Plugin.willSend（发送前通知）
    ↓
Alamofire.request（真正发网络请求）
    ↓
收到响应
    ↓
调用 Plugin.didReceive（响应后通知）
    ↓
回调 completion handler

Moya 本质是 Alamofire 的装饰器（Decorator），所有的实际网络操作都委托给 Alamofire，Moya 只负责协议声明、Plugin 拦截、Stub 切换。

Task 枚举的设计

Task 枚举涵盖了所有常见请求类型：

public enum Task {
    case requestPlain                              // 无 body
    case requestData(_ data: Data)                 // 原始 Data
    case requestParameters(parameters:encoding:)   // URL 参数 or JSON body
    case uploadMultipart(_ data: [MultipartFormData]) // 文件上传
    case downloadDestination(_ destination: DownloadDestination) // 文件下载
    case uploadCompositeMultipart(_, urlParameters:)  // 混合上传
    // ...
}

这种穷举枚举设计确保了所有请求形式都有类型安全的表达方式。

---

四、实战演示

场景：统一网络层封装（生产级模板）

// 1. 定义 API Target
enum NewsAPI {
    case topHeadlines(country: String, page: Int)
    case article(id: String)
}

extension NewsAPI: TargetType {
    var baseURL: URL { URL(string: "https://newsapi.org/v2")! }
    var path: String {
        switch self {
        case .topHeadlines: return "/top-headlines"
        case .article(let id): return "/articles/\(id)"
        }
    }
    var method: Moya.Method { .get }
    var task: Task {
        switch self {
        case .topHeadlines(let country, let page):
            return .requestParameters(
                parameters: ["country": country, "page": page, "pageSize": 20],
                encoding: URLEncoding.queryString
            )
        case .article: return .requestPlain
        }
    }
    var headers: [String: String]? { nil }
    var sampleData: Data { Data() }
}

// 2. Service 层封装（屏蔽 Moya 细节）
final class NewsService {
    private let provider = MoyaProvider<NewsAPI>(plugins: [
        TokenPlugin(),
        NetworkLoggerPlugin()
    ])

    func fetchHeadlines(country: String, page: Int) async throws -> [Article] {
        return try await withCheckedThrowingContinuation { cont in
            provider.request(.topHeadlines(country: country, page: page)) { result in
                switch result {
                case .success(let response):
                    do {
                        let articles = try response.map([Article].self, atKeyPath: "articles")
                        cont.resume(returning: articles)
                    } catch {
                        cont.resume(throwing: error)
                    }
                case .failure(let error):
                    cont.resume(throwing: error)
                }
            }
        }
    }
}

// 3. 业务层调用
let service = NewsService()
Task {
    let articles = try await service.fetchHeadlines(country: "cn", page: 1)
}

---

五、源码亮点

进阶层

TargetType 作为抽象屏障

Moya 的 MoyaProvider<Target: TargetType> 是泛型类型，每种 API 有独立的 Provider 实例。这意味着：

• 不同 API 服务（UserAPI / ProductAPI / OrderAPI）完全隔离
• 每个 Provider 可以配置不同的 Plugin（如不同的 Token 策略）
• 测试时替换 Provider 无需修改任何业务代码

深入层：网络层的 SOLID 原则

Moya 的设计完美体现了 SOLID 原则：

原则	体现
Single Responsibility	TargetType 只描述接口声明，Provider 只负责执行
Open/Closed	新增 API 只需新增枚举 case，不修改 Provider
Liskov Substitution	StubbingProvider 可无缝替换真实 Provider
Interface Segregation	Plugin 协议的每个方法都是可选实现
Dependency Inversion	业务代码依赖 TargetType 协议，而非具体 URL 字符串

---

六、踩坑记录

问题 1：sampleData 返回空 Data 导致测试解析失败

• 原因 ：使用 StubbingProvider 但忘记实现 sampleData
• 解决 ：为每个需要测试的 case 提供合法 JSON 的 sampleData

问题 2：Plugin.prepare 中修改 headers 无效

• 原因 ：URLRequest 是值类型，必须先 copy 再修改

• 解决 ：

  func prepare(_ request: URLRequest, target: TargetType) -> URLRequest {
      var req = request  // ← copy 一份
      req.setValue("Bearer xxx", forHTTPHeaderField: "Authorization")
      return req         // ← 返回修改后的副本
  }

问题 3：Moya 请求不在主线程回调

• 原因 ：默认 callbackQueue 是 .main，但某些版本或配置下可能改变
• 解决 ：UI 更新前显式 DispatchQueue.main.async { ... } 或使用 .receive(on: MainScheduler.instance)

问题 4：多个 API 服务需要不同 baseURL

• 原因：Moya 一个 TargetType 对应一个 baseURL
• 解决 ：拆分为多个 enum（UserAPI, ProductAPI），各自独立 Provider

问题 5：文件上传进度无法监听

• 原因：回调方式无进度回调

• 解决 ：

  provider.request(.uploadAvatar(data: imageData)) { result in ... }
  // 上面不支持进度，改用：
  provider.requestWithProgress(.uploadAvatar(data: imageData)) { progress in
      print("上传进度:", progress.progress)
  }

---

七、延伸思考

同类方案对比

方案	类型安全	测试友好	学习成本	OC 支持	推荐场景
URLSession	❌ 字符串	需 mock	低	✅	超简单场景
Alamofire	⚠️ 需封装	需封装	低	❌	中型 App
Moya	✅ 枚举	✅ 内置	中	❌	中大型 Swift App
Apollo（GraphQL）	✅ 代码生成	✅	高	⚠️	GraphQL API

推荐使用场景

• ✅ API 接口较多（20+）的中大型 App
• ✅ 团队协作，需要统一的 API 文档化
• ✅ 需要完整的单元测试覆盖网络层
• ✅ 已经在使用 Alamofire 想升级架构

不推荐场景

• ❌ API 极少（3 个以内）→ 直接 Alamofire 更简单
• ❌ OC 项目 → Moya 纯 Swift，考虑 AFNetworking
• ❌ 追求最小依赖体积 → URLSession 直接封装

---

八、参考资源

• GitHub: Moya/Moya
• Moya 官方文档
• Moya 与 RxSwift 集成
• Moya 与 Combine 集成
• 系列 Demo 仓库：github.com/yourname/ios-lib-demos

---

九、本期互动

小作业

用 Moya 封装一个天气 API 服务层 ：定义 WeatherAPI enum，包含"当前天气"和"5天预报"两个 case，实现 TargetType，并编写一个 TokenPlugin 注入 API Key，最后用 StubbingProvider 为两个接口各写一个单元测试。评论区分享你的 TargetType 实现。

思考题

Moya 的 TargetType 强制将一个服务的所有 API 放在同一个 enum 里。当 API 接口很多时（50+），这个大 enum 会变得难以维护。你会如何设计拆分方案？能否在不改变使用方代码的前提下实现"API 分模块管理"？

读者征集

下一期我们将深入 SwiftyJSON（JSON 解析利器）。你在处理复杂嵌套 JSON 时用过哪些方案（SwiftyJSON / Codable / ObjectMapper / 手动解析）？在 OC 项目中你是如何处理 JSON 的？欢迎评论区分享。

---

📅 本系列每周五晚更新 ✅ 第11期：DGCharts · ✅ 第12期：Hero · ✅ 第13期：Realm · ➡️ 第14期：Moya · ○ 第15期：SwiftyJSON