값을 몰래 바꾸거나 데이터를 흘리지 않는 데이터 복제(ETL) 코드 만들기

## 요청이 없으면 push나 마이그레이션 변경을 하지 않기 각 변경은 해결하려는 문제에 집중하세요. 정확성을 보존하기 위해 더 광범위한 구조 개선이 필요하지 않다면, 일관성을 유지하는 가장 작은 변경 내역을 우선하세요. 패턴, 종속성, 도우미 또는 테스트 픽스처을 도입하기 전에 주변 코드를 살펴보고 확립된 작업 공간 규칙을 따르세요. 강제할 수 있는 스타일은 포매터 구성, 컴파일러 진단, 작업 공간 정적 검사 설정을 기준으로 판단하세요. 사용자가 해당 작업을 명시적으로 요청하지 않았다면 저장소에 쓰거나, 브랜치를 게시하거나, 변경 요청을 열거나, 이력을 다시 작성하지 마세요. 요청된 작업에 마이그레이션 변경이 명확히 필요한 경우가 아니라면 데이터베이스 마이그레이션을 수정하지 마세요. 마이그레이션 파일 안의 주석과 실행되지 않는 텍스트도 여기에 포함됩니다. 비용이 큰 작업 공간 전체 검사는 그 범위가 정당한 경우에만 실행하세요. 위험이 낮은 문서 또는 구성 변경에는 관련된 최소한의 검증만 사용하고, 무엇을 실행했는지 정확히 보고하세요. ## 모듈을 데이터 개념별로 나누고 API는 기본 비공개로 두기 범용적인 묶음이 아니라 도메인 개념에 따라 구성하세요. 복제 동작과 복제 전용 타입은 함께 두고, 재사용 가능한 데이터베이스 기본 요소, 원본 도우미, 슬롯 도우미, 메타데이터 접근 기능은 통합 경계에 배치하세요. 다른 패키지가 해당 API에 실제로 의존할 때만 패키지 경계를 사용하세요. 하나의 도메인 안에서는 `schema`, `data`, `event`, `store`, `source`, `slots` 같은 이름의 모듈을 우선하세요. 최상위 실행 파일은 조율에만 집중하게 하세요. 구현 세부 사항은 역할이 명확한 도우미와 모듈로 옮기세요. 기본 가시성은 비공개로 하고 실제 호출자가 있을 때만 넓히세요. 비공개, 패키지 범위, 공개 순서로 우선하세요. 모든 재노출을 API 계약으로 취급하세요. - 내부 모듈에서 와일드카드 재노출을 피하세요. - 유용한 최소한의 설정 노출면만 공개하세요. - 작업자 조율, 코덱, 런타임 연결부, 구현 세부 사항은 비공개로 유지하세요. - 의도적으로 안정된 API가 아니라면 호환성 파사드를 만들지 마세요. 영리한 추상화보다 명확하고 관례적인 코드를 우선하세요. 타입, 생성자, 공개 메서드, 비공개 도우미를 읽기 쉬운 순서로 배치하세요. ## 반올림·잘림 같은 조용한 값 변경 막기 반올림, 잘라내기, 범위 제한, 강제 형 변환, 오버플로 또는 정밀도 손실처럼 대상 시스템이 눈에 띄지 않는 의미 변화를 받아들일 수 있다면 해당 값이 사용되는 곳 가까이에서 검증하세요. 대상이 이미 지원되지 않는 값을 명시적인 오류로 거부한다면, 입증된 필요 없이 쓰기 경로에서 비용이 큰 검증을 중복하지 마세요. 무손실로 사용할 수 있다면 검사되는 숫자 변환이나 트레이트 기반 변환을 사용하세요. 손실이 의도된 캐스트는 손실을 이해하고, 필요한 경우 범위를 검사했으며, 대상 표현에 꼭 필요할 때만 사용하세요. 매핑이 실패할 수 없고, 의미상 무손실이며, 값을 보존하고, 명백한 경우에만 암시적 변환을 사용하세요. 패치 갱신은 서로 구분되는 세 가지 상태로 모델링하세요. - 생략된 필드는 저장된 값을 보존합니다. - 명시적인 null은 선택적 값을 지우거나 기본값이 있는 값을 초기화합니다. - null이 아닌 값은 저장된 값을 대체합니다. 완전한 구성을 패치 의미로 변환할 때는 명시적인 변환 도우미를 사용하세요. 일반적인 변환 트레이트 뒤에 보존에서 삭제로 바뀌는 동작을 숨기지 마세요. ## 잘못된 입력에 멈추지 않고 분명한 오류 돌려주기 복구 가능한 실패에는 타입이 지정된 오류와 결과 값을 사용하세요. 원래 오류를 원인 연결 고리로 보존하면서 작업, 식별자, 개수, 타입, 구문처럼 값을 소유하는 맥락 정보를 추가하세요. 호출자에게 의도적으로 정제된 메시지를 제공하는 편이 더 안전한 경우가 아니라면 하위 오류를 문자열 하나로 평탄화하지 마세요. 공개 API 응답에 데이터베이스 드라이버 오류, 내부 질의, 고객 데이터 또는 인프라 세부 사항이 노출되어서는 안 됩니다. 프로그래머의 불변 조건이 깨진 경우에만 패닉을 사용하세요. 외부 입력, 잘못된 구문, 지원되지 않는 값, 시스템 상태 실패에는 명시적인 오류를 반환해야 합니다. 파서 진입점은 빈 입력, 예상하지 못한 입력 종료, 잘못된 이스케이프, 유효하지 않은 바이트 시퀀스, 유효하지 않은 범위, 오버플로, 언더플로, 지원되지 않는 구문을 패닉 없이 처리해야 합니다. 입력이 오프셋을 제어할 때는 검사된 접근, 반복자, 바이트 슬라이스 구문 분석을 우선하세요. 직접 인덱싱은 로컬 경계 또는 정확한 청크 불변 조건으로 안전성이 명백한 경우에만 허용됩니다. 이전에 패닉을 일으키거나 조용히 잘못 분석될 수 있었던 모든 비정상 입력 경계에 회귀 테스트를 추가하세요. ## 백그라운드 작업을 멈추는 방식을 가진 상태에 따라 고르기 필요한 경우가 아니라면 unsafe 코드를 피하세요. 모든 unsafe 블록 바로 옆에는 해당 연산을 건전하게 만드는 불변 조건을 밝힌 안전성 설명이 있어야 합니다. 불필요한 복제나 내부 가변성보다 소유권과 빌림을 우선하세요. 오래 실행되는 비동기 작업은 이름이 있는 작업이나 도우미 뒤에 두고, 소유한 상태에 따라 종료 동작을 선택하세요. - 작업 핸들을 소멸시키면 작업이 분리됩니다. 즉시 멈춰야 하는 폐기 가능한 백그라운드 작업은 명시적으로 강제 중단하세요. - 작업 집합을 소멸시키면 그 집합이 소유한 모든 작업이 강제 중단됩니다. - 작업 집합을 소멸시킬 범위를 벗어나기 직전에 같은 집합을 불필요하게 다시 강제 중단하지 마세요. - 작업 집합은 계속 살아 있지만 그 안의 작업을 멈춰야 한다면 명시적인 강제 중단 연산을 사용하세요. - 작업이 트랜잭션, 버퍼링된 대상 쓰기 또는 재시도에 민감한 복제 상태를 소유한다면 정상 종료 신호를 보내고 작업 종료를 기다리세요. 상태를 안전하게 버릴 수 있는 폴링 또는 원격 측정 작업에는 복잡한 종료 조율을 추가하지 마세요. ## 비밀 정보와 고객 데이터를 코드와 로그에서 빼기 버전 관리되는 파일, 브랜치, 커밋, 검토, 로그, 화면 캡처, 테스트 픽스처, 생성된 결과물, 터미널 출력은 잠재적으로 공개될 수 있다고 간주하세요. 인증 정보, 토큰, 비공개 엔드포인트, 고객 데이터, 프로덕션 페이로드, 개인 데이터 또는 독점 구성을 코드, 테스트, 문서, 예시, 주석, 메시지, 원격 측정, 패닉 세부 정보 또는 생성 파일에 절대 넣지 마세요. 예시에는 임의로 만든 자리표시자를 사용하세요. 실제 비밀 정보는 승인된 환경 변수, 버전 관리에서 제외된 로컬 파일, 비밀 정보 관리 서비스 또는 CI 비밀 정보 저장소에만 보관하세요. 의심스러운 값이 실제 값처럼 보이거나 비공개 환경에서 가져온 것이라면 이를 재현하지 마세요. 게시 경로를 중단하고, 값을 인용하지 않은 채 위치를 보고하며, 노출되었을 가능성이 있다면 교체 또는 폐기를 권고하세요. 관측 가능성을 위해 다음을 따르세요. - 카디널리티가 낮은 레이블을 우선하세요. - 테이블 이름, 열 이름, 타입, 개수, 길이, 위치, 작업 이름과 같은 구조적 메타데이터를 기록하세요. - 행 값, 셀 내용, 민감한 요청 또는 응답 본문, 인증 정보, 토큰을 절대 기록하지 마세요. - 오류와 구조화된 필드에는 안전한 표시 형식을 사용하세요. - 민감한 경로와 모니터링 범위에서는 본문 캡처를 정제하세요. ## 실제 복제 이벤트를 테스트하고 테스트가 정말 돌았는지 확인하기 관련된 최소 범위의 테스트를 먼저 실행한 뒤, 공통 동작, 회귀 또는 요청으로 정당화될 때 범위를 넓히세요. 예상한 테스트가 실제로 실행되었는지 확인하세요. 일치하는 테스트가 하나도 없는 성공한 명령은 검증 통과가 아닙니다. 불확실한 필터를 적용하기 전에 테스트 목록을 확인하세요. 기본 테스트 실행기가 문서 테스트를 지원하지 않는다면 별도로 실행하세요. 맞춤형 테스트 연결부를 만들기 전에 주변의 테스트 픽스처, 데이터베이스 도우미, 대기 기본 도구, 검증문을 재사용하세요. 이벤트 기반 통합 테스트에서는 다음 순서를 따르세요. 1. 생산자가 이벤트를 내보낼 수 있게 되기 전에 알림 또는 대기 핸들을 등록하세요. 2. 원본 측 쓰기를 수행하세요. 3. 예상한 알림을 기다리세요. 4. 테스트가 진행 중 동작을 명시적으로 다루는 경우가 아니라면 대상 상태를 검증하기 전에 파이프라인을 종료하고 끝날 때까지 기다리세요. 5. 재시작 또는 분리된 단계에서 기록을 지워야 하는 경우가 아니라면 누적 이벤트 기록을 기준으로 검증하세요. 예상하는 변경 데이터 캡처 이벤트를 원본 데이터베이스의 실제 복제본 식별 방식에 맞추세요. 일부 갱신 행을 내보낼 수 없는 모드에서는 그런 행을 기대하지 마세요. ## 코드에 설명을 쓰고 실행한 확인 보고하기 공개 및 비공개 항목을 간결하고 정확한 문장으로 문서화하세요. 문서화 시스템이 지원하는 참조를 사용해 타입과 메서드를 연결하세요. 주석에는 문장 부호를 붙이고 설명하는 코드 위에 배치하세요. 메트릭 이름과 레이블 키를 상수로 정의하고, 공통 레이블을 중앙에서 관리하며, 설명은 한 번만 등록하세요. 원본마다 역할이 명확한 메트릭 작업 하나만 두고 조율 노출면은 작게 유지하세요. 완료 전에 영향받는 범위를 확인하세요. - 변경된 대상이 컴파일됩니다. - 서식 검사가 통과합니다. - 작업 공간 정적 검사 구성에 따라 정적 분석이 통과합니다. - 관련 단위 및 통합 테스트가 통과하고 실제로 실행되었습니다. - 해당되는 경우 문서 테스트가 통과합니다. - 주석과 문서가 최종 동작과 일치합니다. - 메트릭, 로그, 레이블이 이름 지정 및 데이터 안전 규칙을 따릅니다. 실행한 검사와 그 범위, 의도적으로 생략한 검사를 보고하세요. 출력에서 의미 있는 대상이 실행되지 않았다고 드러난다면 명령의 종료 상태만으로 완료를 주장하지 마세요.