Go encoding/xml 自定义 Unmarshaler 的字段映射

当 XML 字段名与 Go 结构不一致，只靠 struct tag 往往不够：同一业务字段可能有新旧两个标签，文本金额还要转换成整数，并且任何一步失败都不应留下半更新对象。适合的做法是让目标类型实现 xml.Unmarshaler，先用 DecodeElement 解码到辅助 wire 结构，再集中完成回退、转换和校验。

官方文档：https://pkg.go.dev/encoding/xml#Unmarshaler

一、先量化普通 struct tag 覆盖不了的差异

下面的订单 XML 同时包含属性、嵌套切片和旧系统字段。订单 ID 与标签可以直接声明映射；客户标识存在 customer_id 与 customer 两种名字；总金额以十进制文本传输，但领域结构希望保存为 int64 分值。

buyer-72599prioritygift

基线并不是“所有字段都手写 Token”。四组输入里只有客户字段回退和金额规则需要业务逻辑，其余映射仍应交给 encoding/xml。这样自定义代码的范围更小，也更容易测试。

二、用辅助 wire 结构接住原始 XML

UnmarshalXML(d, start) 收到的 start 就是当前元素的开始标签。官方推荐的常见策略，是定义一个与外部 XML 布局一致的辅助值，调用 d.DecodeElement 完成常规映射，再把结果复制到接收者。

package orderxml

import (
    "encoding/xml"
    "fmt"
    "strconv"
    "strings"
)

type Order struct {
    ID         string
    CustomerID string
    TotalCents int64
    Tags       []string
}

// orderWire 只描述外部 XML 布局，不承担领域规则。
type orderWire struct {
    ID             string   `xml:"id,attr"`
    CustomerID     string   `xml:"customer_id"`
    LegacyCustomer string   `xml:"customer"`
    Total          string   `xml:"total"`
    Tags           []string `xml:"tags>tag"`
}

func (o *Order) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error {
    var wire orderWire

    // DecodeElement 从 start 开始消费一个完整 order 元素。
    if err := d.DecodeElement(&wire, &start); err != nil {
        return fmt.Errorf("解析 order 元素: %w", err)
    }

    // 新字段优先；为空时才兼容旧字段名。
    customerID := strings.TrimSpace(wire.CustomerID)
    if customerID == "" {
        customerID = strings.TrimSpace(wire.LegacyCustomer)
    }
    if customerID == "" {
        return fmt.Errorf("order %q 缺少客户标识", wire.ID)
    }

    // 文本金额必须完整转换为十进制分值。
    totalCents, err := strconv.ParseInt(strings.TrimSpace(wire.Total), 10, 64)
    if err != nil {
        return fmt.Errorf("order %q 的 total 无效: %w", wire.ID, err)
    }
    if totalCents 

独立的 orderWire 还有一个重要作用：避免递归。如果在 Order.UnmarshalXML 里再次把 o 直接传给 DecodeElement，解码器会再次发现 Order 实现了 Unmarshaler，从而重复进入同一个方法。

三、单元素消费和错误传播是硬边界

官方接口约定要求 UnmarshalXML 恰好消费一个 XML 元素。DecodeElement(&wire, &start) 会负责读取与当前开始标签匹配的结束标签，并处理其中的嵌套内容。方法返回错误后，外层 xml.Unmarshal 会停止并把该错误返回给调用方。

不要在 UnmarshalXML 中调用 RawToken，官方文档明确禁止这种用法。确实需要逐 token 处理时使用 Token，并自行保证读到与 start 匹配的结束标签。对于字段重命名和文本转换，DecodeElement 通常更稳。

四、用表驱动用例记录映射结果

这类映射的指标不是吞吐数字，而是规则覆盖率：新字段、旧字段回退、非法金额、缺少客户标识四类输入都要有确定结果。下面的表驱动测试把每条映射规则变成一项可重复检查。

package orderxml

import (
    "encoding/xml"
    "strings"
    "testing"
)

func TestOrderUnmarshalXML(t *testing.T) {
    tests := []struct {
        name       string
        input      string
        wantBuyer  string
        wantErrSub string
    }{
        {
            name:      "优先读取新字段",
            input:     `newold100`,
            wantBuyer: "new",
        },
        {
            name:      "兼容旧字段",
            input:     `legacy200`,
            wantBuyer: "legacy",
        },
        {
            name:       "拒绝非法金额",
            input:      `u312.5`,
            wantErrSub: "total 无效",
        },
        {
            name:       "拒绝缺少客户标识",
            input:      `300`,
            wantErrSub: "缺少客户标识",
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            var got Order
            err := xml.Unmarshal([]byte(tt.input), &got)

            // 错误用例只核对稳定的业务信息，不绑定底层完整错误文本。
            if tt.wantErrSub != "" {
                if err == nil || !strings.Contains(err.Error(), tt.wantErrSub) {
                    t.Fatalf("err = %v, want contains %q", err, tt.wantErrSub)
                }
                return
            }

            if err != nil {
                t.Fatalf("Unmarshal() error = %v", err)
            }
            if got.CustomerID != tt.wantBuyer {
                t.Fatalf("CustomerID = %q, want %q", got.CustomerID, tt.wantBuyer)
            }
        })
    }
}

按这张用例表，目标是四类规则全部有明确结果，而不是只让一个正常样例通过。以后删除旧字段兼容时，只需移除对应分支和用例；字段迁移是否完成会在测试清单里留下清楚记录。

五、什么时候才需要手写 Token 循环

当 XML 包含顺序敏感的混合文本、同名元素需要根据前置属性选择不同结构，或需要在读取过程中流式聚合时，才值得直接调用 d.Token()。此时必须处理嵌套开始与结束标签，并确保方法离开前完整消费当前元素。

如果只是属性、子元素、路径和切片映射，优先用 struct tag；如果需要旧字段回退、值转换和组合校验，用“wire 结构 + DecodeElement”；只有前两者无法表达时才进入 Token 层。这样自定义范围最小，出错位置也最容易定位。

相关问题

UnmarshalXML 为什么通常要用指针接收者？

解码需要修改目标值，指针接收者才能把映射结果写回原对象。值接收者只修改副本，通常不符合预期。

未知 XML 字段会导致失败吗？

常规 encoding/xml 映射会忽略没有匹配结构字段的元素。若业务要求拒绝未知字段，需要在自定义 Token 处理或额外规则层明确实现。

属性映射应该用 UnmarshalXMLAttr 吗？

单个字段类型需要自定义属性转换时可以实现 UnmarshalXMLAttr；像本文这样需要组合多个属性和子元素时，类型级 UnmarshalXML 更合适。

可以在 UnmarshalXML 中继续调用 xml.Unmarshal 吗？

不建议对当前接收者这样做，容易递归。使用独立辅助类型，并让现有 Decoder 的 DecodeElement 从当前 start 继续读取。