FastAPI 설치 및 프로젝트 생성

1. 프로젝트 폴더 생성 및 가상환경 설정

가상환경을 사용하면 프로젝트마다 독립된 개발 환경을 만들 수 있습니다. A 프로젝트는 FastAPI 0.115가 필요하고 B 프로젝트는 0.141이 필요할 때, 가상환경이 없으면 둘 중 하나는 반드시 깨집니다. 프로젝트마다 상자를 하나씩 만들어 그 안에만 패키지를 설치한다고 생각하시면 됩니다. 프로젝트 간 충돌을 방지하고, 필요한 패키지만 설치하여 시스템을 깔끔하게 유지할 수 있으며, 프로젝트를 다른 환경으로 쉽게 이동할 수 있습니다.

이제 직접 해볼 차례입니다. VS Code에서 실습을 진행할 상위 폴더를 하나 열어주세요. 이 책의 모든 실습은 이 폴더 아래에 절별로 폴더를 만들어 진행합니다. 아래의 단계를 따라 프로젝트 폴더를 만들고 가상환경을 설정해 봅시다.

VS Code에서 파일(File) > 폴더 열기(Open Folder) 를 선택하고 FastAPI 작업을 할 폴더를 선택합니다.
VS Code에서 터미널을 엽니다. (Ctrl + ` 또는 Terminal > New Terminal)
Windows는 터미널이 열리면 오른쪽 상단에 '+' 버튼 옆에 있는 아래쪽 화살표(▼)를 클릭합니다. 드롭다운 메뉴에서 PowerShell을 선택합니다. Mac은 기본으로 열리는 Terminal을 사용하셔도 좋습니다. 이 터미널을 통해 명령어를 실행할 것입니다.
터미널에서 다음 명령어를 실행하여 프로젝트 폴더를 생성(mkdir 명령)하고 이동(cd명령)합니다.
```
mkdir 01_4_basic
cd 01_4_basic
```
다음 명령어를 실행하여 가상환경을 생성합니다. python -m venv [가상환경이름] 형식입니다.
- python: Python 인터프리터를 실행합니다. macOS/Linux에서는 python3를 사용합니다.
- -m: 뒤에 오는 이름을 모듈로 인식하고 실행하라는 옵션입니다.
- venv: 실행할 모듈의 이름입니다. 이는 가상 환경을 생성하는 Python의 내장 모듈입니다.
- [가상환경이름]: 생성할 가상 환경의 이름 또는 경로입니다.
여기에서는 venv라는 이름으로 가상환경을 생성합니다. venv는 virtual environment의 약자입니다.
```
python -m venv venv
```
다음 명령어를 실행하여 가상환경을 활성화합니다. 이 가상환경속으로 들어간다고 생각하시면 됩니다. 사용하는 터미널에 맞는 명령 하나만 실행합니다.
- Windows PowerShell
```
.\venv\Scripts\Activate.ps1
```
- Windows 명령 프롬프트(cmd)
```
venv\Scripts\activate.bat
```
- macOS/Linux
```
source ./venv/bin/activate
```
앞에 (venv) 표시가 있는 상태에서만 작업을 진행해야 합니다. venv가 바로 활성화된 가상환경입니다. 이후 패키지 설치와 서버 실행은 이 상태에서 진행합니다.
```
(venv) C:\Users\YourName\projects\01_4_basic>
```

Windows에서 스크립트 실행이 차단될 때

PowerShell에서 Activate.ps1을 실행했을 때 아래와 같이 스크립트 실행이 차단되었다는 보안 오류가 나올 수 있습니다.

가장 간단한 해결책은 VS Code 터미널의 '+' 옆 화살표(▼)에서 Command Prompt(명령 프롬프트)를 선택하는 것입니다. 프로젝트 폴더로 이동한 뒤 venv\Scripts\activate.bat을 실행하면 됩니다.

PowerShell을 계속 사용하려면 현재 터미널에만 적용되는 아래 설정 후 다시 활성화할 수 있습니다. 관리자 권한은 필요하지 않습니다. 조직에서 실행 정책을 관리하는 PC라면 명령 프롬프트 방식을 사용하세요.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
.\venv\Scripts\Activate.ps1

2. FastAPI 설치 및 프로젝트 생성

가상환경이 준비되었다면, FastAPI를 설치하고 첫 프로젝트를 생성해봅시다. 코드에 대한 설명은 이 절의 3번에서 다룹니다.

가상환경이 활성화된 상태에서 FastAPI를 설치합니다. pip은 Python 패키지 관리자입니다. 파이썬의 패키지를 설치하고, 업그레이드하고, 삭제하는 등의 작업을 수행합니다. 뒤쪽 실습에 필요한 도구까지 한 번에 설치하도록 fastapi[standard]를 설치합니다.

pip install "fastapi[standard]"

[standard]는 "FastAPI를 실제로 쓸 때 거의 항상 같이 필요한 것들을 묶어달라"는 뜻입니다. 이 한 줄로 아래 패키지들이 함께 설치됩니다.

패키지	역할	등장하는 곳
pydantic	데이터 검증	2장
uvicorn	서버 실행	지금부터 계속
fastapi-cli	`fastapi dev` 명령어	지금부터 계속
jinja2	HTML 템플릿	2장
python-multipart	파일 업로드와 폼 데이터	4장, 6장
email-validator	이메일 형식 검증	5장

대괄호가 들어간 패키지 이름은 따옴표로 감싸세요. 일부 터미널에서는 따옴표가 없으면 설치에 실패합니다. pip 명령을 찾지 못하거나 다른 파이썬에 설치되는 것 같다면 python -m pip install "fastapi[standard]"로 실행하세요.

01_4_basic 폴더 아래 main.py 파일을 생성하고 아래 코드를 입력합니다. venv 폴더 안에 만들지 않도록 주의하세요.
```
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"Hello": "World"}
```

개발 서버를 실행합니다.

fastapi dev

터미널에 아래와 비슷한 내용이 출력되면 성공입니다.

 Starting FastAPI in development mode
 Using import string: main:app
 Server started at http://127.0.0.1:8000
    Documentation at http://127.0.0.1:8000/docs

웹 브라우저에서 http://127.0.0.1:8000/로 접속하여 서버가 동작하는지 확인합니다. {"Hello":"World"}가 보입니다.
웹 브라우저에서 http://127.0.0.1:8000/docs로 접속하여 FastAPI의 자동 생성된 API 문서를 확인합니다.

개발 서버는 코드 변경을 자동으로 감지하고 서버를 재시작합니다. 서버를 중지하려면 터미널에서 Ctrl + C를 누르세요.

한글 Windows에서 fastapi dev가 에러를 내며 죽는다면

UnicodeEncodeError: 'cp949' codec can't encode character '\u26a1'라는 긴 에러가 나올 수 있습니다. 코드 문제가 아니라, 터미널이 한글 인코딩(cp949)을 쓰고 있어서 FastAPI가 출력하려는 기호를 표시하지 못해 생기는 문제입니다.

PowerShell에서 아래 명령을 한 번 실행한 뒤 다시 서버를 띄우면 해결됩니다.

$env:PYTHONIOENCODING = "utf-8"

터미널을 새로 열 때마다 다시 입력해야 하는 것이 번거롭다면, VS Code 설정에서 터미널 인코딩을 UTF-8로 바꾸거나 아래 명령을 함께 실행하셔도 됩니다.

chcp 65001

2.1 `fastapi dev`와 `uvicorn main:app --reload`

다른 자료에서는 서버를 아래 명령으로 띄우는 경우가 많습니다.

uvicorn main:app --reload

이 명령도 그대로 동작합니다. 다만 아래와 같은 차이가 있어 개발 중에는 fastapi dev가 더 편합니다.

항목	`fastapi dev`	`uvicorn main:app --reload`
파일과 앱 이름	알아서 찾아줍니다	`main:app`을 직접 적어야 합니다
자동 새로고침	기본으로 켜져 있습니다	`--reload`를 붙여야 합니다
문서 주소 안내	실행할 때 출력해 줍니다	직접 기억해야 합니다
실서비스 배포	`fastapi run`을 씁니다	옵션을 직접 조합합니다

uvicorn main:app에서 uvicorn은 FastAPI 애플리케이션을 실행하는 데 사용되는 서버 프로그램입니다. main은 main.py 파일의 이름이며, app은 파일 안에서 만든 app 인스턴스의 이름입니다. --reload는 코드 변경을 감지하고 서버를 자동으로 다시 시작하는 옵션입니다. fastapi dev도 내부적으로는 uvicorn을 실행합니다. 실행 결과에 Using import string: main:app이라고 찍히는 것이 그 증거입니다.

2.2 다음 실습으로 이동할 때

서버를 실행 중이라면 Ctrl + C로 멈추고, deactivate로 현재 가상환경에서 빠져나옵니다. cd ..으로 상위 폴더로 이동한 다음 새 실습 폴더와 가상환경을 만듭니다.

VS Code를 다시 열거나 새 터미널을 열었다면 프로젝트 폴더로 이동해 기존 가상환경을 다시 활성화하세요. 가상환경을 매번 새로 만들거나 패키지를 다시 설치할 필요는 없습니다. VS Code의 Python: Select Interpreter에서도 해당 프로젝트의 venv를 선택하면 코드 자동 완성이 같은 환경을 사용합니다.

3. FastAPI 프로젝트 구조와 코드 설명

3.1 프로젝트 구조

프로젝트는 아래와 같은 폴더 구조로 구성됩니다. 이 구조는 FastAPI 프로젝트의 기본 구조입니다.

01_4_basic
┣━ 📄main.py # FastAPI 애플리케이션의 주 진입점입니다.
┗━ 📁venv/ # Python 가상 환경 폴더입니다.

패키지 목록은 pip freeze로 requirements.txt에 저장합니다. 이 파일로 다른 컴퓨터에 패키지를 설치하는 방법은 6장 패키지 관리에서 다룹니다.

프로젝트가 성장하면서 다음과 같이 구조를 확장할 수 있습니다. 직접 만들어야 하는 폴더이며 필수적인 구조는 아닙니다. 또한 이 구조는 사용자 편의에 따라 자유롭게 변경할 수 있으며, 6장에서 직접 만들어 볼 예정입니다.

my_fastapi_project/
┣━ 📄requirements.txt # 프로젝트에서 사용하는 패키지 목록
┣━ 📁venv/
┗━ 📁app/ # 애플리케이션 코드를 포함하는 폴더
    ┣━ 📄main.py # 앱을 만들고 라우터를 연결하는 파일
    ┣━ 📁routers/ # API 경로를 기능별로 나눈 파일들
    ┣━ 📁models/ # 데이터베이스 모델을 정의하는 파일들
    ┗━ 📁schemas/ # Pydantic 모델을 정의하는 파일들

우리 수업은 FastAPI의 기본적인 사용법을 배우는 것이므로, 폴더 구조를 어렵게 가져가지 않고 5장까지는 대부분 main.py 파일에서 작업할 것입니다. 구조를 나누는 것은 나눌 이유가 생겼을 때 배우는 편이 이해가 빠르기 때문입니다.

3.2 코드 설명

코드를 설명하기 전에 웹 서비스의 가장 기본적인 구성 요소를 살펴보겠습니다.

구성 요소	설명
경로(Path)	사용자가 입력한 URL의 경로
동작(Operation)	경로에 대한 요청을 처리하는 함수

FastAPI는 동작을 주로 함수로 처리합니다. 경로는 함수 위에 데코레이터로 지정합니다. 여기서 주로라고 표현한 이유는 클래스를 사용하여 경로와 동작을 정의할 수도 있기 때문입니다.

이번에는 코드를 살펴보겠습니다.

from fastapi import FastAPI

app = FastAPI()  # FastAPI 클래스의 인스턴스를 생성합니다.


@app.get("/")  # 경로를 지정합니다.
def read_root():  # 경로에 대한 동작을 정의합니다.
    return {"Hello": "World"}  # 동작의 결과를 반환합니다.

app 인스턴스는 FastAPI 클래스의 인스턴스입니다. 이 인스턴스를 통해 FastAPI의 기능을 사용할 수 있습니다. 여기서는 @app.get("/")의 형태로 사용되고 있습니다. @app.get("/")는 데코레이터로, 사용자가 / 경로에 GET 요청을 보냈을 때 아래 함수를 실행하겠다는 의미입니다. 여기서 이 데코레이터는 단지 경로를 함수로 연결시켜주는 것 뿐만 아니라 함수가 반환한 파이썬 딕셔너리를 JSON으로 바꿔 응답까지 만들어 줍니다.

return {"Hello": "World"}가 브라우저에서 {"Hello":"World"}로 보이는 이유가 여기에 있습니다. 파이썬 딕셔너리와 JSON은 생김새가 비슷하지만 다른 것입니다. 이 변환을 FastAPI가 대신 해주고 있습니다.

연습문제

/hello 경로에 접속했을 때 {"message": "hello weniv"}를 반환하는 함수를 추가해보세요.
서버를 켜둔 상태에서 main.py의 반환값을 바꾸고 저장한 뒤, 터미널에 무엇이 출력되는지 관찰해보세요. 서버를 다시 켜지 않아도 브라우저에 바뀐 값이 나오는 것을 확인할 수 있습니다.
http://127.0.0.1:8000/openapi.json에 접속해보세요. 방금 만든 API의 정보가 JSON 형태로 정리되어 있습니다. 이 파일이 /docs 화면을 만들어내는 원본입니다.

FastAPI 설치 및 프로젝트 생성

1. 프로젝트 폴더 생성 및 가상환경 설정

2. FastAPI 설치 및 프로젝트 생성

2.1 fastapi dev와 uvicorn main:app --reload

2.2 다음 실습으로 이동할 때

3. FastAPI 프로젝트 구조와 코드 설명

3.1 프로젝트 구조

3.2 코드 설명

연습문제

2.1 `fastapi dev`와 `uvicorn main:app --reload`