Go http.ParseSetCookie 解析失败时怎样定位非法属性

我在把旧的 Cookie 解析代码迁到 net/http 时，最容易误判的一点是：http.ParseSetCookie 的“解析失败”不等于“某个属性不认识”。它对首段 name=value 的语法错误返回 error；而后续属性即使格式不完整或值无法解释，也可能保留在 Cookie.Unparsed，同时返回一个可继续检查的 Cookie。

官方文档：https://pkg.go.dev/net/http#ParseSetCookie

因此排查顺序应该是：先看 err 是否非 nil，再看 Unparsed，最后结合 Raw 和已识别字段还原是哪一段出了问题。本文只讨论 Go 的解析结果，不讨论浏览器是否发送 Cookie。

先把“解析失败”分成两类

Set-Cookie 可以先抽象成一段核心值和若干分号属性：

session=abc123; Path=/; Max-Age=3600; Secure

核心段决定能否创建 Cookie。空字符串、没有等号、名称不是合法 token，或者首段值包含不允许的字符，都会让函数返回错误。这类问题应该直接记录原始行并修复输入，不能把返回的 Cookie 当成成功结果。

属性段则是另一条路径。能够识别的 Path、Domain、Max-Age、Expires、SameSite、Secure、HttpOnly 和 Partitioned 会写入对应字段；无法解析或不属于已处理属性的片段会进入 Unparsed。这不是“没有问题”，而是“核心 Cookie 已生成，但属性需要单独处理”。

从错误到 Unparsed 的定位表

迁移旧代码时，不要只打印一句“cookie parse failed”。可以按下面的边界建立日志字段：

这里还有一个容易漏掉的细节：Raw 保存传入的整行，RawExpires 保存 Expires 的原文。即使属性最终没有进入结构化字段，也不要只输出结构化后的 Cookie，因为那会丢掉定位所需的原始片段。

从返回对象反推是哪一段出了问题

下面的写法把真正的语法错误和属性级异常分开记录。代码中的 Unparsed 是兼容性信号，不应被误写成函数失败：

package main

import (
	"fmt"
	"net/http"
)

func inspectSetCookie(line string) {
	// 先处理首段语法错误；err 非 nil 时不要使用不完整的 Cookie。
	c, err := http.ParseSetCookie(line)
	if err != nil {
		fmt.Printf("cookie 首段无效: err=%v raw=%q\n", err, line)
		return
	}

	// 核心 Cookie 已经生成，但属性仍可能需要人工或业务策略处理。
	fmt.Printf("name=%q value=%q raw=%q\n", c.Name, c.Value, c.Raw)
	if len(c.Unparsed) > 0 {
		// 保留原始属性，便于定位上游格式和兼容性差异。
		fmt.Printf("未识别或非法属性: %q\n", c.Unparsed)
	}
	if !c.Expires.IsZero() {
		// 只有成功转换的 Expires 才会进入结构化时间字段。
		fmt.Printf("expires=%s\n", c.Expires.UTC().Format("2006-01-02T15:04:05Z07:00"))
	}
}

func main() {
	// 这条输入的核心段有效，属性问题应从 Unparsed 观察。
	inspectSetCookie("sid=abc; Max-Age=oops; Path=/")
	// 这条输入缺少首段等号，应从 error 分支定位。
	inspectSetCookie("sid-abc; Path=/")
}

实际接入日志时，建议同时带上响应来源、请求标识和 Raw，但不要把 Cookie 值无条件写入普通业务日志。本文只关心结构判断，敏感值的脱敏策略仍应由项目自己的日志规范决定。

把旧的“只看 err”迁移成回归清单

旧代码常见的写法是 if err != nil { return }，然后把所有异常都归为“Cookie 不能用”。迁移后至少要补四组用例：

1. 首段为空、缺少等号、名称非法、值非法：期望 err != nil。
2. 合法核心段加未知属性：期望 err == nil，并在 Unparsed 中保留属性原文。
3. 合法核心段加异常 Max-Age 或日期：检查结构化字段没有被误填，同时保留可诊断信息。
4. 合法核心段加大小写不同的已知属性：确认识别结果符合当前 Go 实现，再决定是否接受跨版本差异。

最终可以把结果压缩成一句规则：error 决定首段是否能构造 Cookie，Unparsed 决定属性是否需要后续处理。只要日志同时保存 Raw、Unparsed 和必要的结构化字段，定位非法属性就不必靠猜。

常见问题

Unparsed 非空时能不能继续使用 Cookie？

可以把它视为“核心字段已解析，但属性存在兼容性信号”，是否继续使用应由业务安全边界决定。不要把它等同于浏览器已经接受。

为什么解析成功但 Expires 是零值？

先看 RawExpires 和 Unparsed。原始日期可能存在，但没有被当前解析路径转换为有效时间。