init
This commit is contained in:
dlandy
211
docs/USAGE.md
Normal file
211
docs/USAGE.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# 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 开发调试（推荐）
|
||||
|
||||
在项目根目录执行：
|
||||
|
||||
```bash
|
||||
./gradlew.bat runIde
|
||||
```
|
||||
|
||||
会启动一个带插件的沙箱 IDE。
|
||||
|
||||
### 3.2 打包安装
|
||||
|
||||
在项目根目录执行：
|
||||
|
||||
```bash
|
||||
./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 命令
|
||||
|
||||
```bash
|
||||
# 运行单元测试
|
||||
./gradlew.bat test
|
||||
|
||||
# 启动带插件的沙箱 IDEA
|
||||
./gradlew.bat runIde
|
||||
|
||||
# 打包插件 ZIP
|
||||
./gradlew.bat buildPlugin
|
||||
```
|
||||
|
||||
## 12. 当前版本已知行为
|
||||
|
||||
- 动作仅在右键 `.xsd/.xml/.xom` 文件时出现。
|
||||
- 默认根类型会偏向以 XSD 中名为 `Document` 的全局元素作为根；若不存在则取第一个全局元素。
|
||||
- 输出 XOM 使用 `lable` 字段名属于历史兼容行为。
|
||||
|
||||
Reference in New Issue
Block a user