研发规范杂谈

面向对象的语言诀窍在于思考抽象。

编码质量

推荐工具检测

插件名称	作用	建议程度
IDEA自带插件（IDEA Analyze）	编译器警告	强制
SonarLint	代码质量检查	强制
CodeMetric	代码复杂度提醒	建议
MetricsReloaded	代码复杂度计算	建议
Alibaba Java Coding Guidelines	代码规范	建议/部分规范不建议

代码复杂度各项指标

指标项	英文全称	中文说明
CogC	Cognitive Complexity	认知复杂度，即代码可读性
ev(G)	Essential Cyclomatic Complexity	基本复杂度
iv(G)	Module Design Complexity	模块设计复杂度
v(G)	Cyclomatic Complexity	圈复杂度
WMC	Weighted methods per class	每个类的加权方法 复杂度

关于Lombok

• 属性及方法最小化原则，仅推荐使用@Getter，@Setter，@Slf4j 注解。
• JaveBean属性较多的类禁止使用@Data，@Builder，@Accessors 静态构造，链式调用引发的JavaBean问题
• 禁止使用@RequiredArgsConstructor+ final 进行Spring的Bean强依赖构造。防止生成复杂构造器，Bean初始化问题等。
• 不建议使用@SneakyThrows注解。使用该注解会将受检异常转换为非受检异常，但在转换过程中会丢失原始异常的类型信息。破坏了异常处理的语义，可能导致不可控的程序行为。

IDEA推荐插件

• GitToolBox
• MybatisX
• Maven Helper
• GenerateAllSetter
• GsonFormatPlus
• Statistic

归档原则

OSS文件归档原则

• 临时文件：/temp/{profile}/{bizKey}[/bizId]/{fileName}
• 正常文件：/public/{profile}/{bizKey}[/bizId]/{fileName}
• 私有文件：/private/{profile}/{bizKey}[/bizId]/{fileName}

GIT分支归档原则

• 功能迭代分支：feature/xxx
• 修复分支：hotfix/xxx（线上紧急）或者fix/xxx（开发测试）
• 优化、重构分支 ：optimize/xxx

缓存，分布式锁的KEY原则

原则上redis的key命名应该全部小写，并且使用:作为key的分隔符。 除极端特殊情况外所有的Redis数据都应该有过期时间设置。

• 锁：lock:{BIZ_KEY}[:BIZ_ID] 注意：BIZ_KEY也可以是多级结构。
• 缓存：cache:{BUSI_DATA_NAME}[:BIZ_ID]注意：BUSI_DATA_NAME指的是缓存的业务数据的唯一名称，也可以是多级结构。

日志记录存储原则

日志首选框架logback，SpringBoot默认采用logback作为日志框架，无缝集成，最佳的兼容与支持。虽然log4j2支持异步日志记录，性能较强。但性能差距不是一个决定性因素，且除了巨量的日志记录和极端要求性能的情况下，log4j2的性能与logback性能差距微乎其微。

日志存放路径最佳实践：/opt/logs/${spring.application.name}/${server.port:8080}/out.log

SpringCloud业务微服务结构示例

项目主结构

src/
src/main
src/main/java
src/main/resources
src/main/resources/banner
src/main/resources/META-INFO
.gitlab-ci.yml
.gitignore
Dockerfile
pom.xml
readme.md

重要配置项说明

• application.yml：程序应用的主要/核心配置信息。与应用程序功能直接相关的配置项，包括你的应用程序的业务逻辑和功能所需的各种配置。
• bootstrap.yml：程序引导配置，加载顺序比application.yml早，一般配置应用程序上下文，用于引导的基础设施的环境配置。可分环境，引导可变配置信息，例如Spring Cloud等。

最佳实践：application.yml更适合和程序本身有关的静态配置信息，固定配置信息，例如，日志相关，框架本身程序配置相关。bootstrap.yml更适合对程序环境配置，框架引导配置，包括一些较为动态或频繁变化的参数。

• pom.xml：私服配置，技术选型，依赖原则（拥抱原生框架，Spring生态）。
• .gitlab-ci.yml：Gitlab的CI配置文件
• Dockerfile：镜像构建配置文件

关于类与对象，分层模式

实体、值对象、数据传输对象

示例对象：Entity，ValueObject，Payload，QueryParams

• 每个类都有自己的类行为，包括对自身的构建，对自身属性进行完善，验证，组装，转化。
• 体积最小化原则，避免过度的属性设计，降低序列化/反序列化的压力。贫血模型应减少非自身属性的行为设计。

仓储对象(Repository)

示例对象：IService（Mybatis-Plus），Repository（JPA，Hibernate），Mapper（Mybatis），Dao

• 与数据存取相关的行为，应具备复用性，易用性，职责明确。推荐使用Spring提供的注解@Repository
• 可为数据仓储行为有关的行为进行简单的验证和处理。
• 存在事务管理（除特殊情况外）。

业务领域对象(Service)

示例对象：Service Context Executor Assembler Factory Listener Processor Handler

• 本层代码需要体现业务逻辑主干，应减少无关代码（例如数据构建/验证过程，无效的私有逻辑）
• 重要的逻辑和流程需完善注释和日志。
• 降低代码的复杂度，避免过长，过于零散的逻辑设计。
• 思考抽象，做好类行为归纳，合理使用分层，组合等模式。
• 需综合考虑性能，避免长事务，尤其注意在循环中存在的查询，远程调用等操作。

门面/控制/视图层对象(Controller/API)

示例对象：@RestController Facade API Validator Handler @FrameworkEndpoint

• 接收用户请求，对请求进行过滤，验证（JSR303验证，类行为属性验证），序列化/反序列处理配置。
• 暴露的接口、端点必须有注释说明，必要情况下可附文档链接。
• 应禁止直接在本层中处理业务逻辑。将主要逻辑处理委派给业务领域层处理。
• 应当避免本层中存在继承，互相依赖的情况。