为什么我打的jar包没有注解？
本文来自网易云社区
作者：王飞
一、前言
一切问题的起源就是来自一个问题“为什么我打的jar包没有注解？”，带着这个疑问查了一圈资料，原来问题主要是在没有将源码中的注释进行抽取打包，自然我们在引用jar包的时候，无法获得注解。
二、让maven发布带上注解
这个方法很简单，只需在build->plugins下面中增加javadoc的插件来打包资源包，这样打包的时候就会额外增加一个以javadoc结尾的jar包。javadoc的组件添加源码如下：
<!--配置生成Javadoc包--><plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>2.10.4</version> <configuration> <encoding>UTF-8</encoding> <aggregate>true</aggregate> <charset>UTF-8</charset> <docencoding>UTF-8</docencoding> </configuration> <executions> <execution> <id>attach-javadocs</id> <goals> <goal>jar</goal> </goals> </execution> </executions></plugin>
三、什么是javadoc
javadoc居然可以解决jar包中代码注释的问题，那么什么是javadoc呢？ 百度百科中的解释是：javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。 javadoc的注解方式是有一定格式的，常用的注解方式有
| 标签 | 说明 | JDK 1.1 doclet | 标准doclet | 标签类型 |
|---|---|---|---|---|
| @author 作者 | 作者标识 | √ | √ | 包、 类、接口 |
| @version 版本号 | 版本号 | √ | √ | 包、 类、接口 |
| @param 参数名 描述 | 方法的入参名及描述信息，如入参有特别要求，可在此注释。 | √ | √ | 构造函数、 方法 |
| @return 描述 | 对函数返回值的注释 | √ | √ | 方法 |
| @deprecated 过期文本 | 标识随着程序版本的提升，当前API已经过期，仅为了保证兼容性依然存在，以此告之开发者不应再用这个API。 | √ | √ | 包、类、接口、值域、构造函数、 方法 |
| @throws异常类名 | 构造函数或方法所会抛出的异常。 | √ | 构造函数、 方法 | |
| @exception 异常类名 | 同@throws。 | √ | √ | 构造函数、 方法 |
| @see 引用 | 查看相关内容，如类、方法、变量等。 | √ | √ | 包、类、接口、值域、构造函数、 方法 |
| @since 描述文本 | API在什么程序的什么版本后开发支持。 | √ | √ | 包、类、接口、值域、构造函数、 方法 |
| {@link包.类#成员 标签} | 链接到某个特定的成员对应的文档中。 | √ | 包、类、接口、值域、构造函数、 方法 | |
| {@value} | 当对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值。 | √(JDK1.4) | 静态值域 |
此外还有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、{@code} {@value arg}几个不常用的标签，由于不常使用，我们不展开叙述，感兴趣的读者可以查看帮助文档。
注释非常重要，不能随意增加或者修改成其他内容，否则会只是报错，打包不通过。如果一个类或者方法前增加了注解，且方法中存如param，return 或者throws时，注解中不添加的话也是会抛出警告的。所以注解要加的清晰易懂且符合规范。更多的关于javadoc的注解使用，可以通过参考资料查看其它更丰富的内容。
虽然javadoc能解决大部分的代码注释问题，但像是在代码方法中的注解呢？这个要是也想分享出来，靠javadoc就比较困难了。
四、引出的另外一个问题，如何让别人可以通过maven获取的源码
伴随着注释打包发布的更高需求的打包就是将源码一同打包。那么如何在maven仓库发布的时候，可以将自己的源码发出去呢？这个就需要我们maven的另一个插件了——sources。 和javadoc一样，只需在build->plugins下面中增加sources的插件来打包资源包，这样打包的时候就会额外增加一个以sources结尾的jar包。sources的组件添加源码如下：
<!--配置生成源码包--><plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-source-plugin</artifactId> <version>3.0.1</version> <executions> <execution> <id>attach-sources</id> <goals> <goal>jar</goal> </goals> </execution> </executions></plugin>
将源码也打包发布后，对方在调用我们jar报的时候，可以通过IDEA可以手动加载源码，查看更多的代码内容，而不是只能通过反编译的代码去看，没有任何的注解，要是代码质量不是太高的话，对方是很难理清头绪的。
五、最终效果
打包完成后的样子
maven仓库中的样子
IDEA中的样子
参考资料
网易云免费体验馆，0成本体验20+款云产品！
更多网易研发、产品、运营经验分享请访问网易云社区。
相关文章：
【推荐】 react技术栈实践（1）
【推荐】 JVM锁实现探究2：synchronized深探
【推荐】 适配的那些事
