作者：京東零售 劉仲偉

在軟件開發(fā)的世界里，代碼不僅是程序的基石，更是程序員交流的通用語言。而Java，作為一門廣泛應用于企業(yè)級應用的編程語言，其代碼的可讀性和一致性對于項目的長期維護和團隊協(xié)作至關重要。本文將帶你探索Java代碼的美學，揭示那些能夠讓你的代碼既美觀又高效的樣式規(guī)范。無論是初出茅廬的新手還是經驗豐富的老手，都能從中獲得靈感，提升編碼的藝術。

一、為什么要代碼樣式規(guī)范

對于團隊開發(fā)，不同的代碼規(guī)范或不規(guī)范可能引起的問題包括但不限于：

1.代碼可讀性，代碼是為了人閱讀的，不是只為了機器執(zhí)行；

2.代碼format引發(fā)的大量的diff，干擾code review；

3.間接影響代碼質量和團隊協(xié)作效率；

在敏捷迭代的軟件開發(fā)環(huán)境中，良好的代碼規(guī)范不僅能夠幫助團隊成員快速理解彼此的代碼，減少溝通成本，還能在代碼維護和擴展時節(jié)省寶貴的時間。此外，一致的代碼風格也是項目專業(yè)性的體現(xiàn)，能夠給代碼審查者和未來的維護者留下良好的第一印象。

?

二、探索Java代碼規(guī)范

我們將深入探討Java社區(qū)廣泛認可的編碼規(guī)范，包括但不限于Google Java Style和Oracle官方的編碼指南。從命名約定、代碼格式化、注釋的使用，到錯誤處理和測試代碼的編寫，每一個細節(jié)都是構建高質量Java代碼的關鍵。

2.1 業(yè)界Java代碼樣式規(guī)范

a. Google Java Style

Google在github上維護的多種編程語言的代碼規(guī)范：https://github.com/google/styleguide，其中：

??javaguide.html 是Google對Java編程語言代碼編碼標準的完整定義；

??intellij-java-google-style.xml 是Google Java代碼規(guī)范文件，適用于Intellij IDEA開發(fā)工具；

b. 阿里Java規(guī)范

阿里在 GitHub 上有一個關于 Java 開發(fā)規(guī)范的倉庫 p3c：https://github.com/alibaba/p3c，其中：

??Java開發(fā)手冊(黃山版).pdf 覆蓋編程規(guī)約、異常日志、單元測試等七個維度；

??Alibaba Java Coding Guidelines Jetbrains插件市場提供的代碼指導插件， idea-plugin 提供編譯、安裝、使用手冊；

c. 其它規(guī)范

2.2 規(guī)范選擇與制定

a. 規(guī)范選擇

上面列舉了多項代碼規(guī)范，在決定使用哪種規(guī)范之前，可以考慮三個方面：

?明確目標：使用代碼規(guī)范的目的是什么，只是為了項目內代碼風格一致，還是為了和其他團隊分享或者其他公司分享或者開源？

?使用環(huán)境：開發(fā)閱讀代碼的環(huán)境是什么，GitHub、GitLab、公司內部的Coding？

?工具支持：code format工具支持情況，code sytle check工具支持情況，編譯工具：maven、gradle，IDE：IntelliJ、Eclipse、VS Code；

綜合上面的三個方面的考慮，優(yōu)先選擇Google Java Style。

b. 規(guī)范制定

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 規(guī)范使用

代碼樣式規(guī)范的使用分為兩個方面：

?代碼格式化

?代碼樣式校驗

注意：code style 跟 check style 的「配置文件」必須對應，即按照code style format的代碼check style不報錯。

代碼樣式校驗

代碼格式化依賴于開發(fā)者手動進行格式化，為達到團隊/項目代碼樣式規(guī)范的落地，需要有全面的自動化的代碼檢查。根據當前業(yè)界推薦，采用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還可以配置其它代碼校驗，可根據團隊接受情況予以配置。

?

三、最佳實踐：如何將規(guī)范融入日常開發(fā)

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，并啟用該代碼樣式規(guī)范

b. IDEA使用code style

完成上述配置后，在Mac環(huán)境的IntelliJ IDEA中，可以對選中的代碼格式化（快捷鍵：Option+Command+L）或者對選中的文件格式化（快捷鍵：Shift+Option+Command+L）

?

3.2 check style配置&使用

check style的配置和使用有兩種主要方式：

1. 在開發(fā)環(huán)境IDE中，開發(fā)者配置插件后，可觸發(fā)代碼樣式規(guī)范的檢查，根據提示項進行代碼修改；

2.在maven項目中，配置checkstyle插件，可用命令行觸發(fā)代碼樣式規(guī)范的檢查，集成到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自動生成的配置文件，類似：

    
        project-name
        com.jd.project-name
        1.0.0
    

    4.0.0
    build-tools

配置文件checkstyle.xml、checkstyle-suppressions.xml可以從coding中下載http://xingyun.jd.com/codingRoot/liuzhongwei18/styleguide/blob/master/。

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

    ...
    
        ...
        build-tools
    

    
        ...
        3.6.0
    

    
        
            
                
                    
                    org.apache.maven.plugins
                    maven-checkstyle-plugin
                    ${maven.checkstyle.version}
                    
                        build-tools/src/main/resources/checkstyle.xml
                        true
                        checkstyle-report.xml
                        false
                        true
                        target/**
                    
                    
                        
                            checkstyle
                            validate
                            
                                check
                            
                        
                    
                
            
        
        
            
                org.apache.maven.plugins
                maven-checkstyle-plugin
            
        
    
    
        
            
                org.apache.maven.plugins
                maven-checkstyle-plugin
                
                    
                        
                            checkstyle
                        
                    
                
            
        
    

maven-checkstyle-plugin的配置參數(shù)具體可參見checkstyle:check的參數(shù)說明。

這里對幾項配置進行說明：

?plugins>plugin>executions>execution

?id可以自行決定，這里選擇"checkstyle"；

?phase是綁定到maven lifecycle的哪個執(zhí)行階段，這里綁定到"validate"上，即執(zhí)行maven validate的時候會執(zhí)行該plugin任務；選擇validate階段可以保障checkstyle:check在代碼編譯之前執(zhí)行，如果checkstyle檢查出違反樣式規(guī)范的問題，在代碼編譯之前就會報告出來；

?goals>goal是只綁定執(zhí)行plugin的哪個任務，這里綁定的是"check"；

?plugins>plugin>configuration>failOnViolation

?檢查到違反樣式規(guī)范的問題，打印出來，打印的問題級別根據checkstyle.xml中配置的severity確定；

?將severity級別配置為error，并將failOnViolation設為true，檢查到違反樣式規(guī)范的問題時，會停止maven命令繼續(xù)執(zhí)行；

注意：failOnViolation與failOnError配置項的區(qū)別，failOnError在檢查到問題時立即停止執(zhí)行，failOnViolation在檢查到問題時輸出檢查日志再停止執(zhí)行。

按照上述配置，可達到在mvn編譯代碼前強制檢查代碼樣式規(guī)范，發(fā)現(xiàn)違反規(guī)范的問題，不會繼續(xù)java的編譯、打包。

d. maven使用CheckStyle插件

運行mvn package即可正常打包。

也可以單獨執(zhí)行命令：

mvn checkstyle:check

注意：為了實現(xiàn)自動化代碼樣式規(guī)范檢查，可以為項目配置行云流水線任務，設置代碼評審的自動化檢查：指定流水線做為卡點，指定為卡點的流水線需運行成功后MR才允許合并。

?

四、結語：代碼規(guī)范-團隊協(xié)作的橋梁

最后，我們總結下Java樣式規(guī)范對于團隊協(xié)作的重要性，鼓勵每位開發(fā)者將這些規(guī)范內化為自己的編碼習慣。因為代碼規(guī)范不僅是個人技藝的體現(xiàn)，更是團隊協(xié)作和項目成功的基石。

通過閱讀本文，你將不僅了解到Java樣式規(guī)范的重要性，還將掌握如何將這些規(guī)范應用到實際開發(fā)中，讓你的代碼變得更加優(yōu)雅和強大。讓我們一起追求編碼的藝術，用規(guī)范的代碼點亮編程的世界。

?

參考

??京東JAVA代碼規(guī)范-V1.0.pdf?

?JD編碼規(guī)范：https://doc.jd.com/base/eos-doc/system-rule/JD%E7%BC%96%E7%A0%81%E8%A7%84%E8%8C%83/Java/?

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

?checkstyle官網：https://checkstyle.org/index.html?

?checkstyle發(fā)布：https://github.com/checkstyle/checkstyle/releases/?

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

審核編輯 黃宇