1강. 백엔드와 API 서버의 역할

?1. 이번 강의에서 해결할 문제

프론트엔드에 게임 점수를 배열로만 저장하면 새로고침과 다른 기기에서 기록이 사라집니다. 브라우저가 데이터를 요청하고 서버가 규칙을 검사한 뒤 데이터베이스에 저장하는 경계를 정합니다.

✓2. 학습 목표

✓이 강의를 마치면

• 프론트엔드, API 서버, 데이터베이스의 책임을 구분합니다.
• REST API의 요청과 응답 흐름을 설명합니다.
• 26강 동안 만들 게임 기록·랭킹 API의 범위를 정의합니다.

◇3. 핵심 개념

백엔드는 클라이언트가 직접 신뢰해서는 안 되는 일을 맡습니다. 점수가 0 이상인지 검사하고, 로그인 사용자를 확인하며, 기록을 영구 저장하고, 여러 기록에서 랭킹을 계산합니다. API는 이 기능을 URL, HTTP 메서드, JSON 형식으로 공개한 계약입니다.

먼저 구분할 용어

용어	역할	게임 랭킹 예
클라이언트	서버 기능을 요청하는 프로그램	브라우저, 게임 실행 파일
백엔드	요청을 검증하고 업무 규칙을 실행하는 서버 코드	FastAPI 앱
API	요청 방법과 응답 형식을 정한 약속	POST /records와 JSON
데이터베이스	서버가 영구 데이터를 저장·조회하는 계층	사용자와 점수 기록
HTTP	요청·응답을 전달하는 통신 규칙	메서드, 경로, 상태 코드
JSON	구조화된 값을 주고받는 텍스트 형식	{"score": 1200}

프론트엔드의 검증은 빠른 안내를 위해 필요하지만 보안 경계가 아닙니다. 사용자는 개발자 도구나 별도 프로그램으로 요청을 직접 만들 수 있습니다. 서버는 점수 범위, 로그인 사용자, 대상 리소스 접근 권한을 항상 다시 확인해야 합니다.

브라우저 ── HTTP/JSON ──> FastAPI ── SQL ──> 데이터베이스
   ↑                         │                    │
   └──── 상태 코드 + JSON ───┴──── 조회 결과 ─────┘

기록 생성 요청을 한 단계씩 따라가기

1. 브라우저가 POST /records로 게임 이름과 점수를 JSON으로 보냅니다.
2. FastAPI가 JSON 모양과 값의 범위를 검사합니다.
3. 인증 정보로 "누가 이 기록을 만들려는가"를 확인합니다.
4. 서버가 직접 계산하거나 검증한 값을 데이터베이스 트랜잭션으로 저장합니다.
5. 성공하면 새 기록과 201 Created, 잘못된 입력이면 오류 내용과 4xx 상태 코드를 반환합니다.
6. 브라우저는 상태 코드에 따라 성공 목록을 갱신하거나 오류 메시지를 보여 줍니다.

새로 고침해도 기록이 남는 이유는 프론트엔드 배열이 아니라 데이터베이스에 저장했기 때문입니다. 다른 기기에서도 같은 사용자 기록을 요청할 수 있지만, 그 사용자가 볼 권한이 있는지는 서버가 판단합니다.

</>4. 단계별 코드 예시

파일 경로: game-ranking-api/README.md

이 단계에서는 실행 코드를 만들기 전에 서비스가 다룰 대상과 요청 흐름을 문서로 정합니다. README는 서버 응답이 아니라 이후 경로·모델·테스트가 같은 책임을 바라보게 하는 설계 기준입니다.

README.md

# Game Ranking API

## 핵심 리소스
- users: 계정과 역할
- records: 사용자의 게임 점수 기록
- rankings: 게임별 최고 점수 집계

## 요청 흐름
1. 클라이언트가 JSON 요청을 보낸다.
2. API가 입력과 인증을 검증한다.
3. 데이터베이스 트랜잭션을 수행한다.
4. 상태 코드와 JSON을 응답한다.

실행 위치: 프로젝트를 만들 상위 폴더

New-Item -ItemType Directory game-ranking-api
Set-Location game-ranking-api
git init
git status

작성 결과 확인

명령이 성공하면 빈 game-ranking-api 폴더에 .git 저장소와 README가 있습니다. git status에는 아직 커밋하지 않은 README.md가 표시되어야 합니다. 서버가 실행되거나 데이터베이스가 생기는 단계는 아닙니다.

README의 세 리소스는 다음 질문에 답해야 합니다.

• users: 누가 요청했는가?
• records: 어떤 게임에서 어떤 점수를 얻었는가?
• rankings: 여러 기록을 어떤 기준으로 집계해 보여 줄 것인가?

→5. 코드가 동작하는 이유

README는 아직 서버를 실행하지 않지만 리소스와 책임을 먼저 고정합니다. 이후 경로 이름과 데이터 모델이 바뀔 때 “이 코드가 어느 책임에 속하는가?”를 판단하는 기준이 됩니다.

!6. 자주 하는 실수와 해결법

!자주 하는 실수

• 실수: 브라우저에서 점수를 검사했으니 안전하다고 생각합니다. 해결: 클라이언트 입력은 조작될 수 있으므로 서버에서 다시 검증합니다.
• 실수: 데이터베이스를 API라고 부릅니다. 해결: DB는 저장소이고 API 서버가 DB 접근을 통제합니다.
• 실수: URL을 동사로만 설계합니다. 해결: /create-score보다 리소스 /records와 POST를 조합합니다.

✎7. 직접 실습

✎직접 실습

실습 목표

기록 생성·랭킹 조회·로그인의 전체 요청 흐름과 각 계층의 책임을 README에 설계합니다.

시작 전 상태

예제 폴더와 README.md를 만들고 Git 저장소를 초기화합니다. 아직 FastAPI 코드나 데이터베이스 파일은 만들지 않습니다.

1단계: 따라 하기

README에 users, records, rankings의 목적을 한 문장씩 작성합니다. 기록 생성 요청을 브라우저 → 서버 검증 → DB 저장 → 응답 순서로 그립니다.

2단계: 상황을 바꿔 보기

점수가 -50인 요청과 로그인하지 않은 요청을 추가합니다. 어느 계층이 먼저 안내할 수 있고, 어느 계층이 최종 거부해야 하는지 구분합니다.

3단계: 직접 적용

기록 생성, 랭킹 조회, 로그인 요청의 method·path·성공 상태 코드·DB 변경 여부를 표로 완성합니다. 로그인은 단순 행 생성과 다른 세션/토큰 발급 동작이라는 점도 적습니다.

4단계: 스스로 확인

• 새로고침 이후 보존할 데이터가 어디에 저장되는지 표시했나요?
• 클라이언트가 보낸 점수를 서버가 그대로 신뢰하지 않도록 했나요?
• 각 요청의 성공과 실패를 상태 코드로 구분했나요?

막혔을 때

• API와 DB가 같은 상자로 보임: HTTP 요청을 받는 계층과 SQL로 저장하는 계층을 분리해 그립니다.
• 모든 검증을 브라우저에 둠: 별도 도구로 같은 요청을 보낼 수 있다고 가정하고 서버 검증을 추가합니다.
• URL이 모두 동사형: 대상을 복수 명사 리소스로 정하고 행동은 HTTP 메서드로 옮깁니다.

?8. 이해 점검 질문 3개

?이해 점검

1. 점수 범위 검사를 프론트엔드와 백엔드 모두에서 하는 이유는 무엇인가요?
2. API와 데이터베이스는 어떤 책임 차이가 있나요?
3. 새 게임 기록을 생성하고 전체 기록을 조회해야 할 때 같은 /records 경로에 각각 어떤 HTTP 메서드를 사용해야 하나요?

■9. 핵심 요약

■핵심 요약

백엔드는 신뢰 경계 안에서 검증, 인증, 저장, 집계를 담당합니다. 앞으로 users, records, rankings 리소스를 하나의 REST API로 확장합니다.

§다음 강의 연결

역할과 API 범위를 정했으므로 2강. Python 가상 환경과 패키지에서 프로젝트마다 FastAPI 의존성을 분리해 설치합니다.