모듈로 나뉜 Java 프로젝트에서 호환성을 지키며 작게 고치기

## 편집 전에 빌드, 서식, CI 규칙 확인하기 저장소 지침, 빌드 구성, 서식 규칙, 지속적 통합 검사를 실행 가능한 계약으로 취급하세요. 편집 전에 적용되는 지침을 읽고 어떤 규칙이 도구로 강제되는지 확인하세요. - 표준 빌드 래퍼, 포맷터, 정적 검사, 테스트 명령, 기여 정책을 찾으세요. - 코드를 변경하기 전에 담당 모듈과 그 의존성을 추적하세요. - 로컬에서만 편리한 대안보다 프로젝트에 확립된 유틸리티와 패턴을 우선하세요. - 소스 호환성, 빌드 도구 요구 사항, 런타임 지원, 배포 동작을 구분하세요. - 변경을 통과시키려는 이유만으로 품질 관문을 비활성화하지 마세요. 요청된 동작을 제어하는 가장 작은 범위의 권위 있는 입력을 사용하세요. ## 선언된 Java 버전과 의존성에서 동작하도록 유지하기 빌드에는 최신 도구 체인이 필요하더라도 소스는 이전 런타임과 계속 호환될 수 있습니다. 선언된 소스 수준에 맞춰 컴파일하고 테스트하세요. 로컬 환경이 더 최신이라는 이유로 새로운 언어 기능이나 라이브러리 API를 사용할 수 있다고 가정하지 마세요. - 지원되지 않는 편의 API를 호환되는 대안으로 교체하세요. - 필요한 경우 저장소에서 재배치되거나 셰이딩된 의존성 네임스페이스를 사용하세요. - 검증, 직렬화, 컬렉션, 파일, Future, 시간 처리에는 프로젝트 소유 유틸리티를 우선하세요. - 배포판이 해당 라이브러리를 격리한다면 서드파티 라이브러리를 직접 import하지 마세요. - 의존성을 추가하기 전에 호환성, 라이선스, 패키징, 전이 영향을 논의하세요. 로컬 컴파일에만 의존하지 말고 저장소에서 지정한 빌드 대상으로 호환성을 검증하세요. ## 공개 API에 팩토리, 빌더, 불변 결과 객체 사용하기 의도한 안정성에 따라 API를 표시하세요. 안정된 공개 계약, 발전 중인 공개 계약, 내부 구현 영역은 서로 명확히 구분해야 합니다. - 팩터리에서는 인터페이스를 반환하고 비공개 생성자나 정적 생성 메서드 뒤에 구성 과정을 숨기세요. - 여러 단계의 구성에는 빌더를 사용하고, 연속 호출 방식의 메서드와 검증된 단일 구성 지점을 두세요. - 결과 객체는 상태를 final로 유지하고 setter를 제공하지 않으며 동등성, 해싱, 문자열 표현을 완전하게 구현한 불변 객체로 만드세요. - 호출자가 안전하지 않은 형 변환 없이 두 형태를 모두 필요로 할 때는 제네릭 인터페이스와 타입 지정 인터페이스를 제공하세요. - 공개 타입에 스레드 안전성 요구 사항을 문서화하세요. 공개 계약을 변경하려면 호환성 분석과 적절한 버전 관리 경로가 필요합니다. ## 모듈 간 의존성을 한 방향으로 유지하기 구현 전에 모듈 그래프를 파악하세요. 기반 모듈이 공유 타입과 인터페이스를 소유하고, 그 위에 프로토콜 또는 전송 계층을 구축해야 합니다. 동급의 클라이언트 모듈과 서버 모듈은 서로 의존해서는 안 되며, 통합 기능은 안정된 하위 계층 위에 있어야 합니다. - 공유 인터페이스는 적절한 최하위 모듈에 정의하고 구현은 그 위에 두세요. - 커넥터와 선택적 통합 기능의 의존성이 코어로 유입되지 않게 하세요. - 동급 모듈 사이의 순환 의존성과 편의성만을 위한 가져오기를 막으세요. - 테스트에서 프로덕션 패키지 구조를 그대로 반영하세요. - 생성 코드, 배포 리소스, 문서 생성기, 테스트 유틸리티를 각각 지정된 모듈에 두세요. 기능이 경계를 넘을 때는 아키텍처를 우회하지 말고 각 담당 계층을 명시적으로 변경하세요. ## 오류 종류를 구분하고 공유 상태를 잠금으로 보호하기 API 경계에서 프로젝트 표준 사전 조건 헬퍼와 조치 방법을 알려 주는 메시지로 입력을 검증하세요. 호출자가 사용자 오류, 재시도 가능한 실패, 검사되지 않는 내부 실패를 구분할 수 있도록 예외 계층을 보존하세요. - 확립된 Future 유틸리티와 오류 처리기를 통해 비동기 실패를 전파하세요. - 문서화된 이유 없이 비동기 작업을 차단하지 말고 작업들을 조합하세요. - 명시적 잠금으로 공유 가변 상태를 보호하고 보호 대상 필드를 문서화하세요. - 잠금 밖에서의 접근에 필요한 경우에만 가시성 프리미티브를 사용하세요. - 구조화된 리소스 관리를 통해 리소스를 닫으세요. - 정리 작업이 반복될 수 있다면 close 작업을 멱등적으로 만드세요. 검사 대상 실패를 숨기거나 재시도 가능한 오류와 영구 오류를 구분 없는 하나의 예외로 합치지 마세요. ## 설정 키와 메시지 스키마의 호환성 유지하기 필요한 경우 기본값, 설명, 선택적 값, 사용 중단된 키 처리 기능이 있는 타입 지정 빌더로 구성을 정의하세요. 계층적이고 일관된 키를 사용하며 저장소의 구성 추상화를 통해 값에 접근하세요. 직렬화와 원격 메시지에는 다음 원칙을 적용하세요. - 선언된 스키마와 프로토콜 버전을 보존하세요. - 해당 버전이 지원하는 필드 형식만 사용하세요. - 스키마를 변경한 뒤에는 표준 생성기로 코드를 다시 생성하세요. - 전송 메시지를 불변으로 유지하고 내부 전송 타입을 그에 맞게 표시하세요. - 선택적 필드를 명시적으로 표현하세요. - 생성 워크플로가 관리하는 생성 파일은 절대 직접 편집하지 마세요. 구성 계약이나 전송 계약이 변경될 때마다 호환성 테스트와 생성 문서를 업데이트하세요. ## 프로젝트의 테스트 도구로 단위 테스트와 통합 테스트 작성하기 저장소가 선택한 테스트 프레임워크, 어설션 라이브러리, 명명 규칙, 확장 기능, 기본 픽스처를 사용하세요. 전역 테스트 하니스와 충돌하는 다른 어설션이나 시간 제한 메커니즘을 혼용하지 마세요. - 로컬 동작에는 범위가 명확한 단위 테스트를, 컴포넌트 간 계약에는 통합 테스트를 작성하세요. - 테스트 대상 동작이 드러나는 설명적인 테스트 이름을 사용하세요. - 성공 결과와 예상 실패를 모두 어설션하세요. - 병렬 인프라를 새로 만들지 말고 지원되는 클러스터, 스토리지, 서비스 픽스처를 재사용하세요. - 먼저 범위가 가장 좁은 영향받은 테스트를 실행한 다음 직접 영향받는 테스트 모음을 실행하세요. - 수정의 증거로 삼기 전에 테스트가 의도한 이유로 실패하는지 확인하세요. 내부 구현 세부 사항이 계약의 일부가 아니라면 공개 동작을 통해 테스트하세요. ## 프로젝트의 빌드 래퍼로 빌드하고 검사하기 빌드, 서식 지정, 정적 분석, 라이선스 검사, 코드 생성, 테스트에는 저장소 래퍼를 사용하세요. 표준 명령은 도구를 직접 호출할 때 빠질 수 있는 생성 리소스를 준비하거나 호환성을 강제할 수 있습니다. - 선언된 소스 대상을 보존하면서 문서화된 도구 체인으로 빌드하세요. - 로컬 서비스 의존성과 컴포넌트를 문서화된 순서로 시작하세요. - 지원되는 구성 파일과 값만 편집하세요. - 정적 검사 전에 서식을 지정하세요. - 더 광범위한 검증에 앞서 영향받는 테스트 모음을 실행하세요. - 변경이 테스트 대상 동작을 바꿀 수 있다면 커버리지 프로필을 사용하세요. 완료를 보고하기 전에 지속적 통합 단계를 이해하고 관련 단계를 로컬에서 재현하세요. ## 포매터를 따르고 관련 없는 변경을 diff에 섞지 않기 강제되는 import 순서, 한정자 순서, 배열 문법, 중괄호 규칙, 공백 정책, 명명 규칙을 따르세요. 기계적인 스타일은 표준 포맷터가 처리하게 하세요. - 와일드카드 import와 저장소에서 금지한 주석 마커 또는 저작자 표시 태그를 피하세요. - 프로젝트에서 요구하면 public 및 protected API를 문서화된 상태로 유지하세요. - 가독성을 압축하지 말고 일관된 책임을 추출하여 파일 크기 제한을 지키세요. - 명령, 구성, 호환성 또는 공개 동작이 바뀌면 문서를 업데이트하세요. - 최종 차이에서 관련 없는 재작성, 의도하지 않은 생성 파일 편집, 비밀 정보, 미완료 정리를 확인하세요. 범위가 명확한 동작 변경과 관련 없는 리팩터링을 결합하지 마세요. ## 검토용 브랜치로 변경을 올리고 force-push하지 않기 허가된 브랜치에서 작업하고 push하기 전에 모든 원격 저장소를 확인하세요. 업스트림 또는 공유 브랜치를 보호하고, 보호 대상에 직접 쓰지 말고 프로젝트의 검토 경로를 통해 변경을 게시하세요. - 문서화된 워크플로에 따라 표준 기본 브랜치에서 rebase하거나 업데이트하세요. - 컴포넌트로 범위를 한정한 간결한 commit 제목을 작성하고 필요한 경우 본문에 동기를 설명하세요. - 게시 전에 전체 브랜치 차이를 검토하세요. - 서식 지정, 정적 검사, 라이선스 검사, 영향받는 테스트를 실행하세요. - 검토 요청에 간단한 요약과 테스트 계획을 포함하세요. - 기여 정책에서 요구하는 경우 지원을 받아 만든 변경을 사람이 검토할 대상으로 표시하세요. 명시적 허가 없이 공유 브랜치에 force-push하거나 파괴적인 기록 작업을 사용하지 마세요. ## 새 의존성이나 리셋처럼 범위가 넓거나 파괴적인 작업 전에 묻기 기존 규칙을 따르는 범위 한정 읽기, 로컬 빌드, 테스트, 서식 지정, 진단, 수정은 자율적으로 진행하세요. 모듈 간 리팩터링, 새 의존성, 스키마 마이그레이션, 빌드 시스템 변경, 지속적 통합 변경, 파괴적 작업처럼 범위가 넓거나 결과가 중대한 작업은 먼저 확인하세요. 명시적 허가 없이는 절대 다음 작업을 하지 마세요. - 자격 증명이나 민감한 값을 commit하지 마세요. - 보호된 업스트림 대상에 직접 push하지 마세요. - 공유 기록에 force-push하거나 브랜치를 삭제하지 마세요. - hard reset이나 파괴적인 정리를 실행하지 마세요. - hook, 정적 검사, 서식 규칙을 우회하지 마세요. - 원본 대신 생성된 결과물을 수정하지 마세요. - 통과 결과를 얻기 위해 품질 관문을 약화하지 마세요. 완료 전에 테스트, 서식 지정, 정적 검사, 필수 헤더, 의도한 전체 차이를 확인하세요. 범위나 되돌릴 수 있는지가 불확실하면 멈추고 필요한 결정을 설명하세요.