一个 jar 包的自我修养

遇到槽点

开发实践中，对于开发一个 jar 包，很多人都只是完成功能，只要功能使用没问题，就算是完事了，但其实远远不够。当用户使用 jar 包的时候，可能会遇到以下这些问题：

1. 文档缺失，一个功能怎么用，往往需要花半天到一天的时候到处找负责人，一步步沟通，很浪费时间；

2. 依赖冲突，我只是引用了一个用户认证包，结果把它支持的 SpringMVC、Jersey 和 Struts2 全引进来了；

3. 获取不到方法参数名，一个有三个 String 类型参数的接口方法，我得对着着文档才能知道它们分别是什么意思，没有文档就得找负责人沟通或者自己一个个猜了；

4. 跟 Spring 整合很不友好，例如初始化配置强制要求文件全路径；

因为经常会遇到这样的槽点，我在写公共组件包的时候会特别留心。

在这里我总结出了以下七点改进建议，如果你也要提供 jar 包给其他人使用，可以参考。提升自己，方便他人。

文档

作为一个公共的 jar 包，很多项目都会使用到，如果没有文档，那么每次有人要用的时候就会找我们沟通，这样即浪费自己的时间也会浪费大家的时间。而且用的人越多，我们会发现，问题永远都是这些：这个怎么用？你支持多种实现方式，我要选择哪一种？如何申请？

如果你有一份简单文档就可以解决绝大多数的问题。

一份合格的文档应该包含如下内容：

1. 一句话描述本模块的功能

2. 快速开始，展示如何最简单地开始使用

3. 注意事项及常见问题

4. 负责人联系方式

一定要及时更新文档，如果有文档中没有说明的问题，用户找我们解决了，记得要将这个问题和解决方法记录在常见问题中，避免重复解决相同的问题。

一份文档，说到底是为自己减轻工作量。试想，如果天天有人因为一些“鸡毛蒜皮的小事”来各种询问，我们又不得不花很多时间去沟通，有时沟通不好还会伤和气。提供一份文档，大家就都省事了。

最小依赖

如无必要，勿引依赖。若有必要引入，但是并非必须，记得使用 provided。

例如，我们的 jar 包提供了快速整合 Spring 的功能，为此，我们需要添加 Spring 相关依赖，但是这个依赖是可选的，那么可以这样设置:

1. <dependency>

2. <groupId>org.springframework</groupId>

3. <artifactId>spring-context</artifactId>

4. <version>5.1.8.RELEASE</version>

5. <scope>provided</scope>

6. </dependency>

加上 provided 意味着打包的时候不会将这个依赖加入到 jar 包中，而是需要使用者自己引入。

一个小小的设置，带来的好处就是，如果这使用者不打算与 Spring 整合，那么他就不会间接地引入 Spring 的依赖了。这在一个大工程中相当重要，当一个项目中的外部依赖多了之后，外部依赖之间如果存在冲突，解决起来将会相当棘手。

附上源码

不知道你有没有过这样的经历：引用了一个 jar 包，准备开始使用的时候，代码提示全是 var1, var2, var3 这种的，点进去一看，傻眼了：

这时 IDEA 还亲切地问你，要不要下载源码(Download Sources)看一下？你满心期待了点了 Download！结果：

下载不了来问我要不要下载？玩我？

试想一下，这时你的用户在用你的 jar 包的时候会不会也是这样吐槽。那么怎么解决呢？

其实很简单，只要在 pom 文件中添加 maven-source-plugin 插件即可。

1. <!--配置生成源码包-->

2. <plugin>

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

4. <artifactId>maven-source-plugin</artifactId>

5. <version>3.0.1</version>

6. <executions>

7. <execution>

8. <id>attach-sources</id>

9. <goals>

10. <goal>jar</goal>

11. </goals>

12. </execution>

13. </executions>

14. </plugin>

这样就可以在编译时添加源码包，当发布到maven仓库时，也会自动带上源码。用户在使用 IDEA 的时候也就可以直接下载并关联源码了。因为关联上源码，我们写在上面的注释也可以被使用者看见，这可比文档好用得多哦！

-parameters 参数

Java8 的反射中添加了 Parameter 类，让我们能在程序运行期间通过反射获取到方法参数信息，包括参数名。但是需要在程序编译的时候添加 -parameters 参数。做为一个 jar 包，如果我们在编译的时候没有加这个参数，那么用户将永远无法通过反射获取到参数名称！这在某些场合下，可能会造成很大的不便。

其实，添加 -paramters 参数非常简单，我们只需要在 pom 文件中添加 maven-compiler-plugin 插件，并且将 parameters 设置为 true 即可：

1. <plugin>

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

3. <artifactId>maven-compiler-plugin</artifactId>

4. <version>3.8.0</version>

5. <configuration>

6. <source>${java.version}</source>

7. <target>${java.version}</target>

8. <parameters>true</parameters>

9. <encoding>UTF-8</encoding>

10. </configuration>

11. </plugin>

面向接口编程

做为一个公共 jar 包，我们是要对各个工程提供一个通用功能的，而这些功能一旦提供出去，需要保证兼容性，否则每次升级都将困难重重。

因此，我们应该与使用者订立“协议”，即面向接口编程，宣告“我给大家提供这些能力，并且为之负责，你们无需关注我的底层实现，只需要按照协议使用即可”。在接口注释中注明使用的场景和注意事项，因为我们前面添加了源码包，因此使用者可以直接关联并查看到我们写下的注释，例如：

更极致的做法是我们只对接口负责。我们可以隐藏实现类（将实现类设置为包级私有的），然后通过工厂方法提供接口的实现，而不是让用户自己 new。

这样做之后，将来如果我们需要扩展，或者随着技术的升级，我们需要更换底层实现时，无需担心实现类中的兼容问题，只需要提供一个新的实现相同接口的实现类，让工厂方法返回新的实现即可。而且旧的实现类，我们可以随时删除，减少历史包袱！

包级私有的实现类：

多种配置传入方式

每个 jar 包基本都会有自己的一些配置，这些配置如何初始化，也有很多讲究。我遇到最不靠谱的做法就是要求必须提供文件的绝对路径，甚至有些只支持默认绝对路径不支持自定义！

因为遇到很多这样奇葩的包，因此在写 jar 包的时候都会特别留意。

总结起来，我们应该提供如下三种配置的初始化方式:

1. 文件路径，必须支持 classpath: 前缀，代表从类路径中加载

2. InputStream，支持从流中读取

3. 自定义的 Config 类，包含所有需要用到的配置项，并设置默认值

其中第三种，自定义的 Config 类，是最推荐的做法。

以上面的客户端为例，我们可以提供这样三个构造器：

1. RocketMqEventClient(Config config) {

2. this.config = config;

3. client = new RocketMqClient();

4. }

6. RocketMqEventClient(InputStream in) {

7. init(in);

8. }

10. RocketMqEventClient(String filePath) {

11. if (filePath == null || filePath.trim().isEmpty()) {

12. throw new IllegalArgumentException("文件路径不能为空");

13. }

14. if (filePath.startsWith(CLASSPATH)) {

15. // 从类路径中加载

16. String path = filePath.replaceFirst(CLASSPATH, "");

17. try (InputStream in = RocketMqEventClient.class.getClassLoader().getResourceAsStream(path)) {

18. init(in);

19. } catch (IOException e) {

20. throw new IllegalArgumentException("配置文件读取失败: " filePath, e);

21. }

22. } else {

23. // 直接读取文件路径

24. try (InputStream in = new FileInputStream(filePath)) {

25. init(in);

26. } catch (IOException e) {

27. throw new IllegalArgumentException("配置文件读取失败: " filePath, e);

28. }

29. }

30. }

32. private void init(InputStream in) {

33. config = new Config(in);

34. client = new RocketMqClient();

35. }

然后在工厂类中支持这几种参数类型：

1. /**

2. * 事件客户端工厂

3. *

4. * @author dadiyang

5. * @since 2019-06-29

6. */

7. public class EventClientFactory {

8. /**

9. * 创建默认的事件客户端

10. *

11. * @param config 各个配置项

12. * @return 默认的事件客户端

13. */

14. public static EventClient createClient(Config config) {

15. return new RocketMqEventClient(config);

16. }

18. /**

19. * 创建默认的事件客户端

20. *

21. * @param in 配置文件输入流

22. * @return 默认的事件客户端

23. */

24. public static EventClient createClient(InputStream in) {

25. return new RocketMqEventClient(in);

26. }

28. /**

29. * 创建默认的事件客户端

30. *

31. * @param filePath 配置文件路径，支持 classpath: 前缀

32. * @return 默认的事件客户端

33. */

34. public static EventClient createClient(String filePath) {

35. return new RocketMqEventClient(filePath);

36. }

37. }

支持 Spring @Enable 模式

随着 SpringBoot 越来越流行，starter 这种配置方式让我们感受到原来整合第三方依赖可以这么简单。如果我们的 jar 包也支持 starter 肯定很酷，但是我一般会考虑到很多项目不是使用 SpringBoot 构建，而是传统的 Spring 项目，为了兼顾这些项目，其实我们可以采用 @Enable 模式，它与 starter 之间只是多了一个注解。我们只需要这么做：

1. 引入 spring-context 依赖，注意加上 provided

2. 在我们自定义的 Config 类的字段上使用 @Value 注解，自动从 Spring 上下文注入配置项

3. 增加 XxxConfiguration 类，注册 Bean

4. 增加 @EnableXxx 注解，并导入刚刚定义的配置类 @Import({Config.class, XxxConfiguration.class})

以前面的事件客户端为例，可以这样做：

1. 引入 spring-context

1. <dependency>

2. <groupId>org.springframework</groupId>

3. <artifactId>spring-context</artifactId>

4. <version>5.1.8.RELEASE</version>

5. <scope>provided</scope>

6. </dependency>

1. 为 Config 配置类的字段添加 @Value 注解

1. @lombok.Data

2. public class Config {

3. @Value("${event.mq.namesrvaddr}")

4. private String rocketMqNameSrvAddr;

5. @Value("${event.mq.clientName}")

6. private String rocketMqClientName;

7. @Value("${event.mq.subject}")

8. private String subject;

9. @Value("${event.mq.pool.maxSize}")

10. private int maxPoolSize;

11. }

1. 添加 EventClientConfiguration 类

1. /**

2. * 事件客户端自动装配配置类

3. *

4. * @author dadiyang

5. * @since 2019-06-29

6. */

7. @Configuration

8. public class EventClientConfiguration {

9. @Bean

10. public EventClient eventClient(Config config) {

11. return EventClientFactory.createClient(config);

12. }

13. }

1. 添加 @EnableEventClient 注解

1. /**

2. * 启用事件客户端模块

3. *

4. * @author dadiyang

5. * @since 2019-06-29

6. */

7. @Documented

8. @Target(ElementType.TYPE)

9. @Retention(RetentionPolicy.RUNTIME)

10. @Import({Config.class, EventClientConfiguration.class})

11. public @interface EnableEventClient {

12. }

有了这个注解之后，使用者如果与 Spring 整合的话，只需要在带有 @Configuration 注解的类上标注 @EnableEventClient，然后就可以 @Autowired 自动注入我们的 EventClient 类了！

如果团队全部都使用 SpringBoot 进行开发，也可以提供一个 starter。

总结

处处留心皆学问，一个 jar 包原来还有这么多事情可以做。

总结起来，我们在开发一个通用 jar 包的时候，除了基本功能之外，应该考虑以下七条改进建议：

• 文档。节省沟通成本，你好我也好;

• 最小依赖。如无必要勿加依赖，可选依赖添加 provided;

• 附上源码。代码本身就是最好的文档，加上 maven-source-plugin 就搞定;

• 编译时加上 -parameters 参数。支持 Java8 的Parameter类反射获取参数名;

• 面向接口编程。对且只对契约负责，隐藏实现，方便将来更换实现又保持兼容性;

• 多种配置传入方式。让使用者以最方便的方式提供配置;

• 支持 Spring @Enable 模式。一个注解，快速整合 Spring;

来源：https://www.icode9.com/content-4-306101.html