파이썬 fastapi(api 서버) 구현

Python 기반의 현대적인 웹 프레임워크 FastAPI를 사용하여 API 서버를 구축하는 전체 과정을 알아보도록 하겠습니다.

파이썬 프로젝트의 필수 요소인 **가상 환경(venv)**의 개념부터, PostgreSQL 데이터베이스 연동, 그리고 API 키를 이용한 엔드포인트 보안까지 모두 다룹니다.

 

따라오다 보면 독립적이고 안정적인 API 서버를 직접 구축하고 테스트할 수 있게 될 것입니다.

 

why

1. 왜 가상 환경(venv)을 사용해야 할까?

프로젝트를 시작하기 전, 가장 먼저 이해해야 할 개념은 '가상 환경'입니다.

 

• 가상 환경이란?
  프로젝트마다 독립된 '공구함'을 만들어주는 기능입니다. 각 프로젝트는 자신만의 파이썬 버전과 라이브러리 버전을 이 공구함 안에 설치하여 사용합니다.
• 왜 필수적인가요?
  1. 의존성 충돌 방지: 프로젝트 A는 라이브러리 X의 1.0 버전이, 프로젝트 B는 2.0 버전이 필요할 때, 가상 환경이 없으면 둘 중 하나는 반드시 오류가 발생합니다. 가상 환경은 각 프로젝트가 필요한 버전을 독립적으로 가질 수 있게 해 줍니다.
  2. 깔끔한 프로젝트 관리: requirements.txt (프로젝트에 필요한 라이브러리 목록)를 만들 때, 현재 프로젝트와 관련된 라이브러리만 정확히 기록할 수 있습니다.
  3. 시스템 안정성: 컴퓨터의 기본 파이썬 환경을 건드리지 않으므로, 시스템 전체가 안정적으로 유지됩니다.

1. 프로젝트 설정 및 라이브러리 설치

a. 가상 환경 생성 및 활성화

먼저 특정 위치에 프로젝트를 진행할 폴더(fastapi)를 만들고, 그 안에서 cmd를 켜신 다음 명령어를 실행합니다.

1. 프로젝트 폴더로 이동합니다.

cd path\to\your\fastapi

2. 'venv'라는 이름의 가상 환경을 생성합니다.

python -m venv .venv

3. 가상 환경을 활성화합니다. (Windows 기준)

.venv\Scripts\activate

 

밑에는 실행시킬 필요 없음 참고용 가성환경 비활성화 방법

 

.venv\Scripts\deactivate

 

활성화되면 터미널 프롬프트 맨 앞에 (venv)가 나타납니다. 이제부터 설치하는 모든 라이브러리는 이 가상 환경 안에만 설치됩니다.

 

 

2단계: 필수 라이브러리 설치하기

API 서버에 필요한 라이브러리들을 하나씩 설치합니다.

FastAPI 프레임워크와 ASGI 서버인 Uvicorn 설치

pip install fastapi uvicorn

 

PostgreSQL 데이터베이스 연결을 위한 드라이버 설치

pip install psycopg2-binary

 

.env 파일을 통해 민감 정보를 관리하기 위한 라이브러리 설치

pip install python-dotenv

 

pip list 명령어로 패키지 리스트들이 정상적으로 설치 됐는지 확인합니다.

pip list

 

가상환경에 설치된 패키지 리스트는 따로 파일에 저장해 둡니다.

추후 다른 서버에 설치할 때 아래 txt에 저장된 패키지들을 충돌 없이 동일한 버전으로 재설치할 수 있습니다.

pip freeze > requirements.txt

 

txt 파일이 있다고 가정하면 아래 명시된 패키지들을 한꺼번에 설치 할 수 있습니다.

pip install -r requirements.txt

 

 

3. API 코드 작성하기

이제 실제 코드를 작성할 차례입니다. 프로젝트 폴더(fastapi) 안에 다음 두 파일을 생성하세요.

주의: .venv 폴더 안에 만드시면 안 됩니다!

 

[폴더구조]

fastapi_test/
│
├── .env <-- 데이터베이스 정보, API 키 저장
├── main.py <-- API 로직 구현
├── database.py <-- API 로직 구현(데이터베이스 연결과 세션 관리)
└── venv/ <-- 파이썬과 라이브러리가 설치된 가상 환경

 

1단계: .env 파일 작성 (민감 정보)

데이터베이스 접속 정보나 API 키 같은 민감 정보는 코드와 분리하여 .env 파일에 보관하는 것이 안전합니다.

PostgreSQL 접속 정보 (실제 환경에 맞게 수정)

API 인증에 사용할 시크릿 키 (원하는 값으로 변경)
API_KEY = "SECRET_API_KEY"

DATABASE_URL=postgresql://유저아이디:패스워드@호스트:포트/데이터베이스명
API_KEY="API 키 입력"

 

중요: .env 파일은 Git 같은 버전 관리 시스템에 절대 포함시키면 안 됩니다. .gitignore 파일에 .env를 추가하여 관리

 

2단계: main.py 파일 작성 (API 서버 로직)

 

import os
from fastapi import FastAPI, Depends, HTTPException, Security
from fastapi.security.api_key import APIKeyHeader
from dotenv import load_dotenv
from database import get_db_connection

load_dotenv()

app = FastAPI()

API_KEY = os.getenv("API_KEY")
API_KEY_NAME = "access_token"

api_key_header = APIKeyHeader(name=API_KEY_NAME, auto_error=False)

async def get_api_key(
    api_key_header: str = Security(api_key_header),
):
    if api_key_header == API_KEY:
        return api_key_header
    else:
        raise HTTPException(
            status_code=403,
            detail="Could not validate credentials",
        )

@app.get("/data")
async def get_data(api_key: str = Depends(get_api_key)):
    conn = get_db_connection()
    cur = conn.cursor()
    cur.execute("SELECT * FROM TB_CODE_MA") # Replace with your table name
    data = cur.fetchall()
    cur.close()
    conn.close()
    return {"data": data}

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

 

database.py

import os
import psycopg2
from dotenv import load_dotenv
load_dotenv()
DATABASE_URL = os.getenv("DATABASE_URL")
def get_db_connection():
    conn = psycopg2.connect(DATABASE_URL)
    return conn

 

 

4. 서버 실행 및 테스트

모든 준비가 끝났습니다. 이제 서버를 실행하고 API를 테스트해 봅시다.

 

1단계: 서버 실행

CMD에서 아래 명령어를 실행하여 API 서버를 시작합니다.

--reload` 옵션 덕분에 코드를 수정하고 저장할 때마다 서버가 자동으로 재시작됩니다.

 

uvicorn main:app --reload

 

2단계: API 호출 테스트

curl`이나 Postman 같은 API 테스트 도구를 사용하여 다음을 테스트합니다.

1. 실패 테스트 (API 키가 없는 경우)

curl -X GET "http://127.0.0.1:8000/data"

예상 결과 (403 Forbidden)

 

2. 성공 테스트 (올바른 API 키를 헤더에 포함)

curl -X GET "http://127.0.0.1:8000/data" -H "access_token: api키입력"

 

예상 결과 (200 OK)

데이터베이스 테이블의 내용이 JSON 형식으로 성공적으로 반환됩니다.

 

이 글을 기반으로 이제 특정 자원 예를 들면 주문 건에 대해 어떤 행동(Action)을 할 것인지를 정의하며

여러분들도 잘 알고 계신 CRUD 개념과 밀접하게 연결됩니다.

REST API 메서드 종류는 CRUD 개념과 비슷합니다.

GET(READ), POST(Create), PUT(UPDATE), DELETE(Delete)

 

그리고 localhost:8000/docs 를 치면 별도 api 문서 작성할 필요 없이 바로 나옵니다.

 

 

여러분은 이제 FastApi를 사용하여 가상 환경 위에서 동작하고, 데이터베이스와 연동되며, API 키로 보호되는 안전한 API 서버를 구축하는 방법을 모두 배웠습니다.

 

이제 응용하시면 됩니다.( JWT 토큰, 보안적인 부분 등등..)

 

오늘도 보람찬 생존 ^.^