企业官网建设流程全解析

写Javadoc这件事，很多人觉得它就是“给代码加个注释”，随手写两句、能过编译就行。但你只要接手过一个被反复阅读、被下游团队拿来当接口契约用的公共类库，就会明白：Javadoc写不好，比没有文档更坑人。它不只是注释，它是你的API对外呈现的面孔，是IDE悬停提示里用户第一眼看到的信息，也是团队新人最快理解设计意图的入口。

这篇文章我把Javadoc的格式规范从头到尾捋一遍，包含每个标签的适用场景、排版布局的硬性要求、完整的类级和方法级示例，以及我自己在生成文档和校验规范时踩过的坑。适合正在写公共组件、SDK、内部框架，或者单纯想把代码注释写到“能直接用”这个水准的人参考。

1. 为什么Javadoc格式规范值得认真对待

1.1 文档注释不是给人看的，是给工具和生态用的

我第一次意识到Javadoc格式规范的重要性，不是在IDE里写代码的时候，而是在用javadoc命令行工具生成站点的那个下午。工具把注释里的内容解析成HTML页面，每一个<p>标签、每一个@param都会被结构化地渲染出来。那一刻我才明白：Javadoc的格式不是学术要求，而是它本身就要被解析器消费的语法。一句话，文档注释是一种“半结构化数据”，你写的每一个标签、每一处换行、每一个句号，都会影响最终输出的质量。

所谓“格式规范”，本质上是为了让解析工具能正确识别注释里各个部分的语义，同时让人在阅读源码时保持一致的视觉节奏。这两点缺一不可。不规范的注释，工具也能强行解析，但生成出来的页面会怪模怪样，比如段落挤在一起、HTML标签被原样输出、@param参数名对不上方法签名——这些都属于格式问题。

1.2 格式规范和内容规范是两回事，但必须一起谈

内容规范说的是“该写什么”，比如方法的作用、参数含义、异常触发条件。格式规范说的是“怎么写”，包括标签顺序、主描述结构、HTML标签使用方式、缩进换行规则。不少人的注释内容很好，但格式乱糟糟的；还有一种情况是格式挺整齐，内容却空洞——光写了“构造函数”三个字，等于没写。

真正养成习惯以后，你会发现格式规范其实是帮助你把内容写完整的：当你按规矩列@param、@return、@throws时，你就会逼着自己把每个参数、每个边界情况都想清楚。格式是内容的结构化抓手。

2. Javadoc核心格式：从注释结构到布局规则

2.1 文档注释的基本结构：主描述区、标签区、内联标签

一个完整的Javadoc注释由三部分组成：第一部分是主描述区（main description），它以/**开头，到第一个块标签（block tag）为止；第二部分是块标签区（block tags），由一个个@开头的标签组成，每个标签独占一行；第三部分是分散在主描述里的内联标签（inline tags），形如{@link ...}、{@code ...}，它们可以出现在任意位置。

一个标准的方法注释长这样：

/** * 计算两个整数的最大公约数。 * * <p>使用欧几里得算法实现，时间复杂度为 O(log n)。</p> * * @param a 第一个整数 * @param b 第二个整数 * @return a 和 b 的最大公约数；如果两个参数都为 0，返回 0 * @throws IllegalArgumentException 如果 a 或 b 为负数 * @see #gcd(long, long) * @since 1.0 */ public static int gcd(int a, int b) { // ... }

注意这里的顺序：主描述放在最前面，然后是一个空行（以*空行形式体现），然后依次排列@param、@return、@throws、@see、@since。这个顺序不是死规矩——Javadoc规范本身对块标签顺序没有强制约束，但社区约定俗成的顺序是有逻辑的：先输入（参数），再输出（返回值），再异常，最后是关联说明和版本信息。按这个顺序写，读者读起来的心理负担最小。

2.2 排版布局的硬性规则与缩进细节

格式规范里最容易翻车的点，其实是排版。

第一，/**与*/之间的每一行，都必须以*开头，且*前面的空格在标准工具下建议统一成1个空格。虽然JDK的解析器容忍不写*的纯文本行，但混排会让源码极其难看。市面上所有IDE的自动生成模板都遵守“每行一个星号+一个空格”的规则，不要自作聪明。

第二，主描述结束、块标签开始之前，一定要有一个空行——这条空行的形态是在星号后面不加任何内容。如果不加这个空行，解析器会把@param当作主描述的一部分，导致整个标签区域失效。应用实践中我还见过一种更隐蔽的错误：@param和前面的行之间没有空行，但上一行又恰好是<p>标签，结果页面渲染时参数描述和正文黏在一起，阅读体验很差。

第三，块标签之间不是必须空行，却推荐空行。比如多组@param之间不空行是合规的，但视觉上会挤成一块。我一般在@param组和@return之间空一行，这样层次分明。

第四，关于<p>标签的使用：Javadoc会把主描述视为HTML片段渲染，所以段落之间不能靠换行分隔——普通换行在HTML渲染中被忽略，必须显式写<p>。在JDK 8以后，官方风格建议是写<p>而不是<p>，这样可以避免把下一个段落吞进上一个段落。

关于换行缩进，Javadoc官方并不强制“各标签描述必须对齐”，但在实际工程中，同一组@param的描述文字首列对齐，会大幅提升阅读效率。我习惯把参数名与描述之间用两个或四个空格隔开，并保持对齐：

/** * @param name 用户姓名 * @param age 用户年龄，必须大于 0 * @param description 用户备注，允许为空 */

2.3 主描述区的写作格式：首字母大写、以句号结尾、用第三人称

格式规范里最容易忽略的是文字本身的写法。主描述要求使用完整的陈述句，首字母大写、以句号结尾。这一点很多中文工程师不习惯，因为中文句号也可以收尾，但Javadoc作为源自英文生态的规范，建议统一用英文句号。哪怕是纯中文描述，末尾也建议加英文句点，这是文档生成时判断“主描述是否结束”的辅助信号。

从语法角度，方法的主描述应该用第三人称，而不是祈使句。比如“计算两个整数的最大公约数”是对的，“计算两个整数的最大公约数！”是错的；“返回当前列表的大小”是对的，“返回当前列表的大小”依然对，但“请返回当前列表的大小”就显得翻译味太重。这些细节看似无关紧要，但在大量注释堆积后，会形成一种统一的“文档语感”，也会让生成出来的API文档显得专业很多。

3. 常用Javadoc标签详解与完整示例

3.1 类级注释：@author、@version、@since的正确用法

类级别的Javadoc是整个类所有成员注释的基调。它的主描述应该回答三个问题：这个类是什么、它能做什么、使用它需要注意什么。

package com.example.cache; /** * 基于 LRU（最近最少使用）策略的本地缓存实现。 * * <p>该缓存是线程安全的，内部通过 {@link java.util.concurrent.locks.ReentrantLock} * 保证并发访问的一致性。当缓存条目数超过 {@link #maxCapacity} 上限时， * 最久未使用的条目将被自动淘汰。</p> * * <p>使用示例：</p> * <pre>{@code * LruCache<String, String> cache = new LruCache<>(100); * cache.put("key", "value"); * String value = cache.get("key"); * }</pre> * * @author zhangwei * @version 1.2.0 * @since 1.0 */ public class LruCache<K, V> { // ... private final int maxCapacity; // ... }

类级注释中，@author和@version会被Javadoc工具收集并显示在页面顶部。多人协作的项目，@author要不要写、写谁，每个团队的策略不同，但格式上只要记住：一个@author可以对应一个名字，多位主要贡献者可以用多个@author标签分行写。

@since最常见的使用场景是标记引入该API的版本号——比如某个方法是在1.2版本才加的，@since 1.2会让调用方明确知道自己的依赖版本是否够用。这个标签在提供公共SDK时尤其重要，内部项目可以视情况简化。

类级注释里还有一个容易被忽略的细节：要区分{@link #maxCapacity}和{@link java.util.concurrent.locks.ReentrantLock}。前者的#号表示引用当前类中的成员，后者的全限定名表示引用外部类。这个语法规则我后面专门讲。

3.2 方法级注释：@param、@return、@throws的协作与边界

方法注释是整个Javadoc体系里最核心的部分。@param描述参数，@return描述返回值，@throws描述异常。三者加起来，应该能完整覆盖一个方法的输入、输出和异常面。

对于@param，规范要求：每一个方法参数都应有对应的@param标签，顺序应与方法签名一致。参数名必须精确匹配——这是被IDE校验器检查的行为，名字对不上，工具会直接报错。对于泛型方法，@param既能描述泛型类型参数（如<T>），也能描述普通参数，建议先描述泛型参数、再描述方法参数。

/** * 将列表中的元素按指定转换器映射为新的列表。 * * @param <T> 输入元素类型 * @param <R> 输出元素类型 * @param list 输入列表，不能为 {@code null} * @param mapper 转换器，将 {@code T} 转换为 {@code R} * @return 映射后的新列表，顺序与输入列表一致 * @throws NullPointerException 如果 {@code list} 或 {@code mapper} 为 {@code null} * @since 1.3 */ public static <T, R> List<R> map(List<T> list, Function<T, R> mapper) { Objects.requireNonNull(list); Objects.requireNonNull(mapper); List<R> result = new ArrayList<>(list.size()); for (T item : list) { result.add(mapper.apply(item)); } return result; }

@return标签数量一定是一个——这点和@param不同。返回值描述应当明确说明返回的对象是什么，以及在边界情形下的返回值。比如“返回索引从0开始、首次出现位置；如果不存在返回-1”，这种描述才算完整。另一个容易翻车的点是：如果方法返回值是void，那就不要写@return，JDK的javadoc工具会为这个输出一个warning。

@throws需要描述“什么情况下会抛出什么异常”，而不是简单罗列异常类型。规范要求与方法的throws声明的一致——方法签名里有了受检异常，注释里一定要写；方法签名里没有，但是如果运行时一定会在某些输入下抛出未受检异常，也应该写。写@throws时有两条经验：一是说明触发条件时尽量用参数名，二是多个@throws按异常类型名的字母序排列，阅读者查找起来最省力。

3.3 内联标签：{@link}、{@code}、{@inheritDoc}的使用场景

块标签解决的是“独立区块的信息结构化”，内联标签解决的则是“在句子内部嵌入代码风格文字和跳转链接”。

先说{@code}。它把内容渲染成等宽字体，同时自动对HTML字符做转义。所有出现在Javadoc里的代码片段、类名、方法名、字段名、参数名，都应该用{@code}包裹起来。不用它的后果是：注释里的<T>或Map<String, String>会被HTML解析器当成标签处理，轻则渲染错乱，重则整个页面结构崩掉。

再是{@link}。它分为两种情况：

• {@link #method(paramTypes)}：引用当前类中的成员，#前可省略类名。
• {@link com.example.Foo#bar()}：引用外部类成员，需要全限定类名。

还有一种形式叫{@linkplain}，它和{@link}的区别仅在链接文字的渲染字体上，{@link}默认用等宽字体，{@linkplain}则用普通字体。如果不希望链接文字看起来像代码，就用{@linkplain}。

值得注意的是，{@link}不是块标签，它可以和自然语言混排，但标签区块内也允许使用。例如@see后面跟一个{@link #repeat(String, int)}是完全合规的。

{@inheritDoc}是我见过使用率最低、但实际价值极高的内联标签。它用于子类Override方法或接口实现类的注释中，表示“继承父类/接口方法的注释内容”。当你实现一个接口方法，而接口方法已经有完整、精良的Javadoc时，实现类里完全可以简写：

/** * {@inheritDoc} * * <p>此外，本实现额外保证返回值列表是不可变的。</p> */ @Override public List<String> getNames() { return Collections.unmodifiableList(names); }

这么写的好处很直接：父接口注释如果更新，实现类的文档会同步更新，你不用维护两份。但要注意，{@inheritDoc}不是万能灵药，它用在接口方法上的行为（继承父接口注释）、用在类方法上的行为（继承父类注释）有些微差别，建议先在一个小试验项目里验证一遍再推广。

3.4 完整的类、方法、字段三级示例

把上面的知识点串起来，我写一个比较完整的示例：一个带泛型、继承关系、内部类、常量和构造方法的类。

package com.example.car; /** * 交通工具抽象基类。 * * <p>所有交通工具都具备启动、停止和获取当前速度的能力。 * 子类必须实现 {@link #start()} 和 {@link #stop()} 方法， * 并在实现中维护内部状态一致性。</p> * * <p>本类自 1.1 版本起支持序列化。</p> * * @author zhangwei * @version 2.1.0 * @since 1.0 */ public abstract class Vehicle implements Serializable { private static final long serialVersionUID = 1L; /** 默认最大速度，单位 km/h。 */ protected static final int DEFAULT_MAX_SPEED = 180; /** 当前速度，单位 km/h。 */ private int speed; /** * 构造一个新的交通工具实例。 * * @param initialSpeed 初始速度，单位 km/h，必须大于等于 0 * @throws IllegalArgumentException 如果 {@code initialSpeed} 为负数 */ public Vehicle(int initialSpeed) { if (initialSpeed < 0) { throw new IllegalArgumentException("初始速度不能为负数"); } this.speed = initialSpeed; } /** * 启动交通工具。 * * <p>启动后，车辆进入可行驶状态。重复调用不会产生副作用。</p> */ public abstract void start(); /** * 停止交通工具。 * * <p>停止后，车辆速度将被重置为 0。</p> */ public abstract void stop(); /** * 获取当前速度。 * * @return 当前速度，单位 km/h，始终大于等于 0 */ public int getSpeed() { return speed; } }

注意一个细节：字段注释虽然是Javadoc，却通常不写@param、@return这些块标签，只写描述。常量的字段注释一般说明单位、取值范围、用途。serialVersionUID这类序列化字段的注释尤为重要，因为长期维护时，它是排查序列化兼容性问题的关键线索。

还有一种情况：方法参数特别多的场景下，格式规范容易失控。比如一个构造函数有6个参数，一种推荐的排布方式是把每个参数单独一行，并用对齐空格让视觉整齐。如果参数描述很长，我建议使用“参数名——描述”的破折号格式，避免大家在阅读时产生歧义。

4. 从生成到校验：Javadoc工具使用与规范验证

4.1 用命令行生成文档：jdk自带工具的最简用法

写了规范注释，最终要去验证。JDK自带的javadoc命令就是最直接的校验器。一个最简单的生成命令：

javadoc -d docs -encoding UTF-8 -charset UTF-8 \ -sourcepath src/main/java \ -subpackages com.example.util

这条命令做了四件事：指定输出目录docs、指定源码编码为UTF-8（不指定的话，中文注释在Windows平台上经常乱码）、指定源码根路径、指定要扫描的包。-subpackages表示递归扫描com.example.util下的所有子包。

如果你只校验注释格式、不关心生成的HTML页面，可以加上-Xdoclint参数。这个参数从JDK 8开始引入，专门检查Javadoc中的格式错误。它对缺失@param、错误参数名、无法解析的{@link}、未闭合HTML标签等会报出warning，在CI里非常适合用来做规范门禁：

javadoc -Xdoclint:all -d docs -encoding UTF-8 -sourcepath src/main/java com.example.util

-Xdoclint:all打开所有检查项。实测下来，它对“参数名对不上”“返回值为void却写了@return”“无效的@throws类型”这类问题非常敏感，是规范检查的第一道关。

4.2 在IntelliJ IDEA里使用Javadoc生成器

平时写代码时，没人会为了看注释效果反复敲命令行。IDEA自带Javadoc生成界面，入口在菜单Tools -> Generate JavaDoc。要注意的配置项就三个：

• Output directory选择生成目录；
• -encoding和-docencoding都填UTF-8，否则中文注释生成HTML后大概率乱码；
• Other command line arguments建议填上-Xdoclint:all -quiet，让IDEA在生成时顺手做格式校验。

还有一个更轻量的用法：IDEA在编写代码时会实时检查Javadoc格式，在Preferences -> Editor -> Inspections -> Java -> Javadoc里可以开启相关检查项。我一般把Declaration has Javadoc problems设为Error级别，这样IDE会直接把@param名字写错、{@link}解析失败这类问题标红。

4.3 把规范校验塞进CI

格式规范真正落地，靠人自觉是靠不住的。我在团队里做的方法是：在Maven构建中配置maven-javadoc-plugin，并开启doclint校验：

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>3.6.3</version> <configuration> <doclint>all</doclint> <encoding>UTF-8</encoding> <failOnError>true</failOnError> <failOnWarnings>true</failOnWarnings> </configuration> <executions> <execution> <goals> <goal>jar</goal> </goals> </execution> </executions> </plugin>

failOnWarnings设为true之后，任何一条格式warning都会导致构建失败。刚开始推行时一定会有大量报错，我的建议是先关掉failOnWarnings只开failOnError，等存量代码清理完毕再收紧。

用Gradle的项目可以配置javadoc任务的options.addStringOption('Xdoclint', 'all')，效果等价。

5. 常见格式错误与排查技巧实录

5.1 高频格式错误速查表

这几类问题是我在代码评审和CI报错中见得最多的，整理成了一张速查表。

5.2 三个必须留意的编译期与生成期坑

第一个坑是老版本JDK与<p>语法的兼容问题。JDK 6、7时代的模板普遍写<p>而不闭合，到了JDK 8以上doclint开启后会报HTML警告。团队切JDK版本时，这类存量注释会成片爆warning，处理起来很费劲。

第二个坑是中文注释与编码。Windows平台默认编码是GBK，源码如果是UTF-8，在命令行直接跑javadoc不加-encoding UTF-8就会乱码。我一直维持一个习惯：src/main/java下的所有文件都用UTF-8，git的core.autocrlf也要保持稳定，避免编码问题在团队协作里隐身乱窜。

第三个坑是{@inheritDoc}在接口多继承层级中的行为。如果一个接口继承自两个父接口，且两个父接口的同名方法都有@inheritDoc标记，子接口的注释内容可能来自任意一方，行为取决于工具的具体实现。所以公共API设计时，尽量避免在多根接口继承结构里依赖{@inheritDoc}。

5.3 我用顺手的几个校验辅助手段

除了命令行doclint，我日常还有两个辅助工具。一是在IDEA里用Code -> Inspect Code对整个模块跑一遍，它会额外发现一些doclint发现不了的逻辑问题；二是对比较重要的公共类，我会定期生成HTML文档并用grep扫描页面里的Error和Warning字样，这个方法虽然原始，但能直观看到外部读者最终看到的效果。

另外一个非常实用的小技巧：写注释时多用{@code}包裹参数名。因为HTML渲染器对纯文本里的某类符号处理不可控，凡是“格式敏感”的字符全部交给{@code}转义，就不会出乱子。这个习惯我从写第一个公共SDK时就养成了，至今没有一次因为渲染问题被下游吐槽过。

我个人在实际操作中的体会是：Javadoc格式规范看起来是给人定的规矩，实际上它是在给Javadoc解析器、IDE提示、API文档站点这些工具生态定契约。你在注释上的每一点投入，最终都会通过IDE悬停提示、生成的HTML文档、团队成员的理解速度这些渠道返还回来。把格式规范练成肌肉记忆以后，写注释的速度不会比随手敲慢多少——真正慢的是那些“把注释当装饰”的项目，它们往往在半年后就得用十倍时间反向考古。如果这篇文章对你有一点用，不妨现在就从手头一个公共类的注释开始，给它补齐主描述、对齐参数、加上<p>段落，然后用doclint跑一遍。你会发现自己写代码的“交付感”完全不一样了。