签入版本

DjangoAdmin_Tornado_EleVue/zh/volume2/handler.md

@@ -0,0 +1,157 @@
+# 请求处理器（Handler）
+
+Handler 层是 HTTP 接口层，负责接收请求、校验权限、记录操作日志，然后委托给 Service 层处理。每个业务模块对应一个 `handlers.py` 文件，所有 Handler 继承 `BaseHandler`。
+
+## 文件位置
+
+```
+src/modules/link/handlers.py
+```
+
+## 完整代码
+
+```python
+from common.middleware.access_decorators import check_demo, permission_required
+from common.middleware.operation_log import operation_log
+from core import response as R
+from core.base_handler import BaseHandler
+from modules.link.service import link_service
+
+
+class LinkPageHandler(BaseHandler):
+    """查询友链分页数据。"""
+
+    @permission_required("sys:link:list")
+    async def get(self):
+        return await link_service.get_page(self)
+
+
+class LinkDetailHandler(BaseHandler):
+    """查询友链详情。"""
+
+    @permission_required("sys:link:detail")
+    async def get(self, id):
+        return R.ok(self, data=link_service.get_detail(id))
+
+
+class LinkAddHandler(BaseHandler):
+    """添加友链。"""
+
+    @permission_required("sys:link:add")
+    @check_demo
+    @operation_log("友链管理", "添加")
+    async def post(self):
+        return await link_service.add(self)
+
+
+class LinkUpdateHandler(BaseHandler):
+    """更新友链。"""
+
+    @permission_required("sys:link:update")
+    @check_demo
+    @operation_log("友链管理", "更新")
+    async def put(self):
+        return await link_service.update(self)
+
+
+class LinkDeleteHandler(BaseHandler):
+    """删除友链。"""
+
+    @permission_required("sys:link:delete")
+    @check_demo
+    @operation_log("友链管理", "删除")
+    async def delete(self, id):
+        return await link_service.delete(self, id)
+
+
+class LinkStatusHandler(BaseHandler):
+    """设置友链状态。"""
+
+    @permission_required("sys:link:status")
+    @check_demo
+    @operation_log("友链管理", "设置状态")
+    async def put(self):
+        return await link_service.update_status(self)
+
+
+class LinkBatchDeleteHandler(BaseHandler):
+    """批量删除友链。"""
+
+    @permission_required("sys:link:delete")
+    @check_demo
+    @operation_log("友链管理", "批量删除")
+    async def post(self):
+        return await link_service.batch_delete(self)
+```
+
+## 代码解析
+
+### Handler 类
+
+```python
+class LinkPageHandler(BaseHandler):
+```
+
+每个 Handler 继承 `BaseHandler`（即 `tornado.web.RequestHandler`），负责一个 HTTP 端点。与 Tornado 的 Endpoint 函数不同，Tornado 使用类来组织处理器。
+
+### 装饰器说明
+
+| 装饰器 | 作用 | 位置 |
+|:----|:----|:----|
+| `@permission_required("sys:link:list")` | RBAC 权限校验 | 类方法上 |
+| `@check_demo` | 演示模式拦截（仅写操作） | 权限装饰器之后 |
+| `@operation_log("模块", "动作")` | 操作日志记录 | 最内层 |
+
+**装饰器顺序必须严格遵守**：权限 → 演示模式 → 操作日志。
+
+### 路径参数
+
+```python
+async def get(self, id):
+```
+
+Tornado 的路径参数通过正则捕获组传入方法参数。路由定义 `(r"/link/detail/(\d+)", LinkDetailHandler)` 中的 `(\d+)` 对应 `id` 参数。
+
+### 响应封装
+
+- **Service 返回 R 对象的**（如 `add`、`update`、`delete`）：直接 `return`
+- **Service 返回原始数据的**（如 `get_detail`）：用 `R.ok(self, data=...)` 包装
+
+### HTTP 方法映射
+
+| 操作 | HTTP 方法 | Handler 方法 |
+|:----|:----|:----|
+| 分页查询 | GET | `async def get(self)` |
+| 详情查询 | GET | `async def get(self, id)` |
+| 新增 | POST | `async def post(self)` |
+| 更新 | PUT | `async def put(self)` |
+| 删除 | DELETE | `async def delete(self, id)` |
+| 状态变更 | PUT | `async def put(self)` |
+| 批量删除 | POST | `async def post(self)` |
+
+### 权限字符串命名规范
+
+```
+sys:{module}:{action}
+```
+
+| 动作 | HTTP 方法 | 说明 |
+|:----|:----|:----|
+| `list` | GET | 分页/列表查询 |
+| `detail` | GET | 详情查询 |
+| `add` | POST | 新增 |
+| `update` | PUT | 更新 |
+| `delete` | DELETE | 单条/批量删除 |
+| `status` | PUT | 状态变更 |
+
+## 开发要点
+
+1. **Handler 层不含业务逻辑**：仅做权限校验、日志记录和请求分发
+2. **装饰器顺序**：权限 → 演示模式 → 操作日志
+3. **写操作必须加 `@check_demo`**：防止演示环境被修改
+4. **写操作建议加 `@operation_log`**：记录操作日志用于审计
+5. **所有方法都是 `async def`**：Tornado Handler 方法默认异步
+
+## 总结
+
+Handler 层是 HTTP 请求的入口，负责权限校验、操作日志记录和请求分发，不含业务逻辑。装饰器顺序固定为权限 → 演示模式 → 操作日志，写操作必须加 `@check_demo`，所有逻辑委托 Service 处理。