Cookie只能存字符串,JSON对象必须先序列化:Echo中需用json.Marshal()转字符串,再url.QueryEscape()编码后通过c.SetCookie()写入;读取时先url.QueryUnescape()再json.Unmarshal(),且单个Cookie不宜超过4KB。

Cookie只能存字符串,JSON对象必须先序列化
Echo 框架本身不提供直接存结构体到 Cookie 的能力,c.SetCookie() 只接受 *http.Cookie,而它的 Value 字段是 string 类型。所以你不能把 map[string]interface{} 或自定义 struct 直接塞进去——会 panic 或静默截断。
正确路径是:先用 json.Marshal() 转成 JSON 字符串,再 URL 编码(防止特殊字符破坏 Cookie 格式),最后设值。反向读取时,要先解码再 json.Unmarshal()。
- 不编码直接存 JSON 字符串,遇到
{ "name": "张三", "role": "admin" }里的空格、中文、引号会触发http.SetCookie内部解析失败,浏览器可能丢弃整个 Cookie - 别用
base64.StdEncoding.EncodeToString()替代 URL 编码——它生成的+和/在 Cookie 中会被误解析为空格或路径分隔符 - 推荐用
url.QueryEscape()编码,它专为 HTTP 上下文设计,兼容性最稳
怎么用 echo.Context 安全写入带 JSON 内容的 Cookie
注意:Echo 的 c.SetCookie() 是对 http.SetCookie() 的封装,它不自动处理编码;你得自己包一层。
示例写法:
exa-js 是 Exa 官方 JavaScript 软件开发工具包,Exa 是一个为 AI 工作流构建的网络搜索 API。它为代理提供了一种具体的方式来搜索网络、检索页面内容,并从代码中生成有来源的答案,而不是手动拼接原始 HTTP 调用。
import (
"encoding/json"
"net/url"
"net/http"
)
type UserInfo struct {
ID int `json:"id"`
Name string `json:"name"`
Role string `json:"role"`
}
func setJSONCookie(c echo.Context, name string, value interface{}) error {
b, err := json.Marshal(value)
if err != nil {
return err
}
encoded := url.QueryEscape(string(b))
cookie := &http.Cookie{
Name: name,
Value: encoded,
Path: "/",
MaxAge: 3600,
HttpOnly: true,
Secure: c.Request().TLS != nil, // 生产环境应强制 true
SameSite: http.SameSiteLaxMode,
}
c.SetCookie(cookie)
return nil
}
// 使用
err := setJSONCookie(c, "user", UserInfo{ID: 123, Name: "Alice", Role: "user"})
if err != nil {
return err
}
-
MaxAge建议显式设置,不依赖Expires(部分旧客户端对 RFC 时间格式支持差) -
HttpOnly: true必须开启,否则前端 JS 可读取并泄露敏感字段 -
Secure判断不能只看域名,要检查c.Request().TLS != nil,避免本地开发时硬编码出错
读取时如何避免 json.Unmarshal 失败或 panic
从 c.Cookie("user") 拿到的是 *http.Cookie,它的 Value 是原始字符串,必须先 url.QueryUnescape(),再 json.Unmarshal()。漏掉任一环节都会导致解析失败或静默空值。
常见错误现象:json: cannot unmarshal string into Go value of type main.UserInfo,本质是 Value 还带着 %7B%22id%22%3A123%7D 这种编码没解。
- 始终检查
c.Cookie(name)返回是否为nil,空 Cookie 不该继续解析 - 用
json.Unmarshal([]byte(raw), &target),不要传raw字符串本身(类型不匹配) - 建议封装读取函数,统一处理 decode + unmarshal 错误,并返回明确的 error 类型(比如
ErrCookieInvalid),方便上层判断是否需重定向登录
为什么不能把大 JSON 对象往 Cookie 里塞
Cookie 单个值上限约 4KB,但实际安全阈值更低——HTTP 头总大小通常被服务器限制在 8–16KB,多个 Cookie 累加很容易超限。Nginx 默认 large_client_header_buffers 是 8KB,Apache 也有类似限制。
更关键的是:每次请求,浏览器都会把所有同域 Cookie 自动附在 Cookie: 请求头里。一个 3KB 的用户信息 Cookie,意味着每秒 1000 QPS 就多发 3MB 带宽,且无法压缩。
- 只存必要字段:比如
{ "id": 123, "role": "admin" },别塞完整用户表记录或 token 原文 - 敏感字段如
password、token绝对禁止明文存 Cookie;应使用短期有效的加密 session ID 配合后端查库 - 如果真需要存较多结构化数据,改用
localStorage+ 后端接口校验,或用 short-lived JWT 存进HttpOnlyCookie(但需验证签名和过期)

















