架构师技能2:基础框架和组件规范

傷城~ 2022-09-11 04:11 286阅读 0赞

在[《架构设计》][Link 1][https://blog.csdn.net/hguisu/category\_5905793.html][Link 1]系列里面主要谈的是架构相关方法论，没有具体到代码层面。最近抽点时间来总结架构师如何站在巨人的肩膀上眺望远方。

管理的精髓就是“制度管人，流程管事”。而所谓流程，就是对一些日常工作环节、方式方法、次序等进行标准化、规范化。且不论精不精髓，在技术团队中，对一些通用场景，统一规范是必要的，只有步调一致，才能高效向前。

# 一、什么是框架 #

--------------------

这个在[《架构设计（1）-谈谈架构》][1_-] 已经明确：

框架是组件实现的规范，例如：MVC、MVP、MVVM等，是提供基础功能的半成品，例如开源框架：Spring、spring boot、Django等，这是可以拿来直接使用或者在此基础上二次开发。框架是规范，架构是结构。

## 1、框架主要有两特性： ##

**1)、框架是提供基础功能的半成品：**已经对基础的代码（例如文件上传，数据库查询）进行了封装并提供相应的API，开发者在使用框架是直接调用封装好的api可以省去很多代码编写，从而提高工作效率和开发速度。

**2)、框架是规范：**框架规范应用的体系结构。它定义了整体结构，模块的划分、模块的主要职责，模块之间的协作。

## 2、使用框架的目的： ##

**1)、提高开发效率：**

使用成熟的框架，基础工作已经完成，应用开发人员只需要集中精力完成系统的业务逻辑设计。框架一般已经处理好基础功能和细节问题，比如事务处理，安全性，数据流控制等问题。还有框架一般都经过很多人使用，所以结构很好，所以扩展性也很好，而且它是不断升级的，你可以直接享受别人升级代码带来的好处。

**2)、提高团队人员协同效率。**

通过框架规范，规定大层次的约束与规范，较小层次的设计在这些约束与规范下进行的话，能最大限度地满足某些方面的特性，如可读性、可靠性、可扩展性、安全性。同时有使得代码更为清晰及更易维护。最终目的是提高团队协作效率，降低工程维护成本。

# 二、项目基础框架 #

--------------------

在微服务里面或者生命周期比较长的项目，一般是需要对使用不同原始框架拼装项目的基础框架，目的是封装提供项目使用的基础功能和规范项目技术体系，提高团队的协同效率，降低维护成本。

例如：

1、基础组件规范：如spring boot的版本统一规范和依赖规范。

2、日志组件统一规范。

3、restFull接口规范：比如rest接口返回格式。

4、异常处理统一规范

5、参数校验

6、安全处理机制。

7、api文档

8、基础应用配置。

9、模型统一规范格式。

10、一些基础工具类：比如项目使用获取ip，邮箱、手机号等校验。

11、单元测试规范。

![watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBAaGd1aXN1_size_20_color_FFFFFF_t_70_g_se_x_16][]

下面是一一具体描述。

# 三、项目基础框架说明 #

--------------------

## 1、基础组件和依赖统一规范管理： ##

主要spring boot的版本统一规范和依赖规范。主要的措施：

1)、通过maven的parent工程统一管理项目所有的jar的版本。

2）管理jar包依赖，在parent工程中配置依赖通用性jar包，然后引用该parent的项目就会自动继承。

3）parent工程通过<dependencyManagement>管理了可选的jar依赖，具体项目是按需继承。

如：<dependencyManagement>  
  <dependencies>  
    <dependency>  
      <groupId>junit</groupId>  
      <artifactId>junit</artifactId>  
      <version>3.8.1</version>  
      <scope>test</scope>  
    </dependency>  
  </dependencies>  
</dependencyManagement>

具体项目只要按需去依赖自己所需的jar包，并且version 和 scope 都继承pom。

<dependency>  
      <groupId>junit</groupId>  
      <artifactId>junit</artifactId>  
</dependency>

## 2、日志组件统一规范： ##

Java应用项目经常遇到的一个棘手的问题就是：依赖的包使用了不同的日志组件，常用的有log4j, log4j2， logback, common-logging, JUL等，导致日志输出异常混乱。因此日志的输出有必要进行统一配置，而不是针对不同的日志组件分别配置。

![watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBAaGd1aXN1_size_20_color_FFFFFF_t_70_g_se_x_16 1][]

因此需要做统一规范：

*  使用SLF4J作为日志API框架：通过适配各种日志实现的桥接包，接收所有的日志请求。
 *  使用logback作为最终的唯一日志实现，处理SLF4J收集的所有日志

因此为了统一规范日志的记录，及方便日后扩展，通过抽象接口对日志记录进行了封装。

![watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBAaGd1aXN1_size_20_color_FFFFFF_t_70_g_se_x_16 2][]

然后在具体项目统一使用：

import com.xxx.framework.logs.Logger;
    import com.xxx.framework.logs.LoggerFactory;
    
    private static final Logger logger = LoggerFactory.getLogger(xxController.class);

--------------------

## 3、restFull接口规范： ##

采用的微服务框架，前后端分离，前端和后端进行交互，前端按照约定请求URL路径，并传入相关参数，后端服务器接收请求，进行业务处理，返回数据给前端。

为了提高团队间接口对接的效率，需要做前后端交互的格式规范。一般统一的规范如下：

**1、请求格式规范：建议使用json body格式，**传入参数包含**公共请求头的要求（如：app\_version,api\_version,device等）。**

**2、返回格式规范：**

JSON体方式，定义如下：

{
       code:integer,#返回状态码	
       message:string,#返回信息描述，直接展示友好用户提示信息
       error:string,#错误描述信息，方便开发直接定位
       data:object #返回值
    }

code状态码：我们可以参考http状态设计：

HTTP状态码：
    200 - 请求成功
    301 - 资源（网页等）被永久转移到其它URL
    404 - 请求的资源（网页等）不存在
    500 - 内部服务器错误

分类的好处就把**错误类型归类到某个区间内**，如果区间不够，可以设计成4位数。

#900～999   区间表示系统异常错误
    #1000～1999 区间表示用户模块1错误
    #2000～2999 区间表示用户模块2错误

这样前端开发人员在得到返回值后，**根据状态码就可以知道，大概什么错误**，再根据message相关的信息描述，**可以快速定位。**

简单实现，这里我是为兼容旧项目，不得使用status代替code，这个无关紧要，只要规范统一旧可以。

@Data
    public class RestVO<T> {
    
        private int status = 0;
        private String msg = "success";
        //前端不展示，方便开发检查。
        private String error;
        private T data;
    
        public RestVO() {
        }
    
        public RestVO(T data) {
            this.data = data;
        }
    
        public RestVO(int code, String msg) {
            this.status = code;
            this.msg = msg;
        }
    
        public RestVO(int code, String msg, T data) {
            this.status = code;
            this.msg = msg;
            this.data = data;
        }
    
        public RestVO(RestCode restCode) {
            this.status = restCode.getCode();
            this.msg = restCode.getMsg();
        }
    
        public RestVO(RestCode restCode, String error) {
            this.status = restCode.getCode();
            this.msg = restCode.getMsg();
            this.error = error;
        }
    }

## 4、异常处理统一规范： ##

统一异常处理需要依赖rest接口格式规范。

基础框架组件需要对异常进行统一处理，规范异常处理的行为。这样各个具体项目基于这个框架组建开，减少重复造轮子。

具体实现：

[Spring学习笔记(9)一springMVC全局异常处理\_黄规速博客:学如逆水行舟，不进则退-CSDN博客\_springmvc全局异常处理 ][Spring_9_springMVC_-CSDN_springmvc]

## 5、参数校验 ##

参数校验主要是定义一些注解实现请求参数校验和格式化

**1、示例1：@RegionFormat（地区格式化）：**

被@RegionFormat注解的属性，会接受一个地区id转换为地区对象。

@RegionFormat
    private Region region;

上述注解假设如下请求：

> xxx?region=3

则会将id为1的地区及其父的信息读取并形成Region对象

例如region=3的地区为长安街，父辈为为东城区-->北京，刚形成的Region对象数据如下：

{
        "cityId": 2,
        "townId": 0,
        "countyId": 3,
        "provinceId": 1,
        "province": "长安街",
        "county": "东城区",
        "city": "北京市",
        "town": ""
    }

2、@Mobile （手机格式校验）

使用@Mobile注解可以校验手机号码的正确性。

使用：在声明的对象手机号码属性上面加@Mobile

@Mobile
     private String mobile;

如果校验失败会抛出如下异常：

{
      "code": "004",
      "message": "手机号码格式不正确"
    }

## 6、安全处理机制 ##

主要是防xss攻击的一些措施。例如防xss攻击过滤。

## 7、api文档 ##

使用Swagger2做api文档，同时封装Swagger配置基类：

public abstract class AbstractSwagger2 {
    
        /**
         * 构建认证token参数
         *
         * @return token参数
         */
        protected List<Parameter> buildParameter() {
    
            ParameterBuilder tokenPar = new ParameterBuilder();
            List<Parameter> pars = new ArrayList<Parameter>();
    //       tokenPar.name("sign").description("sign").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
    //       pars.add(tokenPar.build());
            return pars;
        }
    
    }

待续... ...

8、基础应用配置。

9、模型统一规范格式。

10、一些基础工具类：比如项目使用获取ip，邮箱、手机号等校验。

11、单元测试规范。

#  #

[Link 1]: https://blog.csdn.net/hguisu/category_5905793.html
[1_-]: https://guisu.blog.csdn.net/article/details/78258430
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBAaGd1aXN1_size_20_color_FFFFFF_t_70_g_se_x_16]: /images/20220828/97b51e3aa0da462bb40957b6564719a2.png
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBAaGd1aXN1_size_20_color_FFFFFF_t_70_g_se_x_16 1]: /images/20220828/1975ad611e144b8fa1a8c19aebdc220a.png
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBAaGd1aXN1_size_20_color_FFFFFF_t_70_g_se_x_16 2]: /images/20220828/11fe13da218a419b85e51251b55ae029.png
[Spring_9_springMVC_-CSDN_springmvc]: https://guisu.blog.csdn.net/article/details/52537705