数据模型版本 - CUBA REST API

4.3. 数据模型版本

REST API 可以处理数据模型变更。某些场景这个功能很有用，比如，有些实体属性被重命名了，但是 REST API 客户端不知道这个改动，并且还是希望这个属性保留原来的名字。

这种情况下，REST API 允许定义实体 JSON 的转换规则。如果客户端应用在发送请求时，在查询参数里带上数据模型的版本，REST API 的响应体或者请求体中的 JSON 会按照请求中特定的领域模型版本的转换规则进行转换。

JSON 的转换规则必须写在配置文件中，这些配置文件要通过 web 或者 portal 模块的 cuba.rest.jsonTransformationConfig 应用程序属性来定义，比如 web-app.properties 文件：

cuba.rest.jsonTransformationConfig = +com/company/myapp/rest-json-transformations.xml

rest-json-transformations.xml 文件需要放在 web 或者 portal 模块（比如 com.company.myapp）。这个文件的内容是由 rest-json-transformations.xsd schema 定义。文件示例：

<?xml version="1.0"?>
<transformations xmlns="http://schemas.haulmont.com/cuba/rest-json-transformations.xsd">

    <transformation modelVersion="1.0" oldEntityName="sales$OldOrder" currentEntityName="sales$NewOrder">
        <renameAttribute oldName="oldNumber" currentName="number"/>
        <renameAttribute oldName="date" currentName="deliveryDate"/>
        <toVersion>
            <removeAttribute name="discount"/>
        </toVersion>
    </transformation>

    <transformation modelVersion="1.0" currentEntityName="sales$Contractor">
        <renameAttribute oldName="summary" currentName="total"/>
        <renameAttribute oldName="familyName" currentName="lastName"/>
        <fromVersion>
            <removeAttribute name="city"/>
            <removeAttribute name="country"/>
        </fromVersion>
        <toVersion>
            <removeAttribute name="phone"/>
        </toVersion>
    </transformation>

    <transformation modelVersion="1.1" currentEntityName="sales$NewOrder">
        <renameAttribute oldName="date" currentName="deliveryDate"/>
    </transformation>

</transformations>

在配置文件中定义的标准转换器可以进行下列实体 JSON 转换任务：

重命名实体
重命名实体属性
删除实体属性

JSON 转换可以在下列 REST API endpoint 生效：

/entities - 获取实体列表、获取单个实体、实体创建、实体更新、实体删除
/queries - 查询返回的实体 JSON 会被转换
/services - JSON 转换会发生在两个地方，service 方法返回的实体，以及作为参数传入 service 方法的实体。

如果对 REST API 的请求使用了 modelVersion URL 参数指定数据模型版本，那么 JSON 转换就会生效。

参考数据模型版本化示例了解如何配置数据模型版本以及怎样在客户端程序使用。