ivada-infra/DOCS
3
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity
DOCS/ideas/250917_FastAPI_구조와_객체지향_개념_정리.md
happybell80 c172c616b5 docs: skill-slack 배포 지침서 간소화 (349줄→95줄) 
- 로빙 철학(스킬=도구, 판단 금지) 명확화
- thread_ts 버그 및 계정 이전 이슈 정리
- 핵심 배포 정보만 유지
2025-09-19 21:12:01 +09:00

8.4 KiB
Raw Blame History

tags, date, modified
tags date modified
FastAPI
Architecture
OOP
Python
Analogy
Roving
2025-09-17 2025-09-19

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이다.
  • 비유:
    • 인스턴스: 김밥 한 줄
    • 클래스: 김밥 레시피
    • 메타클래스: 그 레시피를 찍어내는 공장

4. 로빙 프로젝트 특수 아키텍처: 인체 비유

로빙 프로젝트는 일반적인 마이크로서비스와 달리 중앙 집중식 판단 구조를 가집니다. 이는 인체의 신경계와 유사합니다.

4.1 로빙 = 디지털 생명체

감각기관 (입력층):

  • Gateway: 모든 감각 수용체 - 외부 자극(Slack 이벤트, HTTP 요청 등) 통합 수신

뇌 (중앙 처리):

  • rb8001 (대뇌): 의식, 판단, 오케스트레이션
  • PostgreSQL (해마): 장기기억 저장소
  • ChromaDB (연합야): 연상 기억, 의미 검색
  • Redis (작업기억): 단기 캐시, 즉각 반응
  • auth-server (시상하부): 신원 확인, 접근 제어

운동기관 (출력층):

  • skill-slack: Slack 메시지 전송 (입/성대)
  • skill-email: 이메일 발송 (편지 쓰는 손)
  • skill-calendar: 일정 관리 (계획하는 손)
  • skill-file: 파일 조작 (물건 다루는 손)

4.2 감각-운동 피드백 루프

인체처럼 로빙도 행동하면서 동시에 감각 피드백을 받습니다:

1차 루프 (외부 자극-반응):

외부 → Gateway(감각) → rb8001(뇌) → Skills(운동) → 외부

2차 루프 (고유감각 피드백):

Skills → 실행 결과 → rb8001 → 다음 행동 조정

구체적 피드백 예시:

  • skill-slack: 메시지 전송 → message_ts 반환 (위치 감각)
  • skill-email: 메일 발송 → 발송 성공/실패 (촉각)
  • skill-file: 파일 생성 → 파일 크기/권한 (압력 감각)

4.3 일반 푸드코트 vs 로빙 푸드코트

일반 푸드코트 (마이크로서비스):

  • 각 가게가 독립적으로 요리+서빙
  • 가게 간 최소한의 통신

로빙 푸드코트 (중앙 집중식):

  • rb8001: 중앙 통합 조리대 - 모든 요리 결정과 조리
  • skill-email: 재료 공급점 - 메일 데이터만 제공
  • skill-slack: 배달 전문점 - 완성 요리를 Slack 도시락으로 포장
  • skill-rag: 재료 창고 - 문서 보관/검색만

핵심 차이:

  • 일반: 각 서비스가 판단+실행
  • 로빙: rb8001만 판단, 스킬은 단순 실행

이러한 구조는 로빙의 베이즈 철학과 일치합니다 - 모든 증거(Evidence)를 중앙에서 종합하여 일관된 사후확률(Posterior)을 도출하고, 이를 각 기관(스킬)이 충실히 실행합니다.