Spotless를 활용한 코드 포맷 자동화와 빌드 품질 관리

이 글은 코드 스타일을 자동으로 정리하고, 빌드 과정에서 포맷 오류를 사전에 차단할 수 있는 도구인 Spotless에 대해 정리한 글입니다. Spotless가 무엇인지, 왜 필요한지, 어떤 언어와 빌드 도구를 지원하는지, 그리고 Gradle·Maven 환경에서 어떻게 활용되는지를 예제 중심으로 설명합니다. 코드 품질과 협업 생산성을 동시에 높이고 싶은 개발자라면 끝까지 읽어볼 만한 내용입니다.

반응형

---

Spotless란 무엇인가

Spotless는 소스 코드 포맷을 자동으로 검사하고 수정해주는 코드 포맷터입니다. 단순히 “포맷이 틀렸다”라고 알려주는 데서 끝나지 않고, 빌드 도구와 연동해 직접 코드를 수정(apply) 할 수 있다는 점이 핵심입니다.

지원 범위도 넓습니다.

• 언어: Java, Kotlin, JavaScript, JSON, SQL, Python, Markdown, YAML 등 다수
• 빌드 도구: Gradle, Maven, SBT 등

즉, 하나의 프로젝트에서 여러 언어를 사용하더라도 일관된 코드 스타일을 유지할 수 있도록 도와주는 도구입니다.

---

Spotless가 필요한 이유

팀 개발 환경에서는 코드 스타일이 쉽게 흐트러집니다.

• 들여쓰기 규칙이 사람마다 다르고
• 공백, 줄바꿈, 정렬 방식이 제각각이며
• 리뷰 단계에서 의미 없는 포맷 논쟁이 발생합니다

Spotless는 이런 문제를 빌드 단계에서 해결합니다.

• 포맷 규칙을 코드로 정의
• 규칙을 어기면 빌드 실패
• 명령어 한 번으로 자동 수정

결과적으로 코드 리뷰는 로직에 집중하고, 스타일은 도구에 맡길 수 있는 구조를 만들 수 있습니다.

---

Spotless의 핵심 특징

1. 자동 수정이 가능한 포맷 검사

Spotless는 단순 체크 도구가 아닙니다.
포맷 오류를 발견하면, 동일한 규칙으로 코드를 다시 정리한 결과를 만들어냅니다.

내부적으로는
Function<String, String> 형태의 “문자열 → 포맷된 문자열” 함수 개념으로 동작하며,
이 덕분에 다양한 포맷터와 유연하게 결합할 수 있습니다.

---

2. 다양한 언어와 포맷 지원

Spotless는 특정 언어에 종속되지 않습니다.

• 백엔드: Java, Kotlin, Scala
• 프론트엔드: JavaScript, TypeScript, CSS, HTML, Vue
• 설정 파일: JSON, YAML, SQL, Markdown
• 기타: Shell, Protobuf 등

하나의 포맷 정책을 프로젝트 전반에 적용할 수 있다는 점이 큰 장점입니다.

---

3. 빌드 도구와의 강력한 통합

Spotless는 Gradle, Maven과 자연스럽게 통합됩니다.
빌드 명령어 흐름 안에서 포맷 검사가 수행되기 때문에, CI 환경에서도 바로 활용할 수 있습니다.

---

Gradle 환경에서의 Spotless 사용 예시

포맷 검사 실패 사례

Gradle 빌드 중 다음과 같은 메시지를 볼 수 있습니다.

./gradlew build
:spotlessJavaCheck FAILED
The following files had format violations:
src/main/java/.../FormatExtension.java
-        if (targets.length == 0) {
+    if (targets.length == 0) {
Run './gradlew spotlessApply' to fix these violations.

이 단계에서 빌드는 실패합니다.
즉, 포맷 규칙을 어긴 코드는 빌드를 통과할 수 없습니다.

---

포맷 자동 수정

아래 명령어로 문제를 바로 해결할 수 있습니다.

./gradlew spotlessApply

수정 후 다시 빌드를 실행하면,

./gradlew build
BUILD SUCCESSFUL

코드 포맷이 자동으로 정리되고, 빌드는 정상 통과합니다.

---

Maven 환경에서의 Spotless 사용 예시

Maven에서도 사용 방식은 매우 유사합니다.

포맷 검사

mvn spotless:check

포맷 위반이 있으면 오류가 발생합니다.

---

포맷 적용

mvn spotless:apply

자동으로 코드를 수정한 뒤, 다시 검사하면 정상 통과합니다.

mvn spotless:check
BUILD SUCCESS

Gradle과 Maven 모두 명령어 구조가 직관적이어서 학습 비용이 낮습니다.

---

Spotless의 내부 동작 개념

Spotless는 “포맷터 그 자체”라기보다,
포맷터를 안정적으로 실행하기 위한 프레임워크에 가깝습니다.

• 줄바꿈 처리
• 문자 인코딩 문제
• 반복 실행 시 결과가 변하지 않는지(idempotency)
• Git 기반 점진적 적용(ratcheting)
• 빌드 도구 연동

이처럼 번거로운 부분을 Spotless가 처리해주기 때문에,
개발자는 “어떤 포맷 규칙을 쓸지”에만 집중할 수 있습니다.

---

728x90

Spotless는 코드 스타일을 강제하는 도구가 아니라,
코드 품질을 자동화하는 기반 도구입니다.

이 도구를 도입하면 다음과 같은 효과를 기대할 수 있습니다.

• 코드 스타일 논쟁 감소
• 리뷰 품질 향상
• 빌드 단계에서의 품질 보장
• CI/CD 파이프라인 안정성 강화

특히 여러 언어와 여러 개발자가 함께 작업하는 환경이라면,
Spotless는 “있으면 좋은 도구”가 아니라 사실상 필수 도구에 가깝습니다.

코드를 깔끔하게 유지하는 일은 의지가 아니라 시스템의 문제입니다.
Spotless는 그 시스템을 가장 단순한 방식으로 만들어줍니다.

300x250

https://github.com/diffplug/spotless

GitHub - diffplug/spotless: Keep your code spotless