[스나이퍼팩토리] 한컴 AI아카데미 4기 13주차 빠른에이피아이(FastAPI)

일단 매주 빠르게 진행하는 학습속도와 양을 하루 블로그로 요약하는 건 매우 어렵다 느껴집니다.

그러므로 오늘은 저변주에 이어 파이썬에서의 그래프 복습이 아닌 fastapi로 넘어가 보겠습니다.

---

🏛️ FastAPI의 탄생 비화 (역사 요약)

FastAPI는 Tiangolo(티앙골로)라는 개발자가 2018년에 세상에 내놓았습니다. 이전의 형님 격인 프레임워크들의 장점만 쏙쏙 뽑아 만든 '혼혈 천재'라고 보시면 됩니다!

시대 (Era)주인공 (Framework)특징 및 한계 (Features & Limits)

고전기	Django / Flask	대중적이지만 비동기(Async) 처리가 약했음 🐢
과도기	Hug / APIStar	빨랐지만 타입 힌트나 문서화가 조금 아쉬웠음 🤔
현대기	FastAPI	Starlette + Pydantic을 합쳐서 속도와 안정성을 다 잡음 🚀

 

---

📝 FastAPI가 역사를 새로 쓴 이유 (기호 버전)

• 🏗️ 기반(Starlette): 웹 서버의 기초 체력을 담당하는 Starlette(스탈렛)을 사용해 비동기 속도를 극강으로 끌어올렸습니다.
• 🛡️ 검증(Pydantic): 데이터 검증의 끝판왕 Pydantic(파이단틱)을 결합해 버그를 미리 잡아냅니다.
• ✍️ 표준(Type Hints): 파이썬 최신 표준인 Type Hints(타입 힌트)를 적극 도입해서 코드가 아주 깔끔해졌습니다.

---

타스 형님! FastAPI 역사를 훑었으니 이제 직접 연장을 챙겨야죠. virtualenv(버추얼엔비)는 형님의 컴퓨터라는 큰 창고 안에, 프로젝트마다 **"독립된 작은 방"**을 만드는 아주 중요한 작업입니다.

방이 섞이면 나중에 패키지 버전 때문에 머리 아픈 일이 생기거든요. 깔끔하게 환경 구축 가봅시다!

---

🏗️ 가상 환경(Virtual Environment) 구축 단계

형님, 터미널(검은 창)을 열고 순서대로만 따라 하시면 됩니다. 복잡할 것 하나도 없습니다!

단계 (Step)명령어 (Command)한글 발음 및 설명 (Description)

[Step 1]	pip install virtualenv	핍 인스톨 버추얼엔비 (도구 설치)
[Step 2]	virtualenv venv	버추얼엔비 브이엔비 (가상 환경 생성)
[Step 3]	source venv/Scripts/activate	소스 브이엔비 스크립트 액티베이트 (환경 접속)
[Step 4]	pip install fastapi uvicorn	핍 인스톨 패스트에이피아이 유비콘 (설치)

 

---

📝 가상 환경 핵심 로직 (기호 버전)

• 🏠 독립: 형님의 PC 기본 파이썬 설정은 건드리지 않고, 이 프로젝트만의 전용 공간을 만듭니다.
• 🔌 활성화: activate(액티베이트)를 해야 비로소 가상 환경 방으로 들어가는 겁니다. (터미널 앞에 (venv)가 떠야 합니다!)
• 🧹 정리: 작업이 끝나면 deactivate(디액티베이트) 한 줄로 깔끔하게 나올 수 있습니다.

---

1. virtualenv를 이용한 개발 환경 구축

  virtualenv(버추얼엔비)는 컴퓨터라는 큰 창고 안에, 프로젝트마다 **"독립된 작은 방"**을 만드는 아주 중요한 작업입니다.

방이 섞이면 나중에 패키지 버전 때문에 머리 아픈 일이 생기거든요. 깔끔하게 환경 구축 가봅시다!

실제로 24년이후 개발이 엄청 돼서 버전 맞추는데 힘들었어요!!

---

1 -1 가상 환경(Virtual Environment) 구축 단계

 터미널(검은 창)을 열고 순서대로만 따라 하시면 됩니다. 복잡할 것 하나도 없습니다! (전 vscode로 공부했습니다.)

단계 (Step)         명령어 (Command)                                    설명 (Description)

[Step 1]	mkdir todos && cd todos	todos 라는 폴더를 만들고 (cd) 그폴더로 이동
[Step 2]	python -m venv venv	파이썬에서 venv 불러와서 venv라는 폴더에 생성후  넣어라
[Step 3]	venv\Scripts\activate	환경 접속 (환경 빠져나오는건 deactivate)
[Step 4]	pip install fastapi uvicorn	유비콘 설치

 

 

1 - 2. 가상 환경 핵심 로직 (기호 버전)

• 🏠 독립: 형님의 PC 기본 파이썬 설정은 건드리지 않고, 이 프로젝트만의 전용 공간을 만듭니다.
• 🔌 활성화: activate(액티베이트)를 해야 비로소 가상 환경 방으로 들어가는 겁니다. (터미널 앞에 (venv)가 떠야 합니다!)
• 🧹 정리: 작업이 끝나면 deactivate(디액티베이트) 한 줄로 깔끔하게 나올 수 있습니다.
• pip 설치 : pip install fastapi 로 설치하고 pip freeze > requirements.txt 에 저장 다시 환경을 나갔다오면 리셋 되니까 다시 환경에 들어오면 pip install -r requirements.txt 해서 인스톨후 사용 프리즈로 저장하면 트리창에 뜹니다.

1 - 3 .윈도우(Windows) 기반 환경 가동 (명령어)

윈도우 터미널(CMD 또는 PowerShell)에서 가상 환경을 켜고 라우팅을 테스트하는 실전 명령어입니다.

1. 가상 환경 깨우기: .\venv\Scripts\activate (더 간단한 실행어도 있지만 나중에 배울께요!)
   • 성공하면 줄 맨 앞에 (venv)가 뜹니다!
2. 서버 실행하기: uvicorn main:app --post 8000 --reload (포스트 번호는 실행시 변경 가능)
   • --reload를 붙여야 코드를 고칠 때마다 서버가 자동으로 다시 돕니다.

🪟 윈도우 형님 전용 팁: 윈도우에서 경로를 다룰 때 파이썬 코드 안에서는 /(슬래시)를 쓰시는 게 정신 건강에 좋습니다. 윈도우는 보통 \(백슬래시)를 쓰지만, 웹 표준은 /이기 때문이죠!

---

2.  라우팅(Routing)

 fastAPI Routing이라는 핵심은 HTTP 요청 메서드 라고 생각이 드네요. 표준 메서드는 GET, POST, PUT,PATCH, DELETE등이 있고, 각 메서드를 코딩하면서 유사점과 실행원리를 알아갈 수 있습니다. FastAPI의 길 찾기 시스템을 만들어 가요.

2 - 1. 라우팅(Routing)의 본질: 디지털 이정표

Routing(라우팅)은 클라이언트(손님)가 보낸 요청을 서버의 어떤 함수(주방장)가 처리할지 연결해 주는 **"이정표"**입니다. 

주소를 치고 들어오면, FastAPI가 그 주소를 보고 "아, 이건 이쪽 함수가 담당이야!"라고 안내하는 과정이죠.

요소 (Element)한글 발음 (Pronunciation)역할 (Role)

Path	패스	/users/me 같이 URL 뒤에 붙는 "경로"
Operation	오퍼레이션	GET, POST 등 어떤 "동작"을 할지 결정
Decorator	데코레이터	@app.get("/") 처럼 함수 위에 붙는 "장식자"

다은은 TODO.PY 코드입니다 중간중간 메서드를 확인해보고 고민해 보아

from fastapi import APIRouter, Path, HTTPException, status, Request, Depends
from fastapi.templating import Jinja2Templates
from model import Todo, TodoItem, TodoItems
from pathlib import Path as PathlibPath

todo_router = APIRouter()

todo_list = []

# 템플릿 설정
BASE_DIR = PathlibPath(__file__).resolve().parent
template_dir = str(BASE_DIR / "templates")
templates = Jinja2Templates(directory=template_dir)

@todo_router.post("/todo", status_code=201)
async def add_todo(request: Request, todo: Todo = Depends(Todo.as_form)):
    # ID 자동 할당 로직
    todo.id = len(todo_list) + 1
    todo_list.append(todo)
    
    # 최신 버전 방식: request=request를 첫 번째 인자로 명시해야 합니다.
    return templates.TemplateResponse(
        request=request, 
        name="todo.html", 
        context={"todos": todo_list}
    )

@todo_router.get("/todo")
async def retrieve_todos(request: Request):
    # 최신 버전 방식: request 인자 전달 필수
    return templates.TemplateResponse(
        request=request, 
        name="todo.html", 
        context={"todos": todo_list}
    )

@todo_router.get("/todo/{todo_id}")
async def get_single_todo(request: Request, todo_id: int = Path(..., title="The Id of the todo to retrieve.")):
    for todo in todo_list:
        if todo.id == todo_id:
            return templates.TemplateResponse(
                request=request, 
                name="todo.html", 
                context={"todo": todo, "todos": todo_list}
            )
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="Todo with supplied ID doesn't exist",
    )

@todo_router.put("/todo/{todo_id}")
async def update_todo(todo_data: TodoItem, todo_id: int = Path(..., title="The ID of the todo to be updated.")) -> dict:
    for todo in todo_list:
        if todo.id == todo_id:
            todo.item = todo_data.item
            return {"message": "Todo updated successfully."}
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="Todo with supplied ID doesn't exist",
    )

@todo_router.delete("/todo/{todo_id}")
async def delete_single_todo(todo_id: int) -> dict:
    for index, todo in enumerate(todo_list):
        if todo.id == todo_id:
            todo_list.pop(index)
            return {"message": "Todo deleted successfully."}
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="Todo with supplied ID doesn't exist",
    )

@todo_router.delete("/todo")
async def delete_all_todo() -> dict:
    todo_list.clear()
    return {"message": "Todos deleted successfully."}

 

2 - 2. 윈도우(Windows) 기반 환경 가동 (명령어)

형님, 윈도우 터미널(CMD 또는 PowerShell)에서 가상 환경을 켜고 라우팅을 테스트하는 실전 명령어입니다.

1. 가상 환경 깨우기: .\venv\Scripts\activate (도트 백슬래시 브이엔비 스크립트 액티베이트)
   • 성공하면 줄 맨 앞에 (venv)가 뜹니다!
2. 서버 실행하기: uvicorn main:app --reload (유비콘 메인 땡땡 앱 대시대시 리로드)
   • --reload를 붙여야 코드를 고칠 때마다 서버가 자동으로 다시 돕니다.

2 - 3. 라우팅 설계의 3가지 핵심 (기호 버전)

• 📍 고정 경로: @app.get("/items") - 정확히 /items로 올 때만 반응합니다.
• 🔢 경로 매개변수: @app.get("/items/{item_id}") - 주소창에 숫자를 넣으면 함수가 그 숫자를 낚아챕니다.
• 🔍 쿼리 매개변수: /items/?skip=0&limit=10 - 주소 뒤에 붙는 상세 옵션입니다.

 

2 - 4. Swagger UI: 코드가 자동으로 만드는 마법의 문서

**Swagger(스웨거)**는 내가 짠 API 코드를 읽어서, 남들이(혹은 미래의 내가) 보고 직접 테스트까지 해볼 수 있게 만든 **"자동 반응형 설명서"**입니다.

 이건 개발자의 귀찮음을 한 방에 해결해 주는 FastAPI의 최대 복지이자 꽃입니다!

윈도우 터미널(CMD/PowerShell)에서 서버를 띄워놓고 바로 확인하는 법부터, 왜 이게 "사기급" 도구인지 진중하게 파헤쳐 보겠습니다.

항목 (Item)                 내용 (Content)                                                               한글 발음 (Pronunciation)

URL 주소	http://127.0.0.1:8000/docs	/ 독스
핵심 기능	API 명세 확인 + 실시간 테스트	트라이 잇 아웃 (Try it out)
대체 도구	http://127.0.0.1:8000/redoc	/ 리독

애플리케이션 끝에 /docs 만 뿥이면 끝 이건 실제 해봐야뎅 http://127.0.0.1:8000/docs

 

2 - 5. 윈도우 기반 스웨거 사용 로직 (기호 버전)

형님, 윈도우 터미널에서 서버를 띄운 상태여야 합니다!

• [Step 1] 🚀 서버 가동: uvicorn main:app --reload (유비콘 메인 땡땡 앱 대시대시 리로드)
• [Step 2] 🌐 브라우저 접속: 크롬이나 엣지를 열고 주소창에 localhost:8000/docs 입력!
• [Step 3] 🖱️ 테스트 시작:
  • 원하는 API 클릭 ➡️ Try it out (트라이 잇 아웃) 버튼 클릭!
  • 데이터 입력 후 ➡️ Execute (엑제큐트) 클릭!
• [Step 4] 📊 결과 확인: 밑에 Response(리스폰스) 칸에 서버가 준 답변이 실시간으로 뜹니다.

2 - 6. 왜 스웨거를 써야 하나요? (비교 분석)

특징 (Feature)          과거 방식 (Old School)                                           FastAPI + Swagger

문서 작성	워드나 엑셀에 일일이 타이핑 (극혐)	코드 짜면 0.1초 만에 자동 생성 (극락)
동작 테스트	별도 프로그램(Postman 등) 필요	웹브라우저 하나로 끝!
데이터 형식	틀려도 실행해봐야 앎	입력창에서 미리 형식을 가이드해줌

 

🪟 윈도우 형님 팁: 가끔 윈도우 보안 설정 때문에 8000번 포트가 막히는 경우가 있습니다. 그럴 땐 당황하지 마시고 uvicorn main:app --reload --port 8080 처럼 포트 번호를 살짝 바꿔서 시도해 보세요!

   /docs 들어가서 형님이 짠 API가 예쁘게 나열된 걸 보면 개발할 맛이 확 나실 겁니다.

---

 3. 템플릿팅 (jinja2)

 **Jinja2**라는 녀석을 만날 차례군요. 지금까지는 데이터만 휙휙 던졌다면, 이제는 그 데이터를 받아서 **예쁜 화면(HTML)**으로 그려주는 **Templating(템플릿팅)**의 세계입니다.

윈도우 환경에서 딱 맞춘 설치법부터, 진중하게 핵심 문법까지 싹 훑어드릴게요!

3 - 1. Jinja2: 파이썬 데이터를 HTML에 녹여내는 마법

Jinja2는 파이썬 전용 템플릿 엔진입니다. HTML 파일 안에 파이썬 변수나 반복문을 심어 넣을 수 있게 해 주죠.

구성 요소 (Element)     한글 발음 (Pronunciation)                     역할 (Role)

Templates	템플릿츠	HTML 뼈대가 담긴 파일들 (주로 templates/ 폴더)
Context	컨텍스트	파이썬에서 HTML로 넘겨주는 "데이터 보따리"
Static Files	스태틱 파일즈	CSS, 이미지 같은 변하지 않는 정적 파일들

 

3 - 2. 윈도우 기반 환경 세팅 (명령어)

Jinja2를 쓰려면 패키지를 하나 더 설치해야 합니다. 윈도우 터미널(CMD/PowerShell)을 여세요!

1. 가상 환경 켜기 (이미 켜져 있으면 패스!): .\venv\Scripts\activate (도트 백슬래시 브이엔비 스크립트 액티베이트)
2. 진자 설치: pip install jinja2 aiofiles (핍 인스톨 진자투 에이아이오파일즈)
   • FastAPI에서 HTML을 내보내려면 파일 읽기 도구(aiofiles)도 같이 있는 게 좋습니다!

3 - 3. Jinja2 핵심 문법 3 대장 (기호 버전)

HTML 파일 안에서  꼭 쓰게 될 3가지 기호입니다.

• [1] {{ variable }} (더블 컬리 브레이스 / 변수 출력)
  • 파이썬에서 넘겨준 값을 화면에 뿌릴 때 씁니다. (예: {{ name }} 형님 환영합니다!)
• [2] {% logic %} (퍼센트 싸인 / 로직 실행)
  • if문이나 for문 같은 조건/반복을 쓸 때 사용합니다. (끝날 땐 {% endif %}, {% endfor %} 필수!)
• [3] {# comment #} (샵 싸인 / 주석)
  • 메모를 남길 때 씁니다. 화면에는 안 보이죠!

다음은 예시로 만든 todo.html 입니다 jinja의 쓰임이나 형식을 찾아보아요

{% extends "home.html" %}

{% block todo_container %}
<div class="container mt-5">
    <div class="row justify-content-center">
        <div class="col-md-8">
            <div class="card shadow">
                <div class="card-header bg-primary text-white">
                    <h3 class="mb-0"><i class="fas fa-plus-circle"></i> 새 할 일 추가</h3>
                </div>
                <div class="card-body">
                    <form method="post" action="/todo">
                        <div class="input-group">
                            <input type="text" name="item" class="form-control form-control-lg" 
                                   placeholder="새로운 일을 주쇼!!" required>
                            <div class="input-group-append">
                                <button class="btn btn-success" type="submit">
                                    <i class="fas fa-save"></i> 추심
                                </button>
                            </div>
                        </div>
                    </form>
                </div>
            </div>

            <div class="mt-5">
                <h3><i class="fas fa-list-ul"></i> 할 일 목록</h3>
                <hr>
                <div class="list-group">
                    {% if todos %}
                        {% for todo in todos %}
                        <div class="list-group-item list-group-item-action d-flex justify-content-between align-items-center shadow-sm mb-2 rounded">
                            <div>
                                <span class="badge badge-secondary mr-2">ID: {{ todo.id }}</span>
                                <span class="h5 mb-0">{{ todo.item }}</span>
                            </div>
                            <div>
                                <button class="btn btn-sm btn-outline-danger" title="삭제">
                                    <i class="fas fa-trash-alt"></i>
                                </button>
                            </div>
                        </div>
                        {% endfor %}
                    {% else %}
                        <div class="text-center py-5">
                            <p class="text-muted">아직 등록된 할 일이 없습니다. 첫 번째 할 일을 추가해 보세요!</p>
                        </div>
                    {% endif %}
                </div>
            </div>
            
            {% if todos %}
            <div class="mt-3 text-right">
                <p class="text-muted small">총 {{ todos|length }}개의 할 일이 있습니다.</p>
            </div>
            {% endif %}
        </div>
    </div>
</div>
{% endblock %}

🪟 윈도우 형님 전용 팁: FastAPI 코드에서 Jinja2Templates(directory="templates")라고 폴더를 지정할 때, 윈도우 탐색기에서 templates 폴더를 프로젝트 루트(main.py가 있는 곳)에 꼭 만들어두셔야 합니다. 안 그러면 "폴더 못 찾겠다"고 징징거릴 거예요!

---

오늘은 여기까지 ~ ~

오늘 복습한 결과물입니다.

매번 공부하면서 느끼는 거지만 버전으로 인한 실행 불가는 정말 빡치게 만듭니다 제미나이를 유료화하고 싶은 맘이 하늘을 찔러요 정말 돈이 아까워서가 아니라 학습에 방해될까 봐 안 쓰고 있지만 코파일럿은 결재하고 싶네요 ㅎ

매번 매번으로 시작하지만 정말 정말 할수록 어려운 거 같아요 가르쳐 주시는 분이나 같이 학습하시는 분들 정말 부럽고 대단하십니다. 제미나이는 에러는 그냥 씹으면서 맞만 보고 가라는데 전 주식이 될 거 같아 너무 불안합니다 눈에 보이는 버전 차이는 아 ! 그러네 하고 코드를 고쳐 나가면 되지만 백엔드나 라이브러리 버전 차이는 아직까진 에이아이의 힘을 빌려 쓰고 있어요 왜 에이아이라고 졌는지 에이어르신이나 에이선생님으로 지었으면 양심에 들 부담 가는데 ㅎㅎ

오늘도 모자란 학습은 단어로 채워 보겠습니다 어원공부가 재미지거든요!

📚 단어 어원 공부 

진중하게 어원도 챙겨가야 진정한 공부죠!

1. Template (템플릿 - 견본/박판)

• 어원: Latin templum (구획/판).
• 설명: 원래는 금속이나 나무를 자를 때 쓰는 본보기를 뜻합니다. 웹에서는 미리 짜놓은 HTML 뼈대를 말하죠!

2. Render (렌더 - 표현하다/주다)

• 어원: Latin re- (다시) + dare (주다).
• 설명: 데이터를 가공해서 완성된 화면으로 다시 내놓는 과정입니다. "화면을 렌더링한다"고 표현하죠.

3. Static (스태틱 - 정적인/변하지 않는)

• 어원: Greek statikos (세우다/정지시키다).
• 설명: 움직이지 않고 가만히 서 있는 상태입니다. 서버가 매번 계산할 필요 없이 그냥 그대로 보여주는 파일(이미지 등)을 뜻합니다.

4. Swagger (스웨거 - 으스대다/뽐내며 걷다)

• 어원: 16세기 노르웨이 방언 swag (흔들거리다)에서 유래.
• 설명: "내 API 좀 봐, 멋지지?"라고 뽐내는 느낌입니다. 원래는 당당하게 걷는 모습을 뜻하는데, 지금은 API 문서의 대명사가 됐죠!

5. Execute (엑제큐트 - 실행하다/수행하다)

• 어원: 라틴어 ex- (밖으로) + sequi (따르다).
• 설명: 끝까지 따라가서 밖으로 결과를 내놓는 것, 즉 명령을 실행한다는 뜻입니다. 버튼 누르면 서버가 일을 시작하죠!

6. Documentation (다큐멘테이션 - 문서화/기록)

• 어원: 라틴어 docere (가르치다).
• 설명: 남을 가르치기 위해 남겨놓은 기록, 즉 문서입니다. 스웨거는 세상에서 가장 똑똑한 자동 문서 도구입니다.

7. Routing (라우팅 - 길 찾기/노선 정하기)

• 어원: Old French route (길/통로)에서 유래.
• 설명: 숲속에 뚫린 길을 따라가듯, 데이터가 가야 할 경로를 정해주는 행위입니다.

8. Decorator (데코레이터 - 장식자)

• 어원: Latin decorare (아름답게 꾸미다).
• 설명: 파이썬에서 @ 기호를 쓰는 녀석이죠. 함수에 특별한 기능(라우팅 기능 등)을 덧씌워 장식해 준다는 뜻입니다.

9. Operation (오퍼레이션 - 작업/운용)

• 어원: Latin operari (일하다).
• 설명: 서버가 단순히 길만 찾는 게 아니라, 데이터를 읽을지(GET) 쓸지(POST) 구체적으로 어떤 작업을 할지 정하는 것입니다.

10. Virtual (버추얼 - 가상의/실질적인)

• 어원: 라틴어 virtus (힘/덕목/효력).
• 설명: 겉모습은 진짜가 아니지만, 그 "효력"이나 "기능"은 진짜와 똑같다는 뜻입니다. 진짜 파이썬은 아니지만 진짜처럼 동작하는 가상 공간이죠!

11. Environment (인바이런먼트 - 환경/주변)

• 어원: Old French en- (안에) + viron (주위/원).
• 설명: 주위를 둥글게 둘러싸고 있는 것들을 말합니다. 개발에 필요한 모든 도구가 나를 둘러싸고 있는 환경을 뜻하죠.

12. Activate (액티베이트 - 활성화하다/작동시키다)

• 어원: 라틴어 actus (행동/움직임).
• 설명: 멈춰있는 것을 움직이게 만든다는 뜻입니다. 잠자고 있는 가상 환경을 깨워서 실제로 사용 가능한 상태로 만드는 활성화 단계입니다!

단어도 딱 한 타스만 !!

 

본 후기는 [한글과 컴퓨터 x한국생산성본부 x스나이퍼팩토리] 한컴 AI 아카데미 (B-log) 리뷰로 작성되었습니다.

#한컴 AI아카데미 #AI개발자 #AI개발자교육 #한글과 컴퓨터 #한국생산성본부 #스나이퍼팩토리 #부트캠프 #AI전문가양성 #개발자교육 #개발자취업