FastAPI(1)

글을 시작하기 앞서 프로그래밍에서 무언가를 학습하기 가장 좋은 방법은 공식 문서를 읽는 것임을 알립니다.
FastAPI tutorial

가상환경 만들고 실행하기

프로젝트를 시작하기 전에 최우선적으로 해야 하는 작업은 바로 가상환경을 생성하고 해당 환경에서 프로젝트를 실행하는 것이다.
그래야 다른 프로젝트와 얽혀 충돌되는 것을 예방 할 수 있다

앞선 포스트에서 우리는 pyenv를 설치 했었다.
이 pyenv를 통해 원하는 버전을 설치한다.

pyenv install 3.11

그 후 원하는 버전으로 변경해 주면 해당 pyton의 버전을 사용 할 수 있다.

pyenv global 3.11 # 전체 시스템에 적용
pyenv local 3.11  # 해당 폴더에서만 적용(이걸 더 권장)

잘 바뀌었는지 확인 하고 싶으면 pyenv versions 로 확인 가능하다.

이제 프로젝트 폴더를 만든 후 python의 가상환경을 만들 것인데 window와 linux는 각자 명령어가 다르니 이에 주의 한다.
이 작업은 PowerShell 7.5와 WSL2로 진행 했음을 알립니다

1. 폴더 생성 및 파일 생성

mkdir your_file_name

Window

New-Item your_file_name

Linux

touch your_file_name

2. 가상 환경 생성 및 실행

python -m venv .your_env_name

이때 가상환경 이름 앞에 .을 붙이는 이유는 숨긴 폴더로 만들기 위함이다(안붙여도 상관없음)
window에서는 숨긴폴더를 해도 보이지만 wsl2에서는 안보인다, 이 때 ls -al 을 하면 숨긴 폴더를 포함해 모든 폴더를 볼 수 있다

Window

.\.your_env_name\Scripts\activate

Linux

source .your_env_name/bin/activate

가상환경을 실행한다는건 해당 경로의 파일을 실행한다는 의미

main.py 작성

먼저 main.py를 작성하기 위한 파일을 생성한다.

터미널에서 다음과 같이 입력하거나 code .을 하여 vscode에서 파일을 생성한다.

 

Window	Linux
createa new-item main.py	touch main.py

 

이 글에서는 fastapi를 다루어 웹 페이지를 제작할 것이다.
그러니 먼저 fastapi를 설치한다.
pip install "fastapi[standard]"

 

무언가를 설치하거나 활용할 때는 공식 문서를 보는 것이 좋다.
일일이 찾기 힘들다면 PyPi에서 검색하여 빠르게 보는 것도 괜찮다.

 

이후 설치가 잘 됐으면 pip list를 했을 때 설치된 라이브러리가 뜰 것이다.
pip는 패키지 관리 도구로 현재 poetry나 uv같이 다른 더 발전 된 도구가 있지만 이는 나중에 다루겠다

 

1. main.py_객체 생성

from fastapi import FastAPI
app = FastAPI()

• from fastapi import FastAPI는 fastapi에서 FastAPI를 가져온다.
• app = FastAPI() 은 app을 FastAPI 클래스의 인스턴스로 사용하겠다는 의미다.
  이 후 FastAPI와의 상호작용은 이 app이라는 이름으로 이루어질 것이다
  (아는 사람은 알겠지만 가져와서 쓴다는건 누군가가 작성한 클래스를 가져와서 쓰는 것이다, 우리는 그걸 쓰기 위해 외부에서 누군가 작성한걸 받아온 것이고 그 중에서 FastAPI를 사용한다고 컴퓨터에게 알린 것이다.)
•  

@app.get("/")
def greet() -> dict:
    return {"message": "hello, world"}

• @app.get("/")은 웹에서 주소 / 로 들어갔을 때 아래의 함수를 실행시키라는 의미다.
• def greet() -> dict: 는 함수 이름을 greet()으로 한다는 의미
• -> dict 는 이 함수의 리턴값이 dict라는 타입 힌트를 제공하는 것이다.
  return {"message": "hello, world"} 은 반환 값이 딕셔너리의 형태로 message: hello,world 라는 의미.

 

타입 힌트를 수행하는 이유는 크게 두가지 이유가 있다.

 

타입 힌트를 사용하는 이유

1. 먼저 우리의 오랜 친구 에디터 자동완성을 수월하게 사용할 수 있다(ctrl+space)
2. 타인의 코드를 활용하여 개발 할 때 타입 힌트가 있으면 더 쉬운 개발, 오류 발견과 같은 이점이 있다.
   • 타입 선언을 하면 FastAPI는 자동으로 요청을 "파싱"하기에 오류를 잘 발견할 수 있다.

@app.get("/hello/{who}")  # 이렇게 하면 주소에 다 보이기 때문에 보안에 취약하다
def hello_path(who: str):
    return {"message":  f"{who}"}

이런식으로 경로 매개변수의 타입을 선언할 수도 있다.

 

라이브 서버 실행하기

이제 main.py를 작성 했으니 라이브 서버를 실행해 보자

터미널에서 다음과 같은 명령어를 입력해준다.

uvicorn main:app --reload

• main: main.py의 main
• app: main.py 내부의 app =FastAPI 인스턴스 이름
• --reload: 코드 변경 시 자동으로 서버 재시작. 개발 시에만 사용.

 

로컬에서 앱이 서비스되는 URL

서버가 잘 작동 됐다면 http://127.0.0.1:8000을 브라우저에 입력하거나 터미널에 뜬 링크를 클릭한다.

{"message":"hello, world!"}

우리가 작성한 return 값인 {"message":"hello, world!"} 값이 뜬다면 성공이다

 

1. 대화형 API 문서 확인하기

http://127.0.0.1:8000/docs 를 들어가면 자동 대화형 API 문서를 확인 할 수 있다.

내가 만든 함수가 변수에 따라 결과가 달라지고 이를 보고 싶은 경우 try out it -> excute에서 원하는 변수명을 넣어보며 어떤 값이 나오는 지 볼 수 있다.

 

혹은 http://127.0.0.1:8000/redoc에서 다른 방식으로 API문서를 볼 수 있다.

왼쪽 판넬에서 내가 만든 함수와 검색을 이용할 수 있다

 

2. OpenAPI

• FastAPI는 API를 정의하기 위한 OpenAPI 표준을 사용하여 당신의 모든 API를 이용해 스키마를 생성한다
• 스키마: API의 경로, 가능한 매개변수 등을 포함하며 JSON처럼 어떤 데이터의 형태를 의미(http://127.0.0.1:8000/openapi.json 에서 확인 가능)
  • 첫출에 openapi로 시작하며 내용이 나열된 것을 볼 수 있다

 

3. 경로 작동 생성

• http://127.0.0.1:8000/hello/{who} 를 url로 사용했다면 첫 번째 /부터 시작하는 url의 뒷 부분, 즉 /hello/{who}가 경로다
  • 일반적으로는 엔드포인트 또는 라우트라고 부른다.
  • 라우트는 관심사와 리소스를 분리하기 위한 주요 방법
• 작동(Operation)은 HTTP 메소드 중 하나를 나타내며 주로 사용되는 메소드는 아래와 같다.
  • POST : 데이터 생성
  • GET : 데이터 읽기
  • PUT : 데이터 수정
  • DELETE : 데이터 삭제
  • HTTP 프로토콜에서는 이러한 "메소드"를 하나(또는 여러개)사용하여 각 경로와 통신할 수 있다.

 

용어 정리

용어	설명
경로(path)	URL 내에서 API를 식별하는 부분( 예:/hello/{who})
엔드포인트	특정 URL + HTTP 메소드 조합
라우터	여러 엔드포인트를 그룹화할 수 있는 FastAPI의 기능 (APIrouter)
오퍼레이션	HTTP메소드 (GET, POST, PUT, DELETE 등)