研发规范杂谈
面向对象的语言诀窍在于思考抽象。
编码质量
推荐工具检测
| 插件名称 | 作用 | 建议程度 |
|---|---|---|
| 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验证，类行为属性验证），序列化/反序列处理配置。
- 暴露的接口、端点必须有注释说明，必要情况下可附文档链接。
- 应禁止直接在本层中处理业务逻辑。将主要逻辑处理委派给业务领域层处理。
- 应当避免本层中存在继承，互相依赖的情况。
