Go-12-序列化与 struct tag 深入

2026-08-21

字数统计: 1.9k字 | 阅读时长≈ 10分

Go-12-序列化与 struct tag 深入

本节目标：掌握 JSON / gob / msgpack / protobuf / YAML 等序列化方案，深入 struct tag 高级用法。

1. encoding/json 完整用法

1.1 基本类型

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email,omitempty"`
}

u := User{ID: 1, Name: "Alice", Email: "alice@example.com"}
data, _ := json.Marshal(u)
fmt.Println(string(data))
// {"id":1,"name":"Alice","email":"alice@example.com"}

1.2 struct tag 选项

type Config struct {
    Host     string `json:"host"`                  // 字段名
    Port     int    `json:"port,string"`           // 序列化为字符串
    Password string `json:"password,omitempty"`     // 空值省略
    Internal string `json:"-"`                     // 完全忽略
    Created  Time   `json:"created,omitzero"`      // 零值省略
    Tags     []string `json:"tags,omitempty"`      // nil/空切片省略
    Backup   string `json:"backup,string,omitempty"` // 多选项
}

选项	作用
`omitempty`	零值省略
`string`	数字/布尔序列化为字符串
`-`	完全忽略该字段
`,inline`	嵌入字段展开（Go 1.19+）

1.3 嵌入 struct

type Base struct {
    ID        int64     `json:"id"`
    CreatedAt time.Time `json:"created_at"`
}

type User struct {
    Base            // 嵌入（字段名 = 类型名）
    Name  string    `json:"name"`
    Email string    `json:"email"`
}

// 输出：{"id":0,"created_at":"...","name":"Alice","email":"..."}

改名嵌入：

type User struct {
    Base    `json:"base"`     // 嵌入字段改成 "base"
    Name    string `json:"name"`
}

用 omitempty 避免 ID=0 也输出：

type User struct {
    Base    `json:",inline"`  // 展开而不是嵌套
    Name    string `json:"name"`
    Email   string `json:"email,omitempty"`
}

1.4 自定义序列化

// 实现 json.Marshaler 接口
type IPAddr [4]byte

func (ip IPAddr) MarshalJSON() ([]byte, error) {
    return []byte(fmt.Sprintf(`"%d.%d.%d.%d"`, ip[0], ip[1], ip[2], ip[3])), nil
}

// 实现 json.Unmarshaler 接口
func (ip *IPAddr) UnmarshalJSON(data []byte) error {
    var s string
    if err := json.Unmarshal(data, &s); err != nil {
        return err
    }
    parts := strings.Split(s, ".")
    if len(parts) != 4 {
        return errors.New("invalid IP")
    }
    for i, p := range parts {
        n, _ := strconv.Atoi(p)
        (*ip)[i] = byte(n)
    }
    return nil
}

addr := IPAddr{127, 0, 0, 1}
data, _ := json.Marshal(addr)
fmt.Println(string(data))  // "127.0.0.1"

1.5 延迟解析（RawMessage）

有时 JSON 中某个字段结构不确定，先存起来后续解析：

type Event struct {
    Type    string          `json:"type"`
    Payload json.RawMessage `json:"payload"`
}

event := Event{Type: "user_created"}
event.Payload = json.RawMessage(`{"id":1,"name":"Alice"}`)

data, _ := json.Marshal(event)

// 后续再解析
var user User
json.Unmarshal(event.Payload, &user)

1.6 流式处理

// 大数组流式写
enc := json.NewEncoder(os.Stdout)
users := []User{{ID: 1, Name: "A"}, {ID: 2, Name: "B"}}
for _, u := range users {
    if err := enc.Encode(u); err != nil {
        log.Fatal(err)
    }
}

2. encoding/gob（Go 二进制）

gob 是 Go 专用的二进制序列化，比 JSON 快、紧凑，但只支持 Go 之间。

import "encoding/gob"

type User struct {
    ID   int
    Name string
}

// 编码到文件
f, _ := os.Create("user.gob")
defer f.Close()
enc := gob.NewEncoder(f)
enc.Encode(User{ID: 1, Name: "Alice"})

// 从文件解码
f, _ = os.Open("user.gob")
dec := gob.NewDecoder(f)
var u User
dec.Decode(&u)
fmt.Println(u)

优势：支持任意 Go 类型（函数、chan 除外），自动处理结构体演化。
劣势：跨语言不通（Java/Python 读不了）。

3. msgpack（推荐跨语言高性能场景）

需要 github.com/vmihailenco/msgpack/v5：

import "github.com/vmihailenco/msgpack/v5"

type User struct {
    ID   int    `msgpack:"id"`
    Name string `msgpack:"name"`
}

u := User{ID: 1, Name: "Alice"}
data, _ := msgpack.Marshal(u)
// 紧凑的二进制，比 JSON 小 30-50%

var u2 User
msgpack.Unmarshal(data, &u2)

msgpack 优势：

比 JSON 小、快
支持二进制、整数、浮点、字符串、数组、map
跨语言（Python、Java、JS 都有库）
适合 RPC、高性能存储

4. protobuf（gRPC 标配）

最适合微服务/跨语言 RPC：

// user.proto
syntax = "proto3";

package user;

message User {
    int64 id = 1;
    string name = 2;
    string email = 3;
    repeated string tags = 4;
}

1 2	# 编译生成 Go 代码 protoc --go_out=. --go_opt=paths=source_relative user.proto

import "google.golang.org/protobuf/proto"

u := &user.User{
    Id:    1,
    Name:  "Alice",
    Email: "alice@example.com",
    Tags:  []string{"admin", "user"},
}

data, _ := proto.Marshal(u)

var u2 user.User
proto.Unmarshal(data, &u2)

优势：

强类型、字段编号稳定（演化友好）
高性能（比 JSON 快 5-10x，比 msgpack 也快）
跨语言（gRPC 标准）

5. YAML

需要 gopkg.in/yaml.v3：

import "gopkg.in/yaml.v3"

type Config struct {
    Server ServerConfig `yaml:"server"`
}

type ServerConfig struct {
    Port int    `yaml:"port"`
    Host string `yaml:"host"`
}

cfg := Config{Server: ServerConfig{Port: 8080, Host: "0.0.0.0"}}
data, _ := yaml.Marshal(cfg)
fmt.Println(string(data))
// server:
//   host: 0.0.0.0
//   port: 8080

常用 YAML 库：

gopkg.in/yaml.v3：纯 Go 实现，主流选择
gopkg.in/yaml.v2：老版本

6. struct tag 高级技巧

6.1 多种序列化器共存

type User struct {
    ID   int    `json:"id" yaml:"id" msgpack:"id" bson:"_id"`
    Name string `json:"name" yaml:"name" msgpack:"name" bson:"name"`
}

6.2 自定义 tag 解析

// reflect 解析自定义 tag
type Field struct {
    Name string
    Validate string
}

type User struct {
    Email string `validate:"email"`
    Age   int    `validate:"min=0,max=150"`
}

func parseTag(s interface{}) []Field {
    t := reflect.TypeOf(s)
    fields := []Field{}
    for i := 0; i < t.NumField(); i++ {
        f := t.Field(i)
        fields = append(fields, Field{
            Name:     f.Name,
            Validate: f.Tag.Get("validate"),
        })
    }
    return fields
}

6.3 实现 validator（用 go-playground/validator）

import "github.com/go-playground/validator/v10"

type User struct {
    Name  string `validate:"required,min=2,max=50"`
    Email string `validate:"required,email"`
    Age   int    `validate:"gte=0,lte=150"`
    URL   string `validate:"omitempty,url"`
}

v := validator.New()
u := &User{Name: "A", Email: "bad", Age: 200, URL: "not a url"}
err := v.Struct(u)
// 验证失败返回详细错误

常用验证 tag：

required：必填
min=N, max=N：长度/数值范围
email、url、uuid、ipv4 等
oneof=red green blue：枚举
regexp=^pattern$：正则

7. 实战：HTTP API 统一响应格式

type Response struct {
    Code    int         `json:"code" example:"0"`
    Message string      `json:"message" example:"ok"`
    Data    interface{} `json:"data,omitempty"`
}

func writeJSON(w http.ResponseWriter, code int, msg string, data interface{}) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)  // HTTP 状态码总返回 200，业务码在 body
    json.NewEncoder(w).Encode(Response{
        Code:    code,
        Message: msg,
        Data:    data,
    })
}

// 用法
writeJSON(w, 0, "ok", user)
writeJSON(w, 1001, "user not found", nil)

8. 实战：自定义 JSON 字段顺序

Go 的 json.Marshal 按字段声明顺序输出，可以巧妙控制：

type User struct {
    ID        int    `json:"id"`
    Name      string `json:"name"`
    Email     string `json:"email"`
    CreatedAt string `json:"created_at"`
    UpdatedAt string `json:"updated_at"`
}

如果用 map[string]interface{} 字段顺序就乱了。

9. 性能对比

格式	体积	速度	跨语言	可读性
JSON	大	慢	✅	✅
gob	中	快	❌	❌
msgpack	小	快	✅	❌
protobuf	最小	最快	✅	❌
YAML	很大	最慢	✅	✅

选择建议：

配置 / 文档：YAML
HTTP API / 调试：JSON
Go 内部 RPC / 缓存：gob
跨语言高性能 / 微服务：protobuf / msgpack

10. 性能优化技巧

1. 用 jsoniter 或 easyjson 替换标准库：

1	go get github.com/json-iterator/go

import jsoniter "github.com/json-iterator/go"

var json = jsoniter.ConfigCompatibleWithStandardLibrary
// API 完全兼容，但快 2-3 倍

2. 避免反射：用 easyjson 生成 Marshal/Unmarshal 代码

1 2	go get github.com/mailru/easyjson easyjson -all user.go

3. 流式处理大文件：

dec := json.NewDecoder(f)
for {
    var u User
    if err := dec.Decode(&u); err == io.EOF {
        break
    } else if err != nil {
        log.Fatal(err)
    }
    process(u)
}

小结

场景	推荐格式
配置文件	YAML
HTTP REST API	JSON
Go 内部通信	gob / protobuf
跨语言 RPC	protobuf (gRPC)
高性能缓存	msgpack / gob
前端友好	JSON

struct tag 是 Go 序列化的灵魂：

业务字段映射（json:"name"）
验证规则（validate:"required"）
数据库列名（db:"column_name"）
文档生成（example:"..."）

下一节深入并发控制：sync.Mutex、context、连接池。

本文作者： CoderSong
本文链接： https://jack-song-gif.github.io/2026/08/21/Go-12-序列化与struct-tag深入/
版权声明： 本博客所有文章除特别声明外，均采用 MIT 许可协议。转载请注明出处！