튜토리얼 헬을 탈출하고 실제 코드를 배포하는 방법

Source: Dev.to

번역을 진행하려면 전체 텍스트를 제공해 주시겠어요? 텍스트를 주시면 요청하신 대로 한국어로 번역해 드리겠습니다.

Source:

튜토리얼 지옥의 순환을 끊어라

튜토리얼을 끝냈다. todo 앱이 동작한다. 이제 준비가 된 느낌이다.

그런 다음 빈 편집기를 열어 실제 무언가를 만들려고 하지만, 전혀 진행되지 않는다.

튜토리얼은 질문과 답변을 모두 제공한다. 실제 프로젝트는 질문만 제공한다.

아래는 5가지 구체적인 단계—각 단계마다 실제 예시가 포함된—로 “막힌” 상태에서 작동하는 독창적인 프로젝트로 나아가는 방법이다.

Step 1: 실제로 필요로 하는 문제를 선택하라

모든 튜토리얼은 “…을 만들어 보자”라는 문구로 시작하고 미리 선정된 문제를 제공한다. 이것이 첫 번째 함정이다: 소프트웨어 개발에서 가장 어려운 부분인 무엇을 만들지 결정하는 과정을 절대 연습하지 못한다.

실제로 필요로 하는 것부터 시작하라. 인상적일 필요는 없으며, 당신에게 유용하기만 하면 된다.

잘못된 선택

• “소셜 미디어 클론을 만들겠다” – 규모가 너무 크고 개인적인 연결이 없다.
• “블록체인 앱을 만들겠다” – 필요하지 않다.
• “전자상거래 사이트를 만들겠다” – 이미 Shopify가 있다.

올바른 선택

• 다운로드한 파일을 날짜별로 이름을 바꾸는 스크립트.
• 올해 읽은 책을 추적하는 API.
• 즐겨 찾는 웹사이트가 다운됐는지 확인하는 CLI 도구.

규칙: 실제로 사용할 수 있다면, 실제로 완성할 수 있다.

Step 2: 코드보다 먼저 README 작성하기

대부분의 초보자는 이 단계를 건너뛴다. 바로 코딩에 뛰어들어 아키텍처 결정에 막히고 포기한다.

1. README.md 파일을 만든다.
2. 다음 세 가지 질문에 답한다:

# Book Tracker API

이것은 무엇을 하나요?

올해 내가 읽은 책을 추가하고, 목록을 보고, 삭제할 수 있는 간단한 REST API입니다.

대상은 누구인가요?

저 – 스프레드시트를 열지 않고도 읽기 진행 상황을 빠르게 확인하고 싶어요.

Source: …

어떻게 작동하는지 확인할 수 있나요?

• GET /books는 내 책들의 JSON 배열을 반환합니다.
• POST /books는 새 책을 추가하고 생성된 레코드를 반환합니다.
• DELETE /books/:id는 책을 삭제하고 204 상태 코드를 반환합니다.

Having this “contract” up front guides your design and keeps you focused.

Step 3: 최소 실행 가능한 제품 (MVP) 스케치

생각할 수 있는 모든 기능을 만들려고 하지 마세요. README를 만족시키기 위해 절대적으로 필요한 최소 항목을 나열하세요.

이제 명확하고 작은 범위가 정해졌습니다.

Step 4: 가장 작은 스택 선택

이미 충분히 익숙해서 생산성을 낼 수 있는 도구를 선택하되, MVP를 완성할 수 있을 정도로만 사용하세요.

• 언어: Node.js (JavaScript) – 튜토리얼에서 사용해 본 적이 있습니다.
• 프레임워크: Express – 최소한의 라우팅, 보일러플레이트 없음.
• 데이터 저장소: fs를 이용한 JSON 파일 – 데이터베이스 설정 필요 없음.
• 테스트: Jest – 각 엔드포인트에 대한 간단한 단위 테스트.

새 라이브러리를 배워야 한다면, 문서가 잘 된 하나의 컴포넌트에만 국한하세요.

Step 5: 구현, 테스트, 반복

1. 구현 – MVP 표에 있는 순서대로 엔드포인트를 하나씩 구현합니다.
2. 테스트 작성 – 코드를 작성하기 전에 각 엔드포인트에 대한 테스트를 작성합니다 (테스트 주도 개발).
3. 테스트 실행 – 실패해야 합니다.
4. 코드 작성 – 테스트를 통과하도록 코드를 작성합니다.
5. 리팩터링이 필요하면 수행하고, 다음 엔드포인트로 이동합니다.

구체적인 README, MVP 리스트, 그리고 작은 스택이 있으면 트랙을 벗어나지 않고 튜토리얼 복제본이 아닌 실제 사용 가능한 프로젝트를 완성할 수 있습니다.

끝까지…

당신은 실제로 사용하게 될 작동하는 Book Tracker API를 갖게 될 것이며, 당신이 관심 있는 문제에서 출발해 명확한 사양, 최소한의 범위, 그리고 관리할 수 있는 스택으로 구축됩니다. 이 프로세스는 향후 어떤 아이디어에도 재사용할 수 있어 “튜토리얼 지옥”을 실제 개발 자신감으로 바꿔줍니다.

What does it do?

• 내가 읽은 책을 추적합니다.
• 제목, 저자, 완료 날짜, 그리고 1‑5점 평가를 저장합니다.
• 저자나 평점으로 검색할 수 있습니다.

어떻게 사용하나요?

어떤 기술?

Python + FastAPI + SQLite

Step 3 – 가장 작은 동작 버전 먼저 만들기

메모리 내 API부터 시작합니다 (DB, 인증, 배포 없이).

# main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()
books: list[dict] = []
next_id: int = 1

class BookCreate(BaseModel):
    title: str
    author: str
    rating: int

@app.post("/books")
def add_book(book: BookCreate):
    global next_id
    entry = {"id": next_id, **book.model_dump()}
    books.append(entry)
    next_id += 1
    return entry

@app.get("/books")
def list_books(author: str | None = None):
    if author:
        return [b for b in books if b["author"].lower() == author.lower()]
    return books

@app.delete("/books/{book_id}")
def delete_book(book_id: int):
    for i, b in enumerate(books):
        if b["id"] == book_id:
            return books.pop(i)
    raise HTTPException(status_code=404, detail="Book not found")

실행:

pip install fastapi uvicorn
uvicorn main:app --reload

http://localhost:8000/docs 에서 인터랙티브 문서를 확인하세요.

Step 4 – 한 번에 하나씩 기능 추가

예시 테스트 (test_main.py):

from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_add_and_list_books():
    resp = client.post("/books", json={"title":"TAOCP Vol 1","author":"Knuth","rating":5})
    assert resp.status_code == 200
    data = resp.json()
    assert data["title"] == "TAOCP Vol 1"
    assert data["id"] == 1

    resp = client.get("/books")
    assert resp.status_code == 200
    assert len(resp.json()) >= 1

테스트 실행:

pip install pytest httpx
pytest test_main.py -v

검증 예시:

from pydantic import BaseModel, Field

class BookCreate(BaseModel):
    title: str = Field(min_length=1, max_length=200)
    author: str = Field(min_length=1, max_length=100)
    rating: int = Field(ge=1, le=5)

잘못된 페이로드는 이제 자동으로 422 오류를 반환합니다.

Step 5 – 사람들이 볼 수 있는 곳에 배포

1. GitHub 저장소를 생성합니다.
2. 코드를 푸시합니다.
3. 다음 내용을 포함한 README를 작성합니다:
   • 프로젝트 설명.
   • 로컬 실행 방법 (pip install, uvicorn).
   • 테스트 명령 (pytest).
   • 향후 로드맵 (주차 3‑4).

간결하고 구조화된 README는 동작하는 코드와 앞으로의 계획을 모두 보여주어, 주니어 개발자 포트폴리오에 핵심적인 요소가 됩니다.

향후 개선 사항

• SQLite로 인‑메모리 저장소 교체
• JWT를 사용한 사용자 인증 추가
• Railway 또는 Render에 배포
• 대규모 도서 목록에 페이지네이션 추가

이것들은 막연한 바람이 아닙니다. 각 라인은 구체적이고 구현 가능한 기능입니다. 이것이 “시간이 부족했다”와 “다음에 무엇을 할지 정확히 안다”의 차이점입니다.

이 단계 뒤의 패턴

우리가 하지 않은 것을 확인하세요:

• 우리는 먼저 12시간짜리 강의를 보지 않았습니다.
• 우리는 “상위 10개 포트폴리오 프로젝트” 목록에서 프로젝트를 선택하지 않았습니다.
• 우리는 비즈니스 로직 한 줄도 작성하기 전에 Docker, CI/CD, 혹은 클라우드 데이터베이스를 설정하지 않았습니다.
• 우리는 시작하기 전에 모든 것을 배우려고 시도하지 않았습니다.

우리는 실제 문제를 선택하고, 사양을 작성하고, 가장 작은 버전을 구축한 뒤, 기능을 점진적으로 추가하고, 이를 공개했습니다. 이것이 전문 소프트웨어가 만들어지는 방식입니다. 튜토리얼은 문법을 가르치고, 프로젝트는 판단력을 가르칩니다.

아직 튜토리얼 지옥에 있는 신호들

스스로에게 솔직해지세요. 다음 중 하나라도 해당된다면 아직도 갇혀 있는 것입니다:

• 따라서는 할 수 있지만 처음부터 만들지는 못한다. 튜토리얼을 닫고 빈 파일을 열어 보세요. 뭔가를 찾아보지 않고 첫 10줄을 작성할 수 없다면, 더 많은 연습이 필요합니다. 튜토리얼이 아니라 직접 만드는 연습을 해야 합니다.
• GitHub에 원본 프로젝트가 전혀 없다. 포크한 레포지토리와 튜토리얼 복제본은 인정되지 않습니다. 스스로 설계한 하나의 투박하지만 동작하는 프로젝트가 다듬어진 튜토리얼 복제본 열 개보다 더 가치 있습니다.
• 프로젝트를 완성하지 못하고 새로운 강좌를 계속 시작한다. 다음 강좌가 문제를 해결해 주지는 않을 겁니다. 해결책은 작은 것이라도 무언가를 배포하는 것입니다.
• 코드를 보여주는 것이 두렵다. 푸시하세요. 완벽할 필요는 없습니다. 첫 번째 프로젝트가 완벽한 사람은 없습니다. 여러분이 존경하는 개발자들도 초기에는 부끄러운 코드를 배포했습니다.

탈출 후에 일어나는 일

한 번 처음부터 프로젝트를 만들면 두 번째는 더 쉬워집니다. 세 번째는 더 빨라집니다. 다섯 번째가 되면 문법에 대해 생각하는 것을 멈추고 설계에 대해 생각하기 시작합니다.

이것이 튜토리얼을 따르는 사람과 빌더 사이의 실제 실력 차이입니다. 빌더는 코드가 이렇게 구조화된 이유를 생각합니다. 튜토리얼은 코드가 어떻게 생겼는지만 보여줍니다.

첫 번째 프로젝트는 엉망일 것입니다. 버그가 있을 것이고, 이름 짓기가 일관되지 않을 것이며, 오류 처리가 불완전할 것입니다. 그래도 배포하세요.

고용주는 가장 깔끔한 코더를 고용하는 것이 아니라, 실제 무언가를 배포하고 그 혼란에서 배워 다음 번에 더 나은 것을 배포한 사람을 고용합니다.

오늘 시작하세요. 문제를 고르세요. README를 작성하세요. 가장 작은 버전을 만드세요. 기능 하나를 추가하세요. 푸시하세요.

더 많은 프로그래밍 및 커리어 콘텐츠를 보려면 @klement_gunndu를 팔로우하세요. 우리는 공개적으로 빌드하고 있습니다.