把生命浪费在美好事物上

产品产品产品

358篇博客

最新博客

最新资源下载

编辑推荐

网易数帆开源API网关与容器云项目，让云原生生产落地“多快好网易汪源：统一负载与多云环境的“开放姿态”，才是云原生网易数帆如何用 Kubernetes“原语”搞定云原生中间件快手打新挤爆券商系统，网易数帆推出券商稳定性保障方案探索智慧校园新模式，网易有数在教育行业的实践分享金融行业大数据治理之路——数据模型篇

Nfit异常服务包易用性提升--将注释打入jar包步骤小记

把生命浪费在美好事物上2018-07-11 09:51

    一般来说，调用第三方jar包中的方法，除非添加本地源码库，否则是不能直接看到调用API的注释说明的，由于之前在本地使用我们发布的nfit java异常服务包都会关联到本地代码库，这样的话鼠标指向要调用的方法，会自动弹出来方法的注释以及参数的一些说明。

但是针对我们的用户来说，使用的是公司库上我们上传的jar包，本地并没有源码库，这时就会对接口的易用性打个折扣，要么需要下载nfit的接口文档。点击这个即可下载，但由于是在wiki维护的，更新需要手工修正，因此不一定能保证实时更新。如果将全部源码都打入包中让用户下载会导致包内容过大，冗余。因此，想到用javadoc的方式来解决这个问题。
目前现状如下，这里是模拟用户使用公司库中nfit-0.0.2包，可以看到只能看到该方法有两个参数，但不清楚这两个参数分别的含义，以及这个方法起到的作用：
pom.xml中设置如下：

  <dependency>

            <groupId>com.netease.qa.cloudqa</groupId>
            <artifactId>nfit</artifactId>
            <version>0.2.0</version>
        </dependency> 
       

最终效果我们想成为这样（以第三方包trilead-ssh2为例），鼠标滑到方法名称上就可以显示这个方法的注释信息了。

 

 开始动手吧，分为如下几个步骤：
1.在本地nfit代码工程库中生成javadoc。
首先，在nfit工程点右键，选择export，然后选择java->javadoc。

 

再点击Next->在javadoc command输入(jdk安装目录下找到javadoc.exe的绝对路径)：C:\Program Files\Java\jdk1.7.0_55\bin\javadoc.exe 在destination路径中选择javadoc输出的目录：D:\CODE\NFIT_NEW\NFIT_PACKAGE\docs。

然后一路next，这时需要注意一个编码问题，如果不指定utf-8的话，它默认使用GBK编码，这时候可能会出现错误，所以需要在VM option中作如下设置：

-encoding utf-8 -charset utf-8

点击finish即可生成最终的javadoc。

 

生成ok以后可以在docs目录下看到javadoc的页面。

点击docs目录下的index.html，可以看到这个包的javadoc首页，如下所示：

 2.将javadoc打包。
  本地现在看注释以及javadoc是没问题了，但是如何将这些信息打包进jar中并且发布呢。需要配置pom.xml中的javadoc插件：

需要注意pom.xml文件中需要加入javadoc的插件才能将生成的javadoc打包到jar中。

   

                 <plugin>

                <groupId>org.apache.maven.plugins</groupId>

                <artifactId>maven-javadoc-plugin</artifactId>

                <executions>

                    <execution>

                        <id>attach-javadocs</id>

                          <goals>

                            <goal>jar</goal>

                          </goals>

                     </execution>

                </executions>

            </plugin>

打包命令如下所示：mvn assembly:assembly -Dmaven.test.skip=true  package

打包成功，发现target路径中生成了2个jar包：一个就是原来的工程包，另外一个就是javadoc包。

3.使用本地包显示javadoc的配置方式。
如果提供给user使用方式是本地lib库的话，则需要配置两步，这里以nefs_test工程为例，想在nefs_test工程中使用nfit-0.0.3的方法并且想实时看到接口的注释信息，则需要配置以下两步：
1）将这两个生成好的jar包放到引用这些jar包的工程lib库中，并且配置pom.xml。
pom.xml中加入本地依赖包：

   <dependency>

             <groupId>com.netease.qa.cloudqa</groupId>

             <artifactId>nfit</artifactId>

             <version>0.3.0</version>

             <systemPath>${basedir}/lib/nfit-0.3.0-jar-with-dependencies.jar</systemPath>

             <scope>system</scope>

        </dependency>

 2）将工程依赖的本地包加入本地javadoc包即可。

右键点击该jar包点击properties->javadoc Location->javadoc in archive

Archive path中选择本地的nfit-0.3.0-javadoc.jar绝对路径，点击ok。

 这时再用鼠标划过调用到该jar包的接口，就可以显示接口的注释说明了。

 

4.将javadoc上传至公司库并使用的配置方式。
   另一种更简便的方式就是直接上传公司库，这样用户不需要手动下载jar包以及进行配置，只需要在pom.xml中配好远程依赖的坐标即可。
上传方式：mvn deploy -Durl=http://mvn.hz.netease.com/artifactory/libs-releases -DrepositoryId=artifactory -Dfile=NFIT-0.3.0.jar -DpomFile=pom.xml -DgroupId=com.netease.qa.cloudqa -DartifactId=NFIT -Dversion=0.3.0 -Dpackaging=jar  -Dmaven.test.skip=true
上传完就可以在公司库看到资源了。
 
用户使用的时候直接在pom.xml中配置如下内容即可使用，效果跟上面是一模一样的，也可以直接显示接口的注释说明。
         <dependency>
            <groupId>com.netease.qa.cloudqa</groupId>
            <artifactId>nfit</artifactId>
            <version>0.3.0</version>
        </dependency> 
总结：
    之前只知道javadoc是用来自动生成项目文档的，但却不知道它能代替源码起到显示注释的作用。这个需求也是使用nfit服务包的童鞋提出的，因为在我们本地有源码的情况下使用接口默认就会出来接口的注释，因此很容易忽略这个问题，因此多和用户交流才能帮助我们更好的改进，也希望我们的用户满意度能够越来越提升 ：）。
本文来自网易实践者社区，经作者崔晓晴 授权发布。


推荐博客