---
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/*` 统一入口不变。
- 旧接口不兼容，禁止新增或恢复旧路径别名。