3. 接口调用基础：RESTful API 与 HTTP 方法

在工期索赔影响评估中，变更申请与谈判记录的提交、查询、修改与删除，均通过 RESTful API 完成。本节将系统讲解 RESTful 架构的核心概念、HTTP 方法、请求/响应结构及状态码含义，为后续接口调用实战奠定基础。

3.1 RESTful API 简介

REST（Representational State Transfer，表述性状态转移）是一种软件架构风格，而非协议。RESTful API 遵循以下六大约束：

• 客户端-服务器分离：前端与后端独立演进。
• 无状态：每次请求包含全部必要信息，服务器不保存客户端上下文。
• 可缓存：响应可被客户端或中间代理缓存，提升性能。
• 统一接口：资源通过 URI 标识，操作通过标准 HTTP 方法表达。
• 分层系统：客户端无法直接感知是否与最终服务器通信。
• 按需代码（可选）：服务器可向客户端传输可执行代码。

3.2 HTTP 方法（GET / POST / PUT / DELETE）

RESTful API 通过 HTTP 方法表达对资源的操作。在工期索赔系统中，四种核心方法的用途如下：

3.3 请求与响应结构

一个完整的 HTTP 请求包含请求行、请求头、空行和请求体（可选）。响应包含状态行、响应头、空行和响应体。

3.3.1 请求结构示例

POST /api/v1/change-orders HTTP/1.1
Host: api.construction-claims.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Idempotency-Key: 7a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d

{
  "projectId": "PRJ-2024-001",
  "changeOrderType": "TIME_EXTENSION",
  "description": "因不可抗力导致基础施工延误14天",
  "requestedDays": 14,
  "attachments": ["doc-001.pdf", "doc-002.pdf"]
}

3.3.2 响应结构示例

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/change-orders/CO-2024-0089
X-Request-Id: req-abc123

{
  "id": "CO-2024-0089",
  "status": "PENDING_REVIEW",
  "createdAt": "2024-11-20T14:30:00Z",
  "estimatedImpact": {
    "delayDays": 14,
    "criticalPathAffected": true
  }
}

3.4 HTTP 状态码含义

状态码由三位数字组成，首位数字表示类别。工期索赔接口调用中常见的状态码如下：

3.5 接口调用最佳实践

• 统一错误响应格式：所有错误响应应包含 code、message、details 字段，便于客户端统一处理。
• 分页与过滤：GET 列表接口支持 ?page=1&size=20&status=PENDING 参数，避免一次性返回大量数据。
• 版本控制：在 URI 中嵌入版本号（如 /api/v1/），保证向后兼容。
• 超时与重试：客户端设置合理超时时间（建议 30s），对 5xx 错误采用指数退避重试策略。
• 日志与追踪：每个请求携带 X-Request-Id，便于全链路追踪和问题排查。