# 请求完整链路

本章以一个具体的 API 请求为例，详细描述从浏览器发起 HTTP 请求到返回响应的完整链路，帮助开发者理解每一层的职责和数据流转方式。

## 请求链路总览

:::tip 链路概览
一个典型的 API 请求经过以下阶段：浏览器 → Nginx → Tornado → Handler 生命周期（set_default_headers → prepare → handler_method → on_finish）→ 响应返回浏览器
:::

以下以 `POST /api/v1/position/add` 添加岗位为例，逐步拆解完整链路。

## Tornado 请求处理模型

Tornado 通过 **Handler 生命周期方法** 和 **装饰器** 实现横切关注点：

```
┌─────────────────────────────────────────────────────────────────┐
│                    Tornado Handler 生命周期                       │
│                                                                  │
│  ① set_default_headers()   → 设置 CORS 头 + trace_id            │
│  ② prepare()               → @login_required（JWT 认证）         │
│  ③ handler method          → @permission_required + @check_demo  │
│                              + @operation_log + 业务逻辑          │
│  ④ on_finish()             → db.close()（释放数据库会话）         │
│                                                                  │
│  异常时：write_error()     → 统一异常响应 + 日志记录              │
└─────────────────────────────────────────────────────────────────┘
```

## 第一阶段：网络层

### 1. 浏览器发起请求

```javascript
// 前端 Axios 调用
const res = await request({
    url: '/api/v1/position/add',
    method: 'post',
    data: {
        name: '高级工程师',
        status: 1,
        sort: 10
    }
});
```

前端通过 Axios 发起 HTTP POST 请求，携带：
- `Authorization: Bearer <JWT Token>` 请求头
- `Content-Type: application/json` 请求头
- JSON 请求体

### 2. Nginx 反向代理（生产环境）

```nginx
location /api/ {
    proxy_pass http://127.0.0.1:8041;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
```

Nginx 将请求代理到 Tornado 服务，同时附加客户端真实 IP 到 `X-Forwarded-For` 头。

## 第二阶段：Handler 生命周期

### 3. 路由匹配

Tornado 根据 HTTP 方法 + URL 路径匹配到对应的 Handler 类：

```python
# src/api/v1/router.py
def build_routes() -> list:
    routes = []
    for module in _RESOURCE_MODULES:
        routes.extend([(V1_PREFIX + path, handler) for path, handler in module.routes])
    routes.append((V1_PREFIX + "/health", HealthHandler))
    return routes
```

路由表中 `POST /api/v1/position/add` 匹配到 `PositionAddHandler`。

### 4. set_default_headers() — 设置响应头

```python
# src/core/base_handler.py
class BaseHandler(tornado.web.RequestHandler):
    def set_default_headers(self):
        super().set_default_headers()
        cros_required(self)     # CORS 跨域头
        apply_trace_id(self)    # 链路追踪 ID
```

- **CORS**：检查 `Origin` 头是否在白名单中，设置 `Access-Control-Allow-*` 响应头
- **trace_id**：生成唯一追踪 ID，写入响应头和上下文变量

### 5. prepare() — JWT 认证

```python
# src/core/base_handler.py
class BaseHandler(tornado.web.RequestHandler):
    @login_required
    def prepare(self):
        pass
```

`login_required` 装饰器在 `prepare()` 阶段执行认证：

```python
# src/common/middleware/authentication.py
def login_required(func):
    def wrapper(self, *args, **kwargs):
        request_url = self.request.path
        # 白名单（/login、/captcha）和 OPTIONS 预检直接放行
        if request_url not in IGNORE_URL and self.request.method != "OPTIONS":
            # 1. 从 Authorization 头提取 Bearer Token
            success, access_token, _ = get_access_token(self.request)
            if not success or not access_token:
                return R.failed(self, code=401, msg="登录过期")
            # 2. JWT 解密验证（签名 + 有效期）
            result = parse_payload(access_token)
            if result["code"] != 0:
                return R.failed(self, code=401, msg="登录过期")
            # 3. 黑名单校验（Redis，不可用时 fail-open 放行）
            if is_token_blacklisted(access_token):
                return R.failed(self, code=401, msg="登录过期")
            # 4. 将用户信息写入上下文变量
            data = result["data"]
            current_user_id.set(int(data["userId"]))
            current_username.set(data.get("username", ""))
            current_realname.set(data.get("realname", ""))
        return func(self, *args, **kwargs)
    return wrapper
```

认证失败时直接返回 `{"code": 401, "msg": "登录过期"}`，不进入后续 Handler 方法。

### 6. Handler 方法 — 权限校验 + 业务处理

```python
# src/modules/position/handlers.py
class PositionAddHandler(BaseHandler):
    @permission_required("sys:position:add")   # ① RBAC 权限校验
    @check_demo                                 # ② 演示模式拦截
    @operation_log("岗位管理", "添加")           # ③ 操作日志记录
    async def post(self):
        return await position_service.add(self)  # ④ 调用 Service 层
```

**装饰器执行顺序**（从外到内）：

```
① permission_required → 校验用户是否拥有 sys:position:add 权限
   ├── user_id == 1（admin）→ 直接放行
   └── 其他用户 → 查询权限列表（Redis 缓存）→ 匹配则放行，否则返回 403

② check_demo → TORNADO_DEMO=True 时返回 "演示环境，暂无操作权限"

③ operation_log → 记录操作日志（请求参数、操作人、IP、耗时等）

④ handler method → 调用 position_service.add(self)
```

### 7. Service 层 — 业务逻辑

```python
# src/core/base_service.py
class BaseService:
    async def add(self, handler) -> R:
        try:
            # 1. 解析请求体 JSON + Pydantic 校验
            form = self._validate(handler, self.create_schema)
            data = form.model_dump()
            # 2. 唯一性校验
            err = self._check_unique(form)
            if err:
                return R.failed(handler, err)
            # 3. 前置扩展钩子
            self._before_add(handler, data)
            # 4. 组装入库字段
            fields = self._build_create_fields(data)
            # 5. 调用 Repository 创建记录
            self.repo.create(self.model(**fields))
            # 6. 返回成功响应
            return R.ok(handler, msg="添加成功")
        finally:
            self.repo.close()
```

### 8. Repository 层 — 数据访问

```python
# src/core/base_repository.py
class BaseRepository:
    def create(self, obj: T) -> T:
        # 自动写入创建人
        if hasattr(obj, "create_user"):
            obj.create_user = str(self._uid())
        self.db.add(obj)
        self.db.commit()
        return obj
```

### 9. 响应返回

```python
# src/core/response.py
def ok(self, data=None, msg="操作成功", code=0, **kwargs):
    body = {"code": code, "data": data, "msg": msg, "ok": True}
    if kwargs:
        body.update(kwargs)
    self._api_result = body
    self.finish(body)  # Tornado 写出 JSON 响应
```

`R.ok()` / `R.failed()` 内部调用 `self.finish(body)`，Tornado 自动序列化为 JSON 并发送 HTTP 响应。

### 10. on_finish() — 释放资源

```python
# src/core/base_handler.py
class BaseHandler(tornado.web.RequestHandler):
    def on_finish(self):
        try:
            db.close()  # 兜底关闭数据库会话
        except Exception:
            pass
```

请求结束后关闭数据库会话，避免长连接泄漏。Service 层的 `finally` 块已关闭时此处为幂等 no-op。

### 11. 异常处理

```python
# src/core/base_handler.py
class BaseHandler(tornado.web.RequestHandler):
    def write_error(self, status_code, **kwargs):
        exc = kwargs.get("exc_info", (None, None, None))[1]
        if isinstance(exc, BaseAppError):
            # 业务异常：按类型分级记录日志
            self.set_status(exc.status_code)
            self.finish({"code": exc.code, "data": None, "msg": exc.msg, "ok": False})
        else:
            # 未预期异常：记录完整堆栈
            self.set_status(500)
            self.finish({"code": 500, "data": None, "msg": "服务器内部错误", "ok": False})
```

| 异常类型 | 触发场景 | 响应 |
|:---|:---|:---|
| `AuthError` | JWT 过期 / 无权限 | `{"code": 401, "msg": "登录过期"}` |
| `PermissionDeniedError` | 权限不足 | `{"code": 403, "msg": "权限不足"}` |
| `ValidationError` | Pydantic 校验失败 | `{"code": 1, "msg": "field: message"}` |
| `BusinessError` | 业务逻辑错误 | `{"code": 1, "msg": "..."}` |
| `NotFoundError` | 记录不存在 | `{"code": 404, "msg": "记录不存在"}` |
| `Exception` | 未捕获异常 | `{"code": 500, "msg": "服务器内部错误"}` |

## 完整链路流程图

```
[浏览器]
   │ POST /api/v1/position/add
   │ Authorization: Bearer <token>
   ▼
[Nginx] ── 反向代理转发
   │
   ▼
[Tornado 路由匹配] ── 匹配 PositionAddHandler
   │
   ▼
[set_default_headers()] ── 设置 CORS 头 + trace_id
   │
   ▼
[prepare() + @login_required] ── JWT 认证
   │  ├─ 白名单（/login、/captcha）→ 跳过
   │  ├─ Token 无效/过期 → 返回 {code:401, msg:"登录过期"}
   │  ├─ Token 在黑名单中 → 返回 {code:401, msg:"登录过期"}
   │  └─ 认证通过 → current_user_id / current_username / current_realname 写入上下文
   │
   ▼
[@permission_required("sys:position:add")] ── RBAC 权限校验
   │  ├─ user_id == 1 → 直接放行
   │  ├─ 权限不足 → 返回 {code:403, msg:"权限不足"}
   │  └─ 权限通过 → 继续
   │
   ▼
[@check_demo] ── 演示模式拦截
   │  ├─ TORNADO_DEMO=True → 返回 {code:1, msg:"演示环境，暂无操作权限"}
   │  └─ 非演示模式 → 继续
   │
   ▼
[@operation_log("岗位管理", "添加")] ── 操作日志装饰器
   │
   ▼
[async def post(self)] ── Handler 方法
   │
   ▼
[position_service.add(self)] ── Service 层
   ├─ parse_json(handler) ── 解析请求体 JSON
   ├─ validate(schema, data) ── Pydantic 校验
   ├─ _check_unique(form) ── 唯一性校验（DB 查询）
   ├─ _before_add(handler, data) ── 前置扩展钩子
   ├─ _build_create_fields(data) ── 组装入库字段
   └─ repo.create(model(**fields)) ── Repository 层
       │
       ▼
   [BaseRepository.create(obj)]
       ├─ obj.create_user = str(uid) ── 自动写入创建人
       ├─ db.add(obj) + db.commit() ── 提交事务
       └─ return obj
   │
   ▼
[R.ok(handler, msg="添加成功")] ── 统一响应
   ├─ self._api_result = body ── 保存结果供日志解析
   └─ self.finish(body) ── 写出 JSON 响应
   │
   ▼
[on_finish()] ── 释放资源
   └─ db.close() ── 关闭数据库会话
   │
   ▼
[浏览器] ← { "code": 0, "data": null, "msg": "添加成功", "ok": true }
```

## 总结

Tornado 的请求处理通过 Handler 生命周期方法（`set_default_headers` → `prepare` → `handler_method` → `on_finish`）和装饰器（`@permission_required`、`@check_demo`、`@operation_log`）实现横切关注点。认证在 `prepare()` 阶段完成，权限/演示模式/操作日志通过装饰器在 Handler 方法执行前校验，数据库会话在 `on_finish()` 中兜底关闭。这种设计使得每一层职责单一、可独立测试。