app.party创建带前缀的独立路由作用域,如app.party("/v1")生成/v1前缀分组,其get/post路径相对该前缀;返回新application实例,需显式注册handler;支持嵌套分组、中间件隔离与继承,禁用空前缀及query/header版本路由。

用 app.Party 创建带前缀的路由分组
直接调用 app.Party("/v1") 就能生成一个路径前缀为 /v1 的分组,后续所有注册到该分组的路由都会自动带上这个前缀。它不是语法糖,而是独立的路由作用域——内部注册的 Get、Post 等方法,其路径是相对于分组前缀的。
常见错误现象:把 app.Party("/v1") 当成普通变量赋值后忘了用,比如写成 v1 := app.Party("/v1"); v1.Get("/users", handler) 却没在 v1 上注册任何 handler,结果请求 /v1/users 404。
-
app.Party返回的是一个新的Application实例(子应用),不是链式调用对象,必须显式在其上调用Get/Post等 - 支持嵌套:比如
admin := app.Party("/admin"); users := admin.Party("/users"),最终路径是/admin/users/xxx - 不支持空字符串前缀:
app.Party("")会退化为根应用行为,失去分组意义
给不同分组挂载不同的中间件
分组的核心价值不是“省几个字符”,而是中间件隔离。比如 v1 用 JWT,v2 改用 OAuth2,就不能共用同一套鉴权中间件。
使用场景:登录接口在 /auth 分组下不需要鉴权,而 /v1/users 必须校验 token;但两者都要记录日志、压缩响应、处理 CORS。
当代理已经知道网站路由或内容URL,并且在启动前需要有效的sitemap XML、sitemap索引或robots.txt引用时,请使用sitemap。这是一个发布构件技能,而不是爬虫或SEO平台。
- 全局中间件用
app.Use(),对所有路由生效;分组中间件在Party调用时传入,如v1 := app.Party("/v1", jwtMiddleware) - 分组内可再叠加中间件:
v1.Use(oauth2Fallback),执行顺序是父分组中间件 → 当前分组中间件 → handler - 注意中间件里别漏掉
ctx.Next(),否则后续 handler 不会执行
避免用 query 或 header 做版本路由
把版本塞进 ?version=v2 或 Accept: application/vnd.myapp.v2+json,短期看着灵活,长期会让日志归类、监控统计、OpenAPI 文档生成全乱套。
真实踩坑点:Swagger 自动生成时,/users?version=v1 和 /users?version=v2 被识别为同一个 endpoint,参数合并冲突;Prometheus metrics 中 http_request_duration_seconds_count{path="/users"} 完全无法区分 v1/v2 流量。
- 路径前缀是唯一被所有工具链(日志系统、APM、网关、文档生成器)一致识别的版本标识方式
- 如果真要兼容旧客户端,可在入口加一层路由转发:用
app.Any("/users", versionRouter)解析 query 后ctx.Redirect到对应/v1/users或/v2/users,但对外暴露的仍是清晰路径 - 别在 handler 里手动解析
ctx.URL().Query().Get("version")做分支,那等于放弃框架的路由能力
分组间共享配置但不共享状态
Party 继承父应用的模板、视图、错误页等配置,但每个分组的中间件栈、路由树、甚至 ctx.Values() 生命周期都是隔离的。
容易被忽略的地方:你在 v1 分组中间件里用 ctx.Values().Set("user_id", 123),到了 v2 分组的 handler 里是取不到的——这不是 bug,是设计使然。跨版本传递数据必须走显式参数(如 path param)、数据库或外部缓存。
- 模板布局可共享:
v1.Layout("shared/layout.html")和v2.Layout("shared/layout.html")指向同一文件 - 静态文件服务(
HandleDir)默认继承,无需在每个分组重复注册 - 自定义错误页(
OnAnyErrorCode)是全局的,不能按分组覆盖
大量免费API接口:立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游,为数据API应用能力赋能!










