F1V3.0-12 微服务开发规范

引言

本文介绍了在使用F1平台V3.0的时候，开发人员应该遵守的规范，以提高代码质量，提高工作效率。

微服务划分原则

把一个大系统划分为多个微服务，使模块间结构更加清晰，模块间更低耦合高内聚，有更好的扩展性和稳定性。

微服务划分请按以下原则：

1. 按功能模块划分微服务，尽量做到一个功能模块一个微服务。
2. 微服务之间减少互相调用，做到低耦合高内聚。

微服务端4大模块原则

微服务按功能类别分为4大模块

微服务

一个功能模块做成一个普通微服务，对系统业务功能的实现的微服务属于这一类。

interface

对外提供接口，比如f1-interface-model是model的接口，其它微服务引入f1-interface-model就可以访问model中的功能。

starter

用自动装配的方式在微服务启动时加载一些公共组件，比如f1-starter-data, 其他微服务引入f1-starter-data之后，就可以使用GenericDao的springbean操作数据库数据。

util

经常用到的一些工具类库，比如f1-util.

 

命名规范

服务命名

 

规则

示例

微服务

[项目名]-[模块名]

f1-permission

interface

[项目名]-interface-[模块名]

f1-interface-model

starter

[项目名]-starter-[模块名]

f1-starter-auth

util

[项目名]-util

f1-util

 

参数命名

参数指的是微服务的application.properties中自定义的配置参数。

分类

规范

示例

取法

平台参数

platform.config.[参数名]

platform.config.messageSwitch

平台的消息开关

Platform.getPlatform().getString(参数名)

项目参数

[项目名].[模块名].[参数名]

Aproject.product.maxCount

A项目的产品模块的最大数量

 微服务常用功能开发——微服务自定义配置参数

包命名、类命名

包命名

我们以f1-model中的包为例，如下图：

类命名

我们以f1-model中的类名为例，如下图：

目录规范

我们这里以f1-model为例，项目目录结构如下图

配置规范

微服务模块下必须包含两个配置文件application.properties、bootstrap.properties。 
application.properties：主要包含通用数据连接、Redis连接等通用配置。该配置文件中的内容每个微服务保持相同，在组织中使用同一的配置管理器的情况下该文件不需要修改。 
bootstrap.properties：主要包含了eureka地址配置、通用配置服务器地址配置等相关信息，本微服务内需要添加的特定配置项可在该文件中进行配置。 

注解规范

自动装配

@Autowired、@Inject、@Resource可注解在set方法上或属性上，但建议注解在属性上，优点是代码更少、层次更清晰。

扫描路径

在微服务中通常需要包含仅有的一个应用启动类，该启动类通常需要包含@ComponentScan以及@EnableFeignClients、@EntityScan等注解。

ComponentScan：相当于以前使用spring配置文件中的包扫描路径，该注解中的配置值需要做到精确匹配，包名称仅包含到当前模块的包名，不要包含其他依赖包的包名，如： 
@ComponentScan(basePackages = "com.jb.config")使用正确 
@ComponentScan(basePackages = "com.jb")涵盖范围过广

EnableFeignClients：必须配置为com.jb.*.client

EntityScan：hibernate实体的扫描路径，使用通配符进行精准匹配，如： 
@EntityScan(basePackages={"com.jb.organization.model","com.jb.permission.model"})

客户端创建规则 

微服务间难免会存在服务调用，如果当前微服务存在对外共享rest服务的情况，当前微服务就需要创建接口模块，原有微服务将rest调用过程中涉及到的实体以及VO对象移动到接口模块，同时在接口模块中创建可供别的微服务直接依赖使用的客户端，原有微服务依赖于创建的接口模块，同时该接口模块也提供给需要访问该模块rest服务的其它微服务所使用。例如： 
 

系统配置功能经常被别的微服务所访问以获取系统的配置信息，所以系统配置中的模型被分离到了接口模块，同时创建了可被别的微服务所使用的客户端对象，其它微服务引用该接口模块，直接调用客户端对象即可访问到系统配置对应的rest服务。

Swagger使用规范

swagger使用范围规范

对于对外访问的rest服务对应的控制器必须添加swager描述。 对于提供给移动端以及pc端同时访问的控制器请求必须添加swager描述。 对于所有控制器尽可能添加swager描述。 

swagger注释规范

在接口上声明swagger的api信息时，尽量保证维护好下列信息，以使api页面上的信息相对完善。

@ApiOperation(value = "接口说明", httpMethod = "接口请求方式", response = "接口返回参数类型", notes = "接口发布说明"；
@ApiParam(required = "是否必须参数", name = "参数名称", value = "参数具体描述")

示例如下：

@ApiOperation(value = "工作流数据示例——发起流程", httpMethod = "GET", response = String.class, notes = "工作流数据示例——发起流程\n本接口是用于演示发起流程")@ApiParam(required = false, name = "流程名称", value = "用于演示发起流程的流程名称")@RequestMapping(value = "newWorkflow", method=RequestMethod.GET)public void newWorkflow(String wfName) {operWorkFlowDataService.newCreateWorkflow();}

单元测试约定 

测试范围规范

微服务中必须编写单元测试，单元测试覆盖的范围至少为controller控制层。

测试类的命名定义规范

Junit自动生成测试类的命名如下：被测试的业务+Test、被测试的接口+Test、被测试的类+Test，例如：AppControllerTest、ClsfltControllerTest

测试用例的命名定义规范

测试用例的命名规则是：test+用例操作。如：testXXXOperCase, XXXOperCase是某个用例操作的名字，例如：testCmdBuildFlatCache、testCmdTransfer

测试程序的包名定义规范

测试程序包的命名和被测试代码的包名一致，只是放在src/test/java目录下。例如：src/main/java源码文件夹下的com.jb.organization.controller包下对应的单元测试代码存放在：src/test/java源码文件夹下的com.jb.organization.controller包下