Go 1.25 http.CrossOriginProtection 怎么防 CSRF：预检请求、Origin 校验与迁移边界

升级到 Go 1.25 后，最容易被误解的一项 net/http 能力就是 http.CrossOriginProtection：它能替服务端挡住一部分非安全跨源浏览器请求，但不会替你完成登录、权限校验，也不会让所有没有来源头的请求自动变得可信。正确接入的关键，是把它放在现有 Handler 外层，再按真实前端来源补充 Origin 白名单。

如果接口主要面对浏览器并且要阻止跨站修改请求，可以从 NewCrossOriginProtection().Handler(mux) 开始；不要把 GET、HEAD、OPTIONS 当成可以修改数据的后门，也不要把这个中间件当作身份认证。

先看清楚它解决的是哪一段风险

典型场景是浏览器已经登录了后台，页面上的某个第三方站点诱导浏览器向你的写接口发起请求。浏览器可能自动带上 Cookie，服务端如果只看 Cookie，就会把这次跨站操作当成已登录用户的正常操作。

CrossOriginProtection 针对的是“浏览器请求是否来自跨源页面”这一层。它会检查 Sec-Fetch-Site，也会在合适时比较 Origin 和 Host。它不解析业务角色，不替换会话管理，也不阻止命令行客户端直接调用接口。这个边界决定了它应该和认证、授权、请求校验一起使用。

从旧的路由包装迁移到 Handler

如果原来的服务已经有 http.ServeMux，迁移通常只改变服务组装位置。把保护层放在最终路由外侧，能让每个写接口共享同一套跨源判断。

mux := http.NewServeMux()
mux.HandleFunc("/profile/email", func(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPost {
        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
        return
    }
    w.WriteHeader(http.StatusNoContent)
})

protection := http.NewCrossOriginProtection()
server := http.Server{
    Addr:    ":8080",
    Handler: protection.Handler(mux),
}

这里的调用链是 NewCrossOriginProtection 创建保护器，Handler 在真正的路由处理前做检查，检查通过后才进入 mux。如果请求违反跨源规则，默认会得到 403，而不是进入 /profile/email 的业务代码。

跨域前端要用 AddTrustedOrigin 精确放行

有些系统把管理台和 API 放在不同源，例如管理台是 https://console.example.com，接口是 https://api.example.com。这时不要为了“先让它通”而放宽所有来源，而是把确实需要调用的 Origin 明确加入。

protection := http.NewCrossOriginProtection()
if err := protection.AddTrustedOrigin("https://console.example.com"); err != nil {
    log.Fatal(err)
}
server.Handler = protection.Handler(mux)

AddTrustedOrigin 比较的是完整的 scheme、host 和可选 port。协议不同、端口不同或多了路径，都不是同一个 Origin。白名单只解决跨源请求是否进入 Handler，用户是否能修改某个账户仍然要由认证和授权代码决定。

安全方法放行不等于可以随便写数据

官方文档把 GET、HEAD 和 OPTIONS 视为安全方法，它们会被放行。这个规则符合 HTTP 语义，但也留下了一个很实际的代码审查点：如果删除、切换状态、发送邮件等动作藏在 GET 路由里，保护层不会替你纠正这个设计。

迁移时建议逐个检查路由表：读取接口保留 GET，真正改变状态的动作使用 POST、PUT、PATCH 或 DELETE，并在处理函数内部再次检查方法。OPTIONS 只用于预检响应，不应该触发订单变更、密码修改或其他副作用。

和旧 CSRF 方案相比，哪些代码不能直接删

如果旧代码已经使用 CSRF token，不建议因为加入了 CrossOriginProtection 就立即删掉 token。新能力依赖现代浏览器发送的请求元数据和 Origin 信息；没有这些头的请求当前会被假定为同源或非浏览器请求。对需要防御脚本客户端、旧浏览器或复杂代理链的系统，token、SameSite Cookie、认证和授权仍然有各自的作用。

更稳妥的迁移顺序是先外层接入、保留原校验，再在测试环境记录 403 请求的来源和业务影响。确认前端调用路径、代理转发和跨源白名单都稳定后，再评估是否减少重复防护，而不是一次性删除。

上线前用请求头做三组回归

不要只测一个浏览器页面。至少准备同源写请求、跨源写请求和无来源头的客户端请求，分别观察是否进入业务 Handler。

# 跨源写请求：预期被保护层拒绝
curl -i -X POST https://api.example.com/profile/email \
  -H 'Origin: https://other.example' \
  -H 'Sec-Fetch-Site: cross-site'

# 允许的跨源来源：预期进入业务 Handler
curl -i -X POST https://api.example.com/profile/email \
  -H 'Origin: https://console.example.com' \
  -H 'Sec-Fetch-Site: cross-site'

检查点不是“返回 200 就算成功”，而是确认拒绝请求没有产生副作用，允许请求经过认证授权后才改变状态，并且 GET、HEAD、OPTIONS 没有承担写操作。

几个容易踩坑的边界

• 把 AddTrustedOrigin 当成通配符配置：它要求精确 Origin，配置错误应在启动时暴露。
• 只依赖跨源保护而跳过权限判断：跨源请求被挡住，不代表同源用户天然有权操作。
• 把写操作放在 GET：安全方法始终会被放行，这种路由设计必须先改。
• 只看浏览器页面成功：代理、网关和客户端可能改变请求头，回归时要覆盖实际链路。

相关问题

没有 Origin 和 Sec-Fetch-Site 的请求会怎样？

当前 net/http 实现会把它假定为同源或非浏览器请求并放行，所以仍要依靠认证、授权、请求签名或 CSRF token 处理不受浏览器元数据保护的调用方。

跨源保护能替代 CORS 配置吗？

不能。它负责拒绝部分跨源请求，CORS 负责浏览器是否允许前端读取响应，两者关注点不同；跨域前端仍需按实际接口配置 CORS。

迁移清单

先确认项目使用 Go 1.25 或更高版本，再在路由最外层接入 NewCrossOriginProtection 和 Handler；跨源前端逐项登记 AddTrustedOrigin；把所有有副作用的 GET、HEAD、OPTIONS 路由改掉；最后用同源、跨源和无来源头三组请求检查“是否放行”和“是否产生副作用”两个结果。这样迁移的重点就从“加一个中间件”落到了可验证的安全边界上。