设计规范 (Standards)

为了保证 API 的一致性和共读性，我们遵循以下设计规范。

命名约定

• URL 路径: 使用小写字母和中划线 (`kebab-case`)。
  • 正确: `/v1/user-profiles`
  • 错误: `/v1/userProfiles` 或 `/v1/user_profiles`
• 资源名称: 使用复数名词。
  • 正确: `/users`, `/orders`

HTTP 方法

方法	描述	是否幂等
`GET`	获取资源详情或列表	是
`POST`	创建新资源	否
`PUT`	替换/更新现有资源 (全量更新)	是
`PATCH`	部分更新现有资源	否
`DELETE`	删除资源	是

常用状态码

成功响应 (2xx)

• 200 OK: 请求成功。
• 201 Created: 资源创建成功 (常用于 POST)。
• 204 No Content: 请求成功但响应主体为空 (常用于 DELETE)。

客户端错误 (4xx)

• 400 Bad Request: 参数错误或格式错误。
• 401 Unauthorized: 未授权，需要身份验证。
• 403 Forbidden: 权限不足，禁止访问。
• 404 Not Found: 资源不存在。
• 422 Unprocessable Entity: 数据校验失败。

服务端错误 (5xx)

• 500 Internal Server Error: 服务器内部错误。

统一错误格式

当发生错误时，API 将返回以下格式的 JSON：

```json { "message": "错误描述信息", "errors": { "field_name": ["具体的错误详情"] }, "code": "ERROR_CODE" } ```