53 lines
2.1 KiB
Markdown
53 lines
2.1 KiB
Markdown
# F. 中间件执行顺序
|
||
|
||
:::tip 说明
|
||
全局中间件链（顺序勿动）：trace → CORS → metrics → response → ratelimit → demo → JWT → tenant → authz → operation_log。每个请求按此顺序穿过。
|
||
:::
|
||
|
||
## 执行表
|
||
|
||
| # | 中间件 | 职责 | 拦截行为 | ctx 写入 |
|
||
|---|---|---|---|---|
|
||
| 1 | Trace | trace_id + 请求元信息 | 不拦截 | trace_id、IP、UA、方法、URL |
|
||
| 2 | CORS | 跨域响应头 | OPTIONS 204 终止 | 无 |
|
||
| 3 | Metrics | Prometheus 计数/耗时 | 不拦截 | 无 |
|
||
| 4 | Response | 统一信封 + panic 恢复 | 错误时写信封终止 | 响应码/体记录 |
|
||
| 5 | RateLimit | 固定窗口限流 | 超限拒绝 | 拒绝原因 |
|
||
| 6 | Demo | 演示模式拒写 | 非 GET/HEAD/OPTIONS 且非公开路径拒绝 | 无 |
|
||
| 7 | JWT | 令牌解析、身份注入 | 401 | 身份、jti/exp、角色权限 |
|
||
| 8 | Tenant | 租户状态校验 | 禁用/过期拒绝 | 无（读身份） |
|
||
| 9 | Authz | 功能权限校验 | 403 | 拒绝原因 |
|
||
| 10 | OperationLog | 操作日志异步落库 | 不拦截 | 无（读响应记录） |
|
||
|
||
另有链外兜底：`gin.CustomRecovery`（静态资源等业务链之外的 panic）。
|
||
|
||
## 顺序约束理由
|
||
|
||
- trace 最先：后续一切日志依赖 trace_id
|
||
- Response 在业务前：panic 恢复包住全部 handler；错误出口统一
|
||
- ratelimit/demo 在身份前：防未认证高频攻击
|
||
- JWT → tenant → authz 逐层依赖前置注入的身份
|
||
- operation_log 链尾：须读到最终响应才采集
|
||
|
||
## 免登录判定（IsPublicRequest）
|
||
|
||
两个来源汇合：
|
||
|
||
| 来源 | 内容 |
|
||
|---|---|
|
||
| 基础设施白名单 | /api/health、/api.json、/swagger*、/metrics |
|
||
| 路由元数据 | RouteSpec.Public=true（登录/验证码/令牌兑换） |
|
||
|
||
## 拒绝类请求的可观测差异
|
||
|
||
| 拒绝 | 操作日志 | metrics 归类 |
|
||
|---|---|---|
|
||
| 限流 / 权限 403 | 不记录 | denied |
|
||
| 租户拒绝 | 不记录 | error |
|
||
| 未认证 401 | 不记录 | —（JWT 层） |
|
||
|
||
## 相关
|
||
|
||
- [4.2 请求处理链路](/zh/architecture/request-flow.html)
|
||
- [5.17 链路追踪与指标](/zh/core/trace-metrics.html)
|