create-base-teek-theme
Version:
``` npm create base-teek-theme@latest my-first-blog ```
232 lines (203 loc) • 8.63 kB
Markdown
---
date: 2025-04-26 04:43:13
title: Javadoc自动填充maven插件
permalink: /pages/6ae52b
author:
name: 华总
link: https://xiaoying.org.cn
categories:
- 后端
- 功能扩展
---
## 背景
发布到中央仓库时需要javadoc注释，所以写了这个maven插件用于在构建阶段自动生成注释。该插件同时支持Java 8和Java 17版本。
## 特性
1. **同时支持Java 8和Java 17及以上**
2. **模块化设计**：将代码按职责拆分为多个类，提高代码的可维护性和可扩展性
3. **配置灵活性**：增加了多个配置选项，允许用户自定义Javadoc生成行为
4. **错误处理**：改进了异常处理机制，提高代码的健壮性
5. **代码复用**：提取重复代码为通用方法，减少代码冗余
## 使用方法
::: tip
依赖可能非最新版本，请前往[maven](https://central.sonatype.com/artifact/io.github.liyao52033/autofill-javadoc-maven-plugin)获取最新版本
:::
### 单独使用
```xml
<build>
<plugins>
<plugin>
<groupId>io.github.liyao52033</groupId>
<artifactId>autofill-javadoc-maven-plugin</artifactId>
<version>1.2.0</version>
<executions>
<execution>
<goals>
<goal>autofill</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<configuration>
<sourceDir>src/main/java</sourceDir> <!-- 指定源代码目录 -->
<addClassJavadoc>true</addClassJavadoc> <!-- 是否添加类注释 -->
<addMethodJavadoc>true</addMethodJavadoc> <!-- 是否添加方法注释 -->
<addParamJavadoc>true</addParamJavadoc> <!-- 是否添加参数注释 -->
<addReturnJavadoc>true</addReturnJavadoc> <!-- 是否添加返回值注释 -->
<addThrowsJavadoc>true</addThrowsJavadoc> <!-- 是否添加异常注释 -->
<!-- 高级配置选项 -->
<excludePatterns>
<excludePattern>.*\/generated\/.*</excludePattern> <!-- 排除生成的代码 -->
<excludePattern>.*Test\.java</excludePattern> <!-- 排除测试文件 -->
</excludePatterns>
<includePrivateMethods>false</includePrivateMethods> <!-- 是否包含私有方法 -->
</configuration>
</plugin>
</plugins>
</build>
```
### 与maven-javadoc-plugin集成发布到中央仓库
```xml
<build>
<plugins>
<plugin>
<groupId>org.sonatype.central</groupId>
<artifactId>central-publishing-maven-plugin</artifactId>
<version>0.5.0</version>
<extensions>true</extensions>
<configuration>
<publishingServerId>xxx</publishingServerId>
<checksums>required</checksums>
<deploymentName>xxx</deploymentName>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>3.2.1</version>
<executions>
<execution>
<id>attach-sources</id>
<phase>verify</phase>
<goals>
<goal>jar-no-fork</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>io.github.liyao52033</groupId>
<artifactId>autofill-javadoc-maven-plugin</artifactId>
<version>1.2.0</version>
<executions>
<execution>
<goals>
<goal>autofill</goal>
</goals>
<phase>generate-sources</phase> <!-- 确保在javadoc之前运行 -->
</execution>
</executions>
<configuration>
<sourceDir>src/main/java</sourceDir> <!-- 指定源代码目录 -->
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.5.0</version>
<configuration>
<encoding>UTF-8</encoding>
<charset>UTF-8</charset>
<docencoding>UTF-8</docencoding>
</configuration>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
<phase>verify</phase> <!-- Javadoc 生成在 verify 阶段运行 -->
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>3.2.7</version>
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase>
<goals>
<goal>sign</goal>
</goals>
</execution>
</executions>
<configuration>
<gpgArguments>
<arg>--pinentry-mode</arg>
<arg>loopback</arg>
</gpgArguments>
</configuration>
</plugin>
</plugins>
</build>
```
## 项目结构
项目结构如下：
```
src/main/java/com/liyao/autofillDoc/
├── JavadocAutofillMojo.java # 主类，Maven插件入口
├── config/
│ └── JavadocAutofillConfig.java # 配置类，存储插件配置参数
├── exception/
│ └── JavadocProcessingException.java # 异常处理类
├── service/
│ ├── FileProcessingService.java # 文件处理服务
│ ├── JavadocProcessor.java # Javadoc处理器
│ └── MethodDescriptionService.java # 方法描述生成服务
└── util/
└── JavadocUtils.java # 工具类
```
## 新增配置选项
包含以下配置选项，可以在Maven配置中自定义：
```xml
<configuration>
<sourceDir>src/main/java</sourceDir> <!-- 源代码目录 -->
<addClassJavadoc>true</addClassJavadoc> <!-- 是否添加类注释 -->
<addMethodJavadoc>true</addMethodJavadoc> <!-- 是否添加方法注释 -->
<addParamJavadoc>true</addParamJavadoc> <!-- 是否添加参数注释 -->
<addReturnJavadoc>true</addReturnJavadoc> <!-- 是否添加返回值注释 -->
<addThrowsJavadoc>true</addThrowsJavadoc> <!-- 是否添加异常注释 -->
<excludePatterns>
<excludePattern>.*\/generated\/.*</excludePattern> <!-- 排除生成的代码 -->
<excludePattern>.*Test\.java</excludePattern> <!-- 排除测试文件 -->
</excludePatterns> <!-- 排除特定文件的模式列表 -->
<includePrivateMethods>false</includePrivateMethods> <!-- 是否包含私有方法 -->
</configuration>
```
### 配置选项详细说明
#### 基本配置
- **sourceDir**: 指定源代码目录，一般为`src/main/java`
- **addClassJavadoc**: 是否为类/接口/枚举添加Javadoc注释，默认为`true`
- **addMethodJavadoc**: 是否为方法添加Javadoc注释，默认为`true`
- **addParamJavadoc**: 是否为方法参数添加Javadoc注释，默认为`true`
- **addReturnJavadoc**: 是否为方法返回值添加Javadoc注释，默认为`true`
- **addThrowsJavadoc**: 是否为方法抛出的异常添加Javadoc注释，默认为`true`
#### 高级配置
- **excludePatterns**: 排除特定文件的正则表达式模式列表。插件将跳过匹配这些模式的文件，不对其进行处理。这对于排除自动生成的代码、测试文件或其他不需要文档的文件非常有用。
- 每个`<excludePattern>`元素应包含一个有效的正则表达式
- 文件路径将与这些模式进行匹配，匹配成功的文件将被跳过
- 默认为空列表，即不排除任何文件
- **includePrivateMethods**: 是否为私有方法生成Javadoc注释
- 设置为`true`时，插件将为所有方法（包括私有方法）生成注释
- 设置为`false`时，插件将跳过私有方法，只为非私有方法生成注释
- 默认为`true`
## 错误处理
提供了完整的错误处理机制，当处理文件过程中出现异常时，插件会：
1. 记录详细的错误信息到日志
2. 继续处理其他文件，不会因单个文件失败而中断整个处理过程
3. 在处理完成后提供处理成功的文件数量统计
## 注意事项
- 插件默认会为类、方法、参数、返回值和异常添加Javadoc注释
- 如果已存在注释，插件不会覆盖，只会补充缺失的部分
- 可以通过配置选项关闭不需要的注释类型