139 lines
3.7 KiB
Markdown
139 lines
3.7 KiB
Markdown
# 路由注册
|
||
|
||
路由注册是将模块的 Blueprint 挂载到应用的过程。所有模块的路由在 `src/routes/v1.py` 中统一注册。
|
||
|
||
## 文件位置
|
||
|
||
```
|
||
src/routes/v1.py
|
||
```
|
||
|
||
## 注册步骤
|
||
|
||
### 第一步：导入 Blueprint
|
||
|
||
在 `v1.py` 文件顶部的导入区域添加：
|
||
|
||
```python
|
||
from src.modules.system.position.router import position_blue
|
||
```
|
||
|
||
### 第二步：挂载 Blueprint
|
||
|
||
在 `BLUEPRINTS` 列表中添加：
|
||
|
||
```python
|
||
BLUEPRINTS = [
|
||
# ... 其他 Blueprint
|
||
position_blue,
|
||
]
|
||
```
|
||
|
||
### 完整上下文
|
||
|
||
```python
|
||
# v1.py 中的路由注册（简化示例）
|
||
|
||
from flask import Blueprint
|
||
|
||
from src.modules.system.position.router import position_blue
|
||
from src.modules.system.level.router import level_blue
|
||
from src.modules.system.dept.router import dept_blue
|
||
# ... 其他模块导入
|
||
|
||
# 全部业务蓝图（按领域分组排序）
|
||
BLUEPRINTS = [
|
||
position_blue,
|
||
level_blue,
|
||
dept_blue,
|
||
# ... 其他模块注册
|
||
]
|
||
|
||
|
||
def register_v1(app):
|
||
"""
|
||
注册 API v1 路由（所有业务蓝图挂载到 /api/v1）。
|
||
|
||
Args:
|
||
app: Flask 应用实例
|
||
"""
|
||
v1 = Blueprint('v1', __name__, url_prefix='/api/v1')
|
||
for blue in BLUEPRINTS:
|
||
v1.register_blueprint(blue)
|
||
app.register_blueprint(v1)
|
||
return app
|
||
```
|
||
|
||
## 最终 API 路径
|
||
|
||
注册后，Position 模块的接口路径为：
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|:----|:----|:----|
|
||
| GET | `/api/v1/position/page` | 分页查询 |
|
||
| GET | `/api/v1/position/detail/<id>` | 详情查询 |
|
||
| GET | `/api/v1/position/list` | 列表查询 |
|
||
| POST | `/api/v1/position/add` | 新增 |
|
||
| PUT | `/api/v1/position/update` | 更新 |
|
||
| DELETE | `/api/v1/position/delete/<id>` | 单条删除 |
|
||
| DELETE | `/api/v1/position/batchDelete` | 批量删除 |
|
||
| PUT | `/api/v1/position/status` | 状态变更 |
|
||
|
||
## prefix 命名规范
|
||
|
||
| 规则 | 示例 |
|
||
|:----|:----|
|
||
| 使用小写英文 | `/position` 而非 `/Position` |
|
||
| 使用单数形式 | `/position` 而非 `/positions` |
|
||
| 多单词用驼峰或短横线 | `/jobLog` 或 `/job-log` |
|
||
| 与模块目录名一致 | `modules/system/position/` → `/position` |
|
||
|
||
## Blueprint 定义示例
|
||
|
||
在模块的 `router.py` 文件中定义 Blueprint：
|
||
|
||
```python
|
||
# src/modules/system/position/router.py
|
||
from flask import Blueprint, request
|
||
|
||
from src.middleware import check_demo, operation_log
|
||
from src.core.permission import check_permission
|
||
from src.modules.system.position import service as position
|
||
from src.common.utils.request import parse_request_body
|
||
from src.core import response as R
|
||
|
||
position_blue = Blueprint('position', __name__, url_prefix='/position')
|
||
|
||
|
||
@position_blue.route('/page', methods=["GET"])
|
||
@check_permission("sys:position:page")
|
||
@operation_log("岗位管理", "查询")
|
||
def page():
|
||
"""查询岗位分页数据"""
|
||
return R.ok(data=position.get_position_page(request.args))
|
||
|
||
|
||
@position_blue.route('/add', methods=["POST"])
|
||
@check_permission("sys:position:add")
|
||
@check_demo
|
||
@operation_log("岗位管理", "新增")
|
||
def add():
|
||
"""添加岗位"""
|
||
json_data, err = parse_request_body()
|
||
if err:
|
||
return R.failed(msg=err)
|
||
position.add_position(json_data)
|
||
return R.ok(msg="添加成功")
|
||
```
|
||
|
||
## 开发要点
|
||
|
||
1. **只需两步**：一行导入，一行添加到 `BLUEPRINTS` 列表
|
||
2. **prefix 与模块目录名保持一致**：便于代码导航
|
||
3. **所有业务蓝图都挂在 `v1` 路由组下**：自动享受 `login_required` 认证保护
|
||
4. **使用 `check_permission` 装饰器**：实现 RBAC 权限控制
|
||
|
||
## 总结
|
||
|
||
路由注册在 `src/routes/v1.py` 中统一管理，`BLUEPRINTS` 列表包含所有业务模块的 Blueprint。所有业务蓝图挂在 `v1` 路由组下，自动享受 `login_required` 认证保护。使用 `check_permission` 装饰器实现 RBAC 权限控制。
|