Javadoc 与文档

可运行的代码只是 half 交付；Javadoc 把公共 API 的契约、参数约束与示例写进源码，生成 HTML 站点供团队与下游引用。本课衔接 java-core-essentials 的包与可见性，为 spring-boot-essentials 里的 OpenAPI 文档提供「从注释到对外契约」的思维基础。

学习目标

• 为 public 类与方法编写符合规范的 Javadoc 块
• 用 Maven/Gradle 插件生成 HTML 文档站点
• 区分 Javadoc、README 与 OpenAPI/SpringDoc 的分工

注释规范示例

/**
 * 按 ISBN 查询图书；不存在时返回空 Optional。
 *
 * @param isbn 13 位 ISBN，不可为 null 或空白
 * @return 匹配的图书记录
 * @throws IllegalArgumentException 当 isbn 格式非法
 * @see BookRepository#findAllByAuthor(String)
 * @since 1.2
 */
public Optional<Book> findByIsbn(String isbn) {
    Objects.requireNonNull(isbn, "isbn");
    if (isbn.isBlank()) {
        throw new IllegalArgumentException("isbn must not be blank");
    }
    // ...
}

常用标签：@param、@return、@throws、@see、@deprecated、@since。

类级与包级文档

/**
 * 图书领域服务：封装 CRUD 与库存校验。
 * <p>
 * 线程安全：实例无可变状态，可安全注入 Spring 容器。
 */
public class BookService { /* ... */ }

包级说明放在 src/main/java/com/example/book/package-info.java：

/**
 * 图书模块：实体、仓储与服务层。
 */
package com.example.book;

Maven 生成文档

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.6.3</version>
  <configuration>
    <doclint>all,-missing</doclint>
    <source>21</source>
  </configuration>
</plugin>

执行 mvn javadoc:javadoc，输出在 target/site/apidocs/。CI 可发布到 GitHub Pages 或内部 Wiki。

三种文档各管什么

类型	读者	内容
Javadoc	调用你库的 Java 开发者	公共 API、契约、示例
README	克隆仓库的人	构建、运行、贡献指南
OpenAPI	HTTP 客户端 / 前端	REST 路径、Schema、鉴权

Spring Boot 项目常用 springdoc-openapi 从 Controller 注解生成 OpenAPI；领域服务的 Javadoc 仍不可少。

练习

• 为 jev-ebean 的 BookService 公共方法补全 Javadoc，含 @param 与 @throws
• 运行 mvn javadoc:javadoc，修复 doclint 报的第一条 warning
• 写一段 {@code Optional<Book>} 内联示例，展示空结果时的调用方式

小结

Javadoc 是 Java 库的专业名片；生成站点只需一条 Maven 命令。 下一课进入 Play Framework 的响应式 Web 模型。