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

相关示例

References

Last verified 2026-07-13 against the official AWS documentation linked above.

无需控制台即可使用 DynamoDB

DynoTable 是面向 DynamoDB 的快速桌面客户端 —— 浏览表、运行 SQL 风格的查询,并在本地编辑项。