<aside> 💡

Notation

• 이탤릭은 더 큰 수준의 프로젝트에서 삭제되는 지침이다.
• 볼드는 이전 수준에는 없다가 새로 추가되는 지침이다. </aside>

토이 프로젝트 가이드

• 이 프로젝트는 도메인 주도 설계의 목적과 용어를 차용한 클린 아키텍처를 적용한다.
• Bounded Context가 1개인 경우 사용한다.
• Aggregate라는 개념조차도 불필요할 정도로 작은 구상인 경우 사용한다.

스캐폴드

• root
  • .git/
  • myproject (flat 구조)
    • domain/
      • entities.py
      • value_objects.py
      • repositories.py - infra 레이어에서 구현될 인터페이스, 반환 타입은 도메인 객체
      • gateways.py - infra 레이어에서 구현될 인터페이스, 반환 타입은 파일 상단에 명세
      • exceptions.py
    • application/
      • services.py
    • interface/
      • controllers.py
      • schema.py
      • mappers.py - 도메인 타입 ↔ Request & Response Model. 시스템의 진입점과 웹 프레임워크가 변경될 일이 거의 없으므로, 애플리케이션 계층이 컨트롤러로 값을 반환할 때 중간 DTO를 반환하는 대신, 곧바로 Response를 만들어 반환한다.
    • infra/
      • db_models.py - ORM 프레임워크로 작성한 DB 모델
      • mappers.py - ORM 프레임워크 ↔ 도메인 객체 변환. 이때 SQLAlchemy의 inspect() 같은 함수를 사용하여 repository의 return을 도메인 객체화는 등 보일러플레이트를 최소화한다.
      • repositories.py
      • gateways.py
    • utils.py
    • settings.py
    • db.py
    • main.py - 루트에서 -m package_name.main 으로 실행
  • README.md
  • pyproject.toml
  • …

기술 선택

• pydantic은 v2 이상을 사용한다.
• id 타입은 UUID 대신 ULID를 사용한다.
• 패키지와 의존성은 pyproject.toml과 uv를 통해 관리한다.
• 포매터는 ruff, 타입 체커는 ty를 사용한다.
  • tests/ 디렉토리도 ruff, ty 체킹을 빠뜨리지 않도록 주의한다.
• ORM 프레임워크은 SQLAlchemy를 사용한다.
  • SQLAlchemy는 v2 이상을 사용한다.
• Database는 Supabase를 사용한다.

모범 사례

• SQLAlchemy

  • ORM 클래스를 작성할 때 __repr__에 id와 name을 담아 디버깅을 용이하게 만든다.
  • my_field: Mapped[클래스] 와 같은 방식을 사용한다.
  • nullable 필드는 Mapped[ … | None] 과 같이 자동으로 추론되므로 명시적으로 적지 않는다.
  • 다음은 위 명세들이 반영된 모범 사례 코드다.

• FastAPI

  • Depends: Annotated 폼 - arg: Annotated[Type, Depends(dependable)] - 으로 적는다.

• 환경 변수는 애플리케이션이 정해진 런타임 입력으로만 읽고, Pydantic의 BaseSettings를 상속받아 시작 지점에서 한 번 검증한다.

  • .env는 Compose, 개발 서버 또는 로컬 실행 명령이 읽어 필요한 값을 프로세스 환경변수로 전달한다. 애플리케이션 코드가 특정 .env 파일을 직접 찾거나 불러오지 않는다.
  • 환경별 주소·키·접속 정보에는 기본값을 두지 않는다. 모든 환경에서 의미상 동일한 정책에만 코드 기본값을 둔다.

  from pydantic_settings import BaseSettings
  from pydantic import computed_field
  
  class Settings(BaseSettings):
      db_driver: str
      db_host: str
      db_port: int
      db_user: str
      db_password: str
      db_name: str
      
      @computed_field
      @property
      def DATABASE_URL(self) -> str:
          return f"{self.db_driver}://{self.db_user}:{self.db_password}@{self.db_host}:{self.db_port}/{self.db_name}"
  
  		# `.env`의 위치는 실행 도구가 알고, Settings는 프로세스 환경변수만 읽는다.
  
  settings = Settings()  # 필수 프로세스 환경변수가 없으면 시작 단계에서 에러 발생
  

• vo는 frozen=True로 설정하여 immutable하게 만든다.

  • Pydantic v2 불변 설정: ConfigDict(frozen=True)