http.ServeMux不支持多级域名路由，因其仅按路径前缀匹配且忽略Host头，无法提取子域名、注入上下文或区分api.example.com与admin.example.com；必须用自定义Handler从r.Header.Get("Host")提取并标准化后分发。
为什么不能用 http.ServeMux 做多级域名路由
http.ServeMux 只能按 Host 字符串做简单匹配，不支持通配符、正则或路径段提取，更无法在匹配后动态注入域名上下文。比如 api.example.com 和 admin.example.com 都指向同一网关进程，但 ServeMux 无法区分二者并分发到不同子路由；它甚至会把 www.example.com 和 example.com 当作两个独立 host，导致重复注册 panic。
常见错误是写成：http.Handle("api.example.com/", apiRouter)——这根本不会生效，ServeMux 忽略 host 前缀，只认路径开头。
- 必须用
http.Handler接口实现自定义入口，从r.Host提取域名再分发 - 别依赖
req.URL.Host，它可能被反向代理篡改；优先用r.Header.Get("Host")并标准化（小写、去端口） - 域名白名单不能硬编码在 if 分支里，否则新增域名要重启服务
如何用 gin 实现域名白名单 + 路由分发
gin 的 gin.Engine 本身不支持多 host 分发，但可以包装一层：启动时加载域名白名单（如从 etcd 或 embed.FS），然后在顶层 handler 中按 host 查表，再将请求转发给对应子 router。
关键不是“怎么注册路由”，而是“怎么快速查域名”。白名单量大时，用 map[string]*gin.Engine 直接查 O(1)，比遍历 slice 快一个数量级。
立即学习“go语言免费学习笔记（深入）”；
- 白名单结构建议用
map[string]struct{}存域名，避免 value 占内存 - 域名标准化：去掉端口（
:443）、转小写、处理通配符（*.example.com→ 正则^[a-z0-9.-]+\.example\.com$） - 子 router 必须用
gin.New()独立创建，不能共用gin.Default()—— 否则中间件和 Recovery 会互相干扰 - 转发时调用
subRouter.ServeHTTP(w, r)，而非r.Context传递，避免 context 生命周期错乱
字符串白名单匹配的性能陷阱
看似简单的 strings.Contains 或 strings.HasPrefix 在域名匹配中极易翻车：比如 example.com 会误匹配 myexample.com；用 == 又无法支持通配符。真正高速且安全的做法是预编译正则或用 trie 树，但多数网关场景用 map 查足够。
如果必须支持泛域名（如 *.svc.internal），别现场 regexp.Compile——每次编译开销大，且并发下易触发锁竞争。应提前编译好正则并缓存：
- 白名单加载时，对每个含
*的条目生成*regexp.Regexp，存入sync.Map - 查匹配时先走精确 map 查，未命中再遍历正则 slice（长度通常
- 避免用
net/http/httputil.DumpRequest做 debug 日志——它会读空req.Body，后续 proxy 拿不到 body
多级域名路由与 Director 的协作要点
域名路由层只是第一道分发，后面仍需 httputil.NewSingleHostReverseProxy 做路径转发。但 Director 函数里不能再动 req.Host，因为域名已由上层确定；重点是确保 req.URL.Path 不被二次截断。
典型结构是：api.example.com → /v1/users → user-svc，其中 /v1 是 API 版本前缀，应在域名路由层剥离，而非丢给 Director 处理。
- 子 router 的
Group("/v1")会自动剥离前缀，Director 只需处理/users段 - Director 中不要调
strings.TrimPrefix(req.URL.Path, "/v1")—— 这会导致嵌套路由（如/v1/users/:id/orders）路径错乱 - 若下游服务依赖原始 Host（如生成重定向 Location），用
req.Header.Set("X-Forwarded-Host", r.Host)透传，别改req.Host - 所有域名白名单变更必须原子更新：先建新 map，再
atomic.StorePointer替换旧指针，避免查表时 panic
localhost:8080 测试没问题，上线后 Nginx 或 ALB 插入的 X-Forwarded-Host 可能带端口或大小写混杂，没清洗就查 map 会直接 fallback 到默认路由。 
