3. RESTful API 设计原则：资源命名规范、HTTP方法选择、状态码与错误处理策略
在构建参数化估算与历史项目智能成本估算接口时，RESTful API 设计原则是确保接口可维护性、可扩展性与易用性的基石。本章将围绕资源命名规范、HTTP 方法选择以及状态码与错误处理策略三个核心维度展开，为后续的接口调试与集成提供标准化指导。
3.1 资源命名规范
RESTful API 的核心是资源（Resource），资源命名应遵循以下原则：
- 使用名词复数形式：如
/projects、/estimates、/cost-items，避免使用动词。 - 小写字母与连字符：使用小写字母，单词间用连字符（-）分隔，如
/historical-projects。 - 层级关系通过路径表达：如
/projects/{projectId}/estimates表示某个项目下的估算列表。 - 避免过深嵌套：建议嵌套不超过三级，如
/projects/{projectId}/estimates/{estimateId}/cost-items。 - 查询参数用于过滤与排序：如
/projects?status=completed&sort=createdAt。
命名示例对比
| 不推荐 | 推荐 | 说明 |
|---|---|---|
/getProjectList | /projects | 使用名词复数，避免动词 |
/project/123/estimateList | /projects/123/estimates | 统一复数形式，层级清晰 |
/projects?type=1&page=1 | /projects?type=parametric&page=1 | 查询参数使用可读值 |
3.2 HTTP 方法选择
HTTP 方法对应资源的 CRUD 操作，选择原则如下：
| HTTP 方法 | 操作类型 | 幂等性 | 安全性 | 典型场景 |
|---|---|---|---|---|
| GET | 查询资源 | 是 | 是 | 获取项目列表、获取估算详情 |
| POST | 创建资源 | 否 | 否 | 创建新项目、提交估算请求 |
| PUT | 全量更新资源 | 是 | 否 | 更新项目全部字段 |
| PATCH | 部分更新资源 | 否 | 否 | 更新估算状态、修改成本项 |
| DELETE | 删除资源 | 是 | 否 | 删除历史项目、移除成本项 |
方法选择避坑指南
- 使用 POST 执行非幂等操作（如创建估算任务），避免使用 GET 修改资源状态。
- 对于批量操作，优先考虑 POST 到集合端点，如
POST /estimates/batch。 - 避免使用 GET 请求体传递参数，应使用查询参数或路径变量。
3.3 状态码与错误处理策略
合理的 HTTP 状态码与统一的错误响应结构是接口可调试性的关键。以下是成本估算接口中常用的状态码分类：
| 状态码 | 含义 | 使用场景 |
|---|---|---|
| 200 OK | 请求成功 | GET、PUT、PATCH 操作成功返回数据 |
| 201 Created | 资源创建成功 | POST 创建项目或估算成功 |
| 204 No Content | 操作成功无返回体 | DELETE 删除成功 |
| 400 Bad Request | 请求参数错误 | 缺少必填字段、参数格式错误 |
| 401 Unauthorized | 未认证 | 缺少或无效的认证令牌 |
| 403 Forbidden | 无权限 | 用户无权访问该资源 |
| 404 Not Found | 资源不存在 | 请求的项目或估算 ID 不存在 |
| 409 Conflict | 资源冲突 | 创建重复资源、版本冲突 |
| 422 Unprocessable Entity | 业务逻辑错误 | 估算参数校验失败、成本项超出范围 |
| 500 Internal Server Error | 服务器内部错误 | 未预期的异常 |
错误响应体规范
所有错误响应应返回统一的 JSON 结构，便于客户端解析：
{
"error": {
"code": "PARAMETER_INVALID",
"message": "估算参数 'labor_rate' 不能为负数",
"details": {
"field": "labor_rate",
"value": -50,
"constraint": "min: 0"
},
"traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}关键字段说明：code 为业务错误码，message 为用户可读信息，details 提供调试上下文，traceId 用于链路追踪。
3.4 实践要点总结
- 资源命名：统一使用名词复数、小写连字符、层级不超过三级，查询参数用于过滤与排序。
- 方法选择：GET 用于查询，POST 用于创建，PUT/PATCH 用于更新，DELETE 用于删除；注意幂等性与安全性。
- 状态码：精确使用 2xx 表示成功，4xx 表示客户端错误，5xx 表示服务端错误；避免滥用 200 返回错误。
- 错误处理：统一错误响应结构，包含业务错误码、可读消息、调试细节与 traceId，便于快速定位问题。
接口调试检查清单
- 资源路径是否符合命名规范？
- HTTP 方法是否与操作语义一致？
- 成功响应是否使用了正确的 2xx 状态码？
- 错误响应是否包含统一的
code、message、details和traceId？ - 是否对敏感字段（如密码、令牌）进行了脱敏处理？