린트와 코딩 스타일
서버 코드는 세 가지 도구가 겹치지 않게 나눠 검사해요. 서식은 Spotless가 고쳐 쓰고, 이름과 관례는 Checkstyle이, 결함 패턴은 SpotBugs가 봐요. jOOQ가 생성한 코드는 셋 모두에서 빼요.
검사 명령
섹션 제목: “검사 명령”서버 코드를 바꾸면 server/에서 테스트를 돌려요. cowork AGENTS.md가 정한 검사예요.
./gradlew test integrationTest| 명령 | 하는 일 |
|---|---|
./gradlew test |
integration 태그가 없는 테스트 |
./gradlew integrationTest |
integration 태그가 붙은 테스트 |
./gradlew spotlessApply |
서식을 고쳐 써요 |
./gradlew spotlessCheck |
서식이 맞는지만 확인해요 |
./gradlew checkstyleMain |
Checkstyle 검사 |
./gradlew spotbugsMain |
SpotBugs 검사 |
./gradlew check |
위 검사와 테스트를 모두 돌려요 |
check는 Gradle 플러그인들이 각자의 검사를 걸어 두는 작업이고, build.gradle이 여기에 integrationTest를 더해요.
Spotless: 서식
섹션 제목: “Spotless: 서식”src 아래 모든 Java 파일에 palantir-java-format을 적용하고, 안 쓰는 import를 지우고, 애너테이션 자리를 맞춰요.
spotless { java { target fileTree('src') { include '**/*.java' } palantirJavaFormat() removeUnusedImports() formatAnnotations() }}Checkstyle: 이름과 관례
섹션 제목: “Checkstyle: 이름과 관례”Checkstyle 13.8.0을 쓰고, 경고를 하나도 허용하지 않아요(maxWarnings = 0). 규칙은 server/config/checkstyle/checkstyle.xml에 있어요.
| 묶음 | 검사 |
|---|---|
| 파일 | 탭 문자 금지, 파일 끝 줄바꿈 |
| import | * import, 겹친 import, 안 쓰는 import, 금지된 import |
| 이름 | 패키지·타입·메서드·필드·인자·지역 변수·상수 이름 |
| 결함 유발 패턴 | equals와 hashCode 짝, 문자열을 ==로 비교, switch의 default 누락, 다음 case로 흘러내림, 빈 블록과 빈 catch, 금지된 포괄 catch |
| 단순화 | 불필요하게 복잡한 불리언 식과 반환 |
| 구조 | 파일 하나에 최상위 클래스 하나, 파일 이름과 타입 이름 일치, 제어자 순서, 불필요한 제어자 |
테스트 코드는 메서드와 상수 이름에 한국어 문장을 쓸 수 있게 이름 규칙에서 빠져요(suppressions.xml).
SpotBugs: 결함 패턴
섹션 제목: “SpotBugs: 결함 패턴”컴파일한 코드에서 결함 패턴을 찾고 HTML·XML 보고서를 남겨요. 일부러 제외한 것은 server/config/spotbugs/exclude.xml에 사유와 함께 적어요. 생성한 jOOQ 패키지, 생성자 주입으로 협력 객체를 보관하는 패턴(EI_EXPOSE_REP2), 테스트에서만 일부러 하는 몇 가지가 여기에 있어요. 제외를 더할 때는 사유를 주석으로 남겨요.
코딩 스타일
섹션 제목: “코딩 스타일”검사기가 다 막지 못하지만 지키는 것이에요.
- 역할을 이름으로 드러내요:
…Controller,…Service,…Query,…Repository,…Requests,…Views,…ErrorCode. 저장소와 조회 구현에는Jooq…처럼 기술 이름을 붙여요. - 의존성은 생성자로 주입해요. 필드와 인자 이름은 선언 타입의 lowerCamelCase로 써요.
- 없을 수 있는 조회는
find…와Optional, 반드시 있어야 하는 조회는get…과 예외를 써요. - 불변 값과 전달 타입은
record로 쓰고, 접근자는name()형식이에요. - HTTP 요청·응답 타입은 피처의
…Requests·…Views에 묶고, 모듈 계약 전용 타입은…Facade안의Param·Result에 묶어요. - 현재 시각은 주입한
Clock에서 받아요. - 예외를 빈
catch나 포괄catch로 삼키지 않아요. 같은 실패를 여러 층에서 겹쳐 기록하지 않아요. - 테스트는 업무 불변식, 원자성, 중복 명령, 권한처럼 밖에서 관찰할 수 있는 결과를 검증해요.