Go http.CrossOriginProtection AddInsecureBypassPattern 怎样给健康检查保留例外

如果健康检查是普通的 GET 或 HEAD，通常不需要增加例外，因为 http.CrossOriginProtection 会把这类安全方法直接放行。只有当内部探针确实使用了非安全方法，例如 POST /healthz，才考虑用 AddInsecureBypassPattern 精确放开这一条请求模式；其它状态变更接口仍交给保护器处理。

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

先判断健康检查是否真的需要例外

CrossOriginProtection 关注的是非安全的跨源浏览器请求。官方文档把 GET、HEAD 和 OPTIONS 视为安全方法，并说明它们始终允许。因此，下面两件事不能混为一谈：

• 探针调用 GET /healthz：重点是让处理器返回健康状态，不要为了“保险”再加一个宽泛 bypass。
• 探针调用 POST /healthz：它属于状态变更方法，需要先确认这个接口没有副作用，再决定是否为精确模式保留例外。

例外的关键词是“精确”。不要把 /、/api/ 这类大范围模式当成健康检查规则，否则其它接口可能一起失去跨源保护。模式、方法和处理器的关系如下图所示。

用方法和路径写出最小例外

模式语法与 ServeMux 相同，所以可以把 HTTP 方法和路径一起写进规则。下面示例假设监控系统因为协议约束使用 POST /healthz，并把例外限制在这一条模式上。示例不执行副作用，只返回固定健康状态。

package main

import (
    "fmt"
    "net/http"
)

func buildHandler() http.Handler {
    mux := http.NewServeMux()
    mux.HandleFunc("POST /healthz", func(w http.ResponseWriter, r *http.Request) {
        // 健康检查只返回状态，不修改业务数据。
        w.Header().Set("Content-Type", "text/plain; charset=utf-8")
        fmt.Fprintln(w, "ok")
    })
    mux.HandleFunc("POST /orders", func(w http.ResponseWriter, r *http.Request) {
        // 订单写接口不加入 bypass，继续接受跨源保护。
        fmt.Fprintln(w, "order handler")
    })

    protection := http.NewCrossOriginProtection()
    // 只放行直接匹配的健康检查模式，不把整个 /api/ 目录设为例外。
    protection.AddInsecureBypassPattern("POST /healthz")
    // 保护器包在业务 mux 外层，未放行的请求先经过跨源检查。
    return protection.Handler(mux)
}

func main() {
    // 示例只组装处理器；生产服务还应配置监听地址、超时和日志。
    if err := http.ListenAndServe(":8080", buildHandler()); err != nil {
        fmt.Println("服务结束:", err)
    }
}

这里的例外不是“允许所有来自某个来源的请求”，而是“允许匹配 POST /healthz 的请求”。如果健康检查可以改成 GET，优先改回安全方法，并删除这条例外，规则会更简单。

保护器仍然要覆盖其它状态变更接口

Handler 会在调用业务处理器前执行跨源检查；检查失败时默认返回 403 Forbidden，也可以通过 SetDenyHandler 统一自定义拒绝响应。不要因为健康检查需要例外，就把保护器只套在某一个路由上，否则其它写接口会绕过同一层边界。

func newServerHandler() http.Handler {
    mux := http.NewServeMux()
    mux.HandleFunc("POST /healthz", health)
    mux.HandleFunc("POST /orders", createOrder)

    protection := http.NewCrossOriginProtection()
    // 例外只对应探针使用的非安全健康检查方法。
    protection.AddInsecureBypassPattern("POST /healthz")
    protection.SetDenyHandler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 拒绝响应不泄露内部规则，只返回统一状态。
        http.Error(w, "cross-origin request denied", http.StatusForbidden)
    }))
    // 同一个保护器包住所有业务路由，避免遗漏订单等写接口。
    return protection.Handler(mux)
}

如果代码拆成多个路由组，仍要确认最终暴露给服务器的顶层处理器只有一个保护边界。Check 方法适合需要自己编排错误处理的场景，但它不会自动调用 SetDenyHandler 设置的处理器；直接使用 Handler 更适合这类统一包裹。

四个容易误配的边界

尤其要注意直接匹配边界：文档明确说明，如果 ServeMux 会把请求重定向到某个模式，例如清理路径或补充尾部斜杠，那么它不属于该 bypass 模式的直接匹配。健康检查客户端应固定请求规范路径，不要依赖重定向后的结果。

健康检查改成 GET 后还要保留 bypass 吗？

通常不需要。GET 属于安全方法，优先删除例外，减少配置面。

可以用 /healthz/... 放行所有探针路径吗？

可以使用 ServeMux 支持的模式，但只有在这些路径都确实是无副作用探针时才考虑；单一固定路径更容易审查。

规则写错会返回 403 还是启动失败？

非法模式或与已有规则冲突时，AddInsecureBypassPattern 会 panic；请求未通过检查时，Handler 默认返回 403。两者是配置阶段和请求阶段的不同问题。