코드 한 줄 안 쳐본 비전공자가, 내 PC에 첫 API 서버를 띄운 하루

24시간 AI 서버 만들기 스터디 · 1주차 과제 기록

📝 한 줄 요약

"코드는 Claude Code가 씁니다. 우리는 시키고, 확인합니다." — 이 한 문장을 믿고, 비전공자인 제가 제 맥에 서버 하나와 API 엔드포인트 3개를 직접 띄우고 확인해봤습니다. 결과보다 원리를 하나씩 파고든 하루였어요.

바쁘시면 이것만 읽어도 돼요:

목표: 내 PC에 24시간 돌아갈 수 있는 서버의 '첫걸음' — API 서버를 직접 세팅해보기
만든 것: Python + FastAPI로 '오늘 할 일(To-Do) API' (엔드포인트 3개)
깨달은 것: 코드를 짜는 것보다 "왜 이렇게 동작하는지"를 아는 게 진짜 실력이라는 것
인상 깊었던 순간: 서버를 켜고 꺼본 것, 터미널 2개를 열어놓고 한쪽에는 서버를, 한쪽에는 클라이언트를 띄워 비교하며 시연해본 것
교훈: AI가 다 만들어줘도, "확인"하려면 바닥 원리를 알아야 한다

🎯 이런 분들께 도움돼요

"서버", "API"라는 말만 들어도 막막한 완전 비전공자
AI한테 시켜서 뭔가 만들긴 했는데, 원리는 하나도 모르겠는 분
내 PC에 나만의 서버를 직접 세팅해보고 싶은 분

😫 문제 상황 (Before)

스터디장님에게 받은 미션은 딱 이 다섯줄이었습니다

오늘 만들 것 — 서버 하나, 엔드포인트 세 개
① GET /hello — 인사말 JSON. 몸풀기입니다.
② GET /나만의-무언가 — 내 소재로 엔드포인트 하나.
③ POST /나만의-무언가 — 데이터를 받아서, 그걸 섞어 돌려주기.
언어는 자유. 코드는 Claude Code가 씁니다. 우리는 시키고, 확인합니다.

이게 도대체 무슨 외계어야?
앞도 뒤도 없이,
웃으면서, 이 다섯줄 문장 보여주면서,
누구나 다 만들 수 있다는거에요..

'엔드포인트'? 'GET'? 'POST'? 하나도 감이 안 왔습니다.

스터디장님은 냅다 AI에게 시키라고 했지만,
저는 오히려 AI에게 이렇게 요청하며 시작했어요.

찬찬히 개념들을 설명해주고,  
나에게 확인할 것들을 물어본 뒤 작업해줘

'모른다'는 걸 인정하고, 천천히 개념부터 잡는 것으로 방향을 잡았습니다.

🛠️ 사용한 도구 (제가 ❌ , 클로드코드가 ⭕)

AI 코딩 도구: Claude Code (Opus 4.8)

언어/프레임워크: Python + FastAPI

서버 실행: uvicorn

확인 방법: 터미널(curl), 브라우저 자동 문서(/docs)

🔧 작업 과정

개념 잡기 (코딩 시작 전에 AI가 나에게 정리해준 내용)

1. 서버(server) — 요청 받으면 답 주는 프로그램
2. 엔드포인트(endpoint) — 서버가 작동할 수 있는 명령 하나하나
3. GET / POST — 명령의 종류, 메소드 (GET=보여줘, POST=처리해줘)
4. 엔드포인트 3개 : ① GET /hello, ② GET /나만의-무언가, ③ POST /나만의-무언가
5. JSON — 데이터를 주고받는 글자 형식

무엇을 만들지부터 '내가' 정하기

AI가 코드를 쓰기 전에, 먼저 저에게 두 가지를 물어봤습니다.
어떤 언어로 할지, 그리고 '나만의 무언가'를 무엇으로 할지요.
1) 언어 → Python (FastAPI): 입문에 쉽고, 만들면 자동으로 문서 화면이 생겨서
'확인'하기 좋다고 해서 골랐어요.
2) 주제 → 오늘 할 일(To-Do): 가장 직관적이라 이걸로 정했습니다.
미션의 핵심이 '내가 시키고, 내가 정하는 것'이라는 걸 여기서 처음 느꼈어요.

① 인사 API — 서버가 살아있다는 첫 신호

가장 먼저 GET /hello를 만들었습니다.
터미널에 이렇게 쳤더니,
curl http://127.0.0.1:8001/hello
이런 답이 돌아왔어요.
{"message":"안녕하세요! 서버가 잘 살아있어요 👋"}
내 컴퓨터 안에서 서버가 실제로 대답을 한 순간이었습니다. 별것 아닌데 은근히 감동적이었어요.

② 오늘 할 일 API — 데이터를 보여주고, 받아서 처리하기

다음은 GET /todos(할 일 목록 보여주기)
터미널에 이렇게 쳤더니,
curl http://127.0.0.1:8001/todos
이런 답이 돌아왔어요.
{"count":2,"todos":[{"id":1,"task":"우유 사기","done":false},{"id":2,"task":"운동 30분","done":false}]}

마지막으로 POST는 제가 명령과 데이터를 함께 보내면 서버가 제 데이터를 갖고 뭔가 작업하고서 그 결과를 돌려주는 거였는데요.
터미널에 이렇게 쳤더니
curl -X POST http://127.0.0.1:8001/todos -H "Content-Type: application/json" -d '{"task": "책 읽기"}'
이런 답이 돌아왔어요.
{"message":"'책 읽기' 할 일을 추가했어요! ✅","added":{"id":3,...},"total":3}

여기서 제가 궁금했던 게 있어요. "-d가 '더해달라'는 뜻이야?" 라고 물었더니, -d는 그냥 '보낼 데이터(data)'일 뿐이고, 실제로 '더하는' 일은 서버 코드가 미리 그렇게 정해놨기 때문에 일어난다는 답을 들었습니다. 그러면, '빼는' 일은 어떻게 하냐고 물었더니, 오늘 배운 GET, POST외에 다른 메소드를 사용한다고 알려주더라구요. 즉, 서버의 모든 작업은 미리 철저하게 약속된 규칙대로 일어난다는 것을 알게 되었습니다.

③ '포트'와 '404'의 의미를 제대로 알게 되다

서버를 처음 띄울 때 8000번 포트가 이미 사용 중이라며, AI가 알아서 8001번으로 바꿔서 실행해줬어요. 저는 이 과정을 보며 '포트'가 뭔지를 정확히 이해하게 됐습니다 — 한 컴퓨터 안에서 프로그램마다 배정받는 번호가 붙은 문 같은 거고, 이미 누가 쓰고 있으면 다른 번호를 써야 한다는 것을요.
또 제가 주소를 /todo로 잘못 쳤을 때 404 Not Found가 떴는데, 이건 에러가 아니라 "그런 창구는 없어요"라는 정중한 대답이더라고요. 철자 하나 's'가 이렇게 중요할 줄이야.

④ 서버를 껐다 켜는 방법을 알고 싶었다 — 그러다 진짜 실행파일을 발견하다

솔직히 여기서부터가 진짜였습니다. To-Do API 3개 실습은 금방 끝났고,
제일 먼저 궁금했던 건 "이 서버를 내 마음대로 껐다 켜려면 어떻게 하지?" 였어요.
그래서 끄는 법과 켜는 법을 물어봤습니다.

끄기 : 서버 로그가 흐르는 창에서는 Ctrl + C, 백그라운드로 돌 때는 lsof로 PID(프로세스 번호)를 찾아 kill로 종료
켜기 : ./venv/bin/uvicorn main:app --port 8001 — "uvicorn아, main.py의 app을 8001번 포트에서 켜라"는 뜻

그런데 여기서 이상한 게 눈에 띄었어요. 파이썬 코드니까 당연히 python main.py로 켜질 줄 알았는데, 정작 서버를 켜는 건 uvicorn이더라고요. 알고 보니 main.py에는 '서버 설계도(app)'만 들어있고, 그걸 실제로 구동하는 진짜 실행 주체는 uvicorn이었습니다. 이게 오늘의 큰 전환점이었어요 — "아, 실행되는 파일이 따로 있구나."

⑤ uvicorn 파일을 열어보다, 실행의 뿌리까지, 꼬리에 꼬리를 묻는 서버 공부

"uvicorn이 뭐길래 이걸로 서버를 켜지?" 하는 궁금증에, 저는 venv/bin/uvicorn이라는 파일을 직접 열어봤습니다.
그런데 이 파일은 확장자도 없는데(그냥 uvicorn), 열어보니 안에는 파이썬 코드가 텍스트로 들어있고, 그런데도 실행이 되는 거예요. 어떻게 이게 가능한지 물으며 원리를 파고들었고, 질문이 꼬리에 꼬리를 물었습니다.

확장자도 없는 파일이 왜 실행되지? → 파일 첫 줄의 셰뱅(#!...python)과 실행권한 덕분. 맥/리눅스는 확장자가 아니라 이 둘로 실행을 판단한다는 것 (윈도우는 .exe가 필요)

uvicorn이랑 FastAPI는 같은 거야? → 아니, HTTP 서버(문지기)와 앱(요리사)으로 역할이 다른 별개. 프로토콜(HTTP)을 실제로 켜는 건 uvicorn

그럼 FastAPI 코드는 어디 있어? → 설치한 라이브러리는 site-packages 폴더에 실제 코드 파일로 존재한다는 것

우리가 안 만든 /docs 문서 화면은 어디서 나왔지? → app = FastAPI() 한 줄이 자동으로 만들어준 것

'서버를 어떻게 끄고 켜지?'라는 단순한 궁금증에서 시작한 게, 파일 하나를 열어보는 데까지 이어지고, 결국 서버의 실행 원리 전체로 번졌어요. 과제 범위를 한참 넘어섰지만, 그만큼 머릿속에 지도가 그려졌습니다.

⑥ 혼자 실습으로 마무리

마지막엔 AI 없이 혼자 해봤어요. 터미널 창을 2개 열어놓고, 한쪽에선 서버를 띄우고 다른 쪽에서 요청을 보내며 반응을 비교했습니다. 데이터를 더해보고, 일부러 없는 엔드포인트도 입력해보고, 앞서 배운 대로 lsof로 PID를 찾아 kill로 서버를 끄고, uvicorn으로 다시 켜보기도 했고요. 배운 걸 내 손으로 재현하니 비로소 '내 것'이 된 느낌이었습니다.

✅ 결과 (After)

Before vs After

서버·API 이해 — Before: "그게 뭔데?" / After: 서버·엔드포인트·HTTP 메서드를 설명할 수 있음
내 PC에 서버 — Before: 상상도 못 함 / After: 직접 띄우고 끄고 확인 가능
터미널 — Before: 무섭고 낯섦 / After: curl, lsof, kill, uvicorn 단어와 친숙(?)해짐
AI 활용 — Before: 시키기만 함 / After: 시키고, 결과를 확인할 수 있음

결과물

엔드포인트 3개짜리 To-Do API 서버 (main.py)
실행/확인 방법 정리(README.md)와 개념 요약(학습노트.md)
그리고 무엇보다 — "내 PC에서 서버가 돌아간다"는 경험 그 자체

💬 이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. "모른다"고 솔직하게 말하고, 천천히 가달라고 요청하기. "찬찬히 설명하고, 물어볼 걸 물어본 뒤 작업해줘"라고 하니 AI가 제 속도에 맞춰줬어요.
2. 결과가 나와도 "왜?"를 계속 묻기. 코드가 도는 걸 넘어 원리를 물으니 이해가 훨씬 깊어졌습니다.
3. AI 설명을 그냥 믿지 말고, 직접 돌려서 대조하기. 실제로 AI가 "포트는 하나만 잡는다"고 한 걸 제가 lsof로 확인하니 둘 다 잡고 있었고, 그 덕에 더 정확한 설명을 들을 수 있었어요.

이렇게 하면 안 돼요

1. 원리를 건너뛰고 "되기만 하면 됐지"로 넘어가기. 문제가 터지면(포트 충돌, 오타 404) 결국 그 원리를 알아야 해결됩니다.
2. 터미널 창을 그냥 닫아버리기. 서버가 그 창의 '자식'이라 같이 죽어버려요. 백그라운드로 살리려면 따로 방법이 필요합니다.

🌍 다른 업무에 적용한다면?

오늘 배운 '서버에 요청을 보내고 응답을 받는' 구조는 사실 우리가 매일 쓰는 앱·웹의 작동 원리 그대로예요. 이 감각이 생기니, 앞으로 내가 필요로 하는 작은 자동화 도구(예: 반복 업무를 대신 처리해주는 나만의 API)를 직접 세팅해볼 수 있겠다는 자신감이 생겼습니다.

🚀 앞으로의 계획

CRUD 모두 해보기: 오늘은 조회(GET)·추가(POST)까지 했으니, 다음엔 수정(PUT)·삭제(DELETE) 엔드포인트도 추가해보기
데이터 안 날아가게: 지금은 서버를 끄면 데이터가 사라져요. 다음 단계인 데이터베이스(DB) 연결에 도전
진짜 24시간 서버로: 내 PC(또는 클라우드)에서 꺼지지 않고 계속 도는 내가 실제로 필요한 기능을 담은 서버 세팅해보기 : 이번 스터디의 최종 목표

코드 한 줄 안 쳐본 비전공자였지만, 오늘 하루로 "나도 내 서버를 만질 수 있다"는 감각을 얻었습니다.

AI가 코드를 대신 써주는 시대에, 제가 할 일은 잘 시키고, 제대로 확인하는 것 — 그 첫 연습을 마쳤습니다. 🙌

🔥<24기 AI 스터디> 얼리버드 신청하기 🔥