Go CrossOriginProtection 如何保护表单写接口

给依赖 Cookie 会话的 Go 表单写接口加 CSRF 防护，可以直接把 http.CrossOriginProtection 放在业务 Handler 外层。它会放行 GET、HEAD、OPTIONS 等安全方法，允许同源浏览器请求，并在写处理器执行前拒绝非安全的跨站浏览器请求；默认拒绝响应是 403。

最实用的接法是保护整个包含写接口的 ServeMux，同时继续保留身份认证、权限校验、输入校验和 SameSite Cookie。CrossOriginProtection 解决的是请求来源边界，不是完整的 Web 安全体系。

官方文档：https://pkg.go.dev/net/http#CrossOriginProtection

背景：手写 Origin 判断为什么越来越别扭

我在整理一个传统表单接口时，旧代码只做了两件事：读取 Origin，再拿它和固定域名比较。看起来简单，但很快会遇到几个问题：有的现代浏览器请求带 Sec-Fetch-Site，有的客户端不带 Origin；反向代理后的 Host 还可能与应用配置不一致；如果每个写接口各写一遍，拒绝规则和日志也很难保持一致。

更容易混淆的是 CORS。CORS 主要控制浏览器是否允许前端脚本读取跨源响应，并不能自动阻止一个恶意页面提交表单。CSRF 场景里，浏览器可能自动携带目标站点 Cookie，即使攻击页面读不到响应，写操作也可能已经发生。因此，写接口需要在业务处理之前判断请求是否来自可接受的浏览器上下文。

Go 1.25 在 net/http 中加入 CrossOriginProtection。官方发布说明把它概括为：利用现代浏览器 Fetch Metadata 拒绝非安全的跨源请求，不要求应用生成 CSRF token 或额外 Cookie，并支持可信来源与模式绕过。对标准表单写接口来说，这让来源判断从散落的业务代码回到了统一中间件。

旧写法的问题不只是代码重复

单独检查 Origin 通常无法清楚回答“头缺失时怎么办”。如果一律拒绝，命令行客户端、服务间请求和旧客户端可能全部失效；如果一律放行，又会让真正的浏览器跨站请求绕过去。手写逻辑还容易把 example.com、admin.example.com、不同端口和不同 scheme 当成同一个来源，白名单范围越写越大。

CrossOriginProtection 的价值不是把几行 if 缩成一个函数，而是提供一套明确且可复用的默认语义。我的采用原则是：让标准库负责浏览器来源判断，让业务层继续负责“这个用户是谁、能改什么、输入是否合法”。两个边界不要混在一起。

新规则：它如何判断一条表单写请求

官方文档和源码给出的判断顺序可以概括为以下几类：

• GET、HEAD、OPTIONS 总是允许。前提是应用绝不能用这些安全方法修改状态。
• 对其他方法，若 Sec-Fetch-Site 为 same-origin 或 none，请求允许进入。
• 如果 Sec-Fetch-Site 表示其他关系，例如跨站请求，则进入可信来源或绕过规则判断，否则拒绝。
• 如果没有 Sec-Fetch-Site，实现会回退到 Origin 与 Host 的比较；Origin 的主机匹配 Host 时允许。
• 如果 Sec-Fetch-Site 和 Origin 都没有，当前规则把它视为同源或非浏览器请求并允许，因此服务间调用仍需认证。

这里有一个容易忽略的取舍：在缺少 Sec-Fetch-Site 时，源码比较 Origin 的 Host 与请求 Host，但无法仅靠 Host 判断 HTTP 到 HTTPS 的 scheme 变化，因此选择放行。官方源码建议站点用 HSTS 缓解这类降级风险。换句话说，这个类型给出的是实用的现代浏览器保护，并不承诺替代传输层配置。

代码对比：把保护器接到写处理器外层

下面的示例保护一个修改邮箱地址的表单接口。路由本身限定为 POST，CrossOriginProtection 包装整个 mux；可信管理前端使用完整 Origin 精确加入，拒绝处理器只返回通用信息，同时记录必要的来源信号。

package main

import (
    "log"
    "net/http"
    "strings"
    "time"
)

func updateEmail(w http.ResponseWriter, r *http.Request) {
    r.Body = http.MaxBytesReader(w, r.Body, 1

AddTrustedOrigin 是精确匹配，值应是 scheme://host[:port]，不能带路径、查询参数或片段。开发环境的 http://localhost:3000 与生产环境的 https://admin.example.com 是两个不同 Origin，应该分别显式配置，不能只写一个宽泛主机后缀。

可信来源、绕过模式和拒绝处理器怎么选

我更倾向优先使用 Handler 包装和少量可信 Origin。只有在 webhook 等路由已经有独立签名认证，而且浏览器来源检查确实不适用时，才考虑模式绕过。绕过模式沿用 ServeMux 的匹配语法，只允许直接匹配；路径清理或补尾斜杠触发的重定向不算直接匹配。配置冲突或语法错误还会 panic，因此它不适合作为运行时接收任意字符串的配置入口。

兼容注意：哪些请求仍会被允许

CrossOriginProtection 对浏览器 CSRF 很有用，但它刻意不阻止所有未知请求。没有 Sec-Fetch-Site 和 Origin 的请求会被允许，这让 CLI、移动客户端和服务间请求保持兼容，也意味着攻击者可以直接构造 HTTP 请求访问接口。身份认证、权限校验、速率限制和审计日志仍然必须存在。

另一个兼容边界是安全方法。GET、HEAD、OPTIONS 永远通过，所以把“删除订单”“修改邮箱”放在 GET 路由上会完全绕开这层保护。迁移前应先盘点所有状态变更端点，把它们调整到 POST、PUT、PATCH 或 DELETE，并确保幂等性与权限规则符合业务语义。

SameSite Cookie 也不需要删除。它可以限制浏览器在跨站场景携带 Cookie，CrossOriginProtection 则在服务器入口根据请求元数据做判断；两者是互补关系。若应用已经有成熟的同步 token 防护，也可以在迁移期并行保留，先观察拒绝指标，再决定是否简化。

采用建议：先保护写接口，再缩小例外

落地时可先列出所有状态变更路由，确认它们没有使用安全方法；然后在测试环境用 Handler 包装 mux，覆盖同源表单、明确跨站请求、可信管理前端、无浏览器头的服务调用四类案例。拒绝日志应按路由和 Sec-Fetch-Site 聚合，不要记录 Cookie 或表单敏感值。

如果上线后出现兼容问题，优先判断它是合法的独立前端 Origin，还是不应经过浏览器 CSRF 检查的机器接口。前者加入精确可信来源，后者更适合使用独立认证和单独路由；不要为了快速恢复而给整个站点添加宽泛绕过。

相关问题

CrossOriginProtection 能代替 CORS 吗？ 不能。它在服务端拒绝不安全的跨站浏览器请求；CORS 决定浏览器脚本能否读取跨源响应，两者目标不同。

为什么同站点子域请求也可能被拒绝？ Sec-Fetch-Site 的 same-site 不等于 same-origin。默认规则只直接允许 same-origin 和 none；确需跨子域写入时应加入精确可信 Origin。

API 客户端没有 Origin 会怎样？ 如果同时没有 Sec-Fetch-Site，当前规则会允许它继续，因此 API 仍必须依靠令牌、签名或其他身份认证。

它从哪个 Go 版本开始可用？ net/http.CrossOriginProtection 在 Go 1.25 加入；较早工具链需要升级或继续使用经过审查的现有 CSRF 方案。