Are you an LLM? You can read better optimized documentation at /v3/backend/contracts/routing.md for this page in Markdown format
后台路由契约
后台路由契约定义管理端资源的访问路径、HTTP 方法、权限边界和操作语义。不同框架的路由注册方式可以不同，但对外暴露的后台接口应保持一致。
本文依据 MineAdmin 当前管理端控制器整理，描述前台模板、权限系统、接口文档和审计日志共同依赖的稳定约定。
基本原则
- 同一资源在不同实现中使用一致的路径语义。
- 列表、详情、创建、更新、删除等常见操作保持稳定的 HTTP 方法和参数位置。
- 需要登录的后台接口必须经过统一认证流程。
- 需要授权的后台接口必须绑定稳定的权限标识。
- 路由元数据应能支撑接口文档、前台能力识别和操作日志。
- 批量操作、导入导出、状态切换等扩展操作应有清晰的资源归属。
URL 命名空间
后台接口统一使用 /admin 作为管理端命名空间，命名空间后的第一段通常表示业务域或资源。
| 类型 | 路径形态 | 示例 |
|---|---|---|
| 认证接口 | /admin/passport/{action} | /admin/passport/login、/admin/passport/refresh |
| 当前用户能力 | /admin/permission/{action} | /admin/permission/menus、/admin/permission/roles |
| 资源管理 | /admin/{resource} | /admin/user、/admin/role、/admin/department |
| 资源列表 | /admin/{resource}/list | /admin/user/list、/admin/attachment/list |
| 资源子能力 | /admin/{resource}/{id}/{relation} | /admin/role/{id}/permissions |
| 插件后台接口 | /admin/plugin/{plugin}/{action} | /admin/plugin/store/index |
框架实现可以使用注解、路由表、控制器前缀或文件路由注册这些地址，但最终公开 URL 不应因为框架差异而变化。
资源操作
| 操作 | HTTP 方法与路径 | 参数位置 | 说明 |
|---|---|---|---|
| 列表 | GET /admin/{resource}/list | 查询参数或请求参数 | 支持分页、筛选、排序和数据权限过滤。 |
| 创建 | POST /admin/{resource} | JSON 请求体 | 请求体承载表单数据。 |
| 更新 | PUT /admin/{resource}/{id} | 路径参数 + JSON 请求体 | 路径参数定位资源，请求体承载可变更字段。 |
| 删除 | DELETE /admin/{resource} | 请求参数或请求体 | 当前多数管理资源通过请求数据传入单个或多个 ID。 |
| 单条删除 | DELETE /admin/{resource}/{id} | 路径参数 | 适用于已经明确用路径参数定位的资源，例如附件。 |
| 关系读取 | GET /admin/{resource}/{id}/{relation} | 路径参数 | 查询用户角色、角色权限等资源关系。 |
| 关系写入 | PUT /admin/{resource}/{id}/{relation} | 路径参数 + JSON 请求体 | 批量授予角色、权限或数据范围。 |
| 资源动作 | POST/PUT /admin/{resource}/{action} | 依动作而定 | 上传、重置密码、状态切换等非标准 CRUD 动作。 |
认证路由
认证路由属于后台契约的一部分，但不按普通资源权限处理。
| 路径 | 方法 | 认证要求 | 说明 |
|---|---|---|---|
/admin/passport/login | POST | 不需要访问令牌 | 使用用户名和密码换取访问令牌与刷新令牌。 |
/admin/passport/logout | POST | 需要访问令牌 | 退出当前登录状态。 |
/admin/passport/getInfo | GET | 需要访问令牌 | 返回当前登录用户的基础信息和后台设置。 |
/admin/passport/refresh | POST | 需要刷新令牌 | 换取新的访问令牌。 |
当前用户能力路由
当前用户能力路由用于前台初始化，不等同于普通资源管理接口。
| 路径 | 方法 | 说明 |
|---|---|---|
/admin/permission/menus | GET | 返回当前用户可访问的菜单树。 |
/admin/permission/roles | GET | 返回当前用户拥有的角色。 |
/admin/permission/update | POST | 修改当前用户资料或密码。 |
这些接口必须保持响应字段稳定，因为前台模板会用它们完成路由生成、菜单渲染和用户信息展示。
参数约定
- 分页参数固定为
page和page_size，默认值分别为1和10。 - 列表筛选字段随资源定义，但应通过请求参数统一传入，并由资源仓储或服务解释。
- 创建和更新接口使用 JSON 请求体，字段以对应表单请求或接口元数据为准。
- 文件上传使用
multipart/form-data，附件上传字段名固定为file。 - 批量删除接口通常使用
ids或资源 ID 数组；如果接口已经声明路径参数，应以路径参数定位单个资源。 - 用户授权角色使用
role_codes数组，角色授权权限使用permissions数组，数组元素分别对应角色代码和菜单权限标识。 - 岗位数据权限使用
policy_type描述策略类型，value描述策略值。
权限标识
权限标识应与后台菜单、按钮和接口元数据保持一致。前台模板根据权限标识控制按钮和页面能力，后端实现根据同一标识执行授权校验。
权限标识推荐使用 业务域:资源:动作 的形式，例如：
| 场景 | 权限标识示例 |
|---|---|
| 用户列表 | permission:user:index |
| 创建用户 | permission:user:save |
| 删除用户 | permission:user:delete |
| 授权用户角色 | permission:user:setRole |
| 角色授权权限 | permission:role:setMenu |
| 附件上传 | dataCenter:attachment:upload |
| 登录日志列表 | log:userLogin:list |
后端授权校验应以该标识为准，前台菜单、按钮权限和接口元数据也应复用同一标识，避免同一能力出现多个命名。
路由元数据
每个后台接口应提供稳定的路由元数据，至少覆盖以下语义：
| 元数据 | 作用 |
|---|---|
operationId | 接口唯一操作名，用于接口文档、客户端生成和变更识别。 |
summary | 接口业务名称，用于接口文档和操作日志。 |
tags | 接口分组，应与后台功能模块或资源归属一致。 |
security | 声明接口需要访问令牌、刷新令牌或无需认证。 |
| 请求体 schema | 描述创建、更新、授权、上传等接口的输入字段。 |
| 响应 schema | 描述列表、详情、当前用户能力等接口的返回结构。 |
如果某个框架没有原生注解能力，也需要在路由注册、OpenAPI 生成或等效配置中保存这些语义。
审计约定
需要记录操作日志的后台接口，应保留可识别的 HTTP 方法、真实路径和业务名称。操作日志至少需要能够追踪：
- 操作用户。
- 请求方法。
- 请求路径。
- 业务名称。
- 客户端 IP。
因此，涉及新增、修改、删除、授权、上传等会改变系统状态的接口，应确保路由元数据中的业务名称明确，不使用空泛描述。
插件路由
插件可以注册自己的后台路由前缀，但仍应遵守管理端路由契约：
- 路径归入
/admin/plugin/{plugin}或插件明确声明的后台命名空间。 - 需要登录的插件接口必须使用统一认证流程。
- 会改变系统状态的插件接口应使用合适的 HTTP 方法，并提供可审计的业务名称。
- 插件接口返回结构应保持与后台统一响应契约一致。
框架实现
Hyperf 当前通过注解、控制器和中间件承载路由与 API 文档生成，具体用法见 Hyperf 路由与 API 文档。