Go cookiejar.Options 怎么接入公共后缀判断

Go 的 net/http/cookiejar 能为 http.Client 自动保存和发送 Cookie，但面向公网时，不应只写 cookiejar.New(nil)。更稳妥的做法是给 cookiejar.Options.PublicSuffixList 传入 publicsuffix.List，让 CookieJar 知道 co.uk、com.au 等公共后缀不能被普通站点当成 Cookie 作用域。标准库文档位于 https://pkg.go.dev/net/http/cookiejar，公共后缀实现位于 https://pkg.go.dev/golang.org/x/net/publicsuffix。

背景：默认 CookieJar 为什么还不够

cookiejar.New 接收一个 *cookiejar.Options。传入 nil 与传入零值 Options 等价，代码能正常运行，却没有可用的公共后缀表。此时 CookieJar 无法可靠区分“同一注册站点的子域”和“公共注册边界上的兄弟站点”。

jar, err := cookiejar.New(nil)
if err != nil {
    panic(err)
}

// 这段代码适合受控测试，不应直接作为公网客户端的安全默认值。
client := &http.Client{Jar: jar}

官方文档给出的风险很具体：当后缀表为 nil 时，foo.co.uk 可能为 bar.co.uk 设置 Cookie。两者只是共享公共后缀 co.uk，并不是同一个可注册站点。若客户端接受这种过宽 Domain，就可能把会话数据带到无关站点。

新规则：把 publicsuffix.List 交给 Options

Go 标准库只定义 cookiejar.PublicSuffixList 接口，官方维护的现成实现位于 golang.org/x/net/publicsuffix。先把依赖加入模块：

# 添加 Go 官方 x/net 模块中的公共后缀实现
go get golang.org/x/net/publicsuffix

创建 Jar 时，把包级变量 publicsuffix.List 放进 Options。它已经实现 cookiejar.PublicSuffixList，不需要额外适配器。

package main

import (
    "fmt"
    "net/http"
    "net/http/cookiejar"
    "net/url"

    "golang.org/x/net/publicsuffix"
)

func main() {
    // 使用官方公共后缀快照约束 Cookie 的 Domain 范围。
    jar, err := cookiejar.New(&cookiejar.Options{
        PublicSuffixList: publicsuffix.List,
    })
    if err != nil {
        panic(err)
    }

    client := &http.Client{Jar: jar}
    target, err := url.Parse("https://shop.example.co.uk/")
    if err != nil {
        panic(err)
    }

    // 这里只演示 Jar 已经挂到 Client；不发起真实网络请求。
    jar.SetCookies(target, []*http.Cookie{{
        Name: "session", Value: "demo", Path: "/", Secure: true,
    }})
    fmt.Println(len(client.Jar.Cookies(target)))
}

这项配置只在创建 Jar 时注入一次。之后，无论 Cookie 来自 HTTP 响应还是通过 SetCookies 写入，Jar 都会在自己的域匹配规则中使用该后缀表。http.Client 仍只依赖通用的 http.CookieJar 接口。

公共后缀判断究竟挡住了什么

公共后缀是互联网用户可在其下直接注册名称的边界。以 co.uk 为例，它是公共后缀；example.co.uk 是多一个标签的 eTLD+1，通常才代表一个可注册站点。shop.example.co.uk 和 api.example.co.uk 可以属于同一站点，但 foo.co.uk 与 bar.co.uk 是两个独立注册域。

publicsuffix 包还提供 EffectiveTLDPlusOne，可把域名归一到 eTLD+1。但 CookieJar 接入时不需要手动调用它；直接传 publicsuffix.List 即可。自行先算 eTLD+1 再改 Cookie Domain，反而容易破坏主机专属 Cookie 与 RFC 匹配语义。

代码对比：测试配置与公网配置

因此，迁移通常只改 Jar 初始化，不必改请求代码。若项目已有 Cookie 持久化层，也要确认恢复 Cookie 时仍通过这个 Jar 写入，而不是绕过 Jar 直接拼接 Cookie 请求头。

兼容注意：自定义 PublicSuffixList 的约束

cookiejar.PublicSuffixList 只有两个方法：PublicSuffix(domain string) string 返回域名的公共后缀，String() string 返回后缀表来源描述。接口虽小，但实现必须可被多个 goroutine 并发安全调用，因为一个 Jar 可能同时服务多个请求。

type PublicSuffixList interface {
    // 返回 domain 对应的公共后缀。
    PublicSuffix(domain string) string
    // 返回后缀表来源或版本说明。
    String() string
}

不要用“永远返回空字符串”的实现当生产默认值。官方允许这种实现用于测试，但同时说明它不安全。对于企业内网的私有后缀，可以在经过域名治理后提供定制实现；一旦客户端也访问公网，仍应保留完整 PSL 语义，避免私有规则覆盖公共规则。

publicsuffix.List 使用编译进库的 Public Suffix List 快照，升级 golang.org/x/net 才会获得更新的数据。它不是运行时联网查询，因此部署稳定，但依赖版本也应纳入常规更新计划。

采用建议与检查清单

普通公网爬虫、API 客户端、登录机器人和自动化测试工具，只要会跨域保存 Cookie，就应采用 publicsuffix.List。完全封闭的测试可以使用 nil，但测试名称或注释应明确这是有意放宽边界，避免样例代码被复制到生产环境。

• Jar 是否通过 cookiejar.Options{PublicSuffixList: publicsuffix.List} 创建。
• 是否把同一个 Jar 挂到实际发请求的 http.Client。
• 是否避免手工拼接 Cookie 请求头绕过 Jar。
• 是否定期升级 golang.org/x/net 以更新 PSL 快照。
• 若使用自定义实现，是否覆盖并发安全、私有后缀与公网回退规则。

接入的核心只有一行，但它决定了 CookieJar 能否识别真实的站点注册边界。把 publicsuffix.List 作为公网客户端默认配置，再把 nil 限定在受控测试中，既符合官方示例，也能把跨注册域 Cookie 风险挡在 Jar 内部。

相关问题

PublicSuffixList 为 nil 会导致 cookiejar.New 报错吗？

不会。nil 是合法值，并与零值 Options 等价；问题在于缺少公共后缀隔离，而不是初始化失败。

还需要手动调用 EffectiveTLDPlusOne 吗？

不需要。CookieJar 只需要一个实现了 cookiejar.PublicSuffixList 的对象，直接传 publicsuffix.List 即可。

publicsuffix.List 会在运行时访问网络吗？

不会。官方包使用编译进库的 PSL 数据快照，更新数据依赖升级模块版本。