Go / 系统课时
构造 JSON 成功响应
构造 JSON 成功响应
成功响应不仅要把 Go 值编码成 JSON,还要让状态码、Content-Type 和响应体按正确顺序提交。本节用绑定临时端口的真实 HTTP 服务构造 201 Created 响应,并从客户端侧验证完整响应契约。
学习目标
- 按正确顺序设置响应头、状态码和 JSON 正文
- 使用
json.Encoder直接向http.ResponseWriter写入对象 - 判断响应已经提交后哪些内容不能再修改
先确定提交顺序
http.ResponseWriter 的安全顺序是“设置 Header → 调用 WriteHeader → 写响应体”。如果没有显式调用 WriteHeader,第一次 Write 或 json.Encoder.Encode 会隐式提交 200 OK。
因此,创建资源要返回 201 Created 时,必须在编码正文之前调用 WriteHeader(http.StatusCreated)。同理,Content-Type 也必须在状态码提交前写入响应头。
构造并验证 201 JSON 响应
下面的完整程序在 127.0.0.1 上监听由操作系统分配的临时端口,再用标准 HTTP 客户端请求处理器。这样既经过真实响应提交路径,也不依赖固定端口。
package main
import (
"encoding/json"
"fmt"
"io"
"net"
"net/http"
"strings"
)
const jsonMediaType = "application/json; charset=utf-8"
type Item struct {
ID int `json:"id"`
Label string `json:"label"`
}
func createItem(w http.ResponseWriter, r *http.Request) {
item := Item{ID: 42, Label: "gopher"}
// 先准备响应头,再提交 201,避免正文写入后状态码被锁定为 200。
w.Header().Set("Content-Type", jsonMediaType)
w.WriteHeader(http.StatusCreated)
// 这里只编码普通字段;若此时写出失败,已提交的 201 也不能再改成 500。
if err := json.NewEncoder(w).Encode(item); err != nil {
return
}
}
func main() {
router := http.NewServeMux()
router.HandleFunc("/items", createItem)
listener, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
panic(err)
}
defer listener.Close()
server := &http.Server{Handler: router}
defer func() { _ = server.Close() }()
go func() {
_ = server.Serve(listener)
}()
resp, err := http.Post("http://"+listener.Addr().String()+"/items", "application/json", nil)
if err != nil {
panic(err)
}
defer func() { _ = resp.Body.Close() }()
body, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println("status:", resp.StatusCode)
fmt.Println("content-type:", resp.Header.Get("Content-Type"))
fmt.Println("body:", strings.TrimSpace(string(body)))
}预期输出:
status: 201
content-type: application/json; charset=utf-8
body: {"id":42,"label":"gopher"}实际监听端口由操作系统动态选择,可视为 <PORT>,但它不会影响上述三项验证结果。状态码、媒体类型和 JSON 正文共同构成这个创建接口的成功响应契约。
理解 Encoder 与隐式 200
json.NewEncoder(w).Encode(item) 会把编码结果直接写向响应流,并在 JSON 后追加换行。若前面省略 WriteHeader(http.StatusCreated),这次写入就会触发默认的 200 OK,此后再补写 201 已经太晚。
与先 json.Marshal 再 w.Write 相比,Encoder 少了一步显式构造完整字节切片的代码,适合直接生成 HTTP JSON 响应。对于普通结构体,两种方式都能正确编码,选择重点应放在响应提交顺序和错误处理上,而不是微小的性能差异。
在提交成功状态前处理可能失败的编码
示例中的 Item 只包含普通可编码字段,因此直接执行“Header → WriteHeader → Encode”即可。如果响应对象包含可能失败的自定义 MarshalJSON,则不能在提交 201 后再指望改成 500。
这类场景更稳妥的做法是先把对象编码到内存缓冲区;编码成功后再设置响应头、提交成功状态并写出字节。无论采用哪种方式,都应避免手工拼接 JSON,并让状态码、Content-Type 与对外字段结构保持稳定。