# 微服务开发规范说明

**Repository Path**: moty/MicroService-DevDocs

## Basic Information

- **Project Name**: 微服务开发规范说明
- **Description**: 微服务开发规范说明
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2022-03-22
- **Last Updated**: 2022-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 微服务开发规范说明
## 前言说明
本开发规范主要围绕Java语言服务端开发为主，其他语言服务端开发也可以参考次规范，本文对服务端开发的项目结构、命名规范、接口调用、接口测试、日志打印、接口文档说明、部署说明等
|  项目说明   | 约束规范  |
|  ----  | ----  |
| 项目结构  | maven工程结构 |
| 开发框架  | Spring Boot 2.x |
| 项目管理  | Maven 3.x |
| 测试框架  | Spring Test + Junit|
| 项目日志  | Logback 1.2.x|
| 数据序列化  | Fastjson 1.2.75 |
| 接口文档  | Swagger2.x |


## 项目结构示例
├─aircas-demo  

	├─Dockerfile
	├─pom.xml
	├─ReadMe.md
	├─src
	├─test
		├─resources
		├─java
			├─org
				├─aircas
					├─demo
					├─service
						└AircasDemoServiceTest.java
					├─dao
						└AircasDemoDaoTest.java
					├─controller
	├─main
		├─resources
				├─application.properties
				└logback-spring.xml
		├─java
			├─org
				├─aircas
					├─demo
					├─Application.java
					├─service
						├─AircasDemoService.java
						├─impl
						└AircasDemoServiceImpl.java
					├─model
						├─AircasDemoModel.java
						└TestModel.java
					├─entity
						└AircasDemoEntity.java
					├─dao
						├─AircasDemoDao.java
						├─impl
							└AircasDemoDaoImpl.java
					├─controller
						└AircasDemoController.java
					├─config
						├─SwaggerConfig.java
						└WebConfiguration.java
 
![RUNOOB 图标](images/2022-03-22_153435.png)
说明：
+ aircas-demo：实例工程名称
+ Dockerfile：Docker部署相关配置文件
+ pom.xml: 工程jar包依赖配置
+ ReadMe.md: 项目工程相关说明
+ src/test/java:测试相关的代码
+ src/test/resources:测试相关的资源文件
+ src/main/java:主程序代码
+ src/main/resource:主程序相关资源，包括配置文件、静态资源html、css等
## 项目工程管理
项目采用Maven进行工程管理，主要依赖通过在pom.xml中添加。
+ 约束规范1
依赖的版本都采用变量的方式引用，举例，如引入fastjson依赖，首先在properties中定义版本变量。
```xml
<properties>
	<!-- 解决pom错误原因呢，报错是因为版本不兼容问题 -->
	<maven-jar-plugin.version>3.1.1</maven-jar-plugin.version>
	<java.version>1.8</java.version>
	<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
	<main.class>aircas.demo.Application</main.class>
	<dockerfile-maven-plugin>1.4.0</dockerfile-maven-plugin>
	<docker.image.prefix>aircas</docker.image.prefix>
	<swagger.version>2.9.2</swagger.version>
	<fastjson.version>1.2.75</fastjson.version>
</properties>
```
+ 约束规范2
在依赖库添加时，采用变量的方式进行版本的管理。如下所示
```xml
<dependency>
	<groupId>com.alibaba</groupId>
	<artifactId>fastjson</artifactId>
	<version>${fastjson.version}</version>
</dependency>
````
## 命名规范
### 项目命名
项目名字主要以空天院英文缩写开头，aircas-项目组名进行命名，项目名要求简单易懂。
### 包命名
包命名主要已经项目实现分层架构进行命名，开头以org.aircas.项目.*进行命名，包命名提供以下通用约束：
* org.aricas.项目名 :主要是程序入口文件如：Application.java
* org.aricas.项目名.entity:实体文件
* org.aricas.项目名.dao:数据访问接口
* org.aricas.项目名.dao.impl:数据访问接口的实现
* org.aricas.项目名.service:数据服务接口
* org.aricas.项目名.service.impl:数据服务接口的实现
* org.aricas.项目名.controller: rest api控制层实现
### 类命名
类命名主要针对config、model、dao、Service、Controller相关代码类进行命名，主要命名约束如下
* **Config:配置类
* **Model:模型类
* **Dao:数据访问接口
* **DaoImpl:数据访问实现类
* **Service:数据服务接口
* **ServiceImpl:数据服务实现类

## 日志打印
微服务日志统一采用spring boot默认的logback作为微服日志框架，微服务规范定义了日志的相关的配置，包括输出的日志格式定义，日志输出端配置等，主要参见项目文件：<b>src/main/resources/logback-spring.xml</b>。
* 使用方式
<strong style="color:red">直接将logback-spring.xml拷贝到项目工程src/main/resources中即可</strong>
+ 描述日志格式定义配置片段如下所示
```xml
	<!-- 彩色日志格式 -->
<property name="CONSOLE_LOG_PATTERN"
	value="${CONSOLE_LOG_PATTERN:-%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}}" />
```
+ 定义输出到控制台（采用上述日志格式输出）
```xml
<!--输出到控制台 -->
<appender name="CONSOLE"
	class="ch.qos.logback.core.ConsoleAppender">
	<!--此日志appender是为开发使用，只配置最底级别，控制台输出的日志级别是大于或等于此级别的日志信息 -->
	<filter class="ch.qos.logback.classic.filter.ThresholdFilter">
		<level>info</level>
	</filter>
	<encoder>
		<Pattern>${CONSOLE_LOG_PATTERN}</Pattern>
		<!-- 设置字符集 -->
		<charset>UTF-8</charset>
	</encoder>
</appender>
```
+ 定义输出到文件，并以时间（天）滚动输出，每一天组织成一个日志文件
```xml
<!-- 时间滚动输出 level为 INFO 日志 -->
<appender name="INFO_FILE"
	class="ch.qos.logback.core.rolling.RollingFileAppender">
	<!-- 正在记录的日志文件的路径及文件名 -->
	<file>${log.path}/log_info.log</file>
	<!--日志文件输出格式 -->
	<encoder>
		<!-- <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50}-%msg%n</pattern> -->
		<pattern>${CONSOLE_LOG_PATTERN}</pattern>
		<charset>UTF-8</charset>
	</encoder>
	<!-- 日志记录器的滚动策略，按日期，按大小记录 -->
	<rollingPolicy
		class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
		<!-- 每天日志归档路径以及格式 -->
		<fileNamePattern>${log.path}/info/log-info-%d{yyyy-MM-dd}.%i.log
		</fileNamePattern>
		<timeBasedFileNamingAndTriggeringPolicy
			class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
			<maxFileSize>100MB</maxFileSize>
		</timeBasedFileNamingAndTriggeringPolicy>
		<!--日志文件保留天数 -->
		<maxHistory>15</maxHistory>
	</rollingPolicy>
</appender>
```
+ 汇总输出，控制台和文件同时输出
```xml
<root level="info">
	<appender-ref ref="CONSOLE" />
	<appender-ref ref="INFO_FILE" />
</root>
```
## 接口调用
接口调用主要分为三层，数据访问(Dao)、数据服务层(Service)、数据控制层(Controller)
+ Controller（控制逻辑）层：它是负责在页面和程序之间传输数据的，还有作用是做页面跳转、以及数据校验。页面由用户填写表单数据，点击提交按钮，页面的表单数据由传入Service层。
+ Service层（业务逻辑层）：负责的是对数据的处理、添加业务逻辑。如果没有数据处理任务的话，此层只做单纯的数据传递作用，而后又到了DAO层。
+ DAO层（数据库操作层）：负责对数据向数据库增删改查的操作。
调用关系如下所示
![RUNOOB 图标](images/2022-03-22_151138.png)


## 接口测试
接口测试采用Spring Test + Junit5测试框架进行测试，测试内容包括对dao层、service层、controller层的测试


## 接口文档说明
接口文档说明主要采用Swagger2,Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
示例程序以集成了Swagger2,包括依赖引用、全局配置、以及一些示例应用。
+ 依赖引用
1）设置依赖版本(pom.xml)
```xml
<properties>
	<swagger.version>2.9.2</swagger.version>
</properties>
```
2）添加Swagger依赖(pom.xml)
```xml
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>${swagger.version}</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>${swagger.version}</version>
</dependency>
````
+ 全局配置
参见: <b style="color:red">src/main/java: org.iecas.demo.config.SwaggerConfig.java</b>
使用时直接将SwaggerConfig.java拷贝到对应目录即可
+ web访问配置(WebConfiguration.java)
```java
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
	registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
	registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
	registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
```
+ 示例应用
Swagger通过对接口添加相应的注解，进行接口的说明。举例如下
```java
@ApiOperation(value = "示例接口(get)")
@RequestMapping(value = "demoGet", method = RequestMethod.GET)
@ResponseBody
public String demoGet(@RequestParam(required = false) String name) {
	logger.info("url:aircas/demoGet");
	return String.format("Hello,%s, you got me.", name);

}
```
使用详情具体参见：org.aircas.demo.controller.AircasDemoController.java
网上学习参考：https://cloud.tencent.com/developer/article/1862325
+ 文档在线查看
swagger-ui接口说明地址:http://ip:port/swagger-ui.html

## 数据传输序列化
本规范约定微服务数据传输序列化统一采用FastJson作为序列化/反序列化工具，主要用于前端查询数据时，后端序列化对象为json返回给前端，前端传入json串时，反序列化给程序对象。
* 添加依赖
```xml
<properties>
	<fastjson.version>1.2.75</fastjson.version>
</properties>

<dependencies>
	<dependency>
		<groupId>com.alibaba</groupId>
		<artifactId>fastjson</artifactId>
		<version>${fastjson.version}</version>
	</dependency>
<dependencies>
```
* 序列化配置
参见org.aircas.demo.config.WebConfiguration.java,相关配置代码片段如下：
```java
@Bean
public FastJsonHttpMessageConverter fastJsonHttpMessageConverter() {
	// 定义一个Convert转换消息的对象
	FastJsonHttpMessageConverter fastConvert = new FastJsonHttpMessageConverter();
	// 添加fastjson的配置信息，比如是否要格式化返回的JSON数据

	FastJsonConfig fastJsonConfig = new FastJsonConfig();
	fastJsonConfig.setSerializerFeatures(SerializerFeature.PrettyFormat);

	fastConvert.setFastJsonConfig(fastJsonConfig);
	List<MediaType> mediaTypes = new ArrayList<MediaType>();
	mediaTypes.add(MediaType.TEXT_PLAIN);
	mediaTypes.add(MediaType.APPLICATION_JSON_UTF8);
	fastConvert.setSupportedMediaTypes(mediaTypes);
	return fastConvert;
}

@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
	converters.add(stringHttpMessageConverter());
	converters.add(fastJsonHttpMessageConverter());
}

@Override
public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
	converters.clear();
	converters.add(stringHttpMessageConverter());
	converters.add(fastJsonHttpMessageConverter());
}
````
## 示例项目全局配置说明
+ 项目编译环境默认设置

|  项目说明   | 约束规范  |
|  ----  | ----  |
| 编译jdk版本  | 1.8 |
| 项目编码  | UTF-8 |
| maven版本  | 3.1.1 |
相关配置如下(pom.xml)
```xml
<properties>
	<!-- 解决pom错误原因呢，报错是因为版本不兼容问题 -->
	<maven-jar-plugin.version>3.1.1</maven-jar-plugin.version>
	<java.version>1.8</java.version>
	<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-compiler-plugin</artifactId>
	<configuration>
		<source>1.8</source>
		<target>1.8</target>
	</configuration>
</plugin>

```

+ 项目日志框架默认设置
项目默认采用logback日志框架进行日志的管理
+ 项目接口说明默认设置
项目接口说明采用Swagger在线文档进行接口文档的管理
+ 项目接口访问默认设置
项目的接口对方访问默认是支持跨域访问，序列化方式统一采用fastjson
对应相关配置代码片段(WebConfiguration.java)
```java
@Bean
public CorsFilter corsFilter() {
	UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
	source.registerCorsConfiguration("/**", bulidConfig());
	return new CorsFilter(source);
}

private CorsConfiguration bulidConfig() {
	CorsConfiguration configuration = new CorsConfiguration();
	configuration.addAllowedOrigin("*");
	configuration.addAllowedHeader("*");
	configuration.addAllowedMethod("*");
	return configuration;
}
```
## 部署说明
项目打包支持普通的jar包输出，同时也支持docker镜像的打包部署（直接打包至服务器

+ 普通打包
maven配置打包插件如下(pom.xml) 
```xml
<!-- spring boot 打包 输出jar包 -->
<plugin>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-maven-plugin</artifactId>
	<configuration>
		<!-- 指定Jar包输出文件夹 -->
		<outputDirectory>${output.directory}</outputDirectory>
		<!-- 指定输出Jar包名 -->
		<finalName>${jar.finalname}</finalName>
		<mainClass>${main.class}</mainClass>
	</configuration>
</plugin>
````
执行命令
```
mvn clean package dockerfile:build -DskipTests
```
打包输出至target目录,生成对应jar包
+ 镜像打包至服务端
镜像打包可以直接将程序部署到远程服务中，需要进行如下环境配置  
1）服务器端配置
    - 部署docker环境
	docker的安装部署、开机自启
    - 开放远程Docker远程访问端口
		```
		# vim /lib/systemd/system/docker.service
		ExecStart=/usr/bin/dockerd -H tcp://0.0.0.0:2375 -H unix:///var/run/docker.sock
		```
		加载基础镜像依赖
		```
		# docker load -i java.tar
		```

	2）开发客户端配置
	需要配置DOCKER_HOST环境变量
	![RUNOOB 图标](images/2022-03-21_144030.png)

	3）执行部署命令
	```
	mvn clean package dockerfile:build -DskipTests
	```
#参数配置
参数配置主要指项目中属性参数的配置（键值对），主要的配置通过*.properties配置文件进行配置，参数配置主要采用注解的方式，将参数注入到配置对象属性字段中，举例如下
文件涉及：
+ aircas-demo\src\main\resources\jdbc.properties
+ aircas-demo\src\main\java\org\aircas\demo\config\JDBCConfig.java
jdbc.properties内容如下
```properties
jdbc.driverClass=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/iemes_v1?useUnicode=true&characterEncoding=UTF-8&zeroDateTimeBehavior=convertToNull&allowMultiQueries=true
jdbc.username=${db.username: 默认值用户名}
jdbc.password=${db.password: 默认值密码}
```
JDBCConfig.java内容如下
```java
@Configuration
@PropertySource("classpath:jdbc.properties")
public class JDBCConfig {

    @Value("${jdbc.driverClass}")
    private String driverClass;
    @Value("${jdbc.url}")
    private String url;

    @Value("${jdbc.username}")
    private String username;
    @Value("${jdbc.password}")
    private String password;
}
```
示例测试接口

http://localhost:8080/aircas/demoArgs

# 项目运行&参数传递
项目运行采用docker run的启动方式，docker run可以通过添加环境变量的方式，设置容器内相关配置参数，举例说明如下
设置jdbc.properties配置文件：
文件路径：aircas-demo\src\main\resources\jdbc.properties
jdbc.properties配置内容如下
```properties
jdbc.driverClass=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/iemes_v1?useUnicode=true&characterEncoding=UTF-8&zeroDateTimeBehavior=convertToNull&allowMultiQueries=true
jdbc.username=${db.username: 默认值用户名}
jdbc.password=${db.password: 默认值密码}
```
配置说明：
${db.username: 默认值用户名}：表示如果能从环境变量中获取db.username的变量值，则设置为该变量值，如果没有找到该变量值则采用设置的默认值：“默认值用户名”，
参数传递通过docker run -e的方式进行，如果需要多个参数传递则需要设置多个 -e，具体举例如下：
```
docker run -e port=8889 -e db.username=admin -e password=123456 --restart=always -itd --name aircas-demo -p 8080:8080 aircas/aircas-demo
```
实例项目给出了调用示例接口
http://192.168.118.137:8080/aircas/demoArgs


## 项目说明
项目的相关说明，写在readMe.md文件中,实例程序aircas-demo给出了readMe.md的说明模板

## 示例工程
aircas-demo

## 后续
+ 项目部署数据库地址的动态配置
+ 各类数据库访问工具包的封装（包含查询分页）
+ 微服务体系的应用
+ 其他