AWS SDK for Go V2 操作 Amazon DynamoDB 实战指南:表基础操作、PartiQL 单条与批量查询场景

原创2026-09-24 22:33:011,889 阅读
文章标签:示例工程教程后端

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 的场景)"两个维度组织,前者展示对单个服务函数的调用,后者通过组合调用完成一项具体任务。

这些示例在仓库中扮演两类角色:

⚠ 运行前的重要提示

  • 运行这些代码可能产生 AWS 账户费用;运行测试同样可能产生费用;
  • 官方强烈建议遵循 least privilege(最小权限) 原则,仅授予完成任务所需的最小权限;
  • 这些代码并未在所有 AWS 区域经过测试,跨区域使用时需自行验证。

二、环境准备(Prerequisites)

按 gov2 目录 README 的要求,运行示例前需要:

  1. 一个 AWS 账户,并按 AWS Tools and SDKs Shared Configuration and Credentials Reference Guide 配置默认凭据与默认区域(即 ~/.aws 下的 credentials 与 config 文件);

  2. 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)

场景通过组合多个函数完成特定任务,本目录包含三个:

  1. Learn the basics(RunMovieScenario):交互式演示创建电影表、写入/读取/更新单条电影、从 JSON 样例批量导入、按年份 Query、按年份区间 Scan、删除电影与表;
  2. Query a table using PartiQL(RunPartiQLSingleScenario):用单条 PartiQL 语句对单条电影执行 SELECT / INSERT / UPDATE / DELETE;
  3. 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 → runMovieScenario
  • partiQLSingle → runPartiQLSingleScenario
  • partiQLBatch → 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)如下:

  1. 创建表:调用 TableBasics.TableExists 判断 doc-example-movie-table 是否已存在,不存在则调用 CreateMovieTable 创建;
  2. 写入单条电影:通过 demotools.IQuestioner 交互式收集片名(非空)、上映年份(1900–2030)、评分(1–10)、剧情简介,然后调用 AddMovie 写入;
  3. 更新单条电影:提示输入新的评分与剧情,调用 UpdateMovie,随后打印更新后的属性;
  4. 批量导入:通过 IMovieSampler.GetSampleMovies() 下载并解析样例 JSON,调用 AddMovieBatch(ctx, movies, 250) 批量写入最多 250 部电影;
  5. 读取单条:列出前 show(最多 10)部电影,让用户选择序号后调用 GetMovie 读取详情;
  6. Query:输入 1972–2018 之间的年份,调用 Query(ctx, releaseYear) 查询该年上映的所有电影;
  7. Scan:输入起止年份,调用 Scan(ctx, startYear, endYear) 扫描区间内的电影(结果通过投影只含标题、年份与评分,因此剧情字段为 nil);
  8. ListTables:询问用户是否列出当前账户全部表;
  9. 清理:询问是否删除自建电影与整张表,避免遗留资源产生持续费用。

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 依次执行:

  1. INSERT:写入一部"24 Hour PartiQL People"电影(年份取当前年),见 partiql.go#L32-L48:

    INSERT INTO "表名" VALUE {'title': ?, 'year': ?, 'info': ?}
    
  2. SELECT:按 title 与 year 读取该电影,见 partiql.go#L56-L77:

    SELECT * FROM "表名" WHERE title=? AND year=?
    
  3. UPDATE:把评分更新为 6.6,见 partiql.go#L123-L138:

    UPDATE "表名" SET info.rating=? WHERE title=? AND year=?
    
  4. SELECT 复查:再次读取以验证更新;

  5. DELETE:删除该电影,见 partiql.go#L145-L160:

    DELETE FROM "表名" WHERE title=? AND year=?
    
  6. 清理:删除整张表。

这里的关键机制是 参数化占位符 ?:所有语句都通过 attributevalue.MarshalList 将 Go 值(字符串、数值、map 等)序列化为参数列表传入 Parameters,既保证了类型正确,也避免了 SQL 注入式的拼接风险。

七、场景详解三:用批量 PartiQL 语句查询表

RunPartiQLBatchScenario(scenario_partiql_batch.go#L30-L136)使用表名 doc-example-partiql-batch-table,构造三部"House PartiQL"系列电影,然后演示:

  1. AddMovieBatch:批量 INSERT(partiql.go#L168-L189),为每部电影构造 types.BatchStatementRequest,一次 BatchExecuteStatement 提交;

  2. GetMovieBatch:批量 SELECT(partiql.go#L197-L229),遍历 output.Responses 逐条 UnmarshalMap 为 Movie;

  3. UpdateMovieBatch:批量 UPDATE,为每部电影设置新评分 7.7 / 4.4 / 1.1(partiql.go#L237-L258);

  4. GetAllMovies 分页投影(partiql.go#L86-L115):

    SELECT title, info.rating FROM "表名"
    

    该调用通过 Limit: aws.Int32(pageSize)(场景中取 2)与 NextToken 循环翻页,直到服务端不再返回下一页令牌,用于演示 PartiQL 查询结果的分页处理;

  5. DeleteMovieBatch:批量 DELETE(partiql.go#L266-L287);

  6. 清理:删除整张表。

八、测试体系:单元测试与集成测试

所有测试统一使用 go test,测试文件与源码同目录存放。根据 gov2/README.md 的说明:

8.1 单元测试(不产生费用)

单元测试通过 gov2/testtools 的 AwsmStubber 拦截 SDK 对 AWS 的调用,校验输入并返回模拟响应,因此不会真正请求 AWS,也不产生费用。本目录的单元测试包括:

运行单元测试:

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 替换真实配置,实现"可注入、可替换"的测试友好设计。

十、延伸学习资源


许可证:本文涉及的示例代码遵循 Apache-2.0 许可(Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.),仅用于学习与参考。

登录后查看全文
aws-doc-sdk-examples