Go 自定义 CookieJar 需要满足哪些接口行为

如果你要给 http.Client 换一个自定义 Cookie 存储，核心不是实现一个“保存 Cookie 的 map”，而是满足 http.CookieJar 的两个方法：SetCookies 接收响应里的 Cookie，Cookies 为即将发送的请求返回 Cookie。这个实现还必须能被多个 goroutine 并发调用。

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

测试替身可以只做有限的主机匹配；生产实现则必须补齐域名、路径、Secure、过期时间和并发保护等规则，否则“能保存”不等于“会正确发送”。

先把两个方法的职责分开

SetCookies 的输入来自服务器响应，参数里的 URL 表示这些 Cookie 的来源；Cookies 的输入来自客户端请求，返回值决定本次请求要带哪些 Cookie。两者方向相反，却共享同一份内部状态。

因此，自定义类型至少应该让接口断言在编译期失败得更早：

package main

import "net/http"

// memoryJar 是一个示例实现；生产代码还要补齐完整 Cookie 规则。
type memoryJar struct{}

// 编译期确认两个方法的签名没有写错。
var _ http.CookieJar = (*memoryJar)(nil)

用锁保护状态，用副本隔离调用方

下面的实现只按主机保存 Cookie，适合测试或演示接口边界。锁解决的是并发读写问题；复制 Cookie 解决的是调用方拿到返回切片后继续修改，不能反向破坏 Jar 内部状态。

package main

import (
    "net/http"
    "net/url"
    "sync"
)

type memoryJar struct {
    mu      sync.RWMutex
    cookies map[string][]*http.Cookie
}

func newMemoryJar() *memoryJar {
    // 用主机名作为演示键；真实实现通常还要考虑 Domain 和 Path。
    return &memoryJar{cookies: make(map[string][]*http.Cookie)}
}

func cloneCookie(in *http.Cookie) *http.Cookie {
    // 复制结构体，避免外部继续修改内部保存的指针。
    if in == nil {
        return nil
    }
    out := *in
    return &out
}

func hostKey(u *url.URL) string {
    // URL 为空或主机为空时不保存，避免产生无法匹配的全局状态。
    if u == nil || u.Hostname() == "" {
        return ""
    }
    return u.Hostname()
}

func (j *memoryJar) SetCookies(u *url.URL, cookies []*http.Cookie) {
    key := hostKey(u)
    if key == "" {
        return
    }
    j.mu.Lock()
    defer j.mu.Unlock() // 统一释放写锁，避免中途返回遗漏解锁。
    for _, cookie := range cookies {
        if cookie == nil || cookie.Name == "" {
            continue
        }
        j.cookies[key] = append(j.cookies[key], cloneCookie(cookie))
    }
}

func (j *memoryJar) Cookies(u *url.URL) []*http.Cookie {
    key := hostKey(u)
    if key == "" {
        return nil
    }
    j.mu.RLock()
    defer j.mu.RUnlock() // 读取切片期间保持内部状态稳定。
    result := make([]*http.Cookie, 0, len(j.cookies[key]))
    for _, cookie := range j.cookies[key] {
        result = append(result, cloneCookie(cookie))
    }
    return result
}

这段代码刻意没有把它包装成完整生产级 Cookie 策略：同名 Cookie 的替换、路径优先级、过期清理、Secure 限制和公共后缀判断，都需要明确规则后再实现。示例的价值在于把接口方向、锁的范围和对象复制讲清楚。

接入 Client 时只放一个 Jar 边界

配置方式很短，但要注意 Jar 是 Client 的共享状态。一个客户端可以复用一个 Jar；如果不同登录会话必须隔离，就为每个会话创建独立的 Jar，不要让多个 Client 意外共用一个可变 map。

jar := newMemoryJar()
client := &http.Client{Jar: jar}

// Client 在收到响应后通过 SetCookies 写入状态，发起后续请求前通过 Cookies 读取状态。
resp, err := client.Get("https://example.com/account")
if err != nil {
    return err // 网络错误直接交给调用方处理。
}
defer resp.Body.Close() // 响应体仍需由调用方负责关闭。

不要把 CookieJar 和服务端的 http.SetCookie 混为一谈：前者是客户端保存与选择 Cookie 的接口，后者是服务端生成响应头的辅助函数。

什么时候不该自己实现

如果目标只是让 HTTP 客户端按标准规则维护 Cookie，优先使用 net/http/cookiejar 提供的实现。自定义 Jar 更适合测试替身、审计记录、会话隔离或明确的内存策略。决定自己实现前，至少列出以下清单：

结论

自定义 CookieJar 的最低契约是两个正确签名的方法、可并发使用的内部状态，以及不泄漏可变对象的返回边界。若只是验证客户端流程，用简化实现即可；一旦进入真实跨域、HTTPS 或长期会话场景，就应优先采用标准 cookiejar，或逐项补齐 Cookie 规范，而不是只给 map 加一把锁。

相关问题

为什么有了 CookieJar 还要复用同一个 Client？因为 Jar 是 Client 的字段；每次新建 Client 都可能丢失原来的客户端状态。

自定义 Jar 只加互斥锁就够了吗？不够。锁只解决并发访问，不能自动实现域名、路径、Secure 和过期等 Cookie 选择规则。