2. RESTful API 基础回顾：HTTP 协议核心方法、状态码与 REST 设计原则
在承运商集成场景中，每一次运单查询、轨迹推送、面单获取，本质上都是对 RESTful API 的一次调用。本章将系统回顾 HTTP 协议的核心方法、状态码语义以及 REST 架构的设计原则，为后续的接口调试与数据传输优化打下坚实基础。
2.1 HTTP 核心方法：CRUD 操作的网络映射
RESTful API 将业务资源的增、删、改、查操作映射为 HTTP 方法。在承运商集成中，最常用的四个方法如下：
| HTTP 方法 | 对应操作 | 请求体 | 响应体 | 承运商集成典型场景 |
|---|---|---|---|---|
| GET | 查询 / 读取 | 无（或查询参数） | 资源列表 / 详情 | 查询运单状态、获取电子面单图片 |
| POST | 创建 / 提交 | 资源数据（JSON） | 新资源标识 / 处理结果 | 创建运单、推送轨迹回调 |
| PUT | 全量更新 / 替换 | 完整资源数据 | 更新后的资源 | 修改运单收件地址（全量覆盖） |
| DELETE | 删除 | 无 | 删除确认 / 204 No Content | 取消运单、删除订阅回调 |
实践要点： 承运商 API 中，
POST 和 GET 的使用频率远高于 PUT 和 DELETE。部分承运商出于安全考虑，会将 DELETE 方法替换为 POST 请求并在请求体中指定操作类型（如 {"action": "cancel"}），调试时需注意接口文档的约定。
2.2 HTTP 状态码：API 响应的通用语言
状态码是服务器对请求处理结果的标准化反馈。掌握常见状态码的语义，能帮助你在调试时快速定位问题。以下是承运商集成中最常遇到的状态码分类：
- 2xx 成功
200 OK：请求成功，响应体包含资源数据（如运单详情）。201 Created：资源创建成功（如成功创建运单），响应头中通常包含Location字段指向新资源 URI。204 No Content：请求成功，但响应体为空（如成功删除运单）。
- 4xx 客户端错误
400 Bad Request：请求格式错误或参数校验失败（如缺少必填字段）。401 Unauthorized：缺少认证信息或认证失败（如 无效）。403 Forbidden：已认证但无权限访问该资源（如账号未开通该服务）。404 Not Found：请求的资源不存在（如运单号错误）。429 Too Many Requests：请求频率超过限流阈值，需等待后重试。
- 5xx 服务端错误
500 Internal Server Error：服务器内部错误，需联系承运商技术支持。502 Bad Gateway/503 Service Unavailable：服务暂时不可用，通常为临时故障。
调试陷阱： 部分承运商 API 在业务逻辑错误（如运单已签收无法取消）时，仍返回
200 OK，但在响应体中包含 {"code": "ERROR", "message": "..."} 等业务状态码。调试时不能仅依赖 HTTP 状态码，必须同时解析响应体的业务状态字段。
2.3 REST 设计原则：无状态与资源导向
REST（Representational State Transfer）是一种架构风格，其核心原则直接影响了承运商 API 的设计方式。以下两个原则与集成调试最为相关：
2.3.1 无状态性（Stateless）
服务器不保存客户端的状态信息。每次请求都必须包含服务器处理该请求所需的全部信息（如认证令牌、上下文参数）。这意味着：
- 你不能假设服务器“记得”你之前查询过的运单列表。
- 分页查询时，每次请求都必须携带
page和size参数。 - 认证信息（如
Authorization头）必须在每次请求中重复发送。
2.3.2 资源导向（Resource-Oriented）
一切皆资源，每个资源通过唯一的 URI 标识。操作通过 HTTP 方法表达，而非在 URI 中嵌入动词。对比以下两种设计：
| 非 RESTful 设计（不推荐） | RESTful 设计（推荐） |
|---|---|
POST /api/getOrder |
GET /api/orders/{orderId} |
POST /api/createOrder |
POST /api/orders |
POST /api/deleteOrder |
DELETE /api/orders/{orderId} |
资源导向的 URI 设计使 API 更直观、更易维护，也便于工具自动发现和文档生成。
2.4 幂等性：重试安全的关键保障
在数据传输优化中，幂等性是一个不可忽视的概念。幂等操作意味着无论执行一次还是多次，对资源产生的最终效果相同。
- GET / DELETE / PUT 天然具有幂等性：多次查询同一运单返回相同数据；多次删除同一运单，第一次成功后后续返回 404 但资源状态不变；多次全量更新同一运单，最终结果一致。
- POST 通常不幂等：多次创建同一运单会导致生成多个重复运单。因此，承运商 API 通常要求客户端在创建请求中提供 幂等键（Idempotency Key），如
Idempotency-Key: order_20250321_001，服务器根据该键判断是否已处理过该请求。
集成建议： 在实现重试机制时，对于
POST 请求务必携带幂等键，避免因网络超时导致重复创建运单。对于 PUT 和 DELETE，可直接重试，无需额外处理。
2.5 内容协商：请求与响应的数据格式
RESTful API 通过 HTTP 头实现内容协商，客户端和服务器就数据格式达成一致：
| HTTP 头 | 用途 | 承运商集成示例 |
|---|---|---|
Content-Type |
告知服务器请求体的格式 | Content-Type: application/json; charset=utf-8 |
Accept |
告知服务器期望的响应格式 | Accept: application/json |
绝大多数承运商 API 使用 application/json 作为数据交换格式。部分老旧的承运商系统可能仍使用 application/xml，此时需在 Accept 头中明确指定。