FastAPI CLI
FastAPI CLI (FastAPI CLI)
FastAPI를 프로젝트에 추가하면 터미널에서 쓸 수 있는 명령줄 프로그램이 딸려 와요. 개발 서버를 띄우고, 프로젝트를 관리하고, 그 이상의 일을 하게 해 주는 FastAPI CLI입니다. 어떻게 쓰는지 하나씩 볼게요.
출처: 공식문서
FastAPI CLI(command line interface)는 FastAPI 앱을 서빙하고, FastAPI 프로젝트를 관리하고, 그 밖의 일을 하는 데 쓰는 명령줄 프로그램이에요.
프로젝트에 FastAPI를 추가하면(예: uv add "fastapi[standard]"), 터미널에서 실행할 수 있는 명령줄 프로그램이 함께 옵니다.
개발용으로 FastAPI 앱을 실행하려면 fastapi dev 명령을 쓸 수 있어요:
$ fastapi dev
FastAPI Starting development server 🚀
Searching for package file structure from directories with
__init__.py files
Importing from /home/user/code/awesomeapp
module 🐍 main.py
code Importing the FastAPI app object from the module with the
following code:
from main import app
app Using import string: main:app
server Server started at http://127.0.0.1:8000
server Documentation at http://127.0.0.1:8000/docs
tip Running in development mode, for production use:
fastapi run
Logs:
INFO Will watch for changes in these directories:
['/home/user/code/awesomeapp']
INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to
quit)
INFO Started reloader process [383138] using WatchFiles
INFO Started server process [383153]
INFO Waiting for application startup.
INFO Application startup complete.
팁
운영(production)에서는
fastapi dev대신fastapi run을 쓰세요. 🚀
내부적으로 FastAPI CLI는 고성능·프로덕션용 ASGI 서버인 Uvicorn을 사용해요. 😎
fastapi CLI는 실행할 FastAPI 앱을 자동으로 탐지하려고 시도하는데, main.py 파일 안의 app 객체(또는 몇 가지 다른 변형)라고 가정해요.
하지만 사용할 앱을 명시적으로 설정할 수도 있어요.
pyproject.toml에서 앱 entrypoint 설정하기
pyproject.toml 파일에서 앱의 위치를 이렇게 설정할 수 있어요:
[tool.fastapi]
entrypoint = "main:app"
그 entrypoint는 fastapi 명령에게 앱을 이렇게 import 하라고 알려줘요:
from main import app
코드가 이렇게 구성되어 있다면:
.
├── backend
│ ├── main.py
│ ├── __init__.py
entrypoint는 이렇게 설정할 수 있어요:
[tool.fastapi]
entrypoint = "backend.main:app"
그리고 이렇게 하는 것과 동일해요:
from backend.main import app
경로나 --entrypoint CLI 옵션으로 fastapi dev 실행하기
fastapi dev 명령에 파일 경로를 넘길 수도 있고, 그러면 사용할 FastAPI 앱 객체를 추측해요:
$ uv run fastapi dev main.py
혹은 fastapi dev 명령에 --entrypoint 옵션을 넘길 수도 있어요:
$ uv run fastapi dev --entrypoint main:app
하지만 fastapi 명령을 부를 때마다 올바른 경로/entrypoint를 기억해서 넘겨야 한다는 번거로움이 있어요.
게다가 다른 도구(VS Code Extension이나 FastAPI Cloud 같은)는 그걸 찾지 못할 수도 있어요. 그래서 pyproject.toml의 entrypoint를 쓰는 쪽을 권장합니다.
fastapi dev
fastapi dev를 실행하면 개발 모드가 시작돼요.
기본적으로 auto-reload가 켜져 있어서, 코드를 바꾸면 서버가 자동으로 다시 로드돼요. 이 기능은 리소스를 많이 먹고, 꺼져 있을 때보다 덜 안정적일 수 있어요. 개발할 때만 사용해야 합니다. 또 IP 주소 127.0.0.1에서 수신하는데, 이건 자기 자신과만 통신하는 마신의 IP(localhost)예요.
앱을 import 하기 전에 fastapi dev는 FASTAPI_ENV 환경 변수를 development로 설정해요. 만약 FASTAPI_ENV가 이미 설정되어 있다면, 기존 값을 그대로 유지합니다. 이렇게 하면 앱 시작 코드가 개발 친화적인 동작을 고를 수 있으면서도, staging 같은 앱별 환경을 직접 제공할 수 있어요.
관례적인 FASTAPI_ENV 값은 development와 production이에요. fastapi run은 현재 FASTAPI_ENV를 변경하지 않으므로, 앱이 운영 모드를 감지해야 한다면 직접 설정해 주세요.
fastapi run
fastapi run을 실행하면 FastAPI가 운영(production) 모드로 시작돼요.
기본적으로 auto-reload는 꺼져 있어요. 또 IP 주소 0.0.0.0에서 수신하는데, 이는 사용 가능한 모든 IP 주소를 뜻해요. 이렇게 하면 그 머신과 통신할 수 있는 모두에게 공개적으로 접근 가능해집니다. 예를 들어 컨테이너 안에서 운영할 때 보통 이렇게 실행해요.
대부분의 경우 그 위에 HTTPS를 처리하는 "termination proxy"(종료 프록시)를 두는 게 일반적이고 권장되기도 해요. 이건 어떻게 배포하느냐에 따라 달라져요 — 제공자가 해 줄 수도 있고, 직접 설정해야 할 수도 있죠.
팁
이에 대해 더 자세히 알고 싶다면 배포 문서(deployment documentation)를 확인하세요.