onejaejae/code-standards

Code Standards

코드 구현 및 테스트 작성 시 참조하는 표준입니다.

---

파일 구조

src/
├── main.py                          # FastAPI 앱 팩토리
├── settings.py                      # Pydantic 설정 관리
├── containers.py                    # DI 컨테이너 (dependency-injector)
├── database.py                      # DB 세션 관리 (async)
│
├── controllers/                     # HTTP 라우트 핸들러
│   └── {domain}.py                 # {domain}_router (복수형)
│
├── services/                        # 비즈니스 로직
│   └── {domain}_service.py         # {Domain}Service (단수형)
│
├── repositories/                    # 데이터 접근 계층
│   └── {domain}_repository.py      # {Domain}Repository (단수형)
│
├── models/                          # SQLAlchemy ORM 모델
│   ├── base.py                     # BaseModel, TimestampMixin
│   └── {domain}.py                 # {Domain} (테이블 모델)
│
├── schemas/                         # Pydantic DTO
│   ├── common.py                   # CommonResponse, Meta
│   ├── error.py                    # ErrorResponse, ErrorSchema
│   └── {domain}.py                 # {Domain}Create, {Domain}Response
│
├── exceptions/                      # 예외 정의
│   ├── common.py                   # 기본 예외 클래스 계층
│   └── {domain}.py                 # 도메인 예외
│
├── enums/                           # 열거형 정의
│   └── {domain}.py                 # Enum 정의
│
└── utils/                           # 유틸리티
    └── auth.py                     # JWT 인증 (RequireAuth, CurrentUserId)

tests/
├── conftest.py                      # 공통 fixtures
├── controllers/
│   └── test_{domain}_controller.py
├── services/
│   └── test_{domain}_service.py
└── repositories/
    └── test_{domain}_repository.py

네이밍 컨벤션

| 유형 | 컨벤션 | 예시 | |------|--------|------| | 파일명 | snake_case | research_repository.py | | 클래스 | PascalCase | ResearchRepository | | 함수/메서드 | snake_case | get_or_throw | | 변수 | snake_case | research_id | | 상수 | UPPER_SNAKE | MAX_RETRY_COUNT | | 라우터 | snake_case + 복수 | research_router | | 라우트 경로 | kebab-case | /api/researches |

계층별 네이밍

| 계층 | 파일명 | 클래스명 | 변수명 | |------|--------|----------|--------| | Controller | research.py | - | research_router | | Service | research_service.py | ResearchService | research_service | | Repository | research_repository.py | ResearchRepository | research_repository | | Model | research.py | Research | research | | Schema | research.py | ResearchCreate, ResearchResponse | - | | Exception | research.py | ResearchNotFoundException | - |

---

테스트 패턴

테스트 케이스 분류

| 유형 | 설명 | 예시 | |------|------|------| | Happy Path | 정상 동작 | 유효한 데이터로 생성 성공 | | Edge Cases | 경계값 | 빈 문자열, 최대 길이 | | Error Cases | 예상 실패 | 존재하지 않는 ID, 중복 데이터 |

테스트 구조 (AAA 패턴)

class TestResearchService:
    @pytest.fixture(scope="function")
    def mock_research_repository(self) -> MagicMock:
        return MagicMock(spec=ResearchRepository)

    @pytest.fixture(scope="function")
    def service(self, mock_research_repository) -> ResearchService:
        return ResearchService(
            research_repository=mock_research_repository,
        )

    @pytest.mark.asyncio
    async def test_get(
        self,
        service,
        mock_research_repository,
        mock_async_session,
    ):
        # Arrange
        research_id = 1
        mock_research = Research(
            id=research_id,
            chat_session_id=uuid4(),
            title="Test Research",
            project_id=1,
            created_by_id=1,
            created_at=datetime.now(),
            updated_at=datetime.now(),
        )
        mock_research_repository.get_or_throw.return_value = mock_research

        # Act
        result = await service.get(research_id, session=mock_async_session)

        # Assert
        assert isinstance(result, ResearchResponse)
        assert result.id == research_id
        assert result.title == "Test Research"
        mock_research_repository.get_or_throw.assert_called_once_with(
            research_id, session=mock_async_session
        )

    @pytest.mark.asyncio
    async def test_get_not_found(
        self,
        service,
        mock_research_repository,
        mock_async_session,
    ):
        # Arrange
        mock_research_repository.get_or_throw.side_effect = ResearchNotFoundException()

        # Act & Assert
        with pytest.raises(ResearchNotFoundException):
            await service.get(1, session=mock_async_session)

모킹 패턴

# tests/conftest.py
@pytest.fixture(scope="session")
def mock_async_session() -> MagicMock:
    return MagicMock(spec=AsyncSession)

@pytest.fixture(scope="session")
def mock_current_user_id() -> int:
    return 1

@pytest.fixture(scope="session")
def app(
    mock_async_session, mock_async_connection, mock_current_user_id
) -> Generator[FastAPI, Any, None]:
    from src.main import create_app
    _app = create_app()

    # 데이터베이스 관련 mocking
    _app.dependency_overrides[database.get_async_session] = lambda: mock_async_session
    _app.dependency_overrides[require_auth] = lambda: None
    _app.dependency_overrides[get_current_user_id] = lambda: mock_current_user_id

    yield _app

@pytest.fixture(autouse=True)
def mock_services(app) -> Generator[dict[str, MagicMock], None, None]:
    container = app.container
    service_specs = {
        "research_service": ResearchService,
    }
    mocks = {}

    for name, cls in service_specs.items():
        mock = MagicMock(spec=cls)
        getattr(container, name).override(mock)
        mocks[name] = mock

    yield mocks

    for name in service_specs:
        getattr(container, name).reset_override()

Controller 테스트 패턴

class TestResearchController:
    TEST_API_PREFIX = "/api/researches"

    @pytest.fixture
    def mock_research_service(self, mock_services):
        return mock_services["research_service"]

    def test_get_research(self, test_client, mock_research_service, mock_async_session):
        # Arrange
        research_id = 1
        mock_research = ResearchResponse(
            id=research_id,
            chat_session_id=uuid4(),
            title="Test Research",
            project_id=1,
            created_by_id=1,
            updated_by_id=1,
            created_at=datetime.now(),
            updated_at=datetime.now(),
        )
        mock_research_service.get.return_value = mock_research

        # Act
        response = test_client.get(f"{self.TEST_API_PREFIX}/{research_id}")

        # Assert
        assert response.status_code == status.HTTP_200_OK
        mock_research_service.get.assert_called_once_with(
            research_id, session=mock_async_session
        )

Repository 테스트 패턴

Repository 테스트는 실제 DB를 사용하는 통합 테스트입니다.

class TestResearchRepository:
    @pytest.fixture
    def repository(self):
        return ResearchRepository()

    @pytest.fixture
    async def test_research(self, repository, async_session):
        """테스트용 데이터 생성"""
        return await repository.create(
            title="테스트 연구",
            project_id=1,
            created_by_id=1,
            session=async_session,
        )

    @pytest.mark.asyncio
    async def test_create(self, repository, async_session):
        # Arrange
        title = "새로운 연구"

        # Act
        result = await repository.create(title=title, ..., session=async_session)

        # Assert
        assert result.title == title

필터 테스트 원칙

필터 테스트는 포함될 데이터 + 제외될 데이터 모두 검증:

@pytest.mark.asyncio
async def test_get_list_filter(self, repository, async_session):
    # Arrange - 포함될 데이터 + 제외될 데이터
    included = await repository.create(project_id=10, ...)  # 포함
    excluded = await repository.create(project_id=20, ...)  # 제외

    # Act
    items, _ = await repository.get_list(project_id=10, ...)

    # Assert - 양쪽 모두 검증
    result_ids = [item.id for item in items]
    assert included.id in result_ids      # 포함 확인
    assert excluded.id not in result_ids  # 제외 확인

정렬 테스트 (명시적 시간값)

PostgreSQL now()는 트랜잭션 시작 시간을 반환하므로 명시적 값 사용:

@pytest.mark.asyncio
async def test_sort_by_created_at(self, repository, async_session):
    # Arrange - 명시적 시간값
    older = Research(created_at=datetime(2024, 1, 1), ...)
    newer = Research(created_at=datetime(2024, 1, 2), ...)
    async_session.add_all([older, newer])
    await async_session.flush()

    # Act
    items, _ = await repository.get_list(sort="-created_at", ...)

    # Assert
    assert items[0].id == newer.id  # 최신순

---

커밋 컨벤션

형식

CLAUDE.md의 Conventional Commits 기반:

타입(적용범위): task_id 설명 #버전태그

타입

| Type | Description | |------|-------------| | feat | 기능 추가 | | fix | 버그 수정 | | improve | 현재 구현체 개선 | | refactor | 내부 리팩토링 | | docs | 문서 | | test | 테스트 코드 | | style | 포맷팅 | | chore | 기타 수정 | | package | 패키지 업데이트 |

버전 태그

| 태그 | 설명 | 버전 변화 | |------|------|----------| | #patch | 버그 수정 | 1.0.0 -> 1.0.1 (기본값) | | #minor | 새로운 기능 | 1.0.0 -> 1.1.0 | | #major | 호환성 깨지는 변경 | 1.0.0 -> 2.0.0 |

규칙

• Conventional Commits 형식 사용 (CLAUDE.md 참조)
• task_id는 Notion task ID (DPT-XXXXX)
• 버전 태그 필수
• PR 번호는 GitHub에서 자동 추가됨

예시

feat(research): DPT-10246 연구 지원 API 구현 #minor
fix(chat): DPT-10309 SSE 스트리밍 모드 구분 #patch
[HOTFIX] 메세지 테이블 마이그레이션 트랜잭션 분리 #patch

특수 커밋

• [HOTFIX]: 긴급 패치 (Conventional Commits 형식 예외)

---

타입 힌팅 스타일

Python 3.13+ 스타일

# 권장 (Python 3.13+)
def get(self, id: int) -> Research | None:
    pass

# 비권장 (Optional 사용)
def get(self, id: int) -> Optional[Research]:
    pass

keyword-only 인자

# Repository/Service 메서드
async def create(
    self,
    *,  # 이 아래는 모두 키워드 전용
    title: str,
    project_id: int | None,
    created_by_id: int,
    session: AsyncSession,
) -> Research:
    pass

Annotated DI 패턴

# Controller 의존성 주입
async def get_research(
    _: RequireAuth,
    research_id: Annotated[int, Path(title="연구 ID")],
    session: Annotated[AsyncSession, Depends(database.get_async_session)],
    service: Annotated[ResearchService, Depends(Provide[Container.research_service])],
) -> CommonResponse[ResearchResponse, Meta]:
    pass

---

Quick Reference

테스트 케이스 필수 항목

class TestServiceName:
    @pytest.mark.asyncio
    async def test_method_success(self, ...):
        """Happy Path - 정상 동작"""
        pass

    @pytest.mark.asyncio
    async def test_method_not_found(self, ...):
        """Error Case - 리소스 없음"""
        pass

커밋 메시지 템플릿

feat(domain): DPT-XXXXX 기능 설명 #minor
fix(domain): DPT-XXXXX 버그 수정 설명 #patch
[HOTFIX] 긴급 수정 설명 #patch

체크리스트

• [ ] 파일이 계층별 디렉토리에 정리되었는가? (controllers/, services/, repositories/)
• [ ] 네이밍이 컨벤션을 따르는가? (snake_case 파일, PascalCase 클래스)
• [ ] 테스트가 Happy/Edge/Error 케이스를 커버하는가?
• [ ] 커밋 메시지가 타입(적용범위): task_id 설명 #버전태그 형식인가?
• [ ] @pytest.mark.asyncio 데코레이터가 있는가?
• [ ] AAA 패턴 (Arrange-Act-Assert)을 따르는가?
• [ ] MagicMock(spec=ClassName)으로 타입 검증하는가?