Go encoding.TextMarshaler 与 json.Marshal 的调用优先级：指针接收者和 nil 指针边界

给一个类型加上文本编码方法后，很多人会以为 json.Marshal 一定会调用它。实际顺序要看方法集：同一个类型如果同时实现了 MarshalJSON 和 MarshalText，前者优先；如果只有 encoding.TextMarshaler，结果会被放进 JSON 字符串。指针为 nil 时又会绕开这些方法，直接编码为 null。

先检查值在调用点的动态类型和方法集，再判断编码结果；不要只看类型声明里“有一个 MarshalText”就猜输出。

先把三条编码路径分开

下面的 Label 只实现文本编码，返回值刻意带上类型名，便于观察调用链。json.Marshal 收到 Label 值时会把文本结果再次作为 JSON 字符串编码，因此返回结果包含双引号。

package main

import (
    "encoding/json"
    "fmt"
)

type Label struct {
    Code string
}

func (l Label) MarshalText() ([]byte, error) {
    return []byte("label:" + l.Code), nil
}

func main() {
    b, _ := json.Marshal(Label{Code: "paid"})
    fmt.Println(string(b)) // "label:paid"
}

这条路径可以概括为 Label → MarshalText → JSON 字符串，最后的默认编码分支在本文中简称为 默认编码。它适合枚举、时间标识或希望以单个字符串传输的值，但不适合需要输出 JSON 对象的类型。

同时实现 MarshalJSON 和 MarshalText 时谁先执行

给同一个类型补上 MarshalJSON，就能看到优先级改变。这里的返回值是合法 JSON 对象，所以 MarshalText 不会再被调用。

func (l Label) MarshalJSON() ([]byte, error) {
    return []byte(`{"code":"` + l.Code + `","source":"MarshalJSON"}`), nil
}

func (l Label) MarshalText() ([]byte, error) {
    return []byte("label:" + l.Code), nil
}

// json.Marshal(Label{Code: "paid"})
// => {"code":"paid","source":"MarshalJSON"}

判断顺序不是“文本方法更简单所以先走”，而是编码器先识别 json.Marshaler，确认值不是 nil 指针后调用 MarshalJSON；没有该方法时才会继续判断 encoding.TextMarshaler。如果两个方法都存在，调试时应先在 MarshalJSON 打断点。

指针接收者会改变方法集

把方法改成指针接收者后，Label 和 *Label 不再拥有相同的方法集。*Label 可以调用 MarshalText，但一个不可取地址的接口值里装着 Label 时，编码器未必能把它变成指针。这里把动态输入写成 nil *Label，就能明确区分空指针与普通 Label。

type Label struct {
    Code string
}

func (l *Label) MarshalText() ([]byte, error) {
    return []byte("label:" + l.Code), nil
}

var value any = Label{Code: "paid"}
var pointer any = &Label{Code: "paid"}

// value 更可能走默认结构编码：{"Code":"paid"}
// pointer 会调用 MarshalText："label:paid"

这里的关键不是 any 这个名字，而是接口里实际装入的动态值。若你的 API 参数是 any，调用方传入值还是指针会直接影响 JSON 形状。建议为这两种输入各写一个表驱动测试，不要让调用约定靠记忆维持。

nil 指针为什么不会调用 MarshalText

一个实现了 MarshalText 的指针如果是 nil，直接交给 json.Marshal 通常得到 null。这是编码器对 nil 指针的保护，避免为了调用方法而解引用空指针。

var label *Label
b, err := json.Marshal(label)
fmt.Println(string(b), err) // null 

因此不要在 MarshalText 里把 nil 当作“空标签”处理，然后期待它覆盖所有 nil 场景。若接口协议需要 ""、"unknown" 或一个对象，应该在进入编码前把这个业务状态显式转换成非 nil 值，或者在外层实现完整的 MarshalJSON。

用一组小测试固定边界

把输出形状写进测试，比在业务日志里猜方法调用可靠。下面的测试覆盖值接收者文本编码、JSON 方法优先和 nil 指针三个判断点。

func TestLabelJSON(t *testing.T) {
    tests := []struct {
        name string
        in   any
        want string
    }{
        {"text", Label{Code: "paid"}, `"label:paid"`},
        {"json", jsonLabel{Code: "paid"}, `{"code":"paid"}`},
        {"nil pointer", (*Label)(nil), `null`},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got, err := json.Marshal(tt.in)
            if err != nil || string(got) != tt.want {
                t.Fatalf("got %s, %v; want %s", got, err, tt.want)
            }
        })
    }
}

实际项目里还应补一条“接口中装入 Label 值”和“接口中装入 *Label 指针”的对照测试。若结构体字段带有 omitempty，再单独验证字段是否被省略，因为那是字段标签规则，不是 MarshalText 的优先级规则。

相关问题

MarshalText 返回的内容会被当成原始 JSON 吗？

不会。它会被当作文本，再编码成 JSON 字符串；需要输出对象或数组时使用 MarshalJSON。

值接收者和指针接收者应该怎么选？

值不会被修改且希望值、指针都保持一致行为时可用值接收者；需要读取可变状态或刻意区分指针输入时才考虑指针接收者。

怎样确认到底调用了哪个方法？

为每个方法写不同的可识别结果，并同时测试直接值、指针和 nil 指针三种动态输入。

把选择规则落到调用点

面对自定义 JSON 类型，先列出输入是值、非 nil 指针还是 nil 指针，再检查是否存在 MarshalJSON。没有它时再看 MarshalText，最后才接受默认结构编码。这个顺序写成测试后，接口重构或字段类型调整就不会悄悄改变返回 JSON。