FastAPI를 사용한 파이썬 웹 개발(CHAPTER 1)

1. CHAPTER 1 개요

CHAPTER 1에서는 FastAPI 애플리케이션 개발을 위한 기초 환경 구성을 다룬다.

📌 주요 학습 내용

• Git 기초
• virtualenv를 이용한 가상 환경 구축
• pip을 이용한 패키지 관리
• Docker(도커) 기본 개념
• 간단한 FastAPI 애플리케이션 개발

---

2. 개발 환경 및 사용 도구

• 운영체제: Windows
• 터미널: Git Bash
• 언어: Python
• 프레임워크: FastAPI
• 서버: Uvicorn (ASGI)
• 버전 관리: Git
• 컨테이너: Docker

프로젝트 폴더는 다음 경로에 생성했다.

 

C:/Users/test/ch01/todos

FastAPI =  애플리케이션 구축을 위해 필요한 프레임워크

               =  빠르고 가벼우며 플라스크(Flask)나 장고(Django)와 같은 프레임워크보다 배우기 쉽다.

 

1.1 Git 기초

Git: 버전 관리 시스템으로, 개발자가 파일을 기록(저장) 및 추적하거나 이전 버전으로 복원할 수 있게 해준다.

     : 운영체제에 상관없이 설치 가능한 탈중앙화 방식의 가벼운 도구

 

Git은 다음의 두 가지 버전을 제공한다.

1. 명령줄 인터페이스(command-line interface(CLI))
2. 그래픽 사용자 인터페이스(graphical user interface(GUI))

Git을 실행하려면 먼저 파일을 관리할 폴더를 초기화해야 한다. 폴더를 Git으로 초기화 하면 해당 폴더 내의 모든 파일을 추적하고 관리할 수 있다(관리 대상에서 제외시킬 수도 있다). 

 

새로운 Git 저장소(repository)를 초기화 

: $ git init

 

파일을 추적하려면 해당 파일을 저장소에 추가하고 커밋(commit)해야 한다.

Git 커밋을 통해 시간의 흐름에 따른 파일 변경 내용을 추적할 수 있다. 

ex) 한 시간 전에 커밋한 파일과 현재 버전의 파일을 비교할 수 있다.

 

다음과 같이 하나의 파일을 실제로 커밋해보자.

$ git add hello.txt

$ git commit -m "Initial commit"

 

만약 파일이 변경되면 다음 명령을 사용해 파일 상태를 추적할 수 있다.

$ git status

 

파일의 변경 내용을 보려면 다음 명령을 실행하면 된다. 어떤 내용이 추가 및 삭제됐는지 알 수 있다.

$ git diff hello.txt

 

모든 폴더에 .gitignore 파일을 추가하는 것은 좋은 습관이다. .gitignore 파일에는 Git의 관리 대상에서 제외할 파일이나 폴더를 지정할 수 있다.

ex) .env 같은 환경 파일을 제외하고 싶다면 .gitignore 파일에 추가하면 된다.

 

다음 명령을 사용해서 .gitignore 파일을 만들어보자.

$ touch .gitignore                  cf) 파일을 생성할 때에는 touch를 사용한다!

ex) (앞서 언급한) .env파일을 Git의 관리 대상에서 제외하려면 다음과 같이 .gitignore 파일에 추가하면 된다.

$ echo ".env" >> .gitignore

 

일반적으로 다음과 같은 파일을 .gitignore에 추가한다.

• 환경 파일(.env)
• virtualenv 폴더(env, venv)
• IDE 메타데이터 폴더(.vscode, .idea)

브랜치(branch)는 개발자가 서로 다른 애플리케이션 기능이나 버그 등을 개별적으로 작업할 수 있게 해준다. 또한 개별 브랜치를 메인 브랜치에 병합할 수 있다. 브랜치 구조는 모든 애플리케이션에서 사용 가능하다. 핵심 브랜치를 메인브랜치(또는 마스터 브랜치)라고 하며 이 브랜치를 기준으로 다른 브랜치를 만들 수 있다. 이때  git checkout -b newbranch 명령을 사용한다.

 

다음은 새로운 브랜치를 만드는 과정이다.

$ git checkout -b hello-python-branch

↘이 명령은 기존 브랜치를 기준으로 hello-python-branch라는 새로운 브랜치를 만들고, 만들어진 브랜치를 활성(active)브랜치로설정한다.

다음 명령을 사용하면 활성 브랜치를 메인 브랜치로 다시 변경할 수 있다.

$ git checkout main

↘이 명령은 메인 브랜치를 활성 브랜치로 설정한다.

$ git checkout -b newbranch

↘이 명령은 현재 브랜치에서 newbranch라는 이름의 새 브랜치를 만든 다음 활성 브랜치로 설정한

    다.

 

1.2 virtualenv를 사용한 개발 환경 구축

일반적으로 파이썬 애플리케이션은 가상 환경(virtual environment)을 사용해 개발된다. 가상 환경에서 애플리케이션을 개발하면 특정 패키지를 시스템에 전역(global)으로 설치하지 않아도 된다. 또한 서로 다른 애플리케이션을 동시에 개발할 때 발생할 수 있는 충돌을 피할 수 있다. 가상환경은 독립된 환경이다.

 

파이썬을 설치하면 기본으로 표준 라이브러리의 venv 모듈이 함께 설치되는데 이 모듈이 가상 환경을 생성한다.

다음 명령을 사용하여 todos라는 폴더를 만들고 이 폴더 안에 가상 환경을 생성해보자.

$ mkdir todos && cd todos (todos 폴더 생성 + todos로 이동)

$ python -m venv venv (python 환경으로 설정)

↘venv 모듈은 가상 환경을 설치할 폴더명을 인수로 지정한다.

   (즉, 두 번째 venv는 가상 환경으로 사용할 폴더명이다.)

   생성된 가상 환경 폴더(venv)에는 파이썬 인터프리터가 설치된 lib폴더와 가상 환경 내에서 상호 작용(가상 환경 활성화/비활성화 등)이 필요한 파일을 저장하는 Scripts(or bin) 폴더가 있다.

 

가상 환경을 활성화하는 명령은 다음과 같다.

$ source venv/Scripts/activate

*가상 환경이 활성화되면 해당 환경 내에 있는 파이썬 인터프리터와 패키지를 기본으로 사용한다.*

가상 환경이 활성화되었으므로 (venv)라는 가상 환경 폴더명이 표시된다.

 

cf) 앞서 생성한 폴더로 이동 : $ cd

 

 

가상 환경을 비활성화하는 명령은 다음과 같다.

$ deactivate

 

가상 환경이 비활성화되었으므로 (venv)라는 가상 환경 폴더명이 사라졌다.

 

 

1.3 pip을 사용한 패키지 관리

FastAPI 애플리케이션은 패키지를 기반으로 만들어진다. 따라서 패키지를 설치하거나 삭제하고 업데이트할 수 있도록 패키지 관리 방법을 잘 알고 있어야 한다.

 

pip은 python install package의 약자로, 파이썬 패키지 관리 도구이다.

pip은 파이썬 설치 시 함께 설치된다. 다음 명령을 사용해 pip이 설치됐는지 확인할 수 있다.

$ python(3) -m pip list

 

명령을 실행하면 아래와 같이 설치된 패키지 목록이 표시된다. 목록에 pip이 포함되어 있다면 계속해서 실습을 진행할 수 있다.

pip으로 fastapi 패키지를 설치하려면 다음 명령을 사용하면 된다. 

$ pip install fastapi 

 

패키지를 제거하려면 다음 명령을 실행하면 된다.

$ pip uninstall fastapi

 

현재 프로젝트에 설치된 모든 패키지 목록을 파일로 저장하려면 다음과 같이 freeze 명령과 > 연산자를 사용하면 된다.

: 현재 설치된 패키지 목록을 requirements.txt에 저장한다

$ pip freeze > requirements.txt

 

 

 

> 연산자는 왼쪽 명령의 실행 결과를 오른쪽 파일에 저장한다. 여기서는 pip freeze가 반환하는 패키지 목록이 requirements.txt 파일에 저장된다.

 

1.4 Docker(도커) 기본 개념

오늘날 애플리케이션은 여러 계층(데이터베이스, 웹 서버 등)으로 구성된다. 따라서 애플리케이션을 쉽게 배포하려면 모든 구성 요소를 하나로 묶어야 한다. 여기서는 도커를 사용해 애플리케이션 계층을 단일 이미지로 컨테이너화한다. 이렇게 하면 애플리케이션을 클라우드나 로컬에 쉽게 배포할 수 있다.

 

*도커를 설치하려면 먼저 아래의 웹 사이트에서 도커 데스크톱을 다운로드해야 한다.*

https://docs.docker.com/get-docker/

 

도커파일에는 애플리케이션 이미지의 구성 방법을 정의한다.

이 도커파일을 사용해서 getting_started라는 태그를 가진 애플리케이션 이미지를 생성해보자.

$ docker build -t getting_started .

 

도커파일이 현재 디렉터리에 없다면 명령 실행 시 다음과 같이 경로를 명시해야 한다.

$ docker build -t getting_started ch01/Dockerfile

 

컨테이너 이미지가 생성됐다면 다음 명령으로 실행하면 된다.

$ docker run getting-started

 

+ 한마디로, 도커는 간단하게 컨테이너를 생성하고 관리하는 도구다.  여기서는 아주 기초적인 명령만 살펴보았다.

 

1.5 간단한 FastAPI 애플리케이션 개발

 

앞서 만든 todos 폴더에 애플리케이션에 필요한 의존 라이브러리와 패키지를 설치한다. 필요한 라이브러리는 다음과 같다.

• fastapi : 애플리케이션을 구축하기 위해 필요한 프레임워크
• uvicorn : 애플리케이션을 실행하기 위한 비동기(asynchronous)방식 서버 게이트웨이 인터페이스(ASGI)

 

uvicorn 

• 매우 가벼운 ASGI 서버
• fastapi framework 만으로는 웹 개발 할 수 X, ASGI와 호환되는 웹 서버가 필요 O
• 비동기 방식이 가능한 python web server framework(FastAPI가 대표적)와 application 간의 표준 interface를 제공함
• 배포에 별도의 준비가 필요 X

 

설치에 앞서 프로젝트 폴더(todos)에서 다음 명령을 실행해 개발 환경(가상 환경)을 활성화한다.

$ source venv/Scripts/activate

 

다음 명령을 사용해서 의존 라이브러리를 설치한다.

(venv)$ pip install fastapi uvicorn

 

cf) fastapi와 uvicorn 각각 설치:

(venv)$ pip install fastapi

(venv)$ pip install uvicorn

 

이제 api.py라는 파일을 만들어 FastAPI의 새 인스턴스를 생성한다.

$ touch api.py       cf) 파일을 생성할 때에는 touch를 사용한다!

from fastapi import FastAPI

app = FastAPI()

 

app 변수에 FastAPI를 초기화해서 라우트(route)를 생성할 수 있다.

 

웰컴(welcome) 라우트를 만들어보자.

 

우선 데코레이터(decorator)를 사용해 처리 유형을 정의하고 라우트가 호출됐을 때 실행할 처리를 함수로 작성한다. 다음 코드는 GET 유형의 요청을 받아서 환영 메시지를 반환하는 "/" 라우트를 만든다.

@app.get("/")
async def welcome() -> dict:
      return {
          "message": "Hello World"
     }

 

이제 uvicorn을 사용해 애플리케이션을 시작해보자.
(venv) $ uvicorn api:app --port 8000 --reload

 

uvicorn을 실행할 때 지정하는 인수는 다음과 같다.

• file:instance : FastAPI 인스턴스가 존재하는 파이썬 파일과 FastAPI 인스턴스를 가지고 있는 변수를 지정한다.
• --port PORT : 애플리케이션에 접속할 수 있는 포트 번호를 지정한다.
• --reload : 선택적 인수로, 파일이 변경될 때마다 애플리케이션을 재시작한다.

실행 결과는 다음과 같다.

이제 애플리케이션이 제대로 실행되고 있는지 테스트해보자. 새 터미널 창을 열고 curl을 사용해 GET 요청을 보낸다.
$ curl http://localhost:8000/

그러면 다음과 같은 환영 메시지를 콘솔에서 볼 수 있다.
{
   "message": "Hello World"
}

 

또는 

 

<최종 파일>(참고)

 

또는

 

 

[느낀점]

이번 CHAPTER 1 학습을 통해 FastAPI의 기본 구조와 API 동작 흐름을 이해할 수 있었다. 개발 환경 구축부터 간단한 API 구현까지 직접 경험하면서, 서버가 요청을 처리하고 응답을 반환하는 전체 과정을 자연스럽게 익힐 수 있었다. 아직은 기초 단계이지만, FastAPI를 활용한 백엔드 개발에 대한 막연한 어려움이 줄었고 , 이후 더 복잡한 기능을 구현해 나갈 수 있는 기반을 마련했다는 점에서 의미 있는 학습이었다.

 

🌱 배운 점

• 백엔드 개발은 코드 작성 이전에 환경 구성부터 중요하다는 것을 알게 되었다.
• Git, 가상 환경, 패키지 관리는 선택이 아니라 필수 요소임을 이해했다.
• FastAPI는 설정이 간단하면서도 빠르게 API를 실행할 수 있어 학습 진입 장벽이 낮다.
• 서버 실행과 요청 테스트를 직접 해보며 API 동작 흐름이 명확해졌다.

---

✨ 정리

이번 CHAPTER 1을 통해 FastAPI 개발을 위한 기본 환경과 도구들을 직접 설정하고 실행해보았다.
아직은 간단한 API 수준이지만, 서버가 요청을 받고 응답을 반환하는 전체 흐름을 이해할 수 있었고,
백엔드 개발에 대한 막연한 부담도 많이 줄어들었다.

이 챕터는 이후 라우팅, 데이터 검증, CRUD 구현으로 이어지는 학습을 위한 탄탄한 기초 단계였으며,
FastAPI 기반 백엔드 개발을 계속 확장해 나갈 수 있는 출발점이 되었다.