TypeScript中如何对对象及API返回的JSON对象做类型标注？

针对API返回JSON做类型注解的相关问题解答 #

1. 是否需要为每个参数、嵌套对象都定义类型？

不需要，根据实际使用场景灵活调整即可：

• 只用到一两次的简单对象，直接写内联对象类型即可，无需单独定义
• 复用频率高的子结构、公共结构抽成单独的type或interface，便于统一维护
• 无需定义响应体的所有字段，只需要声明你实际会用到的字段即可，TypeScript 是结构类型系统，只要用到的字段类型匹配即可通过校验，未声明的多余字段不会影响类型正确性。

2. 提前不知道响应体结构如何处理？

• 临时调试阶段可以先用unknown标注响应类型，拿到实际返回结果后再补全类型，不要直接用any丢失类型校验能力
• 可以先调用一次接口拿到真实返回的JSON结构，借助JSON转TS的工具自动生成对应类型，无需手动逐行编写
• 如果是和后端协同开发，可以先和后端约定好响应结构，提前定义类型，不需要等接口开发完再处理

3. 响应体很长、包含大量嵌套对象和对象数组如何处理？

• 把嵌套的公共子结构单独拆分定义，比如响应里有用户信息列表，就先单独定义User类型，再在父类型里用user: User或者userList: User[]引用即可，避免重复编写相同结构
• 如果后端提供了Swagger/OpenAPI接口文档，可以直接用工具自动生成全量接口的请求、响应类型，完全不需要手动编写，准确度高还节省时间

通用最佳实践 #

• 优先做最小可用的类型定义，不需要追求一次性定义完所有字段，后续用到新字段再补充即可，避免无用的前期工作量
• 配合运行时校验工具使用，比如zod，既可以推导出TS类型，又能在运行时校验接口返回的结构是否符合预期，避免后端字段变更未同步导致的线上问题
• 不要滥用any类型，哪怕是临时过渡也优先用unknown配合类型守卫收窄类型，最大程度保留TS的类型校验能力

官方文档中对对象类型的说明参考：
除基础类型外，你最常遇到的类型就是对象类型，它指代所有带属性的JavaScript值，几乎涵盖了绝大多数数据类型。要定义对象类型，只需列出其所有属性及对应类型即可。以下是接收类点对象的函数示例：

// The parameter's type annotation is an object type
function printCoord(pt: { x: number; y: number }) {
  console.log("The coordinate's x value is " + pt.x);
  console.log("The coordinate's y value is " + pt.y);
}
printCoord({ x: 3, y: 7 });

内容的提问来源于stack exchange，提问作者Henrique Milli