XStream - xml 与对象的转换

前置准备

导入依赖，去Maven仓库搜索 XStrean ，下载核心依赖，这里以 1.4.19 版本为例。

<!-- https://mvnrepository.com/artifact/com.thoughtworks.xstream/xstream -->
<dependency>
    <groupId>com.thoughtworks.xstream</groupId>
    <artifactId>xstream</artifactId>
    <version>1.4.19</version>
</dependency>

简单使用（非注解开发）

通过操作 XStream 类完成对 Xml 和实体的转换。

定义实体

定义Xml报文实体, 组装Xml报文格式，以如下格式为例

<Root>
  <count>1</count>
  <serviceInfo uid="B31FB4508BE82F2E6FB761E067E60CF">
    <serviceName>服务名称</serviceName>
    <updateTime>2024-04-11T14:22:39.559</updateTime>
    <Attr id="1">
      <attrName>事项材料名称1</attrName>
      <attrCode>事项材料编码1</attrCode>
    </Attr>
    <Attr id="2">
      <attrName>事项材料名称2</attrName>
      <attrCode>事项材料编码2</attrCode>
    </Attr>
  </serviceInfo>
</Root>

定义最外层实体类 Root

@Data
@ToString
@EqualsAndHashCode
public class Root {
    
    Integer total = 1;
    
    ServiceInfo serviceInfo = new ServiceInfo();
    
    private String exclouldField = "exclouldField";

}

定义 ServiceInfo 类

@Data
@ToString
@EqualsAndHashCode
public class ServiceInfo {
    
    private String unid = "B31FB4508BE82F2E6FB761E067E60CF";
    
    private String serviceName = "服务名称";
    
    private LocalDateTime updateTime = LocalDateTime.now();
    
    private List<Attr> attrs = new ArrayList<>();

    public ServiceInfo() {
        attrs.add(new Attr(1, "事项材料名称1", "事项材料编码1"));
        attrs.add(new Attr(2, "事项材料名称2", "事项材料编码2"));
    }

}

定义 Attr 类

@Data
@ToString
@EqualsAndHashCode
public class Attr {
    
    private Integer id;
    
    private String attrName;
    
    private String attrCode;
    
    private String exclouldField = "exclouldField";

    public Attr(Integer id, String attrName, String attrCode) {
        this.id = id;
        this.attrName = attrName;
        this.attrCode = attrCode;
    }

}

定义主方法，生成 Xml 报文

public static void main(String[] args) {
    //定义一个 Xml 实体
    Root root = new Root();
    XStream xstream = new XStream();
    //将实体转换为 Xml 报文
    String s = xstream.toXML(root);
    System.out.println(s);
}

生成的报文如下所示：

<com.example.springbootdemo.xml.xstream.Root>
  <total>1</total>
  <serviceInfo>
    <unid>B31FB4508BE82F2E6FB761E067E60CF</unid>
    <serviceName>服务名称</serviceName>
    <updateTime>2024-04-11T15:34:31.984</updateTime>
    <attrs>
      <com.example.springbootdemo.xml.xstream.Attr>
        <id>1</id>
        <attrName>事项材料名称1</attrName>
        <attrCode>事项材料编码1</attrCode>
        <exclouldField>exclouldField</exclouldField>
      </com.example.springbootdemo.xml.xstream.Attr>
      <com.example.springbootdemo.xml.xstream.Attr>
        <id>2</id>
        <attrName>事项材料名称2</attrName>
        <attrCode>事项材料编码2</attrCode>
        <exclouldField>exclouldField</exclouldField>
      </com.example.springbootdemo.xml.xstream.Attr>
    </attrs>
  </serviceInfo>
  <exclouldField>exclouldField</exclouldField>
</com.example.springbootdemo.xml.xstream.Root>

我们发现，生成的报文并没有按照我们的意愿生成，这里涉及到XStream 的几个知识点。

类生成标签时，如果未指定别名，那么会以类的全路径（即：包名.类名）作为标签。
方案一：
调用 aliasPackage(...)方法，去除掉包前缀，此包下面的所有类被序列化时都会被剔除掉包名前缀，如xstream.aliasPackage("", "com.example.springbootdemo.xml.xstream") 表示将 com.example.springbootdemo.xml.xstream.Root 序列化为 Root
方案二：
调用 alias(...) 方法，给类取别名。如 xstream.alias("Root", Root.class) 表示Root 类序列化时，标签名为 Root
类属性（字段）生成标签时，如果未指定别名，那么会以属性（字段）名作为标签。
方案一：
调用 aliasField(...)方法，给字段取别名，如: xstream.aliasField("count", Root.class, "total") 表示将Root类中的Total字段序列化为count。
如果要排除掉实体中的某个字段，可以调用omitField(...) 方法。如 xstream.omitField(Root.class, "exclouldField") 表示Xml序列化时，忽略Root类中的exclouldField字段。
如果要增加形如 < Attr id="1"> 的标签属性，可以通过useAttributeFor(...)和 aliasAttribute(...)方法实现。
useAttributeFor(...)
xstream.useAttributeFor(Attr.class, "id")表示将Attr类中的id字段作为标签属性，形如< Atrr id=""/>
aliasAttribute(...)
xstream.aliasAttribute(ServiceInfo.class, "unid", "uid") 表示将ServiceInfo类中的unid字段作为标签属性, 且属性名称自定义为uid，形如< ServiceInfo uid=""/>
可以通过 addImplicitCollection(...) 方法去除集合标签，如xstream.addImplicitCollection(ServiceInfo.class, "attrs") 表示去除集合标签，生成的Xml去除掉外层的attrs标签，直接取内层数据展示在外层。

添加addImplicitCollection(...)方法前的Xml报文

<Root>
  <count>1</count>
  <serviceInfo uid="B31FB4508BE82F2E6FB761E067E60CF">
    <serviceName>服务名称</serviceName>
    <updateTime>2024-04-11T16:46:00.121</updateTime>
    <attrs>
      <Attr id="1">
        <attrName>事项材料名称1</attrName>
        <attrCode>事项材料编码1</attrCode>
        <exclouldField>exclouldField</exclouldField>
      </Attr>
      <Attr id="2">
        <attrName>事项材料名称2</attrName>
        <attrCode>事项材料编码2</attrCode>
        <exclouldField>exclouldField</exclouldField>
      </Attr>
    </attrs>
  </serviceInfo>
  <exclouldField>exclouldField</exclouldField>
</Root>

添加addImplicitCollection(...)方法后的Xml报文

<Root>
  <count>1</count>
  <serviceInfo uid="B31FB4508BE82F2E6FB761E067E60CF">
    <serviceName>服务名称</serviceName>
    <updateTime>2024-04-11T16:47:42.472</updateTime>
    <Attr id="1">
      <attrName>事项材料名称1</attrName>
      <attrCode>事项材料编码1</attrCode>
      <exclouldField>exclouldField</exclouldField>
    </Attr>
    <Attr id="2">
      <attrName>事项材料名称2</attrName>
      <attrCode>事项材料编码2</attrCode>
      <exclouldField>exclouldField</exclouldField>
    </Attr>
  </serviceInfo>
  <exclouldField>exclouldField</exclouldField>
</Root>

不难发现，添加后的报文中少了< attrs> 标签，即集合的那一层标签被剔除掉了。

使用上述知识点重新编写测试用例，进行一系列属性设置后，我们便能得到预期的输出了，将输出的Xml报文传入 XStream 的fromXML(...) 方法即可反序列化成之前的实体。

public static void main(String[] args) {

        Root root = new Root();
        XStream xstream = new XStream();

        //去除包名前缀
        xstream.aliasPackage("", "com.example.springbootdemo.xml.xstream");
        //可使用类名替代
        //xstream.alias("Root", Root.class);
        //xstream.alias("Attr", Attr.class);

        //属性别名,
        // 将Root类中的Total字段在Xml中以count显示
        xstream.aliasField("count", Root.class, "total");

        //排除属性
        //生成Xml时，忽略Root类中的exclouldField字段
        xstream.omitField(Root.class, "exclouldField");
        //生成Xml时，忽略Attr类中的exclouldField字段
        xstream.omitField(Attr.class, "exclouldField");

        //标签内属性
        //将Attr类中的id字段作为标签属性，形如<Atrr id=""/>
        xstream.useAttributeFor(Attr.class, "id");
        //将ServiceInfo类中的unid字段作为标签属性, 且属性名称自定义，形如<ServiceInfo uid=""/>
        xstream.aliasAttribute(ServiceInfo.class, "unid", "uid");

        //去除集合标签，生成的Xml去除掉外层的attrs标签，直接取内层数据展示在外层
        xstream.addImplicitCollection(ServiceInfo.class, "attrs");

        String s = xstream.toXML(root);
        System.out.println(s);

        xstream.addPermission(AnyTypePermission.ANY);
        //xstream.allowTypesByWildcard(new String[]{pkgName});
        xstream.processAnnotations(Root.class);
        //忽略掉未知的标签，否则如果实体没有将所有标签囊括在内时会触发异常
        xstream.ignoreUnknownElements();
        Object res = xstream.fromXML(s);
        System.out.println(res.toString());
    }

注解开发

首先了解一下常用的一些注解

常用注解

@XStreamAlias
用来指定类或者字段的别名，用于序列化时展示，作用在类上时与aliasField(...)方法作用相同，作用在字段上时与aliasField(...)方法作用相同。

@XStreamAsAttribute
该注解标注的字段将作为类标签的属性存在，不再作为单独的标签。作用与aliasAttribute(...) 和useAttributeFor(...)方法类似。

@XStreamAsAttribute
该注解标注的字段会被忽略，不参加Xml的序列化和反序列化。作用与omitField(...) 方法相同。

@XStreamImplicit
用于定义集合、数组、Map的序列化方式。

注意：以如下为例， @XStreamImplicit(itemFieldName = "attr") 注解的 itemFieldName 属性会覆盖掉内部 Attr 类上的 @XStreamAlias("_attr") 注解，且 attrs标签将不会出现，< attrs>< _attr><attrName></attrName></_attr></attrs> 格式会被替换为 < attr><attrName></attrName>< /attr>格式

@XStreamImplicit(itemFieldName = "attr")
private List<Attr> attrs = new ArrayList<>();

@XStreamAlias("_attr")
public class Attr {

    @XStreamAlias("attrName")
    private String attrName;
    
}

@XStreamConverter
用于指定类型转化器。

定义实体

定义 Root 类

@Data
@ToString
@EqualsAndHashCode
@XStreamAlias("root")
public class Root {

    @XStreamAlias("total")
    Integer total = 1;

    @XStreamAlias("serviceinfo")
    ServiceInfo serviceInfo = new ServiceInfo();

    @XStreamOmitField
    private String exclouldField = "";

}

定义 ServiceInfo 类

@Data
@ToString
@EqualsAndHashCode
@XStreamAlias("serviceinfo")
public class ServiceInfo {

    @XStreamAsAttribute
    private String unid = "B31FB4508BE82F2E6FB761E067E60CF";

    @XStreamAlias("serviceName")
    private String serviceName = "服务名称";

    @XStreamAlias("updateTime")
    //@XStreamConverter(LocalDateTimeConverter.class)
    private LocalDateTime updateTime = LocalDateTime.now();

    //注解属性都为空时，去除掉外层属性， itemFieldName 属性有值时，内层类 Attr 上的@XStreamAlias注解失效，被itemFieldName取代
    @XStreamImplicit(itemFieldName = "attr")
    private List<Attr> attrs = new ArrayList<>();

    public ServiceInfo() {
        attrs.add(new Attr(1, "事项材料名称1", "事项材料编码1"));
        attrs.add(new Attr(2, "事项材料名称2", "事项材料编码2"));
    }

}

定义 Attr 类

@Data
@ToString
@EqualsAndHashCode
@XStreamAlias("_attr")
public class Attr {

    @XStreamAsAttribute
    private Integer id;

    @XStreamAlias("attrName")
    private String attrName;

    @XStreamAlias("attrCode")
    private String attrCode;

    @XStreamOmitField
    private String exclouldField = "exclouldField";

    public Attr(Integer id, String attrName, String attrCode) {
        this.id = id;
        this.attrName = attrName;
        this.attrCode = attrCode;
    }

}

编写工具类 XStreamUtil

public class XStreamUtil {

    //new NoNameCoder() 解决 _ 被序列化成 __ 的问题
    private static final NoNameCoder noNameCoder = new NoNameCoder();

    private static XStream xStream = new XStream(new DomDriver("UTF-8", noNameCoder));

    private static XStream getxStream(HierarchicalStreamDriver driver){
        if(Objects.isNull(driver)){
            return xStream;
        }
        return new XStream(driver);
    }

    public static <T> T unmarshal(String pkgName, Class<T> cla, String xmlStr, HierarchicalStreamDriver driver) {
        xStream = getxStream(driver);

        if (StringUtils.isEmpty(pkgName)) {
            //高版本为了解决安全漏洞，增加了白名单机制， 如果不设置这个权限可能会报错
            xStream.addPermission(AnyTypePermission.ANY);
        } else {
            //设置允许解析的包，如果不想设置可以用 addPermission(AnyTypePermission.ANY) 代替
            xStream.allowTypesByWildcard(new String[]{pkgName});
        }

        //支持注解，不然使用的XStream注解不会生效且不报错
        xStream.autodetectAnnotations(true);
        xStream.processAnnotations(cla);

        //忽略未知属性, 如果不添加这个，当Xml报文中出现实体中没有的属性时会报错 No such field
        xStream.ignoreUnknownElements();

        return (T) xStream.fromXML(xmlStr);
    }

    public static <T> T unmarshal(String pkgName, Class<T> cla, String xmlStr) {
        return unmarshal(pkgName, cla, xmlStr, null);
    }

    public static <T> T unmarshal(Class<T> cla, String xmlStr) {
        return unmarshal(null, cla, xmlStr, null);
    }

    public static String marshal(Object o, DomDriver driver) {
        xStream = getxStream(driver);

        //支持注解，不然使用的 @XStreamAlias() 注解不会生效而且不会报错
        xStream.autodetectAnnotations(true);

        //注册自定义时间转换器，使得XStream全局支持LocalDateTime， 或者不在这里注册，使用@XStreamConverter(LocalDateTimeConverter.class)注解在单一字段上
        xStream.registerConverter(new LocalDateTimeConverter());
        return xStream.toXML(o);
    }

    public static String marshal(Object o){
        return marshal(o, null);
    }

}

测试

public static void main(String[] args) {
        Root root = new Root();
        String s = XStreamUtil.marshal(root);
        System.out.println(s);

        Root res = XStreamUtil.unmarshal(Root.class, s);
        System.out.println(res.toString());
    }

可能遇到的问题

1、注解不生效

描述：
注解在类和字段上的注解不生效，生成的Xml报文是以默认方式生成的。

解决方案：
需要将XStream 的注解开关打开，让他支持注解。

//支持注解，不然使用的注解不会生效而且不会报错
xStream.autodetectAnnotations(true);

2、序列化时 _ 被序列化成 __

描述：
@XStreamAlias("_attr") 注解的属性 ”_attr“ 被序列化为 ”__attr“

解决方法：
创建XStream 对象时，指定NoNameCoder对象。

//new NoNameCoder() 解决 _ 被序列化成 __ 的问题
private static final NoNameCoder noNameCoder = new NoNameCoder();
private static XStream xStream = new XStream(new DomDriver("UTF-8", noNameCoder));

3、反序列化时实体缺失Xml报文属性报错 No such field

解决方法：
忽略未知属性。

//忽略未知属性, 如果不添加这个，当Xml报文中出现实体中没有的属性时会报错 No such field
xStream.ignoreUnknownElements();

4、com.thoughtworks.xstream.security.ForbiddenClassException

描述：高版本为了解决安全漏洞，增加了白名单机制。

解决方法：
方案一： 调用addPermission(...)方法，设置XStream权限为AnyTypePermission.ANY。
方案二： 设置允许解析的包, 将需要使用的实体囊括其中。

 //高版本为了解决安全漏洞，增加了白名单机制， 如果不设置这个权限可能会报错
xStream.addPermission(AnyTypePermission.ANY);
 //设置允许解析的包，如果不想设置可以用 addPermission(AnyTypePermission.ANY) 代替
xStream.allowTypesByWildcard(new String[]{pkgName});

5、指定的时间格式不被支持

描述：
XStream 支持的时间格式是标准时间格式，如果指定时间格式字段要进行反序列化，可能不被支持。
解决方案：
自定义时间转换器，注册到XStream中，或者使用@XStreamConverter注解指定目标字段的转换器。

以LocalDateTime 和 yyyy-MM-dd HH:mm:ss 格式的数据转换为例。

自定义时间转换器 LocalDateTimeConverter

public class LocalDateTimeConverter implements SingleValueConverter {

    private static final DateTimeFormatter pattern = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");

    @Override
    public String toString(Object o) {
        try {
            if (Objects.nonNull(o) && (o instanceof LocalDateTime)) {
                return pattern.format((TemporalAccessor) o);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }

    @Override
    public Object fromString(String s) {
        try {
            if (StringUtils.isNotBlank(s)) {
                return LocalDateTime.parse(s, pattern);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }

    @Override
    public boolean canConvert(Class type) {
        return type == LocalDateTime.class;
    }
}

方案一： 注解到目标字段

@XStreamAlias("updateTime")
//@XStreamConverter(LocalDateTimeConverter.class)
private LocalDateTime updateTime = LocalDateTime.now();

方案二： 将时间转换器注册到XStream对象

//注册自定义时间转换器，使得XStream全局支持LocalDateTime， 或者不在这里注册，使用@XStreamConverter(LocalDateTimeConverter.class)注解在单一字段上
xStream.registerConverter(new LocalDateTimeConverter());

6、空值标签丢失

描述：
值为null的字段在序列化时会被丢弃。

解决方案：
简单类型如String可以给其赋个空字符串，如果是复杂类型的话考虑自定义一个空值转换器注册到XStream对象中。

人面猴
序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
沈念sama阅读 205,386评论 6赞 479
死咒
序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
沈念sama阅读 87,939评论 2赞 381
救了他两次的神仙让他今天三更去死
文/潘晓璐我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
开封第一讲书人阅读 151,851评论 0赞 341
道士缉凶录：失踪的卖姜人
文/不坏的土叔我叫张陵，是天一观的道长。经常有香客问我，道长，这世上最难降的妖魔是什么？我笑而不...
开封第一讲书人阅读 54,953评论 1赞 278
港岛之恋（遗憾婚礼）
正文为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
茶点故事阅读 63,971评论 5赞 369
恶毒庶女顶嫁案：这布局不是一般人想出来的
文/花漫我一把揭开白布。她就那样静静地躺着，像睡着了一般。火红的嫁衣衬着肌肤如雪。梳的纹丝不乱的头发上，一...
开封第一讲书人阅读 48,784评论 1赞 283
城市分裂传说
那天，我揣着相机与录音，去河边找鬼。笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。我是一名探鬼主播，决...
沈念sama阅读 38,126评论 3赞 399
双鸳鸯连环套：你想象不到人心有多黑
文/苍兰香墨我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
开封第一讲书人阅读 36,765评论 0赞 258
万荣杀人案实录
序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
沈念sama阅读 43,148评论 1赞 300
护林员之死
正文独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋以下内容为张勋视角年9月15日...
茶点故事阅读 35,744评论 2赞 323
白月光启示录
正文我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
茶点故事阅读 37,858评论 1赞 333
活死人
序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
沈念sama阅读 33,479评论 4赞 322
日本核电站爆炸内幕
正文年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
茶点故事阅读 39,080评论 3赞 307
男人毒药：我在死后第九天来索命
文/蒙蒙一、第九天我趴在偏房一处隐蔽的房顶上张望。院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
开封第一讲书人阅读 30,053评论 0赞 19
一桩弑父案，背后竟有这般阴谋
文/苍兰香墨我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。一阵脚步声响...
开封第一讲书人阅读 31,278评论 1赞 260
情欲美人皮
我被黑心中介骗来泰国打工，没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。一个月前我还...
沈念sama阅读 45,245评论 2赞 352
代替公主和亲
正文我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
茶点故事阅读 42,590评论 2赞 343

XStream - xml 与 对象的转换

前置准备

简单使用（非注解开发）

定义实体

注解开发

常用注解

定义实体

测试

可能遇到的问题

1、注解不生效

2、序列化时 _ 被序列化成 __

3、反序列化时实体缺失Xml报文属性报错 No such field

4、com.thoughtworks.xstream.security.ForbiddenClassException

5、指定的时间格式不被支持

6、空值标签丢失

推荐阅读更多精彩内容

XStream - xml 与对象的转换