quantbench/balance

Fork 0

Files

Jongheon Kim 0cf452bf3b api와 storage에 대해 멀티모듈 구조로 분리

2026-01-11 22:20:02 +09:00

6.5 KiB

Raw Blame History

Kotlin Lint 설정 가이드

개요

이 프로젝트는 Kotlin 코드 품질을 유지하기 위해 ktlint를 사용합니다.

사용 가능한 Lint 도구

1. ktlint (활성화됨 ✅)

Kotlin 공식 코드 스타일 가이드를 따르는 린터 및 포맷터입니다.

특징:

코드 스타일 체크
자동 포맷팅 기능
Kotlin 2.2.21과 완벽 호환

2. detekt (현재 비활성화됨 ⚠️)

정적 코드 분석 도구로 코드 냄새, 복잡도, 잠재적 버그를 탐지합니다.

비활성화 이유:

Kotlin 2.2.21과 호환성 문제
detekt 1.23.7은 Kotlin 2.0.10까지만 지원
향후 detekt가 Kotlin 2.2.x를 지원하면 재활성화 예정

활성화 방법:

build.gradle에서 detekt 관련 주석 제거
Kotlin 버전을 2.0.x로 다운그레이드하거나
detekt 최신 버전(Kotlin 2.2.x 지원) 출시 대기

사용 가능한 Gradle Tasks

코드 스타일 체크

# 모든 모듈의 Kotlin 코드 스타일 체크
./gradlew ktlintCheck

# 특정 모듈만 체크
./gradlew :balance-core-api:ktlintCheck
./gradlew :storage:ktlintCheck

자동 포맷팅

# 모든 모듈의 Kotlin 코드 자동 포맷팅
./gradlew ktlintFormat

# 특정 모듈만 포맷팅
./gradlew :balance-core-api:ktlintFormat
./gradlew :storage:ktlintFormat

빌드와 함께 실행

# 빌드 전에 자동으로 ktlint 체크 실행
./gradlew clean build

# 또는
./gradlew check  # 모든 검증 태스크 실행 (ktlint 포함)

ktlint 설정

1. 기본 설정 (build.gradle)

ktlint {
    version = '1.4.1'
    android = false
    outputToConsole = true
    coloredOutput = true
    ignoreFailures = false
    filter {
        exclude('**/generated/**')
        exclude('**/build/**')
    }
}

2. .editorconfig 설정

프로젝트 루트의 .editorconfig 파일에서 코드 스타일을 세부 설정할 수 있습니다.

[*.{kt,kts}]
indent_size = 4
continuation_indent_size = 4
max_line_length = 120
ij_kotlin_allow_trailing_comma = true
ij_kotlin_allow_trailing_comma_on_call_site = true

IDE 통합

IntelliJ IDEA / Android Studio

1. ktlint 플러그인 설치

Preferences → Plugins
"ktlint" 검색
설치 및 재시작

2. EditorConfig 활성화

Preferences → Editor → Code Style
"Enable EditorConfig support" 체크

3. 저장 시 자동 포맷팅 (선택사항)

Preferences → Tools → Actions on Save
"Reformat code" 체크
"Optimize imports" 체크

CI/CD 통합

GitHub Actions 예시

name: Lint Check

on:
  pull_request:
    branches: [ main ]
  push:
    branches: [ main ]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up JDK 24
        uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '24'

      - name: Grant execute permission for gradlew
        run: chmod +x gradlew

      - name: Run ktlint
        run: ./gradlew ktlintCheck

      - name: Upload ktlint reports
        if: failure()
        uses: actions/upload-artifact@v3
        with:
          name: ktlint-reports
          path: '**/build/reports/ktlint/'

일반적인 린트 규칙

1. 들여쓰기

4 스페이스 사용 (탭 사용 금지)

2. 최대 줄 길이

120자 제한

3. 임포트

와일드카드 임포트 금지 (java.util.* 제외)
사용하지 않는 임포트 제거

4. 네이밍

클래스: PascalCase
함수/변수: camelCase
상수: UPPER_SNAKE_CASE

5. 공백

파일 끝에 빈 줄 추가
클래스 본문 시작/끝에 불필요한 빈 줄 제거
불필요한 공백 제거

린트 위반 사항 수정

자동 수정 (권장)

대부분의 스타일 위반은 자동으로 수정할 수 있습니다.

./gradlew ktlintFormat

수동 수정

자동 수정이 불가능한 경우, 린트 리포트를 확인하고 수동으로 수정합니다.

리포트 위치:

build/reports/ktlint/
├── ktlintMainSourceSetCheck.txt
└── ktlintTestSourceSetCheck.txt

특정 규칙 비활성화 (비권장)

정말 필요한 경우에만 사용합니다.

// 한 줄 비활성화
@Suppress("ktlint:standard:max-line-length")
val veryLongVariableName = "..."

// 파일 전체 비활성화
@file:Suppress("ktlint:standard:filename")

커밋 전 체크리스트

코드를 커밋하기 전에 다음을 실행하세요:

# 1. 코드 포맷팅
./gradlew ktlintFormat

# 2. 린트 체크
./gradlew ktlintCheck

# 3. 빌드 및 테스트
./gradlew clean build

Git Hook 설정 (선택사항)

커밋 전에 자동으로 ktlint를 실행하도록 설정할 수 있습니다.

pre-commit hook 생성

.git/hooks/pre-commit 파일 생성:

#!/bin/sh
echo "Running ktlint check..."
./gradlew ktlintCheck

if [ $? -ne 0 ]; then
    echo "❌ ktlint check failed. Please run './gradlew ktlintFormat' to fix."
    exit 1
fi

echo "✅ ktlint check passed!"

실행 권한 부여:

chmod +x .git/hooks/pre-commit

문제 해결

1. ktlint 버전 호환성 문제

증상:

Class org.jetbrains.kotlin.lexer.KtTokens does not have member field...

해결:

build.gradle에서 ktlint 버전을 1.4.1 이상으로 업데이트
Kotlin 버전과 호환되는 ktlint 버전 확인

2. 포맷팅 후에도 체크 실패

원인:

IDE와 ktlint의 포맷팅 규칙 불일치