FastAPI 기반 코드에서 라우팅 방법의 차이에 대하여

FastAPI를 기반으로 하는 서비스를 만들기 위해서는 기능 구현 후 해당 위치로 찾아갈 수 있는 라우트를 구성해야 합니다.

예전에 구매했던 FastAPI 도서를 참고해서 기본 코드를 확인하고 있는데...

이상한 설명이 보이더군요.

 

일반적으로 확인하는 기본 라우팅 코드는 다음과 같습니다.

 

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def welcome() -> dict:
    return { "message": "Hello World!"}

 

위의 코드는 URL + "/"의 경로가 주어지면 "Hello World!"를 출력하는 코드입니다.

여기까지는 아무런 문제가 없습니다만..

해당 도서에서는 다음과 같은 설명을 하고 있더군요.

 

이렇게 FastAPI() 인스턴스를 라우팅 작업에 사용할 수 있다. 그러나 이 방식은 라우팅 중에 단일 경로만 고려하는 애플리케이션에서 일반적으로 사용된다. 고유한 함수를 처리하는 각각의 라우트가 FastAPI() 인스턴스를 사용하는 경우 애플리케이션은 한 번에 여러 라우트를 처리할 수 없다. uvicorn이 하나의 엔트리 포인트만 실행할 수 있기 때문이다.
그렇다면 여러 함수를 사용하는 연속적인 라우트처리는 어떻게 할 수 있을까? APIRouter 클래스를 사용하면 다중 라우팅이 허용되므로 이 문제를 해결할 수 있다.

 

 

일단 결론을 말하면 위의 설명은 잘못되었다고 할 수 있습니다.

 

@app.get(...), @app.post(...)와 같이 데코레이터를 사용하여 여러 라우트를 하나의 파일 안에서 등록하여 사용하는 것은 FastAPI의 기본적인 사용방법입니다.

FastAPI 만이 아니라 Django나 Flask와 같은 다른 웹프레임워크에서도 마찬가지입니다.

위의 코드와 같은 방식으로 코드를 만들어도 여러 라우트를 이용한 서비스는 충분히 만들수 있고 아무런 문제없이 작동합니다.

 

uvicorn이 하나의 엔트리 포인트만 실행한다는 것은 사실이지만, 그 하나의 엔트리 포인트는 FastAPI 인스턴스를 가리키는 것이지 하나의 라우트를 가리키는 것은 아닙니다.

따라서 위의 코드는 여러 라우트를 이용하도록 확장하더라도 아무런 문제가 없습니다.

 

APIRouter 클래스를 사용하는 것은 위의 책에서 설명한 이유가 아니라 대규모의 앱을 만들때 발생할 수 있는 문제를 해결하기 위한 것입니다.

FastAPI는 규모가 커질수록 많은 라우트를 사용하게 되는데.. 이런 모든 라우트를 하나의 파일에 집어넣게 되면 코드가 지저분해지고 유지보수가 어려워집니다.

그래서 라우팅을 모듈화하거나 재사용하는 등 구조화된 코드 관리가 필요해지는데 APIRouter 클래스는 여기에 모듈화된 라우트 구성방식을 제공해줍니다.

APIRouter를 사용함으로써 모듈화, 재사용성 및 가독성 향상이라는 효과를 얻을 수 있으며, 접두어를 지원하여 같은 계열의 기능을 같은 경로에 묶어서 정의할 수 있게 됩니다.

또한 문서화 작업 시 경로별 태그 구분이 쉬워지거나.. 하는 효과도 얻을 수 있습니다.

 

그러나 소규모의 프로젝트나 실습과 같은 환경에서는 APIRouter를 사용하는 것이 더 복잡할 수 있습니다.

그래서 소규모 프로젝트와 실습 등의 경우에는 @app.get(...)와 같은 데코레이터를 사용하여 간단하게 라우팅하는 방법이 권장되고, 중대형 프로젝트 또는 협업이 필요한 프로젝트의 경우에는 APIRouter로 구조화하는 방법이 권장됩니다.

 

그리고 위의 주장에서 보듯이 여러 함수를 사용하는 연속적인 라우트처리라는 부분에서도 달라질 것은 없습니다.

여러 라우트를 순차적으로 실행하고자 하더라도, 또 하나의 라우트 요청에서 다른 라우트를 내부적으로 호출하고자 한다는 의미라고 하더라도 이는 FastAPI의 기능이 아니라 비즈니스 로직을 함수로 분리한 후 라우트 핸들러로 해당 비즈니스 로직을 호출하는 것이 일반적인 방법입니다.

 

만약 여러 파일 또는 모듈에 걸쳐서 기능별로 라우트를 나누고 싶을때에는 각 파일에서 필요한 라우트를 포함시킬 필요가 있기 때문에 이런 경우에는 APIRouter가 필요하겠지만... 이 내용은 애초에 하나의 파일 안에 라우트가 들어가 있는 것이 아니기때문에 문제를 보는 관점이 다르다고 할 수 있습니다. 

 

---

 

별 생각없이 책을 보다가 이런 오류를 보게 되니... 코드들이나 설명들을 하나씩 다 체크해 가면서 봐야할 것 같아서 약간 골치가 아프네요.

그냥 책을 그대로 읽으면서 확인해 나가기에는 신뢰가 떨어지는 느낌입니다.

저자도 사람이기에 실수가 있을 수 있다는 것은 당연한 일이지만...

오타나 실수로 발생한 오류가 아니라 설명을 그렇게 한 것으로 보아.. 기본적인 부분에서 잘못 이해를 하고 있는 책이 아닐까.. 라는 의심이 생기게 됩니다.

 

빠르게.. 필요한 부분만 체크하면서 지나가야 할 것 같습니다.

 

 

다 체크해야 하나..(그림출처: MS Bing Image Creator로 직접 그림)