Go Request.CookiesNamed 与 Cookie 有什么区别

如果服务端只需要一个 Cookie 值，Request.Cookie 更直接；如果同一个名称可能出现多个 Cookie，或者你需要保留所有匹配项，就应该使用 Request.CookiesNamed。两者的关键区别不是名称写法，而是返回模型：Cookie 返回单个 *http.Cookie，未找到时返回 http.ErrNoCookie；CookiesNamed 返回同名 Cookie 切片，未找到时得到空切片。

一句话记忆：只取一个并明确判断缺失，用 r.Cookie(name)；必须保留同名项，用 r.CookiesNamed(name)。不要先调用单值 API 再猜测是不是还有第二个值。

先把两个返回模型放在一起看

这两个方法都从当前请求的 Cookie 头中查找名称，但返回值承担的责任不同。Cookie 适合业务已经确认“这个名称最多只看一个值”的场景；CookiesNamed 则把所有同名项交给调用方，调用方可以自行决定取第一个、拒绝重复，或合并后续逻辑。

因此，CookiesNamed 不是 Cookie 的“批量版语法糖”那么简单。它改变了调用方要承担的判断：你必须决定空切片是否代表“没有标签”、是否应该拒绝重复值，以及每个匹配项的值是否都满足业务要求。

同名 Cookie 才能看出差异

假设请求里带有两个名称相同的 tag Cookie。这样的输入不一定意味着服务器必须接受两个值，但它确实说明单值读取会丢失信息。下面的示例只构造请求对象并读取 Cookie，不依赖浏览器或外部服务。

package main

import (
	"fmt"
	"net/http"
)

func main() {
	// 用两个同名 Cookie 构造请求，模拟客户端同时携带多个 tag 值。
	req, err := http.NewRequest(http.MethodGet, "https://example.test/items", nil)
	if err != nil {
		panic(err)
	}
	req.AddCookie(&http.Cookie{Name: "tag", Value: "go"})
	req.AddCookie(&http.Cookie{Name: "tag", Value: "http"})

	// Cookie 只返回一个匹配项；它适合明确只需要单值的业务。
	one, err := req.Cookie("tag")
	if err != nil {
		panic(err)
	}

	// CookiesNamed 保留同名 Cookie，调用方才能看到完整集合。
	all := req.CookiesNamed("tag")
	fmt.Println(one.Value, len(all))
}

这里的重点不是把两个值拼成一个字符串，而是先决定业务是否允许重复名称。若 tag 只应出现一个，使用 Cookie 后还要配合请求约束或额外策略拒绝异常输入；若多个值有独立含义，就用 CookiesNamed 逐项读取。

单值身份标识和多值标签要分开选

可以把选择问题压缩成三个判断。第一，业务字段是否有明确的单值语义；第二，重复名称是否可能携带有效信息；第三，没找到时是否需要区别“没有”与“读取失败”。这三个问题比方法名更能决定调用方式。

• 单值身份标识：例如内部约定的 session_id，只接受一个值，使用 Cookie，并显式处理 http.ErrNoCookie。
• 同名标签或筛选项：例如多个 tag，使用 CookiesNamed，遍历切片并对每个值做业务判断。
• 不允许重复：即使先用 CookiesNamed 读取，也可以在切片长度大于一时拒绝请求；这比悄悄拿第一个更容易审计。
• 只想知道是否存在：仍然可以用 CookiesNamed 判断切片是否为空，但不要把空切片误解成读取错误。

把差异收进一个小型 HTTP 处理器

下面做一个小型处理器：session_id 走单值读取，tag 走同名读取；处理器只负责展示 API 选择，不负责建立登录会话，也不把 CookieJar 纳入本题。

package main

import (
	"fmt"
	"net/http"
)

func cookieSummary(w http.ResponseWriter, r *http.Request) {
	// session_id 的业务契约是单值；缺失时返回明确的客户端错误。
	session, err := r.Cookie("session_id")
	if err != nil {
		if err == http.ErrNoCookie {
			http.Error(w, "缺少 session_id Cookie", http.StatusUnauthorized)
			return
		}
		// 当前 API 的读取错误不应被当成业务值继续使用。
		http.Error(w, "读取 session_id 失败", http.StatusBadRequest)
		return
	}

	// tag 允许同名项，因此保留全部结果，不用单值 API 截断集合。
	tags := r.CookiesNamed("tag")
	fmt.Fprintf(w, "session=%s; tags=%d\n", session.Value, len(tags))
	for _, cookie := range tags {
		// 每个 Cookie 都独立检查，避免把重复值直接拼接进响应。
		if cookie.Value == "" {
			continue
		}
		fmt.Fprintf(w, "tag=%s\n", cookie.Value)
	}
}

这个结构有两个可读性收益：单值字段的缺失分支和多值字段的空集合分支不会混在一起；如果以后把“拒绝重复 session_id”加进来，只需要对相应的 CookiesNamed 结果增加约束，而不是改变所有读取代码。

空结果、未命中和版本问题怎么判断

1. Cookie 返回 http.ErrNoCookie：当前请求没有匹配名称，调用方应决定是匿名访问、补默认值还是返回错误。
2. CookiesNamed 返回空切片：这表示没有匹配项，不代表 API 调用失败；先判断长度，再进入遍历。
3. 同名值只看到一个：检查是否误用了 Cookie，以及业务是否在更早的层把 Cookie 头重写成单值。
4. 编译器提示方法不存在：Request.CookiesNamed 是较新的标准库 API，先确认项目使用的 Go 工具链版本，再决定升级或使用兼容实现。

func readTags(r *http.Request) []string {
	// 空切片表示没有同名 Cookie，保持返回值为空而不是制造默认标签。
	cookies := r.CookiesNamed("tag")
	tags := make([]string, 0, len(cookies))
	for _, cookie := range cookies {
		// 过滤空值只是本示例的业务规则，不改变 CookiesNamed 的返回语义。
		if cookie.Value != "" {
			tags = append(tags, cookie.Value)
		}
	}
	return tags
}

结论：先确定值的数量，再选 API

Request.Cookie 把读取结果表达成“一个对象或一个未命中错误”，适合单值契约；Request.CookiesNamed 把结果表达成“同名对象集合”，适合需要保留重复项或自行制定重复策略的场景。两者都不替你决定业务是否接受空值、重复值和异常值，这些判断应留在调用方。

常见问题

CookiesNamed 没找到 Cookie 时会返回错误吗？

它返回空切片，而不是像 Request.Cookie 那样返回 http.ErrNoCookie。如果业务只关心是否存在，可以用 len(r.CookiesNamed("name")) == 0 判断。

Cookie 找到多个同名值时该怎么办？

如果业务必须知道所有值，应改用 CookiesNamed；如果业务明确只接受一个值，则应在读取后增加重复检查或在请求策略层拒绝，而不是默认把第一个值当成唯一值。

CookiesNamed 和 CookieJar 是一回事吗？

不是。本文两个方法读取的是当前 Request 中已经到达服务端的 Cookie；CookieJar 负责客户端侧 Cookie 的保存与随请求发送，属于另一个问题边界。