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