作者：智能平台 刘仲伟

在软件开发的世界里，代码不仅是程序的基石，更是程序员交流的通用语言。而 Java，作为一门广泛应用于企业级应用的编程语言，其代码的可读性和一致性对于项目的长期维护和团队协作至关重要。本文将带你探索 Java 代码的美学，揭示那些能够让你的代码既美观又高效的样式规范。无论是初出茅庐的新手还是经验丰富的老手，都能从中获得灵感，提升编码的艺术。

一、为什么要代码样式规范

对于团队开发，不同的代码规范或不规范可能引起的问题包括但不限于：

1.代码可读性，代码是为了人阅读的，不是只为了机器执行；

2.代码 format 引发的大量的 diff，干扰 code review；

3.间接影响代码质量和团队协作效率；

在敏捷迭代的软件开发环境中，良好的代码规范不仅能够帮助团队成员快速理解彼此的代码，减少沟通成本，还能在代码维护和扩展时节省宝贵的时间。此外，一致的代码风格也是项目专业性的体现，能够给代码审查者和未来的维护者留下良好的第一印象。



二、探索 Java 代码规范

我们将深入探讨 Java 社区广泛认可的编码规范，包括但不限于 Google Java Style 和 Oracle 官方的编码指南。从命名约定、代码格式化、注释的使用，到错误处理和测试代码的编写，每一个细节都是构建高质量 Java 代码的关键。

2.1 业界 Java 代码样式规范

a. Google Java Style

Google 在 github 上维护的多种编程语言的代码规范：https://github.com/google/styleguide，其中：

•javaguide.html 是 Google 对 Java 编程语言代码编码标准的完整定义；

•intellij-java-google-style.xml 是 Google Java 代码规范文件，适用于 Intellij IDEA 开发工具；

b. 阿里 Java 规范

阿里在 GitHub 上有一个关于 Java 开发规范的仓库 p3c：https://github.com/alibaba/p3c，其中：

•Java开发手册(黄山版).pdf 覆盖编程规约、异常日志、单元测试等七个维度；

•Alibaba Java Coding Guidelines Jetbrains 插件市场提供的代码指导插件，idea-plugin 提供编译、安装、使用手册；

c. 其它规范

2.2 规范选择与制定

a. 规范选择

上面列举了多项代码规范，在决定使用哪种规范之前，可以考虑三个方面：

•明确目标：使用代码规范的目的是什么，只是为了项目内代码风格一致，还是为了和其他团队分享或者其他公司分享或者开源？

•使用环境：开发阅读代码的环境是什么，GitHub、GitLab、公司内部的 Coding？

•工具支持：code format 工具支持情况，code sytle check 工具支持情况，编译工具：maven、gradle，IDE：IntelliJ、Eclipse、VS Code；

综合上面的三个方面的考虑，优先选择 Google Java Style。

b. 规范制定

Google Java Style 部分代码样式团队难以接受，比如 2 空格缩进等，可以在原始 Google Java Style 基础上，适当定制化调整。

•修改 intellij-java-google-style.xml 中的内容：

•修改 intellij-java-jd-style.xml 文件下载：http://xingyun.jd.com/codingRoot/liuzhongwei18/styleguide/blob/master/intellij-java-jd-style.xml

2.3 规范使用

代码样式规范的使用分为两个方面：

•代码格式化

•代码样式校验

注意：code style 跟 check style 的「配置文件」必须对应，即按照 code style format 的代码 check style 不报错。

代码样式校验

代码格式化依赖于开发者手动进行格式化，为达到团队/项目代码样式规范的落地，需要有全面的自动化的代码检查。根据当前业界推荐，采用 Checkstyle 作为自动化代码样式校验工具。

需要对原始 Google Code Style 的google_checks进行定制，以适配上面intellij-java-jd-style.xml的定制。

•修改google_checks中的内容：

•修改 checkstyle.xml 文件下载：http://xingyun.jd.com/codingRoot/liuzhongwei18/styleguide/blob/master/checkstyle.xml



除了上述的长度和缩进的代码样式校验，Checkstyle 还可以配置其它代码校验，可根据团队接受情况予以配置。



三、最佳实践：如何将规范融入日常开发

3.1 code style 配置 &使用

a. IDEA 配置 code style

在 IntelliJ IDEA 下，使用intellij-java-jd-style.xml进行代码格式化之前，需要先进行配置。

设置配置文件，路径：IntelliJ IDEA→Preference→Editor→Code Style，参考下图：

导入定制的 code style 文件：intellij-java-jd-style.xml





命名 Scheme，如图中 JD-Style，并启用该代码样式规范





b. IDEA 使用 code style

完成上述配置后，在 Mac 环境的 IntelliJ IDEA 中，可以对选中的代码格式化（快捷键：Option+Command+L）或者对选中的文件格式化（快捷键：Shift+Option+Command+L）





3.2 check style 配置 &使用 check style 的配置和使用有两种主要方式：

1. 在开发环境 IDE 中，开发者配置插件后，可触发代码样式规范的检查，根据提示项进行代码修改；

2.在 maven 项目中，配置 checkstyle 插件，可用命令行触发代码样式规范的检查，集成到 CI (Continuous Integration)的自动化流水线中；

a. IDEA 配置 CheckStyle 插件

在 IntelliJ IDEA 下，安装 Plugin，路径：IntelliJ IDEA→Preference→Plugins，参考下图：





下载配置文件checkstyle.xml，配置 CheckStyle-IDEA 插件，路径：IntelliJ IDEA→Preference→Tools→Checkstyle，增加自定义配置文件并命名，参考下图：





b. IDEA 使用 CheckStyle 插件

安装配置 CheckStyle 插件后，工具窗口增加了 CheckStyle Tab，在 CheckStyle 窗口进行 check，可以选择：

•Check Current File

•Check Module

•Check Project





c. maven 配置 CheckStyle 插件

参考 Checkstyle maven 插件的官方配置案例：多模块项目配置，通常我们在项目中新建 build-tools 模块，将 checkstyle.xml 等配置文件放在这个模块的 resources 目录下。

project-name| -- pom.xml| -- build-tools| | -- pom.xml| | -- src| | | -- main| | | -- resources| | | -- checkstyle.xml| | | -- checkstyle-suppressions.xml| -- core| -- gui| -- other-module

build-tools 模块的 pom.xml 使用 IDEA 自动生成的配置文件，类似：

<?xml version="1.0" encoding="UTF-8"?><project>    <parent>        <artifactId>project-name</artifactId>        <groupId>com.jd.project-name</groupId>        <version>1.0.0</version>    </parent>
    <modelVersion>4.0.0</modelVersion>    <artifactId>build-tools</artifactId></project>

配置文件 checkstyle.xml、checkstyle-suppressions.xml 可以从 coding 中下。

父项目的 pom.xml 中，增加如下配置：

<project>...<modules>...<module>build-tools</module></modules>

<properties>    ...    <maven.checkstyle.version>3.6.0</maven.checkstyle.version></properties>
<build>    <pluginManagement>        <plugins>            <plugin>                <!-- Approach followed here is roughly the same as mentioned here:                     https://maven.apache.org/plugins/maven-checkstyle-plugin/examples/multi-module-config.html                -->                <groupId>org.apache.maven.plugins</groupId>                <artifactId>maven-checkstyle-plugin</artifactId>                <version>${maven.checkstyle.version}</version>                <configuration>                    <configLocation>build-tools/src/main/resources/checkstyle.xml</configLocation>                    <includeTestSourceDirectory>true</includeTestSourceDirectory>                    <outputFile>checkstyle-report.xml</outputFile>                    <consoleOutput>false</consoleOutput>                    <failOnViolation>true</failOnViolation>                    <excludes>target/**</excludes>                </configuration>                <executions>                    <execution>                        <id>checkstyle</id>                        <phase>validate</phase>                        <goals>                            <goal>check</goal>                        </goals>                    </execution>                </executions>            </plugin>        </plugins>    </pluginManagement>    <plugins>        <plugin>            <groupId>org.apache.maven.plugins</groupId>            <artifactId>maven-checkstyle-plugin</artifactId>        </plugin>    </plugins></build><reporting>    <plugins>        <plugin>            <groupId>org.apache.maven.plugins</groupId>            <artifactId>maven-checkstyle-plugin</artifactId>            <reportSets>                <reportSet>                    <reports>                        <report>checkstyle</report>                    </reports>                </reportSet>            </reportSets>        </plugin>    </plugins> </reporting>
</project>

maven-checkstyle-plugin 的配置<configuration>参数具体可参见 checkstyle:check 的参数说明。

这里对几项配置进行说明：

•plugins>plugin>executions>execution

◦id 可以自行决定，这里选择"checkstyle"；

◦phase 是绑定到 maven lifecycle 的哪个执行阶段，这里绑定到"validate"上，即执行 maven validate 的时候会执行该 plugin 任务；选择 validate 阶段可以保障 checkstyle:check 在代码编译之前执行，如果 checkstyle 检查出违反样式规范的问题，在代码编译之前就会报告出来；

◦goals>goal 是只绑定执行 plugin 的哪个任务，这里绑定的是"check"；

•plugins>plugin>configuration>failOnViolation

◦检查到违反样式规范的问题，打印出来，打印的问题级别根据checkstyle.xml中配置的 severity 确定；

◦将 severity 级别配置为 error，并将 failOnViolation 设为 true，检查到违反样式规范的问题时，会停止 maven 命令继续执行；

注意：failOnViolation与failOnError配置项的区别，failOnError 在检查到问题时立即停止执行，failOnViolation 在检查到问题时输出检查日志再停止执行。

按照上述配置，可达到在 mvn 编译代码前强制检查代码样式规范，发现违反规范的问题，不会继续 java 的编译、打包。

d. maven 使用 CheckStyle 插件

运行 mvn package 即可正常打包。

也可以单独执行命令：

mvn checkstyle:check

注意：为了实现自动化代码样式规范检查，可以为项目配置行云流水线任务，设置代码评审的自动化检查：指定流水线做为卡点，指定为卡点的流水线需运行成功后 MR 才允许合并。



四、结语：代码规范-团队协作的桥梁

最后，我们总结下 Java 样式规范对于团队协作的重要性，鼓励每位开发者将这些规范内化为自己的编码习惯。因为代码规范不仅是个人技艺的体现，更是团队协作和项目成功的基石。

通过阅读本文，你将不仅了解到 Java 样式规范的重要性，还将掌握如何将这些规范应用到实际开发中，让你的代码变得更加优雅和强大。让我们一起追求编码的艺术，用规范的代码点亮编程的世界。



参考

•Jetbrains Java code style: https://www.jetbrains.com/help/idea/code-style-java.html

•checkstyle 官网：https://checkstyle.org/index.html

•checkstyle 发布：https://github.com/checkstyle/checkstyle/releases/

•Apache Maven Checkstyle Plugin: https://maven.apache.org/plugins/maven-checkstyle-plugin/usage.html