2. 接口基础：RESTful API设计原则在采购验收场景中的应用

在采购到货验收流程中，系统间的数据交互频繁且对实时性要求高。RESTful API 作为当前主流的接口设计规范，其核心原则能够有效指导我们构建清晰、可维护、可扩展的验收接口。本章将结合采购验收的实际业务场景，解析 RESTful 六大核心原则的具体应用。

2.1 RESTful 六大核心原则与验收场景映射

REST（Representational State Transfer）是一种架构风格，而非具体协议。以下表格展示了六大原则在采购验收中的落地方式：

2.2 资源命名与 URI 设计规范

采购验收涉及多个资源实体，URI 设计应遵循名词复数、层级清晰、版本控制的原则。以下为推荐的设计模式：

• 核心资源： 采购订单（purchase-orders）、到货单（receipts）、验收项（inspection-items）、质检报告（quality-reports）。
• 层级关系： 使用路径参数表达从属关系，如 /purchase-orders/{poId}/receipts/{receiptId}/items。
• 过滤与排序： 通过查询参数实现，如 ?status=PENDING&sortBy=createdTime,desc。
• 版本控制： 在 URI 前缀中加入版本号，如 /api/v2/，避免向后兼容问题。

# 推荐 URI 示例
GET    /api/v1/receipts/{receiptId}              # 查询单个到货单详情
POST   /api/v1/receipts                          # 创建到货单（到货登记）
PATCH  /api/v1/receipts/{receiptId}/status       # 更新到货单状态（如：待质检→已质检）
GET    /api/v1/receipts/{receiptId}/items        # 查询到货单下的所有验收项
POST   /api/v1/receipts/{receiptId}/items/{itemId}/inspect  # 提交单个验收项的质检结果

2.3 HTTP 方法与状态码在验收流程中的选择

正确选择 HTTP 方法和状态码是接口可读性的关键。以下为采购验收中常见操作的映射关系：

2.4 验收流程接口调用架构图

以下 SVG 图展示了采购验收流程中，各系统间通过 RESTful API 进行交互的典型架构：

2.5 验收接口的请求与响应规范

统一的请求/响应结构能显著降低对接成本。以下为推荐的 JSON 格式规范：

// 请求体示例：创建到货单
POST /api/v1/receipts
Content-Type: application/json
Authorization: Bearer <>

{
  "poId": "PO202405001",
  "supplierCode": "SUP001",
  "warehouseCode": "WH01",
  "items": [
    {
      "materialCode": "MAT001",
      "plannedQty": 100,
      "actualQty": 98,
      "batchNo": "B20240501"
    }
  ]
}

// 成功响应示例
HTTP/1.1 201 Created
Content-Type: application/json

{
  "code": 0,
  "message": "success",
  "data": {
    "receiptId": "REC202405001",
    "status": "PENDING_INSPECT",
    "createdTime": "2024-05-20T10:30:00Z"
  }
}

// 业务错误响应示例
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "code": 42201,
  "message": "实际到货数量超过采购订单允许的浮动范围",
  "data": null,
  "errors": [
    {
      "field": "items[0].actualQty",
      "message": "实际数量 98 超出允许范围 [90, 100]"
    }
  ]
}

2.6 验收流程中的幂等性设计

在到货验收场景中，网络超时或客户端重试可能导致同一验收请求被多次提交。幂等性设计可防止重复创建或重复更新。以下为两种常见实现方式：

// 幂等键使用示例
POST /api/v1/receipts
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "poId": "PO202405001",
  // ... 其他字段
}

// 服务端处理逻辑（伪代码）
if (cache.exists(idempotencyKey)) {
  return cache.get(idempotencyKey);  // 返回上一次的响应
}
// 执行业务逻辑并缓存结果
result = createReceipt(requestBody);
cache.set(idempotencyKey, result, ttl=3600);
return result;

2.7 验收接口的分页与过滤最佳实践

当查询到货单列表或验收项明细时，数据量可能较大。推荐使用游标分页（Cursor-based Pagination）而非传统偏移分页，以提升性能和数据一致性。

// 游标分页请求示例
GET /api/v1/receipts?status=PENDING_INSPECT&cursor=eyJpZCI6MTAwMH0=&limit=20

// 响应示例
HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "data": {
    "items": [ /* 验收单列表 */ ],
    "nextCursor": "eyJpZCI6MTAyMH0=",
    "hasMore": true
  }
}

// 过滤参数示例（组合使用）
GET /api/v1/receipts?supplierCode=SUP001&warehouseCode=WH01&createdTimeFrom=2024-05-01T00:00:00Z&createdTimeTo=2024-05-20T23:59:59Z