首页 > Golang > Go问答

Go map 用什么类型的键才能转成 JSON

来源：17golang原创

时间：2026-09-05 22:33:01 317浏览收藏

把 Go 的 map 传给 json.Marshal 时，最容易踩的坑不是值类型，而是键类型。结论先说：默认的 encoding/json 可以把字符串类型、整数类型，或实现 encoding.TextMarshaler 的键编码成 JSON 对象名；结构体、浮点数、指针等键不能直接这样编码。

要点速览

map[string]T 最直接；整数键会被转换成 JSON 字符串键。
自定义键可以实现 encoding.TextMarshaler，由 MarshalText 返回属性名。
如果键无法稳定表示为文本，改成对象切片通常比强行套 map 更清楚。

先看 json.Marshal 接受哪些 map 键

JSON 对象的键只能是字符串，而 Go 的 map 键可以比字符串丰富得多。因此编码器必须先把 Go 键收敛为对象名。官方文档给出的规则是：任意字符串类型直接使用；整数类型转成字符串；实现 encoding.TextMarshaler 的键调用 MarshalText 后使用返回文本。

Go encoding/json 将字符串键、整数键和 TextMarshaler 键映射为 JSON 对象名的静态结构框图 — 图1：查看 Go map 键到 JSON 对象名的三条静态映射边界，判断当前键是否具备可表示的文本形式。

这个规则解释了一个常见现象：map[bool]string、map[float64]string 或 map[Point]string 在调用 json.Marshal 时，会返回 json: unsupported type 一类错误。不是 map 不能编码，而是对象名没有默认转换规则。

用 string 和整数键完成直接编码

字符串键无需额外处理：

package main

import (
    "encoding/json"
    "fmt"
)

type UserID int

func main() {
    byName := map[string]int{"alice": 2, "bob": 1}
    byID := map[int]string{7: "ready", 42: "running"}
    byTypedID := map[UserID]string{1001: "active"}

    for _, value := range []any{byName, byID, byTypedID} {
        data, err := json.Marshal(value)
        if err != nil {
            panic(err)
        }
        fmt.Println(string(data))
    }
}

byName 的键保持为字符串；byID 的数字键会成为 "7" 和 "42"；底层类型为整数的命名类型也属于整数键。解码时要注意，JSON 对象名仍然是字符串，目标 map 若使用整数键，Unmarshal 会按目标整数类型解析。

让自定义键实现 encoding.TextMarshaler

日期、枚举或租户标识经常希望保留自己的展示格式。这时不要把键改成含义不明的整数，可以让它实现文本接口：

type Month struct {
    Year  int
    Month int
}

func (m Month) MarshalText() ([]byte, error) {
    return []byte(fmt.Sprintf("%04d-%02d", m.Year, m.Month)), nil
}

func main() {
    sales := map[Month]int{
        {Year: 2026, Month: 9}: 18,
        {Year: 2026, Month: 10}: 23,
    }

    data, err := json.Marshal(sales)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(data))
}

这里的关键不是实现了任意一个字符串方法，而是准确实现 encoding.TextMarshaler。返回文本应当稳定、可读，并且能在业务上唯一标识原键。若两个不同的 Go 键返回相同文本，编码后的 JSON 对象名就会发生碰撞，设计上应先避免这种情况。

Go 自定义 Month 键通过 encoding.TextMarshaler 生成 JSON 日期属性名的静态关系图 — 图2：查看 Month、MarshalText、文本属性名和 JSON 对象之间的静态关系，理解自定义键的转换责任落在哪里。

结构体、浮点数和指针键不能直接套用

Go 允许结构体作为 map 键，只要结构体可比较；但“可比较”只解决 map 存储问题，不等于它有 JSON 对象名。下面这些写法都不适合作为默认 JSON 对象键：

Go 键类型	默认 Marshal	更合适的处理
string、整数及其命名类型	支持	直接编码
实现 TextMarshaler 的类型	支持	保证文本唯一且稳定
bool、float、指针、普通结构体	不支持为对象键	改为 string 或对象切片

例如点位统计可以改成 []PointValue，显式保留 x、y 和 value 字段。这样 JSON 结构不依赖隐式键格式，也更方便前端校验；如果确实需要对象形式，就为点类型定义无歧义的 MarshalText。