第 1 章：API 接口设计核心原则 —— RESTful 风格、资源命名规范、版本控制策略
支付 SDK 对接是 API 设计质量的“试金石”——接口定义稍有模糊，就会引发联调混乱、签名错误甚至资金损失。本章从三个底层维度出发，建立一套可落地的高质量 API 设计基准，后续所有支付接口定义都将严格遵循这些原则。
1.1 RESTful 风格：以资源为中心的架构约束
REST（Representational State Transfer）不是协议，而是一组架构约束。在支付系统中，约束尤其关注无状态和统一接口：
- 无状态性：每个请求包含鉴权、上下文、幂等键等全部必要信息，服务器不保存客户端会话状态。
- 统一接口：每个资源通过唯一 URI 标识，通过标准 HTTP 方法进行操作，通过媒体类型（如 JSON）自描述。
- 缓存能力：利用 HTTP 原生缓存机制减少重复查询（如订单状态查询）。
黄金法则：资源是名词，不是动词。
/getUsers 是错误的，正确的做法是 GET /users。
标准 HTTP 方法映射
| 方法 | 作用 | 幂等性 | 安全性 | 典型支付场景 |
|---|---|---|---|---|
| GET | 获取资源 | 是 | 是 | 查询订单状态 |
| POST | 创建资源 | 否 | 否 | 创建支付订单 |
| PUT | 全量更新资源 | 是 | 否 | 覆盖退款配置 |
| PATCH | 部分更新资源 | 否 | 否 | 更新订单备注 |
| DELETE | 删除资源 | 是 | 否 | 取消未支付订单 |
1.2 资源命名规范：可读且一致的结构
命名风格直接影响 SDK 对接效率。支付体系核心资源包括 orders、payments、refunds、merchants 等，命名需遵守以下约定：
- 全部小写 + 连字符：
merchant-settings而非merchantSettings或merchant_settings。 - 使用复数名词：
/v1/orders而非/v1/order。 - 层级关系：
/merchants/{merchantId}/orders/{orderId}/items。 - 路径参数 vs 查询参数：路径参数用于标识唯一资源（
/users/{userId}），查询参数用于筛选排序（/orders?status=paid）。
支付 SDK 实践：支付领域对幂等性和一致性要求极高。严格的资源命名配合幂等键（Idempotency-Key）是防止重复支付的基石。
1.3 版本控制策略：管理 API 演进的生命线
版本控制不是可选项，而是契约保障。支付接口涉及资金，变更必须平滑过渡。常见策略如下：
| 策略 | 示例 | 优点 | 缺点 |
|---|---|---|---|
| URI 路径 | /v1/orders | 最直观，路由明确，易于缓存 | URI 不够简洁，版本号不易剥离 |
| 请求头 | Accept: application/vnd.api+json;version=1 | URI 干净整洁 | 调试不方便，浏览器无法直接测试 |
| 查询参数 | /orders?version=1 | 实现简单，兼容旧客户端 | 破坏 URI 作为资源唯一标识的语义 |
版本控制陷阱：永远不要省略 API 版本号。即使内部微服务，也必须通过版本控制隔离破坏性变更。一旦发布，删除或重命名字段都可能导致下游支付链路断裂。
综合对比：好设计 vs 坏设计
以下对比总结了上述原则的实际效果：
- 坏设计（违反 RESTful 与命名规范）：
POST /getUserInfo?id=1
POST /deleteOrder
GET /v2.1/createItem
GET /merchants?id=123&type=getSettings- 好设计（符合核心原则）：
GET /v1/users/{userId}
DELETE /v1/orders/{orderId}
POST /v1/items
GET /v1/merchants/{merchantId}/settings
设计自检清单：① URI 是否仅包含名词？② 是否使用正确的 HTTP 方法？③ 是否包含版本号？④ 路径参数是否用于标识资源？⑤ 响应是否有统一的 error 结构？