注释解析优化

2026-06-10 15:30:29 +08:00
parent 2990ddd2ff
commit 8ecc22e8af
17 changed files with 132 additions and 34 deletions
--- a/dependency-reduced-pom.xml
+++ b/dependency-reduced-pom.xml
@@ -51,13 +51,6 @@
            <artifactId>maven-deploy-plugin</artifactId>
            <version>3.1.2</version>
            <executions>
-              <execution>
-                <id>default-deploy</id>
-                <phase>deploy</phase>
-                <goals>
-                  <goal>deploy</goal>
-                </goals>
-              </execution>
              <execution>
                <id>deploy-to-nexus</id>
                <phase>package</phase>
--- a/src/main/java/com/codechecker/analyzer/ClassChangeAnalyzer.java
+++ b/src/main/java/com/codechecker/analyzer/ClassChangeAnalyzer.java
@@ -18,6 +18,7 @@ import java.util.Map;

 /**
 * 编排 git 扫描、字段 diff、影响分析，生成待通知的 ClassChangeReport 列表。
+ * Dto / Vo / Entity / Model 均通过 {@link ClassDeclParser}、{@link ClassFieldParser} 提取类级与字段中文说明。
 */
 public class ClassChangeAnalyzer {
    private final GitChangeScanner gitScanner;
--- a/src/main/java/com/codechecker/model/ClassChangeReport.java
+++ b/src/main/java/com/codechecker/model/ClassChangeReport.java
@@ -65,7 +65,7 @@ public class ClassChangeReport {
        return sourceFile;
    }

-    /** 类级中文说明（@Schema / 类 Javadoc），无则空串 */
+    /** 类级中文说明（@Schema / @ApiModel / 类 Javadoc），无则空串 */
    public String getClassDescription() {
        return classDescription;
    }
--- a/src/main/java/com/codechecker/parser/ClassDeclParser.java
+++ b/src/main/java/com/codechecker/parser/ClassDeclParser.java
@@ -68,7 +68,8 @@ public class ClassDeclParser {
    }

    /**
-     * 提取类级中文说明：@Schema(description/title) &gt; 类 Javadoc 首段。
+     * 提取类级中文说明：@Schema(description/title) &gt; @ApiModel(description/value) &gt; 类 Javadoc 首段。
+     * 适用于 Dto / Vo / Entity / Model 全部模型类变更通知。
     */
    public String extractClassDescription(String source, String expectedClassName) {
        if (source == null || source.isBlank()) {
@@ -80,9 +81,9 @@ public class ClassDeclParser {
            if (classDecl == null) {
                return "";
            }
-            String fromSchema = readSchemaDescription(classDecl);
-            if (!fromSchema.isEmpty()) {
-                return fromSchema;
+            String fromAnnotation = readClassAnnotationDescription(classDecl);
+            if (!fromAnnotation.isEmpty()) {
+                return fromAnnotation;
            }
            return extractClassJavadoc(classDecl);
        } catch (Exception ignored) {
@@ -109,18 +110,28 @@ public class ClassDeclParser {
        return null;
    }

-    private String readSchemaDescription(ClassOrInterfaceDeclaration classDecl) {
+    private String readClassAnnotationDescription(ClassOrInterfaceDeclaration classDecl) {
        for (AnnotationExpr annotation : classDecl.getAnnotations()) {
-            if (!"Schema".equals(annotation.getNameAsString())) {
-                continue;
+            String annName = annotation.getNameAsString();
+            if ("Schema".equals(annName)) {
+                String description = readAnnotationStringValue(annotation, "description");
+                if (!description.isEmpty()) {
+                    return description;
+                }
+                String title = readAnnotationStringValue(annotation, "title");
+                if (!title.isEmpty()) {
+                    return title;
+                }
            }
-            String description = readAnnotationStringValue(annotation, "description");
-            if (!description.isEmpty()) {
-                return description;
-            }
-            String title = readAnnotationStringValue(annotation, "title");
-            if (!title.isEmpty()) {
-                return title;
+            if ("ApiModel".equals(annName)) {
+                String description = readAnnotationStringValue(annotation, "description");
+                if (!description.isEmpty()) {
+                    return description;
+                }
+                String value = readAnnotationStringValue(annotation, "value");
+                if (!value.isEmpty()) {
+                    return value;
+                }
            }
        }
        return "";
--- a/src/main/java/com/codechecker/parser/ClassFieldParser.java
+++ b/src/main/java/com/codechecker/parser/ClassFieldParser.java
@@ -74,7 +74,8 @@ public class ClassFieldParser {
    }

    /**
-     * 字段说明：@Schema(description) &gt; @ApiModelProperty &gt; Javadoc，均无则空串。
+     * 字段说明：@Schema(description/title) &gt; @ApiModelProperty(value/notes) &gt; Javadoc，均无则空串。
+     * 适用于 Dto / Vo / Entity / Model 全部模型类字段变更通知。
     */
    String extractFieldLabel(FieldDeclaration fieldDecl) {
        for (AnnotationExpr annotation : fieldDecl.getAnnotations()) {
@@ -84,12 +85,22 @@ public class ClassFieldParser {
                if (!description.isEmpty()) {
                    return description;
                }
+                String title = readAnnotationStringValue(annotation, "title");
+                if (!title.isEmpty()) {
+                    return title;
+                }
            }
-            if ("ApiModelProperty".equals(annName)) {
+        }
+        for (AnnotationExpr annotation : fieldDecl.getAnnotations()) {
+            if ("ApiModelProperty".equals(annotation.getNameAsString())) {
                String value = readAnnotationStringValue(annotation, "value");
                if (!value.isEmpty()) {
                    return value;
                }
+                String notes = readAnnotationStringValue(annotation, "notes");
+                if (!notes.isEmpty()) {
+                    return notes;
+                }
            }
        }
        return extractJavadoc(fieldDecl);
--- a/src/main/resources/notify-templates/README.md
+++ b/src/main/resources/notify-templates/README.md
@@ -18,7 +18,7 @@ Push 触发 CI 后，按变更类的后缀（`Dto` / `Vo` / `Entity` / `Model`

 ## 布局约定

-1. **# 【类变更通知】** — 头部 4 项，每项一行 `>**标签:  值**`（加粗，冒号后两空格）；变更对象括号内展示类中文说明（@Schema / Javadoc），无说明则仅类名
+1. **# 【类变更通知】** — 头部 4 项，每项一行 `>**标签:  值**`（加粗，冒号后两空格）；变更对象括号内展示类中文说明（@Schema / @ApiModel / Javadoc），无说明则仅类名
 2. **## 【对象变更细节】** — 统计行 + 每条变更单行（标签/说明/类型合并）
 3. **## 【影响范围】** — 各 ### 小节内，每项一行引用

@@ -55,4 +55,11 @@ Dto/Vo 均固定展示 request、response 两栏；无匹配接口时显示「

 ## 实现

-`WeComNotifier.buildMarkdown()` · 消息类型 `markdown` · 路径取自 `ClassChangeReport.sourceFile`
+| 组件 | 职责 |
+|------|------|
+| `ClassDeclParser.extractClassDescription()` | 类级中文说明（Dto / Vo / Entity / Model 通用） |
+| `ClassFieldParser.extractFieldLabel()` | 字段中文说明（四类通用） |
+| `ClassChangeAnalyzer` | 编排 diff 并写入 `ClassChangeReport` |
+| `WeComNotifier.buildMarkdown()` | 渲染企微 `markdown` 通知 |
+
+路径取自 `ClassChangeReport.sourceFile`。
--- a/src/main/resources/notify-templates/dto.md
+++ b/src/main/resources/notify-templates/dto.md
@@ -103,4 +103,5 @@
 | 占位符 | 来源 |
 |--------|------|
 | 路径 | Git 相对路径，`ClassChangeReport.sourceFile` |
-| 说明 | `@Schema` / 注释 |
+| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc |
+| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） |
--- a/src/main/resources/notify-templates/entity.md
+++ b/src/main/resources/notify-templates/entity.md
@@ -47,3 +47,13 @@
 > <font color="warning">[类名变更]</font>  <font color="comment">TrainingPositionEntity</font> → <font color="info">TrainingPositionNewEntity</font>
 > <font color="comment">字段无变化</font>
 ```
+
+---
+
+## 占位符
+
+| 占位符 | 来源 |
+|--------|------|
+| 路径 | Git 相对路径，`ClassChangeReport.sourceFile` |
+| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc |
+| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） |
--- a/src/main/resources/notify-templates/field-description.md
+++ b/src/main/resources/notify-templates/field-description.md
@@ -1,16 +1,19 @@
 # 字段说明规则

+适用于 **Dto / Vo / Entity / Model** 四类模型类的变更通知。  
 字段变更采用 **引用块 + 单行合并 + font 颜色**，遵循企微 `markdown` v1（不支持列表）。

 ## 说明提取优先级

 | 优先级 | 来源 |
 |:------:|------|
-| 1 | `@Schema(description = "...")` |
-| 2 | `@ApiModelProperty` |
+| 1 | `@Schema(description = "...")` / `@Schema(title = "...")` |
+| 2 | `@ApiModelProperty(value = "...")` / `@ApiModelProperty(notes = "...")` |
 | 3 | `/** ... */` 字段注释 |
 | 4 | 空串 |

+类级说明优先级：`@Schema(description/title)` → `@ApiModel(description/value)` → 类 Javadoc。
+
 ## 字段变更行格式

 每条变更占**一行**，标签、说明、类型横向排列，冒号后两空格：
--- a/src/main/resources/notify-templates/model.md
+++ b/src/main/resources/notify-templates/model.md
@@ -47,3 +47,13 @@
 > <font color="warning">[类名变更]</font>  <font color="comment">AttendanceRuleModel</font> → <font color="info">AttendanceRuleNewModel</font>
 > <font color="comment">字段无变化</font>
 ```
+
+---
+
+## 占位符
+
+| 占位符 | 来源 |
+|--------|------|
+| 路径 | Git 相对路径，`ClassChangeReport.sourceFile` |
+| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc |
+| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） |
--- a/src/main/resources/notify-templates/vo.md
+++ b/src/main/resources/notify-templates/vo.md
@@ -61,3 +61,13 @@
 ### 类转换影响
 > <font color="comment">未开启检测</font>
 ```
+
+---
+
+## 占位符
+
+| 占位符 | 来源 |
+|--------|------|
+| 路径 | Git 相对路径，`ClassChangeReport.sourceFile` |
+| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc |
+| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） |
--- a/target/classes/notify-templates/README.md
+++ b/target/classes/notify-templates/README.md
@@ -18,7 +18,7 @@ Push 触发 CI 后，按变更类的后缀（`Dto` / `Vo` / `Entity` / `Model`

 ## 布局约定

-1. **# 【类变更通知】** — 头部 4 项，每项一行 `>**标签:  值**`（加粗，冒号后两空格）；变更对象括号内展示类中文说明（@Schema / Javadoc），无说明则仅类名
+1. **# 【类变更通知】** — 头部 4 项，每项一行 `>**标签:  值**`（加粗，冒号后两空格）；变更对象括号内展示类中文说明（@Schema / @ApiModel / Javadoc），无说明则仅类名
 2. **## 【对象变更细节】** — 统计行 + 每条变更单行（标签/说明/类型合并）
 3. **## 【影响范围】** — 各 ### 小节内，每项一行引用

@@ -55,4 +55,11 @@ Dto/Vo 均固定展示 request、response 两栏；无匹配接口时显示「

 ## 实现

-`WeComNotifier.buildMarkdown()` · 消息类型 `markdown` · 路径取自 `ClassChangeReport.sourceFile`
+| 组件 | 职责 |
+|------|------|
+| `ClassDeclParser.extractClassDescription()` | 类级中文说明（Dto / Vo / Entity / Model 通用） |
+| `ClassFieldParser.extractFieldLabel()` | 字段中文说明（四类通用） |
+| `ClassChangeAnalyzer` | 编排 diff 并写入 `ClassChangeReport` |
+| `WeComNotifier.buildMarkdown()` | 渲染企微 `markdown` 通知 |
+
+路径取自 `ClassChangeReport.sourceFile`。
--- a/target/classes/notify-templates/dto.md
+++ b/target/classes/notify-templates/dto.md
@@ -103,4 +103,5 @@
 | 占位符 | 来源 |
 |--------|------|
 | 路径 | Git 相对路径，`ClassChangeReport.sourceFile` |
-| 说明 | `@Schema` / 注释 |
+| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc |
+| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） |
--- a/target/classes/notify-templates/entity.md
+++ b/target/classes/notify-templates/entity.md
@@ -47,3 +47,13 @@
 > <font color="warning">[类名变更]</font>  <font color="comment">TrainingPositionEntity</font> → <font color="info">TrainingPositionNewEntity</font>
 > <font color="comment">字段无变化</font>
 ```
+
+---
+
+## 占位符
+
+| 占位符 | 来源 |
+|--------|------|
+| 路径 | Git 相对路径，`ClassChangeReport.sourceFile` |
+| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc |
+| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） |
--- a/target/classes/notify-templates/field-description.md
+++ b/target/classes/notify-templates/field-description.md
@@ -1,16 +1,19 @@
 # 字段说明规则

+适用于 **Dto / Vo / Entity / Model** 四类模型类的变更通知。  
 字段变更采用 **引用块 + 单行合并 + font 颜色**，遵循企微 `markdown` v1（不支持列表）。

 ## 说明提取优先级

 | 优先级 | 来源 |
 |:------:|------|
-| 1 | `@Schema(description = "...")` |
-| 2 | `@ApiModelProperty` |
+| 1 | `@Schema(description = "...")` / `@Schema(title = "...")` |
+| 2 | `@ApiModelProperty(value = "...")` / `@ApiModelProperty(notes = "...")` |
 | 3 | `/** ... */` 字段注释 |
 | 4 | 空串 |

+类级说明优先级：`@Schema(description/title)` → `@ApiModel(description/value)` → 类 Javadoc。
+
 ## 字段变更行格式

 每条变更占**一行**，标签、说明、类型横向排列，冒号后两空格：
--- a/target/classes/notify-templates/model.md
+++ b/target/classes/notify-templates/model.md
@@ -47,3 +47,13 @@
 > <font color="warning">[类名变更]</font>  <font color="comment">AttendanceRuleModel</font> → <font color="info">AttendanceRuleNewModel</font>
 > <font color="comment">字段无变化</font>
 ```
+
+---
+
+## 占位符
+
+| 占位符 | 来源 |
+|--------|------|
+| 路径 | Git 相对路径，`ClassChangeReport.sourceFile` |
+| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc |
+| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） |
--- a/target/classes/notify-templates/vo.md
+++ b/target/classes/notify-templates/vo.md
@@ -61,3 +61,13 @@
 ### 类转换影响
 > <font color="comment">未开启检测</font>
 ```
+
+---
+
+## 占位符
+
+| 占位符 | 来源 |
+|--------|------|
+| 路径 | Git 相对路径，`ClassChangeReport.sourceFile` |
+| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc |
+| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） |