CrossOriginProtection 怎样接入已有 HTTP 中间件链

已有 Go HTTP 服务通常已经串着恢复、访问日志、认证和路由中间件。接入 CrossOriginProtection 时，最稳妥的做法不是把它散落到每个接口，而是让它包住需要保护的业务 mux，并保留现有链条的可读顺序：请求先经过公共治理，再在进入业务处理器前完成跨源检查。这样被拒请求不会触发业务副作用。

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

核心结论：用 http.NewCrossOriginProtection().Handler(mux) 把检查放在业务边界，可信前端通过 AddTrustedOrigin 精确登记；只有确有必要的无凭据回调才配置 bypass。它解决的是跨源写请求保护，不是给浏览器补 Access-Control-Allow-Origin。

先确定检查边界与中间件顺序

把“检查谁”先想清楚，再决定“放在哪里”。下面的链条示例让恢复和日志仍覆盖整个请求，同时让认证与跨源检查都发生在业务 mux 之前：

package main

import "net/http"

// wrap 按从外到内的顺序包裹中间件，便于审查请求边界。
func wrap(h http.Handler, mws ...func(http.Handler) http.Handler) http.Handler {
	for i := len(mws) - 1; i >= 0; i-- {
		h = mws[i](h)
	}
	return h
}

func buildHandler(mux http.Handler, auth func(http.Handler) http.Handler) http.Handler {
	protection := http.NewCrossOriginProtection()
	// 跨源检查贴近业务 mux，拒绝后不会进入路由处理器。
	protected := protection.Handler(mux)
	// auth、访问日志和恢复仍由已有链条负责。
	return wrap(protected, auth, accessLog, recoverPanic)
}

// 下面三个函数代表已有项目中的中间件，不是新的安全策略。
func accessLog(next http.Handler) http.Handler { return next }
func recoverPanic(next http.Handler) http.Handler { return next }

这里的关键不是 wrap 本身，而是 protected 成为业务链的内层边界。若把检查放在某个单独路由内部，新增路由很容易漏掉；若把状态变更逻辑放在检查之前，拒绝请求也可能留下副作用。生产代码还应按现有认证策略决定认证与跨源检查的相对位置，并保持异常恢复覆盖整个链条。

初始化可信 Origin 并处理配置错误

AddTrustedOrigin 接受精确的 scheme://host[:port]，不能把 /callback、查询串或片段拼进去。配置失败应该在启动时返回，而不是等第一笔请求才暴露：

func newProtection() (*http.CrossOriginProtection, error) {
	c := http.NewCrossOriginProtection()
	// Origin 是完整来源，不包含路径；端口不同也应视为不同来源。
	if err := c.AddTrustedOrigin("https://console.example.com"); err != nil {
		return nil, err // 启动失败比线上静默放行更容易定位
	}
	if err := c.AddTrustedOrigin("https://console.example.com:8443"); err != nil {
		return nil, err
	}
	return c, nil
}

可信 Origin 是 exact match，不是“同一主域名都信任”。前置代理如果改变了 Host 或转发头，先把代理契约和应用看到的请求字段统一，再登记实际浏览器发送的 Origin；不要用一个宽泛的后缀字符串掩盖环境差异。

接入自定义拒绝处理器

默认拒绝会返回 403。API 服务若希望统一 JSON，可以使用 SetDenyHandler，但不要把内部错误文本直接作为客户端协议：

func configureDeny(c *http.CrossOriginProtection) {
	c.SetDenyHandler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// 对外只给稳定错误码，详细原因写入受控日志系统。
		w.Header().Set("Content-Type", "application/json")
		w.WriteHeader(http.StatusForbidden)
		_, _ = w.Write([]byte(`{"error":"cross_origin_request_denied"}`))
	}))
}

Handler 会先调用检查，失败时走 deny handler，成功才把请求交给下游。若直接调用 Check 做自定义编排，要记住 Check 本身不会调用 deny handler；这两种接法不要混成一套。

收敛例外路径并区分 CORS

有些旧回调必须保留，但例外配置应当是窄路径、可审计的最后手段：

func configureCallbackException(c *http.CrossOriginProtection) {
	// 只给明确不依赖浏览器凭据的回调留下例外，路径要具体。
	c.AddInsecureBypassPattern("POST /hooks/provider")
}

AddInsecureBypassPattern 的语法和优先级与 ServeMux 相同，并且是“不安全放行”。不要因为路径末尾斜杠、清理路径或重定向行为就假定范围相同；例外应配合调用方认证、签名或一次性令牌。更不要把它当作 CORS 配置：CrossOriginProtection 负责是否让请求进入业务 handler，CORS 负责浏览器是否允许前端读取响应，两个问题需要分别配置。

按请求特征做反向检查

上线前可以用这张表解释放行与拒绝边界：

Sec-Fetch-Site 为 same-origin 或 none 时会通过；缺少这两个来源信息时，标准库当前把请求视作同源或非浏览器请求。若 GET 接口会修改订单、删除数据或触发任务，仍需先修正 HTTP 语义，不能依赖这层保护。

常见问题

CrossOriginProtection 会自动设置 CORS 响应头吗？

不会。它判断请求是否可以进入下游处理器；需要跨域读取响应时，仍要单独设计 CORS 响应头和预检策略。

可信 Origin 可以只写域名吗？

不可以。应写完整的 scheme、host 和可选端口，例如 https://console.example.com。

为什么没有 Origin 的 POST 也可能通过？

标准库当前把同时缺少 Sec-Fetch-Site 与 Origin 的请求视作同源或非浏览器请求，因此允许；这不等于跳过认证。

什么时候应该用 Check 而不是 Handler？

只有在你确实需要把错误编排进已有调度逻辑时才直接调用 Check；普通 HTTP 服务优先用 Handler，让拒绝自然停在业务边界。