API设计中引用数据类型处理需以资源建模为核心，明确语义、控制边界、保障可预测性；应定义领域资源（如User、Order）而非通用包装层，字段用业务术语，显式约定可变性，协同演进类型定义，并避免隐式引用副作用。
API 设计中对“引用数据类型”（如对象、数组、嵌套结构等）的处理，核心在于明确语义、控制边界、保障可预测性。它不是单纯的技术选型问题，而是资源建模与交互契约的体现。
资源优先，而非传输结构优先
引用类型常被误用为“接口输出容器”，比如命名为 shuchu（输出）、result、dataWrapper 等——这类命名掩盖了真实业务资源。正确做法是先定义领域资源（如 User、Order、InvoiceLineItem），再让引用类型直接映射该资源的属性结构。
- 避免通用包装层（如
{ code: 0, msg: "", data: { ... } }）无条件套用，除非全平台统一且有明确解耦收益 - 每个 API 响应体应尽可能贴近单一资源实体，嵌套仅用于表达自然归属关系（如
Order包含items: OrderItem[]） - 字段名使用业务术语（
shippingAddress），而非技术描述（addrObj或outputJson）
引用类型的可变性需显式约定
JavaScript/TypeScript 中的对象和数组默认可变，但 API 的契约应明确其是否允许客户端修改、是否支持部分更新、是否要求深拷贝等。
- 响应中的引用类型默认视为只读视图；若需客户端修改并回传，应在文档中标明“可变字段”及约束（如
items[].quantity可改，items[].id不可改） - 请求体中使用 Partial 或 Patch 类型时，必须限定可变字段范围，禁止开放整个嵌套对象任意赋值
- 对深层嵌套结构（如
user.profile.preferences.theme），建议拆分为扁平化路径或提供专用更新端点，降低误操作风险
类型定义与演进必须协同演进
引用类型一旦发布，其结构变更直接影响所有调用方。关键原则不是“能不能改”，而是“怎么改才安全”。
- 新增字段必须为 optional（如 TypeScript 中用
?修饰），不可强制要求旧客户端提供 - 删除字段或重命名字段属于破坏性变更，需通过新版本路径（如
/v2/users）隔离 - 嵌套对象的字段类型不可降级（如从
string | null收紧为string），否则会破坏现有客户端解析逻辑 - 推荐使用 OpenAPI Schema 或 TypeScript 接口生成客户端类型，让引用结构的契约在编译期/工具链中生效
避免隐式引用传递带来的副作用
当 API 接收或返回复杂引用类型时，开发者容易无意中复用、缓存或修改原始对象，导致状态污染。
- 服务端不应将数据库实体直接序列化返回；应做 clean mapping，剥离内部字段（如
_id、__v、敏感字段） - 前端 SDK 在接收响应后，建议默认执行浅克隆（
{...response}）或使用 immutable 工具（如 Immer）隔离副作用 - 禁止在参数中接受裸对象并直接写入存储层；应先校验结构完整性，再构造领域对象
