FastAPI API 구축자: 설계부터 배포까지
사용자를 여섯 가지 단계로 안내합니다: 이해 → 설계 → 구축 → 테스트 → 패키징 → 배포. 결과를 바꾸는 것만 질문하고, 나머지는 가정을 선언한 후 단계별 승인 없이 구축합니다.
책임 및 한계
- 사용 가능한 환경에서 코드를 생성하고 테스트합니다.
- 실제 배포는 사용자가 자신의 계정이나 서버에서 실행합니다. 어시스턴트는 일반적으로 액세스 권한이 없기 때문입니다. 정확한 명령어와 확인 단계를 제공합니다.
- 환경이 서버 또는 플랫폼 CLI에 액세스할 수 있는 경우(예: Claude Code), 필요한 사용자 확인을 받은 후에만 작업을 실행합니다.
- 테스트나 배포를 수행할 수 없는 경우 실행했다고 주장하지 않습니다.
1단계: 이해(핵심 질문 한 라운드)
코드를 작성하기 전에 아키텍처를 변경하는 사항을 명확히 합니다. 터치 가능한 옵션이 있는 질문 도구(ask_user_input_v0)가 있으면 사용하고, 없으면 짧은 목록을 만듭니다. 최대 서너 개의 질문이며 이미 답변된 것은 생략합니다:
- 목적 및 리소스: API가 무엇을 하는지, 어떤 엔티티(예: 고객, 청구서, 주문)를 대상으로 하며, 어떤 작업이 필요한가요?
- 지속성: 데이터베이스 없음, SQLite(프로토타입) 또는 PostgreSQL?
- 소비자 및 액세스: 누가 호출하나요?(RPA 봇/Automation Anywhere, 웹 앱, 다른 서비스) 공개 또는 내부여야 하나요? 이는 인증 및 배포를 결정합니다.
- 대상: 이미 알고 있다면 사용하고, 그렇지 않으면 6단계의 옵션을 제시하고 구축을 차단하지 않으면서 하나를 추천합니다.
나머지는 합리적인 값(FastAPI, API 키, 통일된 오류 형식, pytest, Docker)을 가정하고 한 줄로 선언합니다.
2단계: 설계
구축하기 전에 사용자가 수정할 수 있도록 간결한 설계를 제시합니다. 사용자가 확인하거나 반대하지 않으면 구축을 계속합니다:
- 엔드포인트 표: 메서드, 경로, 함수 및 응답 코드.
- 입력/출력 모델: 필드 및 유효성 검사.
- 선택한 인증 및 이유;
references/auth.md가 있으면 참조합니다.
REST 규칙: 복수형 명사(/clientes), 작업에 HTTP 동사 사용, 생성 시 201, 삭제 시 204, 존재하지 않으면 404, 잘못된 데이터는 422, 자격 증명 없으면 401.
3단계: 구축
사용 가능한 경우 스캐폴드를 사용하여 입증된 템플릿을 다시 작성하는 대신 복사합니다:
python <skill-경로>/scripts/scaffold.py "<프로젝트-이름>" --out /home/claude
템플릿을 설계에 맞게 조정합니다:
- 예제 리소스
app/routers/items.py및app/schemas.py를 필요한 리소스로 교체합니다. app/main.py에서include_router로 라우터를 등록합니다.- 새 변수에 대해
app/config.py및.env.example을 조정합니다. - 데이터베이스가 있으면
references/database.md가 있는지 확인합니다. - 사용자 로그인이 필요하면
references/auth.md가 있는지 확인합니다. - 소비자가 Automation Anywhere인 경우
references/aa-integration.md가 있는지 확인하고 해당 계약(명확한 HTTP 코드,status와 유용한 메시지가 포함된 JSON)을 적용합니다.
사용할 수 없는 템플릿 파일이나 참조를 만들지 마십시오. 존재하지 않으면 명시적으로 동등한 솔루션을 만듭니다.
계층 구조(라우터, 스키마, 구성, 보안)는 성장을 용이하게 합니다. Pydantic은 로직 전에 데이터를 검증합니다. 전역 핸들러는 내부 세부 정보를 500 오류에서 필터링하지 않고 {"status":"error","message":"..."}와 같은 통일된 오류를 반환합니다. Docker, 로드 밸런서 및 플랫폼을 위해 /health를 포함합니다. 환경 변수로 구성: 로컬 및 프로덕션에서 동일한 코드, 저장소 외부의 비밀.
4단계: 테스트
환경이 허용할 때 항상 전달하기 전에 실행하고 실패를 수정하여 통과할 때까지 반복합니다:
cd <프로젝트> && pip install -r requirements-dev.txt && python -m pytest -q
각 새 엔드포인트에 대한 테스트를 추가합니다: 정상 케이스, 잘못된 데이터, 리소스를 찾을 수 없음, 해당하는 경우 인증 없음. 가능하면 실제 서버(uvicorn app.main:app --port 8000)를 시작하고 curl로 /health, 보호된 엔드포인트(키 있음/없음), /docs를 확인합니다. 일부 테스트를 실행할 수 없는 경우 이유와 무엇이 누락되었는지 설명합니다.
5단계: 패키징
- Dockerfile은 권한 없는 사용자로 실행되고
$PORT에서 수신 대기해야 Render, Railway, Cloud Run 및 VPS에서 동일하게 작동합니다. .dockerignore및.gitignore는.env를 제외해야 합니다. 코드나 제공된 파일에 비밀이 없는지 확인합니다.- 해당 도구를 사용할 수 있는 경우
/mnt/user-data/outputs/에 전체 프로젝트를present_files로 압축하여 제공합니다. 그렇지 않으면 유용한 형태로 구조와 파일을 제공하고 ZIP을 만들었다고 주장하지 않습니다. - 간단한 요약 포함: 로컬에서 실행하는 방법, 필요한 환경 변수 및 엔드포인트.
프로덕션 전 목록
-
API_KEY(또는 JWT)가 길고 무작위 값으로 정의되고 플랫폼에서 비밀로 저장됨. -
CORS_ORIGINS가 명시적 목록으로 설정됨,*아님. -
ENVIRONMENT=production. - 지속적 데이터베이스 및 백업 있음. 임시 디스크에서 SQLite를 사용하지 않음.
- HTTPS 활성화. HTTP를 통해 API 키를 절대 노출하지 않음.
-
.env가 저장소 외부에 있음. - 테스트 통과 및
/health응답. - 로그에 액세스 가능하고 5xx 오류 시 경고.
6단계: 배포
사용자가 대상을 선택하지 않은 경우 이 비교를 제시하고 사례에 따라 추천합니다. 인프라 경험이 적으면 PaaS, 내부 네트워크 또는 완전한 제어가 필요한 경우 VPS/자체 서버, 회사에서 이미 클라우드를 사용하는 경우 해당 클라우드의 관리형 컨테이너.
| 옵션 | 노력 | 제어 | 일반 비용 | 최적 대상 |
|---|---|---|---|---|
| Docker on VPS 또는 자체 서버 | 중간 | 완전 | 고정 및 낮음 | 내부 네트워크, 제어, 예측 가능한 비용 |
| PaaS (Render, Railway, Fly.io) | 낮음 | 중간 | 낮음-중간, 사용량 기준 | 빠른 출시, 소규모 팀 |
| 클라우드 (Cloud Run, Container Apps, App Runner/ECS) | 중간-높음 | 높음 | 사용량 기준 | 클라우드 사용 기업, 확장, 규정 준수 |
선택 후 해당 가이드만 참조합니다(있는 경우):
references/deploy-vps-docker.mdreferences/deploy-paas.mdreferences/deploy-cloud.md
외부 플랫폼의 명령어와 화면은 변경됩니다. 사용자가 인터페이스가 일치하지 않는다고 표시하면 업데이트되지 않은 지침을 고집하지 말고 현재 문서를 참조합니다.
배포 후 확인으로 마무리합니다:
curl https://<url>/health
/docs를 열고, 엔드포인트를 키 있음/없음으로 테스트하고(키 없으면 401 응답해야 함), 로그를 확인합니다. 실패하면 오류 또는 로그를 요청하고 진단합니다. 일반적인 문제: 잘못된 포트(앱이 $PORT에서 수신해야 함), 누락된 환경 변수, postgres:// 대신 postgresql://, CORS가 프론트엔드를 차단.
최종 제공 형식
간결하고 유용하게 유지하며 다음을 포함합니다:
- 무엇을 구축했고 어떤 가정을 했는지.
- 로컬에서 실행하는 명령어.
- 필수 환경 변수.
- 엔드포인트 표.
- 선택한 배포의 다음 단계.
파일 내용을 불필요하게 반복하지 마십시오.