What is This ?

是一个插件集合 - 能够应用到任何Java项目中提供一致的”Spring” 风格.. 这个集合当前由以下内容组成:

一个资源格式化器 - 提供换行以及空格约定
一个检查样式插件，可在代码库中强制执行一致性

因此这个项目的目标是提供一致性,每一个插件通常是不可配置的,你需要改变你的代码去匹配需要的约定.
你不能够配置插件约定去匹配你的风格 …

Maven

源代码格式化

对于源代码格式,可以增加spring-javaformat-maven-plugin 到build plugins 区域中:

<build>
    <plugins>
        <plugin>
            <groupId>io.spring.javaformat</groupId>
            <artifactId>spring-javaformat-maven-plugin</artifactId>
            <version>0.0.33</version>
        </plugin>
    </plugins>
</build>

并且增加 io.spring.javaformat 插件分组到 ~/.m2/settings.xml中

<pluginGroups>
    <pluginGroup>io.spring.javaformat</pluginGroup>
</pluginGroups>

你现在能够运行 ./mvnw spring-javaformat:apply 格式化代码 ..
如果你想要强制所有的代码匹配需要的风格,增加以下内容

<build>
    <plugins>
        <plugin>
            <groupId>io.spring.javaformat</groupId>
            <artifactId>spring-javaformat-maven-plugin</artifactId>
            <version>0.0.33</version>
            <executions>
                <execution>
                    <phase>validate</phase>
                    <inherited>true</inherited>
                    <goals>
                        <goal>validate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

注意: 源代码格式化器不会完全改变你的代码,举个例子,它不会改变导入语句的顺序 .. 它是非常有效的限制增加或者移除空格以及换行 ..

Checkstyle

为了强制checkstyle 约定必须增加checkstyle plugin 并且包括一个依赖:
“spring-javaformat-checkstyle”

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-checkstyle-plugin</artifactId>
            <version>3.1.1</version>
            <dependencies>
                <dependency>
                    <groupId>com.puppycrawl.tools</groupId>
                    <artifactId>checkstyle</artifactId>
                    <version>9.3</version>
                </dependency>
                <dependency>
                    <groupId>io.spring.javaformat</groupId>
                    <artifactId>spring-javaformat-checkstyle</artifactId>
                    <version>0.0.33</version>
                </dependency>
            </dependencies>
            <executions>
                <execution>
                    <id>checkstyle-validation</id>
                    <phase>validate</phase>
                    <inherited>true</inherited>
                    <configuration>
                        <configLocation>io/spring/javaformat/checkstyle/checkstyle.xml</configLocation>
                        <includeTestSourceDirectory>true</includeTestSourceDirectory>
                    </configuration>
                    <goals>
                        <goal>check</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Gradle

源代码格式化

为了启用源代码格式化,增加“spring-javaformat-gradle-plugin” 到你的构建插件中

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("io.spring.javaformat:spring-javaformat-gradle-plugin:0.0.33")
    }
}
apply plugin: 'io.spring.javaformat'

当然这是一种比较遗留的写法 ..
新的形式查看The Checkstyle Plugin中的使用示例 …
此插件增加了format 以及 checkFormat 任务到项目中,checkFormat任务会自动的应用在(当标准的Gradle check任务执行时运行)
当你想要排除检查的包时,例如如果你生成源代码(例如注解处理器生成代码),你能够通过增加以下配置做到这样:

tasks.withType(io.spring.javaformat.gradle.tasks.CheckFormat) {
    exclude "package/to/exclude"
}

Checkstyle

为了强制使用checkstyle 约定增加checkstyle 插件并增加一个对“spring-javaformat-checkstyle”的依赖

apply plugin: 'checkstyle'

checkstyle {
    toolVersion = "9.3"
}

dependencies {
    checkstyle("io.spring.javaformat:spring-javaformat-checkstyle:0.0.33")
}

你的checkstyle.xml文件应该看起来如下:

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
        "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
        "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="com.puppycrawl.tools.checkstyle.Checker">
    <module name="io.spring.javaformat.checkstyle.SpringChecks" />
</module>

Java 8 Support

默认,这个formatter 需要Java 11. 如果你工作在旧的项目中,你应该可以使用此formatter的一个变种 ,它基于 Eclipse 2021-03(最新版Eclipse JDT 版本使用Java 8 构建)
为了使用Java 8 版本,你需要增加一个叫做 .springjavaformatconfig的文件到项目的根下并配置以下内容

java-baseline=8

Eclipse

Eclipse 插件提供了自定义formatter 实现和自动应用项目特定的配置 … 这个插件自动激活(无论Maven / Gradle 插件是否在项目构建脚本中发现)
如果你需要定制项目特定的配置并让插件应用你的配置你应该增加一个 .eclipse 文件夹到项目的根下,所有来自此目录的.prefs 文件将会复制到项目的.settings文件夹中 ..
通常你将会提供你自己的org.eclipse.jdt.core.prefs 以及 org.eclipse.jdt.ui.prefs 文件 …
你也能够增加.eclipse/eclipse.properties 去定制以下项目

为了安装此插件使用 io.spring.javaformat.eclipse.site 压缩文件 … 你能够从Maven Central 或者使用这里的更新站点进行下载.

IntelliJ IDEA

IDEA插件工具提供了对IDEA的自定义格式化器支持. 这个插件自动的激活,无论Maven / Gradle 插件在项目构建脚本中是否发现 …
一个Spring Java Format icon ()将会展示在状态栏中去支持formatter 激活了,你能够通过标准的code -> reformat code动作执行代码格式化..
为了安装这个插件你需要使用 spring-javaformat-intellij-idea-plugin jar文件 ..
你能够从Maven 中央仓库中下载 ..

启用插件

此插件自动启动,如果以下的一个或者多个条件满足

.springjavaformatconfig 文件存在
一个基于Maven的项目 ,spring-javaformat-maven-plugin定义在pom.xml中

基于Gradle的项目,io.spring.javaforamt 插件被应用

CheckStyle-IDEA plugin

这个插件提供了对IDEA的Checkstyle 集成
为了配置此插件,创建你自己的Checkstyle 配置文件并提供以下配置

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
      "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
      "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="com.puppycrawl.tools.checkstyle.Checker">
  <module name="io.spring.javaformat.checkstyle.SpringChecks" />
</module>

一旦配置文件创建,配置你的IDE去使用它 ..

打开首选项 -> Tools -> Checkstyle
增加 spring-javaformat-checkstyle-0.0.33.jar 以及 spring-javaformat-config-0.0.33.jar 到 Third-Party Checks
指定合适的Checkstyle version
增加Checkstyle 配置文件(上面已经提到)
About the Conventions
大多数代码约定以及风格来自Spring 框架以及SpringBoot项目 ..
Spring 框架手动格式化代码,然而Spring Boot 使用自动格式化 ..
Indenting With Spaces
默认tab 被用来缩进格式化的代码 … 我们强烈推荐使用默认并不需要做出改变,特别是官方的Spring 项目,但是如果你觉得不习惯tab 想要切换为spaces ,那么只需要一个配置选项且支持 ..
为了使用space 而不是tab,增加一个叫做.springjavaformatconfig的配置文件到项目根下并配置以下内容
```
indentation-style=spaces
```
Tips
格式化以及Checkstyle 两者都不足以生成非常一致的代码 ..
当开发Spring Boot项目的时候这里的一些提示非常有用..
Excluding Specific Checks
如果你想要大多数的SpringChecks 但是你需要排除一个或者多个,你能够在checkstyle.xml中配置如下事情 …
```
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
      "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
      "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="com.puppycrawl.tools.checkstyle.Checker">
  <module name="io.spring.javaformat.checkstyle.SpringChecks">
      <property name="excludes" value="io.spring.javaformat.checkstyle.check.SpringAvoidStaticImportCheck" />
  </module>
</module>
```
禁用格式化
通过对代码块进行格式化禁止
有些代码不是特别适合(amenable)自动格式化,举个例子Spring Security 配置通过手动格式化经常工作的更好 ..
如果你需要禁用格式化通过指定这样的一个代码块可以强制关闭 … ```groovy // @formatter:off

… code not be formatted

// @formatter:on

以off -> on的一个约束块禁止格式化
<a name="Datc5"></a>
## Wrapping
源代码格式化器使用120字符进行换行.. 这个旨在利用IDE中可用的横向空间和例如在Github上查看代码避免不必要的额外包装打造一个平衡 ...<br />如果你使用更长的行 ,120 字符能做一些事情 ... 特别的是,如果你有许多内嵌级别的事情可以开始看起来很糟糕。<br />通常，如果您看到代码聚集在屏幕右侧，您应该将其视为使用“提取方法”重构的信号。<br />提取少量的私有方法将提高格式化 并且它在阅读代码以及调试的时候获得帮助 ...

<a name="xjwxA"></a>
## Whitespace
保持空白行在方法体的外部是一个好的方式  - 能够让代码更容易扫描 ...<br />如果空格行仅仅包括在方法之间 它能够变得跟容易看清楚类的整体结构 ..<br />如果你发现在你的方法中也需要空格 ...<br />考虑抽取为一个私有方法是一个更好的方式 ..
<a name="v7jOd"></a>
## Comments
尝试增加javadoc 给每一个public 方法和常量 .. 私有方法通常不需要javadoc ... 除非它提供了一个自然的地方来记录异常行为。<br />checkstyle 规则将会强制所有的公共类必须有javadoc .. 它们也强制@author tag 同样存在 ..
<a name="gDcxt"></a>
## Final
私有成员应该有一个final(尽可能存在),局部变量和参数 应该通常不需要声明为final,因为这样倒还增加了一些繁琐 ..

<a name="v6oZG"></a>
## Read-down Methods,Fields 以及 Parameters
方法不需要通过作用域(空间)组织 .. 这里不需要分类所有的private / protected / public 方法 ,相反尝试让你的代码更加容易阅读 - 当从上向下扫描文件时,换句话说,尝试让方法只在文件中进一步引用方法。让私有方法尽可能靠近调用它们的对象。<br />它同样推荐你字段和构建器参数的顺序一致,例如:
```java
class Name {

    private final String first;

    private final String last;

    public Name(String first, String last) {
        this.first = first;
        this.last = last;
    }

}

官方项目地址

https://github.com/spring-io/spring-javaformat

spring-javaformat

What is This ?

Maven

源代码格式化

Checkstyle

Gradle

源代码格式化

Checkstyle

Java 8 Support

Eclipse

IntelliJ IDEA

启用插件

CheckStyle-IDEA plugin

About the Conventions

Indenting With Spaces

Tips

Excluding Specific Checks

禁用格式化

官方项目地址