공식 SDK와 CLI로 그대로 쓸 수 있는 로컬 클라우드 에뮬레이터 만들기

## 편의보다 실제 클라우드와 같은 요청·응답 형식을 우선하기 다음 순서로 우선순위를 정하십시오. 1. 원본 클라우드 플랫폼 프로토콜과의 호환성 2. 공식 SDK 및 CLI 클라이언트가 기대하는 동작 3. 기존 에뮬레이터 패턴의 재사용 4. 편의성보다 정확성 5. 범위가 좁고 테스트 가능한 변경 구현 편의를 위해 사용자 지정 엔드포인트 구조를 추가하거나 요청 및 응답 형식을 단순화하지 마십시오. 요청된 동작에 필요하지 않다면 광범위한 리팩터링을 수행하지 마십시오. 편집하기 전에 서비스, 제어 플레인 또는 데이터 플레인 역할, 프로토콜 계열, 본보기로 삼을 기존 구현, 구성에 미치는 영향, 저장소에 미치는 영향, 문서에 미치는 영향, 유용한 최소 테스트 계획을 파악하십시오. 동작이 불분명하면 먼저 원본 플랫폼 계약을 따르고, 그다음 확립된 에뮬레이터 동작, 마지막으로 호환성 테스트 모음의 기대 사항을 따르십시오. 작업에 서비스 간 아키텍처 변경이 필요하다면 무작정 리팩터링하지 말고 장단점을 명확히 제시하십시오. ## 프로토콜 처리 부분은 얇게, 업무 로직은 서비스에 두기 계층화된 서비스 설계를 사용하십시오. - 컨트롤러나 핸들러는 프로토콜 입력을 구문 분석하고 프로토콜 호환 응답을 생성합니다. - 서비스는 비즈니스 로직을 포함하고 공유 클라우드 도메인 예외를 발생시킵니다. - 모델은 도메인 데이터를 나타냅니다. - 레지스트리, 구성, 저장소 팩토리, 수명 주기 서비스, 파서, 빌더, 예외 매퍼는 공유 인프라를 제공합니다. 컨트롤러는 간결하게 유지하십시오. 새로운 패턴을 도입하기 전에 공유 유틸리티를 재사용하고 가장 유사한 기존 서비스 구조를 따르십시오. 도메인 오류는 공유 예외 형식을 통해 전달하십시오. 쿼리 및 XML 흐름은 표준 예외 매퍼를 사용해야 하며, JSON 프로토콜 흐름은 필수 구조화 오류 본문을 반환해야 합니다. 컨트롤러 반환 형식은 사전 컴파일 리플렉션 및 직렬화 제약 조건과 계속 호환되어야 합니다. 생성자 주입을 사용하고, 조건문에 중괄호를 쓰며, 코드만으로 의도가 드러나게 하십시오. `catch` 블록을 절대로 비워 두지 마십시오. 예외를 의도적으로 허용한다면 진단에 충분한 맥락을 기록하십시오. ## 작업을 추가하기 전에 서비스의 실제 프로토콜 확인하기 작업을 추가하기 전에 실제 통신 프로토콜을 확인하십시오. - 쿼리 프로토콜은 폼 인코딩 작업과 XML 응답을 사용합니다. - JSON RPC 방식 프로토콜은 대상 헤더와 구조화된 JSON을 사용합니다. - REST JSON과 REST XML은 리소스 경로와 각각의 네이티브 본문 형식을 사용합니다. - 데이터 플레인 서비스에는 HTTP 관리 API 대신 네이티브 TCP 프록시가 필요할 수 있습니다. 공유 XML 빌더, 파서, 네임스페이스 상수를 사용하십시오. 정규식으로 XML을 절대로 구문 분석하지 마십시오. JSON 오류는 대상 프로토콜의 오류 구조에 맞추십시오. 일부 서비스는 둘 이상의 호환 경로를 제공합니다. 대체 핸들러의 동작을 일치시키고 함께 테스트하십시오. ID 검색 엔드포인트를 관리 API 모델에 억지로 맞추지 말고 실제 공개 프로토콜에 따라 처리하십시오. 수작업으로 만든 HTTP 요청만 사용하지 말고 공식 SDK 클라이언트로 관리 API를 검증하십시오. 수동 페이로드가 수락되었다고 해서 클라이언트 직렬화, 헤더, 오류, 페이지 매김 또는 URL 생성이 호환된다는 뜻은 아닙니다. ## 저장 방식과 설정 파일을 항상 함께 고치기 공유 팩토리와 선언된 모드를 통해 저장소를 지원하십시오. 서비스 내부에서 저장소 구현을 직접 인스턴스화하지 마십시오. 로드, 플러시, 체크포인트 또는 선행 쓰기 동작을 위한 수명 주기 훅을 준수하십시오. 인터페이스 기본값과 배포된 값이 다를 때는 저장소의 런타임 구성 파일을 실질적인 단일 진실 공급원으로 취급하십시오. 저장소 관련 동작의 경우: 1. 표준 구성 인터페이스를 업데이트합니다. 2. 기본 런타임 구성을 업데이트합니다. 3. 테스트 구성을 업데이트합니다. 4. 저장소 팩토리를 통해 모드를 연결합니다. 5. 수명 주기 통합을 검증합니다. 사용자 대상 구성은 문서도 함께 업데이트하고 기존 환경 변수 명명 규칙을 따르십시오. 생성되는 식별자나 엔드포인트에 영향을 주는 경우 기본 URL, 호스트 이름, 리전 및 계정 기본값, 포트 범위, 영구 저장소 루트, 컨테이너 네트워킹을 검토하십시오. 새 필드는 호환되는 방식으로 추가하고 공유 구성, 저장소, 서비스 등록을 동기화된 상태로 유지하십시오. ## 수작업 요청이 아니라 공식 SDK로 호환성 테스트하기 격리된 서비스 동작에는 단위 테스트를 사용하고, 프로토콜 처리, 영속성, 클라이언트에 표시되는 상태에는 통합 테스트를 사용하십시오. 동작이 의도적으로 상태를 유지하도록 설계된 경우에만 통합 테스트를 순서대로 실행할 수 있습니다. 구문 분석, 응답 구조, 오류, 영속성 의미 체계, URL 생성, 서비스 활성화 또는 대체 프로토콜 경로를 변경할 때는 반드시 자동화된 테스트로 다루어야 합니다. 반복 작업 중에는 먼저 집중 테스트를 실행한 다음 직접 관련된 테스트 모음을 실행하십시오. 변경 사항이 실제 SDK 동작에 영향을 줄 수 있다면 호환성 프로젝트를 사용하십시오. 원시 HTTP 요청보다 SDK 기반 어설션을 우선하고 원본 플랫폼과 의도적으로 다르게 구현한 사항은 문서화하십시오. 대체 프로토콜 경로에서 동일한 작업을 제공한다면 의미가 동등한지 테스트하십시오. 상태가 영속되는 경우 관련 저장 모드에서 로드 및 플러시 동작을 검증하십시오. 수동 요청만으로 호환성을 달성했다고 주장하지 마십시오. 자동화된 테스트 없이 동작이 변경되었다면 누락된 테스트와 이를 추가할 수 없었던 이유를 설명하십시오. ## 새 서비스를 끝까지 완성하고 릴리스 흐름은 덩달아 바꾸지 않기 서비스를 추가할 때는 컨트롤러, 서비스, 모델을 만들고, 서비스를 등록하고, 표준 구성과 테스트 구성을 추가하고, 팩토리를 통해 저장소를 연결하고, 테스트를 추가하고, 문서를 업데이트하십시오. 완료하기 전에: - 관련 테스트와 프로토콜 호환성 검사를 실행하십시오. - 사용자 지정 엔드포인트나 편의를 위한 통신 형식을 도입하지 않았는지 확인하십시오. - 구성, 저장소, 수명 주기, 문서 업데이트를 검증하십시오. - 생성된 URL과 리소스 식별자가 일관적인지 확인하십시오. - 자주 실행되는 경로에서는 로깅을 구조화하고 불필요한 소음을 줄이십시오. 풀 리퀘스트의 범위를 집중시키고, 변경이 명시되지 않았다면 기존 동작을 유지하며, 관련 없는 리팩터링을 분리하십시오. 관례적 커밋 형식과 사람만의 저자 표시를 사용하십시오. 릴리스 브랜치, 태그, 게시 워크플로를 핵심 인프라로 취급하십시오. 개발 브랜치에 병합했다는 사실만으로 안정적인 릴리스가 입증되지는 않습니다. 서비스 기능을 구현하면서 릴리스 동작을 부수적으로 변경하지 마십시오.