当前位置：首页 > 文章列表 > Golang > Go问答 > Go http.Cookie.String 怎样检查 Cookie 的发送格式

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

来源：17golang原创 2026-10-25 06:29:18 0浏览收藏

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

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

要点速览

只有 Name 和 Value 时，String 形成适合 Cookie 请求头的键值；补充 Path、Domain、Max-Age 等属性后，形态更接近 Set-Cookie。
String 是序列化器，不是完整错误报告器；空字符串、被清理的字节和被丢弃的 Domain 要分别判断。
需要把问题挡在响应头之前时，用 Valid 返回错误，再用 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()) 前，最好先把生成文本记录到调试日志中；这样可以判断问题出在字段值、序列化还是后续的浏览器策略。

Go http.Cookie 字段与 Cookie 或 Set-Cookie 序列化文本的静态关系说明图 — 图1：Cookie 字段序列化说明图，展示基础键值与可选属性在头部文本中的静态关系。

String 会把哪些字段写进头部

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

字段	String 的表现	排查重点
Name、Value	组成基础键值	Name 必须是合法 token
Path、Domain	有值时追加属性	Domain 非法时会被丢弃
MaxAge	大于 0 输出秒数，小于 0 输出 Max-Age=0	0 表示不写该属性
Secure、HttpOnly	为 true 时追加无值标记	不要把它们误当成 Value 的一部分
SameSite、Partitioned	按枚举或布尔值追加	Partitioned 还要满足 Secure 约束

因此，“字段没有出现在文本里”不一定是丢数据。先看它是否处于会输出的状态：例如 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() 就假设文本会保留每个输入字节。