하위 애플리케이션
하위 애플리케이션 (Sub Applications - Mounts)
서로 독립적인 FastAPI 앱을 두 개 만들어야 할 때가 있어요. 각각 자기만의 OpenAPI와 문서 UI를 가지게요. 이럴 땐 메인 앱을 만들고, 하위 애플리케이션(sub-application) 하나(또는 여러 개)를 **마운트(mount)**하면 돼요.
출처: 공식문서
FastAPI 애플리케이션 마운팅하기
**마운팅(mounting)**이란 특정 경로에 완전히 독립적인 애플리케이션을 추가하는 걸 말해요. 그러면 그 경로 아래의 모든 요청을, 그 하위 애플리케이션에서 선언한 *경로 연산들(path operations)*로 처리해요.
최상위 애플리케이션 만들기
먼저 메인, 즉 최상위 FastAPI 애플리케이션과 그 경로 연산을 만들어요. 그리고 같은 파일에 하위 애플리케이션을 만들고 마운트까지 한 번에 보여줄게요:
from fastapi import FastAPI
app = FastAPI()
@app.get("/app")
def read_main():
return {"message": "Hello World from main app"}
subapi = FastAPI()
@subapi.get("/sub")
def read_sub():
return {"message": "Hello World from sub API"}
app.mount("/subapi", subapi)
하위 애플리케이션 만들기
하위 애플리케이션은 그냥 평범한 FastAPI 앱이에요. 다만 이게 마운트될 앱이라는 점만 달라요. 위 코드에서 subapi = FastAPI()로 만들고 /sub 경로 연산을 달아 둔 부분이죠.
하위 애플리케이션 마운트하기
최상위 애플리케이션 app에서 하위 애플리케이션 subapi를 마운트해요. 여기서는 /subapi 경로에 마운트했어요:
app.mount("/subapi", subapi)
자동 API 문서 확인하기
fastapi 명령으로 서버를 실행해요:
$ uv run fastapi dev
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
그리고 http://127.0.0.1:8000/docs에서 문서를 열면, 메인 앱의 경로 연산만 담긴 자동 API 문서가 보여요.
이제 하위 애플리케이션의 문서를 http://127.0.0.1:8000/subapi/docs에서 열어 보면, 하위 애플리케이션의 경로 연산만 담기고 전부 올바른 하위 경로 접두사 /subapi 아래에 있는 자동 API 문서를 볼 수 있어요.
두 UI 중 아무 데서나 조작해 봐도 잘 동작해요. 브라우저가 각각의 앱이나 하위 앱과 정상적으로 통신할 수 있으니까요.
기술적 세부사항: root_path
위처럼 하위 애플리케이션을 마운트하면, FastAPI가 ASGI 스펙의 메커니즘인 **root_path**를 이용해 하위 애플리케이션의 마운트 경로를 전달해 줘요.
그래서 하위 애플리케이션은 문서 UI에 그 경로 접두사를 쓰게 돼요.
그리고 하위 애플리케이션에도 자기만의 하위 애플리케이션을 마운트해도 모든 게 올바르게 동작해요. FastAPI가 이런 root_path들을 전부 자동으로 처리해 주니까요.
root_path와 그것을 명시적으로 쓰는 방법은 리버스 프록시 뒤에서 섹션에서 더 배우게 될 거예요.