# API 接口规格正反例

正例只表示最低质量，不是可复制的业务答案。产出时必须替换为当前项目的真实路径、字段、状态和证据。

## 正例

### POST /v1/orders

- 需求：`REQ-014`
- 幂等键：请求头 `Idempotency-Key`，同一用户 24 小时内重复提交返回首次订单
- 请求：`items[].sku_id` 映射 `order_item.sku_id`，`items[].quantity` 映射 `order_item.quantity`
- 成功：HTTP 201，响应 `order_id`、`status=created`、`created_at`
- 错误：库存不足返回 HTTP 409、业务码 `ORDER_STOCK_CONFLICT`，不得写入半成品订单
- 副作用：订单与明细同事务写入；库存预占失败时整体回滚
- 验收：相同幂等键并发两次，只创建一笔订单且响应 `order_id` 相同

好在：契约、数据映射、错误语义、幂等、副作用和可执行验收都明确。

## 反例

### POST /order

- 入参：订单信息
- 返回：成功或失败
- 错误码：按实际情况处理
- 验收：接口可用

问题：路径和版本不稳定，字段不可追踪，没有 HTTP 与业务码映射，也没有可复现的验收条件。

## Tag 分组

### 正例

顶级 `tags:` 声明（每个带 description，枚举子能力）：

- 订单：下单/取消/查询
- 支付：发起/回调/对账
- 商品：上下架/库存

endpoint 按业务域 + 触发方归属：

- `POST /orders` → 订单（下单流程）
- `GET /orders` → 订单（查询，同域可共用）
- `POST /payments` → 支付
- `POST /payments/{provider}/notify` → 支付（`security: []` + 幂等重复返 200）
- `GET /reconciliations` → 对账（只读聚合）

好在：按业务域聚合、顶级声明完整、回调归业务域并显式标记安全与幂等。

### 反例

- tag 按 HTTP 方法分（GET/POST/DELETE）或技术层分（"管理后台"/"CRUD"）
- endpoint 标了 `tags` 但顶级未声明，或顶级 tag 无 description
- 资金回调单独建 "webhook" tag 脱离业务域，且漏标 `security: []`/幂等语义

问题：分组无业务语义，消费方无法按域定位；声明不完整触发 lint 失败；回调脱离业务域掩盖安全与幂等要求。

> **行业惯例（非普适，按适用条件采用）**：存在收付/核销/结算等资金状态机的业务，建议把资金流端点独立成 tag（便于财务侧消费方定位与权限收敛）；查询/对账/预警只读端点较多时，建议聚合为独立只读 tag。单一业务域或无资金流转的项目不强制。

## 接口设计纪律反例

- 接口只返回明细列表让前端算合计——派生值的口径（含不含退款/四舍五入时机）分裂到每个消费端。
- 同一对象既有档案号又有入住号，契约未声明权威锚——消费方各取所爱，跨端对账对不上。

问题：派生值与标识的口径分裂在联调后期才暴露，修正成本远高于契约期声明。

## 迁移到当前项目

替换示例中的资源名、路径、字段、枚举、业务码、消费方和验收数据。每个值必须能在需求、状态机、当前数据源或领域契约、既有接口或用户确认中找到来源；不存在来源就标为待确认，不能照搬示例。