Go(AWS SDK v2)中的 DynamoDB PutItem
PutItem 写入一个完整项目,创建它,或替换任何具有相同主键的现有项目。在 AWS SDK for Go v2 中,你用一个 dynamodb.PutItemInput 调用 client.PutItem,其 Item 映射把每个属性都存为来自 types 包的带类型值。
Code
package main
import (
"context"
"errors"
"fmt"
"log"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/dynamodb"
"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)
func main() {
ctx := context.TODO()
cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-east-1"))
if err != nil {
log.Fatalf("load config: %v", err)
}
client := dynamodb.NewFromConfig(cfg)
_, err = client.PutItem(ctx, &dynamodb.PutItemInput{
TableName: aws.String("Music"),
Item: map[string]types.AttributeValue{
"Artist": &types.AttributeValueMemberS{Value: "Arturo Sandoval"},
"SongTitle": &types.AttributeValueMemberS{Value: "Cubano Chant"},
"AlbumTitle": &types.AttributeValueMemberS{Value: "Danzon"},
"Year": &types.AttributeValueMemberN{Value: "1994"},
"Awards": &types.AttributeValueMemberN{Value: "0"},
},
ConditionExpression: aws.String("attribute_not_exists(#cond0) AND attribute_not_exists(#cond1)"),
ExpressionAttributeNames: map[string]string{
"#cond0": "Artist",
"#cond1": "SongTitle",
},
})
if err != nil {
var ccf *types.ConditionalCheckFailedException
if errors.As(err, &ccf) {
fmt.Println("A song with that key already exists — not overwritten")
return
}
log.Fatalf("put item: %v", err)
}
fmt.Println("Song written")
}要改从普通的 Go 结构体构建 Item 映射,请使用 github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue 中的 attributevalue.MarshalMap。
说明
Item— 必须包含表的完整主键,外加任意其他属性。数字在AttributeValueMemberN内是字符串({Value: "1994"})。- Put 是替换 — 没有条件时,
PutItem会静默地覆盖具有相同键的现有项目。要在不清除其余部分的情况下更改少数属性,请用UpdateItem。 ConditionExpression— 对键属性使用attribute_not_exists(...)会让写入变成一次仅创建插入;如果项目已存在,写入会以ConditionalCheckFailedException失败。这是 DynamoDB 的乐观锁原语。#cond0/#cond1别名通过ExpressionAttributeNames解析为Artist/SongTitle(保留字安全)。errors.As— Go SDK 会包装服务错误,因此请用errors.As匹配带类型的*types.ConditionalCheckFailedException,绝不要用字符串比较。- 要取回被覆盖的项目,请设置
ReturnValues: types.ReturnValueAllOld。
可视化操作
手工写一次条件 put?DynamoDB Expression Builder 会组装 ConditionExpression 并复制代码。
想在 GUI 中添加和编辑项目——每个属性一个表单、类型选择器、复制为代码——请下载 DynoTable。
相关示例
- Java 中的 DynamoDB PutItem — 用 AWS SDK for Java 2.x 完成同样的条件写入。
- Go 中的 DynamoDB UpdateItem — 更改特定属性而非替换整个项目。
- DynamoDB 条件表达式 —
attribute_not_exists、乐观锁等等。 - DynamoDB ConditionalCheckFailedException — 当项目已存在时,仅创建条件会抛出什么。
- DynamoDB ValidationException — 项目或表达式格式错误时的通用错误。
References
- PutItem — Amazon DynamoDB API Reference
- Use PutItem with an AWS SDK or CLI — Amazon DynamoDB Developer Guide
- dynamodb package — AWS SDK for Go v2 (pkg.go.dev)
- dynamodb/types package — AWS SDK for Go v2 (pkg.go.dev)
- Handling errors — AWS SDK for Go v2 Developer Guide
- Condition expressions — Amazon DynamoDB Developer Guide
Last verified 2026-07-13 against the official AWS documentation linked above.