Go http.Cookie.Valid 怎样在发送前发现非法 Cookie

Go 里动态生成 Cookie 时，建议在调用 http.SetCookie 之前先执行 cookie.Valid()。它会把非法的名称、值、过期时间、路径、域名，以及 Partitioned 没有同时开启 Secure 等问题直接返回为错误；这样比等到序列化后才发现响应里缺少 Cookie 更容易排查。

官方地址：https://pkg.go.dev/net/http#Cookie.Valid

一个重要边界是：Valid 检查的是 Go 对 Cookie 字段的可接受性，不会替你决定 SameSite 策略、登录态生命周期或浏览器是否会在某个跨站场景发送它。

先认识 Valid 检查的字段边界

Cookie.Valid 返回第一个发现的错误。名称必须是合法 token；值中的每个字节要符合 Cookie 值规则；非零过期时间必须是可接受的时间；路径和域名也各有自己的格式约束。若设置了 Partitioned，还必须同时设置 Secure。

这意味着“结构体能成功创建”不代表 Cookie 合法。结构体只是 Go 值的容器，真正写出时还要满足 HTTP Cookie 的字段约束。尤其是外部输入直接进入 Name、Value 或 Domain 时，不要只检查字符串是否为空。

把 Valid 放在 Cookie 输出之前

最稳妥的写法是把校验放在响应写出边界之前。下面的例子故意放入一个带空格的值，并打印具体错误；实际服务中可以把错误交给日志、指标或统一错误处理，而不是继续写出这个 Cookie。

package main

import (
	"fmt"
	"net/http"
)

func checkCookie(cookie *http.Cookie) error {
	// Valid 会返回第一个字段错误，调用方可据此拒绝本次输出。
	if err := cookie.Valid(); err != nil {
		return fmt.Errorf("cookie 校验失败: %w", err)
	}
	return nil
}

func main() {
	cookie := &http.Cookie{
		Name:  "session_id",
		Value: "abc def", // 空格不应直接进入 Cookie 值。
	}
	if err := checkCookie(cookie); err != nil {
		fmt.Println(err)
		return
	}
	// 只有通过字段校验后，才把 Cookie 交给响应输出层。
	fmt.Println(cookie.String())
}

不要把 cookie.String() 的非空结果当成完整校验。String 面向序列化，在某些非法字段场景下会清理或丢弃属性；Valid 的价值正是把问题作为错误显式交还给业务层。官方实现还说明，SetCookie 对无效 Cookie 可能静默丢弃，所以提前调用 Valid 更适合作为排障入口。

区分 Valid、String 和浏览器策略

三者解决的问题不一样：

• Valid：判断 Go 结构体字段是否满足实现中的 Cookie 约束，并返回错误。
• String：把 Cookie 序列化为可用于 Cookie 或 Set-Cookie 头的文本；无效名称会得到空字符串，部分属性可能被清理或忽略。
• 浏览器策略：决定 SameSite、Secure、Domain、Path 和跨站请求等场景下是否真正发送，不能由 Valid 代替。

例如，业务要求只允许 HTTPS 传输时，除了让 Valid 通过，还应明确设置 Secure；业务要求跨站请求携带 Cookie 时，还要按实际场景选择 SameSite。这些是应用策略，不是“校验通过”自动带来的结果。

用错误字段快速定位问题

当浏览器看不到预期 Cookie，先在输出边界记录 Valid 返回的错误文本，再按字段定位，而不是反复调整大小写或重新拼接字符串：

1. 出现 invalid Cookie.Name，检查名称是否混入空格、分隔符或控制字符。
2. 出现 invalid byte ... in Cookie.Value，检查值是否直接来自未编码的用户输入。
3. 出现 invalid Cookie.Path 或 invalid Cookie.Domain，检查路径、域名的来源和拼接逻辑。
4. 出现 partitioned cookies must be set with Secure，先补齐字段组合，再继续判断浏览器兼容性。

func writeCookie(w http.ResponseWriter, cookie *http.Cookie) error {
	// 在 Header 写出之前保留字段错误，避免 SetCookie 静默丢弃无效值。
	if err := cookie.Valid(); err != nil {
		return err
	}
	// 通过校验后再交给 net/http 生成 Set-Cookie 响应头。
	http.SetCookie(w, cookie)
	return nil
}

常见问题

Valid 返回 nil 就代表浏览器一定会发送吗？

不是。它只说明 Go 的字段检查通过，仍要结合请求是否跨站、Secure、SameSite、Domain、Path 和过期时间判断实际发送条件。

为什么直接调用 SetCookie 没有报错？

SetCookie 的接口没有返回 error，文档也提示无效 Cookie 可能被静默丢弃。需要错误反馈时，应在调用前显式执行 Valid。

Valid 会检查 Cookie 的业务内容吗？

不会。它不理解 session 是否过期、值是否属于某个用户，也不会验证签名。业务校验和 Cookie 字段校验要分开。

小结

把 http.Cookie.Valid 放在 Cookie 输出边界之前，可以把“响应里没有 Cookie”的模糊现象变成具体字段错误。实践中先处理 Name、Value、Expires、Path、Domain 和 Partitioned/Secure 约束，再单独设计 SameSite、认证和生命周期策略，排查路径会清楚很多。

技术依据：https://pkg.go.dev/net/http#Cookie.Valid；https://go.dev/src/net/http/cookie.go