Android 프로젝트에 ktlint + Spotless 적용하기

 

✨ Android 프로젝트에 Ktlint + Spotless로 자동 코드 포맷팅 날개 달기 🚀

 

안녕하세요! 동료 개발자들과 협업하다 보면 서로 다른 코드 스타일 때문에 골치 아팠던 경험, 다들 한 번쯤 있으시죠? 😅 오늘은 이런 코드 스타일 스트레스를 한 방에 날려버릴 ktlint와 Spotless 조합을 Android 프로젝트에 적용하는 방법을 알아보겠습니다.

이 가이드를 따라오시면, 팀원 모두가 깔끔하고 일관된 코드를 작성하게 되어 코드 리뷰는 즐거워지고, 프로젝트 품질은 쑥쑥 올라갈 거예요!

🎯 우리의 목표

- 일관된 코드 스타일: 누가 작성하든 항상 같은 모양의 코드를 유지해요.

- 완전 자동화: Ctrl+Alt+L은 이제 그만! 빌드할 때마다 알아서 코드가 예뻐져요.

- 협업 효율 UP: "이 부분은 띄어쓰기가..." 같은 사소한 리뷰는 이제 안녕! 핵심 로직에만 집중해요.

🛠️ 1. 준비물 확인하기 (환경 설정)

시작하기 전에, 개발 환경이 준비되었는지 확인해 주세요. 최신 버전일수록 좋습니다!

Android Studio: 최신 버전

Gradle: 8.0 이상

Kotlin: 1.8 이상

YourProject/
├── app/
│ └── build.gradle.kts # 👈 여기에 설정 추가
├── build.gradle.kts # 👈 여기에 설정 추가
├── gradle/
│ └── libs.versions.toml # 👈 여기에 라이브러리 버전 추가
└── .editorconfig # 👈 여기에 코드 스타일 규칙 추가

 

 

⚙️ 2. Gradle 설정하기

이제 본격적으로 Spotless를 우리 프로젝트에 초대해 봅시다. Gradle 설정은 세 단계로 진행됩니다.

1단계: 버전 카탈로그에 Spotless 등록 (gradle/libs.versions.toml)

먼저, 프로젝트에서 사용할 라이브러리 버전을 한곳에서 관리하는 libs.versions.toml 파일에 Spotless와 ktlint를 추가합니다.

 

[versions]
spotless = "6.25.0"
ktlint = "1.0.1" # Spotless가 내부적으로 사용할 ktlint 버전

[plugins]
# 'spotless'라는 별명으로 플러그인을 등록합니다.
spotless = { id = "com.diffplug.spotless", version.ref = "spotless" }

 

2단계: 최상위 build.gradle.kts 파일 수정

프로젝트 전체에서 Spotless 플러그인을 인식할 수 있도록 최상위 build.gradle.kts에 플러그인 별명을 추가해 주세요.

// Top-level build file
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.spotless) apply false // 👈 이 줄을 추가해 주세요!
}

 

3단계: 앱 모듈 build.gradle.kts 파일에 Spotless 설정 추가

가장 중요한 단계입니다! app 모듈의 build.gradle.kts 파일에 Spotless 플러그인을 적용하고, 상세한 포맷팅 규칙을 설정합니다.

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.spotless) // 👈 Spotless 플러그인 적용!
    // ... 기타 플러그인
}

// ... 기존 android { ... } 설정 아래에 추가

 

// ✨ Spotless 설정 시작 ✨

spotless {
    // 1. Kotlin 소스 코드(.kt)에 대한 규칙
    kotlin {
        target("**/*.kt") // 모든 .kt 파일을 대상으로 합니다.
        targetExclude("**/build/**/*.kt") // build 폴더는 제외해요.

        // ktlint를 포맷터로 사용합니다.
        // libs.versions.ktlint.get()으로 toml에 정의한 버전을 가져와요.
        ktlint(libs.versions.ktlint.get()).editorConfigOverride(
            // .editorconfig 규칙을 무시하고 여기서 직접 규칙을 덮어쓸 수 있어요.
            // 아래 규칙들은 주로 Jetpack Compose 환경에서 편의를 위해 비활성화합니다.
            mapOf(
                "ktlint_function-naming" to "disabled", // @Composable 함수는 대문자로 시작해야 하니까요!
                "ktlint_standard_no-wildcard-imports" to "disabled", // 와일드카드 import를 허용해요.
                "ktlint_standard_discouraged-comment-location" to "disabled" // 인자 옆 주석을 허용해요.
                // ... 기타 비활성화 규칙들
            )
        )

        // 기본적인 포맷팅 규칙도 추가해요.
        trimTrailingWhitespace() // 줄 끝의 불필요한 공백 제거
        endWithNewline() // 파일 끝을 개행 문자로 마무리
    }

    // 2. Gradle Kotlin 스크립트(.gradle.kts)에 대한 규칙
    kotlinGradle {
        target("*.gradle.kts") // 루트의 .gradle.kts 파일들을 대상으로 합니다.
        ktlint(libs.versions.ktlint.get())
    }
}

// 💡 빌드 전에 자동으로 Spotless를 실행하게 설정!
tasks.preBuild {
dependsOn(tasks.spotlessApply)
}

 

 

📝 3. .editorconfig로 스타일 규칙 정의하기

Spotless가 포맷팅을 할 때 참고하는 핵심 규칙 파일입니다. 프로젝트 최상위 경로에 .editorconfig 파일을 만들고 아래 내용을 붙여넣으세요. 이 파일 덕분에 Android Studio도 동일한 코드 스타일을 인식하게 됩니다.

💡 잠깐! .editorconfig 파일의 주석은 어떤 규칙이 왜 필요한지 설명해주므로, 팀원들과 규칙을 논의할 때 아주 유용합니다.

# 이 파일이 프로젝트의 코드 스타일 규칙 최종 보스임을 선언!
root = true

# 모든 파일에 적용될 기본 규칙
[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true

# Kotlin과 관련된 파일들
[*.{kt,kts}]
# Jetpack Compose 같은 현대적인 환경을 고려해 한 줄 길이를 120자로 넉넉하게 설정
max_line_length = 120
# 와일드카드 import 허용 (e.g., import androidx.compose.material.*)
# Android에서는 여러 클래스를 한 번에 가져오는 경우가 많아 편리해요.
ktlint_standard_no-wildcard-imports = disabled
# @Composable 함수는 대문자로 시작하므로 함수 작명 규칙은 꺼둡니다.
ktlint_function-naming = disabled

# XML 파일 (레이아웃, 매니페스트 등)
[*.xml]
indent_size = 4

# 기타 파일 형식
[*.{yml,yaml}]
indent_size = 2

 

 

🚀 4. 이제 사용해볼까요?

설정은 끝났습니다! 이제 터미널에서 간단한 명령어로 코드 스타일을 관리할 수 있습니다.

💻 코드 스타일 검사하고 자동으로 수정하기

./gradlew spotlessApply

 

🤔 수정은 하지 않고, 스타일 위반 사항만 확인하기

./gradlew spotlessCheck

 

Android Studio에서도 편하게 실행할 수 있어요!

오른쪽 Gradle 탭을 열어주세요.

app → Tasks → formatting 폴더로 이동하세요.

spotlessApply를 더블클릭하면 포맷팅이, spotlessCheck를 더블클릭하면 검사가 실행됩니다.

 

🤯 5. 흔한 에러 해결하기 (Troubleshooting)

spotlessCheck를 실행했을 때 마주칠 수 있는 대표적인 에러와 해결 방법입니다. 당황하지 마세요!

❓ 에러: Wildcard import

Wildcard import (import a.b.c.*)를 사용하지 말라는 경고가 떠요.

💡 해결: .editorconfig 파일에 아래 규칙이 있는지 확인하세요.

[*.{kt,kts}]
ktlint_standard_no-wildcard-imports = disabled

 

❓ 에러: Function name should start with a lowercase letter

@Composable 함수 이름이 대문자라고 에러가 발생해요.

💡 해결: .editorconfig 파일에 아래 규칙이 있는지 확인하세요.

[*.{kt,kts}]
ktlint_function-naming = disabled​

 

❓ 에러: Exceeded max line length (120)

한 줄이 너무 길다는 에러가 발생해요.

💡 해결: 코드를 여러 줄로 나누는 것이 가장 좋습니다. 하지만 URL처럼 어쩔 수 없는 경우엔 .editorconfig의 max_line_length 값을 늘려주세요.

꿀팁 대방출 (추가 팁)

commit 전에 자동으로 검사하기 (Git Hooks)

매번 spotlessApply를 실행하기 귀찮다면, Git이 commit 하기 직전에 자동으로 실행하도록 설정할 수 있습니다.

프로젝트의 .git/hooks/ 폴더로 이동하세요.

pre-commit이라는 파일을 만들고 아래 내용을 작성하세요. (확장자 없음)

#!/bin/sh
echo "Running spotlessApply before commit..."
./gradlew spotlessApply
git add .​

 

파일에 실행 권한을 부여하세요: chmod +x .git/hooks/pre-commit

이제 git commit을 할 때마다 코드가 자동으로 포맷팅됩니다! ✨

CI/CD 파이프라인에 통합하기 (GitHub Actions)

팀의 코드 품질을 강제하고 싶다면, GitHub Actions를 사용해 Pull Request가 생성될 때마다 코드 스타일을 검사하도록 설정할 수 있습니다.

.github/workflows/code-style-check.yml

 

name: Code Style Check

on: [push, pull_request]

jobs:
spotless:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up JDK 17
uses: actions/setup-java@v3
with:
java-version: '17'
distribution: 'temurin'
- name: Check code style
run: ./gradlew spotlessCheck # PR에서는 Apply 대신 Check를 사용해 통과/실패만 확인

 

 

🎉 마무리하며

축하합니다! 이제 여러분의 Android 프로젝트는 ktlint와 Spotless라는 강력한 코드 스타일 자동화 시스템을 갖추게 되었습니다. 이 시스템이 가져다줄 이점은 명확합니다.

✅ 높은 가독성: 누구나 쉽게 이해할 수 있는 깔끔한 코드!

✅ 개발 효율성 증대: 스타일 걱정 없이 핵심 기능 개발에만 집중!

✅ 즐거운 협업: 코드 스타일에 대한 불필요한 논쟁은 이제 그만!

✅ 자동화된 품질 관리: CI/CD와 연동하여 언제나 최상의 코드 품질 유지!

이 가이드가 여러분의 즐거운 개발 생활에 도움이 되었기를 바랍니다.