Iris子域名路由需显式注册且依赖hosts绑定:必须在系统hosts中添加127.0.0.1 admin.mydomain.com等条目,否则请求无法到达;app.Subdomain("admin")仅匹配精确子域,不自动监听,须配合.Get()等方法注册路由,嵌套与重定向逻辑需严格区分。

子域名路由必须显式注册 Party,不能靠 DNS 或 Hosts 自动生效
你写 app.Subdomain("admin"),Iris 不会自动监听 admin.mydomain.com 这个域名——它只在请求已经到达当前 Iris 实例后,才根据 Host 请求头做匹配。所以本地测试前,/etc/hosts(macOS/Linux)或 C:\Windows\System32\drivers\etc\hosts(Windows)里必须加两行:
127.0.0.1 mydomain.com 127.0.0.1 admin.mydomain.com
否则浏览器根本发不出请求到你的服务,更别提路由分发了。
常见错误现象:curl http://admin.mydomain.com 返回 Could not resolve host,或者直接超时;app.Subdomain("admin").Get("/" 完全没响应,不是代码漏了,是请求压根没进来。
Subdomain 和 WildcardSubdomain 的行为差异很关键
app.Subdomain("admin") 只匹配精确的 admin.mydomain.com;而 app.WildcardSubdomain() 匹配任意未被静态子域覆盖的子域,比如 test.mydomain.com、api-v2.mydomain.com 都会落到它里面。
- 静态子域优先级高于通配符:如果同时注册了
app.Subdomain("admin")和app.WildcardSubdomain(),访问admin.mydomain.com一定走前者,foo.mydomain.com才进后者 -
app.Subdomain("admin").Subdomain("panel")生成的是panel.admin.前缀,即匹配panel.admin.mydomain.com,不是admin.panel.mydomain.com - 通配符 Party 无法获取具体子域名值,
ctx.Subdomain()在其中返回空字符串;如需提取,得手动解析ctx.Host()
挂载子域路由时别漏掉 .Get()/.Post() 等方法调用
很多人以为 admin := app.Subdomain("admin") 就完成了“绑定”,其实这只是拿到一个 Party 对象,还没注册任何路由。必须显式调用 HTTP 方法:
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景,三层路由架构(触发词→SAD反馈→DAG编排),recall@10=96.97%。配置驱动(chains.yaml),零代码扩展。pip install skill-weave-chains 一键安装。
admin := app.Subdomain("admin")
admin.Get("/", func(ctx iris.Context) {
ctx.Writef("Hello from admin.mydomain.com")
})
admin.Post("/login", loginHandler)
注意点:
- 不能只写
admin.Get而不传 handler,否则该路由不会注册进路由表 - 子域 Party 支持嵌套:
admin.Party("/api").Get("/users", ...),路径拼接为/api/users,不是/admin/api/users - 中间件对子域 Party 生效,但必须在创建 Party 后、注册路由前传入:
app.Subdomain("admin", authMiddleware)
多级子域和重定向容易混淆,别混用 SubdomainRedirect 和路由逻辑
app.SubdomainRedirect(from, to) 是全局包装器,作用在路由器最外层,所有匹配 from 的请求立刻 301/302 跳转,不进任何 handler。它和 ctx.Redirect() 完全不同:
-
app.SubdomainRedirect(app, www):把mydomain.com全量跳到www.mydomain.com,连/favicon.ico都跳 -
app.SubdomainRedirect(app.WildcardSubdomain(), www):所有未注册的子域都跳到 www,但已注册的admin.mydomain.com不受影响 - 千万别在
app.Subdomain("admin")的 handler 里再调ctx.Redirect()做“子域内跳转”,那只是路径跳转,不是子域切换
复杂点在于:HTTPS 下 SubdomainRedirect 发出的跳转 URL 默认用 http://,若没配 TLS 证书,浏览器会拦截并报错 NET::ERR_CERT_INVALID——这个细节本地开发常被忽略,直到部署到真实域名才暴露。










