23 lines
1.0 KiB
Markdown
23 lines
1.0 KiB
Markdown
|
---
|
|||
|
|
name: k12-restful-api-style
|
|||
|
|
description: 当任务涉及接口命名、路径规划或网关转发时使用，统一 K12Study 的 RESTful 风格并强制旧接口不兼容
|
|||
|
|
---
|
|||
|
|
# K12 RESTful 接口风格技能
|
|||
|
|
## 何时使用
|
|||
|
|
- 新增 API 设计
|
|||
|
|
- 旧接口路径改造（如 `current-user`、`* /tree`）
|
|||
|
|
- 需要同步网关白名单与客户端调用路径
|
|||
|
|
## 设计规则
|
|||
|
|
- 路径优先使用资源名（名词）而不是动作名。
|
|||
|
|
- 集合资源使用复数：`/users`、`/departments`。
|
|||
|
|
- “当前用户”使用语义路径：`/users/current`。
|
|||
|
|
- 树形结构优先通过资源路径表达：`/areas`、`/tenants`、`/departments`。
|
|||
|
|
## 执行步骤
|
|||
|
|
1. 在控制器中提供 RESTful 主路径。
|
|||
|
|
2. 删除旧路径映射，不保留兼容别名。
|
|||
|
|
3. 同步更新前端、小程序 API 调用路径。
|
|||
|
|
4. 同步更新鉴权白名单与文档（`docs/architecture/api-design.md`、`docs/architecture/logical-view.md`）。
|
|||
|
|
## 约束
|
|||
|
|
- 保持网关 `/api/*` 统一入口不变。
|
|||
|
|
- 旧接口不兼容，禁止新增或恢复旧路径别名。
|