1 代码控制规范

1.1 拉取原则

强制
每日开始工作拉取

约定
提交之前拉取

1.2 提交原则

强制
提交代码必须构建成功(比如:编译,打包成共)
提交代码必须完整(比如:少提文件)
提交代码必须忽略到本地临时文件(比如:target, logs, .idea, *.iml,dist 等)

约定
完成一个功能提交
修改一个Bug修改提交
解决冲突提交
每日结束工作提交

1.3 提交注释

强制
中文填写注释
注释反映本次提交变更情况
commit 信息参照 Git Commit Template 规范

2 代码注释

  • 类,接口,枚举顶层注释
  • 接口方法注释
  • 静态方法注释
  • 公开方法注释
  • 类的属性字段注释
  • 常量注释
  • 不限于以上

3 接口定义

3.1 原则

接口地址定义表明用意
接口地址定义清晰,简洁,无歧义
同一个服务组件的接口定义具有一致性

3.2 格式

控制类的顶层地址格式:/{顶层分类名},例如:/devices 设备相关接口的顶层地址
接口定义使用Swagger的API注解说明
标注开发人,完整的请求信息,请求方法,请求地址,参数可选性,接口描述

3.3 请求方式

GET URL-Params
PUT Form-Data
POST RequestBody(JSON格式)
POST Form-Data
POST RequestBody(JSON格式)
POST Mulitpart
DELETE URL-Params

3.4 响应方式

ResponseBody(JSON格式)
统一的响应模型

4 异常处理

4.1 运行时异常

通过参数检查等方式避免或抛出运行时异常,日志记录

4.2 检查异常

检查异常需要捕获,处理,日志记录

5 日志记录

统一使用SLF4j接口

6 规范整理系统代码目录结构

6.1 模块命名

模块名称:{项目名称}-{模块名称} 模块名称简洁体现职责
模块名字作为模块组件的名称

6.2 源码目录

源码目录指:{项目目录}/src/main/
代码目录:src/main/java
资源目录:src/main/resources
/db:数据库脚本归档
/data:内部依赖数据归档
文档目录:src/main/docs
脚本目录:src/main/bin
run-manage.sh 运行管理脚本(通过参数start, stop, status, help info控制程序运行)
sh:服务组件启动脚本
sh:服务组件停止脚本

6.3 包规范要求

项目基本包:com.company.{项目英文名(较长时适当简化)}.{模块名(可选)}
config:配置类。包含各种系统配置、springBoot加载配置、Web配置等
startup:与服务启动相关的类
client:提供客户端实现的相关类。包含EmailSender、JMS和对接的其他服务接口的HttpClient等
common:公共类,定义常量类,工具组件 exception: 系统自定义异常类
schedule:调度和任务类,定时任务周期任务等 entity: 数据库相关的实体类
model: 数据模型类(参数或值模型VO,数据传输模型DTO等)
controller: 控制层接口。可包含filter目录、intercepter目录及其Web相关类目录
service: 服务层。包含相关业务接口
dao:数据库访问层,数据访问repository、DAO类

7 Java开发手册

Java开发手册(嵩山版)

Q.E.D.


好久不見,今日營業中