JAVA开发规范(jeesite框架版)

文字版：

一、编程规范：
1.简单设计原则

通过所有测试（Passes its tests）：强调的是外部需求，这是代码实现最重要的
尽可能消除重复 (Minimizes duplication)：代码的模块架构设计，保证代码的正交性，保证代码更容易修改
尽可能清晰表达 (Maximizes clarity)：代码的可阅读性，保证代码是容易阅读的
更少代码元素 (Has fewer elements)：保证代码是简洁的，在简洁和表达力之间，我们更看重表达力
以上四个原则的重要程度依次降低。
2.命名规范
项目，目录命名：全部采用小写方式，以中划线分隔。
正例：mall-management-system / order-service-client / user-api
反例：mall_management-system / mallManagementSystem / orderServiceClient
包命名，虚拟目录，资源路径命名：名称使用英文，全部字母小写，通常都是一个单词，词性是名词，如果需要多个单词，单词之间使用下划线。
正例：mall_management-system / order_service_client / user_api
反例：mall-management-system / mallManagementSystem / orderServiceClient
Java 代码命名：
1、包名：包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，例如：com.htlwk.qpw.util。
2、类名：帕斯卡命名法（PascalCase），又称之为大驼峰式命名法（UpperCamelCase），每一个单词的首字母都大写，类名如果有复数含义，类名可以使用复数形式，例如：SimpleDataFormat、MessageUtils
3、方法名：骆驼式命名法（CamelCase），又称之为小驼峰式命名法（LowerCamelCase），混合使用大小写字母，即多个单词的情况下，第一个单词首字母小写，其余单词首字母均大写。方法名一般采用动词+名词或动词表示，如 append()、getName()、printStackTrace()等。
4、变量名（对象名）：和方法名一样的规范，一般采用名词或形容词+名词的形式表示。
5、属性名：和变量名一样的规范，一般采用名词或形容词+名词的形式表示。如 name、dbClassName、dbUser、dbPassword、dbUrl 等。
6、常量名：下划线命名法（UnderScoreCase），全部大写，单词之间加下划线，例如：MAX_PRIORITY。
3.项目提交规范
(1) type
type用于说明 commit 的类别，只允许使用下面7个标识：
feat：新功能（feature）
fix：修补bug
docs：文档（documentation）
style：格式（不影响代码运行的变动）
refactor：重构（即不是新增功能，也不是修改bug的代码变动）
test：增加测试
chore：构建过程或辅助工具的变动
如果 type 为 feat 和 fix，则该 commit 将肯定出现在 Change log 之中。其他情况（docs、chore、style、refactor、test）由你决定，要不要放入 Change log，建议是不要。
(2) scope
用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。
(3) subject
subject 是 commit 目的的简短描述，不超过 50 个字符。
以动词开头，使用第一人称现在时，比如 change，而不是 changed 或 changes。
第一个字母小写。
结尾不加句号（.）。

4.方法，参数规范
方法之间要有空行，更加清晰。
接口传参时，去掉没用的参数。
无论是 controller，servicer，dao 亦或是其他的代码，每个方法最多 3 个参数，如果超出 3 个参数的话，要封装成 javabean 对象。
1.方便他人调用，降低出错几率。尤其是当参数是同一种类型，仅仅依靠顺序区分，稍有不慎便是灾难性后果，而且排查起来也极其恶心。
2.保持代码整洁、清晰度。当一个个方法里充斥着一堆堆参数的时候，再坚强的人，也会身心疲惫。
反例：
/** * 使用证书加密数据工具方法 * * @param param * @param password 加密密码 * @param priCert 私钥 * @param pubCert 公钥 * @return 返回加密后的字符串 */
public String signEnvelop(JdRequestParam param, String password, String priCert, String pubCert){}

5.注释规范
（ // 代码说明）一般使用行前注释，注释与说明之间要有空格，更加清楚
没有用的注释要去掉。
代码写完，进行代码格式化。快捷鍵：ctrl+alt+L /ctrl+shift+L （因环境不同选择，自行尝试）
业务注释（一般为方法，接口）：使用文档注释（快捷键：ctrl+shift+/)
eg: /**
*说明
*@param 参数名含义
@param 参数名 ...
@return 返回值说明（可选）
/
方法注释
方法要尽量通过方法名自解释，不要写无用、信息冗余的方法头，不要写空有格式的方法头注释。
方法头注释内容可选，但不限于：功能说明、返回值，用法、算法实现等等。尤其是对外的方法接口声明，其注释，应当将重要、有用的信息表达清楚。
正例：
/ * 解析转换时间字符串为 LocalDate 时间类 * 调用前必须校验字符串格式否则可能造成解析失败的错误异常 * * @param dateStr 必须是 yyyy-MM-dd 格式的字符串 * @return LocalDate /public static LocalDate parseYMD(String dateStr){}
反例：
1./ * 校验对象 * * @param t * @return String */
2.public static String checkObj(T t);
反例中出现的问题：
方法注释没有说明具体的作用、使用事项。
参数、返回值，空有格式没内容。这是非常重要一点，任何人调用任何方法之前都需要知道方法对参数的要求，以及返回值是什么。

二、Jeesite框架规范：
1.Controller:
返回变量时，如果不进行处理，直接返回。
抛出异常问题，没有异常可抛时，不使用try-catch。
泛型前边定义了，后边的进行省略。（service使用时同理）
Page分页等视图处理，放在controller层。
只允许在 method 上添加 RequestMapping 注解，不允许加在 class 上（为了方便的查找 url，放到 url 不能一次性查找出来）
正例：
@RestControllerpublic class DepartmentController {

@GetMapping("/department/list")
public ResponseDTO<List> listDepartment() {
return departmentService.listDepartment();
}
反例：
@RequestMapping ("/department")public class DepartmentController {

@GetMapping("/list")
public ResponseDTO<List> listDepartment() {
return departmentService.listDepartment();
}
controller 负责协同和委派业务，充当路由的角色，每个方法要保持简洁：
1.不做任何的业务逻辑操作
2.不做任何的参数、业务校验，参数校验只允许使用@Valid 注解做简单的校验
3.不做任何的数据组合、拼装、赋值等操作
2.Service：
 “”.equals（）常量判断写在前边。
合理拆分 service 文件，如果业务较大，请拆分为多个 service。
如订单业务,所有业务都写到 OrderService 中会导致文件过大，故需要进行拆分如下：
OrderQueryService 订单查询业务
OrderCreateService 订单新建业务
OrderDeliverService 订单发货业务
OrderValidatorService 订单验证业务
为了不那么依赖框架，尽量不使用@Autowired注解，多使用构造器。
正例：public DetailsLandContractManagementService(DetailsLandContractManagementDao detailsLandContractManagementDao) {
this.detailsLandContractManagementDao =
detailsLandContractManagementDao;
}

反例：@Autowired
private LandCirculationApplyBillInfoDao landCirculationApplyBillInfoDao;

3.Dao：
dao层方法命名规范:
1.获取单个对象的方法用 get 做前缀。
2.获取多个对象的方法用 list 做前缀。
3.获取统计值的方法用 count 做前缀。
4.插入的方法用 save/insert 做前缀。
5.删除的方法用 remove/delete 做前缀。
6.修改的方法用 update 做前缀。
建议：dao层方法命名尽量以sql语义命名，避免与业务关联。
正例：
List listByMonthAndItemId(@Param("month") String month, @Param("itemId") Integer itemId);
反例：
List getInternalData(@Param("month") String month, @Param("itemId") Integer itemId);
反例中出现的不规范操作：
1.get代表单个查询，批量查询的应该 list 开头。
2.命名与业务关联，局限了dao方法的使用场景和范围，降低了方法的复用性，造成他人困惑以及重复造轮子。

4.Entity
Xxxx 与数据库表名保持一致
类中字段要与数据库字段保持一致，不能缺失或者多余
类中的每个字段添加注释，并与数据库注释保持一致
项目内的日期类型必须统一，建议使用 java.util.Date，java.sql.Timestamp，java.time.LocalDateTime 其中只一。
5.XML
建议不要使用星号 * 代替所有字段
禁止直接在xml中写死常量，应从dao中传入到xml中

正例：
反例：

查询、修改、删除条件规范：
1.需要区分必要条件和非必要条件。
2.必要条件禁止使用条件，避免上层调用未限制，参数为空导致的数据异常问题。
3.避免使用方言类方法，如 oracle的sysdate等，避免更换数据库时出现不支持的问题。
4.分页查询中的排序字段必须保证唯一性，比如按照创建时间排序，如果同一时间有多条数据，可能会导致分页数据错误，可以将主键ID作为排序因子同时参与排序。

三、数据库规范：

建表规范
表必备三字段：id, create_time, update_time
id 字段 Long 类型，单表自增，自增长度为 1
create_time 字段 datetime 类型，默认值 CURRENT_TIMESTAMP
update_time 字段 datetime 类型，默认值 CURRENT_TIMESTAMP, On update CURRENT_TIMESTAMP
常用类型规范：
状态类型字段优先使用 TINYINT/VARCHAR 3个长度，默认状态值为0，一般作为初始状态
一般字符类字段使用VARCHAR类型，长度建议100或200，避免使用CHAR类型
四、其他：
提交前应该冷静、仔细检查一下，确保没有忘记加入版本控制或不应该提交的文件。
提交前应该先编译一次（idea里ctrl+F9），防止出现编译都报错的情况。
提交前先更新pull一次代码，提交前发生冲突要比提交后发生冲突容易解决的多。
提交前检查代码是否格式化，是否符合代码规范，无用的包引入、变量是否清除等等。
提交时检查注释是否准确简洁的表达出了本次提交的内容。
使用git，必须添加 .gitignore 忽略配置文件。
不要提交与项目无关的内容文件：idea配置、target包等。