跳到主要内容

后端开发

后端工程规范实践​

依赖引入​

  • 为确保依赖版本的统一管理和维护，所有依赖包均在根工程 innospots-root 的 POM 文件中进行集中定义。具体而言，依赖包的版本号统一在 properties 变量中声明，其他子模块在引入依赖时不允许直接指定版本号。

  • 项目中所需的所有第三方 jar 包依赖都必须在 dependencyManagement 中进行统一声明和管理。这样可以有效控制依赖版本，避免版本冲突。

  • 对于包含子模块的父模块，其 packaging 类型需设置为 pom。在父模块的 dependencyManagement 中统一定义子模块所需的依赖包。如果某个依赖被所有子模块共用，则可以直接在父模块的 dependencies 中声明，子模块将自动继承。

命名规范​

模块命名规范​

  • 工程模块全部以innospots-开头
  • 工程模块名称使用kebab-case命名法，单词间以中划线分隔，单词小写
  • 工程模块名称使用2-4个单词命名，最多不超过5个
  • 命名方式上体现模块间的上下级关系，例如：innospots-extension模块下的所有子模块全部以innospots-extension-*开头

包命名规范​

  • 包的命名方式采用两种方式： 一种为基于MVC架构的包命名方式，按数据库层，服务层，接口层，模型层，实体层命名，常用于做管理平台类工程或模块使用。一种为基于业务领域，功能模块的命名方式，按包中的业务功能或支撑功能划分包结构。
  • 包名尽量使用完整单词或行业通用缩写词，不建议使用两个单词定义包名
  • 在语义明确的前提下，尽量精简，做到见名知意
  • 包名称命名全部小写

以下为通用功能下的常用包名定义

  • configuration, Spring Configuration，自定义Properties
  • controller, 管理平台端Restful API接口
  • constant, 常量值类
  • entity, 数据库表的实体POJO
  • model, 业务类模型POJO，与实体POJO有对应关系
  • dao, 数据库操作，返回实体类
  • operator, 在管理端对数据库的CURD的操作，对controller层提供实际数据操作实现，包含参数校验，简单的数据层面的逻辑处理
  • mapper, mapstruct的POJO转换Mapper，entity的POJO和业务模型的POJO的转换
  • service, 复杂业务逻辑，多模块的operator的聚合调用
  • enums, 枚举类型定义
  • exception, 业务异常类
  • utils, 工具类定义，日期，字符串转换，国际化，Bean拷贝等
  • endpoint, 服务类API
  • filter, Servlet Filter的自定义实现类
  • starter, Spring Boot 启动后调用的ApplicationRunner实现类
  • server, 应用服务启动主类，或嵌入服务
  • event, 事件定义，基于ApplicationEvent，或自定义Event的实现
  • interceptor, Spring MVC 的interceptor的自定义实现类
  • aspect, 基于Spring AOP的拦截定义
  • listener, event的监听器
  • loader, 资源加载，数据加载

类命名规范​

  • 符合Java类基本命名规范
  • 采用驼峰式命名
  • 类名称通常采用主语词+核心功能后缀词的方式定义，采用名词作为后缀词，表明当前类的核心用途，可体现出层级
  • 除了业务POJO外，类名需要使用两个以上单词定义，避免使用单个通用性单词定义类名，例如：Config,Status等，更好方式应该定义为DataConfig，TaskStatus等更加语义明确的名称定义
  • 类注释上必须包含作者，版本号，时间日期，以及类的用途说明

常用类名词参考

  • **Entity, 数据库表实体POJO
  • **Dao, 数据库ORM框架中的实体操作类，集成Mybatis Plus的BaseMapper的数据访问类
  • **Controller, 管理平台Restful API接口
  • **Filter, 管理平台端Servlet javax.servlet.Filter的实现类
  • **Interceptor, 管理平台端 Spring Web中的HandlerInterceptor的实现类
  • **Operator, CURD数据的操作类
  • **Service, 跨模块，多Operator的业务服务实现
  • **Mapper, mapstruct的Mapper，实体POJO与业务模型POJO的转换
  • **Handler, 在业务责任链模式中的输入数据的接收者和业务处理
  • **Encoder, 对数据的编码或加密
  • **Decoder, 对数据的解码或解密
  • **Utils, 工具类，静态类
  • **Loader, 数据加载，资源加载
  • **Operator, 数据的业务模型层的CRUD操作
  • **Endpoint, 服务类型的API接口
  • **Exception, 业务异常，继承RuntimeException
  • **Configuration, Spring Configuration 定义
  • **Properties, Spring Properties的定义
  • **Watcher, 观察者，定时执行，监听执行
  • **Manager, 业务资源管理类，用于资源加载到Manager中，由Manager负责业务资源的处理和缓存
  • **Builder, 构造者模式的构造器，用于创建新的对象和数据
  • **Listener, Spring Application Event事件的监听器
  • **Perparer, 资源预备器，做业务逻辑预先准备使用
  • **Starter, Spring ApplicationRunner接口实现，用于启动加载资源，初始化使用
  • **Matcher, 匹配器，用于执行匹配，例如：UrlPattern的疲累
  • **Generator, 生成器，随机数，主键，字符串等生成
  • **Converter, 数据转换处理
  • **Server, 服务启动主入口
  • **Store, 数据存储
  • **Reader, 数据只读功能
  • **Receiver, 消息队列接收者
  • **Sender, 消息队列发送者
  • **Engine, 执行引擎
  • **Factory, 工厂模式功能类
  • **Facade, 门面模式功能类
  • **Executor, 执行器
  • **Event, Spring ApplicationEvent 自定义事件
  • **Status, 枚举类，业务状态的定义
  • **Type, 枚举类，业务类型定义
  • **Context, 执行上下文，数据上下文
  • **Execution, 执行记录，任务执行，流程执行
  • **Base, 业务模型基础类，用于做扩展集成
  • **Exporter, 数据导出，资源导出
  • **Importer, 基于注解的 Spring Configuration bean的集成导入定义
  • **Container, 业务执行容器
  • **Job, 调度任务定义
  • Base**, 抽象类，基础公共类定义

方法命名规范​

  • 方法命名主要采用动词+名词的命名规则，对业务性明确的类中可以直接使用动词做方法名称

以下为常用动词方案

  • fetch，接口获取数据
  • load， 页面加载
  • build，模型构造，对象构建
  • change，状态变更
  • cancel，动作撤销
  • send， 监听模式的发送事件
  • receive，接收事件动作
  • create，新建操作
  • update，modify，更新操作
  • delete，删除操作
  • read，读取数据操作，包含接口获取，read方法主要用于只读功能类中的操作
  • listen，监听事件
  • find，query，select，查询list或数组中的数据，查询数据库数据，可有多种形式的查询条件，着重不同参数条件的查询
  • filter，对某个数据，按条件过滤
  • extract，抽取操作
  • format，将某对象格式化为固定格式字符串
  • parse，将字符串解析为对象
  • list，返回列表数据，无条件或者条件固定，着重返回的数据，弱化查询条件
  • get，获取模型字段值，获取单一模型数据
  • set，设置模型字段值
  • publish，发布动作
  • save，create或者update
  • record，插入数据，用于日志数据，记录型数据
  • refresh，刷新
  • show，展示显示操作，无翻页
  • clean，清除数据，清除状态
  • remove，移除动作，非物理删除
  • generate，创建生成对象，生成随机数等
  • check，检查值，检查合法性
  • start，开始启动，模块功能启动
  • stop，停止服务，停止线程
  • open，打开配置，打开流，打开资源
  • close，关闭资源
  • prepare，预处理准备
  • compile，编译动作
  • run，execute，执行动作
  • initialize，初始化
  • copy，拷贝对象，拷贝数组
  • fill，填充数据，基于参数数据填充
  • add，添加数据到列表或map
  • contain，是否包含数据
  • match，匹配判断

接口规范​

  • 管理平台类Controller接口主要采用Restful风格规范定义
  • 使用Spring MVC的PostMapping，DeleteMapping，PutMapping，GetMapping定义对资源的增删改查
  • Controller使用OpenAPI 3.0定义接口描述和参数信息
  • 对查询条件类字段使用Param类参数
  • 对业务操作类的API需要在URI中增加操作词说明，例如：online，offline，execute等
  • 使用javax.validation来验证输入参数的有效性和合法性，在参数的输入model中包含验证规则注解
  • 在io.innospots.base.constant.PathConstant定义ROOT_PATH为管理端API的contextPath，所有涉及管理平台端权限管控的API都需要以此常量作为contextPath路径设置
  • API Path路径命名使用kebab-case命名法，单词间以中划线分隔，单词小写
  • 服务类接口定义在endpoint包中，服务类接口只使用POST方法和GET方法定义接口操作

配置规范​

  • application.yaml， 服务的基础配置，不跟随环境进行变更
  • application-xxx.yml, 按不同的环境的配置，主要包含数据库的配置，系统变量的配置
  • application-security.yml, 权限拦截，授权key配置

开发实践​

管理模块​

Innospots提供通用管理平台Libra，包含最小化的管理平台功能支撑包括：工作台，通知消息，权限设置，菜单设置，国际化，系统配置管理以及数据看板

后端模块结构采用MVC结构模式，每个模块都有独立的MVC结构。管理平台的功能扩展通过扩展应用的形式增加平台功能扩展

  • controller, 模块API接口，以资源为粒度定义api接口的controller
  • dao, 物理数据表entity的CRUD功能，对数据表关联较强的场景，可在dao中单独定义连表查询方法，以注释的方式扩展连表查询
  • entity, 数据库实体表，按物理表对应，每个物理表对应一个entity的POJO
  • mapper, 业务模型和实体POJO的转换mapper，这里使用mapstruct做POJO的相互转换
  • model, 业务模型的POJO
  • operator, 数据资源的CRUD功能，对数据字段的有效性进行验证，在无表关联时，通常一个operator引用一个dao，对数据表业务关联关系较强的operator中可引用使用多个dao
  • service, 在包含负责的业务逻辑操作，需要在一个模块中跨多个operator完成时，可单独定义业务类的service，此service将引入多个operator处理复杂的业务逻辑，包含业务逻辑类的数据验证及判断

模块间交互​

  • 【service层集成】当有业务场景需要多个模块的功能时可在上层service上引入不同模块的operator或service实现多模块的功能操作
  • 【数据事件通知】通过Spring Event实现在跨模块间的数据交互，当一个模块中的业务逻辑涉及到跨模块的业务交互时，使用event机制实现数据交互。例如：菜单操作关闭，对应的菜单权限的设置关闭

菜单、权限与操作日志​

在管理端的API接口的Controller上定义接口的权限和菜单定义，每一个API接口对应Controller的一个方法，在Controller类和方法上增加注解项，明确定义API接口的菜单项，应页面端的操作以及操作日志

  • 在Controller类上定义菜单项【ModuleMenu】，key值为innospots-application-meta.json中modules的itemKey值，表明当前controller对应的模块操作项
  • 多个Controller对应一个菜单Module时，ModuleMenu设置相同的key值即可
  • 在Controller的方法上添加【ResourceItemOperation】的操作注解，标识菜单的操作接口，用于在菜单权限中设置操作权限配置，操作项不需要设置只读的接口
  • 在Controller的方法上添加【OperationLog】注解用于操作日志的记录，增加OperationLog的注解方法将在操作日志中记录操作日志

POJO​

  • 管理平台端定义了两类POJO，一类为Entity，一类为业务Model
  • Entity为数据表结构映射，使用常量TABLE_NAME定义对应的表名称
  • 在Entity的成员中使用了javax.persistence.Column注解标注数据表字段的类型，长度，主键信息，但系统的ORM并不使用Hibernate或JPA做ORM使用
  • 业务POJO用于接口返回数据结构
  • POJO中使用Lombok的@Getter和@Setter定义属性的操作，POJO中，不使用Lombok的其他注解

异常以及异常码​

  • innospots-base的exception中定义系统常用异常类
  • io.innospots.base.exception.BaseException为系统定义的基础异常类，所有其他系统异常继承此异常类
  • 业务自定义异常的方式使用build静态方法创建异常类实例，可参见业务异常类中的build构建实例
  • ErrorResponse作为异常异常的时的数据返回，code，message，detail包含当前的异常信息
  • GlobalExceptionHandler作为全局异常处理类，将拦截所有接口层面抛出的异常
  • io.innospots.base.model.response.ResponseCode中定义了系统状态码code的定义

数据操作​

  • 本系统使用Mybatis Plus作为基础dao模块的ORM操作类
  • 业务dao接口继承com.baomidou.mybatisplus.core.mapper.BaseMapper, 将继承对公共资源CRUD以及列表查询操作
  • 业务操作定义在operator中，继承com.baomidou.mybatisplus.extension.service.impl.ServiceImpl，将继承常用业务资源的CRUD功能

模块依赖引入​

  • 系统模块采用主动引入的方式将不同模块的'Spring Bean'引入到当前工程模块
  • 在每个模块的基础包定义模块的**Importer注解，此Importer将引入当前模块中所定义配置的'Spring Bean'引入到当前服务中
  • 在Importer中将明确的定义，Spring ComponentScan的生效的包范围，以及使用的Spring Configuration，在Configuration中明确定义模块中所使用的Spring Bean定义

事件总线​

  • 事件总线用于跨模块，跨系统，异步等场景使用，解耦和提升系统处理性能
  • io.innospots.base.events 中为系统自定义使用的事件处理模块
  • 对管理平台中，系统使用自定义的EventBus和对应的EventListener作为事件处理体系

观察者线程​

  • 在innospots-base模块watcher包中定义观察者线程
  • io.innospots.base.watcher.WatcherSupervisor观察者线程池， 系统中定义的观察者线程通过registry方法添加观察者线程的注册，在模块中定义ApplicationRunner中将此模块中的观察者线程添加到
  • 观察者线程由观察者线程池和观察者线程组成，观察者线程将以定时轮询的方式常驻内存执行，用于检查，定时更新等操作
  • 系统中定义了了多种功能的观察者，包括：服务注册观察者，Workflow上线状态观察者，等待定时执行观察者等