签入版本
This commit is contained in:
@@ -0,0 +1,217 @@
|
||||
# 路由注册（Flask Blueprint）
|
||||
|
||||
Flask 使用 `Blueprint` 机制实现模块化路由注册。每个业务模块定义自己的 Blueprint，然后在路由注册中心统一挂载到应用。
|
||||
|
||||
## Blueprint 概念
|
||||
|
||||
`Blueprint` 是 Flask 提供的模块化路由组织方式。它允许将路由、视图函数、模板等组织在一个模块中，然后在应用中注册使用。
|
||||
|
||||
## 模块 Blueprint 定义
|
||||
|
||||
每个业务模块在 `router.py` 文件中定义自己的 Blueprint：
|
||||
|
||||
```python
|
||||
# src/modules/system/position/router.py
|
||||
|
||||
from flask import Blueprint, request
|
||||
from src.core.permission import check_permission
|
||||
from src.core.response import R
|
||||
from src.common.utils.request import parse_request_body, parse_id_list
|
||||
|
||||
# 定义 Blueprint
|
||||
# 参数说明：
|
||||
# - 'position': Blueprint 名称，用于内部标识
|
||||
# - __name__: 模块名称，用于确定静态文件等资源路径
|
||||
# - url_prefix='/position': 路由前缀，所有路由都会添加此前缀
|
||||
position_blue = Blueprint('position', __name__, url_prefix='/position')
|
||||
|
||||
|
||||
@position_blue.route('/page', methods=['GET'])
|
||||
@check_permission('sys:position:page')
|
||||
def page():
|
||||
"""分页查询岗位列表"""
|
||||
from src.modules.system.position.service import get_position_page
|
||||
return get_position_page()
|
||||
|
||||
|
||||
@position_blue.route('/detail/<int:id>', methods=['GET'])
|
||||
@check_permission('sys:position:detail')
|
||||
def detail(id):
|
||||
"""查询岗位详情"""
|
||||
from src.modules.system.position.service import get_position_detail
|
||||
return get_position_detail(id)
|
||||
|
||||
|
||||
@position_blue.route('/add', methods=['POST'])
|
||||
@check_permission('sys:position:add')
|
||||
def add():
|
||||
"""新增岗位"""
|
||||
from src.modules.system.position.service import add_position
|
||||
from src.modules.system.position.schema import PositionForm
|
||||
data = parse_request_body(request, PositionForm)
|
||||
return add_position(data)
|
||||
|
||||
|
||||
@position_blue.route('/update', methods=['PUT'])
|
||||
@check_permission('sys:position:update')
|
||||
def update():
|
||||
"""更新岗位"""
|
||||
from src.modules.system.position.service import update_position
|
||||
from src.modules.system.position.schema import PositionForm
|
||||
data = parse_request_body(request, PositionForm)
|
||||
return update_position(data)
|
||||
|
||||
|
||||
@position_blue.route('/delete/<int:id>', methods=['DELETE'])
|
||||
@check_permission('sys:position:delete')
|
||||
def delete(id):
|
||||
"""删除岗位"""
|
||||
from src.modules.system.position.service import delete_position
|
||||
return delete_position(id)
|
||||
|
||||
|
||||
@position_blue.route('/status', methods=['PUT'])
|
||||
@check_permission('sys:position:status')
|
||||
def status():
|
||||
"""更新岗位状态"""
|
||||
from src.modules.system.position.service import update_position_status
|
||||
from src.modules.system.position.schema import PositionStatusForm
|
||||
data = parse_request_body(request, PositionStatusForm)
|
||||
return update_position_status(data)
|
||||
```
|
||||
|
||||
## 路由注册中心
|
||||
|
||||
所有模块的 Blueprint 在 `src/routes/v1.py` 中统一注册：
|
||||
|
||||
```python
|
||||
# src/routes/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
|
||||
from src.modules.system.role.router import role_blue
|
||||
from src.modules.system.menu.router import menu_blue
|
||||
from src.modules.system.user.router import user_blue
|
||||
# ... 其他模块导入
|
||||
|
||||
# 全部业务蓝图（按领域分组排序）
|
||||
BLUEPRINTS = [
|
||||
# 系统管理模块
|
||||
user_blue, role_blue, menu_blue, dept_blue, position_blue, level_blue,
|
||||
# 内容管理模块
|
||||
# article_blue, category_blue, ...
|
||||
# 监控管理模块
|
||||
# job_blue, job_log_blue, ...
|
||||
# ... 其他模块
|
||||
]
|
||||
|
||||
|
||||
def register_v1(app):
|
||||
"""
|
||||
注册 API v1 路由（所有业务蓝图挂载到 /api/v1）。
|
||||
|
||||
Args:
|
||||
app: Flask 应用实例
|
||||
"""
|
||||
# 创建 v1 父 Blueprint
|
||||
v1 = Blueprint('v1', __name__, url_prefix='/api/v1')
|
||||
|
||||
# 注册所有子 Blueprint
|
||||
for blue in BLUEPRINTS:
|
||||
v1.register_blueprint(blue)
|
||||
|
||||
# 将 v1 注册到应用
|
||||
app.register_blueprint(v1)
|
||||
|
||||
return app
|
||||
```
|
||||
|
||||
## 路由注册流程
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Flask 应用 (app) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ v1 Blueprint (prefix: /api/v1) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────┼─────────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
||||
│ position_blue │ │ level_blue │ │ dept_blue │
|
||||
│ /position │ │ /level │ │ /dept │
|
||||
└───────────────┘ └───────────────┘ └───────────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
/api/v1/position/* /api/v1/level/* /api/v1/dept/*
|
||||
```
|
||||
|
||||
## Blueprint 参数说明
|
||||
|
||||
```python
|
||||
position_blue = Blueprint(
|
||||
'position', # Blueprint 名称
|
||||
__name__, # 模块名称
|
||||
url_prefix='/position', # 路由前缀
|
||||
# template_folder='templates', # 模板文件夹（可选）
|
||||
# static_folder='static', # 静态文件夹（可选）
|
||||
)
|
||||
```
|
||||
|
||||
| 参数 | 说明 |
|
||||
|:----|:----|
|
||||
| `name` | Blueprint 名称，用于内部标识，必须唯一 |
|
||||
| `import_name` | 模块名称，通常使用 `__name__` |
|
||||
| `url_prefix` | 路由前缀，所有路由都会添加此前缀 |
|
||||
| `template_folder` | 模板文件夹路径（相对于 Blueprint） |
|
||||
| `static_folder` | 静态文件夹路径（相对于 Blueprint） |
|
||||
|
||||
## 路由装饰器
|
||||
|
||||
Flask 使用 `@blueprint.route()` 装饰器定义路由：
|
||||
|
||||
```python
|
||||
@position_blue.route('/page', methods=['GET'])
|
||||
def page():
|
||||
"""分页查询岗位列表"""
|
||||
pass
|
||||
```
|
||||
|
||||
| 参数 | 说明 |
|
||||
|:----|:----|
|
||||
| `rule` | 路由规则，如 `/page`、`/detail/<int:id>` |
|
||||
| `methods` | HTTP 方法列表，如 `['GET']`、`['POST']` |
|
||||
|
||||
### 动态路由参数
|
||||
|
||||
```python
|
||||
@position_blue.route('/detail/<int:id>', methods=['GET'])
|
||||
def detail(id):
|
||||
"""查询岗位详情"""
|
||||
pass
|
||||
```
|
||||
|
||||
| 转换器 | 说明 | 示例 |
|
||||
|:----|:----|:----|
|
||||
| `<int:id>` | 整数参数 | `/detail/123` |
|
||||
| `<string:name>` | 字符串参数（默认） | `/detail/abc` |
|
||||
| `<float:price>` | 浮点数参数 | `/price/12.5` |
|
||||
| `<uuid:id>` | UUID 参数 | `/detail/550e8400-e29b-41d4-a716-446655440000` |
|
||||
|
||||
## 开发要点
|
||||
|
||||
1. **每个模块定义自己的 Blueprint**：在 `router.py` 文件中定义
|
||||
2. **统一在 `v1.py` 中注册**：将所有 Blueprint 添加到 `BLUEPRINTS` 列表
|
||||
3. **使用 `check_permission` 装饰器**：实现 RBAC 权限控制
|
||||
4. **路由前缀与模块目录名保持一致**：便于代码导航
|
||||
5. **使用中文注释**：方便理解路由功能
|
||||
|
||||
## 总结
|
||||
|
||||
Flask Blueprint 是模块化路由组织的核心机制。每个业务模块定义自己的 Blueprint，在 `src/routes/v1.py` 中统一注册到 `v1` 父 Blueprint，最终挂载到 Flask 应用。通过 `url_prefix` 设置路由前缀，使用 `@blueprint.route()` 装饰器定义路由，结合 `check_permission` 实现 RBAC 权限控制。
|
||||
Reference in New Issue
Block a user