본문으로 건너뛰기

한눈에 보기

A. 프로젝트 구성과 실행 흐름​

  • A1. Adapter와 upstream: 외부 서비스, 외부 라이브러리, 다른 저장소의 코드와 닿는 부분을 adapter 한 곳에 모으고, 가져온 외부 코드는 고치지 않습니다.
  • A2. Lazy import: 일부 기능에서만 필요한 모듈은 그 기능을 실행하는 함수 안에서 import해서, 그 모듈이 없는 환경에서도 나머지 기능이 돌게 합니다.
  • A3. 단일 진입점과 명령 표: 모든 실행, 하위 프로세스까지 하나의 진입점과 명령 표를 거치게 해서 import 경로와 환경을 하나로 맞춥니다.
  • A4. 실행 전 전체 검증: 할 일 전체를 plan으로 만들고 모두 검증한 뒤에 첫 단계를 실행합니다.
  • A5. 소스 파일 기준 경로: 경로를 작업 디렉터리가 아니라 소스 파일 위치에서 계산해서, 어디서 실행해도 같은 파일을 가리키게 합니다.
  • A6. 저장소 문서의 역할 분담: 문서마다 맡는 내용을 나누고, 코드의 설정 표와 문서의 표를 맞춰 둡니다.

B. 인터페이스와 객체 설계​

  • B1. ABC와 Protocol: interface와 구현을 다른 파일에 두고, 상속은 한두 단계에서 끝냅니다.
  • B2. Template method와 hook: 하위 클래스가 채우는 build()와 바깥에서 부르는 create()를 나눠서, 확장 코드의 실수를 경계에서 잡습니다.
  • B3. Registry: 구현을 이름으로 등록하고 이름으로 꺼내 씁니다. 등록할 때 이름 중복과 추상 클래스를 거부합니다.
  • B4. Mixin: 외부 클래스를 고치지 않고, 함께 상속하는 작은 클래스로 기능을 덧붙입니다.
  • B5. Proxy: 객체를 감싸서 일부 메서드만 바꾸고 나머지는 원래 객체에 넘깁니다.
  • B6. Callable: 실행할 동작을 함수, lambda, 호출 가능한 객체로 전달받습니다.
  • B7. Context와 상태 객체: 단계 사이에 넘기는 값 묶음에서 입력과, 실행 중 바뀌는 상태를 나눠 담습니다.

C. decorator와 언어 기능​

  • C1. Dataclass: 바뀌지 않는 값은 frozen dataclass, 바뀌는 상태는 일반 dataclass로 만듭니다.
  • C2. NamedTuple: 풀어서 받는 작은 반환값과 JSON으로 내보낼 작은 레코드에 씁니다.
  • C3. Property: 파생 값, 지연 로드, 추상 속성, 상태를 확인해야 하는 값의 네 경우에 씁니다.
  • C4. Classmethod: 이름 있는 생성자, 객체 없이 하는 검사, 등록 decorator에 씁니다.
  • C5. Staticmethod: 그 클래스 안에서만 쓰는 private helper에만 씁니다.
  • C6. Abstract method: 필수 기능은 abstract method로, 일부 구현만 지원하는 기능은 이유를 밝히는 오류로 둡니다.
  • C7. Context manager: 한 함수 안에서 상태를 바꾸고 복원할 때는 @contextmanager, 객체의 자원 사용과 정리를 관리할 때는 __enter__/__exit__를 씁니다.
  • C8. Cache: 성공한 외부 조회만 기억하게 해서 같은 조회를 한 번만 합니다.
  • C9 __init_subclass__: 하위 클래스를 정의하는 순간 자동으로 등록합니다.
  • C10. Mapping: 읽기 전용 표를 세 메서드만으로 만듭니다.
  • C11. BaseException: 외부 코드의 except Exception에 잡히면 안 되는 신호를 만듭니다.
  • C12. 작은 언어 기능: walrus, keyword-only argument, zip(strict=True), sentinel 같은 기법을 모았습니다.

D. 실패에 대비하는 방법​

E. 설계할 때 주의할 점​

실패와 정상 결과의 구분, 입력 검증, 상태 관리, 공통 설정, 공개 interface를 설계할 때의 주의점과 판단 기준을 정리했습니다.