Fundamentos de serialización

10 ejemplos para empezar con la serialización: 7 básicos y 3 intermedios.

Prerrequisitos

• Instala Go 1.26.x o posterior desde go.dev/dl.
• Crea un módulo: mkdir serdemo && cd serdemo && go mod init example.com/serdemo.
• Guarda cada fragmento como main.go (o archivos separados en un mismo paquete) y ejecútalo con go run ..

Ejemplos básicos

1. json.Marshal y json.Unmarshal

Realiza un viaje de ida y vuelta de un struct a través de bytes JSON.

package main
 
import (
    "encoding/json"
    "fmt"
)
 
type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}
 
func main() {
    u := User{ID: 1, Name: "Ada"}
    b, err := json.Marshal(u)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(b))
 
    var decoded User
    if err := json.Unmarshal(b, &decoded); err != nil {
        panic(err)
    }
    fmt.Println(decoded.Name)
}

• Marshal devuelve []byte; conviértelo con string(b) para imprimir.
• Unmarshal necesita un puntero al valor de destino.
• Solo los campos exportados participan en la codificación JSON.

Relacionado: Serialización en Go: JSON primero, formatos bajo demanda - por qué JSON es el predeterminado

2. Las etiquetas de struct controlan las claves JSON

Las etiquetas renombran campos y ocultan internos.

package main
 
import (
    "encoding/json"
    "fmt"
)
 
type Account struct {
    Login        string `json:"login"`
    PasswordHash string `json:"-"`
    Role         string `json:"role,omitempty"`
}
 
func main() {
    a := Account{Login: "ada", PasswordHash: "secret"}
    b, _ := json.Marshal(a)
    fmt.Println(string(b))
}

• json:"login" mapea Login a la clave "login".
• json:"-" excluye PasswordHash de la salida por completo.
• omitempty omite campos con valor cero como Role vacío.

Relacionado: Etiquetas de Struct para JSON, DB y Validación - convenciones de múltiples etiquetas

3. Punteros y valores cero

Los punteros distinguen "ausente" de "presente cero".

package main
 
import (
    "encoding/json"
    "fmt"
)
 
type Item struct {
    Qty   int  `json:"qty"`
    Notes *string `json:"notes,omitempty"`
}
 
func main() {
    empty := Item{Qty: 0}
    b1, _ := json.Marshal(empty)
    fmt.Println(string(b1))
 
    note := ""
    withPtr := Item{Qty: 1, Notes: &note}
    b2, _ := json.Marshal(withPtr)
    fmt.Println(string(b2))
}

• Qty con valor 0 todavía aparece a menos que agregues omitempty.
• Notes como nil se omite con omitempty; un puntero a "" se mantiene.
• Usa punteros para campos opcionales de API que necesiten semántica null explícita.

Relacionado: Evolución de esquemas y manejo de campos desconocidos - campos opcionales

4. Los slices y mapas se serializan naturalmente

Las colecciones se codifican como arrays y objetos JSON.

package main
 
import (
    "encoding/json"
    "fmt"
)
 
func main() {
    tags := []string{"go", "json"}
    meta := map[string]int{"a": 1, "b": 2}
 
    b1, _ := json.Marshal(tags)
    b2, _ := json.Marshal(meta)
    fmt.Println(string(b1))
    fmt.Println(string(b2))
}

• Los slices nil se codifican como null; los slices vacíos se codifican como [] cuando no son nil.
• Las claves de mapa deben ser strings (o tipos que implementen encoding.TextMarshaler).
• Prefiere structs a map[string]any para contratos de API estables.

Relacionado: Serialización personalizada de encoding/json - alternativas tipadas a los mapas

5. json.Encoder y json.Decoder para streams

Transmite JSON a io.Writer y desde io.Reader.

package main
 
import (
    "bytes"
    "encoding/json"
    "fmt"
)
 
type Event struct {
    Type string `json:"type"`
}
 
func main() {
    var buf bytes.Buffer
    enc := json.NewEncoder(&buf)
    _ = enc.Encode(Event{Type: "click"})
 
    dec := json.NewDecoder(&buf)
    var e Event
    _ = dec.Decode(&e)
    fmt.Println(e.Type)
}

• Encode agrega una nueva línea después de cada valor (compatible con JSON Lines).
• Los decodificadores son adecuados para cuerpos HTTP sin necesidad de leer todo en memoria primero.
• Reutiliza un decodificador por cuerpo; no lo compartas entre solicitudes.

Relacionado: Mejores prácticas de serialización - límites de tamaño en los cuerpos

6. Los structs incrustados promueven campos

La incrustación anónima aplana la salida JSON.

package main
 
import (
    "encoding/json"
    "fmt"
)
 
type Timestamps struct {
    CreatedAt string `json:"created_at"`
}
 
type Post struct {
    Timestamps
    Title string `json:"title"`
}
 
func main() {
    p := Post{Timestamps: Timestamps{CreatedAt: "2026-01-01"}, Title: "Hi"}
    b, _ := json.Marshal(p)
    fmt.Println(string(b))
}

• Los campos exportados incrustados se promueven al struct externo para la codificación.
• Las colisiones de nombres se resuelven al campo externo; los campos internos se ocultan con cuidado al decodificar.
• Prefiere la composición explícita cuando la forma JSON no deba aplanarse.

Relacionado: Serialización personalizada de encoding/json - incrustación con serializadores personalizados

7. Indentación para una salida de depuración legible

MarshalIndent formatea la salida durante el desarrollo.

package main
 
import (
    "encoding/json"
    "fmt"
)
 
func main() {
    data := map[string]any{"ok": true, "count": 3}
    b, _ := json.MarshalIndent(data, "", "  ")
    fmt.Println(string(b))
}

• Usa la indentación solo en logs y salida de CLI, no en rutas de API activas.
• El JSON formateado es más grande y más lento de generar.
• Las API de producción suelen devolver JSON compacto.

Relacionado: JSON de alto rendimiento: alternativas jsoniter y sonic - cuando la velocidad compacta importa

Ejemplos intermedios

8. Formato de fecha personalizado con MarshalJSON

Anula la codificación de fecha predeterminada RFC3339.

package main
 
import (
    "encoding/json"
    "fmt"
    "time"
)
 
type DateOnly time.Time
 
func (d DateOnly) MarshalJSON() ([]byte, error) {
    t := time.Time(d)
    return json.Marshal(t.Format("2006-01-02"))
}
 
func main() {
    d := DateOnly(time.Date(2026, 7, 15, 0, 0, 0, 0, time.UTC))
    b, _ := json.Marshal(d)
    fmt.Println(string(b))
}

• time.Time ya implementa MarshalJSON con RFC3339; los nuevos tipos lo envuelven para otros formatos.
• Empareja MarshalJSON con UnmarshalJSON para API simétricas.
• Documenta el formato de transmisión en tu especificación de API.

Relacionado: Serialización personalizada de encoding/json - patrones de serializador personalizado completos

9. json.RawMessage para análisis diferido

Mantén JSON desconocido o parcial hasta que conozcas el esquema.

package main
 
import (
    "encoding/json"
    "fmt"
)
 
type Envelope struct {
    Type    string          `json:"type"`
    Payload json.RawMessage `json:"payload"`
}
 
func main() {
    raw := []byte(`{"type":"user","payload":{"id":1}}`)
    var env Envelope
    _ = json.Unmarshal(raw, &env)
    fmt.Println(env.Type, string(env.Payload))
}

• RawMessage es un alias de []byte que retrasa la decodificación anidada.
• Útil para eventos polimórficos y API compatibles con versiones anteriores.
• Valida los payloads internos en un segundo pase después de enrutar según Type.

Relacionado: Evolución de esquemas y manejo de campos desconocidos - patrones de evolución

10. DisallowUnknownFields en la decodificación

Rechaza solicitudes con claves inesperadas.

package main
 
import (
    "bytes"
    "encoding/json"
    "fmt"
)
 
type CreateUser struct {
    Name string `json:"name"`
}
 
func main() {
    body := []byte(`{"name":"Ada","admin":true}`)
    dec := json.NewDecoder(bytes.NewReader(body))
    dec.DisallowUnknownFields()
 
    var req CreateUser
    err := dec.Decode(&req)
    fmt.Println(err)
}

• El modo estricto detecta errores tipográficos y campos obsoletos de forma temprana.
• Las API públicas a menudo permanecen permisivas; las API administrativas internas pueden ser estrictas.
• Combina con la validación después de una decodificación exitosa.

Relacionado: Validación con go-playground/validator - reglas post-decodificación

Versiones de la pila: Esta página se escribió para Go 1.26.x (GC predeterminado Green Tea, modernizadores go fix - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica los objetivos de placa en la compilación), wazero (última versión - verifica en la compilación) y golangci-lint (última versión - verifica el conjunto de linters en la compilación).