@XmlElementWrapper 为 List 集合生成外层包装元素，提升 XML 结构清晰度；必须与 @XmlElement 配合使用，分别指定包装标签名和子元素名，且仅适用于 Collection 类型。
JAXB 处理 List 集合时，@XmlElementWrapper 的作用是为集合外层生成一个包装元素（wrapper element），让 XML 结构更清晰、符合常见规范。它不改变集合内容的序列化逻辑，但影响 XML 层级结构。
@XmlElementWrapper 的基本用法
当 Java 类中有一个 List<String> 或 List<User> 字段，默认 JAXB 会把每个元素直接作为同级子元素输出。加上 @XmlElementWrapper 后，JAXB 会在这些元素外再套一层标签。
例如：
@XmlRootElement
public class Department {
private List<String> members;
@XmlElementWrapper(name = "members")
@XmlElement(name = "member")
public List<String> getMembers() {
return members;
}
public void setMembers(List<String> members) {
this.members = members;
}
}
序列化结果为：
立即学习“Java免费学习笔记（深入）”；
<department>
<members>
<member>Alice</member>
<member>Bob</member>
</members>
</department>
若去掉 @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<User> users;
@XmlElementWrapper(name = "users")
@XmlElement(name = "user")
public List<User> getUsers() {
return users;
}
public void setUsers(List<User> users) {
this.users = users;
}
}
生成的 XML 会是：
<company>
<users>
<user><name>Tom</name><age>30</age></user>
<user><name>Jerry</name><age>25</age></user>
</users>
</company>
注意事项和常见问题
以下情况容易出错，需特别注意：
- 不能只加
@XmlElementWrapper而不加@XmlElement，否则集合字段会被忽略（JAXB 不识别无标注的集合） -
@XmlElementWrapper不能用于数组（String[]），仅适用于Collection类型（如ArrayList、LinkedList） - 如果集合为
null，默认不会生成 wrapper 标签；若希望强制输出空 wrapper，需配合@XmlElementWrapper(nillable = true)和@XmlElement(nillable = true)，并在 marshaller 中启用Marshaller.JAXB_FORMATTED_OUTPUT等设置 - 不支持在同一个字段上同时使用
@XmlElement和@XmlElementRef，否则报错
