【iOS】 Alamofire + Moya + SwiftData 完整教程

这三个框架是构建现代 iOS 应用的数据层的经典组合，它们各司其职，形成了一个清晰的网络请求 → 数据抽象 → 本地持久化的架构闭环。

架构概览：三者的角色定位

• Alamofire (网络地基) : 基于URLSession的 Swift 网络库，负责执行实际的 HTTP 请求、处理响应、管理会话等底层网络通信。
• Moya (网络抽象层) : 建立在 Alamofire 之上，通过定义清晰的枚举来集中管理所有 API 端点，将 URL、参数、请求方式等细节与业务逻辑解耦。
• SwiftData (本地持久化): Apple 官方的数据持久化框架，用于将应用数据（如网络请求结果）存储到本地数据库，实现离线缓存等功能。

1. Alamofire：稳固的网络地基

1.1 环境配置

使用 Swift Package Manager 添加依赖：

dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git", .upToNextMajor(from: "5.10.0"))
]

1.2 基础用法

发送一个 GET 请求

import Alamofire

AF.request("https://api.example.com/posts/1").responseDecodable(of: Post.self) { response in
    switch response.result {
    case .success(let post):
        print("标题: \(post.title)")
    case .failure(let error):
        print("错误: \(error)")
    }
}

responseDecodable 方法会自动将返回的 JSON 数据解析为你定义的 Post 结构体。

发送一个 POST 请求

let parameters: [String: Any] = [
    "title": "Hello",
    "body": "World"
]

AF.request("https://api.example.com/posts",
           method: .post,
           parameters: parameters,
           encoding: JSONEncoding.default)
.responseDecodable(of: Post.self) { response in
    // 处理响应...
}

通过 method: .post 指定方法，并通过 parameters 和 encoding 传递 JSON 参数。

2. Moya：优雅的API抽象层

Moya 的核心是 TargetType 协议，通常通过一个枚举来实现它，每个枚举值代表一个 API 端点。

2.1 环境配置

dependencies: [
    .package(url: "https://github.com/Moya/Moya.git", .upToNextMajor(from: "15.0.0"))
]

2.2 定义 API

import Moya

// 1. 定义枚举，列出所有API端点
enum MyAPI {
    case getUser(id: Int)
    case createUser(name: String, email: String)
}

// 2. 实现TargetType协议
extension MyAPI: TargetType {
    var baseURL: URL { return URL(string: "https://api.example.com")! }

    var path: String {
        switch self {
        case .getUser(let id): return "/users/\(id)"
        case .createUser: return "/users"
        }
    }

    var method: Moya.Method {
        switch self {
        case .getUser: return .get
        case .createUser: return .post
        }
    }

    var task: Task {
        switch self {
        case .getUser:
            return .requestPlain
        case .createUser(let name, let email):
            return .requestParameters(parameters: ["name": name, "email": email], encoding: JSONEncoding.default)
        }
    }

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

2.3 发起请求

// 创建Provider
let provider = MoyaProvider<MyAPI>()

// 发起请求
provider.request(.getUser(id: 1)) { result in
    switch result {
    case .success(let response):
        // 处理成功响应
        let data = response.data
        // 使用JSONDecoder解析...
    case .failure(let error):
        // 处理错误
        print(error)
    }
}

通过这种方式，所有 API 的定义都集中在枚举中，使得代码清晰且易于维护。

3. SwiftData：现代的本地持久化

SwiftData 通过声明式的宏 (@Model) 将你的 Swift 类变为可持久化的数据模型。

3.1 定义模型

import SwiftData

@Model
class User {
    var name: String
    var email: String
    var age: Int

    init(name: String, email: String, age: Int) {
        self.name = name
        self.email = email
        self.age = age
    }
}

在 App 入口配置容器：

import SwiftUI
import SwiftData

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .modelContainer(for: [User.self]) // 注册模型
    }
}

3.2 数据操作 (CRUD)

import SwiftUI
import SwiftData

struct ContentView: View {
    @Environment(\.modelContext) private var modelContext
    @Query private var users: [User] // 自动查询并监听数据变化

    var body: some View {
        List(users) { user in
            Text(user.name)
        }
    }

    func addUser() {
        let newUser = User(name: "Alice", email: "alice@example.com", age: 25)
        modelContext.insert(newUser) // 创建
    }

    func deleteUser(_ user: User) {
        modelContext.delete(user) // 删除
    }
}

4. 三剑合璧：一个完整的数据流示例

场景：从服务器获取用户列表，并缓存到本地。

1. 定义 Moya API （如步骤 2.2 中的 MyAPI）。
2. 定义 SwiftData 模型 （如步骤 3.1 中的 User）。
3. 在 ViewModel 中串联流程：

import SwiftUI
import Moya
import SwiftData

@Observable
class UserViewModel {
    private let provider = MoyaProvider<MyAPI>()
    private var modelContext: ModelContext?

    func setup(modelContext: ModelContext) {
        self.modelContext = modelContext
    }

    func fetchAndCacheUsers() {
        provider.request(.getUsers) { [weak self] result in
            guard let self = self, let context = self.modelContext else { return }

            switch result {
            case .success(let response):
                do {
                    // 1. 解析网络数据
                    let users = try JSONDecoder().decode([User].self, from: response.data)

                    // 2. 清除旧数据（可选）
                    try context.delete(model: User.self)

                    // 3. 存入SwiftData
                    for user in users {
                        context.insert(user)
                    }

                    try context.save()

                } catch {
                    print("解析或保存数据失败: \(error)")
                }
            case .failure(let error):
                print("网络请求失败: \(error)")
            }
        }
    }
}

在 SwiftUI 视图中，你可以通过 @Query 直接获取并使用本地缓存的 User 数据，实现了网络请求与 UI 的解耦。

总结与学习路径

• 从 Alamofire 开始：理解基础的网络请求、参数编码和响应处理。
• 深入 Moya ：掌握 TargetType 协议，学会用枚举管理所有 API，感受代码组织方式的提升。
• 探索 SwiftData ：熟悉 @Model、@Query、ModelContext 等核心概念，并尝试将其与 SwiftUI 结合。
• 终极整合：在一个实际的小项目中（例如一个简单的新闻阅读器或待办事项应用），将三者结合起来，实现从网络获取数据到本地缓存展示的完整流程。