Go http.Cookie.String 怎样检查 Cookie 的发送格式

我在排查 Cookie 头部时，最容易误判的一点是：结构体里“填过字段”，不代表这些字段一定会原样出现在最终文本里。http.Cookie.String()负责把 Cookie 序列化成请求头里的 Cookie 值，或者响应头里的 Set-Cookie 值；它遇到非法 Name 会直接返回空字符串，遇到非法 Domain 会丢弃 Domain 属性，而 Value 和 Path 中的非法字节会被清理。发送前如果还要明确知道哪里不合法，应先调用 Valid()。

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

先分清 String 面向哪一种头部

Cookie 的用途决定了你应该关注哪部分输出。客户端请求通常只携带 Name=Value，服务端响应则可以在同一文本后追加 Path、Domain、Max-Age、HttpOnly、Secure、SameSite 和 Partitioned 等属性。

package main

import (
    "fmt"
    "net/http"
)

func main() {
    c := &http.Cookie{
        Name:     "session",
        Value:    "abc123",
        Path:     "/",
        HttpOnly: true,
        Secure:   true,
        SameSite: http.SameSiteLaxMode,
    }

    // String 只负责把当前字段组合成头部文本，不会替你发送响应。
    fmt.Println(c.String())
}

这个对象的基础部分是 session=abc123，其余字段会被追加为属性。调用 w.Header().Add("Set-Cookie", c.String()) 前，最好先把生成文本记录到调试日志中；这样可以判断问题出在字段值、序列化还是后续的浏览器策略。

String 会把哪些字段写进头部

String()先写入 Name 和等号，再处理 Value；之后按字段是否有效或是否启用，决定是否追加属性。默认值不会自动变成文本，例如 SameSite 的默认模式不会输出 SameSite 属性，MaxAge 为 0 也不会输出 Max-Age。

因此，“字段没有出现在文本里”不一定是丢数据。先看它是否处于会输出的状态：例如 MaxAge=0 是未指定，而不是立即删除；MaxAge 才会序列化为 Max-Age=0。

为什么最终文本会少字段

这里要把三种现象分开。Name 非法或 Cookie 指针为 nil 时，String()返回空字符串；Domain 含非法字符时，Domain 属性会被丢弃，Cookie 可能退化为 host-only 形态；Value 和 Path 的非法字节则会被过滤，并留下清理后的文本。后两种情况都可能让你看到“输出还能用，但和结构体不一样”。

func cookieHeader(c *http.Cookie) (string, error) {
    // Valid 先报告 Name、Value、Path、Domain 等硬错误。
    if err := c.Valid(); err != nil {
        return "", err
    }

    // String 再给出真正准备写入头部的序列化文本。
    wire := c.String()
    if wire == "" {
        return "", fmt.Errorf("cookie serializes to empty text")
    }
    return wire, nil
}

这段组合的价值在于职责清楚：Valid()告诉你对象是否违反字段约束，String()告诉你最终文本是什么。不要只用空字符串判断所有错误，也不要只看 Valid() 就假设文本会保留每个输入字节。

发送前的检查清单

实际接入响应头时，我会按下面的顺序看，而不是先改浏览器端代码：

1. 确认 Name 没有空格、分号或控制字符；这是得到空字符串的首要原因。
2. 确认 Value 和 Path 没有被清理后才发现长度或签名不一致。
3. 确认 Domain 是合法域名或 IP；如果 Domain 属性消失，先看服务端日志。
4. 确认 MaxAge 的正负语义，尤其不要把 0 当成删除。
5. 确认 Partitioned 与 Secure 的组合，再把 String() 的返回值写入 Set-Cookie。

如果目标是请求头而不是响应头，就只保留客户端需要发送的键值，不要把 Path、HttpOnly 之类服务端属性拼进 Cookie 请求头。最后记录实际序列化文本，通常比打印整个结构体更容易定位“为什么少了一个字段”。

相关问题

Cookie.String 为什么返回空字符串？

常见原因是 Cookie 指针为 nil，或者 Name 不是合法 token。先检查 Name，再决定是否继续写入响应头。

Domain 不合法时 String 会返回 error 吗？

不会由 String 返回 error；它会放弃 Domain 属性并记录日志。若希望在发送前阻断，应调用 Valid。

MaxAge 设置为 0 为什么没有 Max-Age？

在 Cookie 结构体语义中，MaxAge=0 表示不指定 Max-Age；小于 0 才序列化为 Max-Age=0，用于立即删除语义。