17370845950

@XmlElementWrapper 为 List 集合生成外层包装元素，提升 XML 结构清晰度；必须与 @XmlElement 配合使用，分别指定包装标签名和子元素名，且仅适用于 Collection 类型。

JAXB 处理 List 集合时，@XmlElementWrapper 的作用是为集合外层生成一个包装元素（wrapper element），让 XML 结构更清晰、符合常见规范。它不改变集合内容的序列化逻辑，但影响 XML 层级结构。

@XmlElementWrapper 的基本用法

当 Java 类中有一个 List 或 List 字段，默认 JAXB 会把每个元素直接作为同级子元素输出。加上 @XmlElementWrapper 后，JAXB 会在这些元素外再套一层标签。

例如：

@XmlRootElement
public class Department {
    private List members;

    @XmlElementWrapper(name = "members")
    @XmlElement(name = "member")
    public List getMembers() {
        return members;
    }

    public void setMembers(List members) {
        this.members = members;
    }
}

序列化结果为：

  
    Alice
    Bob
  

若去掉 @XmlElementWrapper，则直接输出两个 member 元素，没有 members 包裹层。

与 @XmlElement 的配合要点

@XmlElementWrapper 必须和 @XmlElement 成对使用，且 @XmlElement 的 name 指定的是集合中每个元素的标签名，不是 wrapper 标签名。

• wrapper 名由 @XmlElementWrapper(name = "...") 控制
• 子元素名由 @XmlElement(name = "...") 控制
• 两者 name 可以不同，常见命名习惯是 wrapper 用复数（如 users），子元素用单数（如 user）
• 如果省略 @XmlElement.name，默认使用字段名（如 members → 子元素也叫 members，易混淆，不推荐）

处理嵌套对象 List 的示例

对自定义对象集合同样适用：

public class User {
    private String name;
    private int age;

    // getter/setter + @XmlElement
}

@XmlRootElement
public class Company {
    private List users;

    @XmlElementWrapper(name = "users")
    @XmlElement(name = "user")
    public List getUsers() {
        return users;
    }

    public void setUsers(List users) {
        this.users = users;
    }
}

生成的 XML 会是：

  
    Tom30
    Jerry25
  

注意事项和常见问题

以下情

• 不能只加 @XmlElementWrapper 而不加 @XmlElement，否则集合字段会被忽略（JAXB 不识别无标注的集合）
• @XmlElementWrapper 不能用于数组（String[]），仅适用于 Collection 类型（如 ArrayList、LinkedList）
• 如果集合为 null，默认不会生成 wrapper 标签；若希望强制输出空 wrapper，需配合 @XmlElementWrapper(nillable = true) 和 @XmlElement(nillable = true)，并在 marshaller 中启用 Marshaller.JAXB_FORMATTED_OUTPUT 等设置
• 不支持在同一个字段上同时使用 @XmlElement 和 @XmlElementRef，否则报错