XML文件转Dart Class Flutter开发用的XML转Dart工具

用xml2dart生成dart类最省事，需配合build_runner和xml_serializable；支持命名空间（–Namespace-aware）、自动推断list、需手动处理嵌套属性与文本混用、禁用explicittojson。

XML 转 Dart class 用 xml2dart 最省事

flutter 项目里手动写 XML 解析逻辑太容易出错，也难维护。直接用 xml2dart 这类工具生成 Dart class 是主流做法，它能根据 XML 结构自动生成带 XmlSerializable 注解的类，和 build_runner 配合就能跑起来。

注意：别用在线转换网站——它们不支持命名空间、嵌套属性、可选字段推断，而且生成的代码没法和你的项目类型系统对齐。

• xml2dart 是命令行工具，输入 XML 文件路径，输出 Dart 类文件
• 需要提前在项目里装好 build_runner 和 xml_serializable（不是 xml 包）
• 生成的类默认用 @XmlSerializable，字段名会按 XML 元素名转成 lowerCamelCase，比如 <user-name></user-name> → userName
• 如果 XML 有重复标签（如多个 <item></item>），它会自动识别为 List<item></item>，但前提是结构一致；否则会报错或生成 dynamic

遇到命名空间（xmlns）就加 --namespace-aware

很多生产环境 XML 带命名空间，比如 <rss xmlns="http://purl.org/rss/1.0/"></rss>。不处理的话，xml_serializable 默认解析器会把所有元素当成无命名空间，导致 XmlDecoder 找不到字段，运行时返回空或抛 MissingXmlMapKeyError。

• 用 xml2dart --namespace-aware input.xml 启动，它会在生成的类里加 @XmlName('rss') 和 @XmlNamespace('http://purl.org/rss/1.0/')
• 对应地，XmlSerializer 实例必须用 XmlSerializer(namespaceAware: true) 初始化
• 如果你的 XML 有多个命名空间（比如混合 atom + RSS），xml2dart 目前不支持自动区分，得手改生成的类，给不同字段加不同 @XmlNamespace

xml_serializable 的 explicitToJson 必须关掉

生成的 Dart 类默认带 explicitToJson: true 参数，这会让 toJson() 方法只序列化显式标注了 @JsonKey 的字段——但 XML 解析根本不用这个，反而会导致反序列化后字段全为 NULL。

• 检查生成的 .g.dart 文件，确认 part 'xxx.g.dart'; 上方的 @XmlSerializable 没有 explicitToJson: true
• 如果用了自定义 build.yaml，确保没全局开启 explicitToJson
• 最稳妥的做法：在 @XmlSerializable 上显式写 explicitToJson: false，哪怕生成时没加，也建议补上

嵌套属性、文本内容混用时，字段类型要手动调

XML 里常见这种结构：<price currency="USD">29.99</price>。xml2dart 默认只生成一个 String price 字段，把整个内容当文本，currency 属性就丢了。

• 得改成两个字段：String? currency（加 @XmlAttribute(name: 'currency')）和 double? value（加 @XmlText()）
• @XmlText() 只能用于 String 或 num 类型；如果想直接转 double，字段声明必须是 double?，且 XML 内容得是纯数字
• 如果某字段有时是属性、有时是子元素（比如 <id>123</id> vs <id type="uuid">abc</id>），xml2dart 无法自动判断，必须人工合并逻辑，用 @XmlElement + @XmlAttribute + 自定义 fromXml 方法

XML 结构越不规整，生成后手修的越多；别指望一次生成就开箱即用，重点看 XmlText 和 XmlAttribute 的组合是否覆盖了所有混合场景。