构建可扩展的 SwiftUI 网络层：以 Async/Await 与协议为核心的分层架构

大多数 iOS 应用都离不开 API 调用和网络请求。随着功能增长，如何管理这些请求、统筹执行顺序，并保持代码的可扩展性与可维护性成为关键。本文将通过一个电商演示项目（使用 Dummy JSON API），逐步拆解如何构建一个比“简单 API 请求”更高级、更具复用性的网络架构，并深入探讨 Swift 并发的实际落地方式。

涵盖重点：泛型网络客户端、自定义错误处理、依赖注入与协议抽象、端点枚举 vs 协议设计、视图模型与 UI 状态的分离、Sendable 与并发安全、可测试的模拟服务。

1. 项目初始化与并发设置

项目基于 Xcode 16.4 创建，这是一个关键细节：未来版本的编译器对并发错误的处理可能略有不同。在构建设置中，有几项与 Swift 并发直接相关：

Concurrency Checking：建议设为 Targeted，以获取足够的并发警告信息。
Default Actor Isolation：默认会将整个模块标记为 MainActor，但这在实际开发中容易引发大量不必要的编译器错误，需要我们频繁使用 nonisolated 手动退出。因此更推荐关闭该默认行为，让视图和可观察对象按其自身规则正确运行在主线程上。

关闭后，SwiftUI 的 View 与 Observable 仍然会自动遵守 MainActor，而我们自定义的网络层则能保持清晰的后台执行环境，减少不必要的编译器干预。

2. 数据模型与响应结构

从 API 返回的 JSON 结构出发，定义符合 Decodable 的实体。演示项目中需要两个核心模型：

Product：包含 id、title、description、price、thumbnail 等字段，并遵循 Identifiable 以优化列表性能。
ProductsResponse：封装分页信息，包含 products: [Product]、total、skip、limit，为后续无限滚动做好准备。

此外，为方便预览与测试，可以为模型提供静态的示例数据。

3. 从基础请求到可复用的 API 客户端

最初，我们可能直接在 ViewModel 中写出如下代码：使用 URLSession.shared.data(from:) 获取数据，再用 JSONDecoder 解码。但这一过程包含着大量重复逻辑：请求构建、状态码校验、错误解析、取消处理等。为了提高复用性，我们逐步提取：

3.1 通用泛型请求方法

将网络请求抽象为一个泛型函数，它接受一个 URLRequest 和返回值类型 T: Decodable，返回 T。内部统一处理：

发起异步数据任务
校验 HTTP 状态码（仅接受 200~299）
解析服务器返回的错误信息
捕获并转换为自定义的 APIError

3.2 结构化错误处理

自定义错误枚举 APIError 涵盖以下场景：

错误类型	说明
invalidResponse	响应无法转换为 HTTPURLResponse
requestFailed(statusCode:message:)	携带状态码与服务器返回的错误消息
networkError	底层 URLSession 错误（如无网络连接）
cancelled	任务被取消（例如视图消失时自动取消），避免向用户展示无意义错误

在 catch 块中，我们特别区分了 URLError.cancelled 与 CancellationError，将它们统一映射为 APIError.cancelled，防止干扰用户交互。

3.3 纯函数的 API Client 结构体

由于这个泛型请求方法不依赖任何外部状态，我们可以把它放入一个值类型（struct）中，命名为 APIClient。它仅包含纯函数，具备以下优势：

内存开销小，自动满足 Sendable 协议，在并发环境中无需额外同步措施。
可在多个 ViewModel 之间安全共享，无需担心竞态条件。
测试友好，可以轻松替换后端实现。

4. 协议驱动：交换真实与模拟服务

为了让 ViewModel 不直接依赖具体的网络实现，也不需要在预览或测试时频繁修改 URL，我们引入服务协议。例如，为产品列表定义：

protocol ProductService {
    func fetchProducts(limit: Int, skip: Int) async throws -> [Product]
}

然后提供两个具体实现：

RealProductService：使用 APIClient 访问真实 API。
MockProductService：直接返回预设数据或模拟错误场景，极大提升 SwiftUI 预览和单元测试的效率。

ViewModel 仅持有 any ProductService 类型的实例，通过初始化注入即可切换环境。同样的模式也应用于分类列表等其他功能块。

5. 端点协议：告别硬编码 URL

即便使用了 APIClient，请求的构造仍然散落在各处。我们进一步抽象出 Endpoint 协议，将每条 API 的描述集中管理：

protocol Endpoint {
    associatedtype Response: Decodable
    var path: String { get }
    var method: HTTPMethod { get }
    var queryItems: [URLQueryItem] { get }
    func makeRequest(baseURL: URL) throws -> URLRequest
    func map(data: Data) throws -> Response
}

通过协议扩展，我们为 makeRequest 和 map 提供了默认实现（使用 JSONDecoder），大多数端点无需重复实现。

对比使用 enum 存放所有 API 案例，协议方案拥有显著优势：

解耦与独立：每个端点文件可归属于对应的功能模块，避免巨型枚举文件引发的合并冲突和难以维护的问题。
易于扩展：新增端点只需新建一个遵循协议的类型，无需修改集中式枚举。
更好的模块化支持：未来拆分 Swift Package 时，端点可以随功能模块独立迁移。

💡 提示：端点的 Response 类型通过关联类型（associatedtype）与具体接口绑定，使得 APIClient 能自动推断返回值类型，进一步减少调用方的泛型声明负担。

6. 整合端点与客户端：极简服务层

现在，我们将 APIClient 修改为直接接受一个 Endpoint 参数，由端点内部生成请求并执行解码。服务实现变得异常简洁：

struct RealProductService: ProductService {
    let client: APIClient
    let baseURL: URL

    func fetchProducts(limit: Int, skip: Int) async throws -> [Product] {
        let endpoint = ProductEndpoint(limit: limit, skip: skip)
        let response: ProductsResponse = try await client.request(endpoint, baseURL: baseURL)
        return response.products
    }
}

经由 Endpoint 与 APIClient 的配合，所有底层细节（HTTP 方法、查询参数拼接、状态码校验、错误解析、JSON 解码）被完全封装，上层仅需关注业务逻辑。这种“薄服务层”模式非常适合大型项目，因为它保证了网络交互的一致性，同时降低了每个功能模块的心智负担。