GraphQL API 与 Swift：面向初学者的逐步教程

GraphQL 与 Swift 简介

GraphQL 是一种由 Facebook 开发的现代 API 查询语言。与 REST 不同（在 REST 中您会获得固定的数据结构），GraphQL 允许客户端（您的 Swift 应用）仅请求真正需要的字段。这对于从事 iOS 和 macOS 开发的移动开发者尤其重要：数据越少，流量越少，加载越快，用户体验越好。

在本教程中，我们将探讨如何将 GraphQL API 连接到您的 Swift 项目，执行基本查询和变更操作。我们将使用官方客户端 Apollo iOS——这是 Apple 生态系统中用于处理 GraphQL 最流行且维护最完善的库。

到本文结束时，您将能够：

• 在 Xcode 项目中配置 Apollo iOS
• 编写并执行 GraphQL 查询（Query）
• 发送变更操作（Mutation）以修改数据
• 处理响应和错误

1. 项目配置与 Apollo iOS 安装

1.1. 创建新项目

打开 Xcode 并创建一个新项目（iOS App 或 macOS App）。选择 Swift 语言以及 SwiftUI 或 UIKit 界面——这并不关键，因为网络操作与 UI 框架无关。

1.2. 通过 Swift Package Manager 安装

Apollo iOS 可以通过 SPM 轻松集成。转到 File → Add Packages... 并粘贴 URL：

https://github.com/apollographql/apollo-ios.git

选择最新的稳定版本（撰写本文时为 1.15.0）并将包添加到您的目标中。

同时安装 Apollo Code Generation CLI——用于从 GraphQL 模式生成 Swift 类型的工具。最简单的方法是通过 Homebrew 安装：

brew install apollo-ios-cli

如果未安装 Homebrew，可以使用 npm：

npm install -g apollo-ios-cli

1.3. 初始化配置

在终端中，从项目根目录执行：

apollo-ios-cli init --module-name YourAppName --schema-namespace GraphQL

此命令将创建 apollo-codegen-config.json 文件和 GraphQL 文件夹，您的 .graphql 文件将存储在其中。

现在将服务器模式添加到项目中。如果服务器提供 schema.json 或 schema.graphqls，请将其复制到 GraphQL 文件夹中。如果没有，可以使用内置命令下载：

apollo-ios-cli fetch-schema --endpoint=https://your-graphql-endpoint.com/graphql

2. 编写第一个 GraphQL 查询（Query）

2.1. 创建 .graphql 文件

在 GraphQL 文件夹中，创建一个 Queries.graphql 文件并编写一个简单查询。假设我们有一个用于获取用户列表的 API：

query GetUsers {  users {    id    name    email  }}

2.2. 生成 Swift 代码

从终端运行代码生成：

apollo-ios-cli generate

成功生成后，在 Sources/API 文件夹（或您指定的文件夹）中会出现一个 API.swift 文件，其中包含 GetUsersQuery、GetUsersQuery.Data 等类型。

2.3. 从 Swift 执行查询

现在创建一个 Apollo 客户端实例并执行查询。在您的 ContentView.swift（或任何其他文件）中编写：

import Apolloimport SwiftUI

class NetworkManager {    static let shared = NetworkManager()    private(set) lazy var apollo = ApolloClient(url: URL(string: "https://your-graphql-endpoint.com/graphql")!)}

struct ContentView: View {    @State private var users: [GetUsersQuery.Data.User] = []        var body: some View {        List(users, id: \\.id) { user in            VStack(alignment: .leading) {                Text(user.name)