# 4.2 请求处理链路

:::tip 链路概览
一个典型 API 请求经过：浏览器 →（Nginx/Vite 代理）→ 中间件链 → 反射路由绑定 → handler → service → repository → 数据库 → 统一信封返回。本页以 `GET /api/example/page` 为例逐阶段拆解。
:::

## 第一阶段：网络层

前端经封装发起请求（`ui/src/api/tool/example.ts`）：

```typescript
// ui/src/api/tool/example.ts（摘录）
import { http } from '@/utils/http/axios';

// Authorization: Bearer <access_token> 由请求拦截器自动携带
export function getExamplePage(params?: Record<string, any>) {
  return http.request({ url: '/example/page', method: 'GET', params });
}
```

开发期 Vite 代理转发（`ui/.env.development`）：

```text
VITE_PROXY=[["/api", "http://127.0.0.1:8000/api"]]
```

生产由 Nginx 反代到 8000（见 deploy/nginx.conf）。

## 第二阶段：中间件链（顺序勿动）

```text
trace        分配 trace_id，后续全部日志可关联
   ↓
CORS         跨域响应头（cors.allowOrigin）
   ↓
Metrics      Prometheus 指标采集（请求数/耗时）
   ↓
Response     统一信封出口 + panic 恢复（必须包住其后全部 handler）
   ↓
RateLimit    固定窗口限流（认证接口配额更严）
   ↓
Demo         演示模式：写操作拒绝，读与登录放行
   ↓
JWT          解析 Token，注入身份（公开接口跳过）
   ↓
Tenant       加载租户上下文（白名单表隔离依据）
   ↓
Authz        按路由元数据 Permission 校验权限点
   ↓
OperationLog 采集请求摘要，链尾异步落库（须读到最终响应）
```

顺序是设计约束：trace 最先（日志依赖 trace_id）；Response 在业务前（panic 恢复包住全链）；限流/演示在身份前（防未认证高频攻击）；JWT → 租户 → 权限逐层依赖前置注入的身份；日志链尾采集。

## 第三阶段：路由绑定

`router.Bind` 已在启动期把 `GET /api/example/page` 注册到 Gin 路由树。请求命中后，包装函数执行：

```text
绑定写入：query（pageNo/pageSize/name/type/status/keyword）→ body → path
        │  同名后写覆盖，最终 path > body > query
        ▼
binding 标签校验（失败直接 4xx 信封返回，不进 handler）
        │
        ▼
构造 dto.ExamplePageReq → 调用 CExample.Page
```

## 第四阶段：四件套调用

```go
// handler：一行委托
service.Example.Page(ctx, req)

// service：委托基座
list, total, err := exampleSpec.Page(ctx, req, req.GetPageNo(), req.GetPageSize())

// ModuleSpec：applyFilters 固定顺序生效
Model（Ctx 已注入 del_flag=0）→ LikeFields(name) → EqFields(type,status)
→ KeywordFields → Filter → DataScope → OrderBy → 分页 Find
```

ctx 贯穿全链——身份、租户、事务连接都挂在 ctx 上，repository 经 `db.FromContext(ctx)` 取连接。

## 第五阶段：响应与日志

```text
service 返回 PageData[ExampleItem]
   ↓
绑定层包装函数调用 response.Ok(data)
   ↓
Response 中间件信封输出 {code:0, ok:true, msg, data}
   ↓
OperationLog 中间件读取最终响应摘要，异步写 gin_operation_log
   （LogType=query 时还受 operationLog.logQuery 开关控制）
```

失败路径：binding 校验失败 / apperr 错误 / 普通 error / panic，全部经 Response 中间件映射为对应 code 的 JSON 信封，绝不出现 HTML 错误页（NoRoute 也返回 JSON）。

## 关键观察点

| 阶段 | 观察手段 |
|---|---|
| 全链追踪 | 响应头/日志中的 trace_id |
| SQL | `database.default.debug=true` 打印 SQL |
| 权限 | Swagger（/swagger）查看接口权限码 |
| 指标 | /metrics 看请求计数与耗时分布 |
| 日志落库 | gin_operation_log 表 |

## 下一步

→ [4.3 后端分层架构](/zh/architecture/backend-layer.html)