Python & FastAPI 로 백엔드 시작하기 (1) _ 개발환경 세팅하기

01. 개발환경 세팅하기

 

이 글은 Python과 FastAPI를 활용하여 백엔드 개발을 시작하고 싶은 분들을 위해 작성하였습니다.

 

개요

- pyenv로 가상환경을 만들고 Poetry 종속성 관리 도구를 설치한다.
- FastAPI 와 Uvicorn 을 사용해 서버를 실행한다.
- .gitignore 파일을 생성하여 불필요한 업로드를 막는다.
- pre-commit을 활용하여 코드 스타일과 정적 분석을 자동화한다.

 

*사용 기기 : M1 MacBook Air
*사용 IDE : Visual Studio Code

*만약 터미널 사용이 처음이거나 아직 세팅이 완료되지 않았다면 이전 글을 참고해주세요.

2023.03.18 - [나는 이렇게 논다/백엔드 시작하기 with Python] - Mac M1 터미널 환경 세팅 한 번에 끝내기

 

 

---

 

가상환경 만들기

 

Pyenv 설치 - Pyenv는 다른 버전의 Python 간에 쉽게 전환할 수 있는 Python 버전 관리 도구입니다.

 

아래 curl 명령어를 통해 설치합니다.

curl https://pyenv.run | bash

 

pyenv 설치 후 안내문구를 따라 ~/.bashrc 혹은 ~/.zshrc 에 코드를 입력합니다.

 

아래 코드는 참고용입니다. 실제 pyenv가 안내한 코드를 입력해주세요.

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

예를 들어 기본 쉘이 zsh 이라면 vi ~/.zshrc 이라는 명령어를 통해 문서를 열 수 있습니다. (vim 사용법은 여기서 다루지 않겠습니다.)

 

 

Python 설치 - Pyenv가 설치되면 이를 사용하여 개발 환경에 사용할 특정 버전의 Python을 설치할 수 있습니다.

pyenv install 3.10.6

 

 

가상환경 생성 - pyenv virtualenv 명령어를 통해 가상환경을 생성할 수 있습니다. 여기서는 Python 3.10.6 버전과 lovelingo 라는 이름으로 가상환경을 생성하겠습니다. 가상환경 이름은 여러분의 프로젝트에 맞게 지어주시면 됩니다.

pyenv virtualenv 3.10.6 lovelingo

 

 

가상환경 활성화 - pyenv activate {가상환경 이름} 명령어를 통해 가상환경으로 활성화할 수 있습니다.

pyenv activate lovelingo

 

프로젝트를 열 때마다 가상환경을 자동으로 활성화하고 싶다면 루트 디렉토리에서 `.python-version` 파일을 생성, 해당 파일 안에 `가상환경 이름`을 입력해주세요. 

 

# .python-version 파일

lovelingo

 

 

---

 

 

종속성 관리 툴 설치

 

Poetry 설치 - Poetry는 프로젝트의 종속성과 가상 환경을 관리하는 데 도움이 되는 Python용 종속성 관리 도구입니다. Poetry는 패키지의 버전을 자동으로 관리하기 때문에 패키지간의 충돌을 방지하고, 안정적인 환경에서 작업할 수 있도록 도와줍니다.

 

아래 curl 명령어를 통해 설치합니다.

curl -sSL https://install.python-poetry.org | python3 -

 

 

Poetry 초기화 - 종속성 관리를 시작하기 위해 Poetry를 초기화합니다.

poetry init

poetry init 명령어를 입력하면 configure 를 세팅하게 되는데 모두 엔터로 스킵하겠습니다. configure 내용은 추후 pyproject.toml 파일에서 수정하실 수 있습니다.

 

 

---

 

 

FastAPI 설치 및 server 실행

 

poetry add 명령어를 통해 FastAPI 와 uvicorn 을 추가합니다.

poetry add fastapi uvicorn

 

FastAPI - Python 기반의 비동기 처리 웹 프레임워크로 OpenAPI 및 JSON 스키마 자동 생성 및 Python 타입 힌트를 통한 입력 데이터 검증을 지원합니다. Python 서버 프레임워크로 많이 사용하는 Django 와 비교하자면 상대적으로 가볍고 빠른, 커스텀하기 용이한 프레임워크라고 볼 수 있습니다.

 

uvicorn - FastAPI를 비롯한 ASGI 애플리케이션 실행, 이벤트 루프 및 비동기 I/O를 사용해 높은 성능 보장하는 Python의 ASGI(Asynchronous Server Gateway Interface) 서버입니다. uvicorn 명령어를 통해 FastAPI 서버를 실행할 수 있습니다.

 

 

 

루트 디렉토리에 main.py 파일을 생성하고 아래 코드를 입력합니다.

from fastapi import FastAPI

app = FastAPI()

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

 

 

터미널에서 아래 명령어를 입력해 서버를 실행합니다.

uvicorn main:app --reload

--reload 는 코드의 변경 사항이 감지될 때마다 자동으로 서버를 다시 시작합니다. 이는 개발 단계에서 유용하게 사용합니다.

 

 

 

웹 브라우저 http://127.0.0.1:8000/ 로 접속하여 "Hello World" 메시지를 확인합니다.

{"message":"Hello World"}

 

 

웹 브라우저 http://127.0.0.1:8000/docs 로 접속하여 OpenAPI 가 생성되었는지 확인합니다.

FastAPI 는 OpenAPI 를 자동으로 생성합니다. 앞으로 API를 구현할때마다 API명세를 최신 상태로 보여줄 것입니다.

 

 

---

 

 

.gitignore 파일 생성하기

.gitignore 파일은 Git 저장소에 포함되지 않아야 하는 파일들을 지정하는 설정 파일입니다. 보안성을 높이기 위해 인증 정보나 민감한 데이터를 포함한 파일, 불필요한 로그 파일, 컴파일된 바이너리 파일 등 저장소에 저장할 필요가 없는 파일들을 제외하고 Git에 커밋되지 않도록 설정할 수 있습니다.

 

루트 디렉토리 경로에 .gitignore 파일을 생성합니다.

 

https://www.toptal.com/developers/gitignore

 

위 사이트에 접속하여 사용하는 운영체제, 개발 환경, 프로그래밍 언어 등을 입력합니다. 생성 버튼을 누르고, 나온 내용을 .gitignore 파일에 붙여넣기 합니다. 이제 캐시 파일같은 불필요한 찌꺼기 파일들이 IDE에서 회색으로 처리되고 Git 저장소에도 올라가지 않을 것입니다.

 

 

---

 

 

pre-commit 설정하기

pre-commit은 Git 커밋 전에 자동으로 실행되도록 만든 검사 도구입니다. 이 도구는 코드 스타일, 코드 린트, 정적 분석 등을 검사하여 코드 품질을 향상시키고 버그를 예방하는데 도움을 줍니다.

 

Python 의 경우 실행 시점에 자료형을 결정하는 동적 언어이기 때문에 code push 전, 정석 분석을 강제할 수 있는 pre-commit 은 매우 유용한 도구 입니다.

 

 

poetry add 를 통해 pre-commit 의 종속성을 추가합니다.

poetry add pre-commit --group dev

--group dev 옵션은 dev(개발) 환경의 종속성을 의미합니다. 실제 prod(운영) 환경에서는 사용하지 않으므로 이를 구분하기 위해 나누는 것입니다.

 

 

pyproject.toml 문서를 보면 아래처럼 구분되어 입력되는 것을 확인할 수 있습니다.

# pyproject.toml


[tool.poetry.dependencies]
python = "^3.10"
fastapi = "^0.95.0"
uvicorn = "^0.21.1"


[tool.poetry.group.dev.dependencies]
pre-commit = "^3.2.2"

 

 

루트 디렉토리에 .pre-commit-config.yaml 파일을 생성하여 아래 내용을 입력합니다.

repos:
  - repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
      - id: black

  - repo: https://github.com/charliermarsh/ruff-pre-commit
    rev: v0.0.259
    hooks:
      - id: ruff

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.1.1
    hooks:
      - id: "mypy"

 

black 은 Python 코드 formatter입니다.
ruff 는 Rust로 작성된 Python linter입니다.
mypy 는 Python *정적 분석 도구입니다.

 

*정적 분석이란? 코드가 실행되기 전에 코드를 분석하여 잠재적인 오류를 찾아내는 프로세스입니다.

 

mypy는 개발자가 작성한 타입 힌트를 바탕으로 코드 분석을 수행하여 코드의 타입 안정성을 높이고, 잠재적인 버그를 사전에 예방할 수 있도록 돕습니다. 이를 통해 코드의 가독성과 유지 보수성을 높이고, 실수를 줄일 수 있습니다.

 

 

 

pre-commit hook 설치 - 아래 명령어를 통해 지정된 hook을 활성화합니다.

pre-commit install

pre-commit installed at .git/hooks/pre-commit 이라는 메시지가 출력되었다면 성공입니다.

 

 

이제 프로젝트를 Git 으로 관리하기 위해 git init 명령어를 입력합니다.

git init

 

아래 명령어를 통해 임의의 커밋을 만들겠습니다.

git commit -m "first commit" 

 

커밋이 실행되면서 pre-commit 이 동작합니다. 다음처럼 출력되었다면 성공입니다.

black.........................Passed
ruff..........................Passed
mypy..........................Passed

 

 

---

 

 

마치며

이제 본격적으로 백엔드 개발을 시작할 준비가 되었습니다.

 

다음 글에서는 app 디렉터리를 생성하고 연습용 API를 통해 'path parameter', 'query parameter', 'body' 데이터 수신 방법을 소개하겠습니다.