소개
시도하고자 했던 것과 그 이유를 알려주세요.
지난 글(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 서버 띄운 하루)도 큰 도움이 됐습니다.
