javadoc生成文檔API以及解決lombok註解沒有字段生成問題

將Lombok註解應用到一個項目中可以大大減少在IDE中生成或手工編寫的樣板代碼行數。
這樣可以減少維護開銷，減少bug，提高類的可讀性。

在idea中要使用lombok是很簡單的事情，只需要安裝一個lombok plugin，然後在pom.xml加入對lombok的依賴即可。

			<dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>1.18.4</version>
            </dependency>

與任何技術選擇一樣，使用Lombok既有積極的作用，也會有消極的影響。而最典型的不好的一面就是，將源代碼生成javadoc的時候，因爲源碼裏邊使用了lombok，只聲明瞭private的屬性，而未編寫setter/getter方法等，最後生成的文檔當然就不會包含這些屬性的getter和setter方法。先通過一個簡單的例子復現一下這個場景。

一、問題重現
要用idea生成javadoc，需要引入javadoc的plugin，在pom.xml中加入引入即可。詳情可參見官網。

1、我們用idea創建一個lombok的示例項目，pom.xml是這樣的：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
 
    <groupId>com.dengxiaolong</groupId>
    <artifactId>lombok</artifactId>
    <version>1.0.0</version>
 
    <dependencies>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.2</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
 
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

利用lombok定義一個簡單的DTO類如下：

package com.dengxiaolong.lombok;
import lombok.Data;
@Data
public class FooDto {
private int id;
private String name;
private String email;
}

2、引入依賴後，點擊idea的右側，就可以看到javadoc的相關命令了。我們雙擊執行”javadoc:javadoc”這個命令即可。

執行完成後，會在項目的target/site/apidocs/目錄重生成javadoc。點擊查看會發現GiftVo類中的字段id、name、email都沒有出現在javadoc中。

二、成本和收益
對於Lombok的成本和收益，在Lombok的官網的文章中，做了詳細地介紹，爲了解決Lombok帶來的問題，官方也提供了相應的***解決方案——delombok***，它的作用就是將Lombok的註解還原成等效的源代碼。可以通過命令行使用：

java -jar lombok.jar delombok src -d src-delomboked

當然，也可以通過ant任務來實現。不過，本文要探討的還是基於idea來解決這個問題。

使用delombok
既然提供了delombok，那麼我們就可以考慮通過它來生成源代碼，然後再想辦法讓javadoc來通過源代碼的目錄生成javadoc，這樣我們就能一方面享受lombok的好處，一方面又能避免它帶來的問題了。

至此，我們可以這樣來完成我們的目標了：

1、要使用delombok，我們需要配置一個lombok的maven插件到pom.xml：

<build>
    <plugins>
        ...
        <plugin>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok-maven-plugin</artifactId>
            <version>1.18.0.0</version>
            <configuration>
                <encoding>UTF-8</encoding>
                <sourceDirectory>src/main/java</sourceDirectory>
            </configuration>
        </plugin>
  </plugins>
</build>
 

2、在右側Maven Projects裏邊找到”lombok:delombok”的任務，雙擊執行。執行成功後，會在target/generated-sources/delombok目錄生成的等效源代碼。

3、修改javadoc的源代碼目錄
delombok生成了一份新的等效源代碼後，我們就需要修改javadoc的源代碼的目錄了，同使用lombok的插件一樣，我們只需要在配置裏邊增加sourcepath的配置項即可。

sourcepath用來指定查找源文件(.java)的搜索路徑，可以通過用冒號(:)分隔多個路徑。

        ...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.0.1</version>
            <configuration>
                <sourcepath>target/generated-sources/delombok</sourcepath>
            </configuration>
        </plugin>
       ...

4、然後，我們再通過右側的Maven Projects執行javadoc:javadoc命令即可生成我們需要的javadoc文檔了。

打開index.html

經過上面delombok和javadoc對於源代碼目錄的巧妙組合，我們一方面減少了開發時的代碼量，另一方面也能保證javadoc生成的文檔的完整性。這樣一來，lombok就是非常完美的工具了。