Go encoding.TextMarshaler 怎么统一配置值序列化：JSON、日志与空值边界

配置值经常要同时进入 JSON 响应、结构化日志和环境变量。每个地方各写一段格式化代码，最容易出现的不是编译错误，而是同一个值在不同出口变成了三种字符串。Go 的 encoding.TextMarshaler 适合把这层文本表示收拢到类型本身；只要不需要自定义 JSON 结构，就可以让多个编码入口共享一套规则。

先定接口目标：同一个值只维护一份文本规则

假设服务里有一个发布环境值 Environment，它在配置文件里写成 staging，API 返回也希望是 "staging"，日志字段则希望直接打印 env=staging。这类值不需要展开成多个 JSON 字段，也不需要携带额外元数据，文本接口比手写三套转换更合适。

决策边界可以先这样划分：

参数设计：让 MarshalText 成为唯一的文本出口

先把合法值收紧，再实现文本接口。这里故意不让零值悄悄变成一个看似合法的环境名；调用方能从错误里知道配置需要补齐。

package main

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

type Environment string

const (
    EnvDev     Environment = "dev"
    EnvStaging Environment = "staging"
    EnvProd    Environment = "prod"
)

func (e Environment) MarshalText() ([]byte, error) {
    switch e {
    case EnvDev, EnvStaging, EnvProd:
        return []byte(e), nil
    default:
        return nil, fmt.Errorf("invalid environment %q", e)
    }
}

type ServiceConfig struct {
    Name string      `json:"name"`
    Env  Environment `json:"env"`
}

func main() {
    cfg := ServiceConfig{Name: "billing", Env: EnvStaging}
    b, err := json.Marshal(cfg)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(b))

    _, err = (Environment("preview")).MarshalText()
    fmt.Println(err)
}

运行后，env 会是 JSON 字符串 "staging"，而不是一个自定义对象。注意这里的 MarshalText 返回的是 UTF-8 文本；JSON 的引号和转义仍由 encoding/json 负责。

错误模型：格式化失败必须能追到原始配置值

MarshalText 不只是一个格式化函数，它还可以拒绝非法状态。比如配置来自环境变量，拼写成 preprod 时，宁可让 json.Marshal 返回错误，也不要把错误值写进响应后再由下游猜含义。

在复合结构里，错误通常会被包装成 json.MarshalerError。上层可以用 errors.As 查看类型，同时用 errors.Is 或错误文本保留业务判断。不要在 MarshalText 内打印日志后返回空字符串，那会让调用方误以为序列化成功。

兼容边界：值接收者、指针接收者和 nil 不是一回事

如果类型的文本表示只依赖自身字段，优先使用值接收者。这样值和非 nil 指针都能满足接口。若改成指针接收者，只有指针形式实现接口；而 JSON 对 nil 指针还有自己的特殊处理，不能把它当成普通空字符串。

一个实用检查是直接写接口断言和表格中的最小测试：

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

func TestEnvironmentText(t *testing.T) {
    got, err := EnvProd.MarshalText()
    if err != nil || string(got) != "prod" {
        t.Fatalf("got %q, err %v", got, err)
    }
}

如果未来把接收者改成指针，这两条断言会立刻提醒你：调用方的接口形态已经发生变化。

落地检查：JSON、日志和配置读取要测同一组样例

不要只测一个正常值。至少覆盖合法值、非法值、零值和指针边界，确认三个出口不会悄悄分叉：

• 合法的 dev、staging、prod 都输出约定文本。
• 非法值让序列化失败，并且错误中能看出原始值。
• 零值是否允许，要在类型定义里明确；不允许就尽早报错。
• 日志字段使用同一转换函数，不要重新拼接一套缩写。
• 如果需要从文本恢复对象，再单独实现 TextUnmarshaler 并测试往返。

相关问题

TextMarshaler 会让 JSON 变成对象吗？

不会。没有 MarshalJSON 时，文本结果会作为 JSON 字符串编码；需要对象结构时应直接实现 MarshalJSON。

为什么 MarshalText 返回 error 还要保留原始错误？

因为上层可能按错误类型做监控、降级或配置定位。吞错后返回空文本，最难排查。

nil 指针能不能在 MarshalText 里返回空字符串？

可以设计成某种业务语义，但必须明确约定并单测。更稳妥的做法是让调用方先判断 nil，避免方法内部解引用崩溃。

最后确认

当一个类型只需要一个稳定的文本表示时，把规则放进 MarshalText，再用 JSON 和日志的测试验证复用效果。接口目标、错误边界和 nil 语义先定清楚，后续新增配置出口时就不必复制转换逻辑。