본문으로 건너뛰기

드디어 진짜 서버를 띄웠습니다 - Claude Code로 FastAPI API 서버 만들기

Joy

2026.07.30

소개

시도하고자 했던 것과 그 이유를 알려주세요.

지난 글(api 서버 만들어보기)에서는 HTML 시뮬레이션으로 GET/POST 개념만 이해했습니다. 이번에는 그때 구상만 했던 세 가지 엔드포인트(GET /hello, GET /today-plan, POST /plan)를 실제로 동작하는 서버로 구현해 내 컴퓨터에서 띄우는 것이 목표였습니다. 브라우저와 PowerShell로 직접 요청을 보내 서버가 응답하는 전 과정을 확인했습니다.

진행 방법

어떤 도구를 사용했고, 어떻게 활용하셨나요?

Tip: 사용한 프롬프트 전문을 꼭 포함하고, 내용을 짧게 소개해 주세요.

Tip: 활용 이미지나 캡처 화면을 꼭 남겨주세요.

Tip: 코드 전문은 코드블록에 감싸서 작성해주세요. ( / 을 눌러 '코드 블록'을 선택)

활용한 툴: Claude Code(클코) - 서버 코드 작성·에러 해결 / FastAPI + uvicorn - 서버 프레임워크와 실행 엔진 / Windows PowerShell - 설치·실행·테스트 / 브라우저(Swagger UI) - /docs 화면 테스트

① Claude Code에게 서버 기본 구조 요청하기

프로젝트 폴더를 만들고 클코를 실행한 뒤, 지난 시뮬레이션에서 정한 세 가지 엔드포인트를 그대로 설명하며 요청했습니다. 사용한 프롬프트 전문: "FastAPI로 API 서버를 만들어줘. 엔드포인트는 3개야. 하나, GET /hello : 쿼리로 name을 받아서 '안녕하세요, {name}님!' 을 돌려줘. 둘, GET /today-plan : 서버가 가진 할 일 목록에서 안 끝난 것만 골라서 남은 시간 합계와 같이 돌려줘. 셋, POST /plan : 가용 시간(분)과 할 일 목록을 받아서 시간 안에 들어가는 일은 '오늘 할 일', 넘치는 일은 '내일로 미룰 일'로 나눠서 돌려줘. 파일은 main.py 하나로 만들어줘." 클코가 main.py 한 파일로 서버 전체를 작성해 줬습니다.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

@app.get("/hello")
def hello(name: str = "손님"):
    return {"message": f"안녕하세요, {name}님!"}

todos = [
    {"task": "은행 업무", "minutes": 30, "done": False},
    {"task": "발표자료 마무리", "minutes": 90, "done": False},
    {"task": "아침 운동", "minutes": 40, "done": True},
]

@app.get("/today-plan")
def today_plan():
    remaining = [t for t in todos if not t["done"]]
    total = sum(t["minutes"] for t in remaining)
    return {"남은_할일": remaining, "남은_시간_합계": f"{total}분"}

class PlanRequest(BaseModel):
    available_minutes: int
    tasks: list[dict]

@app.post("/plan")
def make_plan(req: PlanRequest):
    today, tomorrow, used = [], [], 0
    for t in req.tasks:
        if used + t["minutes"] <= req.available_minutes:
            today.append(t); used += t["minutes"]
        else:
            tomorrow.append(t)
    return {"오늘_할일": today, "내일로_미룰_일": tomorrow, "사용_시간": f"{used}분"}

② 패키지 설치하고 서버 실행하기

PowerShell에서 pip install fastapi uvicorn 으로 설치하고 uvicorn main:app --reload 로 실행했습니다. 그런데 'uvicorn 용어가 인식되지 않습니다' 에러가 나왔고, 클코에게 물어보니 Windows에서 스크립트 경로가 PATH에 안 잡힌 경우라며 python -m uvicorn main:app --reload 로 실행하라고 알려줬습니다. 'Uvicorn running on http://127.0.0.1:8000' 이 출력되며 서버가 살아있는 상태가 됐습니다. (📷 터미널 실행 화면)

③ 브라우저에서 GET 요청 테스트하기

주소창에 http://127.0.0.1:8000/hello?name=윤 을 입력하니 {"message": "안녕하세요, 윤님!"} 이 바로 표시됐습니다. 지난주 HTML 시뮬레이션으로 보던 장면이 진짜 서버에서 재현되는 순간이었습니다. /today-plan 도 남은 할 일 2건과 합계 120분을 정확히 돌려줬습니다. (📷 브라우저 응답 화면)

④ Swagger UI(/docs)에서 POST 테스트하기

POST는 주소창으로 테스트할 수 없다는 클코의 설명을 듣고, FastAPI가 자동으로 만들어주는 http://127.0.0.1:8000/docs 화면에서 Try it out 버튼으로 테스트했습니다. 가용 시간 120분에 할 일 3건(은행 업무 30분, 발표자료 마무리 90분, 블로그 글쓰기 60분)을 보냈더니, 앞의 두 건은 '오늘 할 일', 블로그 글쓰기는 '내일로 미룰 일'로 정확히 분류됐습니다. 서버가 데이터를 받아 판단하고 새 결과를 만들어내는 POST의 개념이 실제 코드로 확인됐습니다. (📷 Swagger UI 테스트 화면)

⑤ PowerShell로도 같은 요청 보내보기

인터넷에서 본 curl 명령을 그대로 붙여넣었더니 '매개 변수 이름 X를 찾을 수 없습니다' 에러가 났습니다. 클코에게 물어보니 PowerShell의 curl은 진짜 curl이 아니라 Invoke-WebRequest의 별칭이라는 답을 들었고, Invoke-RestMethod 명령으로 바꿔 성공했습니다. 브라우저든 터미널이든 앞으로 만들 AI 에이전트든, 서버 입장에서는 모두 같은 '요청'이라는 점을 이해했습니다.

결과와 배운 점

배운 점과 나만의 꿀팁을 알려주세요.

과정 중에 어떤 시행착오를 겪었나요?

도움이 필요한 부분이 있나요?

앞으로의 계획이 있다면 들려주세요.

배운 점: 개념을 먼저 잡고 코드로 넘어가는 순서가 비전공자에게 훨씬 효과적이었습니다. 지난주 시뮬레이션(그림)과 이번 주 실제 구현(실물)의 간격이 생각보다 크지 않았습니다. 서버는 결국 '요청을 기다리다가, 정해진 규칙대로 판단해서, 답을 돌려주는 프로그램'이라는 것을 알게 됐고, 4주차 목표인 24시간 AI 에이전트 서버의 그림이 그려지기 시작했습니다.

시행착오: 하나, 서버 재실행 시 '[WinError 10048] 각 소켓 주소는 하나만 사용할 수 있습니다' 에러가 났는데, 이전 프로세스가 백그라운드에 살아있던 것이 원인이었고 netstat -ano | findstr 8000 으로 PID를 찾아 taskkill로 종료해 해결했습니다. 둘, POST에서 available_minutes를 빼먹고 보냈더니 422 에러가 났는데, 서버 고장이 아니라 pydantic이 잘못된 요청을 걸러주는 정상 동작이었습니다. 에러가 무조건 실패가 아니라 서버가 스스로를 지키는 방식일 수 있음을 배웠습니다.

도움이 필요한 부분: 지금은 서버가 127.0.0.1(내 컴퓨터 안)에서만 동작합니다. 24시간 서버로 가려면 외부 접근이 필요한데, ngrok과 Cloudflare Tunnel 중 초보자에게 안전하고 적절한 방식이 무엇인지 코치님 추천이 필요합니다.

앞으로의 계획: 3주차에는 POST /plan의 시간 배분 로직에 Claude API를 연결해 고정 규칙이 아닌 AI가 우선순위를 판단하는 엔드포인트로 업그레이드하고, 백그라운드 실행과 자동 재시작을 적용해 24시간 도는 서버로 발전시킬 계획입니다.

도움 받은 글 (옵션)

참고한 지피터스 글이나 외부 사례를 알려주세요.

제 1주차 글 'api 서버 만들어보기'(GET/POST 개념 이해편)에서 구상한 엔드포인트를 그대로 구현했습니다. 스터디 같은 조 멤버들의 API 서버 사례글(강희주님의 GET/POST 이해하기, 나병우님의 첫 API 서버 띄운 하루)도 큰 도움이 됐습니다.

1

함께 이야기해요 1

로그인하고 댓글을 남겨 주세요

kim 프로필 이미지
kim2026.07.30

안녕하세요 조이님 여쭤볼게 있는데 지피터스는 처음이라 혹시 시간이 되시면 잠시 대화 가능할까요?

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기