企业官网建设流程全解析

• 示例工程
• 教程
• 后端

导读

本指南基于 swift/example_code/rds/README.md 及其配套场景示例，系统讲解如何用 AWS SDK for Swift 与 Amazon Relational Database Service（Amazon RDS）交互。文章以仓库中的rds-scenario可执行示例为主线，完整覆盖"查询引擎版本 → 创建自定义 DB 参数组 → 修改参数 → 创建 DB 实例 → 等待就绪 → 创建快照 → 清理回收"的端到端流程，并逐一解析 12 个单动作 API 的入参与底层调用细节。读完本文，你将能够独立构建、运行并读懂这套 RDS 入门场景代码，掌握在 Swift 中通过 AWS SDK 管理关系型数据库实例的完整方法论。

概述：Amazon RDS 与 Swift SDK 的组合

Amazon RDS 是一项让用户"更容易在云中设置、运维和扩展关系型数据库"的 Web 服务。它托管了 MySQL、PostgreSQL、MariaDB 等引擎的数据库实例，并承担了补丁升级、备份、容错等繁重运维工作。

本仓库中的 RDS 示例位于 swift/example_code/rds，目标是用 AWS SDK for Swift）引入 RDS 客户端，所有调用均为异步 Swift 并发风格（async/await），符合 SDK for Swift 的现代编程范式。

⚠费用提醒：运行本示例或相关测试都可能对您的 AWS 账户产生费用。官方建议遵循最小权限原则，仅授予完成任务所需的最低权限；同时请注意，这些代码并未在所有 AWS 区域做过测试，请结合 AWS Regional Services 确认目标区域的可用性。

前置条件

运行 RDS 示例前，需要先完成以下准备（详见 swift/README.md）：

• 拥有 AWS 账户，并按 AWS SDK for Swift 开发者指南的 Getting started 章节配置好默认凭证与默认区域。
• 安装 Swift 编译器（5.4 或更高版本）及配套工具；若已安装新版 Xcode，则已自带 Swift 工具链。
• 部分示例对 Swift 工具版本有更高要求，应以示例目录下Package.swift顶部注释声明的swift-tools-version为准——本 RDS 场景示例要求Swift 5.9（见 scenario/Package.swift）。

代码示例一览

单动作（Single actions）

每个单动作都是一段聚焦单个服务 API 调用的代码摘录，全部实现在场景入口文件 scenario/Sources/entry.swift 中，列表如下：

场景（Basics）：Learn the basics

Learn the basics 是一个完整的入门场景示例，通过组合多个 RDS API 完成一条典型实例生命周期。它演示了以下四项核心能力：

• 创建自定义 DB 参数组，并设置参数值。
• 创建配置了该参数组、且内建一个数据库的 DB 实例。
• 对该实例拍摄快照（snapshot）。
• 删除实例与参数组。

这一"创建 → 使用 → 备份 → 清理"的闭环正是生产环境中 RDS 资源治理的最小模型。

运行示例

构建方式

从终端进入示例目录后执行：

$ swift build

若要在 Xcode 中构建，进入示例目录（例如rds场景目录）后输入xed .，即可用 Xcode 打开该目录并按标准 Xcode 构建、运行命令执行。

运行场景程序

场景可执行目标名为rds-scenario（见 Package.swift），入口文件顶部通过ArgumentParser声明了三个命令行参数（entry.swift#L15-L21）：

@main入口（entry.swift#L818-L831）解析参数后调用ExampleCommand.runAsync()，内部构造Example对象并执行主流程。构建完成后，可通过类似方式携带参数运行：

$ swift run rds-scenario --db-password 'YourPassword'

场景主流程：14 步全生命周期详解

Example.run()（entry.swift#L66-L291）是场景的主干，其每一步都可与上文列出的单动作一一对应，下面按执行顺序展开。

第 1 步：探测 MySQL 引擎版本与参数组家族

调用getDBEngineVersions(engineName: "mysql")（封装describeDBEngineVersions，entry.swift#L303-L324），把返回结果中每个版本携带的dbParameterGroupFamily收集进一个Set<String>。这一步本质上是"先摸清当前区域支持哪些 MySQL 参数组家族"，为后续创建参数组选定familyName。若未找到任何可用版本，程序会直接清理退出。

第 2 步：选择家族并创建自定义 DB 参数组

对家族集合排序后取最后一个作为selectedFamily，再用tempName(prefix: "rds-example")生成随机唯一名称（随机数取自 100 万到 10 亿之间，entry.swift#L799-L801），随后调用createDBParameterGroup（entry.swift#L326-L348）。

其入参为：

CreateDBParameterGroupInput( dbParameterGroupFamily: familyName, // 参数组家族，如 mysql8.0 dbParameterGroupName: groupName, // 自定义参数组名称 description: "Created using the AWS SDK for Swift" )

第 3 步：核对参数组详情

调用describeDBParameterGroups（entry.swift#L350-L371）按名称查询刚创建的参数组并打印清单，用于验证创建结果。此调用对应单动作列表中的DescribeDBParameterGroups。

第 4～5 步：分页拉取并解析全部参数

describeDBParameters（entry.swift#L373-L411）展示了 SDK for Swift 的分页遍历模式：

let pages = rdsClient.describeDBParametersPaginated( input: DescribeDBParametersInput( dbParameterGroupName: groupName, source: source // 可选："user" / "system" / "engine-default" ) ) for try await page in pages { parameterList += page.parameters ?? [] }

由于参数组内参数通常很多，这里利用AsyncSequence风格的for try await逐页累加，最终从完整列表里挑出auto_increment_offset与auto_increment_increment两个参数，打印其parameterValue、dataType、description、allowedValues字段。source参数用于过滤参数来源：user表示用户自定义的修改、system表示系统参数、engine-default表示引擎默认值。

第 6 步：一次调用修改两个参数

modifyDBParameters（entry.swift#L413-L446）构造两个RDSClientTypes.Parameter对象：

let parameter1 = RDSClientTypes.Parameter( applyMethod: RDSClientTypes.ApplyMethod.immediate, // 立即生效 parameterName: "auto_increment_offset", parameterValue: "5" ) let parameter2 = RDSClientTypes.Parameter( applyMethod: RDSClientTypes.ApplyMethod.immediate, parameterName: "auto_increment_increment", parameterValue: "5" ) let parameterList = [parameter1, parameter2] _ = try await rdsClient.modifyDBParameterGroup( input: ModifyDBParameterGroupInput( dbParameterGroupName: groupName, parameters: parameterList ) )

注意这里把两个参数打包在一次请求中提交，applyMethod设为immediate表示无需重启实例即可生效（另一个可选值为pending-reboot）。

第 7 步：按来源过滤，复核修改结果

再次调用describeDBParameters(groupName:source: "user")，只取source == "user"的参数并打印，用于确认第 6 步的修改已经落库。这是"先改后查"的验证闭环，也是排查参数是否生效的惯用手段。

第 8 步：列出该家族允许的引擎版本

listAllowedEngines(family:)（entry.swift#L453-L475）再次调用describeDBEngineVersions，同时传入dbParameterGroupFamily与engine: "mysql"，打印该家族下每个版本号及其描述，用于确认所选版本的合法性。

第 9 步：挑选 micro 规格的实例类型

chooseMicroInstance（entry.swift#L477-L527）使用describeOrderableDBInstanceOptionsPaginated按引擎与版本分页拉取可选实例规格，仅保留类名包含"micro"的项并打印清单，最终返回第一个匹配项。这一策略既规避了跨区域规格差异，也控制了示例成本（micro 规格通常属于低配档位）。

第 10 步：创建带数据库的 DB 实例

createDBInstance（entry.swift#L529-L579）是场景的核心，其入参体现了创建实例时最常用的配置维度：

CreateDBInstanceInput( allocatedStorage: 100, // 100 GB 通用存储 dbInstanceClass: instanceClass, // 上一步选出的 micro 规格 dbInstanceIdentifier: instanceIdentifier, // 随机唯一实例标识 dbName: name, // 形如 SampleDatabase<随机9位> dbParameterGroupName: parameterGroupName, // 关联第 2 步创建的自定义参数组 engine: "mysql", engineVersion: engineVersion, // 第 1 步选定的版本 masterUserPassword: password, masterUsername: username, storageType: "gp2" // 通用型 SSD )

成功后会返回并打印新实例的ARN（dbInstanceArn）；失败则进入清理流程。

第 11 步：轮询等待实例就绪

waitUntilDBInstanceReady（entry.swift#L581-L625）演示了标准的轮询模式：循环调用describeDBInstances，检查dbInstanceStatus是否包含"available"；否则每 15 秒（Task.sleep(for: .seconds(15))）重试一次并打印.提示进度。注释明确指出该过程最长可能超过 10 分钟，实例创建与初始化期间状态会依次经历creating等中间态。

实例就绪后，取出endpoint（主机名 + 端口）并打印可直接使用的连接命令：

mysql -h <endpointAddress> -P <endpointPort> -u <dbUsername>

第 13～14 步：创建快照并等待就绪

createDBSnapshot（entry.swift#L627-L654）以实例标识和随机快照标识（前缀sample-snapshot）调用createDBSnapshot，成功后打印快照的资源 ID（dbiResourceId）。随后waitUntilDBSnapshotReady（entry.swift#L656-L703）沿用与第 11 步相同的 15 秒轮询节奏，通过describeDBSnapshots检查快照status是否变为"available"。

清理：删除实例与参数组

主流程结束时调用cleanUp()（entry.swift#L293-L301），依次执行：

1. deleteDBInstance（entry.swift#L705-L723）——注意其入参同时设置了deleteAutomatedBackups: true（删除自动备份）与skipFinalSnapshot: true（跳过最终快照），避免遗留备份资源；
2. waitUntilDBInstanceDeleted（entry.swift#L729-L768）——轮询describeDBInstances直到目标实例从列表中消失（同样 15 秒间隔）；
3. deleteDBParameterGroup（entry.swift#L770-L785）——删除第 2 步创建的自定义参数组。

任何步骤失败都会提前跳转到cleanUp()，保证异常路径下资源也能被回收，避免残留计费资源。

工程细节：Swift Package 配置

场景的 Package.swift 定义了完整的 SwiftPM 工程，关键配置如下：

• swift-tools-version: 5.9：声明构建所需的最低 Swift 工具版本（文件顶部以注释形式同时出现在 snippet 首行，是因为该声明必须位于文件第一行，同时又要进入代码摘录块）。
• 平台声明：platforms: [.macOS(.v13), .iOS(.v15)]，即最低支持 macOS 13 与 iOS 15。
• 依赖项：
  • https://github.com/awslabs/aws-sdk-swift，版本约束from: "1.4.0"，提供AWSRDS产品模块；
  • https://github.com/apple/swift-argument-parser.git（main分支），提供ArgumentParser模块，用于命令行参数解析。
• 可执行目标rds-scenario，依赖AWSRDS与ArgumentParser，源码目录为Sources。

测试说明

⚠ 运行测试同样可能对 AWS 账户产生费用。Swift 示例的测试运行方式统一为在示例目录下执行swift test（详见 swift/README.md#Tests）。RDS 场景示例侧重演示真实云上资源操作，其正确性最终由"创建成功 → 状态可轮询到 available → 清理完毕"这一运行链路上的打印输出与实际资源状态来验证。

延伸阅读

• Amazon RDS 用户指南（Amazon RDS User Guide）
• Amazon RDS API Reference
• SDK for Swift Amazon RDS 参考（AWSRDS 模块的 Swift 文档）

在仓库内还可继续探索：swift/example_code/rds/scenario/Sources/entry.swift 的完整源码与 scenario/Package.swift 的工程配置，以及 swift/example_code/swift-sdk 下的 ErrorHandling、Waiters、pagination 等主题示例——它们与本场景中for try await分页、轮询与错误处理等模式一脉相承。

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: Apache-2.0

• 示例工程
• 教程
• 后端