Chi Router 技能介绍
用途
本技能提供使用 Chi v5 构建 Go HTTP 路由与 REST API 的模式参考,覆盖路由、中间件与处理函数(handlers)的组织方式。当涉及 chi、go router、http handlers、go middleware、rest api go 等场景时可参考。
依赖栈
require ( github.com/go-chi/chi/v5 v5.0.12 github.com/go-chi/cors v1.2.1 github.com/go-chi/httprate v0.9.0 github.com/go-chi/render v1.0.3 )
项目结构
apps/api/ ├── cmd/api/main.go ├── internal/ │ ├── config/config.go │ ├── handler/ │ │ ├── handler.go │ │ ├── resource_handler.go │ │ └── response.go │ ├── middleware/ │ │ ├── auth.go │ │ ├── tenant.go │ │ └── logging.go │ ├── router/router.go │ ├── service/ │ └── repository/ └── go.mod
路由初始化
使用 chi.NewRouter() 创建路由器,依次挂载全局中间件:RequestID、RealIP、Logger、Recoverer 与 30 秒超时;再挂载 CORS(允许来源取自配置、方法为 GET/POST/PUT/DELETE/OPTIONS、请求头为 Accept/Authorization/Content-Type、允许凭证、MaxAge 300)与基于 IP 的限流 httprate.LimitByIP(100, time.Minute)。/health 健康检查不鉴权;/api/v1 下包含公开的 /auth/login 与受保护分组,受保护分组先经 JWTAuthMiddleware 与 TenantMiddleware,再挂载 /resources 的列表、创建与按 resourceID 的单条读取/更新/删除,单条路由使用 ResourceCtx 中间件。
处理函数模式
处理器结构体持有 service 依赖并由构造函数注入。List 处理器从上下文取 tenantID,解析 status、page、limit 查询参数,调用 service.List 后返回分页响应;Create 处理器解析 JSON、执行 Validate 校验、调用 service.Create 并返回 201;Get 处理器从上下文中取出已加载资源返回 200。
JWT 中间件
定义 contextKey 常量(ClaimsKey、UserIDKey、TenantKey)。中间件从 Authorization 头提取 Bearer token,校验格式后使用 golang-jwt/jwt/v5 解析并校验签名方法为 HMAC,token 无效返回 401。校验通过后将 claims 与用户 ID 写入上下文。提供 UserIDFromContext 从上下文取值。
资源上下文中间件
ResourceCtx 通过 chi.URLParam 取 resourceID,用 uuid.Parse 校验 ID,非法时返回 400;随后按 tenantID 查询资源,未找到返回 404;成功则将资源写入上下文供后续处理器使用。
响应辅助函数
定义 DataResponse、ErrorResponse、PaginatedResponse 与 Meta 结构。respondJSON 设置 Content-Type 并写出状态码与 JSON;respondError 返回错误信息;respondPaginated 根据 total 与 limit 计算总页数并按统一分页结构返回。
路由模式示例
包括按分组挂载中间件(r.Group)、按单条路由挂载中间件(r.With)、挂载子路由(r.Mount)、读取 URL 参数(chi.URLParam)、读取查询参数(r.URL.Query().Get)以及读取路由上下文与路由模式(chi.RouteContext、RoutePattern)。
测试
给出处理函数单测示例:构造 mock service、使用 httptest.NewRequest 与 httptest.NewRecorder、在上下文中注入 tenant,断言状态码;并给出路由级测试示例,创建 router、使用测试用 auth 中间件、注册路由后调用 ServeHTTP 并断言状态码。
最佳实践
中间件分层:全局用于日志,分组用于认证,单路由用于限流;资源上下文模式:在中间件中加载并校验资源;统一响应:始终使用辅助函数;输入校验:先解码 JSON 再校验后处理。
相关技能
pgx-postgres:数据库访问模式;jwt-auth:认证中间件集成;redis-cache:响应缓存;opentelemetry:分布式追踪。
限制
资料未提供该技能的安装命令、收费信息、支持的平台范围与具体效果说明。