4. ChangeLog 文件结构：XML / YAML / JSON / SQL 四种格式详解与选择策略

Liquibase 支持四种 ChangeLog 格式：XML、YAML、JSON 和 SQL。格式选择直接影响团队协作效率、版本控制可读性、迁移性能以及 GC 停顿风险。本章从解析性能、可维护性、变更追踪能力三个维度进行对比，并给出生产环境选择策略。

4.1 四种格式核心差异

4.2 格式详解与代码示例

4.2.1 XML 格式（推荐企业级）

XML 是 Liquibase 原生格式，支持所有 refactoring 标签，IDE 自动补全完善。适合需要严格变更审计的团队。

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.20.xsd">
    <changeSet id="1" author="admin">
        <createTable tableName="user">
            <column name="id" type="bigint" autoIncrement="true">
                <constraints primaryKey="true" nullable="false"/>
            </column>
            <column name="name" type="varchar(100)">
                <constraints nullable="false"/>
            </column>
        </createTable>
    </changeSet>
</databaseChangeLog>

4.2.2 YAML 格式（推荐 DevOps）

YAML 以缩进表示层级，代码量比 XML 减少约 40%。但缩进错误会导致解析失败，且大文件解析时 GC 压力较高。

databaseChangeLog:
  - changeSet:
      id: 1
      author: admin
      changes:
        - createTable:
            tableName: user
            columns:
              - column:
                  name: id
                  type: bigint
                  autoIncrement: true
                  constraints:
                    primaryKey: true
                    nullable: false
              - column:
                  name: name
                  type: varchar(100)
                  constraints:
                    nullable: false

4.2.3 JSON 格式（推荐微服务）

JSON 解析速度快，与 REST API 生态兼容性好。但可读性较差，不适合复杂嵌套变更。

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "1",
        "author": "admin",
        "changes": [
          {
            "createTable": {
              "tableName": "user",
              "columns": [
                {
                  "column": {
                    "name": "id",
                    "type": "bigint",
                    "autoIncrement": true,
                    "constraints": {
                      "primaryKey": true,
                      "nullable": false
                    }
                  }
                },
                {
                  "column": {
                    "name": "name",
                    "type": "varchar(100)",
                    "constraints": {
                      "nullable": false
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

4.2.4 SQL 格式（推荐 DBA 主导）

SQL 格式直接编写原生 DDL/DML，解析开销最低，适合对性能极度敏感的场景。但无法使用 Liquibase 的自动回滚和上下文标签功能。

-- liquibase formatted sql
-- changeset admin:1
CREATE TABLE user (
    id BIGINT AUTO_INCREMENT PRIMARY KEY NOT NULL,
    name VARCHAR(100) NOT NULL
);
-- rollback DROP TABLE user;

4.3 格式选择决策树

4.4 混合使用策略

生产环境推荐混合策略：根 ChangeLog 使用 XML 或 YAML 作为入口，内部通过 include 引入不同格式的子文件。

<!-- root.xml -->
<databaseChangeLog>
    <include file="init-schema.sql" relativeToChangelogFile="true"/>
    <include file="seed-data.yaml" relativeToChangelogFile="true"/>
    <include file="indexes.json" relativeToChangelogFile="true"/>
</databaseChangeLog>

4.5 格式迁移与兼容性

Liquibase 支持在项目中期切换 ChangeLog 格式，但需注意以下兼容性规则：

• 格式互转：使用 liquibase convert 命令可将 XML 转为 YAML/JSON，但 SQL 格式无法反向转换。
• ID 冲突：切换格式后，changeSet 的 id + author 组合必须保持唯一，否则 Liquibase 会视为新变更。
• 上下文标签：SQL 格式不支持 <context> 标签，需通过文件名约定（如 prod-schema.sql）实现环境隔离。
• 回滚支持：XML/YAML/JSON 支持自动生成回滚语句；SQL 格式必须手动编写 -- rollback 注释。