后端开发实践系列——Spring Boot项目模板(6)

除了Checkstyle统一代码格式之外，项目中有些通用的公共的编码实践方式也需要在整个开发团队中进行统一，包括但不限于以下方面：

• 客户端的请求数据类统一使用相同后缀，比如Command
• 返回给客户端的数据统一使用相同后缀，比如Represetation
• 统一对请求处理的流程框架，比如采用传统的3层架构或者DDD战术模式
• 提供一致的异常返回(请参考“异常处理”小节)
• 提供统一的分页结构类
• 明确测试分类以及统一的测试基础类(请参考“自动化测试分类”小节)

静态代码检查

静态代码检查主要包含以下Gradle插件，具体配置请参考本文示例代码：

• Checkstyle：用于检查代码格式，规范编码风格
• Spotbugs：Findbugs的继承者
• Dependency check：OWASP提供的Java类库安全性检查
• Sonar：用于代码持续改进的跟踪

健康检查

健康检查主要用于以下场景：

• 我们希望初步检查程序是否运行正常
• 有些负载均衡软件会通过一个健康检查URL判断节点的可达性

此时，可以实现一个简单的API接口，该接口不受权限管控，可以公开访问。如果该接口返回HTTP的200状态码，便可初步认为程序运行正常。此外，我们还可以在该API中加入一些额外的信息，比如提交版本号、构建时间、部署时间等。

启动本文的示例项目：

./run.sh 

然后访问健康检查API：http://localhost:8080/about，结果如下：

{ 
  requestId: "698c8d29add54e24a3d435e2c749ea00", 
  buildNumber: "unknown", 
  buildTime: "unknown", 
  deployTime: "2019-04-11T13:05:46.901+08:00[Asia/Shanghai]", 
  gitRevision: "unknown", 
  gitBranch: "unknown", 
  environment: "[local]" 
} 

以上接口在示例项目中用了一个简单的Controller实现，事实上Spring Boot的Acuator框架也能够提供相似的功能。

API文档

软件文档的难点不在于写，而在于维护。多少次，当我对照着项目文档一步一步往下走时，总得不到正确的结果，问了同事之后得到回复“哦，那个已经过时了”。本文示例项目所采用的Swagger在一定程度上降低了API维护的成本，因为Swagger能自动识别代码中的方法参数、返回对象和URL等信息，然后自动地实时地创建出API文档。

配置Swagger如下：

@Configuration 
@EnableSwagger2 
@Profile(value = {"local", "dev"}) 
public class SwaggerConfiguration { 
 
    @Bean 
    public Docket api() { 
        return new Docket(SWAGGER_2) 
                .select() 
                .apis(basePackage("com.ecommerce.order")) 
                .paths(any()) 
                .build(); 
    } 
} 

启动本地项目，访问http://localhost:8080/swagger-ui.html：

Swagger API文档

数据库迁移

在传统的开发模式中，数据库由专门的运维团队或者DBA来维护，要对数据库进行修改需要向DBA申请，告之迁移内容，最后由DBA负责数据库变更实施。在持续交付和DevOps运动中，这些工作逐步提前到开发过程，当然并不是说不需要DBA了，而是这些工作可以由开发者和运维人员一同完成。另外，在微服务场景下，数据库被包含在单个服务的边界之内，因此基于内聚性原则(咦，这好像是本文第三次提到内聚原则了，可见其在软件开发中的重要性)，数据库的变更最好也与项目代码一道维护在代码库中。

本文的示例项目采用了Flyway作为数据库迁移工具，加入了Flyway依赖后，在src/main/sources/db/migration目录下创建迁移脚本文件即可：

resources/ 
├── db 
│   └── migration 
│       ├── V1__init.sql 
│       └── V2__create_product_table.sql 

迁移脚本的命名需要遵循一定的规则以保证脚本执行顺序，另外迁移文件生效之后不要任意修改，因为Flyway会检查文件的checksum，如果checksum不一致将导致迁移失败。

多环境构建

（编辑：ASP站长网）