欢迎您访问 最编程 本站为您分享编程语言代码，编程技术文章！

热门搜索/Hot Search

您现在的位置是： 首页

对于10人小团队，打造高效Java开发的利器 - 这份Java开发规范指南足够实用!

最编程 2024-07-21 20:19:49
...

一、编程规范

1、好代码的原则

Kent Beck 的简单设计四原则非常好地来指导我们的如何写出优秀的代码，如何有效地判断我们的代码是优秀的。

通过所有测试（Passes its tests）：强调的是外部需求，这是代码实现最重要的
尽可能消除重复 (Minimizes duplication)：代码的模块架构设计，保证代码的正交性，保证代码更容易修改
尽可能清晰表达 (Maximizes clarity)：代码的可阅读性，保证代码是容易阅读的
更少代码元素 (Has fewer elements)：保证代码是简洁的，在简洁和表达力之间，我们更看重表达力

以上四个原则的重要程度依次降低， 这组定义被称做简单设计原则。

2、项目命名规范

全部采用小写方式， 以中划线分隔。

正例：mall-management-system / order-service-client / user-api

反例：mall_management-system / mallManagementSystem / orderServiceClient

3、TODO/FIXME 规范

TODO/TBD(to be determined) 注释一般用来描述已知待改进、待补充的修改点,并且加上作者名称。  FIXME 注释一般用来描述已知缺陷，它们都应该有统一风格，方便文本搜索统一处理。如：

// TODO <author-name>: 补充XX处理

// FIXME <author-name>: XX缺陷

4、方法参数规范

无论是 controller，service，manager，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、注释规范

5-1、注释和代码一样重要

注释是我们披荆斩棘历经磨难翻越需求这座大山时，留下的踪迹和收获的经验教训，这些宝贵的知识除了证明我们曾经存在过，也提醒着后来的人们殷鉴不远、继往开来。

注释除了说明作用、逻辑之外。还有一个很重要的原因：当业务逻辑过于复杂，代码过于庞大的时候，注释就变成了一道道美化环境、分离与整理逻辑思路的路标。这是很重要的一点，它能有效得帮助我们免于陷入代码与业务逻辑的泥沼之中。

正例：

/**
* 开始抽奖方法
* 保存中奖信息、奖励用户积分等
* @param luckDrawDTO
* @return ResponseDTO 返回中奖信息
*/
public ResponseDTO<String> startLuckDraw(LuckDrawDTO luckDrawDTO) {
 
    // -------------- 1、校验抽奖活动基本信息 ------------------------
    xxx伪代码一顿操作
 
    // -------------- 2、新增抽奖记录 -------------------------------
    xxx伪代码一顿操作
 
    // -------------- 3、如果需要消耗积分，则扣除钢镚积分 -------------
    xxx伪代码一顿操作
 
    // -------------- 4、获取奖品信息，开始翻滚吧 --------------------
    xxx伪代码一顿操作
 
    return ResponseDTO.succ(luckDrawPrizeVO);
}

5-2、注释和代码的一致性

注释并不是越多越好，当注释过多，维护代码的同时，还需要维护注释，不仅变成了一种负担，也与我们当初添加注释的初衷背道而驰。  

首先：大家应该通过清晰的逻辑架构，好的变量命名来提高代码可读性；需要的时候，才辅以注释说明。注释是为了帮助阅读者快速读懂代码，所以要从读者的角度出发，按需注释。注释内容要简洁、明了、无二义性，信息全面且不冗余。

其次：无论是修改、复制代码时，都要仔细核对注释内容是否正确。只改代码，不改注释是一种不文明行为，破坏了代码与注释的一致性，会让阅读者迷惑、费解，甚至误解。

反例：

// 查询部门
EmployeeDTO employee = employeeDao.listByDeptId(deptId);

5-3、方法注释

方法要尽量通过方法名自解释，不要写无用、信息冗余的方法头，不要写空有格式的方法头注释。

方法头注释内容可选，但不限于：功能说明、返回值，用法、算法实现等等。尤其是对外的方法接口声明，其注释，应当将重要、有用的信息表达清楚。

正例：

/**
 * 解析转换时间字符串为 LocalDate 时间类
 * 调用前必须校验字符串格式 否则可能造成解析失败的错误异常
 *
 * @param dateStr 必须是 yyyy-MM-dd 格式的字符串
 * @return LocalDate
 */
public static LocalDate parseYMD(String dateStr){}

反例：

/**
 * 校验对象
 *
 * @param t
 * @return String
 */
public static <T> String checkObj(T t);

反例中出现的问题：

方法注释没有说明具体的作用、使用事项。
参数、返回值，空有格式没内容。这是非常重要一点，任何人调用任何方法之前都需要知道方法对参数的要求，以及返回值是什么。

二、项目规范

1、代码目录结构

统一的目录结构是所有项目的基础。

src                               源码目录

|-- common                            各个项目的通用类库

|-- config                            项目的配置信息

|-- constant                          全局公共常量

|-- handler                           全局处理器

|-- interceptor                       全局连接器

|-- listener                          全局监听器

|-- module                            各个业务

|-- |--- employee                         员工模块

|-- |--- role                             角色模块

|-- |--- login                            登录模块

|-- third                             三方服务，比如redis, oss，微信sdk等等

|-- util                              全局工具类

|-- Application.java                  启动类

2、common 目录规范

common 目录用于存放各个项目通用的项目，但是又可以依照项目进行特定的修改。

src 源码目录

|-- common 各个项目的通用类库

|-- |--- anno          通用注解，比如权限，登录等等

|-- |--- constant      通用常量，比如 ResponseCodeConst

|-- |--- domain        全局的 javabean，比如 BaseEntity,PageParamDTO 等

|-- |--- exception     全局异常，如 BusinessException

|-- |--- json          json 类库，如 LongJsonDeserializer，LongJsonSerializer

|-- |--- swagger       swagger 文档

|-- |--- validator     适合各个项目的通用 validator，如 CheckEnum，CheckBigDecimal 等

3、config 目录规范

config 目录用于存放各个项目通用的项目，但是又可以依照项目进行特定的修改。

src                               源码目录

|-- config                            项目的所有配置信息

|-- |--- MvcConfig                    mvc的相关配置，如interceptor,filter等

|-- |--- DataSourceConfig             数据库连接池的配置

|-- |--- MybatisConfig                mybatis的配置

|-- |--- ....                         其他

4、module 目录规范

module 目录里写项目的各个业务，每个业务一个独立的*文件夹，在文件里进行 mvc 的相关划分。其中，domain 包里存放 entity, dto, vo，bo 等 javabean 对象

src

|-- module                         所有业务模块

|-- |-- role                          角色模块

|-- |-- |--RoleController.java              controller

|-- |-- |--RoleConst.java                   role相关的常量

|-- |-- |--RoleService.java                 service

|-- |-- |--RoleDao.java                     dao

|-- |-- |--domain                           domain

|-- |-- |-- |-- RoleEntity.java                  表对应实体

|-- |-- |-- |-- RoleDTO.java                     dto对象

|-- |-- |-- |-- RoleVO.java                      返回对象

|-- |-- employee                      员工模块

|-- |-- login                         登录模块

|-- |-- email                         邮件模块

|-- |-- ....                          其他

5、 domain 包中的 javabean 命名规范

1） javabean 的整体要求：

不得有任何的业务逻辑或者计算
基本数据类型必须使用包装类型（Integer, Double、Boolean 等）
不允许有任何的默认值
每个属性必须添加注释，并且必须使用多行注释。
必须使用 lombok 简化 getter/setter 方法
建议对象使用 lombok 的 @Builder ，@AllArgsConstructor，同时使用这两个注解，简化对象构造方法以及set方法。

正例：

@Builder
@NoArgsConstructor
@Data
public class DemoDTO {
 
    private String name;
     
    private Integer age;
}

 

// 使用示例：
 
DemoDTO demo = DemoDTO.builder()
                .name("yeqiu")
                .age(66)
                .build();

 

2）数据对象；XxxxEntity，要求：

以 Entity 为结尾（阿里是为 DO 为结尾）
Xxxx 与数据库表名保持一致
类中字段要与数据库字段保持一致，不能缺失或者多余
类中的每个字段添加注释，并与数据库注释保持一致
不允许有组合
项目内的日期类型必须统一，建议使用 java.util.Date，java.sql.Timestamp，java.time.LocalDateTime 其中只一。

3）传输对象；XxxxDTO，要求：

不可以继承自 Entity
DTO 可以继承、组合其他 DTO，VO，BO 等对象
DTO 只能用于前端、RPC 的请求参数

3）视图对象；XxxxVO，要求：

不可继承自 Entity
VO 可以继承、组合其他 DTO，VO，BO 等对象
VO 只能用于返回前端、rpc 的业务数据封装对象

4）业务对象 BO，要求：

不可以继承自 Entity
BO 对象只能用于 service，manager，dao 层，不得用于 controller 层

三、MVC 规范

1、整体分层

controller 层
service 层
manager 层
dao 层

2、 controller 层规范

1） 只允许在 method 上添加 RequestMapping 注解，不允许加在 class 上（为了方便的查找 url，放到 url 不能一次性查找出来）

正例：

@RestController
public class DepartmentController {
 
    @GetMapping("/department/list")
    public ResponseDTO<List<DepartmentVO>> listDepartment() {
        return departmentService.listDepartment();
    }
}

反例：

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

2）不推荐使用 rest 命名 url， 只能使用 get/post 方法。url 命名上规范如下：

虽然 Rest 大法好，但是有时并不能一眼根据 url 看出来是什么操作，所以我们选择了后者，这个没有对与错，只有哪个更适合我们的团队。

/业务模块/子模块/动作

正例：

上一篇： 快速掌握JAVA基础入门必知要点

下一篇： 深入理解Java基础：探索Map集合的奥秘与细节

推荐阅读