Go encoding.TextMarshaler 怎样让自定义类型支持文本编码

项目里经常会有一种类型：程序内部希望它保持强类型，写入 JSON、XML 或配置文本时却需要一个稳定的字符串。例如订单状态在代码里是枚举，传给外部系统时必须输出 pending，而不是整数 2。这时可以让类型实现 encoding.TextMarshaler，把“内部值如何变成文本”收进类型本身。

官方地址：https://pkg.go.dev/encoding

先把接口目标定清楚：类型负责输出，调用方负责承载

encoding.TextMarshaler 的接口只有一个方法：MarshalText() ([]byte, error)。它约定返回 UTF-8 编码的文本，调用方不需要知道枚举值、内部字段或格式化细节。这个分工很适合状态码、短 ID、日期别名和配置值等“有固定文本协议”的类型。

接口的边界也很重要：它只描述“怎样输出文本”，不决定文本要放进 JSON 字符串、XML 元素还是命令行参数。encoding/json、encoding/xml 等包可以在各自的编码路径中检查这个接口，但最终的转义、容器结构和字段命名仍由编码包决定。

实现 MarshalText：把内部状态映射成稳定文本

下面用订单状态举例。状态值在代码里仍然是枚举，外部文本则由 MarshalText 集中维护。未知状态直接返回错误，这比输出一个看似合法的 unknown 更容易让调用方发现数据问题。

package main

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

type OrderStatus uint8

const (
	StatusPending OrderStatus = iota
	StatusPaid
	StatusCancelled
)

func (s OrderStatus) MarshalText() ([]byte, error) {
	switch s {
	case StatusPending:
		return []byte("pending"), nil // 对外协议使用稳定的英文值。
	case StatusPaid:
		return []byte("paid"), nil
	case StatusCancelled:
		return []byte("cancelled"), nil
	default:
		return nil, fmt.Errorf("%w: %d", errors.New("invalid order status"), s) // 未知枚举不能静默输出。
	}
}

func main() {
	data, err := json.Marshal(StatusPaid)
	if err != nil {
		panic(err) // 示例只展示编码边界，生产代码应由上层决定如何处理错误。
	}
	fmt.Println(string(data)) // TextMarshaler 的文本会进入 JSON 字符串。
}

这里选择值接收者，是因为 OrderStatus 本身是一个不可变的小值。这样值和指针都能满足接口，放入结构体字段或直接传给编码器时更不容易因为方法集不同而失效。返回的字节只在当前调用中使用，不要把内部可变缓冲区暴露给调用方。

接收者和错误模型决定了调用方能否稳定使用

如果把 MarshalText 写成指针接收者，*OrderStatus 满足接口，而 OrderStatus 值本身不一定满足。这个选择适合输出内容依赖可变状态的对象，但对枚举、坐标、版本号这类值对象通常没有必要。设计前先看调用点：调用方传入的究竟是值、指针、结构体字段，还是接口变量。

错误信息要包含调用方能定位的上下文，但不要在 MarshalText 里记录日志、修改全局状态或偷偷修正非法值。这个方法最好保持纯粹：给定同一个值，返回同一种文本或同一种错误。

JSON 和 XML 如何复用这层文本协议

当类型实现了文本编组接口，标准编码包可以把这份文本协议放到自己的输出结构里。JSON 负责字符串转义和外层 JSON 格式，XML 负责元素或字段的承载；类型本身不应该为了适配某一个容器而返回带引号、尖括号或转义符的内容。

type Envelope struct {
	Status OrderStatus `json:"status" xml:"status"`
}

func encodeEnvelope(value Envelope) ([]byte, []byte, error) {
	jsonData, err := json.Marshal(value)
	if err != nil {
		return nil, nil, fmt.Errorf("marshal JSON: %w", err) // 保留底层错误，便于区分字段编码失败。
	}

	xmlData, err := xml.Marshal(value)
	if err != nil {
		return nil, nil, fmt.Errorf("marshal XML: %w", err) // 两种容器共用同一文本协议。
	}
	return jsonData, xmlData, nil
}

示例中的 xml 包需要和 encoding/json 一起导入。真正的工程代码还应为未知状态补一条失败用例：JSON 和 XML 不应一个输出正常字符串、另一个吞掉错误。统一的类型方法能减少这种格式之间的漂移。

需要可逆输入时，再配 TextUnmarshaler

只实现 TextMarshaler 适合单向输出。配置文件、查询参数或接口请求还要把文本恢复成类型时，应配套 encoding.TextUnmarshaler。解析时同样要拒绝未知字符串，并且先验证输入，再修改接收者，避免半解析状态污染原对象。

func (s *OrderStatus) UnmarshalText(text []byte) error {
	var value OrderStatus
	switch string(text) {
	case "pending":
		value = StatusPending // 先写入临时值，成功后再更新接收者。
	case "paid":
		value = StatusPaid
	case "cancelled":
		value = StatusCancelled
	default:
		return fmt.Errorf("unknown order status %q", text) // 未知文本直接拒绝。
	}
	*s = value
	return nil
}

这对接口的核心不是“让 JSON 变成字符串”这么简单，而是把类型的文本协议收敛到一个稳定位置：输出方法定义格式，输入方法定义可接受范围，JSON/XML 只负责承载。以后协议值发生变化时，调用方仍能从同一个类型看到兼容策略。

常见问题

MarshalText 返回的内容要自己加 JSON 引号吗？

不要。返回纯文本即可，JSON 编码器负责字符串引号和转义；手动加引号会让外层再编码一次。

为什么值接收者通常更适合枚举类型？

枚举的输出只依赖自身数值，值接收者能让值和指针都拥有这组方法，减少放入接口或结构体字段时的方法集差异。

未知状态应该返回空字符串还是错误？

如果空字符串不是明确协议值，就应返回错误。静默降级会把内部数据损坏伪装成合法输出。

实际选择可以归结为一句话：让自定义值实现纯粹、可预测的 MarshalText，让编码包负责容器格式；需要输入闭环时再实现 TextUnmarshaler，并为非法值保留清晰的错误边界。