모듈형 네트워크 서비스에 모듈 경계를 지키며 모듈 추가하기

## 모듈끼리 내부 구현이 아닌 공통 인터페이스로 연결하기 - 모듈 시스템을 확장의 핵심 경계로 취급한다. 인증, 저장소, 검증, 변환, 라우팅, 프로토콜 엔드포인트는 서로의 내부 구현 세부 사항을 직접 호출하지 말고 공유 프레임워크 인터페이스를 구현해야 한다. - 안정적인 인터페이스, 구성 기본 요소, 주소 처리, 오류 유형, 로깅 계약은 재사용 가능한 프레임워크 계층에 둔다. 구체적인 구현은 역할별 내부 패키지에 둔다. - 실행 파일의 진입점은 얇게 유지한다. 서비스 패키지를 불러오고, 내장 모듈이 등록되었는지 확인하고, 시작 절차를 호출하는 역할만 맡아야 한다. - 최상위 모듈은 구성과 지연 초기화 레지스트리를 통해 연결한다. 각 요청이나 메시지는 일치 규칙으로 선택된 검증기, 수정기, 전달 대상으로 이루어진 명시적 파이프라인을 거쳐 전달한다. - 구현이 같은 계층의 다른 구현이 아니라 안정적인 인터페이스에 의존하게 하여 순환 의존성을 피한다. ## 리포지토리의 빌드 래퍼로 빌드하고 영향받는 테스트 실행하기 - 지원되는 빌드 태그나 기능 옵션을 포함하여 리포지토리의 빌드 래퍼를 정식 빌드 경로로 사용한다. 버전 메타데이터나 필수 플래그를 누락하는 임시 컴파일러 명령으로 대체해서는 안 된다. - 여러 영역에 걸친 변경에는 전체 단위 테스트 모음을 실행한다. 동작이 프로토콜, 저장소, 전송 경계를 가로지르면 문서화된 작업 디렉터리에서 통합 테스트 하네스를 실행한다. - 빌드 시스템이 수행하는 버전 정보 주입을 유지한다. 런타임이 네이티브 구현에 의존하는 구성 요소를 사용한다면 소스 코드를 진단하기 전에 필요한 네이티브 컴파일러와 라이브러리를 사용할 수 있는지 확인한다. - 반복 작업 중에는 대상 패키지에 집중한 테스트를 우선하고, 완료 전에는 직접 영향을 받는 통합 경로를 실행한다. 건너뛴 테스트가 있다면 구체적인 환경상의 이유와 함께 보고한다. ## 새 모듈을 역할별 폴더에 두고 등록하기 1. 구현을 검증, 대상, 인증, 저장소, 조회, 변환, 엔드포인트 처리 등 해당 역할에 맞는 내부 디렉터리에 둔다. 2. 공통 모듈 수명 주기 인터페이스와 역할별 인터페이스를 모두 구현한다. 역할 계약은 안정적인 프레임워크 계층에 둔다. 3. 정해진 역할 접두사 명명 규칙을 사용하여 패키지 초기화 중에 팩터리를 등록한다. 4. 리포지토리에서 지정한 등록용 임포트나 매니페스트를 통해 구현을 서비스의 내장 모듈 연결 구성에 추가한다. 정해진 방식이 부수 효과로만 등록하는 구조라면 등록 코드는 해당 부수 효과만 수행해야 한다. 5. 기존 역할용 골격이나 도우미가 있으면 그것을 출발점으로 삼는다. 무상태 도우미는 모듈이 요청 간에 변경 가능한 상태를 실제로 유지하지 않을 때만 사용한다. 6. 구성, 등록, 정상 동작, 일시적 실패, 경계 오류 매핑에 초점을 맞춘 테스트를 추가한다. ## 재시도 가능 여부를 표시하고 내부 정보를 숨긴 오류 돌려주기 - 모듈 경계를 넘는 오류에는 프레임워크의 구조화된 오류 패키지를 사용한다. 호출자가 프로토콜 상태, 재시도 동작, 모듈 귀속 정보를 필요로 할 때 분류되지 않은 형식화 오류를 반환해서는 안 된다. - 외부 상태 코드, 지원되는 경우 확장 상태나 하위 유형, 클라이언트에 안전한 일반 메시지, 담당 검사 또는 대상의 이름을 포함한다. - 일시적 실패를 명시적으로 표시하여 디스패처가 재시도 가능한 조건과 영구 거부를 구분할 수 있게 한다. - 클라이언트에 표시되는 메시지에는 서버 구성, 내부 경로, 인증 정보, 구현 세부 사항을 포함하지 않는다. - 예상하지 못한 내부 실패에 구조화된 진단 필드를 추가하고 프레임워크 로거를 통해 기록한다. 원래 원인은 보존하되 원격 클라이언트에 노출하지 않는다. ## 요청 사이에 상태를 공유하지 않고 백그라운드 작업의 panic 복구하기 - 요청이나 메시지 사이에서 요청별 변경 가능 상태를 절대 공유하지 않는다. 프레임워크 계약이 명시적으로 직렬화하지 않는 한 검사와 변환은 동시에 실행된다고 가정한다. - 시작한 모든 goroutine이나 백그라운드 작업은 경계에서 panic을 복구하고 실패를 기록하며, 하나의 작업 때문에 전체 서비스가 중단되지 않게 해야 한다. - 외부 식별자는 비교하거나 저장하기 전에 정규화한다. 도메인과 유사한 식별자에는 독자적인 부분 정리 방식을 만들지 말고 프레임워크가 요구하는 Unicode 표현, 정규화 형식, Unicode 대소문자 폴딩을 적용한다. - 공유 구성 맵과 수명 주기 메서드를 통해 모듈 구성을 구문 분석한다. 알 수 없거나 유효하지 않은 설정은 기존 모듈과 일관된 방식으로 거부한다. - 프로그래밍 언어의 전역 로거 대신 프레임워크 로거를 사용한다. 프레임워크에서 제공하는 경우 관련 이벤트가 맥락을 유지하도록 작업 범위 또는 전송 범위의 로거를 만든다. - 병합 전에 등록, 구성 구문 분석, 동시 실행, 정규화, 구조화된 실패, 로그를 각 동작을 입증할 수 있는 가장 좁은 경계에서 테스트로 검증한다.