Documentation
¶
Overview ¶
Logger 请求日志中间件（洋葱模型）
洋葱模型执行顺序 ¶
Logger(入站) → Cors → Trace → RateLimit → JWTAuth → Handler Handler → JWTAuth → RateLimit → Trace → Cors → Logger(出站)
Logger 注册在最外层，因此：
- 入站阶段最先执行：记录请求信息，将结构化 logger 注入 Context
- 出站阶段最后执行：此时 traceID 已由 Trace 中间件写入 Context， status/latency 也已确定，可记录完整的响应信息
日志字段说明 ¶
入站（-->）字段：method、path、ip、user_agent 出站（<--）字段：method、path、status、latency、trace_id
trace_id 在入站阶段尚未生成（Trace 中间件在 Logger 内层）， 因此只在出站阶段记录，确保日志里的 trace_id 与响应头一致。
Permission RBAC 权限校验中间件（洋葱模型）
数据模型为五张表：users + roles + permissions + user_roles + role_permissions， 校验逻辑由 user.Permission 服务负责（网关通过 RPC 调用）。
校验流程 ¶
- JWTAuth 先执行，将用户 id 写入 Context
- 本中间件提取 method + path，通过 RPC 调用 user.Permission.CheckRoutePermission
- 不满足则 403
注册示例 ¶
v1.Use(middleware.JWTAuth(), middleware.Permission())
Trace 链路追踪中间件（洋葱模型）
为什么需要 TraceID ¶
微服务架构下，一次请求会流经多个服务（gateway → user → note ...）， 每个服务独立输出日志。没有统一标识时，排查问题需要逐服务翻日志，效率极低。 TraceID 贯穿整条链路，所有服务的日志都带上它，搜索一个 ID 即可还原全链路。
传播规则 ¶
- 优先复用请求头 X-Trace-ID（来自上游服务或 API 测试工具手动传入）
- 没有则由 pkg/trace 生成新 UUID，作为本次请求的链路起点
- 将 traceID 写入响应头 X-Trace-ID，客户端可凭此向客服/研发反馈问题
- 存入 gin.Context（trace.GinContextKey），供 Logger 中间件出站阶段及 handler 读取
与 Logger 中间件的协作 ¶
Trace 在 Logger 内层注册，执行顺序：
Logger(入站) → Trace(入站，生成 traceID) → ... → Trace(出站) → Logger(出站，读 traceID)
因此 Logger 出站阶段可以读到 traceID，实现请求日志与链路 ID 的关联。
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func JWTAuth ¶
func JWTAuth() gin.HandlerFunc
JWTAuth JWT 鉴权中间件（洋葱模型）。
校验流程：
- 读取请求头 token 字段
- pkg/jwt.ParseToken 校验签名和过期时间
- 校验 token_type == "access"（拒绝 refresh token 直接访问接口）
- 校验 jti 不在黑名单（已退出登录或已刷新的 token 立即失效）
- 将 id / role / client_type / jti 写入 Context
Context key 说明：
"id" float64 用户 ID（使用时转 int64：int64(c.GetFloat64("id"))）
"role" float64 角色
"client_type" float64 客户端类型
"jti" string token 唯一 ID，退出登录时用于加入黑名单
func Logger ¶
func Logger() gin.HandlerFunc
Logger 请求日志中间件。 通过 logger.InjectCtx 将携带请求级字段的 logger 注入 Context， 后续 handler 调用 logger.FromCtx(c) 即可获得自动带有 method/path/ip 字段的 logger。
func Permission ¶
func Permission() gin.HandlerFunc
Permission 返回基于 RPC 的权限中间件。 按接口级（method + gin.FullPath）控制，须在 JWTAuth 之后注册。
func RateLimit ¶
func RateLimit() gin.HandlerFunc
RateLimit 限流中间件（洋葱模型），按 IP 令牌桶限流，逻辑在 pkg/ratelimit。
func RateLimitWith ¶
func RateLimitWith(l *ratelimit.Limiter) gin.HandlerFunc
RateLimitWith 使用自定义限流器（可配置 RPS/Burst）。
func Sign ¶
func Sign() gin.HandlerFunc
Sign 签名校验中间件：对所有经过网关的请求生效（在 router.go 全局挂载）。 作用：没有正确签名的人，伪造不了请求（即使他扒到了前端 JS 里的调用方式）。
func Trace ¶
func Trace() gin.HandlerFunc
Trace 链路追踪中间件。 调用 pkg/trace 生成或复用 TraceID，写入 Context 和响应头。
Types ¶
This section is empty.
Source Files