为何AWS SDK中DynamoDB的ReturnValue等类型定义包含string类型

问题描述 #

从官方AWS SDK中提取到DynamoDB相关的如下类型定义：

export type ReturnValue = "NONE"|"ALL_OLD"|"UPDATED_OLD"|"ALL_NEW"|"UPDATED_NEW"|string;      
export type ReturnConsumedCapacity = "INDEXES"|"TOTAL"|"NONE"|string;
export type ReturnItemCollectionMetrics = "SIZE"|"NONE"|string;
export type ReturnValuesOnConditionCheckFailure = "ALL_OLD"|"NONE"|string;

相关疑问如下：

• 上述类型定义为何要在已知的字面量枚举值之外额外联合string类型？
• 这种写法和直接将类型声明为纯string（如下写法）存在什么差异：

export type ReturnValue = string;

• 实际开发中发现，由于类型联合了通用string类型，IDE无法为这些字段提供预设枚举值的自动补全，该写法的设计考量是什么？

解答 #

核心设计目的：向前兼容兜底 #

这种写法是AWS SDK v3全系列通用的类型设计范式，核心是为了适配云服务的迭代节奏：DynamoDB作为托管服务，服务端可能随时新增这类参数的合法取值，但SDK的类型定义发版节奏必然滞后于服务端更新。如果类型只写死当前版本已知的字面量联合，当服务端上线新的合法值时，还没升级SDK的用户传入该值会直接触发TypeScript类型报错，哪怕这个值在服务端是完全可正常生效的。末尾联合string相当于留了类型逃生通道，允许用户传入服务端已支持、但当前SDK版本类型尚未收录的字符串值，不会被类型系统无意义拦截。

和纯string类型的差异 #

不少开发者会误以为"NONE"|"ALL_OLD"|...|string会被TypeScript直接折叠为string，实际上两者存在明确差异：

• 从类型校验规则看，两者确实等价：任意字符串值都可以被这两种类型接收，不会触发类型不匹配错误
• 从信息承载能力看，前者把当前官方明确支持的合法值直接写在了类型定义里，开发者跳转到类型声明就能直接看到所有已知可选值，相当于内置了一份轻量文档，不需要额外翻找API文档
• 关于IDE自动补全失效的问题：TypeScript 4.5及以上版本的语言服务本身是支持识别这类"字面量联合+基础类型兜底"的写法、正常给出字面量补全的，如果遇到补全失效，一般是本地项目使用的TypeScript版本过低，或者IDE的TypeScript语言服务配置异常导致的。

为什么不采用纯字面量联合/枚举的写法 #

这是严谨性和灵活性权衡后的选择：

• 如果只用纯字面量联合、不做string兜底，就会出现前面提到的向前兼容问题，用户必须跟随服务端更新频繁升级SDK版本才能使用新特性，生产环境下SDK升级的验证成本很高，会给用户造成不必要的阻碍
• 如果使用TypeScript枚举，一方面枚举会生成额外的运行时代码，增加SDK打包体积，另一方面同样存在纯字面量联合的版本兼容问题，新增枚举值必须发布新版本SDK才能被类型系统识别。

内容的提问来源于stack exchange，提问作者Ankit Aabad