讲讲我和 Spring 创始级程序员共同 review 代码的故事

本文出自阿里巴巴中间件,作者:辽天,社区ID walking98,阿里巴巴技术专家,Apache RocketMQ内核控,拥有多年分布式系统研发经验,对Microsoft Messaging、Storage等领域有深刻理解。

讲讲我和 Spring 创始级程序员共同 review 代码的故事
© Duy Pham
RocketMQ-Spring毕业了。

作为Apache RocketMQ的子项目,经过6个多月的孵化,RocketMQ-Spring发布了第一个Release版本v2.0.1,通过使用Spring Boot的方式把RocketMQ的客户端进行封装,帮助用户通过简单的Annotation和标准的Spring Messaging API编写代码,来进行消息的发送和消费,以降低开发复杂度。

本文将以故事的形式,还原RocketMQ社区开发者和Spring社区创始工程师一同Review代码以及对代码进行改进的全过程,希望对做Spring Boot开发的同学有所帮助。

罗美琪?:RocketMQ社区开发者
春波特小哥?:Spring社区创始工程师


故事的开始


罗美琪有一套RocketMQ的客户端代码,负责发送消息和消费消息。听说春波特小哥善于消息发送,通过Spring Boot可以把自己客户端调用变得非常简单,只需要一些简单的注解(Annotation)和代码就可以使用独立应用的方式来启动,省去了复杂的代码编写和参数配置。

罗美琪参考了业界已经实现的消息组件的Spring实现了一个RocketMQ Spring客户端,它有两部分组成:

1. 消息的发送客户端:这是一个自动创建的Spring Bean,相关属性能够根据配置文件的配置自动设置,命名它为: RocketMQTemplate, 同时用来封装发送消息的各种同步和异步的方法。
@Resourceprivate RocketMQTemplate rocketMQTemplate;
SendResult sendResult = rocketMQTemplate.syncSend(xxxTopic, “Hello, World!”);

2. 消息的接收客户端:这是一个能够被应用回调的Listener, 用于将消费消息回调给用户进行相关的处理。
@Service@RocketMQMessageListener(topic = “xxx”, consumerGroup = “xxx_consumer”)
public class StringConsumer implements RocketMQListener<String> {
  @Override   public void onMessage(String message) {
      System.out.printf(“——- StringConsumer received: %s n”, message);
  }
}

特别说明一下:这个消费客户端Listener需要通过一个自定义的注解@RocketMQMessageListener来标注,这个注解的作用有两个:
  • 定义消息消费的配置参数(如: 消费的Topic, 是否顺序消费,消费组等); 
  • 可以让spring-boot在启动过程中发现标注了这个注解的所有Listener,并进行初始化,详见ListenerContainerConfiguration类及其实现SmartInitializingSingleton的接口方法afterSingletonsInstantiated()。

罗美琪发现,Spring-Boot最核心的实现是自动化配置(Auto Configuration),它分为三个部分:
  • 由@Configuration标注,用来创建RocketMQ客户端所需要的SpringBean,如上面所提到的RocketMQTemplate和能够处理消费回调Listener的容器,每个Listener对应一个容器SpringBean,来启动MQPushConsumer,并能将监听到的消费消息推送给Listener进行回调。
    参考:RocketMQAutoConfiguration.java  (编者注: 这个是最终发布的类,没有review的痕迹)
  • 实现“自动”配置,还需要由META-INF/spring.factories来声明。参考:spring.factories。使用这个META配置的好处是上层用户不需要关心自动配置类的细节和开关,只要classpath中有这个META-INF文件和Configuration类,就能实现自动配置。
  • 定义了@EnableConfiguraitonProperties注解,来引入ConfigurationProperties类,它的作用是定义自动配置的属性。参考:RocketMQProperties.java。上层用户可以根据这个类里定义的属性,配置相关的属性文件(即 META-INF/application.properties 或 META-INF/application.yaml)


故事的发展


罗美琪按照这个思路完成了RocketMQ SpringBoot的封装并形成了starter,提交给社区的小伙伴们试用,nice,大家使用后反馈效果不错。但是还是想请教一下专业的春波特小哥哥,看看他的建议。

春波特小哥相当的负责地对罗美琪的代码进行了Review, 首先他抛出了两个链接:
https://github.com/spring-projects/spring-boot/wiki/Building-On-Spring-Boot 
https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-developing-auto-configuration.html

然后解释道:在Spring Boot中包含两个概念: auto-configuration和starter-POMs, 它们之间相互关联,但并非简单绑定在一起的:
a. auto-configuration负责响应应用程序的当前状态,并配置适当的Spring Bean。它放在用户的CLASSPATH中,结合在CLASSPATH中的其它依赖,就可以提供相关的功能;
b. Starter-POM负责把auto-configuration和一些附加的依赖组织在一起,提供开箱即用的功能,它通常是一个maven project, 里面只是一个POM文件,不需要包含任何附加的classes或resources;

“换句话说,starter-POM负责配置全量的classpath, 而auto-configuration负责具体的响应(实现);前者是total-solution, 后者可以按需使用。你现在的系统是单一的一个module把auto-configuration和starter-POM混在了一起,这个不利于以后的扩展和模块的单独使用。”

罗美琪明白区分对项目维护的重要性,于是将代码进行了模块化:
  • rocketmq-spring-boot-parent:父POM
  • rocketmq-spring-boot:auto-configuraiton模块
  • rocketmq-spring-stater:starter模块 (实际上只包含一个pom.xml文件)
  • rocketmq-spring-samples:调用starter的示例样本

“很好,这样的模块结构就清晰多了”,春波特小哥哥点头,“但是这个AutoConfiguration文件里的一些标签的用法并不正确,我来注释一下,另外,考虑到明年8月Spring Boot 1.X将不再提供支持,所以建议实现直接支持Spring Boot 2.X”。
@Configuration
@EnableConfigurationProperties(RocketMQProperties.class)
@ConditionalOnClass(MQClientAPIImpl.class)
@Order  ~~春波特: 这个类里使用Order很不合理呵,不建议使用,完全可以通过其他方式控制runtime是Bean的构建顺序
@Slf4j
publicclassRocketMQAutoConfiguration {
  @Bean
  @ConditionalOnClass(DefaultMQProducer.class) ~~春波特: 属性直接使用类是不科学的,需要用(name=“类全名”) 方式,这样在类不在classpath时,不会抛出CNFE
  @ConditionalOnMissingBean(DefaultMQProducer.class)
  @ConditionalOnProperty(prefix = “spring.rocketmq”, value = {“nameServer”, “producer.group”}) ~~春波特: nameServer属性名要写成name-server [1]
  @Order(1) ~~春波特: 删掉呵   public DefaultMQProducer mqProducer(RocketMQProperties rocketMQProperties) {
      …
  }
  @Bean
  @ConditionalOnClass(ObjectMapper.class)
  @ConditionalOnMissingBean(name = “rocketMQMessageObjectMapper”) ~~春波特: 不建议与具体的实例名绑定,设计的意图是使用系统中已经存在的ObjectMapper, 如果没有,则在这里实例化一个,需要改成
   @ConditionalOnMissingBean(ObjectMapper.class)
  public ObjectMapper rocketMQMessageObjectMapper() {
      return new ObjectMapper();
  }
  @Bean(destroyMethod = “destroy”)
  @ConditionalOnBean(DefaultMQProducer.class)
  @ConditionalOnMissingBean(name = “rocketMQTemplate”) ~~春波特: 与上面一样
  @Order(2) ~~春波特: 删掉呵 
   public RocketMQTemplate rocketMQTemplate(DefaultMQProducer mqProducer,
      @Autowired(required = false)              ~~春波特: 删掉
      @Qualifier(“rocketMQMessageObjectMapper”) ~~春波特: 删掉,不要与具体实例绑定              
         ObjectMapper objectMapper) {
      RocketMQTemplate rocketMQTemplate = new RocketMQTemplate();
      rocketMQTemplate.setProducer(mqProducer);
      if (Objects.nonNull(objectMapper)) {
          rocketMQTemplate.setObjectMapper(objectMapper);
      }
      return rocketMQTemplate;
  }
  @Bean(name = RocketMQConfigUtils.ROCKETMQ_TRANSACTION_ANNOTATION_PROCESSOR_BEAN_NAME)
  @ConditionalOnBean(TransactionHandlerRegistry.class)
  @Role(BeanDefinition.ROLE_INFRASTRUCTURE) ~~春波特: 这个bean(RocketMQTransactionAnnotationProcessor)建议声明成static的,因为这个RocketMQTransactionAnnotationProcessor实现了BeanPostProcessor接口,接口里方法在调用的时候(创建Transaction相关的Bean的时候)可以直接使用这个static实例,而不要等到这个Configuration类的其他的Bean都构建好 [2]
  public RocketMQTransactionAnnotationProcessor transactionAnnotationProcessor(     
  TransactionHandlerRegistry transactionHandlerRegistry) {
    return new RocketMQTransactionAnnotationProcessor(transactionHandlerRegistry);
 }
  @Configuration  ~~春波特: 这个内嵌的Configuration类比较复杂,建议独立成一个顶级类,并且使用
  @Import在主Configuration类中引入 
  @ConditionalOnClass(DefaultMQPushConsumer.class)
  @EnableConfigurationProperties(RocketMQProperties.class)
  @ConditionalOnProperty(prefix = “spring.rocketmq”, value = “nameServer”) ~~春波特: name-server
  public static classListenerContainerConfigurationimplementsApplicationContextAware, InitializingBean {
     …
     @Resource ~~春波特: 删掉这个annotation, 这个field injection的方式不推荐,建议使用setter或者构造参数的方式初始化成员变量
     private StandardEnvironment environment;
      @Autowired(required = false)  ~~春波特: 这个注解是不需要的
      public ListenerContainerConfiguration(
          @Qualifier(“rocketMQMessageObjectMapper”) ObjectMapper objectMapper) { ~~春波特: @Qualifier 不需要
          this.objectMapper = objectMapper;
      }


注[1]: 在声明属性的时候不要使用驼峰命名法,要使用-横线分隔,这样才能支持属性名的松散规则(relaxed rules)。
注[2]: BeanPostProcessor接口作用是:如果需要在Spring容器完成Bean的实例化、配置和其他的初始化的前后添加一些自己的逻辑处理,就可以定义一个或者多个BeanPostProcessor接口的实现,然后注册到容器中。为什么建议声明成static的,春波特的英文原文如下:

 If they don’t we basically register the post-processor at the same “time” as all the other beans in that class and the contract of BPP is that it must be registered very early on. This may not make a difference for this particular class but flagging it as static as the side effect to make clear your BPP implementation is not supposed to drag other beans via dependency injection.

AutoConfiguration里果真有很多学问,罗美琪迅速的调整了代码,一下看起来清爽了许多。不过还是被春波特提出了两点建议:
@Configuration
public class ListenerContainerConfiguration implements ApplicationContextAware, SmartInitializingSingleton {
   private ObjectMapper objectMapper = new ObjectMapper(); ~~春波特: 性能上考虑,不要初始化这个成员变量,既然这个成员是在构造/setter方法里设置的,就不要在这里初始化,尤其是当它的构造成本很高的时候。
  private void registerContainer(String beanName, Object bean) {   Class<?> clazz = AopUtils.getTargetClass(bean);
  if(!RocketMQListener.class.isAssignableFrom(bean.getClass())){
      throw new IllegalStateException(clazz + ” is not instance of “ + RocketMQListener.class.getName());
  }
  RocketMQListener rocketMQListener = (RocketMQListener) bean;     RocketMQMessageListener annotation = clazz.getAnnotation(RocketMQMessageListener.class);
  validate(annotation);   ~~春波特: 下面的这种手工注册Bean的方式是Spring 4.x里提供能,可以考虑使用Spring5.0 里提供的 GenericApplicationContext.registerBean的方法,通过supplier调用new来构造Bean实例 [3]
   BeanDefinitionBuilder beanBuilder = BeanDefinitionBuilder.rootBeanDefinition(DefaultRocketMQListenerContainer.class);
  beanBuilder.addPropertyValue(PROP_NAMESERVER, rocketMQProperties.getNameServer());
  …
  beanBuilder.setDestroyMethodName(METHOD_DESTROY);
  String containerBeanName = String.format(“%s_%s”, DefaultRocketMQListenerContainer.class.getName(), counter.incrementAndGet());
  DefaultListableBeanFactory beanFactory = (DefaultListableBeanFactory) applicationContext.getBeanFactory();
  beanFactory.registerBeanDefinition(containerBeanName, beanBuilder.getBeanDefinition());
  DefaultRocketMQListenerContainer container = beanFactory.getBean(containerBeanName, DefaultRocketMQListenerContainer.class);   ~~春波特: 你这里的启动方法是通过 afterPropertiesSet() 调用的,这个是不建议的,应该实现SmartLifecycle来定义启停方法,这样在ApplicationContext刷新时能够自动启动;并且避免了context初始化时由于底层资源问题导致的挂住(stuck)的危险
  if (!container.isStarted()) {
      try {
          container.start();
      } catch (Exception e) {
        log.error(“started container failed. {}”, container, e);           throw new RuntimeException(e);
      }
  }
   …
}
}

注[3]: 使用GenericApplicationContext.registerBean的方式
public final < T > void registerBean(Class< T > beanClass, Supplier< T > supplier, BeanDefinitionCustomizer… ustomizers)

还有,还有”,罗美琪按照春波特的建议调整完代码后,春波特哥哥提出了Spring Boot特有的几个要求:
  • 使用Spring的Assert在传统的Java代码中我们使用assert进行断言,Spring Boot中断言需要使用它自有的Assert类,如下示例:
importorg.springframework.util.Assert;
Assert.hasText(nameServer, “[rocketmq.name-server]mustnotbenull“);

  • Auto Configuration单元测试使用Spring 2.0提供 ApplicationContextRunner
publicclassRocketMQAutoConfigurationTest {
  private ApplicationContextRunner runner = new ApplicationContextRunner()           .withConfiguration(AutoConfigurations.of(RocketMQAutoConfiguration.class));

  @Test(expected = NoSuchBeanDefinitionException.class)   publicvoid testRocketMQAutoConfigurationNotCreatedByDefault() {
      runner.run(context -> context.getBean(RocketMQAutoConfiguration.class));   }
  @Test
  publicvoid testDefaultMQProducerWithRelaxPropertyName() {
      runner.withPropertyValues(“rocketmq.name-server=127.0.0.1:9876”,               “rocketmq.producer.group=spring_rocketmq”).
              run((context) -> {
                  assertThat(context).hasSingleBean(DefaultMQProducer.class);                   assertThat(context).hasSingleBean(RocketMQProperties.class);               });
  }
  
  • 在auto-configuration模块的pom.xml文件里,加入spring-boot-configuration-processor注解处理器。这样它能够生成辅助元数据文件,加快启动时间。详情见这里(https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-developing-auto-configuration.html#boot-features-custom-starter-module-autoconfigure)。
最后,春波特还向罗美琪分享了一些实践经验:

  • 通用的规范,好的代码要易读易于维护

a. 注释与命名规范
我们常用的代码注释分为多行(/** … */)和单行(// …)两种类型,对于需要说明的成员变量,方法或者代码逻辑应该提供多行注释; 有些简单的代码逻辑注释也可以使用单行注释。在注释时通用的要求是首字母大写开头,并且使用句号结尾;对于单行注释,也要求首字母大写开头; 并且不建议行尾单行注释。

在变量和方法命名时尽量用词准确,并且尽量不要使用缩写,如: sendMsgTimeout, 建议写成sendMessageTimeout;包名supports,建议改成support。

b. 是否需要使用Lombok
使用Lombok的好处是代码更加简洁,只需要使用一些注释就可省略constructor, setter和getter等诸多方法(bolierplate code);但是也有一个坏处就是需要开发者在自己的IDE环境配置Lombok插件来支持这一功能,所以Spring社区的推荐方式是不使用Lombok,以便新用户可以直接查看和维护代码,不依赖IDE的设置。

c. 对于包名(package)的控制
如果一个包目录下没有任何class,建议要去掉这个包目录。例如:org.apache.rocketmq.spring.starter 在spring目录下没有具体的class定义,那么应该去掉这层目录(编者注: 我们最终把package改为org.apache.rocketmq.spring,将starter下的目录和classes上移一层)。

我们把所有Enum类放在包org.apache.rocketmq.spring.enums下,这个包命名并不规范,需要把Enum类调整到具体的包中,去掉enums包;类的隐藏,对于有些类,它只被包中的其它类使用,而不需要把具体的使用细节暴漏给最终用户,建议使用package private约束,例如: TransactionHandler类。

d. 不建议使用Static Import
虽然使用它的好处是更少的代码,坏处是破坏程序的可读性和易维护性。

  • 效率,深入代码的细节

a. static + final method,一个类的static方法不要结合final,除非这个这个类本身是final并且声明private构造(ctor),如果两者结合以为这子类不能再(hiding)定义该方法,给将来的扩展和子类调用带来麻烦。

b. 在配置文件声明的Bean尽量使用构造函数或者Setter方法设置成员变量,而不要使用@Autowared,@Resource等方式注入。[4]

c. 不要额外初始化无用的成员变量。

d. 如果一个方法没有任何地方调用,就应该删除;如果一个接口方法不需要,就不要实现这个接口类

注[4]: 下面的截图是有 FieldInjection 转变成构造函数设置的代码示例:

讲讲我和 Spring 创始级程序员共同 review 代码的故事

转换成
讲讲我和 Spring 创始级程序员共同 review 代码的故事

故事的结局


罗美琪按照春波特小哥的建议,进一步调整了代码,大幅度提高了代码质量,并且总结了Spring Boot开发的要点:

a. 编写前参考成熟的spring boot实现代码;
b. 要注意模块的划分,区分autoconfiguration 和 starter;
c. 在编写autoconfiguration Bean的时候,注意@Conditional注解的使用;尽量使用构造器或者setter方法来设置变量,避免使用Field Injection方式;多个Configuration Bean可以使用@Import关联;使用Spring 2.0提供的AutoConfigruation测试类;
d. 注意一些细节: static与BeanPostProcessor; Lifecycle的使用;不必要的成员属性的初始化等;

后记


开源软件不仅要关注产品的易用性,更要在乎代码质量和代码风格。

活跃的社区贡献者罗美琪继续在与RocketMQ社区的小伙伴们不断完善Spring的代码,并邀请春波特的Spring社区进行更多的技术分享。下一步他们将rocketmq-spring-starter推进到Spring Initializr,让用户可以在start.spring.io上像使用其它starter(如: Tomcat starter)一样使用rocketmq-spring。
    本站所有文章均来自互联网,如有侵权,请联系站长删除。极客文库 » 讲讲我和 Spring 创始级程序员共同 review 代码的故事
    分享到:
    赞(0)

    评论抢沙发

    评论前必须登录!