Go cookiejar.Options.PublicSuffixList 怎么兼容内网测试域名

如果 Go 的 http.Client 在 api.dev.test 和 web.dev.test 之间测试会话，问题通常不在 Cookie 持久化，而在 cookiejar 如何判断 Domain 是否越过了公共后缀边界。测试环境可以通过 cookiejar.Options.PublicSuffixList 注入一个只认识测试后缀的实现；生产环境则应继续使用正式的公共后缀列表。

官方地址：https://pkg.go.dev/net/http/cookiejar#Options

最稳妥的做法是把测试域名统一放在 .test 下，实现一个不可变的测试专用列表，让 PublicSuffix("api.dev.test") 和 PublicSuffix("dev.test") 都以 test 为边界。nil 虽然能绕过测试限制，但只适合隔离测试，不能当作生产配置。

先把 PublicSuffixList 当成 Cookie 域边界

Options.PublicSuffixList 只在创建 Jar 时注入公共后缀判断器。它回答的问题是：“服务器能不能把 Cookie 设置到这个 Domain？”它不负责落盘，也不替代 http.CookieJar 的路径、Secure 和过期时间判断。

例如请求来自 api.dev.test，服务端想设置 Domain=dev.test。如果列表把 test 视为公共后缀，那么 dev.test 仍然是可用的注册域；但直接设置 Domain=test 就应该被拒绝。这个边界正是测试替身需要稳定表达的规则。

内网测试域名为什么容易卡住

很多测试会把服务拆成 api.dev.test、web.dev.test 等多级主机名，然后希望登录服务设置的 Cookie 能在两个子域之间共享。这里至少要分清三件事：

• 主机名：api.dev.test 是当前请求的 Host。
• 共享域：dev.test 是希望写入 Cookie 的 Domain。
• 公共后缀：test 是测试规则中的后缀，不能被当成可写 Cookie 域。

如果测试域名没有统一规则，代码可能在某些机器上使用 localhost，另一些机器上使用多级内网域名，最后把“缺少 Cookie”误判成客户端问题。先固定域名形态，再决定是否注入测试列表，排查会简单很多。

用测试专用后缀列表创建 cookiejar

下面的实现只为测试保留：凡是单独的 test 或以 .test 结尾的域名，都返回 test；其他域名返回空值，表示不要拿这份规则做生产安全判断。实现没有可变状态，因此可被多个 goroutine 并发调用。

package cookiefixture

import (
	"net/http/cookiejar"
	"strings"
)

// testSuffixes 只服务于测试，避免把测试域名规则带入生产环境。
type testSuffixes struct{}

// PublicSuffix 把 .test 作为测试公共后缀，保留 dev.test 这样的共享域。
func (testSuffixes) PublicSuffix(domain string) string {
	domain = strings.TrimSuffix(strings.ToLower(domain), ".")
	if domain == "test" || strings.HasSuffix(domain, ".test") {
		return "test"
	}
	// 非测试域名不由这份替身提供安全判断。
	return ""
}

// String 让日志能标识当前使用的是测试规则。
func (testSuffixes) String() string { return "test-only-public-suffixes" }

// newTestJar 创建跨 api.dev.test、web.dev.test 共享 Cookie 的测试 Jar。
func newTestJar() (*cookiejar.Jar, error) {
	// 规则不可变，适合在并发测试中复用；不要把它注入生产客户端。
	return cookiejar.New(&cookiejar.Options{PublicSuffixList: testSuffixes{}})
}

关键不是把所有域名都返回空字符串，而是让测试域名拥有明确、可复现的边界。dev.test 不是公共后缀本身，所以服务端设置 Domain=dev.test 仍有机会被 Jar 接受；Domain=test 则会撞上公共后缀边界。

生产代码和测试代码怎么分开

正式客户端应使用完整的公共后缀列表，例如 golang.org/x/net/publicsuffix 提供的实现。它可以防止一个站点把 Cookie 写到不应共享的公共后缀上。测试替身只应出现在测试构造函数、测试辅助包或带明确 build tag 的代码中。

func newClientForTest() (*http.Client, error) {
	jar, err := newTestJar()
	if err != nil {
		// 保留构造错误，避免测试在初始化阶段静默降级。
		return nil, err
	}
	return &http.Client{Jar: jar}, nil
}

func newProductionClient() (*http.Client, error) {
	// 生产环境使用项目选定的正式 publicsuffix.List；不要用 nil 绕过边界。
	jar, err := cookiejar.New(&cookiejar.Options{PublicSuffixList: publicsuffix.List})
	if err != nil {
		return nil, err
	}
	return &http.Client{Jar: jar}, nil
}

这里的分界也解释了为什么不建议简单写成 cookiejar.New(nil)。官方文档明确说 nil 对测试有用，但不安全；它会放宽不同注册域之间的 Cookie 设置范围。对于只验证请求流程的单元测试，可以短暂使用 nil，但测试辅助函数最好仍然保留显式的 testSuffixes，这样测试意图和域名边界都能被读懂。

常见误区与速查

一句话记忆：PublicSuffixList 决定 Cookie 域的“不能越过哪里”，测试替身只负责把内网域名的边界说清楚；它不应该成为线上安全策略。

相关问题

• 为什么不用 localhost 共享子域 Cookie？因为 localhost 不是多级测试域名，无法自然表达 api.dev.test 与 web.dev.test 的共享边界。
• PublicSuffixList 实现能不能修改 map？可以自行设计，但必须保证并发调用安全；更适合在构造后保持不可变。
• 这个设置会保存 Cookie 到磁盘吗？不会，标准 cookiejar.Jar 是内存实现，持久化需要另外设计。