Kotlin 코드 스타일 가이드 ktlint 적용하기

코드의 품질을 높이고 일관된 스타일을 유지하는 것은 프로젝트의 유지보수성과 가독성을 위해 매우 중요합니다.

Kotlin 프로젝트에서는 ktlint를 통해 이러한 코드 스타일을 자동으로 검사하고 수정할 수 있습니다.

이 글에서는 ktlint가 무엇인지 알아보고, Spring Boot 프로젝트에 적용하는 방법에 대해 자세히 살펴보겠습니다.

ktlint란?

ktlint는 Kotlin 언어를 위한 정적 코드 분석 도구입니다. 안드로이드 팀에서 제공하는 공식 Kotlin 코딩 컨벤션을 기반으로 하며, 추가적인 규칙들도 포함하고 있습니다. 주요 특징은 다음과 같습니다:

설정이 거의 필요없는 간단한 사용법
자동 포맷팅 기능 제공
.editorconfig 파일을 통한 규칙 커스터마이징
IDE 플러그인 지원

ktlint features

설정이 필요 없음 : ktlint는 Kotlin 코딩 컨벤션과 Android Kotlin 스타일 가이드를 기반으로 합니다. 일부 측면에서 ktlint는 더 엄격한 규칙을 적용합니다.
규칙 세트 : ktlint는 standard 규칙 세트를 제공합니다. 또한 사용자 정의 규칙 세트를 쉽게 추가할 수 있습니다.
.editorconfig : 일부 규칙은 추가 설정이 가능하지만, 설정이 없는 경우에도 합리적인 기본값이 설정됩니다. ktlint는 주로 .editorconfig 파일을 사용하여 기본 .editorconfig, IntelliJ IDEA 특정 속성 및 Ktlint 특정 속성을 읽습니다.
규칙 비활성화 : 필요한 경우 규칙을 쉽게 비활성화할 수 있습니다.
내장 포맷터 : 대부분의 린트 위반 사항은 수동으로 수정할 필요가 없습니다. ktlint는 가능한 경우 위반 사항을 수정하는 내장 포맷터를 제공합니다. 일부 위반 사항은 결정적인 방식으로 수정할 수 없어 수동 조치가 필요합니다.
사용자 정의 가능한 출력 : 여러 리포터가 기본적으로 제공됩니다: plain (+ plain?group_by_file), plain-summary, json, html, checkstyle. 또한 사용자 정의 리포터를 쉽게 만들 수 있습니다.
실행 가능한 jar : ktlint는 모든 의존성이 포함된 단일 실행 가능한 jar로 배포됩니다.

Spring Boot 프로젝트에 ktlint 적용하기

1. Gradle 설정하기

먼저 build.gradle.kts 파일에 ktlint 플러그인을 추가합니다:

plugins {
    id("org.jlleitschuh.gradle.ktlint") version "11.3.1"
}

2. ktlint 설정 추가하기

build.gradle.kts 파일에 ktlint 설정을 추가합니다:

ktlint {
    verbose.set(true)
    outputToConsole.set(true)
    filter {
        exclude("**/generated/**")
        include("**/kotlin/**")
    }
}

3. .editorconfig 설정

프로젝트 루트 디렉토리에 .editorconfig 파일을 생성하고 아래와 같이 설정합니다:

root = true

[*]
charset = utf-8
end_of_line = lf
indent_size = 4
indent_style = space
insert_final_newline = true
max_line_length = 120
tab_width = 4
trim_trailing_whitespace = true

[*.{kt,kts}]
disabled_rules = import-ordering,no-wildcard-imports

ktlint 사용하기

코드 검사하기

아래 명령어로 코드 스타일을 검사할 수 있습니다:

./gradlew ktlintCheck

코드 자동 수정하기

검사된 코드 스타일 문제를 자동으로 수정하려면 다음 명령어를 사용합니다:

./gradlew ktlintFormat

Git Hooks 설정하기

코드를 커밋하기 전에 자동으로 ktlint 검사를 수행하도록 Git Hooks를 설정할 수 있습니다:

ktlint {
    installGitPreCommitHook.set(true)
}

주요 코드 스타일 규칙

ktlint가 검사하는 주요 규칙들을 살펴보겠습니다:

들여쓰기는 4칸 공백을 사용
줄 끝에 불필요한 공백 금지
파일 끝에 빈 줄 추가
import 문 정렬
중괄호 위치 규칙
함수 파라미터 정렬
문자열 템플릿 규칙

규칙 커스터마이징

특정 규칙을 비활성화하거나 수정하고 싶다면 .editorconfig 파일에서 설정할 수 있습니다:

[*.{kt,kts}]
# 특정 규칙 비활성화
disabled_rules = import-ordering,no-wildcard-imports

# 최대 줄 길이 설정
max_line_length = 120

# 들여쓰기 설정
indent_size = 4

CI/CD 파이프라인 통합

Jenkins나 GitHub Actions 같은 CI/CD 환경에서 ktlint를 실행하려면 다음과 같이 설정할 수 있습니다:

name: Kotlin Linter
on: [push]
jobs:
  ktlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run ktlint
        run: ./gradlew ktlintCheck

문제 해결하기

ktlint 실행 중 발생할 수 있는 일반적인 문제들과 해결 방법입니다:

특정 파일 무시하기

ktlint {
    filter {
        exclude("**/generated/**")
    }
}

빌드 실패 방지하기

ktlint {
    ignoreFailures.set(true)
}

IntelliJ IDEA에 적용하기

IntelliJ IDEA에서 ktlint를 사용하기

ktlint 플러그인 설치
Code Style 설정에서 Kotlin Convention 선택
Reformat Code 액션에 ktlint 포맷터 사용 설정

ktlint는 Kotlin 프로젝트의 코드 품질을 향상시키는 강력한 도구입니다. 특히 팀 프로젝트에서 일관된 코드 스타일을 유지하는 데 큰 도움이 됩니다. 초기 설정이 간단하고 자동화된 포맷팅을 제공하므로, 개발자들이 코드 스타일에 신경 쓰는 대신 비즈니스 로직 구현에 집중할 수 있게 해줍니다.

저작자표시 비영리 변경금지

재아군의 관찰 인생

[ktlint] Kotlin 코드 스타일 가이드 ktlint 적용하기