编辑推荐

网易数帆开源API网关与容器云项目，让云原生生产落地“多快好

网易汪源：统一负载与多云环境的“开放姿态”，才是云原生

网易数帆如何用 Kubernetes“原语”搞定云原生中间件

快手打新挤爆券商系统，网易数帆推出券商稳定性保障方案

探索智慧校园新模式，网易有数在教育行业的实践分享

金融行业大数据治理之路——数据模型篇

为什么我打的jar包没有注解？

勿忘初心2018-10-15 13:25

本文来自网易云社区

作者：王飞

一、前言

一切问题的起源就是来自一个问题“为什么我打的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可以手动加载源码，查看更多的代码内容，而不是只能通过反编译的代码去看，没有任何的注解，要是代码质量不是太高的话，对方是很难理清头绪的。