4. 数据模型设计原则：实体与值对象的区分、数据模型的内聚性、模型与API的映射关系
数据模型是API契约的核心载体。在契约治理中，数据模型的设计质量直接决定了接口的可演进性、可理解性和可维护性。本节围绕三个关键维度展开：实体与值对象的区分、数据模型的内聚性以及模型与API的映射关系。
4.1 实体与值对象的区分
在领域驱动设计（DDD）中，实体（Entity）和值对象（Value Object）是两种最基本的数据建模单元。在API契约中，正确区分二者能显著提升接口的语义清晰度和演进灵活性。
| 维度 | 实体（Entity） | 值对象（Value Object） |
|---|---|---|
| 标识 | 拥有唯一标识（ID），标识在生命周期内不变 | 无独立标识，由属性值整体定义 |
| 可变性 | 可变（Mutable），状态可随时间变化 | 不可变（Immutable），替换而非修改 |
| 相等性 | 通过标识判断相等 | 通过所有属性值判断相等 |
| 生命周期 | 有独立生命周期，可被追踪 | 无独立生命周期，随实体存在 |
| API示例 | /users/{userId} 中的 User |
Address、Money、GeoPoint |
| 契约治理影响 | 需提供独立端点，ID不可变 | 可内嵌在实体中，支持向后兼容替换 |
实践建议：在OpenAPI/Swagger契约中，实体通常对应一个带有
id 字段的 schema，并拥有独立的 /resources/{id} 路径；值对象则作为嵌套 schema 出现，不暴露独立端点。
4.1.1 实体建模要点
- 标识不可变：实体的ID一旦分配，在契约版本内不得变更类型或语义。
- 状态可追踪：实体应包含
createdAt、updatedAt等时间戳，支持审计。 - 端点映射：每个实体通常对应一组CRUD端点，路径以实体ID为参数。
4.1.2 值对象建模要点
- 不可变性：值对象的所有字段应为只读（readOnly），更新时整体替换。
- 内聚性：值对象应封装一组逻辑上不可分割的属性，例如
Money(amount, currency)。 - 复用性：值对象可在多个实体间共享，减少重复定义。
反模式警示：将值对象设计为可变对象，或为值对象分配独立ID，会导致契约语义混乱，增加消费者理解成本。
4.2 数据模型的内聚性
数据模型的内聚性衡量的是一个schema内部的属性是否在逻辑上紧密相关。高内聚的模型更容易理解、测试和演进；低内聚的模型则会导致“胖模型”和“脆弱契约”。
4.2.1 内聚性评估维度
| 评估维度 | 高内聚表现 | 低内聚表现 |
|---|---|---|
| 属性相关性 | 所有属性共同描述一个完整概念 | 属性来自多个不相关的业务领域 |
| 变更影响范围 | 属性变更仅影响本schema | 属性变更波及多个无关schema |
| 复用粒度 | schema可独立复用，不携带冗余字段 | schema包含大量可选字段，复用困难 |
| 语义完整性 | schema名称能准确描述其内容 | schema名称模糊，如 Data、Info |
4.2.2 提升内聚性的策略
- 按业务概念拆分：将“用户”与“用户地址”拆分为独立schema，而非将所有字段塞入一个
User对象。 - 使用组合而非继承：通过
allOf或嵌套值对象组合属性，避免深层次继承链。 - 限制可选字段数量：可选字段超过总字段数的30%时，考虑拆分为多个独立schema。
- 统一命名空间：同一业务域内的schema使用统一前缀，如
OrderItem、OrderSummary。
治理红线：禁止在契约中出现超过20个属性的“上帝模型”。超过此阈值必须进行拆分评审。
4.3 模型与API的映射关系
数据模型与API端点之间的映射关系决定了消费者如何感知和使用数据。良好的映射关系能降低耦合，提升接口的直观性。
4.3.1 三种映射模式
| 映射模式 | 描述 | 适用场景 | 示例 |
|---|---|---|---|
| 直接映射 | API端点直接暴露实体schema，CRUD操作一一对应 | 内部服务、管理后台、简单CRUD | GET /users/{id} 返回完整User对象 |
| 投影映射 | API端点返回实体的子集或聚合视图 | 移动端、列表页、性能敏感场景 | GET /users/{id}/profile 只返回姓名和头像 |
| 命令映射 | API端点以操作意图命名，而非资源CRUD | CQRS、事件驱动、复杂业务操作 | POST /orders/{id}/submit 触发状态变更 |
4.3.2 映射关系设计原则
- 消费者视角优先：映射关系应基于消费者需要的数据形态，而非后端数据库表结构。
- 避免过度暴露：内部实体属性不应全部暴露给外部API，使用投影映射隔离内部实现。
- 版本对齐：模型变更与API版本同步，避免模型版本与端点版本脱节。
- 文档化映射规则：在契约注释或外部文档中说明模型与端点的映射逻辑。
案例：某电商平台将
Order 实体映射为三个API视图：OrderSummary（列表用）、OrderDetail（详情用）、OrderCommand（提交用），每个视图只包含消费者需要的字段，内聚性显著提升。
4.4 数据模型设计流程
下图展示了从业务概念到API契约的数据模型设计流程，涵盖实体/值对象识别、内聚性检查、映射关系定义三个核心阶段。
4.5 模型与API映射的常见模式
在实际契约治理中，数据模型与API端点之间存在多种映射模式。下图展示了三种核心模式及其适用场景。
4.6 契约治理中的模型评审清单
在API契约评审中，数据模型是重点审查对象。以下清单可作为评审检查表：
| 检查项 | 通过标准 | 严重等级 |
|---|---|---|
| 实体是否拥有唯一标识 | 每个实体schema包含 id 字段，类型为string/uuid |
必须 |
| 值对象是否声明为不可变 | 值对象schema中所有属性标记为 readOnly: true |
必须 |
| 模型属性数量是否合理 | 单个schema属性不超过20个 | 建议 |
| 可选字段比例是否可控 | 可选字段占比不超过30% | 建议 |
| 模型名称是否语义清晰 | 名称能准确描述业务概念，无模糊命名 | 必须 |
| 映射关系是否文档化 | 契约注释或外部文档说明模型与端点的映射逻辑 | 建议 |
| 是否存在循环引用 | schema之间无循环引用，或使用引用ID打破循环 | 必须 |
工具推荐：使用 Spectral 或 Vacuum 等 lint 工具，将上述评审清单自动化集成到CI/CD流水线中，实现契约治理的持续合规。