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 客户端请求处理器。这样既经过真实响应提交路径,也不依赖固定端口。

go
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)))
}

预期输出:

text
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 与对外字段结构保持稳定。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

构造 JSON 成功响应

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通