拯救Java Code Style强迫症
MFYBernd
7年前
<p style="text-align:center"><img alt="拯救Java Code Style强迫症" src="https://simg.open-open.com/show/b1b0d37f9d1a11f22aacdf9d1d33ad54.jpg" width="700" height="391"></p> <blockquote> <p>文/周宇刚</p> <p>拥有 10 年的 JAVA EE 开发经验，在 ThoughtWorks 担任高级咨询师。在加入 ThoughtWorks 之前，在一家国内领先的航旅企业担任架构师，专注于持续交付实践和大型企业应用架构治理。</p> </blockquote> <p> 这篇文章缘起于上一个持续交付的咨询项目，当时正在指导客户团队的 Java 工程师做 Code Review，发现一个很有意思的现象：有一位工程师对 Code Style 特别在意，所以在 Code Review 的大部分时间中都是该工程师在指出哪里哪里的格式不对，但是团队并没有找到改进方法，每次的结论都是“下次我注意一点。”我挺欣赏这位工程师对 Code Style 的认真态度，所以就萌生了“怎么拯救 Code Style 强迫症”的想法。</p> <p> <strong>要点</strong></p> <ul> <li>Code Style 不是个人喜好问题，它会影响工作效率，团队应将其当做工程实践予以重视。</li> <li>Code Style 需要端到端的工具支持，尽早解决问题，避免技术债。</li> <li>以 Checkstyle 作为核心工具支撑 Java 项目的 Code Style 实施方案。</li> </ul> <p> <strong>Code Style 是一项工程实践</strong></p> <p style="text-align:center"><img alt="拯救Java Code Style强迫症" src="https://simg.open-open.com/show/e71d4527bd04e7bfdf903c3ccf1e3c54.jpg" width="479" height="310"></p> <p> 我是右侧风格的忠实拥趸，如果让我在工作的项目中看到左侧风格的代码，你猜猜我的反应是什么。</p> <p style="text-align:center"><img alt="拯救Java Code Style强迫症" src="https://simg.open-open.com/show/015be5caff10736831a8ec32e4e82d35.jpg" width="400" height="400"></p> <p> 嗯，可能我对代码风格确实有些强迫症，但事实上，Code Style 并不仅仅是代码是否好看那么简单，如果没有按照惯例来编写代码，甚至会让阅读者产生疑惑。</p> <pre> <code class="language-java"><span style="color:#0000ff">private</span> Listener listener = <span style="color:#0000ff">new</span> Listener () <span style="color:#008000">//</span><span style="color:#008000"> So Listener looks like a class? {}; </span><span style="color:#008000">//</span><span style="color:#008000"> Oops, it is an interface</span></code></pre> <p><code> 如果代码可读性还不足以打动你，那么想象一下这个场景，你的同事说他修复了两个空指针问题，请你帮忙 Code Review，你查看了这个文件的修订历史，乍看之下有许多改动，看来是个大动作。然而事实上，绝大部分改动是代码格式调整，只有两处改动与需要 Review 的问题相关。</code></p> <p style="text-align:center"><img alt="拯救Java Code Style强迫症" src="https://simg.open-open.com/show/09999254d8fbadf46dbe2208137a3ce1.jpg" width="1024" height="365"></p> <p style="text-align:center"> (看来这位同事的 IDE 使用了不同的自动缩进设置，导致所有行都产生了缩进)</p> <p> 之所以会产生以上这些影响工作效率的问题，是因为团队没有重视 Code Style，没有把它当做一项工程实践，既没有对其达成一致，也没有正确地使用工具帮助实施。</p> <p> <strong>那就按照工程实践的标准来实施 Code Style</strong></p> <p> 本文将重点介绍 Java 项目中 Code Style 的工具支持，但在此之前，你的团队需要一起做一些决定：</p> <ol> <li><strong>使用哪种 Code Style？</strong> <p> 每个人可能都有偏好的 style，但在团队协作面前，需要一定的妥协。有些公司或组织有着统一的 Code Style 指导标准，萧规曹随是个不错的选择（但是要确保这类统一指导标准在制定时参考了开发人员的意见，是切实可行的），你的团队也可以自己裁剪，但至少要保证项目（Repository）级别上使用同一种 Style。</p> </li> <li><strong>如何处理不符合 Code Style 的提交？</strong> <p> 大家往往懈怠于事后补救的方式，我的建议是不要让不符合约定的代码流入代码库。对于遗留项目，尤其是大型项目，可以选择一部分代码作为实施范围，集中修复 Style 问题后严格实施，切忌操之过急，最后团队疲惫不堪只得放弃。</p> </li> </ol> <p> 我们都知道人工监督检查的方式是不可持续和不可靠的，来看看有哪些工具可以提供帮助吧。</p> <p> <strong>懒惰是第一生产力</strong></p> <p> 工程实践不能没有自动化工具支持，在 Java 生态圈中，Code Style 工具最出名的应该是 Checkstyle 了，它可以通过 XML 形式的<a href="/misc/goto?guid=4959749957334879709">外部 DSL</a> 来定义 Code Style 的检查风格，比如你可以从这里找到 <a href="/misc/goto?guid=4959749957425308021">Google 的 Java Checkstyle 配置文件</a>。这里我不会详细介绍 Checkstyle 本身，相反，我会更多地探讨如何工程化地使用 Checkstyle，在交付代码的各个活动中，我们都可以用到 Checkstyle，进行 360°无死角的检查。</p> <p style="text-align:center"><img alt="拯救Java Code Style强迫症" src="https://simg.open-open.com/show/bc697a7afed1a1ba98bdb9acdfa8efc1.jpg" width="1024" height="558"></p> <p> （和 Code Style 相关的代码交付生命周期）</p> <p> <strong>守住提交的质量关口</strong></p> <p> 为了贯彻不让不符合约定的代码流入代码库的决定，可以优先在服务端设置 Code Style 的检查关卡。</p> <p style="text-align:center"><img alt="拯救Java Code Style强迫症" src="https://simg.open-open.com/show/468dc2d6d185ffa94b5884736a8df408.jpg" width="1024" height="584"></p> <p style="text-align:center"> （优先守住代码提交时的服务端检查，可以考虑使用 CI 服务器来实现）</p> <p> <strong>从实现层面上说，有两种方式：</strong></p> <p> 一是在 SCM（Source Control Management，例如 Git/SVN）服务端设置检查项，如果不达标则拒绝提交，但这种方式相对不容易实现，而且一般 SCM 服务端也不由开发团队管理，设置起来不灵活也不方便。</p> <p> 二是利用<a href="/misc/goto?guid=4959749957515720571">持续集成</a>服务器，开发团队的每一次提交都会触发一次构建，我们可以在构建脚本中加入 Checkstyle 检查，如果有不达标的代码则让构建失败，以便告诉提交者立即修复 Style 问题。我更推荐这个方案，因为相关的工具支持都很成熟，实现简单，而且构建过程可以在开发者的本地环境复制，以便在后续改进中将 Checkstyle 检查前移，提供更快的反馈。如果团队使用 Maven/Gradle 等构建工具，可以用插件的方式实现 Checkstyle 检查并嵌入到整个构建过程中。这样 CI 服务器只要调用构建脚本就行了。</p> <p> <strong>在开发者本地验证 Style</strong></p> <p style="text-align:center"><img alt="拯救Java Code Style强迫症" src="https://simg.open-open.com/show/469227c89c3d3c882ddea1c831390df9.jpg" width="1024" height="559"></p> <p style="text-align:center"> （在开发者本地实现验证，反馈关口前移）</p> <p> 在实现了 CI 验证后，就可以着手实现开发者本地验证了，这样开发者就不用等到提交代码到服务端后才会获得反馈了。由于之前采用的是构建工具的插件方案，所以开发者在本地运行构建就能实现验证了。比如 Gradle 提供了 Checkstyle 插件支持，你可以在这里找到 Gradle Checkstyle Plugin 的详细配置文档，如果你使用 Maven，则可以参考这里。现在只需要一条命令，开发者久能在本地验证 Code style 了。</p> <pre> <code class="language-java"><span style="color:#000000"># build.gradle # omitted plugins apply plugin: </span>'checkstyle'<span style="color:#000000"> checkstyle { configFile </span>= file ("config/checkstyle.xml") <span style="color:#008000">//</span><span style="color:#008000">指定 checkstyle 配置文件 </span> toolVersion = "7.4" <span style="color:#008000">//</span><span style="color:#008000">指定 checkstyle 工具的版本，部分 style 规则有版本要求 </span> <span style="color:#000000">} checkstyleTest.exclude </span>"**/ContractVerifierTest**" <span style="color:#008000">//</span><span style="color:#008000"> 忽略检查生成代码，这个锅我们不背 </span><span style="color:#008000">//</span><span style="color:#008000"> 如果出现 checkstyle warning 也使构建失败，插件默认只支持 checkstyle error 失败 </span><span style="color:#008000">//</span><span style="color:#008000"> Fail build on Checkstyle Warning Violation · Issue #881 </span> tasks.withType (Checkstyle) .each { checkstyleTask -><span style="color:#000000"> checkstyleTask.doLast { reports.all { report </span>-><span style="color:#000000"> def outputFile </span>=<span style="color:#000000"> report.destination </span><span style="color:#0000ff">if</span> (outputFile.exists () && outputFile.text.contains ("<error "<span style="color:#000000">)) { </span><span style="color:#0000ff">throw</span> <span style="color:#0000ff">new</span> GradleException ("There were checkstyle warnings! For more info check $outputFile"<span style="color:#000000">) } } } }</span></code></pre> <p> 现在只需要一条命令，每个开发者就能在本地验证 Code Style 了。你可以在<a href="/misc/goto?guid=4959749957598219551">这里</a>找到 Gradle Checkstyle Plugin 的详细配置文档，如果你使用 Maven，则可以参考<a href="/misc/goto?guid=4959749957676310234">这里</a>。</p> <pre> <code class="language-java">➜ court-booking-backend (master) ✗ ./<span style="color:#000000">gradlew check Starting a Gradle Daemon (subsequent builds will be faster) :compileJava :processResources UP</span>-TO-<span style="color:#000000">DATE :classes :checkstyleMain [ant:checkstyle] [WARN] </span>/Users/twer/Workspace/restbucks/court-booking-backend/src/main/java/com/restbucks/courtbooking/http/CourtRestController.java:16<span style="color:#000000">: </span>'method def' child have incorrect indentation level 4, expected level should be 8<span style="color:#000000">. [Indentation] :checkstyleMain FAILED FAILURE: Build failed with an exception.</span></code></pre> <p> <strong>本地验证很不错，但我有时候会忘记执行</strong></p> <p><img alt="拯救Java Code Style强迫症" src="https://simg.open-open.com/show/233b95c6cbcec63275ef5893c3c609be.jpg" width="1024" height="559"></p> <p style="text-align:center">（让机器代劳琐事）</p> <p> 有时候，开发者修改了代码后会忘记执行本地检查就提交代码了，最好能够在提交代码前自动执行检查。如果你使用 Git 的话，可能会想到 Git commit hook，比如这是我常用的 pre-commit hook</p> <pre> <code class="language-java">#!/bin/<span style="color:#000000">sh # From gist at https:</span><span style="color:#008000">//</span><span style="color:#008000">gist.github.com/chadmaughan/5889802</span> <span style="color:#000000"> # stash any unstaged changes git stash </span>-q --keep-<span style="color:#000000">index # run the tests with the gradle wrapper .</span>/<span style="color:#000000">gradlew clean build # store the last exit code in a variable RESULT</span>=$?<span style="color:#000000"> # unstash the unstashed changes git stash pop </span>-<span style="color:#000000">q # </span><span style="color:#0000ff">return</span> the './gradlew build'<span style="color:#000000"> exit code exit $RESULT</span></code></pre> <p> 将该脚本拷贝到<code>.git/hooks/</code>下，在执行<code>git commit</code>的时候就会自动触发检查了，如果检查失败则提交失败。但问题是<code>.git</code>并不能提交到远程代码仓库，那么除了人工分发和拷贝外，有没有更好的方式在团队中共享这个机制呢？</p> <p> 可以曲线救国！把 pre-commit 纳入版本控制(如下面的<code>config/pre-commit</code>)，再使用构建工具的扩展机制来自动完成拷贝工作，这样可以间接实现 git hooks 的团队间共享。</p> <pre> <code class="language-java"><span style="color:#000000"># build.gradle task installGitHooks (type: Copy) { </span><span style="color:#008000">//</span><span style="color:#008000">将 pre-commit 拷贝到指定位置</span> from <span style="color:#0000ff">new</span> File (rootProject.rootDir, 'config/pre-commit'<span style="color:#000000">) into { </span><span style="color:#0000ff">new</span> File (rootProject.rootDir, '.git/hooks'<span style="color:#000000">) } fileMode </span>0755<span style="color:#000000"> } build.dependsOn installGitHooks </span><span style="color:#008000">//</span><span style="color:#008000">设置执行 build 任务时会自动触发 installGitHooks 任务</span></code></pre> <p> <strong>关闭包围圈，编辑时反馈</strong></p> <p><img alt="拯救Java Code Style强迫症" src="https://simg.open-open.com/show/e1f867d3ef4ecdd6b3237b0275f9aac0.jpg" width="1024" height="558"></p> <p style="text-align:center">(实时反馈)</p> <p> 之前基于构建工具的方案都很好，但是对于开发者来说，最好能将反馈前移到编辑时，并且可视化。所幸的是，Checkstyle 的生态系统非常成熟，各主流 IDE 都有插件支持，以 Intellij Idea 为例，可以使用 <a href="/misc/goto?guid=4959749957763002290">checkstyle-idea</a> 插件，让团队成员手工设置插件，使用项目的 checkstyle 配置文件即可(我目前还没有找到自动化配置的方式，或许 gradle idea 插件可以？)</p> <p><img alt="拯救Java Code Style强迫症" src="https://simg.open-open.com/show/f6afd46d9ba39ea84f2828aa5476b272.jpg" width="1024" height="258"></p> <p><img alt="拯救Java Code Style强迫症" src="https://simg.open-open.com/show/85a2545d72d1f9b4cd55eedd38b7b36a.jpg" width="1024" height="142"></p> <p style="text-align:center">(checkstyle-idea 插件配置和效果)</p> <p> 有了自动实时检查，最好还能将 IDE 的自动格式化与 Checkstyle 配置文件挂钩，否则自动格式化反倒给你添麻烦了。</p> <p><img alt="拯救Java Code Style强迫症" src="https://simg.open-open.com/show/cab3d3bcd60139c64d208cb03310c550.jpg" width="1024" height="485"></p> <p style="text-align:center">(为 IDE 导入 checkstyle 配置文件作为自动格式化的依据)</p> <p> 如果你连自动格式化都懒得按，那可以试试 <a href="/misc/goto?guid=4959749957837888870">Save Actions</a> 插件，它可以在 Intellij 保存文件时自动执行代码格式化等动作。</p> <p><img alt="拯救Java Code Style强迫症" src="https://simg.open-open.com/show/d951fe587df7cf41a99a058c4daf1b4b.jpg" width="1024" height="583"></p> <p style="text-align:center">(这个插件目前对部分文件有些问题，可以通过 File path exclusion 忽略)</p> <p> <strong>总结</strong></p> <ol> <li>Code Style 影响工作效率，团队应将其当做工程实践予以重视。</li> <li>Code Style 不能靠人工监督和检查，应该提供端到端的工具支持</li> <li>服务端检查（推荐集成到 CI 的构建步骤中）</li> <li>开发环境检查（使用各构建工具的 Checkstyle 插件）</li> <li>自动提交检查（git pre-commit hook 与共享）</li> <li>IDE 增强（checkstyle 插件实时可视化反馈/自动的自动格式化！）</li> <li>以上的工具都要依据为同一份 Checkstyle 配置文件，并纳入版本控制</li> </ol> <p> 希望以上这些招数可以解救 Java Code Style 强迫症 ：）</p> <p> </p> <p>来自: <a href="/misc/goto?guid=4959749957919221373" id="link_source2">insights.thoughtworkers.org</a></p> <p> </p> <p> </p>