DynamoDB Streams中AttributeValue类型不兼容问题及原因问询

问题背景 #

在TypeScript中使用@aws-sdk/util-dynamodb提供的unmarshall函数反序列化DynamoDB流记录时，遇到类型不兼容错误：

Argument of type '{ [key: string]: AttributeValue; }' is not assignable to parameter of type 'Record<string, AttributeValue>'. Index signatures are incompatible. Type 'AWSLambda.AttributeValue' is not assignable to type 'import("/Users/hitesh/learnapp/la-aws/node_modules/@aws-sdk/client-dynamodb/dist-types/models/models_0").AttributeValue'. Property '$unknown' is missing in type 'AttributeValue' but required in type '$UnknownMember'.

核心矛盾是@aws-sdk/client-dynamodb与@types/aws-lambda/trigger/dynamodb-stream.d.ts中定义的AttributeValue类型存在差异。

差异产生的原因 #

• 维护主体不同：@types/aws-lambda是社区维护的第三方类型包（归属DefinitelyTyped），而@aws-sdk/client-dynamodb是AWS官方维护的SDK，自带官方类型定义。两者的维护团队、更新节奏完全独立。
• 类型设计逻辑不同：
  • AWS SDK v3的AttributeValue加入了$unknown属性，用于兼容服务端返回的未在类型定义中声明的字段，属于SDK层面的容错设计，确保能处理API返回的所有可能数据。
  • @types/aws-lambda中的AttributeValue是基于Lambda触发时DynamoDB流的实际数据结构设计，更贴合Lambda事件的场景，没有考虑SDK通用的未知字段兼容逻辑。
• 版本迭代不同步：AWS服务和官方SDK会持续更新，社区维护的@types/aws-lambda可能存在版本滞后，或者在类型细节上与官方SDK的设计方向不一致。

临时解决方法 #

可以通过类型断言跳过类型检查，将Lambda流中的AttributeValue转换为SDK要求的类型：

import { unmarshall } from "@aws-sdk/util-dynamodb";
import type { DynamoDBStreamEvent } from "aws-lambda";
import type { AttributeValue } from "@aws-sdk/client-dynamodb";

export const handler = async (event: DynamoDBStreamEvent) => {
  for (const record of event.Records) {
    if (!record.dynamodb?.NewImage) continue;
    // 类型断言转换类型
    const deserializedItem = unmarshall(record.dynamodb.NewImage as Record<string, AttributeValue>);
    // 处理反序列化后的条目
    console.log(deserializedItem);
  }
};

内容的提问来源于stack exchange，提问作者Hitesh Balwani