Go CrossOriginProtection.SetDenyHandler 怎样统一处理跨源拒绝响应

Go 1.25 及以上的 net/http.CrossOriginProtection 可以在 Handler 入口拦截跨源浏览器写请求。若你只想把默认的 403 改成统一 JSON、补充 request_id 或接入现有日志系统，关键方法就是 SetDenyHandler：它只替换“拒绝后怎么回应”，不改变“请求是否应该被拒绝”的判断。

官方地址：https://pkg.go.dev/net/http#CrossOriginProtection.SetDenyHandler

最稳妥的接法是：先用 CrossOriginProtection.Handler 包住业务路由，再用 SetDenyHandler 统一输出拒绝响应；不要在拒绝处理器里重新实现 Origin 或 Sec-Fetch-Site 判断。

先分清谁负责判断，谁负责返回

CrossOriginProtection 关注的是跨源请求保护。GET、HEAD、OPTIONS 属于安全方法，会被放行；没有 Sec-Fetch-Site 或 Origin 的请求，目前也会被视为同源或非浏览器请求。真正需要重点关注的是带跨源证据的状态改变请求，例如 POST、PUT 或 DELETE。

SetDenyHandler 不接收判断结果参数，它只设置一个 Handler：当 Check 判定请求不应继续时，由这个 Handler 生成拒绝响应。这样可以把安全判断留给标准库，把 JSON 字段、日志和前端约定留在应用层。

用 SetDenyHandler 固定 JSON 响应

拒绝处理器要做的事情很少：设置状态码和 Content-Type，写出稳定字段，再记录必要的请求标识。不要把 Origin 原值直接回显给客户端，也不要因为某个路径是“内部接口”就绕过保护器。

package main

import (
    "encoding/json"
    "net/http"
)

func denyJSON(w http.ResponseWriter, r *http.Request) {
    // 统一拒绝格式；不回显 Origin，避免把跨源信息变成响应内容。
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(http.StatusForbidden)
    _ = json.NewEncoder(w).Encode(map[string]string{
        "code":    "cross_origin_rejected", // 给前端稳定的机器可读码。
        "message": "request is not allowed from this origin", // 不暴露内部判断细节。
    })
}

func protectedHandler() http.Handler {
    mux := http.NewServeMux()
    mux.HandleFunc("/profile", func(w http.ResponseWriter, r *http.Request) {
        // 这里假设业务已经通过跨源保护，继续执行状态修改。
        w.WriteHeader(http.StatusNoContent)
    })

    protection := http.NewCrossOriginProtection()
    protection.SetDenyHandler(http.HandlerFunc(denyJSON))
    // 把保护器放在路由入口，避免遗漏其他写接口。
    return protection.Handler(mux)
}

如果项目已经有统一错误中间件，可以让 denyJSON 复用同一套字段，但要保留 403 语义。SetDenyHandler 可以并发调用并作用于后续请求，不过生产代码仍建议在服务器启动阶段完成配置，避免运行中出现响应契约切换。

测试时要覆盖允许、拒绝和未知三类请求

不要只发一个没有请求头的 POST 就宣布配置成功。至少构造三组请求：没有 Origin 的非浏览器请求、带同源 Origin 的请求，以及带跨源 Origin 的写请求。若要覆盖现代浏览器信号，再分别设置 Sec-Fetch-Site: same-origin 与 cross-site。

func testRequest(method, origin, fetchSite string) *http.Request {
    // 用固定头部构造边界样本，便于测试拒绝处理器的 JSON 契约。
    req := httptest.NewRequest(method, "http://api.example.test/profile", nil)
    if origin != "" {
        req.Header.Set("Origin", origin) // 模拟浏览器携带的来源。
    }
    if fetchSite != "" {
        req.Header.Set("Sec-Fetch-Site", fetchSite) // 模拟同源或跨源站点关系。
    }
    return req
}

实际测试代码需要导入 net/http/httptest，并用 httptest.NewRecorder 调用返回的 Handler。检查 Code 是否为 403、响应头是否为 JSON、正文的 code 是否稳定即可；不要把没有相关头部的请求误判成“保护失效”，因为标准库当前明确把它们当作同源或非浏览器请求。

三个容易踩到的边界

• 它不是 CORS：CrossOriginProtection 负责拒绝危险的跨源浏览器请求，不能替代跨域资源读取策略；需要让浏览器读取响应时，仍要单独设计 CORS。
• 可信来源要精确：如果使用 AddTrustedOrigin，按完整的 scheme、host 和可选 port 配置，不要用模糊的通配来源。
• 不要把拒绝处理器当审计系统：可以记录 request_id、方法和路由，但应避免记录 Cookie、Authorization 或完整 Origin 等敏感值。

常见问题

SetDenyHandler 会让跨源请求变成允许吗？不会。它只改变拒绝分支的响应 Handler，检查仍由 CrossOriginProtection 完成。

为什么测试请求没有 Origin 也返回 200？当前规则把缺少 Origin 和 Sec-Fetch-Site 的请求视作同源或非浏览器请求；要测试跨源拒绝，应明确设置跨源 Origin 或 cross-site 信号。

最后的落地顺序可以压缩成一句话：在启动阶段创建保护器，先配置可信来源和拒绝响应，再用 Handler 包住完整路由树，最后用三类请求验证 403 JSON 契约。这样既保留标准库的判断边界，也能让前端和日志系统获得稳定结果。