Go HTTP Header管理核心在于时机:客户端头必须在client.Do()前设置,服务端头必须在WriteHeader()或Write()前设置,否则无效;标准头由Go自动处理,自定义头建议用X-前缀。
Go 的 HTTP Header 管理分客户端(请求)和服务端(响应)两套逻辑,不能混用;最常出问题的不是“怎么设”,而是“什么时候设”和“谁有权改”。
req.Header.Set() 必须在 client.Do() 之前调用
你只能在 http.Client.Do() 执行前修改 req.Header,之后任何改动都无效——Go 不会报错,但头根本不会发出去。
- 错误写法:
resp, _ := client.Do(req)之后再req.Header.Set("X-Trace", "abc")→ 完全没用 - 正确顺序:先
req.Header.Set(),再client.Do(req) - 标准头如
Host、Content-Length由 Go 自动计算并覆盖,手动设会被忽略,甚至触发 panic(比如设了错误的Content-Length) - 需要多值(如多个
Accept)用req.Header.Add(),单值(如Authorization)优先用Set()
w.Header().Set() 必须在 WriteHeader() 或 Write() 之前调用
服务端写响应头时,w.Header().Set() 必须出现在 w.WriteHeader() 或第一次 w.Write() 之前,否则头被锁定,后续设置全部丢弃。
- 典型错误:
w.WriteHeader(200)放在w.Header().Set("Content-Type", "application/json")前 →Content-Type不生效,Go 默认用text/plain - 更隐蔽的坑:
fmt.Fprintf(w, "...")或w.Write([]byte{})会隐式调用WriteHeader(200),所以只要一写响应体,头就再也改不了 - Cookie 不要用
w.Header().Set("Set-Cookie", ...),改用http.SetCookie(w, &http.Cookie{...}),它会自动编码、处理HttpOnly和过期时间
读取 Header 时注意大小写与空值
Go 内部会把所有 header key 标准化(user-agent → User-Agent),所以 r.Header.Get("user-agent") 和 r.Header.Get("User-Agent") 效果一样,但建议统一用规范写法。