Go http.Cookie.Valid 为什么会拒绝不合法的 SameSite 值

如果你看到 Go 的 Cookie 校验似乎“拒绝了不合法的 SameSite”，先记住一个容易混淆的事实：http.Cookie.Valid() 当前并不检查 SameSite 枚举。它负责检查 Cookie 结构字段和 Partitioned 与 Secure 的组合；未知的 SameSite 值更可能在序列化时被静默省略，而不是由 Valid 返回错误。

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

排查时把问题拆成两层：先用 Cookie.Valid() 判断字段是否能组成合法 Cookie，再单独限制业务允许的 SameSite 值。不要把“响应头里没有 SameSite”直接当成 Valid 拒绝。

先纠正一个判断：Valid 不会校验 SameSite

Valid 的检查顺序很具体：Cookie 不能是 nil，Name 必须是合法 token，Expires 要能表示为合法时间，Value 和 Path 不能含非法字节，Domain 必须通过域名检查；如果设置了 Partitioned，还必须同时设置 Secure。源码中没有对 SameSite 做枚举校验。

因此下面这个对象即使把 SameSite 设成一个不存在的数值，Valid 仍可能返回 nil；真正会让它失败的通常是名称、值、路径、域名、过期时间，或 Partitioned 没有配合 Secure。

package main

import (
    "fmt"
    "net/http"
)

func main() {
    cookie := &http.Cookie{
        Name:     "session",
        Value:    "abc123",
        SameSite: http.SameSite(99), // 中文注释：故意放入未知枚举值，观察 Valid 的职责边界
    }

    err := cookie.Valid() // 中文注释：这里只检查 Cookie 字段，不负责业务策略枚举
    fmt.Printf("valid error: %v\n", err)
    fmt.Printf("header value: %s\n", cookie.String()) // 中文注释：序列化阶段决定是否输出 SameSite
}

这个例子里更值得关注的是职责分工：Valid 的 nil 只说明结构字段通过了标准库的字段检查，并不代表你的业务允许任意 SameSite 数值。

为什么看起来像拒绝：String 与 ParseSetCookie 的静默处理

创建响应头时，Cookie.String() 只对 Default、Lax、Strict、None 四种已知模式写出对应属性。Default 模式本来就不写 SameSite，未知整数也不会写出一个“非法 SameSite”字符串，所以最终响应头可能只是 session=abc123。SetCookie 进一步使用这个序列化结果，非法名称还可能让它静默放弃整个 Cookie。

反过来解析 Set-Cookie 时，Go 会把 lax、strict、none 映射到对应常量；遇到未知或非 ASCII 的 SameSite 文本时，则回到默认模式。也就是说，解析和序列化都不会替你完成业务层的“只允许哪几种值”判断。

旧代码怎么改：把字段合法性和策略校验分开

建议先限制业务枚举，再调用标准库校验。这样错误信息能说明到底是“业务不允许”还是“Cookie 字段不合法”，也不会把未知值悄悄降成默认模式。

package main

import (
    "fmt"
    "net/http"
)

func validateCookie(cookie *http.Cookie) error {
    if cookie == nil { // 中文注释：先挡住 nil，避免后续读取字段
        return fmt.Errorf("cookie 不能为空")
    }

    switch cookie.SameSite { // 中文注释：业务层只接受标准库定义的四种模式
    case 0, http.SameSiteDefaultMode, http.SameSiteLaxMode,
        http.SameSiteStrictMode, http.SameSiteNoneMode:
        // 中文注释：0 表示调用方没有指定 SameSite，交给默认策略处理
    default:
        return fmt.Errorf("不支持的 SameSite 值: %d", cookie.SameSite)
    }

    if err := cookie.Valid(); err != nil { // 中文注释：再检查名称、值、域名等结构字段
        return fmt.Errorf("Cookie 字段无效: %w", err)
    }
    return nil
}

如果使用 SameSite=None，还应按你的浏览器兼容和部署策略确认是否需要同时设置 Secure；这属于发送策略，不是 Cookie.Valid 的枚举校验。不要把客户端浏览器行为与服务端结构检查混成一个错误来源。

最小验证与速查

一句话总结：Cookie.Valid() 解决“这个 Cookie 的字段是否合法”，而 SameSite 白名单解决“业务允许发送哪种策略”。两层分别处理，才能准确定位所谓的“拒绝”。

相关问题

• 为什么 Cookie 设置了非法 Domain 后仍然能看到响应？
• Partitioned 为什么必须和 Secure 一起设置？
• Go 解析未知 SameSite 文本后怎样保留原始属性？