Java编程规范(代码规范)--精选

蔚落 2023-09-23 21:49 100阅读 0赞

原文网址：[Java编程规范(代码规范)--精选\_IT利刃出鞘的博客-CSDN博客][Java_--_IT_-CSDN]

## 简介 ##

**说明**

本文介绍精选的Java编程规范（代码规范）。遵守这些规范，代码的bug数将会大幅减少，代码可维护性、可读性、扩展性会大幅上升。（本文持续更新）

**为什么要有编程规范？**

编程规范有如下作用：

1.  提高代码可读性、维护性、扩展性
2.  提高开发速度、减少bug
3.  有助于留住人才（接手别人的垃圾代码占离职原因的很大一部分）

**好的编程规范是怎样的？**

1.  规范要精简，否则不利于普及

**规范的落实**

1.  编程规范要配合代码审核，否则都是空话。
2.  代码审核必须在代码提测之前进行。（因为如果测试通过了，由于不符合编程规范再改动的话，需要费时间进行回归测试，导致影响上线）
3.  代码评审要以平台的方式进行：被评审者将代码提到评审平台，然后评审者在此平台进行批注，被评审者进行代码修改。
    
    1.  这种代码评审基本是毫无卵用的：多个人聚在一个会议室里，盯着一个电脑投屏进行评审。
4.  代码规范要加入绩效考核（占比在1%~5%之间），否则无法引起重视。
    
    1.  好的大公司就是这么做的，代码极好，扩展性极好，技术氛围极好，项目的质量极好、用户的反馈极好...

## 格式 ##

1.  单个方法不能超过**60行**，如果超过必须拆分
    
    1.  IDEA大概能显示40行代码，60行对一个方法来说肯定是够用的。
    2.  反例：所有逻辑堆在一个方法里，单个方法成百上千行
2.  单行代码不能超过**100个字符**（包括空格），如果超过必须换行。换行时遵循如下原则:
    
    1.  第二行相对第一行缩进 4 个空格；从第三行开始，不再继续缩进
    2.  运算符与下文一起换行；方法调用的点符号与下文一起换行
3.  if/for/while/switch/do 等保留字与括号之间必须加空格。

## 命名 ##

1.  命名可以很长，**不能为了缩短长度进行单词的简写**（提高可读性）。（例外：接口实现类以Impl结尾等通用的缩写）
    
    1.  正例：interfaceOperationCode
    2.  反例：intOpCode
2.  类名和包名统一使用单数形式，但是如果类名有复数含义，类名可以使用复数形式
    
    1.  正例：com.abc.user.detail
    2.  反例：com.abc.user**s**.detail
3.  包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。如果必须要用两个单词，用驼峰格式
    
    1.  正例 : com.alibaba.open.util、com.abc.userDetail
4.  抽象类命名使用Abstract开头；异常类命名用Exception结尾；接口类命名**不要添加无用的前缀与后缀**（比如：I开头、Interface结尾）
5.  POJO类中**布尔类型变量不要加is前缀**，否则部分框架解析会引起序列化错误。
    
    1.  反例：将是否删除定义为：Boolean isDeleted
    2.  正例：将是否删除定义为：Boolean deletedFlag
6.  Controller的url命名规范：
    
    1.  驼峰命名。
    2.  统一是这种：**/表名/增删改查**，比如：用户详情的增加接口：/userDetail/add。增删改查对应的英文如下：
        
        1.  增加：add
        2.  编辑：edit
        3.  删除：delete
        4.  分页查询：page
        5.  列表查询：list

## 常量 ##

1.  不要使用一个常量类维护所有常量，应该**按常量功能进行归类**，分开维护（提高可维护性）。
    
    1.  正例：缓存相关的常量: CacheConstant；配置相关的常量: ConfigConstant。
2.  **常量命名全部大写**，单词间用下划线隔开。
    
    1.  正例 : MAX\_STOCK\_COUNT
    2.  反例 : Max\_Stock\_Count

## 类型 ##

1.  **禁止使用Map**作为方法的入参或返回值，必须使用对象明确列出所有字段。（例外：有些地方只能是Map类型，比如：短信发送接口，参数是不确定的，调用方自定义key和value）
    
    1.  反例：给别人提供Feign接口时，返回值是Map类型。
    2.  正例：定义一个XxxVO，将字段写到XxxVO里，作为接口返回值。
    3.  正例：查很多用户详情时，为提高接口速度，将单个SQL转成批量SQL（将多个=转化成单个IN），然后将其结果转成key为用户id，value为用户数据的Map，再进行后续操作。
2.  如果代码内部用到了Map，必须在map定义处**写明key和value分别是什么**。
3.  这些地方**必须使用包装数据类型**：所有的 POJO 类属性、RPC 方法的返回值和参数
    
    1.  即：要用Integer、Long等，不要用int、long
4.  实体类**不要implements Serializable**
    
    1.  Serializable是序列化，现在都是使用JSON了，不要再实现Serializable了！（题外话：写代码时要思考，看究竟有什么用，不明白的就去搞明白，不要糊里糊涂地写）。
    2.  当然，有时候就必须要实现Serializable，比如：Dubbo的实体类，默认用的是Serializable的序列化来传递数据，所以必须实现Serializable。

## 参数与返回值 ##

1.  **不能修改入参对象的字段**，如果要修改，必须新创建一个对象
    
    1.  例外：如果方法就是为了给入参对象赋值的，可以去修改。
2.  方法**入参的个数必须小于5**
    
    1.  如果大于等于5，必须将入参封装为一个类。
3.  分页接口的请求和响应必须继承公共父类，如下：

分页的请求类

import com.fasterxml.jackson.annotation.JsonFormat;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    import java.time.LocalDateTime;
    
    @Data
    public class PageRequest {
        @ApiModelProperty("当前页")
        private Long currentPage = 0L;
    
        @ApiModelProperty("每页个数")
        private Long pageSize = 10L;
    
        @ApiModelProperty("创建时间开始")
        private LocalDateTime createTimeStart;
    
        @ApiModelProperty("创建时间结束")
        private LocalDateTime createTimeEnd;
    }

分页的响应类

import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    import java.util.List;
    
    @Data
    public class PageResponse<T> {
        @ApiModelProperty("当前页")
        private Long currentPage = 0L;
    
        @ApiModelProperty("每页个数")
        private Long pageSize = 10L;
    
        @ApiModelProperty("总个数")
        private Long totalSize = 0L;
    
        private List<T> dataList;
    }

## 注释 ##

1.  所有**接口说明都使用knife4j**的，不要重复写注释。
2.  方法注释中没用的说明要删掉，比如：参数后如果没加详细说明，就把这行参数注释删掉。
3.  文件前不要让Idea自动生成创建时间、创建人。
    
    1.  原因：这是多余的操作，git已经记录了此文件的创建人和创建时间

## 复用 ##

1.  逻辑重复的代码要抽取为同一个（提高复用性）
    
    1.  正例：页面上的分页查询、Excel导出查询的数据，这两个共用查数据的方法。

上边是本文的部分内容，为便于维护，全文已转移到此网址：[Java编程规范(代码规范)-精选 - 自学精灵][Java_-_ -]

[Java_--_IT_-CSDN]: https://knife.blog.csdn.net/article/details/128619339
[Java_-_ -]: https://learn.skyofit.com/?p=1783