329 lines
12 KiB
Markdown
329 lines
12 KiB
Markdown
# 请求完整链路
|
||
|
||
本章以一个具体的 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()` 中兜底关闭。这种设计使得每一层职责单一、可独立测试。
|