Cách mà mình áp dụng Spotless để code clean hơn

1060 words

5 minutes

Cách mà mình áp dụng Spotless để code clean hơn

2025-12-19

Công nghệ

Java

/

Spotless

/

SpringBoot

/

Code Format

Anh em làm việc với hệ sinh thái Nodejs thì sẽ nghe tới Prettier, Eslint là combo Formatter, Linter phổ biến nhất hầu như dự án nào mình cũng thấy xài Formatter là tool giúp anh em xóa khoảng trắng thừa, sắp xếp lại thứ tự import, tab 2 cách hay 4 cách… về format của code Linter là tool đánh giá chất lượng code theo chuẩn nào đó, hoặc tự define, ví dụ function không trả gì thì không ghi gì hay ghi void? Cho phép, cảnh báo, hoặc cấm dùng type any trong Typescript

Vấn đề mình hay gặp khi code chung với team là, mỗi người một kiểu setup IDE, format code, khi xảy ra conflict rất “nhảm” giữa việc một thằng tab 2 dấu cách và tab 4 dấu cách. Ít file còn đỡ, nhiều file conflict, mà toàn bị lỗi format thì ối dồi ôi lắm. Không chỉ code mỗi Intelliji vì nó không có tính năng Ctrl+Save (visual), có người sẽ mở code trong vscode -> Hỏi AI, AI Response -> Ctrl + Save -> Là xong luôn ăn hết format của VScode, tiến thoái lưỡng nan, giờ mình thêm có vài dòng mà Save file lại ăn hết changes của mình? Rồi push đống này lên, teammate pull về lại xào xáo ủa sao code nhìn lạ vậy :) Đó là lí do code lộn xộn, cần phải xử lí.
Có 2 hướng để giải quyết, một là từ đầu họp, setup convention code rõ ràng, Setup IDE chuẩn. Anh em chỉ code theo thôi. Trường hợp 1 mình hiếm thấy quá, vì mình chỉ trong dự án học tập, sinh viên nên mọi người không quan trọng lắm vấn đề này, khi mình đặt vấn đề thì sẽ có ý kiến “mệt thế, rườm rà thế”. Trường hợp 2 thì sẽ không ép, bắt team align từ đầu nhưng dần dần code sẽ đẹp hơn *hehehe, đối với những codebase đã có sẵn rồi, ta cần từ từ dọn dẹp nó. Có thể kiểm tra liên tục nhờ gắn CI flow với format check, lint check nhằm phát hiện sớm hơn các lỗi, nhằm viết code đẹp hơn.

Hôm nay mình ở bên hệ sinh thái Java, có 1 tool siêu ngon là Spotless

Anh em tham khảo ở đây: https://github.com/diffplug/spotless
Cái hay của spotless là nó gộp lại Formatter và Linter, rất dễ sử dụng, config. Khi bên Prettier, Eslint setup tối thiểu cần 5 file,
- .prettierrc.json
- .prettierignore
- eslintrc.json
- .eslintignore
- .editorconfig
Thì bên spotless chỉ cần bỏ thêm plugin vào pom.xml nếu làm dự án bạn làm với Maven hoặc build.gradle.kts nếu làm với Gradle, sau đây mình sẽ chia sẻ đoạn code copy plug-play luôn nhé.

pom.xml#

Trong phần thêm giúp mình spotless-maven-plugin

1
<groupId>com.diffplug.spotless</groupId>
2
<artifactId>spotless-maven-plugin</artifactId>
3
<version>2.46.1</version>

pom.xml đầy đủ

1
<build>
2
    <plugins>
3
        <!--  Spotless for code formatting-->
4
        <plugin>
5
            <artifactId>spotless-maven-plugin</artifactId>
6
            <configuration>
7
                <!-- Java files formatting (if any) -->
8
                <formats>
9
                    <format>
10
                        <endWithNewline/>
11
                        <includes>
12
                            <include>src/**/*.xml</include>
13
                            <include>pom.xml</include>
14
                        </includes>
15
                        <trimTrailingWhitespace/>
16
                    </format>
17

18
                    <!-- Properties files -->
19
                    <format>
20
                        <endWithNewline/>
21
                        <includes>
22
                            <include>src/**/*.properties</include>
23
                        </includes>
24
                        <trimTrailingWhitespace/>
25
                    </format>
26

27
                    <!-- YAML files -->
28
                    <format>
29
                        <endWithNewline/>
30
                        <includes>
31
                            <include>src/**/*.yml</include>
32
                            <include>src/**/*.yaml</include>
33
                        </includes>
34
                        <trimTrailingWhitespace/>
35
                    </format>
36

37
                    <!-- JSON files -->
38
                    <format>
39
                        <includes>
40
                            <include>src/**/*.json</include>
41
                        </includes>
42
                        <prettier>
43
                            <config>
44
                                <tabWidth>4</tabWidth>
45
                                <useTabs>false</useTabs>
46
                            </config>
47
                            <devDependencyProperties>
48
                                <property>
49
                                    <name>prettier</name>
50
                                    <value>3.0.3</value>
51
                                </property>
52
                            </devDependencyProperties>
53
                        </prettier>
54
                    </format>
55
                </formats>
56

57
                <!-- XML files formatting -->
58
                <java>
59
                    <endWithNewline/>
60
                    <excludes>
61
                        <exclude>src/main/java/**/package-info.kt</exclude>
62
                        <exclude>src/test/java/**/package-info.kt</exclude>
63
                    </excludes>
64
                    <!-- Use Google Java format: https://github.com/google/google-java-format -->
65
                    <formatAnnotations/>
66
                    <googleJavaFormat>
67
                        <formatJavadoc>false</formatJavadoc>                      <!-- optional, 1.8 is the minimum supported version for Java 11 -->
68
                        <reflowLongStrings>true</reflowLongStrings>                       <!-- or GOOGLE (optional) -->
69
                        <style>AOSP</style> <!-- optional -->
70
                        <version>1.28.0
71
                        </version>        <!-- optional -->
72
                    </googleJavaFormat>
73
                    <includes>
74
                        <include>src/main/java/**/*.java</include>
75
                        <include>src/test/java/**/*.java</include>
76
                    </includes>
77
                    <licenseHeader>
78
                        <file>${project.basedir}/src/main/resources/license-header.txt</file>
79
                    </licenseHeader>
80
                    <removeUnusedImports/>
81
                    <trimTrailingWhitespace/>
82
                </java>
83
            </configuration>
84
            <executions>
85
                <execution>
86
                    <goals>
87
                        <goal>check</goal>
88
                        <goal>apply</goal>
89
                    </goals>
90
                    <phase>compile</phase>
91
                </execution>
92
            </executions>
93
            <groupId>com.diffplug.spotless</groupId>
94
            <version>2.46.1</version>
95
        </plugin>
96
    </plugins>
97
</build>

Chạy bằng terminal
- mvn spotless (format hết tất cả các file bị sai định dạng, cẩn thận chạy lệnh này vì nó sẽ sửa tất cả những file, trường hợp mình chạy lệnh này nó sẽ ảnh hưởng đến code của các thành viên khác, nếu không align format từ đầu, sẽ gây conflict rất nặng. Best practice nên checkout nhánh khác và merge vào, đồng thời bảo mọi người pull về và resolve conflict sớm nhất có thể nha. Lỗi format sửa conflict rất chán)
- mvn spotless (check file nào bị sai format)
Các option khác mọi người tham khảo thêm ở doc chính thức nhé
- https://github.com/diffplug/spotless/tree/main/plugin-maven#java

build.gradle.kts#

Thêm: id(“com.diffplug.spotless”) version “8.1.0”
subprojects {} liên quan đến config sâu hơn của gradle, khi build tự động chạy format hoàn toàn source code
Chú ý giúp mình scope của spotless {}, tại sao mình có thể viết được như vậy, đọc doc đê
- https://github.com/diffplug/spotless/tree/main/plugin-gradle#java

1
plugins {
2
  java
3
  id("org.springframework.boot") version "3.3.2"
4
  id("io.spring.dependency-management") version "1.1.6"
5
  id("com.diffplug.spotless") version "8.1.0"
6
}
7

8
group = "com.lcaohoanq"
9

10
version = "0.0.1"
11

12
java { toolchain { languageVersion = JavaLanguageVersion.of(17) } }
13

14
configurations { compileOnly { extendsFrom(configurations.annotationProcessor.get()) } }
15

16
repositories { mavenCentral() }
17

18
dependencies {
19
  implementation("org.springframework.boot:spring-boot-starter-actuator")
20
  implementation("org.springframework.boot:spring-boot-starter-data-jpa")
21
  implementation("org.springframework.boot:spring-boot-starter-security")
22
  implementation("org.springframework.boot:spring-boot-starter-thymeleaf")
23
  implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0")
24
  implementation("org.springframework.boot:spring-boot-starter-validation")
25
  implementation("org.springframework.boot:spring-boot-starter-web")
26
  implementation("org.springframework.boot:spring-boot-starter-mail")
27
  implementation("org.springframework.boot:spring-boot-starter-oauth2-resource-server")
28
  implementation("org.thymeleaf.extras:thymeleaf-extras-springsecurity6")
29
  implementation("com.turkraft.springfilter:jpa:3.1.7")
30
  compileOnly("org.projectlombok:lombok")
31
  annotationProcessor("org.projectlombok:lombok")
32
  developmentOnly("org.springframework.boot:spring-boot-devtools")
33
  runtimeOnly("com.mysql:mysql-connector-j")
34
  testImplementation("org.springframework.boot:spring-boot-starter-test")
35
  testImplementation("org.springframework.security:spring-security-test")
36
  testRuntimeOnly("org.junit.platform:junit-platform-launcher")
37
}
38

39
subprojects {
40
  apply(plugin = "com.diffplug.spotless")
41
  configure<com.diffplug.gradle.spotless.SpotlessExtension> {
42
    kotlin {
43
      target("**/*.kt")
44
      targetExclude("${rootProject.layout.buildDirectory}/**/*.kt")
45

46
      ktlint()
47
        .editorConfigOverride(
48
          mapOf(
49
            "ktlint_standard_filename" to "disabled", // cho phép tên file tự do hơn
50
            "ij_kotlin_imports_layout" to "*", // optimize imports
51
            "ij_kotlin_allow_trailing_comma" to "true",
52
            "ktlint_standard_no-wildcard-imports" to "disabled", // cho phép wildcard imports
53
            "ktlint_function_naming_ignore_when_annotated_with" to "Composable",
54
          )
55
        )
56
      licenseHeaderFile(rootProject.file("license-header.kt"))
57
    }
58

59
    kotlinGradle {
60
      target("*.gradle.kts")
61
      ktlint()
62
    }
63
  }
64

65
  // Tự động chạy spotlessApply trước khi build
66
  afterEvaluate { tasks.named("preBuild") { dependsOn("spotlessApply") } }
67
}
68

69
spotless {
70
  kotlinGradle {
71
    target("*.gradle.kts") // chỉ root gradle scripts
72
  }
73
  yaml {
74
    target("*.yml", ".github/**/*.yml", "src/**/*.yml")
75
    jackson()
76
    trimTrailingWhitespace()
77
    lineEndings
78
  }
79

80
  java {
81
    target("src/**/*.java")
82

83
    removeUnusedImports()
84
    forbidWildcardImports()
85
    formatAnnotations()
86

87
    eclipse()
88
    licenseHeaderFile(rootProject.file("license-header.kt"), "package|import|public|class|@")
89
  }
90
}
91

92
tasks.withType<Test> { useJUnitPlatform() }

license-header#

Với pom.xml mình có dùng license-header.txt và build.gradle.kts mình dùng license-header.kt, file gì cũng được nha, text là được, mình ngựa á.
File này dùng để nối thêm bản quyền vào đầu tất cả các file trong source code, có thể custom include exclude được
license-header.txt

1
/**
2
 * Copyright (c) 2025 lcaohoanq. All rights reserved.
3
 * This software is the confidential and proprietary information of lcaohoanq.
4
 * You shall not disclose such confidential information and shall use it only in
5
 * accordance with the terms of the license agreement you entered into with hcmurs.
6
 */

license-header.kt

1
/**
2
 * Copyright (c) 2025 lcaohoanq. All rights reserved.
3
 * This software is the confidential and proprietary information of lcaohoanq.
4
 * You shall not disclose such confidential information and shall use it only in
5
 * accordance with the terms of the license agreement you entered into with hcmurs.
6
 */