meta-plugin/docs/USAGE.md

MetaPlugin 使用文档

1. 插件简介

MetaPlugin 是一个 IntelliJ IDEA 插件，用于把 XSD 结构转换为可配置的 XOM 映射 XML，并按配置生成对应的 Java 实体类。

当前项目中的插件信息：

• 插件名：MetaPlugin
• 插件 ID：com.dmiki.metaplugin
• 当前版本：1.0.0
• IDE 兼容下限：sinceBuild = 193（IntelliJ IDEA 2019.3+）

2. 核心能力

• 解析 XSD 并以树表格方式展示节点结构。
• 可视化配置每个节点的：
  • 配置策略
  • Java 属性名
  • Java 类型
  • 自定义属性（可按节点启用）
  • 预处理属性（可按节点启用）
• 预览最终 XOM 内容。
• 生成完整 XOM 文件。
• 可按“选中节点”局部预览/局部生成 XOM。
• 打开已有 .xml / .xom 映射文件后，反向回显到配置界面继续编辑。

3. 安装与启动

3.1 开发调试（推荐）

在项目根目录执行：

./gradlew.bat runIde

会启动一个带插件的沙箱 IDE。

3.2 打包安装

在项目根目录执行：

./gradlew.bat buildPlugin

打包产物位于：

• build/distributions/MetaPlugin-1.0.0.zip

在 IDEA 中通过 Settings -> Plugins -> Install Plugin from Disk... 选择该 ZIP 安装。

4. 入口与触发条件

插件动作名称为：XOM生成。

显示位置：

• Project View 右键菜单
• Editor 右键菜单

显示条件：仅在右键目标是以下文件时可见：

• .xsd
• .xml
• .xom

说明：

• 右键 .xsd：进入 XSD 解析与配置流程。
• 右键 .xml / .xom：按 XOM 回显流程加载已有映射。
• .xml 入口对任意 XML 文件可见，但只有包含 message/schema/resultMap 结构的映射 XML 才能正确回显。

5. 快速使用流程

5.1 从 XSD 开始生成

1. 在项目中右键一个 .xsd 文件，点击 XOM生成。
2. 插件自动解析 XSD 并展示树表格。
3. 按需修改顶部参数与节点配置。
4. 点击 预览XOM 检查输出。
5. 点击 生成XOM文件 生成映射文件与 Java 实体。

5.2 从已存在映射文件继续编辑（回显）

1. 右键一个 .xml 或 .xom 映射文件，点击 XOM生成。
2. 插件根据 <schema xsdPath="..."> 找到对应 XSD。
3. 自动恢复节点策略、属性映射、自定义属性、预处理属性等配置。
4. 调整后可再次预览或生成。

6. 界面参数说明

6.1 顶部基础参数

• 报文类型（schemaId）：默认取 XSD 文件名（去扩展名）。
• 包名：默认 com.example.message。
  • 注意这里填写的是“包名”，最终 resultMap.type 会自动拼接为：包名 + 报文类型大写格式。
  • 例如 hvps.101.001.01 会转为 HVPS_101_001_01。
• 输出目录：支持绝对路径或相对项目根目录路径。
• 自定义属性：全局默认值，默认 sign。
• 预处理属性：全局默认值，默认空。

6.2 表格列说明

• XML节点：节点名称与标记（必填、Choice、List、属性节点等）。
• 配置策略：控制该节点是否保留层级/属性/子项。
• JAVA属性名：生成 property 与 Java 字段名的来源。
• JAVA类型：生成 Java 实体字段类型（可编辑）。
• 自定义属性：勾选后为该节点输出 attribute="..."。
• 预处理属性：勾选后为该节点输出 pre-processor="..."。

说明：

• 自定义属性、预处理属性为“每行可启用 + 文本值”的组合输入。
• 若行内启用但文本为空，会回退使用顶部全局默认值。

7. 配置策略语义

7.1 非叶子节点可选策略

• 保留层级保留属性
  • 输出该节点 <result>，同时输出 property。
• 保留层级不保留属性
  • 输出该节点 <result>，不输出 property。
• 不保留层级
  • 不输出当前层 <result>，子节点上提到父层；标签会写成 父:子。
• 不保留层级且不保留子项
  • 当前节点及其子树都不输出。

7.2 叶子节点可选策略

• 保留：输出该节点 <result>。
• 不保留：忽略该节点。

8. 输出规则

8.1 XOM XML 结构

输出结构固定为：

• <message>
• <schema id="..." xsdPath="..."/>
• <resultMap id="..." type="..."> ... </resultMap>

8.2 标签属性命名

• 普通节点使用 lable="..."（历史拼写，插件当前仍按该键输出）。
• 属性节点使用 lable-attribute="..."。

说明：回显逻辑同时兼容 label/lable 与 label-attribute/lable-attribute 两套写法。

8.3 输出目录与文件名

• 默认输出目录：src/main/resources 下第一个不存在的目录：
  • msgmapper
  • msgmapper1
  • msgmapper2
  • ... 依次类推
• 默认输出文件名：报文类型.xml。
• 右键“生成选中节点XOM文件”时，默认文件名：报文类型_节点名.xml。

8.4 Java 实体输出规则

• 仅当 resultMap.type 含包名（存在 .）时才会生成 Java 文件。
• Java 文件输出目录固定为：XOM 文件所在目录/java。
• 如果包名为空（或未形成完整限定名），仅生成 XOM，不生成 Java。

9. 右键节点快捷能力

在树表格中右键某节点可用：

• 预览选中节点XOM
• 生成选中节点XOM文件

用途：

• 仅验证或导出某个子树配置，减少大文件全量生成的调试成本。

10. 常见错误与排查

• XOM-001：XSD 路径为空，或文件不存在/不可读。
• XOM-002：生成参数为空，或 schemaId 为空。
• XOM-003：
  • 未解析到可渲染节点，或
  • 严格模式下出现同级重复 label。
• XOM-004：
  • 严格模式启用但 resultMap.type 为空，或
  • 启用未知类型校验时节点 Java 类型缺失。
• XOM-005：最大层级不合法，或节点深度超限。
• XOM-006：输出文件/目录写入失败、目录创建失败等 IO 问题。

排查建议：

• 优先确认 schema.xsdPath 指向的文件实际存在。
• 确认输出目录有写权限。
• 先用 预览XOM 验证结构，再执行生成。
• 如果回显失败，优先检查映射文件是否存在 resultMap 节点及 schema.xsdPath。

11. 常用 Gradle 命令

# 运行单元测试
./gradlew.bat test

# 启动带插件的沙箱 IDEA
./gradlew.bat runIde

# 打包插件 ZIP
./gradlew.bat buildPlugin

12. 当前版本已知行为

• 动作仅在右键 .xsd/.xml/.xom 文件时出现。
• 默认根类型会偏向以 XSD 中名为 Document 的全局元素作为根；若不存在则取第一个全局元素。
• 输出 XOM 使用 lable 字段名属于历史兼容行为。