API 设计与版本管理
一、REST 与资源设计
REST（Representational State Transfer）是一种基于资源的 API 风格：把「业务对象」抽象成资源，用URL 表示资源，用HTTP 方法表示操作。GET 查、POST 创建、PUT/PATCH 更新、DELETE 删除。资源用名词、复数常见，如 /orders、/orders/123；避免动词在 URL 里（/getOrder 不如 GET /orders/123）。
资源设计要点：层级合理（/orders/123/items 表示订单下的行项）、避免过深（超过两三层层级可考虑扁平或查询参数）、用 HTTP 状态码表达结果（200/201/204/400/404/500）、用请求/响应体表达数据格式（通常 JSON）。同一资源可支持多种表述（Content-Type）；若需筛选与分页，用查询参数如 ?status=open&page=2&size=20。
二、API 契约与文档（OpenAPI）
契约：API 的请求/响应格式、路径、方法、状态码的明确约定。前后端或多服务之间按契约开发与联调，减少「口说无凭」的偏差。OpenAPI（原 Swagger）是常用的 REST API 描述规范：用 YAML/JSON 写路径、参数、请求体 schema、响应码与响应体，工具可据此生成文档页、客户端 SDK、Mock 服务或服务端桩。
实践上：契约即代码、或代码即契约二选一或结合（先写 OpenAPI 再生成接口框架 vs 从代码生成 OpenAPI）；在 CI 中校验实现是否满足契约（契约测试）。文档要对人类可读（描述、示例、错误说明），便于对接方快速上手。
paths:
/orders:
get:
summary: List orders
parameters: [{ name: status, in: query }]
responses:
200:
content:
application/json:
schema: { type: array, items: { $ref: '#/components/schemas/Order' } }
三、版本策略：URL、Header、兼容性
API 会演进，版本策略决定「老客户端继续用、新客户端用新能力」如何表达。
URL 版本：如 /v1/orders、/v2/orders。直观、易缓存、易在网关按路径路由；但 URL 会变「脏」，且同一资源多版本并存要维护多套路径。
Header 版本：如 Accept: application/vnd.api+json;version=2 或自定义 X-API-Version: 2。URL 不变，版本在请求头里；但缓存、日志、调试时不如 URL 一目了然，需统一约定默认版本。
兼容性优先：若能通过向后兼容（只加字段不删、不破坏语义）满足大部分需求，可少用「大版本号」，用兼容的演进代替 v2。需要破坏性变更时再开新版本（v2）或新路径，并配合废弃策略。
四、向后兼容与废弃策略
向后兼容：新版本 API 不破坏老客户端的正常使用。常见做法：只加不删——新加可选字段、新加端点，不删已有字段与端点；语义不收紧——已有字段含义不变、枚举不减少已用取值；若必须删或改语义，则开新版本或新路径，并走废弃流程。
废弃策略：计划下线某 API 或某字段时，先标记废弃（deprecated）：在文档与响应头（如 Deprecation: true、Sunset: 2025-06-01）中声明，给调用方迁移期；到期再下线并保留足够时间缓冲。沟通要到位：邮件、文档、日志中提醒，避免突然断掉老客户端。
向后兼容要点
- 只加不删：新加可选字段、新端点，不删已有字段与路径
- 语义不收紧：已有字段含义与枚举取值不破坏
- 必须破坏时：开新版本或新路径，并配合废弃策略
废弃策略要点
- 先标记 deprecated，文档与响应头声明，给出 Sunset 日期
- 留足迁移期，到期再下线；通知到位，避免突然断线
一句话： REST 用资源与 HTTP 方法设计 URL，资源用名词、层级清晰。契约与 OpenAPI 对齐前后端、可生成文档与 Mock。版本可用 URL 或 Header；向后兼容只加不删、语义不收紧，废弃先标记再给迁移期后下线。
X-Request-Id 或类似请求 ID，方便调用方把「某次请求」与日志、工单对应起来，排障会快很多。
五、小结
REST 与资源设计：资源即 URL、操作用 HTTP 方法，层级与状态码要合理。契约与 OpenAPI：描述路径与 schema，可生成文档与代码。版本策略：URL 或 Header，兼容性优先可减少大版本。向后兼容与废弃：只加不删、先废弃再下线、通知到位。下一章讲数据存储与一致性考量，从关系型与 NoSQL 选型到事务、CAP 与最终一致性。