---
name: api-design-rules
description: "后端 RESTful API 设计与规范。适用于所有后端接口层代码编写、控制器定义与 API 文档生成。"
globs: ["src/main/java/**/*.java", "**/controller/*.java", "src/controllers/**/*.ts", "**/controllers/*.ts"]
alwaysApply: false
updated: 2026-05-22
---

# 后端 RESTful API 设计与规范

> [!IMPORTANT]
> 干净、统一、语意化强的 API 接口是前后端高效协作的基础。AI 助手在设计或维护后端接口路由时，必须严格遵守 RESTful 标准命名以及统一的安全容错响应格式。

## 1. 适用场景

当您定义新的 HTTP 接口路由、编写控制器（Controllers/Views）逻辑、处理请求参数校验，或输出对外 API 响应时生效。

## 2. 操作规则

1. **路由命名资源名词化 (Noun Plurals for Slugs)**：
   - 所有的 API 资源路径必须使用名词复数作为 Slug，使用嵌套代表归属关系。
   - **正确格式**：`/api/v1/users`、`/api/v1/users/12345/orders`
   - **禁止出现动词**：严禁在路径中写入类似 `/api/v1/getUser`、`/api/v1/delete_order`。
2. **严格遵守 HTTP 语意动词 (Semantic HTTP Methods)**：
   - **获取**：使用 `GET`（幂等，不应引起服务器资源状态变动）。
   - **新建**：使用 `POST`（非幂等）。
   - **完全更新**：使用 `PUT`（幂等）。
   - **局部更新**：使用 `PATCH`（非幂等）。
   - **删除**：使用 `DELETE`（幂等）。
3. **统一标准化 JSON 错误响应 (Unified Error Payload)**：
   - 当 API 请求发生失败（校验不通过、越权、崩溃）时，必须统一抛出符合团队约定的 JSON 错误载荷，且必须包含业务自定义错误码（`code`）与面向用户的文案（`message`）。
4. **健全的安全分页机制 (Pagination Safety Limits)**：
   - 所有的列表（List）查询接口，必须强行支持分页参数（`limit`/`offset` 或 `page`/`page_size`）。
   - 必须在后端设置单次查询的**最大安全上限（如 `page_size <= 100`）**，绝对禁止为了图省事直接进行无限制的裸 `select_all` 查询，防止内存耗尽崩溃。

## 3. 禁止事项

- 严禁无论成功还是失败，一律使用 `200 OK` 并在 JSON body 中自定义 `{ success: false, status: 500 }` 的反模式设计。必须配合使用标准的 HTTP 状态码（如 `201`、`400`、`401`、`403`、`404`、`500`）。

## 4. 验证方式

- 运行单元测试套件对接口路由与响应状态码进行端到端校验。

## 5. JSON 响应对比示例

### ❌ 错误示例（200 状态码包打天下反模式，混乱的错误结构）

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": false,
  "status_code": 40003,
  "msg": "error: database parameter constraint mismatch at col (user_id)"
}
```

###  正确方向（标准 HTTP 错误状态、统一 JSON 容错载荷）

```http
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": "INVALID_INPUT_PARAMETER",
  "message": "请求输入参数格式有误，请核对后重试。",
  "details": [
    {
      "field": "user_id",
      "issue": "user_id 字段格式不符合 UUID-v4 标准"
    }
  ]
}
```