签入版本
This commit is contained in:
@@ -0,0 +1,215 @@
|
||||
# Router层规范
|
||||
|
||||
## 概述
|
||||
|
||||
Router 层是 HTTP 接口层，定义路由和请求处理。每个模块的 Router 文件位于 `src/modules/{group}/{name}/router.py`，使用 Flask `Blueprint` 定义接口。
|
||||
|
||||
:::tip 设计原则
|
||||
- Router 只做请求分发，不含业务逻辑
|
||||
- 通过装饰器控制权限
|
||||
- 委托 Service 处理业务逻辑
|
||||
- 返回 R 封装的响应
|
||||
:::
|
||||
|
||||
## 装饰器顺序
|
||||
|
||||
```python
|
||||
@position_blue.route('/add', methods=['POST']) # 1. 路由定义
|
||||
@check_permission('sys:position:add') # 2. 权限校验
|
||||
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)
|
||||
```
|
||||
|
||||
:::warning 装饰器顺序规则
|
||||
1. `@blueprint.route()`：路由定义（最外层）
|
||||
2. `@check_permission("权限标识")`：RBAC 权限校验
|
||||
|
||||
顺序不可调换，否则权限校验可能失效。
|
||||
:::
|
||||
|
||||
## 读操作
|
||||
|
||||
```python
|
||||
# 分页查询
|
||||
@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 R.ok(data=get_position_detail(id))
|
||||
|
||||
# 列表查询（无分页）
|
||||
@position_blue.route('/list', methods=['GET'])
|
||||
@check_permission('sys:position:list')
|
||||
def get_position_list():
|
||||
from src.modules.system.position.service import get_position_list
|
||||
return R.ok(data=get_position_list())
|
||||
```
|
||||
|
||||
## 写操作
|
||||
|
||||
```python
|
||||
# 添加
|
||||
@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)
|
||||
|
||||
# 批量删除
|
||||
@position_blue.route('/batchDelete', methods=['DELETE'])
|
||||
@check_permission('sys:position:batchDelete')
|
||||
def batch_delete():
|
||||
from src.modules.system.position.service import batch_delete_positions
|
||||
id_list = parse_id_list(request)
|
||||
return batch_delete_positions(id_list)
|
||||
```
|
||||
|
||||
## 权限标识规范
|
||||
|
||||
权限标识格式：`sys:{module}:{action}`
|
||||
|
||||
| 操作 | 权限标识 | HTTP 方法 |
|
||||
|------|---------|----------|
|
||||
| 分页查询 | `sys:{module}:page` | GET |
|
||||
| 详情查询 | `sys:{module}:detail` | GET |
|
||||
| 列表查询 | `sys:{module}:list` | GET |
|
||||
| 添加 | `sys:{module}:add` | POST |
|
||||
| 编辑 | `sys:{module}:update` | PUT |
|
||||
| 删除 | `sys:{module}:delete` | DELETE |
|
||||
| 批量删除 | `sys:{module}:batchDelete` | DELETE |
|
||||
| 状态设置 | `sys:{module}:status` | PUT |
|
||||
|
||||
:::tip admin 用户
|
||||
用户 ID 为 1 的管理员账号跳过所有 `check_permission` 检查。
|
||||
:::
|
||||
|
||||
## 完整 Router 文件模板
|
||||
|
||||
```python
|
||||
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_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 R.ok(data=get_position_detail(id))
|
||||
|
||||
|
||||
@position_blue.route('/list', methods=['GET'])
|
||||
@check_permission('sys:position:list')
|
||||
def get_position_list():
|
||||
from src.modules.system.position.service import get_position_list
|
||||
return R.ok(data=get_position_list())
|
||||
|
||||
|
||||
@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)
|
||||
|
||||
|
||||
@position_blue.route('/batchDelete', methods=['DELETE'])
|
||||
@check_permission('sys:position:batchDelete')
|
||||
def batch_delete():
|
||||
from src.modules.system.position.service import batch_delete_positions
|
||||
id_list = parse_id_list(request)
|
||||
return batch_delete_positions(id_list)
|
||||
```
|
||||
|
||||
## 路由注册
|
||||
|
||||
在 `src/routes/v1.py` 中注册模块路由：
|
||||
|
||||
```python
|
||||
from src.modules.system.position.router import position_blue
|
||||
|
||||
BLUEPRINTS = [
|
||||
# ... 其他模块
|
||||
position_blue,
|
||||
# ... 其他模块
|
||||
]
|
||||
```
|
||||
|
||||
## 总结
|
||||
|
||||
Router 层是 HTTP 接口定义层，只做请求分发和装饰器配置。核心规则：装饰器顺序为 `@blueprint.route()` → `@check_permission`；权限标识格式 `sys:{module}:{action}`；所有逻辑委托 Service 处理。
|
||||
Reference in New Issue
Block a user