3. HTTP协议与RESTful API：HTTP请求方法、状态码详解、RESTful设计原则、幂等性与安全性
3.1 HTTP请求方法详解
HTTP协议定义了多种请求方法，用于指示对资源执行的操作。在承运商集成接口中，正确选择请求方法是保证接口语义清晰、行为可预测的基础。
| 方法 | 语义 | 幂等性 | 安全性 | 承运商集成典型场景 |
|---|---|---|---|---|
| GET | 获取资源 | 是 | 是 | 查询运单状态、获取电子面单 |
| POST | 创建资源 / 提交处理 | 否 | 否 | 创建运单、推送轨迹、发起拦截 |
| PUT | 完整替换资源 | 是 | 否 | 更新运单全部信息、重置配置 |
| PATCH | 部分更新资源 | 否 | 否 | 修改运单备注、更新收件人电话 |
| DELETE | 删除资源 | 是 | 否 | 取消运单、删除订阅回调 |
关键原则：在承运商接口设计中，GET 和 DELETE 必须保证幂等性；POST 用于非幂等创建操作；PUT 用于幂等的全量替换。混淆这些语义会导致接口行为不可预测，增加故障排查难度。
3.2 HTTP状态码详解
状态码是服务器对请求处理结果的标准化反馈。承运商集成接口必须遵循状态码语义，避免滥用 200 返回业务错误。
2xx 成功类
- 200 OK：请求成功，响应体包含结果。用于 GET、PUT、PATCH 成功。
- 201 Created：资源创建成功，响应头应包含 Location 指向新资源 URI。用于 POST 创建运单成功。
- 204 No Content：请求成功，但无返回体。用于 DELETE 成功、异步回调确认。
3xx 重定向类
- 301 Moved Permanently：资源永久迁移，客户端应更新 URI。
- 307 Temporary Redirect：资源临时迁移，客户端应继续使用原 URI 发起后续请求。
4xx 客户端错误类
- 400 Bad Request：请求语法错误或参数校验失败。常见于 JSON 格式错误、必填字段缺失。
- 401 Unauthorized：缺少认证信息或认证失败。
- 403 Forbidden：已认证但无权限执行操作。
- 404 Not Found：请求的资源不存在。
- 405 Method Not Allowed：资源不支持该请求方法。
- 409 Conflict：资源当前状态与请求冲突。例如重复创建运单、运单已签收却发起拦截。
- 422 Unprocessable Entity：请求体语义正确但业务逻辑校验失败。例如收件人地址不在承运商服务范围。
- 429 Too Many Requests：触发限流，客户端应等待后重试。
5xx 服务端错误类
- 500 Internal Server Error：服务器内部错误，需排查服务端日志。
- 502 Bad Gateway：网关或代理收到上游无效响应。
- 503 Service Unavailable：服务暂时不可用（如过载、维护中），客户端应重试。
- 504 Gateway Timeout：网关或代理等待上游响应超时。
常见反模式：部分承运商接口将所有请求（包括参数错误、业务校验失败）统一返回 200 OK，仅在响应体中用业务码区分。这种做法破坏了 HTTP 语义，导致客户端无法通过状态码快速判断错误类型，增加故障排查成本。建议严格遵循状态码语义，业务错误使用 4xx 状态码。
3.3 RESTful 设计原则
REST（Representational State Transfer）是一种架构风格，而非协议。在承运商集成接口中遵循 RESTful 原则，可以提升接口的可理解性、可维护性和可扩展性。
3.4 幂等性与安全性
幂等性和安全性是 RESTful 接口设计中的两个核心概念，直接影响接口的可靠性和重试策略。
3.4.1 安全性
安全性指请求不会改变服务器端资源状态。安全的方法可以被缓存、预取，无需担心副作用。
- 安全方法：GET、HEAD、OPTIONS
- 不安全方法：POST、PUT、PATCH、DELETE
3.4.2 幂等性
幂等性指同一个请求无论执行一次还是多次，对资源产生的副作用相同。幂等性是网络重试机制的基础保障。
- 天然幂等方法：GET（多次查询结果一致）、PUT（全量替换，多次结果相同）、DELETE（第一次删除成功，后续返回 404 或 204）
- 非幂等方法：POST（每次创建新资源）、PATCH（部分更新可能产生累积效果）
幂等性实现策略：对于非幂等的 POST 创建接口，可以通过 幂等键（Idempotency-Key） 机制实现幂等。客户端在请求头中携带唯一幂等键，服务端缓存该键对应的处理结果，重复请求直接返回缓存结果，避免重复创建。
3.4.3 幂等键实现示例
// 客户端请求
POST /api/v1/shipments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{
"orderNo": "ORD20250321001",
"sender": { "name": "张三", "phone": "13800138000" },
"receiver": { "name": "李四", "phone": "13900139000", "address": "北京市朝阳区..." },
"parcel": { "weight": 2.5, "length": 30, "width": 20, "height": 15 }
}
// 首次响应 201 Created
// 重复请求（相同幂等键）响应 200 OK（返回已创建的资源）3.5 承运商接口故障排查清单
基于 HTTP 协议和 RESTful 原则，总结承运商集成接口故障排查的核心检查项：
| 检查项 | 常见问题 | 排查方向 |
|---|---|---|
| 请求方法 | 使用 POST 执行查询操作 | 改为 GET，确保语义正确 |
| 状态码 | 所有响应返回 200，业务错误在 body 中 | 推动承运商遵循 HTTP 状态码语义 |
| URI 设计 | URI 包含动词，版本控制混乱 | 遵循 RESTful 资源导向设计 |
| 幂等性 | 重试导致重复创建运单 | 实现幂等键机制 |
| 认证鉴权 | 401/403 频繁出现 | 检查 有效期、签名算法 |
| 限流 | 429 状态码未处理 | 实现指数退避重试策略 |
| 超时 | 504 Gateway Timeout | 优化接口响应时间，增加超时配置 |