3. RESTful API 设计原则：构建符合REST规范的ERP接口

在ERP系统中，RESTful API是前端应用与后端服务之间的核心通信桥梁。设计不良的接口会导致系统耦合度高、维护成本激增、调试困难。本节将围绕资源命名、版本控制、状态码使用三大支柱，讲解如何设计出可读性强、易于调试且符合REST规范的ERP接口。

3.1 资源命名：用名词而非动词

REST的核心思想是将业务实体抽象为“资源”，并通过URL唯一标识。ERP系统中常见的资源包括：订单、客户、物料、财务凭证、库存记录等。

3.2 版本控制：保障接口演进

ERP系统生命周期长，接口版本管理是避免“牵一发而动全身”的关键。推荐使用URL路径版本控制，直观且易于调试。

• 路径版本（推荐）： /api/v1/orders、/api/v2/orders。适合ERP多版本并行场景，调试时一眼可辨。
• 请求头版本： Accept: application/vnd.erp.v1+json。更符合REST纯正语义，但调试工具配置复杂，不推荐用于ERP内部接口。
• 参数版本： /api/orders?version=1。容易造成缓存混乱，且URL语义不清晰，应避免。

3.3 HTTP状态码：精准表达通信结果

状态码是API调试的第一道线索。ERP接口中，错误状态码的滥用是导致“穿透查询”调试困难的主要原因之一。

3.4 RESTful API 设计全景图

下图展示了ERP系统中一个完整的RESTful API请求-响应流程，涵盖资源定位、版本控制、状态码返回以及错误处理机制。

3.5 统一响应结构：让调试更高效

除了状态码，响应体的结构也应统一。推荐ERP接口采用以下标准格式：

// 成功响应
{
  "status": "success",
  "data": {
    "id": 12345,
    "orderNumber": "PO-2024-001",
    "totalAmount": 15000.00,
    "items": [...]
  },
  "timestamp": "2024-03-15T10:30:00Z"
}

// 错误响应
{
  "status": "error",
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "未找到订单编号为 PO-2024-999 的采购订单",
    "details": "请检查订单编号是否正确，或联系采购部门确认"
  },
  "timestamp": "2024-03-15T10:30:05Z"
}

3.6 分页与过滤：应对大数据量查询

ERP系统中，财务报表、订单列表等接口往往返回大量数据。设计良好的分页与过滤机制是保证接口性能的基础。

• 分页参数： 使用 page 和 size，如 /api/v1/vouchers?page=1&size=20。
• 排序： 使用 sort 参数，如 sort=date:desc,amount:asc。
• 过滤： 使用查询参数，如 status=posted、dateFrom=2024-01-01。
• 响应元数据： 返回总记录数、总页数，方便前端渲染分页组件。

// 分页响应示例
{
  "status": "success",
  "data": [...],
  "pagination": {
    "page": 1,
    "size": 20,
    "totalRecords": 156,
    "totalPages": 8
  }
}

3.7 总结：RESTful API 设计检查清单

遵循以上RESTful设计原则，ERP接口将具备良好的可读性、可维护性和可调试性，为后续的“财务报表穿透查询”功能打下坚实的通信基础。