diff --git a/dependency-reduced-pom.xml b/dependency-reduced-pom.xml index bebffd2..cf9a604 100644 --- a/dependency-reduced-pom.xml +++ b/dependency-reduced-pom.xml @@ -51,13 +51,6 @@ maven-deploy-plugin 3.1.2 - - default-deploy - deploy - - deploy - - deploy-to-nexus package diff --git a/src/main/java/com/codechecker/analyzer/ClassChangeAnalyzer.java b/src/main/java/com/codechecker/analyzer/ClassChangeAnalyzer.java index 97cd605..2f8d48c 100644 --- 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; diff --git a/src/main/java/com/codechecker/model/ClassChangeReport.java b/src/main/java/com/codechecker/model/ClassChangeReport.java index 195632b..381f1ee 100644 --- 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; } diff --git a/src/main/java/com/codechecker/parser/ClassDeclParser.java b/src/main/java/com/codechecker/parser/ClassDeclParser.java index eafa1b2..c43e902 100644 --- 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) > 类 Javadoc 首段。 + * 提取类级中文说明：@Schema(description/title) > @ApiModel(description/value) > 类 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 ""; diff --git a/src/main/java/com/codechecker/parser/ClassFieldParser.java b/src/main/java/com/codechecker/parser/ClassFieldParser.java index 15be0c1..b918fde 100644 --- 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) > @ApiModelProperty > Javadoc，均无则空串。 + * 字段说明：@Schema(description/title) > @ApiModelProperty(value/notes) > 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); diff --git a/src/main/resources/notify-templates/README.md b/src/main/resources/notify-templates/README.md index 86e10cc..cc4c241 100644 --- 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`。 diff --git a/src/main/resources/notify-templates/dto.md b/src/main/resources/notify-templates/dto.md index b192bd2..b4789e6 100644 --- 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)） | diff --git a/src/main/resources/notify-templates/entity.md b/src/main/resources/notify-templates/entity.md index 77e8e8a..22f74cd 100644 --- a/src/main/resources/notify-templates/entity.md +++ b/src/main/resources/notify-templates/entity.md @@ -47,3 +47,13 @@ > [类名变更] TrainingPositionEntity → TrainingPositionNewEntity > 字段无变化 ``` + +--- + +## 占位符 + +| 占位符 | 来源 | +|--------|------| +| 路径 | Git 相对路径，`ClassChangeReport.sourceFile` | +| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc | +| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） | diff --git a/src/main/resources/notify-templates/field-description.md b/src/main/resources/notify-templates/field-description.md index 9243b29..8f4e50a 100644 --- 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。 + ## 字段变更行格式 每条变更占**一行**，标签、说明、类型横向排列，冒号后两空格： diff --git a/src/main/resources/notify-templates/model.md b/src/main/resources/notify-templates/model.md index cc93d4d..e8223f7 100644 --- a/src/main/resources/notify-templates/model.md +++ b/src/main/resources/notify-templates/model.md @@ -47,3 +47,13 @@ > [类名变更] AttendanceRuleModel → AttendanceRuleNewModel > 字段无变化 ``` + +--- + +## 占位符 + +| 占位符 | 来源 | +|--------|------| +| 路径 | Git 相对路径，`ClassChangeReport.sourceFile` | +| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc | +| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） | diff --git a/src/main/resources/notify-templates/vo.md b/src/main/resources/notify-templates/vo.md index 1289030..359630e 100644 --- a/src/main/resources/notify-templates/vo.md +++ b/src/main/resources/notify-templates/vo.md @@ -61,3 +61,13 @@ ### 类转换影响 > 未开启检测 ``` + +--- + +## 占位符 + +| 占位符 | 来源 | +|--------|------| +| 路径 | Git 相对路径，`ClassChangeReport.sourceFile` | +| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc | +| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） | diff --git a/target/classes/notify-templates/README.md b/target/classes/notify-templates/README.md index 86e10cc..cc4c241 100644 --- 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`。 diff --git a/target/classes/notify-templates/dto.md b/target/classes/notify-templates/dto.md index b192bd2..b4789e6 100644 --- 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)） | diff --git a/target/classes/notify-templates/entity.md b/target/classes/notify-templates/entity.md index 77e8e8a..22f74cd 100644 --- a/target/classes/notify-templates/entity.md +++ b/target/classes/notify-templates/entity.md @@ -47,3 +47,13 @@ > [类名变更] TrainingPositionEntity → TrainingPositionNewEntity > 字段无变化 ``` + +--- + +## 占位符 + +| 占位符 | 来源 | +|--------|------| +| 路径 | Git 相对路径，`ClassChangeReport.sourceFile` | +| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc | +| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） | diff --git a/target/classes/notify-templates/field-description.md b/target/classes/notify-templates/field-description.md index 9243b29..8f4e50a 100644 --- 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。 + ## 字段变更行格式 每条变更占**一行**，标签、说明、类型横向排列，冒号后两空格： diff --git a/target/classes/notify-templates/model.md b/target/classes/notify-templates/model.md index cc93d4d..e8223f7 100644 --- a/target/classes/notify-templates/model.md +++ b/target/classes/notify-templates/model.md @@ -47,3 +47,13 @@ > [类名变更] AttendanceRuleModel → AttendanceRuleNewModel > 字段无变化 ``` + +--- + +## 占位符 + +| 占位符 | 来源 | +|--------|------| +| 路径 | Git 相对路径，`ClassChangeReport.sourceFile` | +| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc | +| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） | diff --git a/target/classes/notify-templates/vo.md b/target/classes/notify-templates/vo.md index 1289030..359630e 100644 --- a/target/classes/notify-templates/vo.md +++ b/target/classes/notify-templates/vo.md @@ -61,3 +61,13 @@ ### 类转换影响 > 未开启检测 ``` + +--- + +## 占位符 + +| 占位符 | 来源 | +|--------|------| +| 路径 | Git 相对路径，`ClassChangeReport.sourceFile` | +| 类说明 | `@Schema` / `@ApiModel` / 类 Javadoc | +| 字段说明 | `@Schema` / `@ApiModelProperty` / 字段 Javadoc（见 [field-description.md](field-description.md)） |