Introducing the Server Side Cloud Swift SDK

推出面向服务器端的 Google Cloud Swift SDK | Google Cloud 博客

开发者与实践者

推出面向服务器端的 Google Cloud Swift SDK

2026年10月1日

##### Karl Weinmeister

开发关系总监

##### Carlos O'Ryan

软件工程师

多年来，Swift 主要被视为与苹果客户端设备绑定的 UI 语言。随着 Swift 6 的发布和严格的并发检查机制，Swift 已经成熟为一种可行的系统和云语言，兼具类似 Rust 的数据竞争安全性与可预测的、基于引用计数的性能表现。

为支持这一生态系统，Google 工程团队推出了官方的 Google Cloud Swift API 客户端库。该 SDK 专为 Swift 6.2+ 从零构建，采用最新的非阻塞 Swift NIO 事件循环、HTTP/2 多路复用、gRPC 传输以及零成本编译时数据竞争安全性机制。

在本文中，我们将为您逐步讲解如何入门，并深入解析 Server Side Cloud Swift SDK（即 google-cloud-swift）的工作原理。

服务器端 Swift 的兴起与云原生并发

传统后端开发通常需要在开发者体验与资源利用率之间做出权衡。虽然托管运行时提供了快速开发能力，但低级系统语言则能提供更精细的内存和 CPU 占用控制，但往往以牺牲功能迭代速度为代价。

服务器端 Swift 的目标是实现实际的平衡。Swift 将轻量级运行时和自动引用计数（ARC）与表达性强的语法相结合。更重要的是，Swift 6 引入了编译时并发检查机制。当您在云微服务中跨异步任务共享状态时，编译器会强制要求类型符合 Sendable 协议。数据竞争问题会在二进制文件编译或部署到生产环境之前，就通过编辑器被检测出来。

在网络层，所有对 Google Cloud API 的请求都通过事件驱动的非阻塞套接字进行传输，可在多核 Linux 服务器环境中横向扩展，而无需为每个连接创建系统线程。

如果你正在为 Apple App Store 开发 iOS、iPadOS 或 visionOS 应用，不应将 google-cloud-swift 直接嵌入到客户端捆绑包中。在客户端二进制文件中嵌入 Google Cloud 服务账户密钥或管理凭据会带来安全风险。对于直接的客户端功能，请使用 Firebase SDK for Apple Platforms 来处理用户认证、实时 Firestore 同步和客户端安全规则，或通过自己的 Cloud Run 后端 API 路由请求。

在 IDE 和包中入门

由于 google-cloud-swift 将 Linux 和 macOS 视为一等公民，你可以在 Apple 硬件上使用 Xcode 开发，或在 Linux 工作站上使用 Visual Studio Code 和 swiftly 进行开发。

要使用 swiftly CLI 安装器在 Linux 工作站上安装官方 Swift 编译器，请运行：

Loading...

curl -O https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz && tar zxf swiftly-$(uname -m).tar.gz && ./swiftly init --quiet-shell-followup && . "${SWIFTLY_HOME_DIR:-$HOME/.local/share/swiftly}/env.sh" && hash -r

或者，你可以直接从官方 Swift 下载页面下载适用于 Ubuntu、Debian、Fedora 或 Amazon Linux 的预构建工具链 tarball。请注意 google-cloud-swift 需要 Swift 6.2 或更高版本，因此安装后使用 swift --version 验证编译器版本。

在跨 Linux 文件系统克隆时，为了解决 Swift 包管理器裸仓库信任警告，请在构建前使用 git config --global safe.bareRepository all 配置 Git。

将所需包添加到你的 Package.swift 清单中：

swift package add-dependency https://github.com/googleapis/swift-google-cloud-language-v2.git --from 0.4.0 swift package add-target-dependency GoogleCloudLanguageV2 CloudBackendService --package swift-google-cloud-language-v2

在 macOS 上你需要修改 platforms 指令：

// swift-tools-version: 6.2 import PackageDescription let package = Package( name: "CloudBackendService", // 在 Darwin/macOS 上编译时应用；Linux 目标由 SPM 忽略 platforms: [.macOS(.v15)], ... ...

在大多数环境中，默认初始化的客户端可以发起请求：

import Foundation import GoogleCloudLanguageV2 func analyzeTextSentiment(text: String) async throws { // 显式初始化 API 密钥凭证 let client = try LanguageServiceClient() // 使用结构化构建器闭包配置请求 let document = Document().with { $0.type = .plainText $0.source = .content(text) } let response = try await client.analyzeSentiment( request: AnalyzeSentimentRequest().with { $0.document = document } ) if let sentiment = response.documentSentiment { print("Document sentiment score: $sentiment.score)") } }

注意 Document().with { ... } 通过提供一个干净的线程安全配置闭包，避免了冗长的临时变量或变异设置器。

网络、传输和认证

该仓库将基础设施原语拆分为 packages/ 下的模块化包：

• swift-google-cloud-auth：实现应用默认凭证发现、服务账户 JWT 签名、工作负载身份联合的外部账户交换以及 API 密钥。

• swift-google-cloud-wkt：为 Google 协议缓冲区知名类型提供符合 Swift 风格的类型，包括与 Swift 的 Date 类型无缝桥接的纳秒精度 Timestamp 表示。

• swift-google-cloud-gax：处理 Google API 扩展功能，例如自动重试循环、指数退避和分页状态机。

当使用无参数方式初始化任何客户端库时，Credentials.default() 会自动扫描环境（GOOGLE_APPLICATION_CREDENTIALS、配额项目变量或本地 Google Cloud CLI 配置），并通过 gRPC 或 HTTP/2 对连接进行身份验证。

如果需要通过 API 密钥显式覆盖凭据或附加自定义访问头，可以传递显式配置选项。例如，可以修改之前的示例，使用以下代码：

import Foundation import GoogleCloudAuth import GoogleCloudGax import GoogleCloudLanguageV2

func analyzeTextSentiment(apiKey: String, text: String) async throws { // 初始化显式 API 密钥凭据 let credentials = try Credentials(configuration: .apiKey(apiKey)) let client = try LanguageServiceClient( ClientOptions().with { $0.credentials = credentials } ) // 使用结构化构建器闭包配置请求 let document = Document().with { $0.type = .plainText $0.source = .content(text) } let response = try await client.analyzeSentiment( request: AnalyzeSentimentRequest().with { $0.document = document } ) if let sentiment = response.documentSentiment { print("Document sentiment score: $sentiment.score)") } }

自动生成的客户端生态系统

Google Cloud 运营着一个庞大的 API 生态系统，其模式会定期更新。支持 google-cloud-swift 的团队使用代码生成器自动将最新功能和新 API 更新到客户端库中。使用代码生成器可以生成稳定的 API，避免出现破坏性变更。虽然发布遵循固定节奏，但如果急需特定功能或 API，请联系 Cloud Customer Care。

无论您需要在 Secret Manager 中轮换密钥，还是通过 Gemini API 在 Gemini Enterprise Agent Platform 上调用多模态推理模型，生成的 SDK 都遵循一致的命名规范和 async/await 签名。

这些生成的客户端提供的不仅仅是简单的单向 RPC 封装器。它们还提供简化应用开发的封装器。例如，迭代长结果时，需要通过一次 RPC 获取结果页、迭代结果页，然后准备新请求以获取下一页。使用生成的客户端，这将变成异步迭代器。以下示例展示了如何使用 GoogleCloudSecretManagerV1 查询项目密钥：

import Foundation import GoogleCloudSecretManagerV1

@main struct SecretManagerQuickstart { static func main() async throws { guard let projectId = CommandLine.arguments.dropFirst().first else { print("Usage: SecretManagerQuickstart <projectId>") exit(1) } // 自动使用默认应用凭据连接 let client = try SecretManagerServiceClient() let request = ListSecretsRequest().with { $0.parent = "projects/$projectId)" } // 异步序列自动流式传输密钥页 print("Secrets in project $projectId):") for try await item in try client.listSecretsByItem(request: request) { print(" - $item.name)") } } }

分页响应返回一个异步序列（AsyncSequence）。您可以使用 for try await 迭代项，而客户端库会在后台通过非阻塞 NIO 通道获取后续页面。

下一步

使用 google-cloud-swift，服务端 Swift 开发者可以借助编译时竞态安全机制、原生异步/等待 API 以及零操作系统线程阻塞特性，构建端到端的云基础设施。

要查看源代码、提交问题或贡献新包装器，请访问官方仓库 googleapis/google-cloud-swift。

想讨论服务端 Swift 架构或 Cloud Run 容器化方案？加入 Google 开发者计划继续交流。

发布于

• 开发者与实践者