2. 接口基础

在工程合同发票匹配与付款风险控制系统中，API 是前后端及第三方系统交互的桥梁。本章聚焦 RESTful API 的核心设计原则、HTTP 方法语义、状态码规范以及幂等性设计，为后续接口调用实战打下坚实基础。

2.1 RESTful API 六大设计原则

REST（Representational State Transfer）是一种架构风格，而非协议。遵循以下原则可构建出易维护、可扩展的工程财务接口：

2.2 HTTP 方法语义与工程财务场景

每个 HTTP 方法对应一种标准操作。在付款风险控制接口中，正确使用方法可提升接口的可读性和安全性。

2.3 HTTP 状态码：精准表达接口结果

状态码是客户端判断请求结果的直接依据。在付款风险控制中，错误的状态码可能导致资金操作异常，必须严格遵循规范。

2xx 成功类

• 200 OK：GET、PUT、PATCH 请求成功，响应体包含资源数据。
• 201 Created：POST 请求成功创建资源，响应头 Location 指向新资源 URL。
• 204 No Content：DELETE 请求成功，或某些无需返回体的操作（如批量确认）。

3xx 重定向类

• 301 Moved Permanently：资源 URL 已永久变更，客户端应更新缓存。
• 304 Not Modified：条件请求（如 If-None-Match）命中缓存，无需传输资源。

4xx 客户端错误类

• 400 Bad Request：请求参数错误（如发票金额格式不正确）。
• 401 Unauthorized：未提供或提供了无效的身份凭证。
• 403 Forbidden：已认证但无权限（如普通用户尝试审批付款）。
• 404 Not Found：资源不存在（如查询不存在的合同 ID）。
• 409 Conflict：资源当前状态冲突（如发票已被其他付款单锁定）。
• 422 Unprocessable Entity：请求体语义正确但业务校验失败（如合同金额与发票金额不匹配）。
• 429 Too Many Requests：超出 API 调用频率限制。

5xx 服务端错误类

• 500 Internal Server Error：服务器内部异常，需排查日志。
• 502 Bad Gateway：上游服务不可用（如数据库连接池耗尽）。
• 503 Service Unavailable：服务暂时过载或维护中。

2.4 幂等性设计：保障付款安全的关键

幂等性（Idempotency）指同一操作执行多次与执行一次的结果相同。在付款场景中，网络重试可能导致重复扣款，幂等性设计是核心防线。

HTTP 方法的幂等性矩阵

幂等性实现方案

1. 幂等键（Idempotency-Key）：客户端在 POST/PATCH 请求头中传入唯一键（如 UUID），服务端记录已处理的键，重复请求直接返回首次结果。
2. 乐观锁（版本号）：资源携带 version 字段，更新时校验版本号，防止并发覆盖。
3. 业务唯一约束：利用数据库唯一索引（如 contract_id + invoice_id + payment_seq 联合唯一），重复插入直接报错。

2.5 接口设计综合示例：合同发票匹配

以下是一个完整的 RESTful 接口设计示例，涵盖合同与发票的匹配流程：

// 幂等性中间件
const idempotencyStore = new Map(); // 生产环境应使用 Redis

function idempotencyMiddleware(req, res, next) {
  if (['POST', 'PATCH'].includes(req.method)) {
    const key = req.headers['idempotency-key'];
    if (!key) {
      return res.status(400).json({ error: 'Idempotency-Key header is required' });
    }
    if (idempotencyStore.has(key)) {
      // 返回首次缓存的结果
      return res.status(idempotencyStore.get(key).status)
                .json(idempotencyStore.get(key).body);
    }
    // 保存原始 send 方法以缓存响应
    const originalSend = res.send.bind(res);
    res.send = function(body) {
      idempotencyStore.set(key, { status: res.statusCode, body: JSON.parse(body) });
      originalSend(body);
    };
  }
  next();
}

2.6 常见设计反模式与避坑指南

• 反模式 1：在 URL 中使用动词 —— 如 /api/approveContract。应改为 PATCH /api/contracts/123 并传入 {"status":"approved"}。
• 反模式 2：忽略幂等性 —— 付款接口未实现幂等键，网络重试导致重复扣款。必须为 POST/PATCH 添加幂等性支持。
• 反模式 3：状态码使用不当 —— 所有错误都返回 400 或 500。应区分 400（参数错误）、409（冲突）、422（业务校验失败）。
• 反模式 4：GET 请求带请求体 —— 某些客户端在 GET 中携带 JSON body，违反 HTTP 规范。查询参数应放在 URL query string 中。
• 反模式 5：嵌套资源过深 —— 如 /api/contracts/123/invoices/456/items/789。建议扁平化或使用查询参数：/api/items?contractId=123&invoiceId=456。