在 Go 中如何编码/解码 JSON？

Question

在 Go 中如何编码/解码 JSON？

Accepted Answer

Go 的标准库 **`encoding/json`** 包处理 JSON 序列化（marshaling）和反序列化（unmarshaling），在 Go 结构体和 JSON 之间映射。**结构体标签**控制字段命名，这是大多数 Go web API 的基础。

## Marshaling: Go struct → JSON

```go
type User struct {
    Name    string `json:"name"`              // tag maps the field to a JSON key
    Email   string `json:"email"`
    Age     int    `json:"age,omitempty"`     // omitempty → skip if zero/empty
    private string                             // unexported → NOT serialized (lowercase)
}

u := User{Name: "Ann", Email: "ann@x.com", Age: 30}
data, err := json.Marshal(u)
fmt.Println(string(data))   // {"name":"Ann","email":"ann@x.com","age":30}
```

`json.Marshal` 将结构体转换为 JSON 字节。**只有导出的（大写）字段被序列化** — 未导出字段被跳过。

## 结构体标签的作用

```go
type Product struct {
    ID    int    `json:"id"`                  // → "id"
    Name  string `json:"product_name"`        // → "product_name" (rename)
    Price float64 `json:"price,omitempty"`     // omit if 0
    Notes string `json:"-"`                    // "-" → NEVER serialize this field
}
```

没有标签的情况下，JSON 键默认为完全相同的（大写）字段名。标签让你控制 JSON 键名、省略空值（`omitempty`）和完全排除字段（`-`） — 这对于匹配 API 约定（例如 snake_case JSON）至关重要。

## Unmarshaling: JSON → Go struct

```go
jsonData := []byte(`{"name":"Bob","email":"bob@x.com","age":25}`)

var user User
err := json.Unmarshal(jsonData, &user)   // pass a POINTER to populate it
if err != nil { log.Fatal(err) }
fmt.Println(user.Name)   // "Bob"
```

`json.Unmarshal` 将 JSON 解析为结构体 — 你必须传递一个**指针**以便它可以填充结构体。字段通过标签/名称匹配（不区分大小写）。

## 处理未知/动态 JSON

```go
// when the structure is unknown, unmarshal into a map or interface{}
var result map[string]interface{}
json.Unmarshal(data, &result)
name := result["name"].(string)        // type-assert the value (JSON numbers → float64!)
```

## 使用 Encoder/Decoder 进行流式处理（用于 I/O）

```go
// encode directly to an io.Writer (e.g. an HTTP response) — efficient, no intermediate buffer
json.NewEncoder(w).Encode(user)

// decode directly from an io.Reader (e.g. an HTTP request body)
json.NewDecoder(r.Body).Decode(&user)
```

对于 web 服务器，`Encoder`/`Decoder` 直接与流（请求/响应正文）配合工作 — 这是处理程序中的常见模式。

## 为什么这很重要

JSON 编码/解码对于几乎所有 Go web 开发都是基础性的 — REST API、微服务和配置都依赖于 Go 结构体和 JSON 之间的转换。

`encoding/json` 包（标准库，无依赖）是标准工具，深入理解它是必要的日常知识：marshaling/unmarshaling 如何工作、**只有导出字段被序列化**的关键规则，以及特别是**结构体标签**（使用 `json:"..."` 控制 JSON 键名、使用 `omitempty` 跳过空值、使用 `-` 排除）这对于匹配现实世界的 API 约定（如 snake_case）是必需的。

了解如何向 `Unmarshal` 传递指针、通过 maps/`interface{}` 处理动态 JSON（注意 JSON 数字解码为 `float64`）以及为 HTTP 正文使用流式 `Encoder`/`Decoder`，涵盖了构建 API 的实际需求。

这是 Go 后端工作中一个持续的、实际的部分。