api와 storage에 대해 멀티모듈 구조로 분리

2026-01-11 22:20:02 +09:00
parent 24b3b640bc
commit 0cf452bf3b
13 changed files with 1828 additions and 48 deletions
--- a/LINT.md
+++ b/LINT.md
@@ -0,0 +1,344 @@
+# 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를 지원하면 재활성화 예정
+
+**활성화 방법:**
+1. `build.gradle`에서 detekt 관련 주석 제거
+2. Kotlin 버전을 2.0.x로 다운그레이드하거나
+3. detekt 최신 버전(Kotlin 2.2.x 지원) 출시 대기
+
+---
+
+## 사용 가능한 Gradle Tasks
+
+### 코드 스타일 체크
+
+```bash
+# 모든 모듈의 Kotlin 코드 스타일 체크
+./gradlew ktlintCheck
+
+# 특정 모듈만 체크
+./gradlew :balance-core-api:ktlintCheck
+./gradlew :storage:ktlintCheck
+```
+
+### 자동 포맷팅
+
+```bash
+# 모든 모듈의 Kotlin 코드 자동 포맷팅
+./gradlew ktlintFormat
+
+# 특정 모듈만 포맷팅
+./gradlew :balance-core-api:ktlintFormat
+./gradlew :storage:ktlintFormat
+```
+
+### 빌드와 함께 실행
+
+```bash
+# 빌드 전에 자동으로 ktlint 체크 실행
+./gradlew clean build
+
+# 또는
+./gradlew check  # 모든 검증 태스크 실행 (ktlint 포함)
+```
+
+---
+
+## ktlint 설정
+
+### 1. 기본 설정 (build.gradle)
+
+```gradle
+ktlint {
+    version = '1.4.1'
+    android = false
+    outputToConsole = true
+    coloredOutput = true
+    ignoreFailures = false
+    filter {
+        exclude('**/generated/**')
+        exclude('**/build/**')
+    }
+}
+```
+
+### 2. .editorconfig 설정
+
+프로젝트 루트의 `.editorconfig` 파일에서 코드 스타일을 세부 설정할 수 있습니다.
+
+```ini
+[*.{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 플러그인 설치
+
+1. `Preferences` → `Plugins`
+2. "ktlint" 검색
+3. 설치 및 재시작
+
+#### 2. EditorConfig 활성화
+
+1. `Preferences` → `Editor` → `Code Style`
+2. "Enable EditorConfig support" 체크
+
+#### 3. 저장 시 자동 포맷팅 (선택사항)
+
+1. `Preferences` → `Tools` → `Actions on Save`
+2. "Reformat code" 체크
+3. "Optimize imports" 체크
+
+---
+
+## CI/CD 통합
+
+### GitHub Actions 예시
+
+```yaml
+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. 공백
+- 파일 끝에 빈 줄 추가
+- 클래스 본문 시작/끝에 불필요한 빈 줄 제거
+- 불필요한 공백 제거
+
+---
+
+## 린트 위반 사항 수정
+
+### 자동 수정 (권장)
+
+대부분의 스타일 위반은 자동으로 수정할 수 있습니다.
+
+```bash
+./gradlew ktlintFormat
+```
+
+### 수동 수정
+
+자동 수정이 불가능한 경우, 린트 리포트를 확인하고 수동으로 수정합니다.
+
+**리포트 위치:**
+```
+build/reports/ktlint/
+├── ktlintMainSourceSetCheck.txt
+└── ktlintTestSourceSetCheck.txt
+```
+
+### 특정 규칙 비활성화 (비권장)
+
+정말 필요한 경우에만 사용합니다.
+
+```kotlin
+// 한 줄 비활성화
+@Suppress("ktlint:standard:max-line-length")
+val veryLongVariableName = "..."
+
+// 파일 전체 비활성화
+@file:Suppress("ktlint:standard:filename")
+```
+
+---
+
+## 커밋 전 체크리스트
+
+코드를 커밋하기 전에 다음을 실행하세요:
+
+```bash
+# 1. 코드 포맷팅
+./gradlew ktlintFormat
+
+# 2. 린트 체크
+./gradlew ktlintCheck
+
+# 3. 빌드 및 테스트
+./gradlew clean build
+```
+
+---
+
+## Git Hook 설정 (선택사항)
+
+커밋 전에 자동으로 ktlint를 실행하도록 설정할 수 있습니다.
+
+### pre-commit hook 생성
+
+`.git/hooks/pre-commit` 파일 생성:
+
+```bash
+#!/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!"
+```
+
+실행 권한 부여:
+```bash
+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의 포맷팅 규칙 불일치
+
+**해결:**
+```bash
+# ktlint 포맷팅 사용
+./gradlew ktlintFormat
+
+# IDE 포맷팅 사용 금지 또는 .editorconfig 확인
+```
+
+### 3. 특정 파일 제외하기
+
+`build.gradle`의 ktlint 설정 수정:
+
+```gradle
+ktlint {
+    filter {
+        exclude('**/generated/**')
+        exclude('**/build/**')
+        exclude('**/MySpecialFile.kt')  // 특정 파일 제외
+    }
+}
+```
+
+---
+
+## 참고 자료
+
+- [ktlint 공식 문서](https://pinterest.github.io/ktlint/)
+- [Kotlin 코드 스타일 가이드](https://kotlinlang.org/docs/coding-conventions.html)
+- [EditorConfig](https://editorconfig.org/)
+
+---
+
+## 향후 계획
+
+### detekt 재활성화
+
+Kotlin 2.2.x를 지원하는 detekt 버전이 출시되면:
+
+1. `build.gradle`에서 주석 해제:
+```gradle
+apply plugin: 'io.gitlab.arturbosch.detekt'
+```
+
+2. detekt 설정 활성화
+
+3. 정적 분석 실행:
+```bash
+./gradlew detekt
+```
+
+---
+
+**최종 업데이트:** 2026-01-11
+**ktlint 버전:** 1.4.1
+**Kotlin 버전:** 2.2.21