3. 接口映射核心概念

接口映射是API契约治理体系中的核心枢纽，它定义了数据库数据模型与API资源表示之间的转换规则。一个清晰、一致的映射关系，能够确保后端数据变更不会直接破坏前端契约，同时让API消费者以业务语义而非数据库结构来理解资源。

3.1 数据模型与API资源的映射关系

数据模型（通常指PostgreSQL中的表、列、关系）与API资源（JSON/XML表示）之间存在三种基本映射模式：直接映射、聚合映射和投影映射。下表对比了三种模式的核心差异：

映射模式 定义 适用场景 示例
直接映射 API资源字段与数据库列一一对应，无结构转换 简单实体、配置表、字典表 users 表 → /users 资源
聚合映射 API资源由多张表的数据组合而成，包含嵌套对象或数组 订单含明细、用户含地址列表 orders + order_items → /orders
投影映射 API资源只暴露数据库列的子集，或对列进行重命名/计算 敏感字段脱敏、字段别名、计算属性 users.password_hash 不映射
治理要点：在契约文件中，必须显式声明映射模式。直接映射适合内部服务间调用；聚合映射适合面向客户端的BFF（Backend For Frontend）；投影映射常用于权限控制下的数据裁剪。

以下SVG图展示了从PostgreSQL表结构到RESTful API资源表示的完整映射链路：

数据模型与API资源映射关系图 数据模型 → API资源映射链路 PostgreSQL 数据模型 orders 表 id, user_id, total_amount order_items 表 id, order_id, product, qty users 表 id, name, email, password_hash 映射引擎 聚合 + 投影 + 重命名 API 资源表示 GET /orders/{id} id, user_name, total_amount items: [{product, qty}] GET /users/{id} id, name, email password_hash 被投影排除 user_name 来自 users 表聚合

3.2 CRUD操作映射原则

CRUD（Create、Read、Update、Delete）操作映射定义了HTTP方法如何对应到PostgreSQL的DML语句。以下原则是构建可预测、可治理的API契约的基础：

  1. 幂等性原则：GET、PUT、DELETE 必须幂等；POST 不要求幂等。映射到数据库时，UPDATE 和 DELETE 语句应使用主键或唯一约束确保幂等。
  2. 资源完整性原则：一个API资源对应一个聚合根，CRUD操作不应跨多个无关联的聚合根。例如，POST /orders 同时插入 orders 和 order_items 是允许的，但不应同时修改 users 表。
  3. 状态码与数据库结果对齐原则：数据库插入成功 → 201 Created；查询无结果 → 200 OK + 空数组 或 404 Not Found；更新影响0行 → 404 Not Found；删除影响0行 → 204 No Content。
  4. 字段级映射最小化原则：PATCH 操作只映射请求体中出现的字段到数据库列，未出现的字段保持不变。禁止全量覆盖。
最佳实践：在契约中为每个CRUD操作显式声明对应的SQL模板或ORM映射规则。例如：GET /users/{id} → SELECT id, name, email FROM users WHERE id = :id。这能显著降低运行时映射错误。

下表总结了标准CRUD操作与PostgreSQL DML的映射关系：

HTTP方法 API操作 PostgreSQL DML 幂等 典型状态码
POST Create INSERT INTO ... RETURNING * 否 201 Created
GET Read（单个） SELECT ... WHERE pk = :id 是 200 OK / 404 Not Found
GET Read（列表） SELECT ... WHERE ... LIMIT/OFFSET 是 200 OK
PUT Replace（全量替换） UPDATE ... SET col1=:v1, col2=:v2 ... WHERE pk = :id 是 200 OK / 204 No Content
PATCH Partial Update（部分更新） UPDATE ... SET col_x = :v_x WHERE pk = :id 是 200 OK / 204 No Content
DELETE Delete DELETE FROM ... WHERE pk = :id 是 204 No Content / 404 Not Found

以下SVG图展示了CRUD操作从HTTP请求到PostgreSQL执行计划的完整映射流程：

CRUD操作映射流程 CRUD操作映射流程：HTTP → PostgreSQL HTTP 请求 POST /orders API 路由解析 识别资源 + 方法 映射引擎 契约 → SQL 模板 PostgreSQL INSERT INTO orders 映射规则详情 资源路径：/orders 主表：orders 字段映射：user_id → user_id, total_amount → amount 子表：order_items (items[]) SQL模板：INSERT INTO orders (...) VALUES (...) RETURNING id INSERT INTO order_items (...) VALUES (...) 约束：事务包裹，任一失败回滚 返回 201 + 新资源ID

3.3 映射治理检查清单

在API契约评审中，使用以下清单验证映射的正确性：

  • 完整性检查：API资源的所有必填字段是否都有对应的数据库列？数据库中的非空列是否都在API资源中暴露（或通过投影规则显式排除）？
  • 类型一致性检查：JSON数据类型（string、number、boolean、array、object）是否与PostgreSQL数据类型（text、integer、boolean、jsonb、array）兼容？是否存在精度丢失风险？
  • 关系映射检查：外键关系是否映射为资源嵌套或资源引用（如 user_id → user: { id, name } 或 user_id: 123）？
  • 操作边界检查：一个CRUD操作是否只影响一个聚合根？是否存在跨表副作用未在契约中声明？
  • 幂等验证：PUT/DELETE 操作对应的SQL是否确保幂等？例如，UPDATE 是否使用主键作为唯一过滤条件？
常见反模式：将数据库表结构直接暴露为API资源，不做任何映射。这会导致：① 数据库字段名（如 usr_nm）直接出现在API中，破坏语义；② 敏感字段（如 password_hash）意外泄露；③ 表结构变更直接破坏客户端兼容性。正确的做法是始终通过映射层隔离数据库与API。
← 上一章 📖 返回目录 下一章 →