4. API 端点设计规范：统一资源路径命名、版本控制策略与分页过滤

在承运商集成场景中，API 端点的设计质量直接决定了对接方的开发效率与系统的可维护性。本章围绕三个核心设计维度展开：资源路径的语义化命名、版本控制策略的选择、分页与过滤参数的标准化。遵循这些规范，能够显著降低集成过程中的沟通成本与运行时错误率。

4.1 统一资源路径命名规范

RESTful API 的核心思想是将业务实体抽象为资源，并通过 HTTP 动词对资源进行操作。路径命名应遵循以下原则：

• 使用名词复数形式：如 /carriers、/shipments、/tracking-events，避免使用动词（如 /getCarrier）。
• 层级关系通过斜杠表达：子资源嵌套在父资源路径下，如 /carriers/{carrierId}/services。
• 使用小写字母与连字符：多单词用连字符 - 连接，如 /tracking-events，避免下划线或驼峰。
• 路径参数使用花括号占位：如 /shipments/{shipmentId}/status，清晰标识变量位置。

GET    /v1/carriers                          # 获取承运商列表
GET    /v1/carriers/{carrierId}              # 获取单个承运商详情
POST   /v1/carriers/{carrierId}/services     # 为承运商新增服务
GET    /v1/shipments?status=in_transit       # 过滤在途运单
PUT    /v1/shipments/{shipmentId}/tracking   # 更新运单跟踪信息

4.2 版本控制策略：URL 路径 vs Header

API 版本控制是向后兼容的基础。业界主流有两种策略：URL 路径版本控制与请求头版本控制。下表从多个维度进行对比：

4.3 分页与过滤参数设计

承运商集成中，运单列表、跟踪事件等数据量可能达到百万级。合理的分页与过滤设计是保障 API 响应速度与客户端可用性的关键。

4.3.1 分页参数规范

推荐使用基于偏移量的分页方式，参数命名统一为 page 和 size：

GET /v1/shipments?page=1&size=50
# 返回第 1 页，每页 50 条记录

响应体包含分页元数据：
{
  "data": [...],
  "pagination": {
    "page": 1,
    "size": 50,
    "total_items": 1234,
    "total_pages": 25
  }
}

4.3.2 过滤参数规范

过滤参数应遵循以下设计原则：

• 使用查询字符串传递过滤条件：如 ?status=delivered&carrier_id=123。
• 多值过滤使用逗号分隔：如 ?status=in_transit,delivered，表示“在途或已签收”。
• 范围过滤使用双下划线后缀：如 ?created_at__gte=2024-01-01&created_at__lte=2024-12-31。
• 模糊搜索使用专用参数：如 ?q=运单号前缀，避免与精确过滤混淆。

4.4 端点设计检查清单

在完成 API 端点设计后，建议对照以下清单进行自检：

1. 资源路径：是否全部使用名词复数？层级关系是否合理？路径参数是否清晰？
2. 版本控制：是否选择了适合场景的策略？版本号是否在 URL 或 Header 中明确标识？
3. 分页参数：是否统一使用 page 和 size？响应中是否包含分页元数据？
4. 过滤参数：是否支持精确匹配、多值匹配、范围过滤？参数命名是否一致？
5. 错误处理：参数校验失败时是否返回清晰的错误码与描述？