把旧入口迁到新地址时,我更愿意先把“固定跳转”从业务处理函数里拿出来。Go 的 http.RedirectHandler 接收一个固定 URL 和一个 3xx 状态码,返回可以直接挂到路由上的 http.Handler。如果每个请求都去计算目标地址,就不该继续使用它。
官方文档:https://pkg.go.dev/net/http#RedirectHandler
本文围绕一个很窄但容易混用的问题展开:怎样让固定旧路径稳定返回重定向响应,以及什么时候应该升级为动态的 http.Redirect 或自定义 Handler。
RedirectHandler 到底固定了什么
它的签名是 http.RedirectHandler(url string, code int) http.Handler。两个参数在创建 Handler 时就确定了:每次收到请求,目标地址仍然是同一个 url,状态码仍然是同一个 code。标准库文档要求状态码处于 3xx 范围,常见选择包括 301、302 和 303。
这里的“固定”不等于请求只能用 GET,也不等于客户端一定会继续访问新地址。服务端返回的是重定向响应,是否跟随、跟随后如何处理方法和请求体,由客户端及其策略决定。
从内嵌跳转代码迁移到标准 Handler
旧代码常见的写法是在业务函数里直接调用 http.Redirect。当旧入口只是“永远去同一个新地址”时,迁移的变化可以压缩成一行:把响应逻辑提前构造成 Handler,再交给路由表管理。
package main
import "net/http"
func main() {
// 固定目标和状态码在 Handler 创建时确定。
legacy := http.RedirectHandler("/v2/profile", http.StatusMovedPermanently)
mux := http.NewServeMux()
// 旧路径只负责跳转,不再混入业务读取和写响应逻辑。
mux.Handle("/profile", legacy)
_ = http.ListenAndServe(":8080", mux) // 示例省略启动错误处理。
}
上面的迁移适合旧路径、固定回调入口、文档地址搬迁等场景。多个路径如果都指向同一个目标,可以复用同一个 Handler;如果目标不同,就分别创建 Handler,仍然不需要复制响应代码。
301、302、303 怎么选
状态码表达的是迁移意图,不是装饰。可以先按下面这张表做初选,再结合客户端和缓存策略确认。
| 状态码 | 更适合的场景 | 迁移时要注意 |
|---|---|---|
| 301 | 旧地址永久迁到新地址 | 客户端和中间缓存可能长期记住结果,确认迁移确实不可逆再用 |
| 302 | 临时把请求引到另一个地址 | 适合仍可能恢复原入口的短期切换,不要把它当永久迁移信号 |
| 303 | 提交完成后转到结果页 | 用于“提交后查看”语义时更清楚,结果页通常按 GET 访问 |
把 RedirectHandler 接到 ServeMux
RedirectHandler 本身就是 Handler,所以可以直接交给 Handle 或 HandleFunc 周边的路由组织方式。迁移旧路径时,建议让路径匹配和跳转目标各自清楚,避免把“匹配规则”和“目标计算”揉在同一个匿名函数里。
package main
import "net/http"
func newMux() *http.ServeMux {
mux := http.NewServeMux()
// 永久迁移旧文档入口,目标地址不随请求变化。
mux.Handle("/docs/old", http.RedirectHandler("/docs/current", http.StatusMovedPermanently))
// 临时切换维护入口,恢复旧路径时只需要调整这一处配置。
mux.Handle("/maintenance", http.RedirectHandler("/status", http.StatusFound))
return mux
}
如果你还需要给旧入口添加日志、鉴权或响应头,可以在外层包一层 Handler,而不是修改标准库返回的 Handler。这样固定跳转仍然保持单一职责。
请求方法和客户端跟随不要混为一谈
服务端的 RedirectHandler 只负责返回重定向响应。客户端可能自动跟随,也可能把响应交给调用方;不同客户端对 301、302、303 的方法处理也可能不同。因此,不能仅凭服务端创建了一个 RedirectHandler,就断言原请求一定会以某种方法到达新地址。
迁移前至少要把这三个问题写清楚:
- 目标地址是否允许所有请求方法访问,还是只接受 GET。
- 原请求是否带有不能重复发送的请求体。
- 客户端是否会自动跟随重定向,调用方是否需要读取 Location。
如果是表单提交后进入结果页,303 通常比“随手写一个 302”更能表达意图;如果是 API 调用,则应先确认客户端的跟随策略和请求体重放能力。
什么时候应该改用 http.Redirect
只要目标地址或状态码依赖请求内容,固定 Handler 就不够了。例如按 Host 选择目标、根据路径变量拼接新地址,或需要在跳转前记录审计信息,这些都属于动态逻辑。
func redirectByHost(w http.ResponseWriter, r *http.Request) {
// 目标地址依赖 Host,不能预先固定成一个 RedirectHandler。
target := "https://www.example.com" + r.URL.Path
if r.Host == "legacy.example.com" {
// 临时迁移时保留 302,避免把缓存语义写死成永久跳转。
http.Redirect(w, r, target, http.StatusFound)
return
}
// 不满足迁移条件时继续执行正常响应。
http.NotFound(w, r)
}
判断标准很简单:固定 URL、固定 3xx、固定行为,用 RedirectHandler;目标或状态码由请求决定,用 http.Redirect 或自定义 Handler。不要为了“看起来统一”而把动态逻辑硬塞进固定 Handler。
迁移清单
- 确认旧路径是否真的永远指向同一个 URL。
- 根据永久、临时或提交后查看结果选择 301、302 或 303。
- 把 Handler 直接挂到 ServeMux,避免在业务函数中重复写跳转。
- 检查客户端是否自动跟随,以及原请求方法和请求体能否安全重放。
- 发现目标依赖请求时,改用
http.Redirect或自定义 Handler。
一句话总结:http.RedirectHandler 适合“每次都去同一个地方”的固定入口迁移;它简化的是服务端路由组织,不替你决定客户端如何跟随,也不替你设计动态跳转策略。
常见问题
RedirectHandler 能根据请求参数改变目标地址吗?
不能。它创建时就接收固定 URL。需要读取查询参数或路径变量时,使用自定义 Handler,并在其中调用 http.Redirect。
301 和 302 只是数字不同吗?
不是。它们表达永久迁移与临时跳转的不同缓存和迁移语义,选择前要确认旧地址是否还会恢复。
服务端返回 303 后,客户端一定会自动跳转吗?
不一定。是否跟随由客户端决定,服务端只能提供状态码和 Location。调用方需要按所用客户端的文档确认行为。