Java代码规范实践心得

iunique
462 阅读4分钟

一份好的代码Java代码离不开好的架构的设计以及一套成熟的代码规范，本文就我所在的部门的代码规范进行一些记录分享。

代码规范

1. Java 注释

建议所有的public函数和接口函数都加上规范的java Doc注释 如:

    /**
     * queryDataList,根据id查询数据列表
     *
     * @param id 主键id
     * @return 数据列表
     * @throws ServiceException
     */
    List<Data> queryDataList(String id)throws ServiceException;

这个可以在idea中配置模板
进阶: 可以使用

<pre> <p> <br>

等标签对java doc进行格式化，否则fmt一下会挤在一起。如果是http的数据拉取接口，甚至可以把 请求参数，返回，示例，接口文档放在java doc中，方便自己和他人阅读理解。

2. 函数长度

函数长度不建议超过100行，当超过100行时，需要考虑一些步骤是否合理，是否能够进一步抽象成私有函数来缩短函数长度。每行的代码也不应该超过100个字符，这个可以在idea中配置自动换行。

3. 函数参数

在代码设计中，函数的参数不宜过多，一般要求不超过5个，如果超过了，考虑是否把一部分数据封装成一个对象传入，会使得可读性增加

4. 圈复杂度

什么是代码圈复杂度呢，其实就是你代码逻辑所有的分支逻辑的和的一种计算公式，代码圈复杂度不宜过高，如代码中大量的if和swicth语句，这个时候需要考虑是否可以使用一个静态常量的list或者是map加上for循环来降低代码的圈复杂度，一般要求一个函数的代码圈复杂度不超过10(本层，不递归)，超过10一般就会让人难以理解了。

5. 单元测试

我们要求除配置类代码外，其他的代码都要有相应的单元测试代码。好的单元测试可以避免百分之90的bug，我另一个文章里面有分享 juejin.cn/post/696391…

6. pom文件参数版本化

我们组要求是所有的maven依赖包都版本参数化，我个人感觉将一些项目和子项目通用的包比如shiro，mysql，spring，http等包进行参数化就好了。这样带来的好处是统一类的包便于统一的版本管理，不存在用spring-mvc和spring aop等包版本不一致带来一些暗坑的问题。 如:

    <properties>
        <springboot.version>2.1.1.RELEASE</springboot.version>
    </properties>

   <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>${springboot.version}</version>
            <exclusions>
            </exclusions>
        </dependency>
   </dependencies>

7. 常量

对于常量，普通常量参数，一般是使用static的string或者int类型，如果经常变动，建议抽成配置文件。对于不经常变动的，有详细业务语义的常量，可以抽成枚举类，有相应的message会比较合适，会使代码的可读性大大提高。无论是静态常量还是说枚举类都应该有相应的注释。 如:

/**
 * 计算数据状态，应用于xxx展示
 */
public enum DataStatus {

    NO_CONFIG(-1, "未配置"),
    FAIL(0, "计算失败"),
    COMPLETE(1, "计算完成"),
    EXEMPTION(2, "豁免"),
    NO_INVOLVE(3, "不涉及");

    private int status;
    private String des;

    DataStatus(int status, String des) {
        this.status = status;
        this.des = des;
    }
}

8. 异常的处理

对于异常处理，建议是对于通用的异常，定义为Runtime异常，统一由最上层捕获(也可以使用异常处理框架，或者使用AOP进行处理异常)，这样就不用一层层声明异常了(但是最好在java doc中说明会抛出该RE异常，方便调用方做处理)。对于单个接口的特殊异常则需要去声明，每一层都应该有该层的异常日志和处理逻辑(即使是直接上抛也要处理和打日志)，建议打日志时不要马虎，说明出错的接口，请求的参数和异常的堆栈。对于最上层对外接口，需要有兜底的异常处理，防止异常漏出使得服务直接不可用，对内应该定义内部的错误异常类型和错误码，对外也应该定义相应的业务异常码以供调用方处理。

9.日志规范

在我们团队中，debug级别用于打印些细节的辅助信息，info用于打印进入某个组件或者是方法的整体叙述，warn使用于打印不至于整个程序crash的异常信息，error则答应会影响整个服务的基础组件，或者致命错误的信息。像本地和测试环境，可以考虑打印debug或者info的信息，待调整上线后，建议打印warn日志和必要的info日志。日志也不是越多越好，多了如果在接口复杂时可能会影响你对于问题的定位判断，而是越关键，关键的时候详细越好。

avatar
文章
阅读
粉丝