设计规范

API 设计需要在路径、查询参数、请求体和响应体之间保持清晰的命名边界：

部分	命名格式	示例
API 路径中的静态资源片段	kebab-case	security-events
API 路径中的参数变量	snake_case	{event_id}
Query 参数	snake_case	event_type
JSON 请求体字段	snake_case	source_ip
JSON 响应体字段	snake_case	created_at

除 API 路径中的静态资源片段外，其它参数名和字段名必须使用 snake_case。

API 路径

API 路径用于表达资源层级。路径中的静态资源片段必须使用小写字母和 kebab-case，不应该使用下划线、驼峰或大写字母。

资源必须使用复数名词表示集合；如果该词没有合适的复数形式，则应该使用单数形式。

✅ Good

GET /employees
GET /weather
GET /security-events
GET /security-events/{event_id}

❌ Bad

GET /employee         // ❌ 应使用复数名词
GET /security_events  // ❌ 不应使用 snake_case
GET /securityEvents   // ❌ 不应使用 camelCase
GET /SecurityEvents   // ❌ 不应使用 PascalCase

层级关系

路径必须使用正斜杠（/）表示资源层级，且不应该使用尾部正斜杠。

只有当子资源脱离父资源后没有独立意义时，才应该使用嵌套路径。如果资源可以独立访问，或可以从属于多个父资源，则不应该强制嵌套。

✅ Good

GET /files/{file_id}/file-lines/{line_id}
GET /albums/{album_id}
GET /songs/{song_id}

❌ Bad

GET /files/{file_id}/file_lines/{line_id}  // ❌ 静态资源片段 file_lines 应使用 kebab-case
GET /security-events/                      // ❌ 不应使用尾部正斜杠
GET /albums/{album_id}/songs/{song_id}     // ❌ song 域可独立访问时不应强制嵌套

Query 参数

Query 参数用于表达过滤、分页、排序和其它查询条件。参数名必须使用 snake_case，不应该使用 kebab-case 或驼峰命名。

分页、过滤、排序的具体约束分别见分页、过滤、排序。

✅ Good

GET /security-events?event_type=login_failure&offset=0&limit=10
GET /security-events?page_size=10&page_token=CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA
GET /departments?parent_department_id=10&department_type=engineering

❌ Bad

GET /security-events?event-type=login_failure  // ❌ 不应使用 kebab-case
GET /security-events?eventType=login_failure   // ❌ 不应使用 camelCase
GET /employees?DepartmentID=10                 // ❌ 不应使用 PascalCase

请求部分

POST、PUT、PATCH 等包含请求体的方法默认使用 JSON。请求头应该设置 Content-Type: application/json，请求体字段名必须使用 snake_case。

嵌套对象和数组中的字段同样必须使用 snake_case。更多请求约束见请求约束。

✅ Good

POST /security-events
Content-Type: application/json

{
  "event_type": "login_failure",
  "source_ip": "192.0.2.10",
  "occurred_at": "2026-06-02T10:00:00Z"
}

PUT /employees/{employee_id}
Content-Type: application/json

{
  "employee_name": "Zhang San",
  "department_id": "10",
  "mobile_phone": "13800000000"
}

❌ Bad

{
  "event-type": "login_failure",       // ❌ 不应使用 kebab-case
  "sourceIp": "192.0.2.10",            // ❌ 不应使用 camelCase
  "OccurredAt": "2026-06-02T10:00:00Z" // ❌ 不应使用 PascalCase
}

响应部分

响应体字段名必须使用 snake_case。调用成功时，响应数据应该直接返回资源本身，不额外包装通用响应层；调用失败时，响应数据必须包含 error 对象。

更多响应约束见响应约束，错误格式见错误处理。

✅ Good

{
  "event_id": "1001",
  "event_type": "login_failure",
  "source_ip": "192.0.2.10",
  "created_at": "2026-06-02T10:00:00Z"
}

{
  "total": 910,
  "items": [
    {
      "event_id": "1001",
      "event_type": "login_failure"
    }
  ]
}

❌ Bad

{
  "event-id": "1001",                 // ❌ 不应使用 kebab-case
  "eventType": "login_failure",       // ❌ 不应使用 camelCase
  "sourceIP": "192.0.2.10",           // ❌
  "CreatedAt": "2026-06-02T10:00:00Z" // ❌ 不应使用 PascalCase
}