Go 怎样让自定义类型参与文本编码

如果一个自定义类型需要出现在配置文件、查询参数、日志或 JSON 字符串中，最稳妥的做法不是在每个调用点手写转换，而是让类型自己声明文本格式。Go 的 encoding.TextMarshaler 和 encoding.TextUnmarshaler 正好提供了这一层约定：前者把值变成 UTF-8 文本，后者把文本解析回值。

官方资料：https://pkg.go.dev/encoding

本文用一个带前缀的资源标识类型说明完整做法。核心变化只有两点：输出方法必须稳定、可读且不返回半成品；输入方法必须先解析到临时值，确认合法后再写回接收者。这样同一套规则可以被多个编码包复用，错误也集中在类型边界处理。

先看清两个接口各自负责什么

TextMarshaler 的方法签名是 MarshalText() ([]byte, error)，表示当前值如何编码成文本；TextUnmarshaler 的方法签名是 UnmarshalText([]byte) error，表示输入文本如何改变当前值。它们只描述文本表示，不负责 JSON 外层的引号、字段名或对象结构。

因此，接口的重点不是“让任意类型都能转成字符串”，而是把一种稳定的外部表示绑定到类型上。例如下面的 ResourceID 约定使用 res_ 前缀和小写十六进制内容：

package resource

import (
    "encoding/hex"
    "errors"
    "fmt"
)

var ErrInvalidResourceID = errors.New("invalid resource id")

type ResourceID [8]byte

// MarshalText 只负责输出稳定的文本格式，不把 JSON 引号混进结果。
func (id ResourceID) MarshalText() ([]byte, error) {
    encoded := make([]byte, 2+hex.EncodedLen(len(id)))
    copy(encoded, "res_")
    hex.Encode(encoded[2:], id[:])
    return encoded, nil
}

// UnmarshalText 先校验到临时数组，避免错误输入破坏接收者原来的值。
func (id *ResourceID) UnmarshalText(text []byte) error {
    if id == nil || len(text) != 2+hex.EncodedLen(len(id)) || string(text[:2]) != "res_" {
        return fmt.Errorf("%w: %q", ErrInvalidResourceID, text)
    }

    var decoded ResourceID
    if _, err := hex.Decode(decoded[:], text[2:]); err != nil {
        return fmt.Errorf("%w: %q: %v", ErrInvalidResourceID, text, err)
    }
    *id = decoded
    return nil
}

这里的长度检查和前缀检查属于格式契约。MarshalText 不需要猜测调用方想要什么格式，UnmarshalText 也不应该悄悄接受另一种拼写，否则同一个值会出现多套外部表示。

输出方法要稳定，输入方法要可回滚

实现 MarshalText 时，优先选择不依赖环境的表示。资源 ID、枚举值和日期类型通常适合固定前缀、固定大小写或明确分隔符。不要把调试信息、指针地址、当前时区这类不稳定内容放进协议字段。

UnmarshalText 则要把“解析成功”和“写入接收者”分成两个动作。示例中的 decoded 是临时值，只有十六进制和前缀都通过后才执行 *id = decoded。这会带来一个重要性质：调用方收到错误时，原值仍然保持不变。

如果文本格式有多个合法版本，可以在解析端显式分支，但输出端只保留一个规范写法。这样旧数据可以继续读，新数据不会不断产生新的拼写。

指针接收者决定谁能参与解码

编码方法通常使用值接收者，因为它只读取当前值；解码方法必须修改对象，所以应使用指针接收者。也就是说，下面的接口断言分别检查“值可输出”和“指针可输入”：

var _ encoding.TextMarshaler = ResourceID{}
var _ encoding.TextUnmarshaler = (*ResourceID)(nil)

这两行是编译期契约，不是运行时测试。若误把 UnmarshalText 写成值接收者，方法内部修改的只是副本；若把 MarshalText 只写在指针接收者上，某些不可寻址的值、接口值或 map 元素就可能无法按预期触发方法。

还有一个边界：nil 指针不是合法的写入目标。示例直接返回错误，避免在解引用时产生崩溃。是否允许空文本，也应由类型契约决定；如果空文本代表“未设置”，建议使用额外的可选字段或指针，而不是让一个有效 ID 和空字符串共享同一含义。

JSON 会在字符串和 map 键场景发现它

encoding/json 会把实现了 TextMarshaler 的值编码为 JSON 字符串；解码时，只有输入是 JSON 字符串，才会调用 TextUnmarshaler。它还允许实现文本接口的类型作为 map key，这正是稳定文本表示很有价值的地方。

type Envelope struct {
    ID    ResourceID            `json:"id"`
    Items map[ResourceID]string `json:"items"`
}

func encodeEnvelope(value Envelope) ([]byte, error) {
    // JSON 负责引号和对象结构，ResourceID 负责自己的文本内容。
    return json.Marshal(value)
}

func decodeEnvelope(data []byte, value *Envelope) error {
    // 解码目标必须是指针，嵌套的 ResourceID 会收到 UnmarshalText 调用。
    return json.Unmarshal(data, value)
}

这里不要为了让 JSON 看起来“更短”而额外实现一套 MarshalJSON。如果类型的需求只是稳定文本，文本接口的职责更小，也更容易被 URL、配置解析或其他编码包复用。只有当 JSON 结构本身不是字符串，或者需要自定义字段级语义时，才考虑 JSON 专用接口。

用小测试锁住编码契约

这类方法最值得测试的不是“有没有调用到”，而是输入输出是否互相兼容，以及失败时是否保持原值。测试可以覆盖规范文本、错误前缀、错误长度、非法字符和 JSON 嵌套场景：

func TestResourceIDTextRoundTrip(t *testing.T) {
    original := ResourceID{1, 2, 3, 4, 5, 6, 7, 8}

    text, err := original.MarshalText()
    if err != nil {
        t.Fatal(err) // 输出失败应立即结束当前用例。
    }

    var decoded ResourceID
    if err := decoded.UnmarshalText(text); err != nil {
        t.Fatal(err) // 规范文本必须能被同一类型重新读取。
    }
    if decoded != original {
        t.Fatalf("decoded=%v want=%v", decoded, original)
    }
}

func TestResourceIDRejectsWithoutMutation(t *testing.T) {
    id := ResourceID{9, 9, 9, 9, 9, 9, 9, 9}
    before := id

    err := id.UnmarshalText([]byte("res_not-hex"))
    if err == nil {
        t.Fatal("invalid text should return an error") // 错误输入不能被静默接受。
    }
    if id != before {
        t.Fatalf("id changed after error: got=%v want=%v", id, before)
    }
}

如果未来需要改格式，先决定旧文本是否必须继续读取，再增加兼容分支和测试。不要只修改 MarshalText，却忘了检查已有配置、缓存键或外部接口中的旧值。

一张表记住采用边界

归根结底，文本接口是一份小而明确的协议：MarshalText 决定规范输出，UnmarshalText 负责严格读取，外层编码包负责自己的容器结构。把这三层分开，自定义类型就能在更多边界复用，而不会把格式判断散落到业务代码里。

相关问题

• 为什么 UnmarshalText 通常要用指针接收者？因为它需要把解析后的值写回调用方对象，值接收者只能修改副本。
• 实现 TextMarshaler 后还需要实现 Stringer 吗？两者用途不同。Stringer 面向显示和日志，TextMarshaler 是编码协议；如果格式契约一致，可以复用内部格式化函数，但不要混淆职责。
• 非法文本应该返回什么错误？返回可判断的哨兵错误或包装错误，并保留原始输入上下文；不要把错误输入转换成零值后静默继续。