如何使用 Jackson XML 为集合元素自定义标签名称

在使用Jackson XML进行Java对象与XML数据转换的场景中，默认的集合元素标签名称通常是基于集合泛型类型生成的，很多时候无法满足项目约定的XML格式规范，因此需要手动自定义集合元素的标签名称。

核心注解介绍

Jackson XML提供了@JacksonXmlElementWrapper和@JacksonXmlProperty两个核心注解来实现集合元素标签的自定义，二者配合使用可以完成大部分场景的需求。

• @JacksonXmlElementWrapper：用于指定集合外层包裹元素的标签名称，同时可以设置是否生成外层包裹标签。
• @JacksonXmlProperty：用于指定当前元素（包括集合中的子元素）的标签名称、命名空间等属性。

基础使用步骤

1. 添加依赖

首先需要在项目中引入Jackson XML的相关依赖，以Maven项目为例，在pom.xml中添加如下配置：

<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-xml</artifactId>
    <version>2.15.2</version>
</dependency>

2. 定义实体类

假设我们有一个用户列表的场景，需要将用户集合序列化为指定标签名称的XML，首先定义用户实体类：

import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlProperty;

public class User {
    @JacksonXmlProperty(localName = "user_id")
    private Long id;

    @JacksonXmlProperty(localName = "user_name")
    private String name;

    // 构造方法、getter、setter省略
}

接下来定义包含用户集合的父实体类，在这里配置集合相关的标签名称：

import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlElementWrapper;
import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlProperty;
import java.util.List;

public class UserGroup {
    // 指定外层包裹标签名为user_list，集合中的每个子元素标签名为single_user
    @JacksonXmlElementWrapper(localName = "user_list")
    @JacksonXmlProperty(localName = "single_user")
    private List<User> users;

    @JacksonXmlProperty(localName = "group_name")
    private String groupName;

    // 构造方法、getter、setter省略
}

3. 执行序列化测试

编写测试代码验证自定义标签是否生效：

import com.fasterxml.jackson.dataformat.xml.XmlMapper;
import java.util.ArrayList;
import java.util.List;

public class Test {
    public static void main(String[] args) throws Exception {
        XmlMapper xmlMapper = new XmlMapper();
        UserGroup group = new UserGroup();
        group.setGroupName("测试用户组");

        List<User> users = new ArrayList<>();
        User user1 = new User();
        user1.setId(1L);
        user1.setName("张三");
        User user2 = new User();
        user2.setId(2L);
        user2.setName("李四");
        users.add(user1);
        users.add(user2);
        group.setUsers(users);

        String xml = xmlMapper.writeValueAsString(group);
        System.out.println(xml);
    }
}

运行上述代码后，输出的XML内容如下：

<UserGroup>
    <user_list>
        <single_user>
            <user_id>1</user_id>
            <user_name>张三</user_name>
        </single_user>
        <single_user>
            <user_id>2</user_id>
            <user_name>李四</user_name>
        </single_user>
    </user_list>
    <group_name>测试用户组</group_name>
</UserGroup>

无外层包裹标签的场景

如果不需要集合的外层包裹标签，可以将@JacksonXmlElementWrapper的useWrapping属性设置为false：

import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlElementWrapper;
import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlProperty;
import java.util.List;

public class UserGroupNoWrapper {
    // 不生成外层包裹标签，直接生成多个single_user标签
    @JacksonXmlElementWrapper(useWrapping = false)
    @JacksonXmlProperty(localName = "single_user")
    private List<User> users;

    @JacksonXmlProperty(localName = "group_name")
    private String groupName;

    // 构造方法、getter、setter省略
}

此时序列化后的XML会去掉user_list外层标签，直接输出多个single_user子元素。

注意事项

• 如果集合泛型是自定义类型，@JacksonXmlProperty的localName属性指定的是集合中每个元素的标签名，而@JacksonXmlElementWrapper指定的是集合整体的外层标签名。
• 反序列化时，相同的注解配置也会生效，Jackson XML会根据自定义标签名匹配对应的集合元素。
• 如果同时存在多个集合字段，需要为每个集合字段单独配置对应的注解，避免标签名称冲突。

Jackson_XML集合元素自定义标签名称XML序列化Java修改时间：2026-06-21 03:33:33