FastAPI 기반 비동기 처리 전략: 고성능 API 설계의 출발점

FastAPI는 Python 기반의 고성능 웹 프레임워크로, 비동기 처리를 지원하며 RESTful API나 GraphQL API를 빠르게 개발할 수 있도록 도와준다.
Python 3.6 이상에서 작동하며, Pydantic의 데이터 검증 기능과 타입 힌팅 기반의 자동 문서화 기능 덕분에 코드의 안정성과 생산성을 동시에 확보할 수 있다.

왜 FastAPI인가?

말 그대로 'Fast'API라서 빠르게 API서버 개발을 진행하며 매우 높은 성능을 자랑한다.

1. 성능 (Speed)
   FastAPI는 Starlette과 Uvicorn 기반으로 동작하며, 비동기 I/O를 기본 지원하여 Node.js 수준의 속도를 자랑한다. 따라서 수천 개의 요청을 효율적으로 처리할 수 있다.

2. 자동 문서화
   코드만 작성하면 Swagger UI와 ReDoc으로 API 문서가 자동 생성되며, 별도 설정 없이 테스트까지 가능하다.

3. 간결한 코드
   타입 힌팅을 통해 코드 가독성이 뛰어나며, IDE의 자동완성 기능과 정적 분석 도구까지 활용 가능하다.

4. 비동기 처리
   비동기 처리(async/await)를 기본적으로 지원하여, 외부 API 호출, 파일 입출력, DB 연산 등에서 논블로킹 처리가 가능하다.

🔄 동기 vs 비동기 처리

우선 비동기(asynchronous processing)과 동기(synchronous processing)의 차이점에 대해 알아보자
결론부터 말하자면 동기처리는 요청이 끝날때까지 기다리고, 비동기처리는 기다리지 않고 다음 작업을 병렬로 처리한다.

동기 처리

요청 -> 작업 완료될 때까지 기다림 -> 다음 작업
순차적 실행방식이다.

✅ 동기 (sync) 적합 상황
간단한 CRUD 작업
I/O가 적고, 순차 처리가 필요한 로직
테스트 코드 작성 등 빠른 실행이 필요한 경우

비동기 처리

요청 -> 기다리지 않고 다음 작업 수행 -> 결과가 준비되면 코랙
따라서 병렬적이고 논블로킹 방식으로 작업수행이 가능하다.

✅ 비동기 (async) 적합 상황
간단한 CRUD 작업
I/O가 적고, 순차 처리가 필요한 로직
테스트 코드 작성 등 빠른 실행이 필요한 경우

📊 주요 프레임워크 비교

🌊 서비스 흐름

[클라이언트 요청]
     ↓
[routers/task.py] - FastAPI 라우터에서 요청 수신
     ↓
[schemas/task.py] - 응답 데이터 구조화 후 반환
		 ↓
[cruds/task.py] - 실제 DB 연산 처리
     ↓
[models/task.py] - SQLAlchemy로 DB 조작
     ↓
[클라이언트 응답 전송]

1. routers - 실제 API 라우팅 처리

클라이언트의 요청을 어떤 curd함수에 보낼지 지정
@router.get, @router.post 같은 데코레이터는 HTTP 요청에 대한 엔드포인트 정의 → FastAPI에서 실제로 외부 요청을 받는다.

2. schemas - 데이터 검증 및 직렬화

입력값 및 응답값 정의 (요청, 응답)
FastAPI의 입력과 출력을 책임지는 Data Schema들을 정의하는 공간

3. cruds - 비즈니스 로직 및 DB 조작 함수

실제 DB와 상호작용하는 로직 정의
SQLAlchemy 세션을 받아 쿼리를 실행
라우터는 요청, 응답 처리만 cruds는 실제 동작만 맡게 되어 유지보수성과 테스트 효율성의 향상

4. models - 데이터베이스 모델 정의

SQLAlchemy를 사용한 데이터베이스 모델 정의
Task와 Done이라는 두개의 테이블을 SQLAlchemy ORM 클래스로 정의

5. tests - 테스트 코드 작성

각 API 동작이 의도한 대로 동작하는지 확인
단위 테스트 / 통합 테스트 수행

🔥 Trouble Shooting

🔗 DBMS 연동

데모 앱을 동작시킬 때, 접근할 DBMS 연결을 설정
컨테이너 환경에서 기본적으로 필요한 설정이다
단순하게 manager@'%' 하나만 생성해 외부 접속만 처리

→ FastAPI나 DBeaver에서 DB 접속은 되었지만 테이블이 안보이는 문제 발생

localhost 접속전용 계정을 별도로 만들어 권한을 부여하고
MariaDB에서는 manager@'%' & manager@'localhost'를 다르게 취급하므로
모두 만들어야 다양한 환경에서 문제 없이 접속 가능하게 변경

-- demo 데이터베이스에 대한 권한 부여
GRANT ALL PRIVILEGES ON demo.* TO 'manager'@'%';
GRANT ALL PRIVILEGES ON demo.* TO 'manager'@'localhost';

🚨 async/await

❌ 오류 발생
done = done_crud.get_done(db, task_id=task_id)   
return done_crud.create_done(db, task_id)       

이렇게 작성하면 다음과 같은 오류 발생

RuntimeWarning: coroutine 'get_done' was never awaited

done_crud.get_done()과 create_done()는 비동기 함수이다.
비동기 함수는 호출만 하면 실행되지 않고, coroutine 객체만 반환한다.
따라서 await가 필요하다.

done = await done_crud.get_done(db, task_id=task_id)
return await done_crud.create_done(db, task_id)