# API 规范（精简版）

> 适用入口：`backend-main`

## 路径与方法

- 资源名使用名词复数：`/api/v1/users`
- 禁止动词式路径：`/getUsers` / `/createUser`
- 方法语义：GET 查询、POST 创建、PUT/PATCH 更新、DELETE 删除

## 统一响应结构

```json
{
  "success": true,
  "data": {},
  "message": "success",
  "timestamp": "2026-01-15T12:00:00.000Z",
  "path": "/api/v1/..."
}
```

```json
{
  "success": false,
  "error": {
    "code": "PERF_xxx",
    "message": "<i18n.key>",
    "details": {}
  },
  "timestamp": "2026-01-15T12:00:00.000Z",
  "path": "/api/v1/...",
  "method": "GET",
  "statusCode": 400
}
```

## 分页规范

- 请求参数：`page`、`pageSize`
- 响应字段：`items`、`pagination: { page, pageSize, total, totalPages }`

## 封包/解包规范

- 成功响应由 `TransformInterceptor` 统一封包。
- 错误响应由 `AllExceptionsFilter` 统一格式化。
- 前端由 `api-client` 响应拦截器统一解包（直接返回 `data` 字段）。

## API 文档要求（07-api.md）

- 必须包含接口数量汇总、按域接口清单（序号/方法/路径/权限/域内数量）。
- 接口详情采用编号化统一格式 + 简短示例。
- 与 `08-error-codes.md`、`09-test-scenarios.md` 保持一致。

## 状态码

- `200` 查询成功
- `201` 创建成功
- `400` 参数错误
- `401` 未认证
- `403` 无权限
- `404` 资源不存在
- `409` 冲突/重复
- `422` 数据校验失败