Go http.Cookie Unparsed 怎样保留无法解析的属性

Go 解析 Set-Cookie 时，不能映射到 http.Cookie 已知字段的属性，会以原始片段放进 Cookie.Unparsed；如果整行违反语法，则通过 error 返回。也就是说，未知属性不等于解析失败，但它也不会自动变成一个可以被业务安全使用的结构化字段。

官方文档入口：https://pkg.go.dev/net/http#Cookie。本文只讨论 ParseSetCookie、Unparsed 和记录边界，不讨论浏览器是否采纳某个自定义属性。

先区分解析错误与未知属性

排查现场通常是：上游在响应头里增加了一个标准库尚未映射的属性，程序却把“没有对应字段”误判成“Cookie 解析失败”。判断顺序应是先看 err，再看返回对象的 Unparsed。前者说明语法或输入有问题，后者表示解析器保留了未解释的属性文本。

package main

import (
    "fmt"
    "net/http"
)

func main() {
    // 这个示例只展示 Set-Cookie 的解析对象，不发送网络请求。
    line := "session=abc123; Path=/; Priority=High; VendorFlag"
    cookie, err := http.ParseSetCookie(line)
    if err != nil {
        // 语法错误要停止当前解析，不能把半成品交给业务层。
        fmt.Println("parse error:", err)
        return
    }

    // Unparsed 保存未被 Cookie 已知字段吸收的原始属性片段。
    fmt.Println("name:", cookie.Name)
    fmt.Println("path:", cookie.Path)
    fmt.Println("unparsed:", cookie.Unparsed)
}

按这组输入，读者应关注的预期关系是：session 和 Path 进入已知字段，Priority=High 与 VendorFlag 留在 Unparsed。这里的文字是帮助理解代码的预期观察，不是本机运行回执。

读取 Unparsed 时要保留它的原始语义

Unparsed 的元素是原始属性值对文本，不是已经完成校验的业务参数。遇到 Priority=High，程序可以把它记录下来，交给针对该属性的兼容层；但不要直接把所有字符串当成可信配置，更不要用字符串包含判断代替属性名和值的解析策略。

如果业务只需要观察兼容情况，可以复制一份切片并记录属性名；如果业务必须解释它，则应为该属性写清楚自己的格式、允许值和冲突策略。这样即使 Go 标准库后续增加对应字段，兼容层也能通过版本策略调整，而不是散落在日志字符串里。

func collectUnknown(cookie *http.Cookie) []string {
    // 复制切片，避免后续代码修改 Cookie.Unparsed 时影响记录快照。
    unknown := append([]string(nil), cookie.Unparsed...)
    for _, raw := range unknown {
        // 这里只做观测；不要在没有协议约定时擅自解释 raw。
        fmt.Println("unknown cookie attribute:", raw)
    }
    return unknown
}

这里的返回值适合交给结构化日志、指标标签白名单或兼容记录。若属性内容可能来自不可信上游，记录前仍要遵守日志脱敏和长度限制；Unparsed 只是解析器给出的文本，不是安全证明。

不要把 Cookie.String 当成未知属性回写器

一个常见误区是：解析后调用 cookie.String()，再期待原来的未知属性自动出现在新的 Set-Cookie 中。String 面向已知 Cookie 字段的序列化；Raw、Unparsed 等解析痕迹不能被当作完整的回写契约。

如果代理或网关必须保留上游原始头，最稳妥的办法是同时保存输入行，并把解析出的结构化字段与原始输入建立关联。若只是为了向下游重新设置 Cookie，则应明确哪些属性由本服务支持，再用结构化字段生成新的头，不要把未知文本无条件拼接到输出中。

请求侧和响应侧不要混用解析入口

Set-Cookie 是响应头，使用 http.ParseSetCookie；请求头里的 Cookie 是多个简单的名称和值，使用 http.ParseCookie。把一整行 Set-Cookie 交给请求侧解析器，会让属性语义和错误判断混在一起。

落地时可以按四步处理：先保存必要的原始头，再调用对应解析函数；检查 err 并区分拒绝与兼容；对 Unparsed 建立有限的白名单记录；最后只用明确支持的字段生成下游 Cookie。这样既能发现上游协议变化，也不会因为一个未知属性就丢掉整枚 Cookie。

Unparsed 为空是不是说明没有未知属性？

通常可以这样理解，但它只表示解析结果中没有被放入该字段的属性，不代表上游一定没有扩展语义。仍应结合输入协议和日志策略判断。

解析成功后能不能直接把 Unparsed 拼回响应头？

不建议无条件拼接。先确认属性名和值的协议、输出位置和信任边界；需要完整保真时保留原始输入，需要重建时只输出业务明确支持的字段。

自定义属性最终要不要变成结构体字段？

当属性已经成为稳定协议的一部分，并且需要校验、比较或参与业务决策时，可以在兼容层中定义结构化表示；在此之前，保留原文并记录版本来源更稳妥。