126 lines
4.0 KiB
Markdown
126 lines
4.0 KiB
Markdown
# 路由注册
|
|
|
|
路由注册是将模块的 Handler 挂载到应用的过程。所有模块的路由在 `src/api/v1/router.py` 中统一注册。
|
|
|
|
## 文件位置
|
|
|
|
```
|
|
src/api/v1/router.py
|
|
src/api/v1/{module}.py # 每个模块的路由定义
|
|
```
|
|
|
|
## 注册步骤
|
|
|
|
### 第一步：定义模块路由
|
|
|
|
在 `src/api/v1/position.py` 中定义 routes 列表：
|
|
|
|
```python
|
|
# +======================================================================
|
|
# | 模块: 岗位路由层
|
|
# | 说明: 提供岗位管理的增删改查、批量删除、状态管理等 API 接口
|
|
# +======================================================================
|
|
"""岗位相关路由。"""
|
|
|
|
from modules.position.handlers import (
|
|
PositionAddHandler, PositionBatchDeleteHandler, PositionDeleteHandler,
|
|
PositionDetailHandler, PositionGetListHandler, PositionPageHandler,
|
|
PositionStatusHandler, PositionUpdateHandler,
|
|
)
|
|
|
|
routes = [
|
|
# 查询岗位分页数据
|
|
(r"/position/page", PositionPageHandler),
|
|
# 查询岗位详情
|
|
(r"/position/detail/(\d+)", PositionDetailHandler),
|
|
# 获取岗位下拉列表
|
|
(r"/position/getPositionList", PositionGetListHandler),
|
|
# 添加岗位
|
|
(r"/position/add", PositionAddHandler),
|
|
# 更新岗位
|
|
(r"/position/update", PositionUpdateHandler),
|
|
# 删除岗位
|
|
(r"/position/delete/(\d+)", PositionDeleteHandler),
|
|
# 设置岗位状态
|
|
(r"/position/status", PositionStatusHandler),
|
|
# 批量删除岗位
|
|
(r"/position/batchDelete", PositionBatchDeleteHandler),
|
|
]
|
|
```
|
|
|
|
### 第二步：在 router.py 中注册
|
|
|
|
在 `src/api/v1/router.py` 的 `_RESOURCE_MODULES` 列表中追加模块：
|
|
|
|
```python
|
|
# src/api/v1/router.py
|
|
from api.v1 import (auth, index, upload, user,
|
|
user_role, role, role_menu, menu,
|
|
dept, dict, dict_item, config,
|
|
config_item, level, position, city,
|
|
notice, link, category, article,
|
|
param, file_template, job, generator,
|
|
operation_log, login_log, job_log, example)
|
|
|
|
from api.v1 import position # 新增
|
|
|
|
_RESOURCE_MODULES = [
|
|
auth, index, upload, user,
|
|
# ... 已有模块 ...
|
|
position, # 新增
|
|
]
|
|
```
|
|
|
|
:::tip 注册规则
|
|
新模块只需两步：
|
|
1. 在 `src/api/v1/` 下创建路由文件，定义 `routes` 列表
|
|
2. 在 `router.py` 的 `_RESOURCE_MODULES` 中追加模块导入
|
|
|
|
路由前缀 `/api/v1` 由 `build_routes()` 自动拼接，无需手动添加。
|
|
:::
|
|
|
|
## 最终 API 路径
|
|
|
|
注册后，Position 模块的接口路径为：
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|:----|:----|:----|
|
|
| GET | `/api/v1/position/page` | 分页查询 |
|
|
| GET | `/api/v1/position/detail/(\d+)` | 详情查询 |
|
|
| GET | `/api/v1/position/getPositionList` | 下拉列表 |
|
|
| POST | `/api/v1/position/add` | 新增 |
|
|
| PUT | `/api/v1/position/update` | 更新 |
|
|
| DELETE | `/api/v1/position/delete/(\d+)` | 单条删除 |
|
|
| POST | `/api/v1/position/batchDelete` | 批量删除 |
|
|
| PUT | `/api/v1/position/status` | 状态变更 |
|
|
|
|
## URL 命名规范
|
|
|
|
| 规则 | 示例 |
|
|
|:----|:----|
|
|
| 使用小写英文 | `/position` 而非 `/Position` |
|
|
| 使用单数形式 | `/position` 而非 `/positions` |
|
|
| 多单词用驼峰 | `/fileTemplate` 或 `/file-template` |
|
|
| 路径参数用正则 | `(\d+)` 匹配数字 ID |
|
|
|
|
## build_routes 工作原理
|
|
|
|
```python
|
|
# src/api/v1/router.py
|
|
V1_PREFIX = "/api/v1"
|
|
|
|
def build_routes() -> list:
|
|
"""构建全部路由（含 /api/v1 前缀与健康检查）。"""
|
|
routes = []
|
|
for module in _RESOURCE_MODULES:
|
|
routes.extend([(V1_PREFIX + path, handler) for path, handler in module.routes])
|
|
routes.append((V1_PREFIX + "/health", HealthHandler))
|
|
return routes
|
|
```
|
|
|
|
`build_routes()` 遍历所有模块的 `routes` 列表，为每条路由拼接 `/api/v1` 前缀，最后追加健康检查端点。
|
|
|
|
## 总结
|
|
|
|
路由注册采用声明式模式：每个模块在 `src/api/v1/{module}.py` 中定义 `routes` 列表，在 `router.py` 的 `_RESOURCE_MODULES` 中追加导入即可。路由前缀 `/api/v1` 自动拼接，无需手动配置。
|