142 lines
4.6 KiB
Markdown
142 lines
4.6 KiB
Markdown
# Handler 层规范
|
||
|
||
## 概述
|
||
|
||
Handler 层是 HTTP 接口层，定义路由和请求处理。每个模块的 Handler 文件位于 `src/modules/{name}/handlers.py`，使用 Tornado Handler 类定义接口。
|
||
|
||
:::tip 设计原则
|
||
- Handler 只做请求分发，不含业务逻辑
|
||
- 通过装饰器控制权限和演示模式
|
||
- 委托 Service 处理业务逻辑
|
||
- 返回 R 封装的响应
|
||
:::
|
||
|
||
## 装饰器顺序
|
||
|
||
```python
|
||
class PositionAddHandler(BaseHandler):
|
||
@permission_required("sys:position:add") # 1. 权限校验
|
||
@check_demo # 2. 演示模式拦截
|
||
@operation_log("岗位管理", "添加") # 3. 操作日志
|
||
async def post(self):
|
||
return await position_service.add(self)
|
||
```
|
||
|
||
:::warning 装饰器顺序规则
|
||
1. `@permission_required("权限标识")`：RBAC 权限校验
|
||
2. `@check_demo`：演示环境写操作拦截（仅写接口需要）
|
||
3. `@operation_log("模块", "动作")`：操作日志记录（仅写接口需要）
|
||
|
||
顺序不可调换，否则权限校验或演示拦截可能失效。
|
||
:::
|
||
|
||
## 读操作（无需 @check_demo）
|
||
|
||
```python
|
||
class PositionPageHandler(BaseHandler):
|
||
@permission_required("sys:position:list")
|
||
async def get(self):
|
||
return await position_service.get_page(self)
|
||
|
||
class PositionDetailHandler(BaseHandler):
|
||
@permission_required("sys:position:detail")
|
||
async def get(self, id):
|
||
return R.ok(self, data=position_service.get_detail(id))
|
||
|
||
class PositionGetListHandler(BaseHandler):
|
||
@permission_required("sys:position:list")
|
||
async def get(self):
|
||
return R.ok(self, data=position_service.get_options(self))
|
||
```
|
||
|
||
## 写操作（需要 @check_demo + @operation_log）
|
||
|
||
```python
|
||
class PositionAddHandler(BaseHandler):
|
||
@permission_required("sys:position:add")
|
||
@check_demo
|
||
@operation_log("岗位管理", "添加")
|
||
async def post(self):
|
||
return await position_service.add(self)
|
||
|
||
class PositionUpdateHandler(BaseHandler):
|
||
@permission_required("sys:position:update")
|
||
@check_demo
|
||
@operation_log("岗位管理", "更新")
|
||
async def put(self):
|
||
return await position_service.update(self)
|
||
|
||
class PositionDeleteHandler(BaseHandler):
|
||
@permission_required("sys:position:delete")
|
||
@check_demo
|
||
@operation_log("岗位管理", "删除")
|
||
async def delete(self, id):
|
||
return await position_service.delete(self, id)
|
||
|
||
class PositionStatusHandler(BaseHandler):
|
||
@permission_required("sys:position:status")
|
||
@check_demo
|
||
@operation_log("岗位管理", "设置状态")
|
||
async def put(self):
|
||
return await position_service.update_status(self)
|
||
|
||
class PositionBatchDeleteHandler(BaseHandler):
|
||
@permission_required("sys:position:delete")
|
||
@check_demo
|
||
@operation_log("岗位管理", "批量删除")
|
||
async def post(self):
|
||
return await position_service.batch_delete(self)
|
||
```
|
||
|
||
## 权限标识规范
|
||
|
||
权限标识格式：`sys:{module}:{action}`
|
||
|
||
| 操作 | 权限标识 | HTTP 方法 |
|
||
|------|---------|----------|
|
||
| 分页查询 | `sys:{module}:list` | GET |
|
||
| 详情查询 | `sys:{module}:detail` | GET |
|
||
| 下拉列表 | `sys:{module}:list` | GET |
|
||
| 添加 | `sys:{module}:add` | POST |
|
||
| 编辑 | `sys:{module}:update` | PUT |
|
||
| 删除 | `sys:{module}:delete` | DELETE |
|
||
| 批量删除 | `sys:{module}:delete` | POST |
|
||
| 状态设置 | `sys:{module}:status` | PUT |
|
||
|
||
:::tip admin 用户
|
||
用户 ID 为 1 的管理员账号跳过所有 `permission_required` 检查。
|
||
:::
|
||
|
||
## 路由注册
|
||
|
||
在 `src/api/v1/{module}.py` 中定义路由列表，在 `src/api/v1/router.py` 中注册：
|
||
|
||
```python
|
||
# src/api/v1/position.py
|
||
from modules.position.handlers import (
|
||
PositionPageHandler, PositionDetailHandler, PositionAddHandler,
|
||
PositionUpdateHandler, PositionDeleteHandler, PositionStatusHandler,
|
||
PositionBatchDeleteHandler,
|
||
)
|
||
|
||
routes = [
|
||
(r"/position/page", PositionPageHandler),
|
||
(r"/position/detail/(\d+)", PositionDetailHandler),
|
||
(r"/position/add", PositionAddHandler),
|
||
(r"/position/update", PositionUpdateHandler),
|
||
(r"/position/delete/(\d+)", PositionDeleteHandler),
|
||
(r"/position/status", PositionStatusHandler),
|
||
(r"/position/batchDelete", PositionBatchDeleteHandler),
|
||
]
|
||
```
|
||
|
||
```python
|
||
# src/api/v1/router.py
|
||
from api.v1 import position
|
||
_RESOURCE_MODULES = [..., position]
|
||
```
|
||
|
||
## 总结
|
||
|
||
Handler 层是 HTTP 接口定义层，只做请求分发和装饰器配置。核心规则：装饰器顺序为 `@permission_required` → `@check_demo` → `@operation_log`；读操作无需 `@check_demo` 和 `@operation_log`；权限标识格式 `sys:{module}:{action}`；所有逻辑委托 Service 处理。
|