XML 解析

@XmlDecorator() 是一个参数装饰器，用于解析 XML 请求体并转换为 JavaScript 对象。

基础用法

import { XmlDecorator } from '@maxtan/nest-core'

@Post('webhook')
handleXml(@XmlDecorator() data: any) {
  // data 为解析后的 XML 对象
  return data
}

输入：

<root>
  <user name="John">
    <age>30</age>
  </user>
</root>

输出：

{
  "root": {
    "user": {
      "@_name": "John",
      "age": 30
    }
  }
}

解包根节点

使用 unwrap: true 自动移除根元素包装：

@Post('webhook')
handleXml(@XmlDecorator({ unwrap: true }) data: any) {
  // <root><user>...</user></root> → { user: ... }
  return data
}

自定义解析选项

传入 fast-xml-parser 的 X2jOptions 自定义解析行为：

@Post('webhook')
handleXml(
  @XmlDecorator({
    parserOptions: {
      ignoreAttributes: true,       // 忽略属性
      parseTagValue: false,         // 不自动转换值类型
      attributeNamePrefix: '',      // 属性名前缀
    }
  })
  data: any
) {
  return data
}

默认解析器配置

选项	默认值	说明
ignoreAttributes	false	是否忽略 XML 属性
attributeNamePrefix	@_	属性名前缀
textNodeName	#text	文本节点名称
parseTagValue	true	自动转换值类型
parseAttributeValue	true	自动转换属性值类型
trimValues	true	去除值前后空格

选项

interface XmlDecoratorOptions {
  /** 自定义 fast-xml-parser 解析选项 */
  parserOptions?: X2jOptions
  /** 是否自动解包根节点，默认 false */
  unwrap?: boolean
}

错误处理

场景	异常	消息
XML 格式错误	BadRequestException	XML 解析失败: ...
读取流失败	BadRequestException	XML 读取失败: ...
解析超时	BadRequestException	XML 解析超时 (10000ms)

性能优化

• 默认解析器实例全局复用
• 自定义配置的解析器实例缓存（最多 16 个）
• 超出缓存上限时自动淘汰最早的实例

依赖

需要安装 fast-xml-parser：

pnpm add fast-xml-parser

最佳实践

1. 使用 unwrap: true：大多数场景不需要根节点包装，建议默认解包
2. 保留默认配置：除非有特殊需求，尽量使用默认解析器配置（可复用全局实例，性能更优）
3. 配合异常过滤器：XML 解析失败自动抛出 BadRequestException，已被 AllExceptionsFilter 统一处理

相关文档

• 异常过滤器 — XML 解析错误的响应格式