4. 同步接口规范定义：请求/响应结构、认证方式与幂等性设计

供应商目录同步接口是采购管理平台与外部供应商系统之间的核心数据通道。本章从请求/响应结构、认证机制和幂等性三个维度定义接口规范，确保同步过程具备标准化、安全性和可恢复性。

4.1 请求/响应结构规范

所有同步接口统一采用 RESTful 风格，请求与响应均使用 JSON 格式。请求体包含同步批次标识、操作类型和业务数据；响应体则返回处理结果、错误详情及重试建议。

字段层级 字段名称 类型 必填 说明
请求头 Content-Type string 是 application/json
Authorization string 是 Bearer {} 或 {key}
X-Request-Id string 是 全局唯一请求标识，用于幂等去重
X-Timestamp string 是 ISO 8601 格式，防重放攻击
请求体 batchId string 是 同步批次号，格式：YYYYMMDDHHmmss-{uuid}
operation string 是 CREATE / UPDATE / DELETE / FULL_SYNC
supplierCode string 是 供应商编码，全局唯一
data object 是 供应商目录业务数据
retryCount int 否 当前重试次数，首次请求不传
响应体 code string 是 SUCCESS / PARTIAL_SUCCESS / FAILURE
message string 是 处理结果描述
requestId string 是 回传请求头中的 X-Request-Id
errors array 否 错误详情列表，包含字段级校验失败
retryAfter int 否 建议重试间隔（秒），仅失败时返回 
// 请求示例：创建供应商目录
POST /api/v1/supplier/catalog/sync
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
X-Request-Id: 20250321143000-a1b2c3d4
X-Timestamp: 2025-03-21T14:30:00Z

{
  "batchId": "20250321143000-a1b2c3d4",
  "operation": "CREATE",
  "supplierCode": "SUP-2025-001",
  "data": {
    "catalogName": "电子元器件目录",
    "category": "被动元件",
    "items": [
      {
        "sku": "RES-100K-0603",
        "name": "贴片电阻 100KΩ 0603",
        "unitPrice": 0.85,
        "currency": "CNY",
        "stock": 50000
      }
    ]
  },
  "retryCount": 0
}

// 响应示例：成功
{
  "code": "SUCCESS",
  "message": "目录同步成功，共处理 1 条物料",
  "requestId": "20250321143000-a1b2c3d4",
  "errors": []
}

// 响应示例：部分失败
{
  "code": "PARTIAL_SUCCESS",
  "message": "部分物料同步失败",
  "requestId": "20250321143000-a1b2c3d4",
  "errors": [
    {
      "sku": "RES-100K-0603",
      "field": "unitPrice",
      "reason": "价格超出预设阈值，需人工审核"
    }
  ],
  "retryAfter": 300
}
设计要点：请求头中的 X-Request-Id 是幂等性的核心标识，服务端必须基于该字段做去重判断。响应中的 retryAfter 字段为客户端提供精确的重试等待时间，避免盲目重试造成服务端压力。

4.2 认证方式： 与 OAuth 2.0

根据供应商系统的安全等级和集成复杂度，平台支持两种认证方式。 适用于轻量级、低风险场景；OAuth 2.0 适用于需要细粒度权限控制的企业级集成。

对比维度 OAuth 2.0（Client Credentials）
适用场景 内部系统、低风险数据同步 跨企业、高安全要求集成
凭证形式 固定字符串，置于请求头 动态 ，需定期刷新
权限粒度 全局权限，无法细分 支持 scope 细粒度控制
凭证轮换 手动更换，有泄露风险 自动刷新，支持吊销
审计追溯 仅记录 Key 标识 可关联客户端 ID 和用户身份
实现复杂度 低，无需额外端点 中，需集成授权服务器
推荐策略：对于供应商目录同步场景，建议采用 OAuth 2.0 Client Credentials 模式。平台作为客户端，使用 client_id 和 client_secret 向授权服务器获取 access_，并在 过期前通过 refresh_ 自动续期。 仅作为临时方案或低风险环境下的备选。 
//  认证示例
GET /api/v1/supplier/catalog/sync
Authorization:  sk_live_3a1b2c3d4e5f67890

// OAuth 2.0 获取  示例
POST /oauth/
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=supplier-portal-001
&client_secret=supersecret123
&scope=catalog:read catalog:write

// 响应
{
  "access_": "eyJhbGciOiJSUzI1NiIs...",
  "_type": "Bearer",
  "expires_in": 3600,
  "scope": "catalog:read catalog:write"
}

// 使用  调用同步接口
POST /api/v1/supplier/catalog/sync
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
X-Request-Id: 20250321143000-a1b2c3d4
安全注意事项： 必须通过平台管理后台生成，支持随时吊销。OAuth 2.0 的 client_secret 不得硬编码在代码中，应使用密钥管理服务（KMS）或环境变量注入。 过期后，客户端应主动刷新，避免使用过期的 发起同步请求。

4.3 幂等性设计

供应商目录同步可能因网络抖动、服务超时等原因导致重复请求。幂等性设计确保同一请求无论被调用多少次，业务结果都保持一致，避免重复创建或重复更新。

4.3.1 幂等性实现机制

  • 请求标识去重：服务端基于 X-Request-Id 维护一个去重表，记录已处理成功的请求 ID。重复请求直接返回上次的处理结果。
  • 业务主键幂等：对于 CREATE 操作，使用 supplierCode + sku 作为业务主键，重复创建时返回已存在的记录，而非报错。
  • 版本号乐观锁：对于 UPDATE 操作，请求体中携带 version 字段，服务端校验版本号是否匹配，避免覆盖并发修改。
  • 状态机约束：DELETE 操作设计为幂等，删除不存在的记录返回成功，而非 404 错误。
// 幂等去重表结构（Redis 示例）
// Key: idempotent:{requestId}
// Value: { "code": "SUCCESS", "response": {...} }
// TTL: 24 小时（超过该时间可重新处理）

// 服务端幂等处理伪代码
function handleSyncRequest(request) {
  const cached = redis.get(`idempotent:${request.requestId}`);
  if (cached) {
    return cached.response;  // 直接返回缓存结果
  }

  // 执行业务逻辑
  const result = processCatalogSync(request);

  // 缓存结果，设置过期时间
  redis.setex(`idempotent:${request.requestId}`, 86400, result);

  return result;
}
幂等性验证清单：
  1. CREATE 操作：同一 supplierCode + sku 重复请求返回已存在记录，不报错。
  2. UPDATE 操作：version 字段必须递增，服务端拒绝版本号小于等于当前版本的请求。
  3. DELETE 操作：删除不存在的记录返回 SUCCESS，不产生错误。
  4. FULL_SYNC 操作：以 batchId 为幂等键，同一批次只执行一次全量覆盖。

4.3.2 幂等性状态转换图

下图展示了同步请求从接收到完成的幂等处理流程，重点体现去重判断和结果缓存机制。

同步请求幂等处理流程 接收同步请求 提取 X-Request-Id 查询去重表：是否存在该 RequestId 返回缓存结果 执行业务逻辑 缓存结果到去重表 返回处理结果 存在 不存在 说明 去重表 TTL 建议设为 24 小时 超过 TTL 的请求可重新处理

4.4 接口规范总结

规范维度 核心要求 实现方式
请求结构 统一 JSON 格式，包含批次标识和操作类型 请求头 + 请求体分离，X-Request-Id 必传
响应结构 明确区分成功、部分成功、失败 code + message + errors + retryAfter
认证方式 或 OAuth 2.0 推荐 OAuth 2.0 Client Credentials
幂等性 同一请求多次调用结果一致 请求 ID 去重 + 业务主键 + 版本号乐观锁
错误重试 服务端返回 retryAfter 建议间隔 客户端按指数退避策略重试
最佳实践：接口规范定义完成后，建议生成 OpenAPI 3.0 规范文档，并配套提供 Postman 集合或 SDK 示例。供应商接入时，优先使用 OAuth 2.0 认证，并强制要求所有写操作接口必须携带 X-Request-Id 以实现幂等性。对于历史遗留系统，可提供 兼容方案，但需在管理后台设置 Key 的有效期和权限范围。
← 上一章 📖 返回目录 下一章 →