98 lines
5.9 KiB
Markdown
98 lines
5.9 KiB
Markdown
---
|
|
tags: [FastAPI, Architecture, OOP, Python, Analogy]
|
|
date: 2025-09-17
|
|
modified: 2025-09-17
|
|
---
|
|
|
|
# FastAPI 프로젝트 구조와 객체지향 개념 정리 (식당 비유)
|
|
|
|
이 문서는 FastAPI의 계층형 아키텍처와 객체지향 프로그래밍의 핵심 용어들을 '식당/푸드코트' 비유를 통해 정리한 내용입니다.
|
|
|
|
## 1. FastAPI 프로젝트 구조: 푸드코트와 개별 식당
|
|
|
|
마이크로서비스 아키텍처는 하나의 큰 식당이 아닌, 여러 전문 식당이 모인 '푸드코트'와 같습니다.
|
|
|
|
- **API 게이트웨이**: 푸드코트 정문 안내 데스크. 모든 손님은 여기로만 들어오며, 공통 인증, 경로 안내 등을 담당.
|
|
- **개별 서비스**: 푸드코트 내의 각 식당 (한식 코너, 중식 코너 등). 각자 독립된 주방과 창고를 가짐.
|
|
- **메시지 버스**: 푸드코트 전체에 울리는 호출 벨. 가게 간 직접 통신이 아닌, 이벤트(주문 완료 등)를 알리는 역할.
|
|
|
|
### 1.1. 개별 식당(서비스)의 내부 구조
|
|
|
|
| 파일/폴더 | 역할 (간단 설명) | 식당 비유 |
|
|
|---|---|---|
|
|
| `main.py` | 앱 실행, 라우터 등록 | 가게 정문 스위치, 메뉴판 거는 곳 |
|
|
| `api/routers/*.py` | HTTP 요청 처리, 서비스 호출 | 홀 서빙 직원 |
|
|
| `services/*.py` | 비즈니스 로직 구현 | 주방장 |
|
|
| `repositories/*.py` | 데이터베이스 접근 로직 | 창고 관리 직원 |
|
|
| `db/session.py` | DB 연결 및 세션 관리 | 창고 관리인, 창고 출입문 |
|
|
| `models/*.py` | DB 테이블 구조 정의 (ORM) | 창고 선반 설계도 (내부용) |
|
|
| `schemas/*.py` | 데이터 입출력 형식 정의 (Pydantic) | 손님 주문서 양식 (외부용) |
|
|
| `core/*.py` | 설정, 보안, 로깅 등 공통 규칙 | 가게 사장, 운영 규칙 책자 |
|
|
| `tests/*.py` | 코드 기능 자동 검증 | 시식 코너, 품질 검사 |
|
|
| `.env` | 민감 정보 보관 (비밀번호 등) | 금고 속 비밀 문서 |
|
|
|
|
### 1.2. 올바른 작업 흐름 (주문 프로세스)
|
|
|
|
> **원칙: 작업 지시서(API 요청) 없이 작업하지 않는다.**
|
|
|
|
1. **손님**, 메뉴판을 보고 **주문(API 요청)**을 한다.
|
|
2. **홀 서빙 직원(라우터)**이 **주문서 양식(스키마)**에 맞는지 확인하고 주방에 전달한다.
|
|
3. **주방장(서비스)**은 레시피(비즈니스 로직)에 따라 요리를 시작한다.
|
|
4. **창고 직원(리포지토리)**에게 **창고 설계도(모델)**를 보고 재료를 가져오라고 시킨다.
|
|
5. 요리가 완성되면 다시 홀 서빙 직원을 통해 손님에게 전달된다.
|
|
|
|
> **핵심**: 홀 서빙 직원이 직접 요리하거나, 주방장이 창고를 뒤지는 등 역할을 섞으면 가게가 엉망이 된다. 각자의 역할 분리가 중요하다.
|
|
|
|
## 2. 핵심 용어: 스키마, 모델, 객체, 인스턴스
|
|
|
|
이 용어들은 헷갈리기 쉽지만, 본질과 표현의 관계로 이해할 수 있습니다.
|
|
|
|
### 2.1. 스키마 (Schema) - 본질, 실체의 구조
|
|
|
|
- **의미**: 데이터가 어떤 모양과 규칙을 가져야 하는지에 대한 본질적인 틀, 설계.
|
|
- **비유**:
|
|
- **DB 스키마**: 아마존 창고의 실제 선반 구조, 구역 구분, 물리적 규칙. (실체)
|
|
- **API 스키마**: 테이블 오더 시스템의 전자 주문서 양식. (규칙)
|
|
- **역할**: 데이터가 제멋대로 존재하지 못하도록 형식을 강제한다.
|
|
|
|
### 2.2. 모델 (Model) - 사영(投影), 껍데기
|
|
|
|
- **의미**: 스키마라는 본질을 코드 세계에서 다루기 쉽게 표현한 것.
|
|
- **비유**:
|
|
- **DB 모델(ORM 모델)**: 아마존 창고 구조를 원격으로 보여주는 대시보드 화면.
|
|
- **API 모델(Pydantic 모델)**: 전자 주문서 양식을 코드로 표현한 클래스(틀).
|
|
- **역할**: 개발자가 코드를 통해 실체(스키마)를 다룰 수 있게 해주는 인터페이스.
|
|
|
|
> **결론**: 스키마는 본질, 모델은 그 본질을 다루기 위한 코드 상의 표현(껍데기)이다. 현업에서는 둘을 섞어 쓰기도 하지만, 이 개념을 구분하면 구조를 더 깊이 이해할 수 있다.
|
|
|
|
### 2.3. 객체(Object)와 인스턴스(Instance)
|
|
|
|
- **의미**: 클래스(설계도)를 바탕으로 메모리에 실제로 만들어진 개별 실체.
|
|
- **어원**: `Instance`는 '무리 속에 함께 서 있는 하나(one of them)', 즉 '구체적 사례'라는 뜻.
|
|
- **비유**:
|
|
- **클래스**: 김밥 레시피.
|
|
- **객체/인스턴스**: 그 레시피로 실제로 만든 김밥 한 줄.
|
|
- **차이**: 거의 동의어지만, **객체**는 존재 자체를, **인스턴스**는 '어떤 클래스의 사례'라는 관계를 강조한다.
|
|
|
|
## 3. 파이썬 클래스와 객체지향의 핵심
|
|
|
|
### 3.1. `self` - "나 자신(객체)"
|
|
|
|
- **역할**: 클래스 메서드 안에서, "현재 이 코드를 실행하고 있는 객체 자신"을 가리킨다.
|
|
- **필요성**: `self`가 없다면, 같은 클래스로 만든 여러 객체(김밥 100줄) 중 어느 객체(어떤 김밥)의 속성을 바꿔야 할지 구분할 수 없다. 객체의 '개별성'을 보장하기 위해 필수적이다.
|
|
- **동작**: `u.greet()`처럼 호출하면, 파이썬이 자동으로 `User.greet(u)`처럼 `u`를 `self` 자리에 넣어준다.
|
|
|
|
### 3.2. `cls` - "우리 가게(클래스)"
|
|
|
|
- **역할**: `@classmethod` 데코레이터가 붙은 메서드 안에서, "클래스 자신"을 가리킨다.
|
|
- **비유**: 개별 김밥(`self`)이 아닌, 김밥 가게(`cls`) 전체의 정보(e.g., 오늘 판 김밥 총개수)를 다룰 때 사용한다.
|
|
|
|
### 3.3. 클래스와 메타클래스
|
|
|
|
- **클래스도 객체다**: 파이썬에서는 `class User:` 자체도 하나의 객체(`type` 클래스의 인스턴스)이다.
|
|
- **메타클래스(Metaclass)**: '클래스를 만드는 클래스'. 파이썬의 기본 메타클래스는 `type`이다.
|
|
- **비유**:
|
|
- **인스턴스**: 김밥 한 줄
|
|
- **클래스**: 김밥 레시피
|
|
- **메타클래스**: 그 레시피를 찍어내는 공장
|