AWS SDK for Go V2 操作 Amazon DynamoDB 实战指南:表基础操作、PartiQL 单条与批量查询场景
AWS SDK for Go V2 操作 Amazon DynamoDB 实战指南:表基础操作、PartiQL 单条与批量查询场景
本文以 aws-doc-sdk-examples 仓库
gov2/dynamodb目录下的示例代码为核心,系统讲解如何用 AWS SDK for Go V2 完成 DynamoDB 的表生命周期管理、单条与批量数据操作,以及如何通过 PartiQL 的ExecuteStatement与BatchExecuteStatement以类 SQL 方式读写数据。读完本文,你将掌握三套可独立运行、可测试的 Go 场景:电影表基础操作(Movie Table)、PartiQL 单条语句场景和 PartiQL 批量语句场景,并理解其底层 API 调用链与测试组织方式。
一、示例概述
gov2/dynamodb 目录下的 README.md 展示了如何通过 AWS SDK for Go V2 与 Amazon DynamoDB 协同工作。DynamoDB 是一种全托管的 NoSQL 数据库服务,以快速、可预测的性能和无缝扩展能力著称。该目录中的代码示例按"Actions(单条 API 操作)"与"Scenarios(组合多个 API 的场景)"两个维度组织,前者展示对单个服务函数的调用,后者通过组合调用完成一项具体任务。
这些示例在仓库中扮演两类角色:
- 基础操作(Basics):演示在 DynamoDB 中执行的核心操作序列,即 Learn the basics 场景;
- 场景(Scenarios):Query a table by using batches of PartiQL statements 与 Query a table using PartiQL 两个场景,展示用 PartiQL 语句(含批量形式)完成增删改查。
⚠ 运行前的重要提示
- 运行这些代码可能产生 AWS 账户费用;运行测试同样可能产生费用;
- 官方强烈建议遵循 least privilege(最小权限) 原则,仅授予完成任务所需的最小权限;
- 这些代码并未在所有 AWS 区域经过测试,跨区域使用时需自行验证。
二、环境准备(Prerequisites)
按 gov2 目录 README 的要求,运行示例前需要:
-
一个 AWS 账户,并按 AWS Tools and SDKs Shared Configuration and Credentials Reference Guide 配置默认凭据与默认区域(即
~/.aws下的 credentials 与 config 文件); -
Go 1.18 或更高版本。本模块的 go.mod 声明
go 1.21,并依赖:github.com/aws/aws-sdk-go-v2 v1.30.5(核心 SDK)github.com/aws/aws-sdk-go-v2/config v1.27.33(加载默认配置)github.com/aws/aws-sdk-go-v2/service/dynamodb v1.34.8(DynamoDB 服务客户端)github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue(Go 结构体与 DynamoDB 属性值互转)github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression(构建条件与更新表达式)- 同仓库的
gov2/demotools(交互提问器)与gov2/testtools(测试桩工具)
三、代码示例结构:Actions 与 Scenarios
3.1 单条 API 操作(Single actions)
单个操作示例展示了如何调用某个独立服务函数,全部集中在 actions/table_basics.go 与 actions/partiql.go 中。核心操作与其在源码中的位置对照如下:
| 操作 | 对应 API | 源码位置 |
|---|---|---|
| DescribeTable(判断表是否存在) | DescribeTable |
table_basics.go#L31-L52 |
| CreateTable(建电影表) | CreateTable |
table_basics.go#L54-L95 |
| ListTables(列出所有表) | ListTables(分页器) |
table_basics.go#L97-L117 |
| PutItem(写入单条电影) | PutItem |
table_basics.go#L119-L136 |
| UpdateItem(更新电影评分与剧情) | UpdateItem |
table_basics.go#L138-L173 |
| BatchWriteItem(批量写入) | BatchWriteItem |
table_basics.go#L175-L217 |
| GetItem(按主键读取) | GetItem |
table_basics.go#L219-L239 |
| Query(按年份查询) | Query(分页器) |
table_basics.go#L241-L281 |
| Scan(按年份范围扫描) | Scan(分页器) |
table_basics.go#L283-L328 |
| DeleteItem(删除单条电影) | DeleteItem |
table_basics.go#L330-L343 |
| DeleteTable(删除表) | DeleteTable |
table_basics.go#L345-L357 |
| ExecuteStatement(PartiQL 单条) | ExecuteStatement |
partiql.go#L7 |
| BatchExecuteStatement(PartiQL 批量) | BatchExecuteStatement |
partiql.go#L7 |
3.2 场景(Scenarios)
场景通过组合多个函数完成特定任务,本目录包含三个:
- Learn the basics(
RunMovieScenario):交互式演示创建电影表、写入/读取/更新单条电影、从 JSON 样例批量导入、按年份 Query、按年份区间 Scan、删除电影与表; - Query a table using PartiQL(
RunPartiQLSingleScenario):用单条 PartiQL 语句对单条电影执行 SELECT / INSERT / UPDATE / DELETE; - Query a table by using batches of PartiQL statements(
RunPartiQLBatchScenario):用一批 PartiQL 语句批量执行上述四种操作,并演示带Limit与NextToken的分页投影查询。
三个场景全部通过 cmd/main.go 统一驱动,并使用 scenario 命令行标志选择要运行的场景。
四、运行示例
4.1 场景运行入口(cmd runner)
在 gov2/dynamodb 目录下运行以下命令可获取场景列表与帮助信息:
go run ./cmd -h
cmd/main.go 内部维护了一张 scenarioMap,将三个场景名称映射到对应的入口函数:
movieTable→runMovieScenariopartiQLSingle→runPartiQLSingleScenariopartiQLBatch→runPartiQLBatchScenario
选择场景并运行,例如:
go run ./cmd -scenario movieTable
go run ./cmd -scenario partiQLSingle
go run ./cmd -scenario partiQLBatch
main 函数首先通过 flag.String("scenario", "", ...) 解析 -scenario 参数;若取值不在映射表中,则打印错误并显示 flag.Usage()。随后调用 config.LoadDefaultConfig(ctx) 从 ~/.aws 加载默认凭据与配置(这也是为什么运行前必须完成第二节的环境准备),再以 log.SetFlags(0) 精简日志格式后执行所选场景。
4.2 场景对应的真实表名
cmd/main.go 中三个场景使用的表名如下:
- 电影表场景:
doc-example-movie-table; - PartiQL 单条场景:
doc-example-partiql-single-table; - PartiQL 批量场景:
doc-example-partiql-batch-table。
其中电影表场景会从 https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/samples/moviedata.zip 下载样例电影数据(含 250 部电影的 JSON)并批量写入表中。
五、场景详解一:Learn the basics(电影表基础操作)
RunMovieScenario 的整体流程(对应 scenario_movie_table.go#L39-L203)如下:
- 创建表:调用
TableBasics.TableExists判断doc-example-movie-table是否已存在,不存在则调用CreateMovieTable创建; - 写入单条电影:通过
demotools.IQuestioner交互式收集片名(非空)、上映年份(1900–2030)、评分(1–10)、剧情简介,然后调用AddMovie写入; - 更新单条电影:提示输入新的评分与剧情,调用
UpdateMovie,随后打印更新后的属性; - 批量导入:通过
IMovieSampler.GetSampleMovies()下载并解析样例 JSON,调用AddMovieBatch(ctx, movies, 250)批量写入最多 250 部电影; - 读取单条:列出前
show(最多 10)部电影,让用户选择序号后调用GetMovie读取详情; - Query:输入 1972–2018 之间的年份,调用
Query(ctx, releaseYear)查询该年上映的所有电影; - Scan:输入起止年份,调用
Scan(ctx, startYear, endYear)扫描区间内的电影(结果通过投影只含标题、年份与评分,因此剧情字段为nil); - ListTables:询问用户是否列出当前账户全部表;
- 清理:询问是否删除自建电影与整张表,避免遗留资源产生持续费用。
5.1 表结构与 Movie 模型
CreateMovieTable 创建的复合主键定义如下(table_basics.go#L60-L93):
- 分区键:
year,类型N(数值); - 排序键:
title,类型S(字符串); - 计费模式:
BillingMode: types.BillingModePayPerRequest(按量付费,无需预置吞吐量); - 创建后通过
dynamodb.NewTableExistsWaiter轮询等待,最长 5 分钟,确保表进入ACTIVE状态再返回。
对应的 Movie 结构体 用 dynamodbav 标签映射到 DynamoDB 属性名:
type Movie struct {
Title string `dynamodbav:"title"`
Year int `dynamodbav:"year"`
Info map[string]interface{} `dynamodbav:"info"`
}
Movie.GetKey() 返回可直接发送给 DynamoDB 的主键映射(title 与 year)。MovieSampler 实现 IMovieSampler 接口,通过 http.Get 下载 zip 压缩的 moviedata,在内存中解压并 json.Unmarshal 为 <a href="https://link.gitcode.com/i/2de3b415ab7c57ce1891a5a0861433f4" target="_blank">]Movie([movie.go#L71-L106)。
5.2 用 expression 包构建 Query 与 Scan
Query 与 Scan 都借助 feature/dynamodb/expression 包以类型安全的方式构建表达式,避免手工拼接字符串:
- Query(table_basics.go#L246-L279):
expression.Key("year").Equal(expression.Value(releaseYear))生成键条件表达式KeyConditionExpression,并通过NewQueryPaginator分页拉取全部结果; - Scan(table_basics.go#L289-L326):
expression.Name("year").Between(...)生成过滤表达式FilterExpression,expression.NamesList(...)生成投影表达式ProjectionExpression(仅返回 year、title、info.rating),并通过NewScanPaginator分页。
5.3 UpdateItem 的表达式构建
UpdateMovie(table_basics.go#L143-L171)用 expression.Set(expression.Name("info.rating"), expression.Value(...)) 连续设置两个属性,随后 expression.NewBuilder().WithUpdate(update).Build() 一次性得到 UpdateExpression、ExpressionAttributeNames 与 ExpressionAttributeValues,并设置 ReturnValues: types.ReturnValueUpdatedNew 返回更新后的新值,再通过 attributevalue.UnmarshalMap 反序列化。
5.4 BatchWriteItem 的分批策略
AddMovieBatch(table_basics.go#L180-L215)体现了 DynamoDB 的单次批量写入上限为 25 项这一硬性约束:函数以 batchSize := 25 切片分批构造 types.WriteRequest(每个为 PutRequest),逐批调用 BatchWriteItem,直到写满 maxMovies 或 movies 耗尽,并返回实际写入数量。单位测试 AddMovieBatch(table_basics_test.go#L138-L172)用 30 条测试数据验证了 25+5 的两批分割逻辑。
六、场景详解二:用 PartiQL 单条语句查询表
RunPartiQLSingleScenario(scenario_partiql_single.go#L29-L119)与电影表场景共用 CreateMovieTable 建表(表名 doc-example-partiql-single-table),随后用 PartiQLRunner 依次执行:
-
INSERT:写入一部"24 Hour PartiQL People"电影(年份取当前年),见 partiql.go#L32-L48:
INSERT INTO "表名" VALUE {'title': ?, 'year': ?, 'info': ?} -
SELECT:按 title 与 year 读取该电影,见 partiql.go#L56-L77:
SELECT * FROM "表名" WHERE title=? AND year=? -
UPDATE:把评分更新为 6.6,见 partiql.go#L123-L138:
UPDATE "表名" SET info.rating=? WHERE title=? AND year=? -
SELECT 复查:再次读取以验证更新;
-
DELETE:删除该电影,见 partiql.go#L145-L160:
DELETE FROM "表名" WHERE title=? AND year=? -
清理:删除整张表。
这里的关键机制是 参数化占位符 ?:所有语句都通过 attributevalue.MarshalList 将 Go 值(字符串、数值、map 等)序列化为参数列表传入 Parameters,既保证了类型正确,也避免了 SQL 注入式的拼接风险。
七、场景详解三:用批量 PartiQL 语句查询表
RunPartiQLBatchScenario(scenario_partiql_batch.go#L30-L136)使用表名 doc-example-partiql-batch-table,构造三部"House PartiQL"系列电影,然后演示:
-
AddMovieBatch:批量 INSERT(partiql.go#L168-L189),为每部电影构造
types.BatchStatementRequest,一次BatchExecuteStatement提交; -
GetMovieBatch:批量 SELECT(partiql.go#L197-L229),遍历
output.Responses逐条UnmarshalMap为Movie; -
UpdateMovieBatch:批量 UPDATE,为每部电影设置新评分 7.7 / 4.4 / 1.1(partiql.go#L237-L258);
-
GetAllMovies 分页投影(partiql.go#L86-L115):
SELECT title, info.rating FROM "表名"该调用通过
Limit: aws.Int32(pageSize)(场景中取 2)与NextToken循环翻页,直到服务端不再返回下一页令牌,用于演示 PartiQL 查询结果的分页处理; -
DeleteMovieBatch:批量 DELETE(partiql.go#L266-L287);
-
清理:删除整张表。
八、测试体系:单元测试与集成测试
所有测试统一使用 go test,测试文件与源码同目录存放。根据 gov2/README.md 的说明:
8.1 单元测试(不产生费用)
单元测试通过 gov2/testtools 的 AwsmStubber 拦截 SDK 对 AWS 的调用,校验输入并返回模拟响应,因此不会真正请求 AWS,也不产生费用。本目录的单元测试包括:
- actions/table_basics_test.go:逐一验证
TableExists(含ResourceNotFoundException分支)、CreateMovieTable、AddMovie、UpdateMovie、AddMovieBatch(25 项分批)、GetMovie、Query、Scan、DeleteMovie、DeleteTable、ListTables; - actions/partiql_test.go:验证全部 PartiQL 单条与批量操作的语句字符串、参数列表与结果反序列化;
- scenarios 下的三个 _test.go:以 stub 配置驱动完整场景流程;
- 对应的请求桩定义位于 stubs/table_basics_stubs.go 与 stubs/partiql_stubs.go。
运行单元测试:
go test ./...
8.2 集成测试(可能产生费用)
集成测试(文件名带 _integ_test.go,如 scenario_movie_table_integ_test.go)会向 AWS 发起真实请求,创建和销毁真实资源,可能产生费用。运行方式需附加 integration 构建标签:
go test -tags=integration ./...
九、源码级速查:两个核心封装类型
// TableBasics 封装 DynamoDB 服务动作,持有服务客户端与目标表名
type TableBasics struct {
DynamoDbClient *dynamodb.Client
TableName string
}
// PartiQLRunner 封装 PartiQL 相关服务动作,与 TableBasics 结构相同
type PartiQLRunner struct {
DynamoDbClient *dynamodb.Client
TableName string
}
两个类型的客户端都由 dynamodb.NewFromConfig(sdkConfig) 创建,这也使它们能在单元测试中用 stubber 的 SdkConfig 替换真实配置,实现"可注入、可替换"的测试友好设计。
十、延伸学习资源
- DynamoDB 开发者指南
- DynamoDB API 参考
- SDK for Go V2 的 DynamoDB 包参考
- 同仓库相关实现:gov2/demotools(交互提问器)、gov2/testtools(测试桩)、gov2/README.md(gov2 全部示例的运行与测试总览)
许可证:本文涉及的示例代码遵循 Apache-2.0 许可(Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.),仅用于学习与参考。