write31991 님의 블로그

FastAPI 4일차

write31991 — Mon, 26 Oct 2026 15:19:34 +0900

⚡ FastAPI & asyncio 비동기 프로그래밍, 의존성 주입(DI) & 스레드 풀 완벽 정리 노트

FastAPI의 핵심 아키텍처인 **자원 관리(try-finally ➔ Context Manager ➔ Depends 의존성 주입)**부터 클라이언트 요청-응답 4단계 라이프사이클, 응답 속도를 극대화하는 Background Tasks, 비동기(asyncio)의 본질과 컴퓨터 하드웨어(RAM vs Disk I/O) 속도 차이, 코루틴(Coroutine)과 '세 쌍둥이 밥 먹이기' 이벤트 루프(Event Loop)의 원리, await를 쓰는 2대 필수 조건과 체이닝 실습, 그리고 FastAPI가 동기 함수(def)를 이벤트 루프 블로킹 없이 처리하는 비밀인 스레드 풀(Thread Pool)과 Lifespan 제어까지 총정리한 실무 가이드

1. 자원 관리의 진화: try-finally에서 Context Manager까지

1-1. try-except-finally 예외 처리 3대 블록의 역할

파이썬의 예외 처리는 프로그램이 예기치 못한 에러로 강제 종료(크래시)되는 것을 막고, 사용한 시스템 자원을 안전하게 반납하기 위한 핵심 문법입니다.

try: 에러가 발생할 가능성이 있는 코드를 실행. 에러가 나면 즉시 실행을 멈추고 except로 점프.
except: 발생한 에러를 잡아내어 대처(로그 기록, 사용자 친화적 메시지 출력 등).
finally: 예외 발생 여부와 상관없이 무조건 마지막에 실행되는 구역. 파일 닫기(f.close()), 네트워크 연결 종료, 데이터베이스 세션 종료(session.close()) 등에 필수적입니다.
except 생략 가능: 에러 처리는 상위로 넘기되 뒷정리만 확실히 하고 싶다면 try - finally 구조로만 작성할 수 있습니다.

1-2. DB 세션에서 finally가 필수적인 이유 (return보다 늦게 닫히는 문제 해결)

def get_items_handler():
    session = SessionFactory()
    try:
        stmt = select(Item)
        items = session.scalars(stmt).all()
        return items  # ⚠️ 여기서 함수가 즉시 종료됨!
        # session.close() 를 여기에 적으면 절대 도달할 수 없음(Dead Code)!
    finally:
        session.close()  # ✅ return이 실행되기 직전에 무조건 실행되어 세션을 안전하게 닫음!

데이터베이스 세션을 열었으면 데이터를 다 쓰고 난 뒤 반드시 session.close()로 커넥션을 반납해야 커넥션 풀 누수(Memory Leak)가 발생하지 않습니다.
하지만 함수 중간에 return items를 만나면 함수가 그 즉시 끝나버립니다.
finally 블록을 사용하면 return 문을 만나더라도 파이썬 엔진이 그 직전에 finally 내부 코드를 먼저 실행하고 함수를 빠져나갑니다.

1-3. Context Manager (with SessionFactory() as session:)의 자동 뒷정리 마법

매번 모든 API 엔드포인트마다 session = SessionFactory(), try:, finally: session.close()를 반복해서 적는 것은 코드가 지저분해지고 번거롭습니다.
파이썬의 **컨텍스트 매니저 (Context Manager, with 문)**를 사용하면 이 모든 과정을 한 줄로 축약할 수 있습니다.

def get_items_handler():
    # with 문 진입 시 자동으로 session이 열리고, 블록을 벗어날 때 자동으로 session.close() 호출!
    with SessionFactory() as session:
        stmt = select(Item)
        items = session.scalars(stmt).all()
        return items

⚙ with 문 동작 메커니즘:

with SessionFactory() as session:에 진입하는 순간 세션 인스턴스가 생성됩니다 (__enter__).
블록 내부 코드가 정상적으로 끝나든, 중간에 return을 만나든, 에러가 발생해 튕겨 나가든 상관없이, 들여쓰기가 끝나는 순간 컨텍스트 매니저가 내부적으로 session.close()를 100% 보장하며 안전하게 호출합니다 (__exit__).

2. FastAPI 라우팅과 클라이언트 요청-응답 4단계 라이프사이클

2-1. 라우팅(Routing)의 본질: 도로 표지판과 HTTP Method + URL 매핑

**라우팅(Routing)**이란:
클라이언트(웹 브라우저, 모바일 앱)가 보낸 요청의 **HTTP 메서드(GET, POST, PUT, DELETE)**와 **URL 경로(/items, /users)**를 조합하여, 서버 내부의 어떤 담당 함수(핸들러)를 실행시킬지 길을 안내하고 연결해 주는 과정입니다.
도로 표지판 비유:
- GET /items 표지판 ➔ list_items() 함수로 안내 (데이터 조회)
- POST /items 표지판 ➔ create_item() 함수로 안내 (데이터 생성)
주소가 같아도 메서드가 다르면 완전히 다른 함수가 실행됩니다!

2-2. 요청부터 응답까지의 4단계 라이프사이클 전체 흐름도

클라이언트가 버튼을 클릭한 순간부터 화면에 데이터가 렌더링될 때까지 FastAPI 내부에서 일어나는 일입니다:

Unable to render rich display

Parse error on line 11:
...m); session.commit() Handler-->>Form
-----------------------^
Expecting 'SOLID_OPEN_ARROW', 'DOTTED_OPEN_ARROW', 'SOLID_ARROW', 'SOLID_ARROW_TOP', 'SOLID_ARROW_BOTTOM', 'STICK_ARROW_TOP', 'STICK_ARROW_BOTTOM', 'SOLID_ARROW_TOP_DOTTED', 'SOLID_ARROW_BOTTOM_DOTTED', 'STICK_ARROW_TOP_DOTTED', 'STICK_ARROW_BOTTOM_DOTTED', 'SOLID_ARROW_TOP_REVERSE', 'SOLID_ARROW_BOTTOM_REVERSE', 'STICK_ARROW_TOP_REVERSE', 'STICK_ARROW_BOTTOM_REVERSE', 'SOLID_ARROW_TOP_REVERSE_DOTTED', 'SOLID_ARROW_BOTTOM_REVERSE_DOTTED', 'STICK_ARROW_TOP_REVERSE_DOTTED', 'STICK_ARROW_BOTTOM_REVERSE_DOTTED', 'BIDIRECTIONAL_SOLID_ARROW', 'DOTTED_ARROW', 'BIDIRECTIONAL_DOTTED_ARROW', 'SOLID_CROSS', 'DOTTED_CROSS', 'SOLID_POINT', 'DOTTED_POINT', got 'NEWLINE'

For more information, see https://docs.github.com/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams

sequenceDiagram
    autonumber
    actor Client as   클라이언트 (Chrome)
    participant FastAPI as ⚡ FastAPI 라우팅 & 사전 검증
    participant Handler as ⚙ 비즈니스 핸들러 & DB
    participant Formatter as   응답 직렬화기

    Client->>FastAPI: 1단계: HTTP 요청 (예: POST /items {"name": "apple", "price": 1000})
    Note over FastAPI: 2단계: 사전 검증<br/>a) 라우팅: URL+Method로 함수 탐색<br/>b) 데이터 유효성 검사: Pydantic 타입/길이 검증<br/>c) 검증 통과 시 핸들러 호출
    FastAPI->>Handler: 3단계: 함수 코드 실행 & DB 세션 관리
    Note over Handler: with SessionFactory() as session:<br/>session.add(new_item); session.commit()
    Handler-->>Formatter: 파이썬 Item ORM 객체 반환
    Note over Formatter: 4단계: 최종 응답 조립<br/>a) Python ➔ JSON 직렬화<br/>b) 상태 코드(201 Created) 부여
    Formatter-->>Client: HTTP 201 응답 전송 (JSON 본문)

1단계: 클라이언트의 HTTP 요청 전송: 웹/앱에서 주소를 호출 (localhost:8000은 외부망으로 나가지 않고 내 컴퓨터 내부에서 루프백 통신).
2단계: FastAPI 사전 검증 및 라우팅:
- URL과 Method로 대상 함수 매핑
- Path, Query, Request Body 데이터 형식 사전 검사 (실패 시 즉시 422 반환)
3단계: 함수 실행 및 DB 세션 관리: 비즈니스 로직 수행 및 안전한 세션 자원 해제.
4단계: 최종 응답 처리: 파이썬 데이터를 표준 JSON 텍스트로 자동 직렬화하고 HTTP 상태 코드와 함께 클라이언트로 회신.

3. 의존성 주입 (Dependency Injection, DI): with 구문마저 지우는 비결

3-1. 의존성 주입(DI)이란 무엇인가? (자원 생성과 렌탈 개념)

의존성 주입(Dependency Injection):
함수 내부에서 필요한 공통 자원(DB 세션, 인증 유저 정보, 외부 API 클라이언트 등)을 함수가 직접 만들지 않고, FastAPI 프레임워크가 외부에서 대신 만들어 파라미터로 주입(Inject)해 주는 아키텍처입니다.
렌탈(대여) 개념:
자동차를 매번 내가 직접 사서 타고 폐차하는 것이 아니라, 렌터카 업체(FastAPI)에서 차를 빌려 타고 반납하면 뒷정리는 업체가 알아서 해주는 것과 같습니다.

3-2. yield 키워드를 활용한 세션 팩토리 제너레이터 (get_session())

# connection.py
from sqlalchemy.orm import Session
from connection import SessionFactory

def get_session():
    # 1. 요청이 들어오면 DB 세션을 열고
    session = SessionFactory()
    try:
        # 2. yield로 핸들러 함수에게 세션을 대여(전달)해 줌!
        # (함수가 종료될 때까지 get_session은 여기서 일시정지 상태 유지)
        yield session
    finally:
        # 3. 핸들러 함수가 return을 마치는 순간 일시정지가 풀리고 세션을 안전하게 닫음!
        session.close()

yield의 작동 원리:
- return은 값을 돌려주고 함수를 완전히 종료시킵니다.
- 반면 yield는 **값을 반환한 뒤 그 자리에서 일시정지(Pause)**합니다.
- FastAPI 핸들러 함수가 DB 작업을 모두 마치고 나면, 멈춰있던 yield 다음 줄(finally: session.close())이 실행되면서 자원을 완벽하게 회수합니다.

3-3. Depends(get_session) 실전 적용과 엔드포인트 극단적 단순화

이제 엔드포인트 함수에서는 with 문조차 쓸 필요가 없습니다!

from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session
from sqlalchemy import select
from connection import get_session

app = FastAPI()

@app.get("/items", response_model=list[ItemResponse])
def list_items(session: Session = Depends(get_session)):
    #   with SessionFactory() as session: 을 작성할 필요가 전혀 없음!
    stmt = select(Item)
    items = session.scalars(stmt).all()
    return items

Tip

의존성 주입(DI)의 압도적인 장점:

비즈니스 로직에만 집중: 세션을 열고 닫는 반복적인 보일러플레이트 코드가 완전히 사라집니다.
테스트 용이성 (Mocking): 테스트 코드 작성 시 실제 DB 세션 대신 가짜(Mock) 세션으로 손쉽게 교체할 수 있습니다.

4. Background Tasks (백그라운드 태스크)

4-1. 요청-응답 이후 실행의 의미와 체감 응답 속도 극대화

클라이언트에게 HTTP 응답 메시지를 먼저 초고속으로 반환한 뒤, 시간이 걸리는 부가 작업을 백그라운드에서 실행하는 FastAPI 내장 기능입니다.
사용자는 화면에서 로딩 스피너를 오래 보지 않고 즉시 "완료되었습니다" 응답을 받으므로 서비스의 체감 속도가 비약적으로 향상됩니다.

4-2. 실전 코드: 회원가입 후 5초 이메일 발송 비동기 처리

import time
from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

# 5초가 걸리는 무거운 이메일 발송 함수
def send_email(email: str):
    time.sleep(5)  # 실제 이메일 SMTP 서버 통신 시뮬레이션
    print(f"  [발송 완료] {email} 님에게 환영 메일을 성공적으로 보냈습니다!")

@app.post("/sign-up")
def sign_up(email: str, background_tasks: BackgroundTasks):
    # 1. 백그라운드 태스크 큐에 작업 등록 (함수명, 인자)
    background_tasks.add_task(send_email, email)
    
    # 2. 이메일이 다 보내질 때까지 기다리지 않고 0.01초 만에 즉시 클라이언트에 응답!
    return {"message": "User SignUp Completed"}

4-3. Background Tasks 사용 시 주의점 (무거운 작업과 Celery/Redis 비교)

적합한 작업: 이메일 발송, 푸시 알림 전송, 간단한 통계 로깅, 캐시 갱신 등 1~5초 내외의 가벼운 후처리.
❌ 부적합한 작업 (주의!):
- 수 분 이상 걸리는 대용량 동영상 인코딩, 대규모 데이터셋 머신러닝 학습 등.
- FastAPI의 Background Tasks는 동일한 서버 프로세스 안에서 실행되므로, 너무 무거운 CPU 작업을 넣으면 메인 웹 서버의 전체 성능이 떨어집니다.
- 초대형 작업은 Celery + Redis / RabbitMQ 같은 분산 작업 큐 시스템을 사용하는 것이 정석입니다.

5. 비동기 프로그래밍 (asyncio)의 본질과 컴퓨터 구조

5-1. 동기(Synchronous)의 한계와 I/O Bound 작업의 비효율

동기(Synchronous) 방식:
호출자(Caller)가 피호출자(Callee)의 작업이 완전히 끝날 때까지 아무것도 하지 않고 가만히 멈춰서 기다리는 방식.

import time

def hello():
    time.sleep(2)  # 2초 동안 CPU가 멍하니 대기 (Blocking)
    print("hello")

hello()
print("end")
# 총 2초 동안 프로그램 전체가 멈춤!

5-2. 컴퓨터 구조로 보는 속도 차이 (빛처럼 빠른 CPU/RAM vs 목 빠지는 Disk/Network I/O)

왜 웹 서버에서는 동기 방식이 치명적일까요? 컴퓨터 하드웨어의 영역 차이를 이해해야 합니다.

Unable to render rich display

Parse error on line 12:
... <-->|물리적 I/O 대기 발생 (Blocking!)| SlowZon
-----------------------^
Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND', 'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'PS'

For more information, see https://docs.github.com/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams

graph LR
    subgraph FastZone["⚡ 빛의 속도 (나노초 단위)"]
        CPU["CPU (연산 장치)<br/>1 + 1 = 2 계산"]
        RAM["RAM (주기억장치)<br/>FastAPI 파이썬 메모리"]
    end

    subgraph SlowZone["  달팽이 속도 (밀리초~초 단위)"]
        DISK["SSD / HDD (보조기억장치)<br/>SQLite test.db 파일"]
        NET["외부 네트워크 / DB 서버<br/>API 통신 패킷"]
    end

    FastZone <-->|물리적 I/O 대기 발생 (Blocking!)| SlowZone

CPU와 RAM의 연산: 빛처럼 빠릅니다 (나노초 단위로 수억 번 계산).
디스크(SSD/HDD)와 네트워크 I/O: 물리적으로 모터가 돌거나 광케이블을 타야 하므로 상대적으로 수백만 배 느립니다.
결론:
FastAPI가 DB 조회를 요청할 때, CPU는 0.0001초 만에 요청 명령을 내렸지만 디스크에서 데이터가 RAM으로 올라올 때까지 **수 밀리초 동안 손을 놓고 멍하니 대기(Blocking)**하게 됩니다.
이 아까운 대기 시간 동안 다른 사용자의 요청을 처리하자는 것이 **비동기 프로그래밍(asyncio)**의 핵심입니다!

5-3. 비동기의 일상 비유: 라면 끓이기와 주문 접수

상황 동기 (Synchronous) ⚡ 비동기 (Asynchronous)

라면 끓이기	냄비에 물을 올리고, 물이 끓을 때까지 3분 동안 가스레인지 앞에 가만히 차렷 자세로 서 있기	물을 올려두고, 물이 끓는 동안(I/O 대기) 설거지를 하거나 테이블을 닦고 돌아오기
식당 운영	1번 손님의 스테이크 요리가 다 완성되어 서빙될 때까지 2번 손님의 주문 접수를 일절 거부하고 문을 닫아두기	1번 손님 주문을 주방에 넘겨두고(조리 대기), 카운터에서 2번, 3번 손님의 주문을 쉬지 않고 연속해서 접수하기

5-4. 파이썬 표준 라이브러리 asyncio

파이썬에서 비동기 I/O 프로그래밍을 공식 지원하는 내장 라이브러리입니다 (import asyncio).
외부 라이브러리(numpy, pytorch 등)와 달리 별도 pip install 없이 즉시 사용 가능합니다.
CPU를 쓰지 않고 쉬는 I/O 대기 시간(네트워크 요청, DB 쿼리, sleep)에 다른 작업을 교대로 처리하게 해줍니다.

6. 코루틴(Coroutine)과 협력적 멀티태스킹

6-1. 코루틴의 정의: "너 한 번, 나 한 번" 협력(co-routine)하는 함수

코루틴(Coroutine):
co-(함께, 협력하다) + routine(함수, 절차)의 합성어로, 실행 도중에 멈췄다가(양보) 나중에 그 자리에서 다시 이어서 실행할 수 있는 협력적인 함수를 말합니다.
특정 함수가 CPU를 혼자 독점하지 않고, "나 지금 DB 기다려야 하니까 다른 함수 먼저 일해!" 하고 서로 양보하며 번갈아 실행됩니다.

6-2. 코루틴 함수(async def) vs 코루틴 객체 (왜 바로 실행되지 않는가?)

# 1. async def로 정의된 함수 -> 코루틴 함수 (Coroutine Function)
async def hello():
    print("hello")

# 2. 코루틴 함수 호출
coro = hello()
print(coro)
# 출력: <coroutine object hello at 0x1056f3580>

Q. 왜 일반 함수처럼 hello()를 부르면 바로 실행되지 않고 객체만 튀어나올까요?
A. 코루틴은 단독으로 혼자 실행되려고 태어난 것이 아니기 때문입니다!
코루틴의 전제는 **"동시에 진행해야 할 여러 작업들이 있을 때, 대기 시간에 서로 양보하며 협력하는 것"**입니다.
따라서 실행하기 전에 먼저 **작업 지시서(코루틴 객체)**를 만들어 두고, 이벤트 루프에 한꺼번에 올려서 실행해야 합니다.

6-3. asyncio.run()과 asyncio.gather()를 통한 동시 실행 패키징

import asyncio

async def task_a():
    print("A 시작")
    await asyncio.sleep(2)  # 2초 동안 양보하며 대기
    print("A 끝")

async def task_b():
    print("B 시작")
    await asyncio.sleep(2)  # 2초 동안 양보하며 대기
    print("B 끝")

async def main():
    # 1. 코루틴 객체들을 생성하여 asyncio.gather로 한 바구니에 묶음
    coro_a = task_a()
    coro_b = task_b()
    await asyncio.gather(coro_a, coro_b)

# 2. 메인 진입점에서 이벤트 루프 가동
asyncio.run(main())

6-4. 동기 vs 비동기 실행 시간 벤치마크 (4초 ➔ 2초 단축)

동기 방식 (time.sleep): A가 2초 멈추고 끝난 뒤 B가 2초 멈춤 ➔ 총 4초 소요!
비동기 방식 (asyncio.sleep): A가 2초 대기에 들어가며 양보하자마자 B가 즉시 시작되어 함께 2초를 대기 ➔ 총 2초 만에 두 작업 동시 완료!
작업이 5개, 10개로 늘어나도 I/O 대기 시간은 여전히 2초로 수렴합니다.

7. await 키워드와 양보(Yield Control)의 미학

7-1. await: "여기서 잠깐 멈추고 제어권을 넘겨라!"

코루틴은 I/O를 기다릴 때 양보하지만, 컴퓨터는 언제 I/O 대기가 발생할지 스스로 예측할 수 없습니다.
따라서 개발자가 코드에 **await**라는 키워드를 붙여서 "여기가 바로 오래 걸리는 지점이니까, 결과가 올 때까지 다른 코루틴에게 CPU 제어권을 넘겨라!" 하고 명시해 주어야 합니다.

7-2. ⭐ await를 사용하는 2가지 절대 조건

반드시 async def로 선언된 비동기 함수(코루틴) 내부에서만 사용 가능!
일반 동기 함수(def)나 파이썬 파일 최상단에서 단독으로 쓰면 문법 에러(SyntaxError: 'await' outside function)가 발생합니다.
기다릴 수 있는 대상(Awaitable 객체) 앞에만 사용 가능!
아무 함수에나 붙일 수 없으며, 반드시 비동기 작업을 지원하는 대상이어야 합니다.

# ❌ 일반 동기 함수에 await를 붙인 잘못된 코드 (에러 발생!)
async def wrong():
    await time.sleep(3)  # TypeError: object NoneType can't be used in 'await' expression

# ✅ 비동기 전용 함수에 await를 붙인 올바른 코드
async def correct():
    await asyncio.sleep(3)  # 정상 동작

7-3. 어떤 작업이 Awaitable한가? (판단 3단계 공식)

async def로 정의된 함수인가? ➔ 호출 시 코루틴 객체를 반환하므로 100% await 가능.
비동기 라이브러리(aiohttp, asyncpg, aiofiles, asyncio 등) 출신인가? ➔ 대부분 await 가능.
I/O 대기가 발생하는 작업인가? ➔ 비동기 버전 함수라면 await를 붙여야 함.

7-4. [실습] 코루틴 체이닝 퍼즐 (출력 순서 제어 완성)

슬라이드 31~34페이지의 실전 퍼즐 문제입니다.

목표 출력 순서:
1. C 시작
2. A 시작
3. A 끝
4. B 시작
5. C 끝
6. B 끝

풀이 분석 및 완성 코드:

각 코루틴의 await asyncio.sleep() 시간을 세밀하게 조율하여 타임라인을 맞춥니다.

import asyncio

async def a():
    await asyncio.sleep(0.1)  # 0.1초 후 A 시작
    print("A 시작")
    await asyncio.sleep(0.0)  # 대기 없이 즉시 A 끝
    print("A 끝")

async def b():
    await asyncio.sleep(0.2)  # 0.2초 후 B 시작
    print("B 시작")
    await asyncio.sleep(0.2)  # 추가 0.2초(누적 0.4초) 후 B 끝
    print("B 끝")

async def c():
    await asyncio.sleep(0.0)  # 0.0초! 가장 먼저 C 시작
    print("C 시작")
    await asyncio.sleep(0.3)  # 추가 0.3초 후 C 끝
    print("C 끝")

async def main():
    await asyncio.gather(a(), b(), c())

asyncio.run(main())

8. 이벤트 루프(Event Loop)와 블로킹(Blocking) 금지의 법칙

8-1. 이벤트 루프란? ("세 쌍둥이 밥 먹이기" 완벽 비유)

**이벤트 루프(Event Loop)**는 수많은 코루틴들의 양보와 대기, 실행 재개를 쉴 새 없이 조율하는 중간 총괄 관리자입니다.

Unable to render rich display

Parse error on line 8:
...D1 -->|2. 오물오물 씹는 중 (await)| PARENT
-----------------------^
Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND', 'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'PS'

For more information, see https://docs.github.com/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams

graph TD
    PARENT[" ‍ ‍  이벤트 루프 (부모)"]
    KID1["  코루틴 A (첫째)"]
    KID2["  코루틴 B (둘째)"]
    KID3["  코루틴 C (셋째)"]

    PARENT -->|1. 한 숟갈 먹임| KID1
    KID1 -->|2. 오물오물 씹는 중 (await)| PARENT
    PARENT -->|3. 씹는 동안 둘째 먹임| KID2
    KID2 -->|4. 오물오물 씹는 중 (await)| PARENT
    PARENT -->|5. 셋째 먹임| KID3
    PARENT -->|6. 첫째가 다 씹었으면 다음 숟갈!| KID1

비유 분석:
- 부모 = 이벤트 루프: 단 한 명의 부모(싱글 스레드)가 숟가락을 들고 있습니다.
- 아이들 = 코루틴: 아이가 밥을 씹는 시간은 **I/O 대기 시간(await)**입니다.
- 부모는 한 아이가 씹는 동안 멍하니 기다리지 않고 바로 옆 아이에게 숟가락을 가져갑니다.
- 밖에서 보면 세 아이가 동시에 밥을 먹는 것처럼(동시성 / Concurrency) 보입니다!

8-2. 절대 규칙: 이벤트 루프를 블로킹하면 서버 전체가 얼어붙는다!

⚠️ 비동기 세상의 대역죄: Blocking the Event Loop!
만약 코루틴 내부에서 await 없이 time.sleep(10)이나 거대한 while True 연산을 돌려버리면, 이벤트 루프(부모)의 손발이 통째로 묶여버립니다.
그 순간 다른 모든 코루틴의 실행이 정지되어, 접속해 있는 모든 클라이언트의 웹 페이지가 동시에 멈추게 됩니다.

9. FastAPI 내부 동작의 비밀: 동기 함수(def)와 스레드 풀(Thread Pool)

9-1. "FastAPI는 비동기인데 왜 우린 지금까지 def 일반 함수를 썼을까?"

미스터리:
"FastAPI는 비동기(Async) 기반 프레임워크라고 배웠는데, 왜 이전 실습에서는 @app.get("/items") 밑에 async def가 아니라 그냥 def list_items():를 썼을까요? 동기 함수를 쓰면 이벤트 루프가 블로킹되어 서버가 멈춰야 정상 아닌가요?"

9-2. 스레드 풀(Thread Pool)의 대리 실행 메커니즘 (run_endpoint_function)

비밀은 FastAPI 내부 소스코드(fastapi/routing.py의 run_endpoint_function)에 숨어 있습니다.

FastAPI의 천재적인 배려:
- 개발자가 def로 동기 함수를 작성하면, FastAPI는 "아! 이 함수는 동기 함수니까 이벤트 루프에서 직접 돌리면 서버가 멈추겠구나!" 하고 판단합니다.
- 그래서 이벤트 루프를 건드리지 않고, 외부의 별도 일꾼 모음인 스레드 풀(Thread Pool)의 작업자 스레드에게 작업을 대신 던져서 실행시킵니다.
- 덕분에 개발자가 실수로 동기 코드를 작성해도 이벤트 루프가 얼어붙지 않는 것입니다!

9-3. 스레드 풀 크기 조절과 Lifespan 컨텍스트 매니저 (기본 40개 ➔ 200개 상향)

스레드 풀의 한계:
동기 엔드포인트는 **스레드 풀의 개수(기본값: 40개)**가 곧 최대 동시 처리량입니다.
동시 요청이 40개를 넘어가면 41번째 요청부터는 스레드가 날 때까지 대기 큐에서 지연(Lag)이 발생합니다.
해결책:
최신 FastAPI 표준인 Lifespan 컨텍스트 매니저를 활용해 서버 기동 시 스레드 풀의 크기(total_tokens)를 상향 조정합니다.

from contextlib import asynccontextmanager
import anyio
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 1. [서버 시작 직후 실행] AI 모델 로드, 스레드 풀 조정 등
    limiter = anyio.to_thread.current_default_thread_limiter()
    limiter.total_tokens = 200  # 기본 40개 ➔ 200개로 대폭 상향!
    print("  [서버 시작] 스레드 풀 200개 확장 완료")
    
    yield  # 서버가 돌아가는 동안 대기
    
    # 2. [서버 종료 직전 실행] DB 커넥션 풀 종료 등 마무리 코드
    print("  [서버 종료] 자원 정리 완료")

app = FastAPI(
    title="e-Commerce 상품 관리 서버",
    lifespan=lifespan
)

10. 실전 핵심 요약 치트시트

┌────────────────────────────────────────────────────────────────────────┐
│         FastAPI 자원 관리 & 비동기(asyncio) & 스레드 풀 치트시트       │
├──────────────────────────────┬─────────────────────────────────────────┤
│ 문법 / 개념                  │ 핵심 요약 및 사용 공식                  │
├──────────────────────────────┼─────────────────────────────────────────┤
│ try - finally                │ return 직전에 session.close() 보장     │
├──────────────────────────────┼─────────────────────────────────────────┤
│ with SessionFactory() as s:  │ 들여쓰기 빠져나갈 때 자동 close()       │
├──────────────────────────────┼─────────────────────────────────────────┤
│ yield session                │ get_session() 제너레이터로 세션 렌탈    │
├──────────────────────────────┼─────────────────────────────────────────┤
│ Depends(get_session)         │ FastAPI 의존성 주입 (with 문도 생략)    │
├──────────────────────────────┼─────────────────────────────────────────┤
│ BackgroundTasks.add_task()   │ 응답 반환 후 백그라운드에서 후처리 실행 │
├──────────────────────────────┼─────────────────────────────────────────┤
│ async def                    │ 코루틴 함수 정의 (호출 시 코루틴 객체)  │
├──────────────────────────────┼─────────────────────────────────────────┤
│ await                        │ I/O 대기 시 CPU 제어권 양보 키워드      │
├──────────────────────────────┼─────────────────────────────────────────┤
│ await 사용 2대 조건          │ 1) async def 내부 2) Awaitable 객체     │
├──────────────────────────────┼─────────────────────────────────────────┤
│ asyncio.gather(c1, c2)       │ 여러 비동기 작업을 묶어 동시 실행       │
├──────────────────────────────┼─────────────────────────────────────────┤
│ 이벤트 루프 (Event Loop)     │ 코루틴들의 양보/대기/재개를 총괄 관리   │
├──────────────────────────────┼─────────────────────────────────────────┤
│ 블로킹 금지                  │ 이벤트 루프 멈추면 모든 비동기 작업 올스톱│
├──────────────────────────────┼─────────────────────────────────────────┤
│ def (동기 엔드포인트)        │ FastAPI가 스레드 풀(기본 40개)에서 실행 │
├──────────────────────────────┼─────────────────────────────────────────┤
│ lifespan (스레드 풀 확장)    │ anyio limiter.total_tokens = 200        │
└──────────────────────────────┴─────────────────────────────────────────┘

FastAPI 3일차

write31991 — Mon, 26 Oct 2026 15:01:01 +0900

️ FastAPI & SQLAlchemy ORM 데이터베이스 연동과 실전 영속 CRUD 완벽 정리 노트

메모리(list) 기반 CRUD의 한계와 데이터베이스(RDB) 도입 이유부터 SQL 직접 작성의 한계와 ORM(Object-Relational Mapping)의 본질, SQLAlchemy 2.0 모던 아키텍처(Engine, Session, Model), Mapped & mapped_column 모델링, 세션의 생명주기와 영속성 컨텍스트(Staging ➔ Commit), Result 커서의 원리와 3대 추출 메서드(mappings, all, scalars), 그리고 Context Manager(with)를 적용한 견고한 실전 DB CRUD 구현까지 총정리한 실무 가이드

1. 왜 데이터베이스(DB)가 필요한가? (메모리 CRUD의 한계)

1-1. 메모리(list) 기반 CRUD의 2대 치명적 한계

이전 장까지는 파이썬 코드 안의 리스트(ITEMS = [...])에 데이터를 담아 CRUD를 구현했습니다.
하지만 메모리 기반 데이터 관리는 실제 상용 서비스에서는 절대 사용할 수 없는 치명적인 결함이 있습니다:

휘발성 (서버 재시작 시 데이터 소멸):
- RAM(메모리)에 상주하므로 코드를 수정해 서버가 리로드되거나, 배포, 서버 재부팅이 발생하는 순간 기존에 저장된 모든 데이터가 영구적으로 날아갑니다.
동시 공유 불가 (다중 프로세스/서버 환경):
- 실제 서비스는 트래픽을 감당하기 위해 서버 프로세스를 여러 개(Uvicorn 워커 4개, 도커 컨테이너 여러 대) 띄웁니다.
- 각 프로세스는 독립된 메모리를 가지므로, 1번 서버에서 등록한 상품을 2번 서버에서는 조회할 수 없습니다.

1-2. 데이터베이스의 3대 핵심 역할 (영속성, 동시성, 신뢰성)

1. 영속성 (Persistence):
서버가 다운되거나 재부팅되더라도 하드디스크/SSD의 물리적 파일이나 블록에 데이터가 영구적으로 안전하게 기록됩니다.
2. 동시성 (Concurrency):
수천, 수만 명의 사용자가 동시에 같은 상품을 조회하고 주문하더라도 락(Lock)과 격리 수준(Isolation)을 통해 데이터 충돌 없이 안전하게 조율합니다.
3. 신뢰성 (Reliability / ACID):
트랜잭션(Transaction)을 지원하여, 작업 도중 에러가 발생하면 이전 상태로 완벽히 되돌리는 롤백(Rollback)을 보장합니다.

2. SQL 직접 작성(Raw SQL)의 한계와 ORM의 탄생

2-1. 클라이언트 - FastAPI - SQLite 전체 아키텍처

Unable to render rich display

Parse error on line 10:
...m); session.commit() ORM->>DB: INSER
-----------------------^
Expecting 'SOLID_OPEN_ARROW', 'DOTTED_OPEN_ARROW', 'SOLID_ARROW', 'SOLID_ARROW_TOP', 'SOLID_ARROW_BOTTOM', 'STICK_ARROW_TOP', 'STICK_ARROW_BOTTOM', 'SOLID_ARROW_TOP_DOTTED', 'SOLID_ARROW_BOTTOM_DOTTED', 'STICK_ARROW_TOP_DOTTED', 'STICK_ARROW_BOTTOM_DOTTED', 'SOLID_ARROW_TOP_REVERSE', 'SOLID_ARROW_BOTTOM_REVERSE', 'STICK_ARROW_TOP_REVERSE', 'STICK_ARROW_BOTTOM_REVERSE', 'SOLID_ARROW_TOP_REVERSE_DOTTED', 'SOLID_ARROW_BOTTOM_REVERSE_DOTTED', 'STICK_ARROW_TOP_REVERSE_DOTTED', 'STICK_ARROW_BOTTOM_REVERSE_DOTTED', 'BIDIRECTIONAL_SOLID_ARROW', 'DOTTED_ARROW', 'BIDIRECTIONAL_DOTTED_ARROW', 'SOLID_CROSS', 'DOTTED_CROSS', 'SOLID_POINT', 'DOTTED_POINT', got 'NEWLINE'

For more information, see https://docs.github.com/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams

sequenceDiagram
    autonumber
    actor Client as 클라이언트 (웹/앱)
    participant API as FastAPI 백엔드
    participant ORM as ORM (SQLAlchemy)
    participant DB as SQLite DB (test.db)

    Client->>API: HTTP POST /items {"name": "apple", "price": 1000}
    Note over API: Pydantic으로 Request Body 유효성 검증
    API->>ORM: item = Item(name=..., price=...)<br/>session.add(item); session.commit()
    ORM->>DB: INSERT INTO items (name, price) VALUES ('apple', 1000);
    DB-->>ORM: 1 Row Inserted (id=1 발급)
    ORM-->>API: Item ORM 객체 반환
    API-->>Client: HTTP 201 Created {"id": 1, "name": "apple", "price": 1000}

2-2. "SQL을 코드 안에 직접 적었을 때"의 2대 문제점

데이터베이스와 통신할 때 과거처럼 SELECT * FROM items WHERE id = ? 같은 원시 SQL(Raw SQL) 쿼리문을 파이썬 문자열로 직접 하드코딩하면 다음과 같은 심각한 문제가 발생합니다:

스키마 변경 시 연관된 쿼리를 직접 관리 (유지보수 지옥):
- DB 테이블 구조(컬럼명 변경, 새 필드 추가 등)가 바뀌면, 파이썬 코드 전체에 흩어진 모든 SQL 문자열(SELECT, INSERT, UPDATE)을 개발자가 일일이 검색해서 수동으로 고쳐야 합니다.
- 오타 하나로 런타임 SQL Syntax Error가 터지는 등 휴먼 에러가 빈번해집니다.
SQL ➔ tuple ➔ 객체화 (데이터 변환의 극심한 번거로움):
- SQL을 실행하면 DB 드라이버는 데이터를 순수한 튜플((1, 'apple', 1000))이나 로우(Row) 형태로 반환합니다.
- 개발자가 item_id = row[0], item_name = row[1] 처럼 수동으로 인덱싱해서 파이썬 객체로 조립하는 노가다 코드를 수없이 작성해야 합니다.

2-3. ORM(Object-Relational Mapping)이란?

ORM (객체 관계 매핑):
문자열 형태의 SQL 쿼리를 개발자가 직접 작성하는 대신, 객체 지향 프로그래밍(OOP) 언어의 문법(파이썬 클래스와 인스턴스)으로 데이터베이스를 다룰 수 있게 해주는 중개 기술입니다.

2-4. ORM 3대 매핑 공식 (테이블=클래스, 행=인스턴스, 열=속성)

RDB (관계형 데이터베이스) ➔ 매핑 ➔ Python (객체 지향 언어) 실전 코드 예시

1개 테이블 (Table)	➔	1개 클래스 (Class)	class Item(Base): ➔ items 테이블
1개 행 (Row / 레코드)	➔	1개 인스턴스 (Object)	item = Item(...) ➔ 테이블의 한 줄 데이터
1개 열 (Column / 필드)	➔	1개 인스턴스 속성 (Attribute)	item.name, item.price ➔ name, price 컬럼

3. SQLAlchemy: Python 표준 ORM 라이브러리

3-1. SQLAlchemy를 사용하는 이유와 프레임워크별 ORM 비교

SQLAlchemy는 파이썬 생태계에서 가장 강력하고 성숙하며, 널리 사용되는 사실상의 표준(Defacto Standard) ORM입니다.
FastAPI와 설계 철학이 완벽하게 들어맞으며, 대규모 트래픽 환경에서도 안정적인 커넥션 풀링과 트랜잭션 관리를 지원합니다.

Python 웹 프레임워크별 ORM 스타일 비교:

Django: Django ORM 내장 (Active Record 패턴: 모델 객체 자체가 DB 저장 메서드를 가짐 item.save())
FastAPI: SQLAlchemy, SQLModel, TortoiseORM 자유 선택 (Data Mapper 패턴: 비즈니스 로직과 DB 영속성 레이어를 세션으로 명확히 분리)

3-2. 패키지 설치 (pip install SQLAlchemy)

가상환경(.venv)이 활성화된 상태에서 설치합니다:

pip install SQLAlchemy

4. SQLAlchemy 기초 3대 요소 (Engine, Session, Model)

SQLAlchemy를 지탱하는 3개의 핵심 기둥입니다:

4-1. Engine (엔진): DB 물리적 연결의 관문

파이썬 애플리케이션과 실제 SQLite 데이터베이스 파일(test.db 등) 사이의 **물리적인 연결 통로(Connection Pool)**를 쥐고 있는 핵심 객체입니다.
개발자가 작성한 ORM 코드를 실제 SQL 문장으로 번역하여 DB에 전달하고 실행합니다.
echo=True 옵션을 주면 실행되는 원시 SQL 로그를 터미널에 실시간으로 출력해 주어 학습과 디버깅에 매우 유용합니다.

4-2. Session (세션): 작업 단위와 트랜잭션 관리

실제로 데이터를 추가(add), 조회(select), 수정, 삭제(delete)할 때 엔진 위에 띄우는 **작업 창구(단위)**입니다.
트랜잭션(Transaction)을 시작하고, 변경 사항을 모아두었다가 commit() 시점에 한 번에 DB에 반영합니다.

4-3. Model (모델): 파이썬 클래스로 표현한 테이블

데이터베이스의 테이블 스키마를 파이썬 클래스로 정의한 청사진입니다.

4-4. 엔진을 통한 데이터베이스 요청/실행 전체 흐름

연결 생성 (Engine): create_engine(DATABASE_URL)이 DB와의 통신 회선을 개설합니다.
세션 생성 (Session): session = SessionFactory()를 통해 실제 작업자가 창구(세션)를 엽니다.
요청 전달 및 실행: session.add() 또는 session.execute(stmt)를 호출하면 세션이 엔진에게 전달하고, 엔진이 실제 SQL을 실행한 뒤 결과를 파이썬 객체로 감싸서 돌려줍니다.

5. SQLAlchemy 2.0 모던 모델 정의와 테이블 자동 생성

5-1. DeclarativeBase를 상속한 Base 선언

SQLAlchemy 2.0부터는 declarative_base() 함수 대신 DeclarativeBase 클래스를 상속받는 깔끔한 클래스 선언 방식을 표준으로 권장합니다.

from sqlalchemy.orm import DeclarativeBase

# 모든 ORM 모델들이 상속받을 최상위 부모 클래스
class Base(DeclarativeBase):
    pass

5-2. Mapped와 mapped_column을 활용한 Item 모델 정의

파이썬의 표준 타입 힌트 시스템과 결합된 모던 문법입니다:

from sqlalchemy.orm import Mapped, mapped_column
from sqlalchemy import Integer, String

class Item(Base):
    # 실제 생성될 데이터베이스 테이블 이름 지정
    __tablename__ = "items"

    # id: 정수형, 기본키(PK), 1부터 자동 증가(Auto-increment)
    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    
    # name: 문자열(최대 128자)
    name: Mapped[str] = mapped_column(String(128))
    
    # price: 정수형
    price: Mapped[int] = mapped_column(Integer)

5-3. 왜 DB 컬럼의 타입을 고정해야 하는가? (일관성 & 저장 효율성)

일관성 (Data Consistency):
가격(price) 컬럼에 어떤 사람은 문자열 "천원"을 넣고 어떤 사람은 숫자 1000을 넣으면 계산과 정렬이 불가능해집니다. 타입을 고정하여 데이터의 무결성을 지킵니다.
저장 효율성 (Storage Efficiency):
정수형(Integer)은 4바이트 고정 메모리를 사용하므로 디스크 공간을 절약하고 검색 색인(인덱스) 속도를 극대화합니다.

5-4. Base.metadata.create_all(bind=engine) 테이블 자동 생성

정의한 파이썬 모델 클래스를 바탕으로 SQLite DB 파일에 실제 물리적 테이블을 한 줄로 생성합니다:

from sqlalchemy import create_engine

DATABASE_URL = "sqlite:///./test.db"
engine = create_engine(DATABASE_URL, echo=True)

# Base를 상속받은 모든 모델(Item 등)의 CREATE TABLE 문을 자동 실행!
Base.metadata.create_all(bind=engine)

터미널 출력 로그:

CREATE TABLE items (
    id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(128) NOT NULL,
    price INTEGER NOT NULL
);

6. 세션의 라이프사이클과 데이터 저장 (Staging ➔ Commit)

6-1. 객체 생성 vs session.add() (Staging 상태의 의미)

# 1단계: 순수 파이썬 객체 생성
item = Item(name="apple", price=100)
# ⚠️ 이 시점에는 파이썬 RAM 메모리에만 존재하며, SQLite DB 파일에는 전혀 기록되지 않음!

# 2단계: 세션에 등록 (Staging)
session.add(item)
# "이 객체를 나중에 DB에 저장할 거니까 영속성 관리 영역(Persistence)에 등록해 둬!"
# Git으로 치면 `git add`를 실행해 스테이징 영역에 올려둔 것과 동일합니다.

6-2. session.commit()과 session.close()

# 3단계: 변경 사항을 DB에 영구 확정 (Commit)
session.commit()
# Git의 `git commit`처럼 실제 DB 파일에 INSERT SQL 쿼리가 날아가 영구 기록됩니다.

# 4단계: 세션 종료 (Close)
session.close()
# 점유했던 DB 커넥션 자원을 깔끔하게 반납합니다.

6-3. 다중 데이터 일괄 등록과 RETURNING id의 원리

여러 데이터를 한 번에 세션에 담고 커밋할 수 있습니다:

item2 = Item(name="banana", price=200)
item3 = Item(name="cherry", price=300)

session.add(item2)
session.add(item3)
session.commit()

# DB 엔진 로그:
# INSERT INTO items (name, price) VALUES (?, ?) RETURNING id

Note

RETURNING id의 의미:
우리가 코드로 item2를 만들 때 id 값을 지정하지 않았지만, 데이터베이스가 기본키 자동 증가를 통해 id=2, id=3을 발급한 뒤 즉시 파이썬 객체의 id 속성에 자동으로 채워줍니다!
print(item2.id) ➔ 2 출력!

7. SQLAlchemy 데이터 조회(SELECT)와 Result 객체의 비밀

7-1. select() 쿼리문 빌드와 session.execute()

SQLAlchemy 2.0에서는 함수형 쿼리 빌더인 select()를 사용합니다:

from sqlalchemy import select

# 1. 쿼리문 객체 생성
stmt = select(Item)
print(stmt)  # 출력: SELECT items.id, items.name, items.price FROM items

# 2. 쿼리 실행
result = session.execute(stmt)

7-2. 왜 print(result) 해도 데이터가 안 보일까? (Iterator/Result 커서)

많은 입문자가 print(result)를 해보고 당황합니다:

print(result)
# 출력: <sqlalchemy.engine.result.ChunkedIteratorResult object at 0x103b616a0>

이유: result는 데이터 리스트 자체가 아니라, **데이터베이스에서 데이터를 한 줄씩 꺼내올 수 있는 '결과 핸들러(Iterator / Result 커서)'**이기 때문입니다.
사물함 안에 데이터가 들어있는데, 사물함의 겉모습(메모리 주소)만 출력한 것과 같습니다.
따라서 데이터를 실제로 꺼내는 전용 메서드(mappings(), all(), scalars())를 호출해야 합니다.

7-3. 3대 데이터 추출 메서드 비교 (mappings, all, scalars)

메서드 반환 데이터 형태 주요 용도

result.mappings().all()	list[dict] (딕셔너리 리스트)	딕셔너리 형태로 JSON 직렬화하거나 키값으로 접근할 때
result.all()	list[tuple] (튜플 리스트)	원시 튜플 데이터 그대로 인덱싱할 때
result.scalars().all() (또는 session.scalars(stmt).all())	list[Item] (ORM 객체 리스트)	실무 최다 사용! item.name, item.price 처럼 ORM 객체로 다룰 때

7-4. 치명적 주의점: Result 커서의 일회성 소모(Consumption) 특성

⚠️ 한 번 비워버린 상자는 다시 쓸 수 없다!
result 커서 객체는 result.mappings().all()을 호출하여 데이터를 모두 꺼내고 나면, 커서가 데이터의 맨 끝(End of File)에 도달합니다.
따라서 바로 아래 줄에서 result.all()을 또 호출하면 이미 비어버렸으므로 빈 리스트([])가 반환됩니다!

해결책:

데이터를 다시 조회하고 싶다면, 반드시 result = session.execute(stmt)로 쿼리를 재실행하여 새 커서를 받아와야 합니다.

7-5. 특정 데이터 단일 조회: .where()와 session.scalar()

조건절 추가: select(Item).where(Item.id == item_id)
단일 객체 1개만 꺼낼 때는 .all()이 아니라 **.scalar()**를 호출합니다:

stmt = select(Item).where(Item.id == 1)

# 단 1개의 Item 인스턴스를 반환 (없으면 None)
item = session.scalar(stmt)
if item:
    print(item.name, item.price)

8. FastAPI + SQLAlchemy 연동 실전 영속 CRUD 구현

8-1. DB 연결 및 세션 팩토리 공통 모듈 (connection.py)

# connection.py
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "sqlite:///./test.db"

# echo=True: 터미널에 실행되는 SQL 출력
engine = create_engine(
    DATABASE_URL,
    echo=True,
    connect_args={"check_same_thread": False}  # SQLite를 FastAPI에서 쓸 때 필수 옵션
)

# 세션 생성 공장(SessionFactory)
SessionFactory = sessionmaker(
    bind=engine,
    autocommit=False,
    autoflush=False,
    expire_on_commit=False
)

8-2. [Create] 상품 생성 (POST /items, try-finally vs Context Manager)

세션을 열고 닫는 방식에는 2가지 패턴이 있습니다.

방법 A: try-finally 패턴 (슬라이드 14페이지)

@app.post("/items", response_model=ItemResponse, status_code=201)
def create_item(body: ItemCreateRequest):
    session = SessionFactory()
    try:
        new_item = Item(name=body.name, price=body.price)
        session.add(new_item)
        session.commit()
        return new_item
    finally:
        session.close()  # 에러가 발생해도 세션은 반드시 닫힘

방법 B: Context Manager (with) 패턴 (슬라이드 15페이지 - 추천!)

@app.post("/items", response_model=ItemResponse, status_code=201)
def create_item(body: ItemCreateRequest):
    # with 블록을 빠져나갈 때 session.close()가 자동으로 호출됨!
    with SessionFactory() as session:
        new_item = Item(name=body.name, price=body.price)
        session.add(new_item)
        session.commit()
        return new_item

8-3. [Read All] 전체 상품 조회 (GET /items, scalars().all())

@app.get("/items", response_model=list[ItemResponse])
def list_items():
    session = SessionFactory()
    try:
        stmt = select(Item)
        items = session.scalars(stmt).all()
        return items
    finally:
        session.close()

8-4. [Read One] 단일 상품 상세 조회 (GET /items/{item_id}, 404 예외)

@app.get("/items/{item_id}", response_model=ItemResponse)
def get_item(item_id: int):
    session = SessionFactory()
    try:
        stmt = select(Item).where(Item.id == item_id)
        item = session.scalar(stmt)
        
        # 상품이 존재하지 않으면 404 에러 반환
        if item is None:
            raise HTTPException(status_code=404, detail="Item not found")
            
        return item
    finally:
        session.close()

8-5. [Update] 상품 부분 수정 (PATCH /items/{item_id}, DB 변경 반영)

수정할 필드가 전달되었는지(is not None) 각각 독립적인 if문으로 검사한 뒤 session.commit()을 호출하면 DB에 즉시 UPDATE SQL이 실행됩니다.

@app.patch("/items/{item_id}", response_model=ItemResponse)
def patch_item(item_id: int, body: ItemUpdateRequest):
    session = SessionFactory()
    try:
        stmt = select(Item).where(Item.id == item_id)
        item = session.scalar(stmt)
        
        if item is None:
            raise HTTPException(status_code=404, detail="Item not found")
        
        # 1. 이름이 들어왔으면 수정
        if body.name is not None:
            item.name = body.name
            
        # 2. 가격이 들어왔으면 수정 (elif가 아닌 독립된 if문!)
        if body.price is not None:
            item.price = body.price
            
        session.commit()  # 변경 사항 DB 반영
        return item
    finally:
        session.close()

8-6. [Delete] 상품 삭제 (DELETE /items/{item_id}, session.delete)

DB에서 조회한 ORM 객체를 session.delete(item)에 전달하고 커밋하면 DELETE SQL이 실행됩니다.
삭제 성공 시 본문 없는 204 No Content 응답을 반환합니다.

from fastapi import Response

@app.delete("/items/{item_id}", status_code=204)
def delete_item(item_id: int):
    session = SessionFactory()
    try:
        stmt = select(Item).where(Item.id == item_id)
        item = session.scalar(stmt)
        
        if item is None:
            raise HTTPException(status_code=404, detail="Item not found")
            
        session.delete(item)    # DB에서 삭제 예약
        session.commit()         # 삭제 확정
        return Response(status_code=204)
    finally:
        session.close()

9. 실전 핵심 요약 치트시트

┌────────────────────────────────────────────────────────────────────────┐
│            FastAPI & SQLAlchemy ORM 데이터베이스 핵심 치트시트         │
├──────────────────────────────┬─────────────────────────────────────────┤
│ 문법 / 개념                  │ 핵심 요약 및 사용 공식                  │
├──────────────────────────────┼─────────────────────────────────────────┤
│ RDB 도입 이유                │ 영속성(재시작 시 보존), 동시성, 신뢰성 │
├──────────────────────────────┼─────────────────────────────────────────┤
│ ORM 매핑 3대 공식            │ 테이블 = 클래스 / 행 = 객체 / 열 = 속성 │
├──────────────────────────────┼─────────────────────────────────────────┤
│ Engine                       │ create_engine() : DB 물리적 연결 통로   │
├──────────────────────────────┼─────────────────────────────────────────┤
│ Session                      │ SessionFactory() : DB 작업 창구/트랜잭션│
├──────────────────────────────┼─────────────────────────────────────────┤
│ class Base(DeclarativeBase): │ 모든 ORM 모델의 부모 클래스 선언        │
├──────────────────────────────┼─────────────────────────────────────────┤
│ Mapped[T] = mapped_column()  │ SQLAlchemy 2.0 표준 컬럼 타입 매핑 문법 │
├──────────────────────────────┼─────────────────────────────────────────┤
│ Base.metadata.create_all()   │ 파이썬 모델 기준으로 실제 DB 테이블 생성│
├──────────────────────────────┼─────────────────────────────────────────┤
│ session.add(item)            │ 영속성 관리 영역(Staging)에 등록        │
├──────────────────────────────┼─────────────────────────────────────────┤
│ session.commit()             │ 변경 사항을 실제 DB 파일에 최종 확정    │
├──────────────────────────────┼─────────────────────────────────────────┤
│ session.close()              │ DB 세션 및 연결 자원 반납               │
├──────────────────────────────┼─────────────────────────────────────────┤
│ with SessionFactory() as s:  │ Context Manager로 세션 자동 닫기 보장   │
├──────────────────────────────┼─────────────────────────────────────────┤
│ session.scalars(stmt).all()  │ 쿼리 결과를 ORM 객체 리스트로 추출      │
├──────────────────────────────┼─────────────────────────────────────────┤
│ result.mappings().all()      │ 쿼리 결과를 딕셔너리 리스트로 추출      │
├──────────────────────────────┼─────────────────────────────────────────┤
│ session.scalar(stmt)         │ .where() 조건에 맞는 단일 객체 1개 추출 │
├──────────────────────────────┼─────────────────────────────────────────┤
│ session.delete(item)         │ 조회된 ORM 객체를 DB에서 삭제           │
└──────────────────────────────┴─────────────────────────────────────────┘

FastAPI 2일차

write31991 — Fri, 23 Oct 2026 15:25:14 +0900

⚡ FastAPI & Pydantic 데이터 검증과 실전 CRUD 완벽 정리 노트

Python 백엔드의 심장 **타입 힌트(Type Hints)**부터 Request Body와 직렬화/역직렬화 메커니즘, Pydantic의 핵심 동작 원리(BaseModel, Field, model_dump), Response Model의 3대 가치(검증, 민감정보 필터링, 문서화), HTTP 상태 코드(201, 200, 204, 404, 422) 설계 표준, 그리고 HTTPException 에러 핸들링과 완벽한 CRUD(Create, Read, Update, Delete) 풀 구현까지 총정리한 실전 가이드

1. Type Hints (타입 힌트)의 본질과 모던 문법

1-1. Type Hints를 쓰는 4대 이유 (왜 FastAPI는 타입 힌트 위에 지어졌는가?)

파이썬은 원래 동적 타입(Dynamic Typing) 언어입니다. 즉, 변수에 어떤 값을 넣어도 에러가 나지 않는 자유로움이 있지만, 프로젝트 규모가 커지면 "이 함수에 문자열을 넣어야 하나? 숫자를 넣어야 하나?" 헷갈리게 됩니다.

Python 3.5+부터 도입된 Type Hints는 변수, 함수의 매개변수, 반환값에 "의도된 데이터 타입"을 명시하는 문법입니다.

Note

순수 Python과 FastAPI의 결정적 차이:

순수 파이썬 인터프리터는 타입 힌트를 작성해도 실행 자체를 강제하지 않습니다 (힌트일 뿐 무시함).
하지만 FastAPI와 Pydantic은 이 타입 힌트를 런타임에 직접 읽어와서(Reflection) 데이터 유효성 검사 규칙 및 직렬화 규칙으로 자동 승격시킵니다!

1-2. 기본 자료형과 유니온 타입 (|)

변수명 뒤에 콜론(:)을 붙이고 원하는 데이터 타입을 명시합니다.
Python 3.10부터는 Union[int, float] 대신 파이프 기호(|)를 사용하여 여러 타입을 허용할 수 있습니다.

# 1. 단일 기본 타입 힌트
name: str = "alex"          # 문자열
price: int = 100            # 정수
ratio: float = 0.3          # 실수(부동소수점)
is_active: bool = True      # 불리언 (참/거짓)

# 2. 유니온 타입 (|): 둘 이상의 타입을 허용하고 싶을 때
# 정수 또는 실수를 모두 허용
score: int | float = 90
score = 85.5  # ✅ 둘 다 정상

1-3. 함수의 인자 및 반환 타입 지정 (->)

함수 매개변수에는 콜론(:), 함수의 최종 반환값에는 화살표(->)를 사용하여 타입을 명시합니다.

def add(n1: int, n2: int) -> int:
    """정수 2개를 입력받아 정수 합을 반환하는 함수"""
    return n1 + n2

result = add(10, 20)
# IDE는 result가 int임을 즉시 알고 int 전용 메서드를 자동완성해 줍니다!

1-4. 컬렉션 타입 (list[T], dict[K, V], 중첩 구조)

리스트나 딕셔너리 내부의 원소 타입까지 구체적으로 명시할 수 있습니다.

# 1. 문자열만 담긴 리스트
names: list[str] = ["alex", "bob", "chris"]

# 2. 정수, 실수, None을 모두 담을 수 있는 유연한 리스트
numbers: list[int | float | None] = [100, 90.5, 80, None]

# 3. 키는 str, 값은 int 또는 None을 갖는 딕셔너리
scores: dict[str, int | None] = {
    "math": 90,
    "eng": 100,
    "history": None
}

# 4. 실무에서 가장 흔한 '딕셔너리들의 리스트' (중첩 구조)
users: list[dict[str, int | str]] = [
    {"id": 1, "name": "alex"},
    {"id": 2, "name": "bob"}
]

1-5. Optional 타입 (T | None = None)

어떤 데이터가 **"있을 수도 있고, 없을 수도 있는 경우(None 허용)"**에 사용합니다.

# 값이 안 들어오면 기본값으로 None을 가짐
name: str | None = None

# 나중에 문자열이 채워질 수 있음
name = "alex"

2. Request Body와 데이터 직렬화 / 역직렬화

2-1. Path/Query vs Request Body의 결정적 차이

구분 Path Parameter Query Parameter Request Body (요청 본문)

전달 위치	URL 경로 자체 (/items/3)	URL 뒤 쿼리스트링 (?page=1)	HTTP 요청 본문(Body) 내부
데이터 형식	단순 문자열 / 숫자	단순 Key-Value 문자열	복잡한 JSON 객체, 중첩 리스트 등 대용량 데이터
주 사용 목적	리소스 식별(Identify)	필터링, 정렬, 검색 옵션	데이터 신규 등록(POST), 수정(PUT/PATCH)
보안/노출	URL 및 서버 접근 로그에 그대로 노출	URL 및 로그에 노출	URL에 노출되지 않아 비교적 안전

2-2. 직렬화(Serialization) vs 역직렬화(Deserialization) 개념 정리

네트워크 통신에서 컴퓨터 메모리 속 객체와 네트워크 전송용 문자열은 서로 변환 과정을 거쳐야 합니다.

Unable to render rich display

Parse error on line 10:
... CJ -->|1. HTTP 요청 (Request)<br/>JSON ➔
-----------------------^
Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND', 'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'PS'

For more information, see https://docs.github.com/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams

graph LR
    subgraph Client["  클라이언트 (Browser / App)"]
        CJ["JSON 텍스트 포맷<br/>{'name': 'apple', 'price': 1000}"]
    end

    subgraph Server["⚡ FastAPI 서버 (Python Runtime)"]
        PO["Python 객체 (Pydantic Instance)<br/>item.name == 'apple'"]
    end

    CJ -->|1. HTTP 요청 (Request)<br/>JSON ➔ Python : 역직렬화 (Deserialization)| PO
    PO -->|2. HTTP 응답 (Response)<br/>Python ➔ JSON : 직렬화 (Serialization)| CJ

역직렬화 (Deserialization):
클라이언트가 보낸 HTTP 요청 본문의 JSON 문자열을 파이썬이 다룰 수 있는 객체/딕셔너리로 조립하는 과정.
직렬화 (Serialization):
서버 내부의 파이썬 데이터(Pydantic 모델, 딕셔너리, 리스트)를 전송 가능한 JSON 문자열로 변환하여 HTTP 응답 본문에 싣는 과정.

3. Pydantic: 데이터 검증과 파싱의 핵심 엔진

3-1. FastAPI의 2대 지주 (Starlette vs Pydantic)

FastAPI는 바퀴를 다시 발명하지 않고, 세상에서 가장 뛰어난 두 오픈소스를 결합하여 탄생했습니다.

3-2. BaseModel 정의와 자동 타입 변환 원리

Pydantic의 모든 데이터 모델은 **BaseModel**을 상속받아 클래스로 정의합니다.

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: int

타입 강제 변환(Type Coercion):
만약 클라이언트가 {"name": "apple", "price": "1000"} 처럼 숫자를 문자열로 보냈더라도, Pydantic은 int로 변환 가능하면 자동으로 정수 1000으로 파싱해 줍니다.
타입 검증 실패:
만약 {"name": "apple", "price": "cheap"} 처럼 정수로 바꿀 수 없는 값을 넣으면 Pydantic은 즉시 에러를 발생시킵니다.

3-3. Pydantic 핵심 메서드 4선 (model_dump, model_dump_json, model_validate)

Pydantic v2 기준, 실무에서 매일 사용하는 필수 메서드들입니다:

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: int

# 1. 인스턴스 생성
item = Item(name="apple", price=1000)
print(item)  # 출력: name='apple' price=1000

# 2. model_dump(): Pydantic 인스턴스를 순수 파이썬 dict로 변환
dict_data = item.model_dump()
print(dict_data)  # {'name': 'apple', 'price': 1000}

# 3. model_dump_json(): Pydantic 인스턴스를 JSON 문자열로 변환
json_str = item.model_dump_json()
print(json_str)   # '{"name":"apple","price":1000}'

# 4. model_validate(): 기존 dict 데이터를 검증하여 Pydantic 인스턴스로 복원
raw_dict = {"name": "banana", "price": 2000}
banana_item = Item.model_validate(raw_dict)
print(banana_item.name)  # "banana"

3-4. Field(...)를 활용한 정밀한 유효성 검사 (min_length, ge, le)

단순 타입 체크를 넘어, 글자수 최소/최대 제한, 숫자의 범위 제한을 걸 수 있습니다.

from pydantic import BaseModel, Field

class Item(BaseModel):
    # 이름은 필수(...)이며 최소 2글자 이상
    name: str = Field(..., min_length=2, description="상품 이름 (2자 이상)")
    
    # 가격은 필수(...)이며 0원 이상 (음수 가격 방지)
    price: int = Field(..., ge=0, description="상품 가격 (0원 이상)")

# ❌ 검증 실패 예시:
# Item(name="a", price=-10) 
# -> 1) name 길이가 2 미만이므로 에러!
# -> 2) price가 0보다 작으므로 에러!

4. FastAPI에서 Request Body 다루기

4-1. Pydantic 모델을 타입 힌트로 전달하여 인스턴스 자동 주입받기

FastAPI 엔드포인트 함수의 매개변수에 BaseModel을 상속받은 클래스를 타입으로 적어주면 끝납니다!

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class CreateItemRequest(BaseModel):
    name: str
    price: int

@app.post("/items", summary="새로운 상품 등록 API")
def create_item(body: CreateItemRequest):
    # FastAPI가 내부적으로 CreateItemRequest(**request_json) 인스턴스를 만들어 주입함!
    return body

4-2. 점(.) 표기법을 통한 안전하고 편리한 데이터 접근

딕셔너리의 body["name"] 방식은 오타가 나도 실행 전까지 알기 어렵습니다.
반면 Pydantic 모델은 점(.) 표기법을 지원하므로 오타가 나면 IDE가 즉시 경고를 띄워줍니다.

@app.post("/items")
def create_item_handler(body: CreateItemRequest):
    # 안전하고 직관적인 점 표기법
    new_item = {
        "id": 1,
        "name": body.name,   # ✅ 자동완성 지원
        "price": body.price  # ✅ 자동완성 지원
    }
    return new_item

4-3. 기본값(Default)과 선택 필드(Optional Field) 설계

클라이언트가 특정 필드를 보내지 않아도 오류가 나지 않도록 기본값을 부여할 수 있습니다.

class Item(BaseModel):
    name: str                             # 필수값 (기본값 없음)
    price: int                            # 필수값 (기본값 없음)
    description: str | None = None        # 선택값 (생략 시 None)
    is_active: bool = True                # 선택값 (생략 시 True)

4-4. 계층형 JSON을 처리하는 중첩 모델 (Nested Model)

실무에서 자주 쓰이는 복잡한 계층형 JSON 구조도 Pydantic 클래스 안에 다른 Pydantic 클래스를 넣으면 완벽하게 검증됩니다.

class User(BaseModel):
    id: int
    name: str

class Order(BaseModel):
    user: User      # User 모델을 중첩 필드로 포함
    amount: int

@app.post("/orders")
def create_order(order: Order):
    # 클라이언트 전송 JSON 형태:
    # {
    #   "user": { "id": 1, "name": "alex" },
    #   "amount": 50000
    # }
    print(order.user.name)  # "alex"
    return order

5. Response Model (응답 모델)의 3대 핵심 가치

데코레이터에 **response_model=Pydantic클래스**를 지정하면 서버가 클라이언트에게 내보내는 응답 데이터를 엄격하게 통제할 수 있습니다.

@app.post("/items", response_model=ItemResponse)
def create_item(item: ItemCreateRequest):
    ...

5-1. 왜 응답 모델을 별도로 지정해야 하는가?

데이터베이스(DB)에서 데이터를 꺼내오면 password, created_at, internal_score 등 클라이언트에게 절대 노출되면 안 되는 필드들이 함께 딸려옵니다.
만약 이를 그대로 return하면 **심각한 보안 사고(개인정보 노출)**로 이어집니다.

5-2. 가치 2: 민감정보 마스킹 및 불필요한 필드 자동 제거 (Filtering)

# 클라이언트에게 응답할 모델 정의 (비밀번호 없음!)
class UserResponse(BaseModel):
    id: int
    username: str

@app.get("/users/{user_id}", response_model=UserResponse)
def get_user(user_id: int):
    # DB에서 조회한 원본 데이터 (민감한 password 포함)
    db_user = {
        "id": 1,
        "username": "alex",
        "password": "super-secret-password-1234",  #   위험 필드!
        "internal_memo": "블랙리스트 유저 아님"
    }
    
    # response_model=UserResponse 덕분에 FastAPI가 password를 자동으로 버려줌!
    return db_user
    # 클라이언트가 최종 수신하는 JSON:
    # { "id": 1, "username": "alex" }

Important

핵심 요약:
함수 내부에서 아무리 많은 필드가 담긴 딕셔너리를 반환하더라도, response_model에 선언되지 않은 필드는 FastAPI가 깨끗하게 걸러내고(제거하고) 안전한 데이터만 반환합니다!

5-3. 가치 3: 프론트엔드 협업을 위한 Swagger 문서 자동화

response_model=list[ItemResponse]를 걸어두면, Swagger UI 문서에 이 API가 어떤 구조의 JSON 리스트를 돌려주는지(키 이름, 데이터 타입)가 시각적으로 완벽하게 표시됩니다.
프론트엔드 개발자는 백엔드 코드를 보지 않고도 문서를 보고 바로 화면을 연동할 수 있습니다.

6. HTTP 상태 코드 (Status Code) 설계 표준

6-1. 상태 코드의 정의와 숫자의 의미

HTTP 상태 코드는 클라이언트의 요청에 대해 서버가 처리 결과를 3자리 숫자로 명확하게 알려주는 전 세계 공통 약속입니다.
- 2xx: 성공 (Success)
- 4xx: 클라이언트 요청 오류 (Client Error - 잘못된 파라미터, 권한 없음 등)
- 5xx: 서버 내부 오류 (Server Error - 코드 버그, DB 다운 등)

6-2. CRUD 기능별 표준 Method & Status Code 매핑표

FastAPI 개발 시 무조건 준수해야 하는 REST API 상태 코드 표준 매핑입니다:

CRUD 기능 HTTP Method 표준 상태 코드 상태 코드 이름 설명

생성 (Create)	POST	201	Created	새로운 리소스가 성공적으로 생성됨
전체 조회 (Read)	GET	200	OK	요청이 성공적으로 처리됨
단일 조회 (Read)	GET	200	OK	단일 데이터 조회 성공
수정 (Update)	PUT / PATCH	200	OK	리소스 수정 성공
삭제 (Delete)	DELETE	204	No Content	삭제 성공 (본문에 반환할 데이터가 없음)
자원 없음	모든 Method	404	Not Found	요청한 ID의 리소스가 존재하지 않음
데이터 검증 실패	모든 Method	422	Unprocessable Entity	Pydantic 타입/길이 검증 규칙 위반

6-3. @app.post(..., status_code=201) 적용법

FastAPI는 기본 성공 상태 코드가 200이므로, 신규 생성(POST)이나 삭제(DELETE)는 데코레이터에서 상태 코드를 명시해야 합니다.

# 신규 상품 생성 시 201 Created 지정
@app.post("/items", response_model=ItemResponse, status_code=201)
def create_item(body: ItemCreateRequest):
    ...

# 상품 삭제 성공 시 204 No Content 지정
@app.delete("/items/{item_id}", status_code=204)
def delete_item(item_id: int):
    ...

7. 에러 처리 (Error Handling) & HTTPException

7-1. HTTPException의 역할과 문법

서버 로직 수행 중 비정상적인 상황(예: 찾는 상품이 없음)을 마주쳤을 때, 서버 프로세스를 다운시키지 않고 클라이언트가 납득할 수 있는 정돈된 HTTP 에러 응답을 던지는 도구입니다.

from fastapi import FastAPI, HTTPException

app = FastAPI()

# 에러 발생 시 즉시 코드 실행 중단 및 404 응답 반환
raise HTTPException(
    status_code=404,
    detail="요청하신 상품을 찾을 수 없습니다."
)

클라이언트 수신 JSON:

{
  "detail": "요청하신 상품을 찾을 수 없습니다."
}

8. 실전 실습: 요청-응답 유효성 검증 (POST /hello)

과제 요구사항:
1. 엔드포인트: POST /hello
2. 요청 본문 형식: {"name": "xxx"} 검증
3. 응답 형식: {"message": "안녕하세요, xxx님!"} 형식 검증
4. 특수 조건: name이 빈 문자열("")이면 {"message": "이름을 입력하세요"} 반환

완성 코드:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 1. 요청 모델 정의
class HelloRequest(BaseModel):
    name: str

# 2. 응답 모델 정의
class HelloResponse(BaseModel):
    message: str

@app.post("/hello", response_model=HelloResponse)
def say_hello(body: HelloRequest):
    # 빈 문자열 검증 (공백 제거 후 체크)
    if not body.name.strip():
        return HelloResponse(message="이름을 입력하세요")
    
    return HelloResponse(message=f"안녕하세요, {body.name}님!")

9. 대망의 완성: 실무형 CRUD API 완벽 구현

슬라이드 24~32페이지의 모든 내용을 종합한 인메모리 상품 관리 풀 CRUD API 완성 소스코드입니다.

9-1. DTO(Data Transfer Object) 모델 분리 설계

from fastapi import FastAPI, HTTPException, Path, Body
from pydantic import BaseModel

app = FastAPI(title="상품 관리 CRUD API", version="1.0.0")

# 1. 등록용 요청 모델 (id는 서버가 생성하므로 받지 않음)
class ItemCreateRequest(BaseModel):
    name: str
    price: int

# 2. 부분 수정용 요청 모델 (수정하고 싶은 필드만 보낼 수 있도록 None 허용)
class ItemUpdateRequest(BaseModel):
    name: str | None = None
    price: int | None = None

# 3. 클라이언트 반환용 응답 모델
class ItemResponse(BaseModel):
    id: int
    name: str
    price: int

# 인메모리 데이터 저장소
ITEMS = [
    {"id": 1, "name": "apple", "price": 1000},
    {"id": 2, "name": "banana", "price": 2000},
    {"id": 3, "name": "cherry", "price": 3000},
]

9-2. [Create] 상품 등록 (POST /items, 201 Created)

@app.post("/items", response_model=ItemResponse, status_code=201, summary="상품 등록 API")
def create_item(body: ItemCreateRequest):
    new_item = {
        "id": len(ITEMS) + 1,
        "name": body.name,
        "price": body.price,
    }
    ITEMS.append(new_item)
    return new_item

9-3. [Read All] 전체 상품 조회 (GET /items, 200 OK)

@app.get("/items", response_model=list[ItemResponse], summary="상품 전체 조회 API")
def list_items():
    return ITEMS

9-4. [Read One] 단일 상품 상세 조회 (GET /items/{item_id}, 404 예외)

@app.get("/items/{item_id}", response_model=ItemResponse, summary="단일 상품 상세 조회 API")
def get_item(item_id: int = Path(..., ge=1, description="조회할 상품 ID")):
    for item in ITEMS:
        if item["id"] == item_id:
            return item
    
    # 끝까지 못 찾으면 404 에러 발생
    raise HTTPException(status_code=404, detail="상품을 찾을 수 없습니다.")

9-5. [Update] 상품 부분 수정 (PATCH /items/{item_id}, 독립 if문 주의점)

Warning

수정 로직 작성 시 치명적 주의점:
if body.name is not None: 뒤에 elif body.price is not None: 을 쓰면 안 됩니다!
elif를 쓰면 클라이언트가 이름과 가격을 둘 다 수정하려고 보냈을 때 이름만 바뀌고 가격은 무시됩니다.
반드시 독립된 개별 if문으로 각각 검사해야 합니다.

@app.patch("/items/{item_id}", response_model=ItemResponse, summary="상품 부분 수정 API")
def patch_item(
    item_id: int = Path(..., ge=1),
    body: ItemUpdateRequest = Body(...)
):
    for stored_item in ITEMS:
        if stored_item["id"] == item_id:
            # 1. 이름이 전달되었으면 이름 갱신
            if body.name is not None:
                stored_item["name"] = body.name
            
            # 2. 가격이 전달되었으면 가격 갱신 (독립적인 if문!)
            if body.price is not None:
                stored_item["price"] = body.price
                
            return stored_item

    # 대상 상품이 없으면 404 에러
    raise HTTPException(status_code=404, detail="상품을 찾을 수 없습니다.")

9-6. [Delete] 상품 삭제 (DELETE /items/{item_id}, 204 No Content)

@app.delete("/items/{item_id}", status_code=204, summary="상품 삭제 API")
def delete_item(item_id: int = Path(..., ge=1)):
    for item in ITEMS:
        if item["id"] == item_id:
            ITEMS.remove(item)
            # ⚠️ return을 명시하지 않으면 아래 404 코드로 흘러내려가므로 즉시 조기 반환!
            return

    raise HTTPException(status_code=404, detail="상품을 찾을 수 없습니다.")

10. 실전 핵심 요약 치트시트

┌────────────────────────────────────────────────────────────────────────┐
│               FastAPI & Pydantic & CRUD 핵심 치트시트                  │
├──────────────────────────────┬─────────────────────────────────────────┤
│ 문법 / 개념                  │ 핵심 요약 및 사용 공식                  │
├──────────────────────────────┼─────────────────────────────────────────┤
│ val: int | None = None       │ None을 허용하는 선택적 타입 힌트        │
├──────────────────────────────┼─────────────────────────────────────────┤
│ Request Body                 │ JSON으로 들어오는 대용량 요청 본문      │
├──────────────────────────────┼─────────────────────────────────────────┤
│ 직렬화 (Serialization)       │ Python 객체 ➔ JSON 문자열               │
├──────────────────────────────┼─────────────────────────────────────────┤
│ 역직렬화 (Deserialization)   │ JSON 문자열 ➔ Python 객체               │
├──────────────────────────────┼─────────────────────────────────────────┤
│ class Item(BaseModel):       │ Pydantic 기반 입출력 데이터 검증 모델   │
├──────────────────────────────┼─────────────────────────────────────────┤
│ model.model_dump()           │ Pydantic 모델을 순수 Python dict로 변환 │
├──────────────────────────────┼─────────────────────────────────────────┤
│ Field(..., min_length=2)     │ Pydantic 필드 상세 유효성 검사 규칙 설정│
├──────────────────────────────┼─────────────────────────────────────────┤
│ body: CreateItemRequest      │ Request Body를 Pydantic 객체로 자동 주입│
├──────────────────────────────┼─────────────────────────────────────────┤
│ response_model=ItemResponse  │ 응답 검증 + 민감 필드 자동 필터링(제거) │
├──────────────────────────────┼─────────────────────────────────────────┤
│ status_code=201              │ 리소스 신규 생성 성공 (POST 표준)       │
├──────────────────────────────┼─────────────────────────────────────────┤
│ status_code=204              │ 리소스 삭제 성공, 본문 없음 (DELETE 표준)│
├──────────────────────────────┼─────────────────────────────────────────┤
│ 422 Unprocessable Entity     │ Pydantic 타입 검증 실패 시 자동 반환    │
├──────────────────────────────┼─────────────────────────────────────────┤
│ raise HTTPException(404, ...)│ 리소스가 없을 때 던지는 명시적 에러 응답│
├──────────────────────────────┼─────────────────────────────────────────┤
│ PATCH 부분 수정 주의점       │ name과 price 검증 시 elif 금지!         │
│                              │ 각각 독립된 if문으로 처리할 것          │
└──────────────────────────────┴─────────────────────────────────────────┘

FastAPI 1일차

write31991 — Wed, 21 Oct 2026 17:09:26 +0900

⚡ FastAPI 기초 & AI 모델 서빙 완벽 정리 노트

Python 기반 고성능 웹 프레임워크 FastAPI의 핵심 철학과 아키텍처부터 가상환경 격리(.venv), 네트워크 통신 원리(외부 통신 vs localhost 내부 루프백), Python 객체의 JSON 자동 직렬화, 데코레이터(@app.get)의 역할, 대화형 API 문서(Swagger UI & ReDoc), Path Parameter vs Query Parameter의 명확한 구분과 유효성 검증(Path, Query), 그리고 라우팅 충돌 방지 원칙과 종합 이커머스 API 실전 구현까지 총정리한 실무 가이드

1. FastAPI란 무엇인가? (고성능 웹 API 프레임워크)

1-1. 'Fast'의 2가지 본질 (처리 속도 & 개발 속도)

FastAPI는 현대적인 Python 3.10+의 표준 기능(타입 힌트, 비동기)을 기반으로 구축된 최첨단 고성능 웹 API 프레임워크입니다.
이름에 붙은 **'Fast'**에는 엔지니어링 관점에서 2가지 중요한 의미가 담겨 있습니다:

실행 및 요청 처리 속도가 빠르다 (High Performance):
- 비동기 네트워킹 코어인 Starlette과 초고속 데이터 검증 라이브러리인 Pydantic을 기반으로 설계되었습니다.
- 전통적인 Python 웹 프레임워크(Django, Flask)에 비해 압도적으로 빠르며, **Node.js(Express)나 Go 언어에 필적하는 벤치마크 처리량(RPS)**을 달성합니다.
개발하는 속도가 빠르다 (Fast Development):
- 표준 Python 타입 힌트만 적어주면 데이터 유효성 검사, 직렬화, API 문서화가 자동으로 완료됩니다.
- 개발자의 반복적인 보일러플레이트 코드를 줄여 개발 생산성을 200~300% 향상시킵니다.

1-2. FastAPI의 3대 핵심 특징

빠른 성능 (Starlette 기반):
async / await 비동기 프로그래밍을 완벽 지원하여 I/O 바운드 작업(DB 쿼리, 외부 API 호출, ML 추론 요청)을 효율적으로 병렬 처리합니다.
타입 힌트 기반 자동 검증 (Type Hinting & Validation):
함수 인자에 user_id: int처럼 파이썬 타입만 지정하면, 요청 데이터의 타입을 자동으로 체크하고 잘못된 입력값은 사전에 422 에러로 차단합니다.
자동 API 문서 (Swagger UI & ReDoc):
코드를 작성하고 서버를 띄우는 순간, 브라우저에서 직접 테스트할 수 있는 대화형 웹 문서가 1초 만에 자동 생성됩니다.

Note

언제 FastAPI를 사용하는가?

RESTful 백엔드 API 마이크로서비스 구축
AI / ML / 딥러닝 모델 서빙 (PyTorch, TensorFlow, Scikit-learn, OpenAI API 래핑): 데이터 과학자와 머신러닝 엔지니어들이 가장 사랑하는 서빙 프레임워크의 표준입니다.

1-3. Python 웹 프레임워크 3대장 비교 (FastAPI vs Django vs Flask)

비교 항목 Django Flask ⚡ FastAPI

철학 & 아키텍처	풀스택, Batteries-Included (ORM, 어드민, 인증 기본 내장)	마이크로 프레임워크, 극단적 미니멀리즘과 높은 자유도	모던 API 전용 프레임워크, 비동기 네이티브, 타입 세이프
처리 성능	보통 (동기 중심, 전통적 WSGI)	보통 (동기 중심, 전통적 WSGI)	매우 빠름 (ASGI 기반, Starlette 코어)
타입 검증	수동 폼/시리얼라이저 작성 필요	서드파티 라이브러리(Marshmallow 등) 필요	Python 표준 타입 힌트로 자동 검증 (Pydantic)
API 문서화	Swagger 연동 시 별도 플러그인 필요	flasgger 등 외부 패키지 수동 세팅	코드 작성 즉시 Swagger/ReDoc 자동 생성
러닝 커브	높음 (규칙과 내부 구조가 방대함)	낮음 (시작은 쉬우나 규모 확장 시 설계 어려움)	낮음~보통 (직관적인 문법, 명확한 에러 메시지)
주요 사용처	대규모 모놀리식 웹 서비스, 관리자 페이지	간단한 프로토타입, 소규모 웹 사이트	고성능 REST API 서버, AI/ML 모델 서빙

2. 개발 환경 구축과 가상환경(.venv)의 본질

2-1. 왜 프로젝트마다 가상환경을 분리해야 하는가?

컴퓨터의 전역(Global) 파이썬 환경에 라이브러리를 마구잡이로 설치하면, 프로젝트 A(예: FastAPI 0.95, Pydantic v1)와 프로젝트 B(FastAPI 0.110, Pydantic v2) 간의 **패키지 버전 충돌(Dependency Hell)**이 발생합니다.
**가상환경(Virtual Environment)**은 프로젝트 폴더 내부에 파이썬 실행 파일과 라이브러리를 격리 보관하는 독립된 방입니다.
폴더 이름 관례 (.venv):
- 이름 앞에 붙은 점(.)은 운영체제에서 숨김(Hidden) 파일/디렉터리를 의미합니다.
- 소스 코드가 아니라 환경 설정 격리용 디렉터리이므로 Git 관리 대상에서 제외(.gitignore)합니다.
- 보통 프로젝트 폴더 하나당 하나의 가상환경만 생성하여 사용합니다.

2-2. OS별 가상환경 생성 및 활성화 명령어 (macOS vs Windows)

# 1. 프로젝트 폴더 생성 및 이동
mkdir fastapi-study && cd fastapi-study

# 2. Python 3.10+ 버전 확인
python3 --version

# 3. .venv 가상환경 생성
python3 -m venv .venv

가상환경 활성화(Activate) 명령어 비교:

운영체제 (OS) 가상환경 활성화 명령어 터미널 표시 변화 비활성화(종료) 명령어

macOS / Linux	source .venv/bin/activate	프롬프트 앞에 (.venv) 표시	deactivate
Windows (CMD)	.venv\Scripts\activate.bat	프롬프트 앞에 (.venv) 표시	deactivate
Windows (PowerShell)	.venv\Scripts\Activate.ps1	프롬프트 앞에 (.venv) 표시	deactivate

2-3. 활성화 전후의 파이썬 인터프리터 경로 변화

which python3 (Windows의 경우 where python) 명령어로 파이썬 실행 위치를 추적해보면 가상환경의 작동 원리가 선명해집니다.

활성화 전: OS 전체에서 공유하는 전역 파이썬 경로를 가리킴.
활성화 후: 터미널의 환경변수(PATH)가 변경되어, 내가 생성한 .venv 폴더 안의 파이썬 인터프리터와 pip 저장소를 바라보게 됨.

2-4. FastAPI 표준 패키지 설치 (pip install "fastapi[standard]")

가상환경이 켜진 상태((.venv) 확인)에서 아래 명령어를 실행합니다:

pip install "fastapi[standard]"

Tip

왜 "fastapi[standard]" 인가요?
과거에는 pip install fastapi uvicorn 처럼 서버 엔진을 따로 설치했으나, 최신 FastAPI는 [standard] 옵션을 붙여 설치하면 프로덕션 ASGI 서버인 Uvicorn, 개발용 CLI 도구인 FastAPI CLI, Pydantic 이메일 검증기 등이 한 번에 완벽하게 세팅됩니다.

2-5. 새 프로젝트 분석의 2대 진입점 (README.md & main.py)

현업이나 오픈소스에서 새로운 파이썬 백엔드 프로젝트를 인수인계받거나 열어볼 때는 다음 2가지를 먼저 확인합니다:

README.md: 프로젝트의 전체 소개, 목적, 아키텍처 다이어그램, 환경 변수 세팅 및 실행 가이드 역할.
main.py (또는 app.py): 전체 애플리케이션의 코드 진입점(Entry Point). app = FastAPI() 인스턴스가 생성되고 라우터들이 등록되는 출발점.

3. FastAPI 서버 실행과 네트워크 통신 메커니즘

3-1. 개발 서버 기동: fastapi dev 명령어

main.py 파일이 있는 위치에서 터미널에 아래 명령어를 입력합니다:

fastapi dev
# 또는 명시적 파일 지정: fastapi dev main.py

fastapi dev의 핵심 기능:
- http://127.0.0.1:8000 (8000번 포트)에서 개발 서버 자동 시작.
- 핫 리로드 (Auto-reload): 코드를 수정하고 저장(Ctrl + S)하면 서버가 재시작 없이 실시간으로 변경 사항을 감지하여 반영.
- 대화형 문서 링크 자동 안내 (Documentation at http://127.0.0.1:8000/docs).

3-2. 외부 요청(naver.com/DNS) vs 내부 요청(localhost:8000/루프백) 완벽 비교

우리가 브라우저 주소창에 주소를 칠 때, 외부 웹사이트 접속과 로컬 개발 서버 접속은 네트워크 레벨에서 근본적으로 다르게 동작합니다.

Unable to render rich display

Parse error on line 5:
... -->|3. 실제 공인 IP 반환 (예: 223.130.195.95)|
-----------------------^
Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND',
'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'PS'

For more information, see https://docs.github.com/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams

graph TD
    subgraph Case1["1. 외부 서버에 요청하는 경우 (naver.com)"]
        U1["내 컴퓨터 브라우저 (Chrome)"] -->|1. naver.com 입력| OS1["운영체제 O/S 네트워크 스택"]
        OS1 -->|2. 외부 DNS 서버 질의| DNS["DNS 서버 (전화번호부)"]
        DNS -->|3. 실제 공인 IP 반환 (예: 223.130.195.95)| OS1
        OS1 -->|4. 광랜/인터넷망 경유| EXT["원격지 네이버 데이터센터 서버"]
    end

    subgraph Case2["2. 내 컴퓨터에 요청하는 경우 (localhost:8000)"]
        U2["내 컴퓨터 브라우저 (Chrome)"] -->|1. localhost:8000 입력| OS2["운영체제 O/S (루프백 감지)"]
        OS2 -->|2. 외부 인터넷으로 나가지 않음!| LOCAL["내 컴퓨터 내부 8000번 포트 (FastAPI 서버)"]
    end

구분 외부 서버 요청 (https://naver.com) 내부 로컬 요청 (localhost:8000)

목적지	전 세계 어딘가에 위치한 원격 데이터센터 서버	현재 내가 작업하고 있는 바로 그 컴퓨터
DNS 질의	외부 DNS 서버를 거쳐 실제 공인 IP(예: 1.2.3.4)를 알아옴	DNS 질의 불필요 (localhost는 OS 내부에서 127.0.0.1로 즉시 해석)
네트워크 경로	공유기 ➔ 통신사 망 ➔ 인터넷 백본망 ➔ 목적지 서버	루프백 인터페이스(Loopback Interface)를 타고 컴퓨터 내부에서 유턴
인터넷 연결 필요 여부	인터넷이 끊기면 통신 불가	인터넷(Wi-Fi)이 완전히 끊겨도 로컬 테스트 100% 가능

3-3. Python 데이터의 자동 JSON 직렬화 원리 (list/dict ➔ JSON)

HTTP 프로토콜의 엄격한 제약:
- 클라이언트(웹 브라우저, 모바일 앱)와 서버가 주고받는 HTTP 응답 메시지의 본문(Body)에는 JSON 문자열 형태의 텍스트만 실을 수 있습니다.
FastAPI의 자동 변환(Serialization) 마법:
- 개발자가 파이썬 함수에서 복잡하게 json.dumps()를 호출할 필요가 없습니다.
- 파이썬 딕셔너리나 리스트를 그대로 return하면, FastAPI가 내부적으로 HTTP 응답 헤더(Content-Type: application/json)와 함께 완벽한 JSON 규격으로 변환해 줍니다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items")
def get_items():
    # 파이썬 List와 Dict 자료구조 반환
    return [
        {"id": 1, "name": "apple", "price": 1000},
        {"id": 2, "name": "banana", "price": 2000}
    ]

Python 자료형과 JSON 데이터 타입 매핑표:

Python 자료형 변환 방향 표준 JSON 데이터 타입

dict (딕셔너리)	➔	JSON Object ({ "key": "value" })
list (리스트)	➔	JSON Array ([ 1, 2, 3 ])
tuple (튜플)	➔	JSON Array ([ "a", "b" ])
str (문자열)	➔	JSON String ("text")
int, float (숫자)	➔	JSON Number (123, 3.14)
bool (True, False)	➔	JSON Boolean (true, false)
None	➔	JSON Null (null)

4. Python 데코레이터(Decorator)와 라우팅 시스템

4-1. 데코레이터(@)의 본질과 동작 원리

**데코레이터(Decorator)**란:
어떤 함수를 수정하지 않고 감싸서(Wrapping), 해당 함수의 실행 전이나 후에 공통 로직(로깅, 인증, 시간 측정 등)을 덧붙여주는 파이썬 문법입니다.
핵심 가치: 중복 코드 제거, 선언적(Declarative) 기능 부여.

# [데코레이터의 기본 원리 구조]
def my_decorator(func):
    def wrapper(*args, **kwargs):
        print("--- [전처리] 함수 실행 전 공통 작업 ---")
        result = func(*args, **kwargs)
        print("--- [후처리] 함수 실행 후 공통 작업 ---")
        return result
    return wrapper

# @ 기호로 함수 위에 장식
@my_decorator
def hello():
    print("안녕하세요! 메인 비즈니스 로직입니다.")

hello()
# 출력 결과:
# --- [전처리] 함수 실행 전 공통 작업 ---
# 안녕하세요! 메인 비즈니스 로직입니다.
# --- [후처리] 함수 실행 후 공통 작업 ---

4-2. FastAPI에서 데코레이터의 역할 (@app.get)

FastAPI에서는 데코레이터가 일반 파이썬 함수를 웹 상에서 접근 가능한 'HTTP 엔드포인트(라우트)'로 승격시키는 결정적 역할을 합니다.

@app.get("/")
def root():
    return {"message": "Hello FastAPI"}

데코레이터가 수행하는 3가지 내부 작업:
1. HTTP 메서드 지정: get, post, put, delete 등 클라이언트가 어떤 방식으로 요청해야 하는지 정의.
2. URL 경로 매핑: 클라이언트가 브라우저 주소창에 / 경로로 요청을 보낼 때 이 함수를 실행하도록 라우팅 테이블에 등록.
3. 메타데이터 등록: 함수의 매개변수, 반환 타입, 주석을 읽어와 Swagger 문서(OpenAPI 스키마)에 자동 등록.
동작 비유: 프론트엔드의 addEventListener("click", handler)처럼, **"이 특정 URL로 GET 요청이 들어오면, 바로 밑에 있는 함수를 실행해 줘!"**라고 등록해 두는 것입니다.

4-3. 대화형 자동 API 문서 (Swagger UI & ReDoc)

서버가 켜진 상태에서 브라우저 주소창에 아래 주소를 입력하면 문서를 확인할 수 있습니다:

Swagger UI (http://localhost:8000/docs):
- 가장 널리 사용되는 대화형 테스트 대시보드.
- 각 API를 펼쳐서 Try it out 버튼을 누르면, Postman 같은 외부 툴 없이도 브라우저에서 실시간으로 파라미터를 입력하고 요청을 전송해 결과를 확인할 수 있습니다.
ReDoc (http://localhost:8000/redoc):
- 깔끔하고 정돈된 3단 레이아웃의 공식 개발자 API 명세서 페이지.
- 다른 팀이나 고객사에게 API 스펙을 공유할 때 매우 유용합니다.

5. Path Parameter (경로 매개변수)

5-1. Path Parameter의 정의와 리소스 식별(Identify)

Path Parameter (경로 매개변수): URL 경로 자체의 일부분으로 변수처럼 포함되어 전달되는 값입니다.
언제 사용하는가?: 특정 **리소스(자원)를 고유하게 식별(Identify)**할 때 사용합니다.
- 예: /users/3 ➔ 3번 고유 ID를 가진 유저 정보
- 예: /items/apple ➔ apple이라는 고유 식별명을 가진 아이템

# 경로에 중괄호 {user_id} 를 넣고, 함수 인자로 동일한 이름을 전달받음
@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

5-2. 타입 힌트 기반 자동 검증과 422 Unprocessable Entity

FastAPI는 파이썬의 타입 힌트(user_id: int)를 보고 자동으로 유효성 검사를 수행합니다.

정상 요청 (GET /users/3):
- URL의 문자열 "3"을 파이썬 정수 3으로 자동 형변환하여 함수에 전달 ➔ 200 OK 성공!
비정상 요청 (GET /users/abc):
- "abc"는 정수(int)로 변환할 수 없음.
- FastAPI가 함수 내부를 실행하기도 전에 가로채서 422 Unprocessable Entity 에러 응답을 자동으로 반환!

/* 422 에러 응답 예시 (FastAPI 자동 생성) */
{
  "detail": [
    {
      "type": "int_parsing",
      "loc": ["path", "user_id"],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "abc"
    }
  ]
}

5-3. 치명적 주의점: 라우팅 순서 충돌과 해결 공식

같은 접두사(prefix)를 가진 엔드포인트를 만들 때, 코드 작성 순서에 따라 심각한 라우팅 버그가 발생할 수 있습니다.

# ❌ 잘못된 순서 (버그 발생!)
@app.get("/items/{item_id}")
def get_item(item_id: str):
    return {"item_id": item_id}

@app.get("/items/search")
def search_item():
    return {"message": "검색 결과"}

왜 문제가 발생할까?
FastAPI는 라우트를 위에서 아래로 선언된 순서대로 매칭합니다.
만약 /items/{item_id}가 위에 있다면, 사용자가 /items/search를 호출했을 때 FastAPI는 "search"라는 단어를 {item_id} 변수 값으로 인식하여 위쪽 함수를 실행해 버립니다!

해결 공식 (라우팅 우선순위 원칙):

"고정된 정적 경로(/items/search)를 항상 코드 위쪽에 먼저 선언하고,
가변 변수가 들어간 경로(/items/{item_id})를 아래쪽에 나중에 선언하라!"

5-4. Path 고급 유효성 검사 옵션 (Path())

FastAPI의 Path 모듈을 사용하면 숫자 범위, 문자열 길이, Swagger 문서 설명 등을 강력하게 강제할 수 있습니다.

from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/users/{user_id}")
def get_user(
    user_id: int = Path(
        ...,                    # ... (Ellipsis)는 '필수값'임을 의미
        ge=1,                   # ge: Greater than or equal to (1 이상이어야 함)
        description="조회할 유저의 고유 ID (1 이상의 양수)"
    )
):
    return {"user_id": user_id}

주요 검증 키워드:

... (Ellipsis): 기본값이 없는 필수 파라미터임을 명시
ge (>=): 이상
gt (>): 초과
le (<=): 이하
lt (<): 미만
min_length, max_length: 문자열 최소/최대 길이 제한
description: Swagger 문서에 친절한 한글 설명 표시

5-5. [실습 1] Path Parameter 만들기 (max_length=6)

요구사항:
- 엔드포인트: GET /items/{item_name}
- item_name은 문자열(str) 타입이어야 하며, 최대 글자수(max_length)는 6글자 이하로 제한
응답 예시: /items/apple 입력 시 {"item_name": "apple"} 반환

완성 코드:

from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_name}")
def get_item(
    item_name: str = Path(..., max_length=6, description="6자 이하의 아이템 이름")
):
    return {"item_name": item_name}

6. Query Parameter (쿼리 매개변수)

6-1. Query Parameter의 정의와 주요 용도 (필터링·정렬·검색)

Query Parameter (쿼리 매개변수): URL 경로 끝에 물음표(?)를 붙이고 key=value 형태로 전달하는 데이터입니다. 여러 개일 경우 &로 연결합니다.
- 예: /search?q=fastapi&limit=10
주요 용도:
- 특정 리소스를 지칭하는 것이 아니라, 목록을 조회할 때 필터링(Filtering), 검색(Search), 정렬(Sorting), 페이지네이션(Pagination) 등의 부가 옵션을 줄 때 사용합니다.

6-2. 필수(Required) vs 선택(Optional/기본값) 파라미터 구분

URL 경로({})에 선언되지 않은 함수 매개변수는 FastAPI가 자동으로 Query Parameter로 취급합니다.

@app.get("/search")
def search(q: str, limit: int = 10):
    return {"q": q, "limit": limit}

q: str: 기본값이 지정되지 않았으므로 필수(Required) 쿼리 파라미터입니다. (?q=단어가 없으면 422 에러)
limit: int = 10: 기본값 10이 할당되어 있으므로 선택(Optional) 쿼리 파라미터입니다. (생략 시 자동으로 10이 적용됨)

6-3. Query 고급 옵션 (Query(), min_length, ge, le)

Path와 마찬가지로 from fastapi import Query를 임포트하여 쿼리 스트링에 대한 상세한 유효성 검증을 걸 수 있습니다.

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/search")
def search(
    q: str = Query(..., min_length=2, max_length=30, description="검색어 (2~30자)"),
    limit: int = Query(10, ge=1, le=100, description="한 페이지당 가져올 개수 (1~100)")
):
    return {"q": q, "limit": limit}

6-4. [실습 2] 상품 검색 API 만들기

요구사항:
- 엔드포인트: GET /products/search
- 쿼리 파라미터 q(검색어, str, 필수), limit(개수, int, 기본값 10)
응답 예시: /products/search?q=apple&limit=5 호출 시 {"q": "apple", "limit": 5} 반환

완성 코드:

from fastapi import FastAPI

app = FastAPI()

@app.get("/products/search")
def product_search(q: str, limit: int = 10):
    return {"q": q, "limit": limit}

7. Path Parameter vs Query Parameter 비교 및 혼합 사용

7-1. 언제 Path를 쓰고, 언제 Query를 쓰는가? (의사결정 기준)

구분 Path Parameter Query Parameter

URL 형태	/users/10	/users?role=admin&sort=desc
핵심 목적	리소스의 '고유 식별(Identification)'	리소스 목록의 '조건 제어(Filtering, Pagination)'
필수 여부	URL 경로의 일부이므로 무조건 필수	대부분 선택 옵션(기본값 제공 가능)
데이터 의미	"10번 유저를 가져와라"	"유저들 중 관리자 역할만 내림차순 정렬해서 가져와라"
RESTful 권장	자원의 계층 구조를 나타낼 때	자원을 정렬, 검색, 페이징할 때

7-2. Path와 Query를 동시에 결합한 엔드포인트 설계

실무에서는 리소스 식별과 조회 옵션을 동시에 전달하기 위해 두 방식을 함께 사용합니다.

# 예: 3번 유저의 게시글 중 5개만 조회
# GET /users/3/posts?limit=5
@app.get("/users/{user_id}/posts")
def list_user_posts(user_id: int, limit: int = 10):
    # user_id는 URL 경로에 있으므로 -> Path Parameter
    # limit는 URL 경로에 없으므로 -> Query Parameter
    return {
        "user_id": user_id,
        "limit": limit,
        "message": f"{user_id}번 유저의 게시글을 최대 {limit}개 조회합니다."
    }

8. 종합 실전 예제: 이커머스 상품 관리 API & Swagger 검증

강의 슬라이드 29페이지에 등장한 실무형 이커머스 상품 조회 및 검색 API 전체 완성 코드입니다.

8-1. 전체 상품 조회, 검색, 단일 상품 상세 조회 풀 소스코드

from fastapi import FastAPI, Path, Query

app = FastAPI(
    title="이커머스 상품 관리 API",
    description="FastAPI 기초 학습을 위한 상품 조회 및 검색 엔드포인트",
    version="1.0.0"
)

# 인메모리 가상 상품 데이터베이스
ITEMS = [
    {"id": 1, "name": "apple", "price": 1000},
    {"id": 2, "name": "banana", "price": 2000},
    {"id": 3, "name": "cherry", "price": 3000},
]

# 1. 전체 상품 조회 API
@app.get("/items", summary="전체 상품 조회 API")
def get_items_handler():
    """등록된 모든 상품의 리스트를 반환합니다."""
    return ITEMS


# 2. 상품 검색 API (고정 경로이므로 {item_id}보다 무조건 먼저 선언해야 함!)
@app.get("/items/search", summary="상품 검색 API")
def search_items_handler(
    q: str = Query(..., min_length=2, description="검색할 상품 키워드 (2자 이상)")
):
    """
    상품 이름에 검색 키워드(q)가 포함된 상품 목록을 필터링하여 반환합니다.
    예: /items/search?q=ap -> apple 상품 반환
    """
    searched = []
    for item in ITEMS:
        if q.lower() in item["name"].lower():
            searched.append(item)
    return searched


# 3. 단일 상품 상세 조회 API (변수 경로이므로 search보다 아래에 배치)
@app.get("/items/{item_id}", summary="단일 상품 상세 조회 API")
def get_item_detail_handler(
    item_id: int = Path(..., ge=1, le=3, description="조회할 상품의 ID (1~3 범위)")
):
    """
    고유 item_id를 받아 해당하는 단일 상품 정보를 반환합니다.
    인덱스는 0부터 시작하므로 item_id - 1로 접근합니다.
    """
    return ITEMS[item_id - 1]

8-2. Swagger UI 대시보드 테스트 및 유효성 에러 분석

서버 실행 후 http://localhost:8000/docs에 접속하면 아래와 같은 화면이 나타납니다:

OpenAPI 3.1 스키마 준수:
- summary로 지정한 한글 설명이 엔드포인트 오른쪽에 깔끔하게 노출됩니다.
- 파라미터 타입, 제약조건(min_length, ge, le), 필수 여부가 표 형태로 일목요연하게 표시됩니다.
- 잘못된 값을 넣고 Execute를 실행하면 FastAPI 엔진이 자동으로 검증 실패(422 HTTPValidationError)를 반환하는 것을 브라우저에서 즉시 체험할 수 있습니다.

9. 실전 핵심 요약 치트시트

┌────────────────────────────────────────────────────────────────────────┐
│                   FastAPI 기초 & 서빙 핵심 치트시트                    │
├──────────────────────────────┬─────────────────────────────────────────┤
│ 명령어 / 문법                │ 기능 및 핵심 사용 공식                  │
├──────────────────────────────┼─────────────────────────────────────────┤
│ python -m venv .venv         │ 프로젝트 전용 독립 가상환경 생성        │
├──────────────────────────────┼─────────────────────────────────────────┤
│ source .venv/bin/activate    │ 가상환경 활성화 (Windows: Scripts\activate)│
├──────────────────────────────┼─────────────────────────────────────────┤
│ pip install "fastapi[standard]"│ FastAPI + Uvicorn + CLI 통합 설치     │
├──────────────────────────────┼─────────────────────────────────────────┤
│ fastapi dev main.py          │ 핫 리로드 지원 로컬 개발 서버 구동      │
├──────────────────────────────┼─────────────────────────────────────────┤
│ localhost:8000               │ 외부로 나가지 않는 내 컴퓨터 내부 루프백│
├──────────────────────────────┼─────────────────────────────────────────┤
│ /docs                        │ Swagger UI 대화형 API 테스트 문서       │
├──────────────────────────────┼─────────────────────────────────────────┤
│ /redoc                       │ ReDoc 읽기 전용 공식 기술 문서         │
├──────────────────────────────┼─────────────────────────────────────────┤
│ @app.get("/경로")            │ 함수를 HTTP 엔드포인트로 등록하는 데코레이터│
├──────────────────────────────┼─────────────────────────────────────────┤
│ return {...} / [...]         │ 파이썬 딕셔너리/리스트를 자동 JSON 직렬화│
├──────────────────────────────┼─────────────────────────────────────────┤
│ {item_id}: int               │ Path Parameter (리소스 고유 식별용)     │
├──────────────────────────────┼─────────────────────────────────────────┤
│ 라우팅 선언 공식             │ 정적 경로(/search)를 항상 변수 경로      │
│                              │ (/{item_id})보다 먼저 위에 선언할 것!  │
├──────────────────────────────┼─────────────────────────────────────────┤
│ q: str                       │ Query Parameter (필수 검색어)           │
├──────────────────────────────┼─────────────────────────────────────────┤
│ limit: int = 10              │ Query Parameter (기본값 있는 선택 옵션) │
├──────────────────────────────┼─────────────────────────────────────────┤
│ Path(..., ge=1, le=100)      │ 경로 매개변수 범위 및 유효성 검사       │
├──────────────────────────────┼─────────────────────────────────────────┤
│ Query(..., min_length=2)     │ 쿼리 매개변수 글자수 및 조건 강제       │
├──────────────────────────────┼─────────────────────────────────────────┤
│ 422 Unprocessable Entity     │ 타입 검증 실패 시 자동 반환되는 HTTP 에러│
└──────────────────────────────┴─────────────────────────────────────────┘

HTML/CSS & Javascript 8일차

write31991 — Wed, 21 Oct 2026 10:29:48 +0900

JavaScript Web API 완벽 정리 노트: Timer, Storage & Fetch API

브라우저가 제공하는 강력한 도구 상자 **Web API의 핵심 3대장(Timer API, Web Storage API, Fetch API)**을 총정리한 실전 가이드입니다.
setInterval과 timerId를 활용한 카운트다운 타이머, LocalStorage vs SessionStorage의 수명·보안·객체 직렬화, 비동기(Asynchronous) 통신의 원리와 .then() 체이닝의 진실, GET/POST 통신과 얼리 리턴(Early Return) 최적화, 그리고 클라이언트 캐싱과 모던 프레임워크 상태 관리까지 한 번에 정리합니다.

1. Timer API: 주기적 실행과 제어 (setInterval & timerId)

1-1. setInterval의 기본 개념과 1초 주기 실행

setInterval(callback, delay): 브라우저 Web API로, 지정한 시간(밀리초, ms) 간격마다 등록된 콜백 함수를 무한히 반복 실행합니다. (1000ms = 1초)

// 1초(1000ms)마다 주기적으로 콘솔에 메시지 출력
setInterval(function () {
  console.log("1초마다 실행");
}, 1000);

1-2. timerId의 본질과 clearInterval

timerId: 브라우저 엔진이 활성화된 타이머들을 고유하게 식별하기 위해 발급해 주는 **식별 번호(ID)**입니다.
필요성:
1. 반복 실행 중인 타이머를 원하는 시점에 종료(clearInterval)하기 위해.
2. 사용자가 시작 버튼을 여러 번 연속으로 눌렀을 때, 타이머가 중복 생성되어 카운트 속도가 비정상적으로 빨라지는 버그를 사전에 방지하기 위해.

// 타이머를 실행하고 고유 식별 번호를 timerId 변수에 저장
const timerId = setInterval(function () {
  console.log("실행");
}, 1000);

// 특정 조건 도달 시 타이머 중단
clearInterval(timerId);

1-3. [실습 1] 5초 카운트다운 타이머와 버튼 연타 방지 가드

과제: "카운트다운 시작" 버튼을 클릭하면 5초부터 1초마다 숫자가 감소하고, 0초가 되면 타이머가 멈추며 "끝"을 출력하는 타이머를 작성하세요.

HTML

<button id="start">카운트다운 시작</button>
<p id="result"></p>

JavaScript

const startBtn = document.querySelector("#start");
const timeEl = document.querySelector("#result");

let time = 5;
let timerId = null; // 현재 타이머가 돌고 있는지 체크하는 상태값

startBtn.addEventListener("click", function () {
  //   [버튼 연타 방지 가드 / Early Return]
  // 이미 실행 중이면 추가 타이머를 만들지 않고 즉시 함수 종료!
  if (timerId !== null) return;

  // 시작 즉시 현재 시간 표시
  timeEl.textContent = time;

  // 1초마다 실행되는 타이머 등록
  timerId = setInterval(function () {
    time--; // 1초 감소

    if (time === 0) {
      // 0초가 되면 카운트다운 종료
      timeEl.textContent = "끝";
      clearInterval(timerId); // 타이머 반복 중단!
      timerId = null;         // 상태를 null로 리셋하여 다시 시작 가능하게 함
      time = 5;               // 다음 실행을 위해 시간 복구
    } else {
      timeEl.textContent = time; // 4, 3, 2, 1 화면 갱신
    }
  }, 1000);
});

2. Web Storage API: 브라우저 저장소 (LocalStorage vs SessionStorage)

2-1. Web Storage의 특징 (Key-Value & 문자열 저장)

브라우저가 클라이언트(사용자 컴퓨터) 환경에 제공하는 내장 데이터 저장소입니다.
3대 핵심 특징:
1. 서버 없는 로컬 데이터 보관: 데이터베이스(DB)나 백엔드 서버 없이도 브라우저 자체에 데이터를 저장하고 조회할 수 있습니다.
2. Key - Value 구조: 데이터는 언제나 고유한 이름(Key)과 실제 값(Value)의 쌍으로 저장됩니다.
3. 값은 항상 문자열(String): 숫자, 불리언, 객체, 배열 등 어떤 데이터를 넣어도 내부적으로는 문자열 형태로만 저장됩니다.

2-2. LocalStorage vs SessionStorage 완벽 비교

브라우저 스토리지의 두 축인 로컬 스토리지와 세션 스토리지의 결정적 차이는 **데이터의 수명(지속성)**과 **공유 범위(Scope)**입니다.

구분 로컬 스토리지 (Local Storage) ⏳ 세션 스토리지 (Session Storage)

데이터 수명 (지속성)	영구적 (Permanent) 사용자가 직접 삭제하거나 코드로 지우지 않는 한 브라우저를 닫거나 컴퓨터를 재부팅해도 보존됨	임시적 (Temporary) 해당 탭(Tab) 또는 브라우저 창을 닫는 즉시 메모리에서 영구 삭제됨
공유 범위 (Scope)	동일 도메인(Origin) 전체 공유 새 탭, 새 창을 여러 개 열어도 동일한 도메인이면 데이터가 실시간 공유됨	해당 탭(Tab) 단독 독립 공간 같은 사이트라도 탭마다 별개의 세션이 생성되며 서로 데이터를 공유하지 않음
만료 시간	없음 (수동 삭제 전까지 영구 유지)	탭 종료 시 자동 소멸
대표 활용 예시	• 자동 로그인 토큰/아이디 기억 • 다크 모드 / 라이트 모드 테마 설정 • 비회원 장바구니 목록 보관	• 일회성 설문조사 / 회원가입 폼 임시 데이터 • 은행 / 금융 웹사이트 일회성 로그인 세션 • 이전 페이지 뒤로가기 시 복구할 임시 UI 상태

2-3. 핵심 메서드 4총사 (setItem, getItem, removeItem, clear)

localStorage와 sessionStorage는 사용하는 메서드 이름과 문법이 100% 동일합니다.

// 1. 데이터 저장 (Key, Value)
localStorage.setItem("name", "Alex");
localStorage.setItem("theme", "dark");

// 2. 데이터 조회 (Key)
const username = localStorage.getItem("name");
console.log(username); // "Alex"
// ⚠️ 존재하지 않는 Key를 조회하면 null을 반환합니다.

// 3. 특정 데이터 1개 삭제 (Key)
localStorage.removeItem("name");

// 4. 스토리지 전체 데이터 비우기 (초기화)
localStorage.clear();

2-4. 객체(Object) 저장의 필수 공식: JSON 직렬화 & 역직렬화

Warning

스토리지에 객체를 그냥 넣으면 발생하는 대참사!
localStorage.setItem("user", { name: "Alex" });
위 코드를 실행하면 자바스크립트는 객체를 문자열로 강제 변환하여 "[object Object]"라는 쓸모없는 문자열로 저장해버립니다!

해결책:
- 저장할 때: JSON.stringify(객체)를 사용해 객체를 **JSON 문자열로 직렬화(Serialization)**하여 저장.
- 꺼낼 때: JSON.parse(문자열)를 사용해 JSON 문자열을 **다시 자바스크립트 객체로 역직렬화(Deserialization)**하여 사용.

const user = { name: "Alex", age: 20 };

// 1. 객체를 JSON 문자열로 변환하여 저장: '{"name":"Alex","age":20}'
localStorage.setItem("user", JSON.stringify(user));

// 2. 스토리지에서 문자열을 꺼내와서 다시 실제 JS 객체로 복원!
const savedUser = JSON.parse(localStorage.getItem("user"));

console.log(savedUser.name); // "Alex"
console.log(savedUser.age);  // 20

2-5. [실습 2] 새로고침해도 유지되는 입력값 저장 프로그램

과제: 이름을 입력하고 "저장" 버튼을 누르면 화면에 출력되고, 브라우저를 새로고침(F5)해도 이전 입력값이 그대로 남아있도록 구현하세요.

HTML

<input id="name" placeholder="이름 입력" />
<button id="save">저장</button>
<p id="result"></p>

JavaScript

const input = document.querySelector("#name");
const button = document.querySelector("#save");
const result = document.querySelector("#result");

// 1. [페이지 초기 로드 시점] 스토리지에 기존 저장된 이름이 있는지 확인
const savedName = localStorage.getItem("name");
if (savedName) {
  // 저장된 값이 존재하면 결과 문단에 즉시 복원 표시!
  result.textContent = savedName;
}

// 2. [저장 버튼 클릭 시점] 새 입력값을 스토리지에 저장하고 화면 갱신
button.addEventListener("click", function () {
  localStorage.setItem("name", input.value);
  result.textContent = input.value;
});

3. 브라우저 스토리지 보안 & 공용 PC 필수 보안 수칙

브라우저 스토리지는 접근이 매우 간편하지만, 보안 측면(XSS 공격, 공용 PC 개인정보 유출 등)에서 각별한 주의가 필요합니다.

3-1. 시크릿 모드 (Incognito Mode)의 장점과 원리

모든 흔적 완전 차단:
- 시크릿 모드에서는 방문 기록, 검색 기록, 쿠키, 그리고 로컬/세션 스토리지 데이터가 창을 닫는 순간 브라우저 메모리에서 깨끗하게 소멸됩니다.
자동 로그인 방지:
- 기존 일반 모드의 쿠키나 저장된 세션이 적용되지 않으며, 아이디/비밀번호 자동 완성이 비활성화되어 다음 사용자가 내 계정에 접근하는 위험을 원천 차단합니다.

3-2. 공용 PC 사용 시 개발자가 꼭 지켜야 할 3대 보안 습관

로그인 계정 직접 로그아웃:
구글 드라이브, 깃허브 등 민감한 서비스는 단순히 탭이나 창만 닫지 말고, 반드시 [로그아웃] 버튼을 직접 눌러 서버 세션을 무효화해야 합니다.
브라우저 비밀번호 저장 팝업 주의:
"비밀번호를 저장하시겠습니까?" 팝업이 뜰 때 실수로 '저장'을 누르면 공용 PC의 브라우저 프로필에 평문으로 남을 수 있으므로 반드시 '저장 안 함'을 선택합니다.
개발자 도구(F12) 테스트 후 완전 종료:
테스트나 학습 목적으로 공용 PC의 F12 Application 탭에서 스토리지를 조작했다면, 작업 직후 브라우저 창 전체를 완전히 닫아 임시 데이터와 세션을 깔끔히 초기화해야 합니다.

4. Fetch API와 비동기(Asynchronous) 통신의 본질

4-1. Fetch API란 무엇인가?

브라우저가 자바스크립트에게 제공하는 최신 표준 서버 통신용 Web API입니다.
웹 페이지가 화면 전체를 새로고침하지 않고도 백엔드 서버에 HTTP 요청(Request)을 보내고 응답(Response)을 수신할 수 있게 해줍니다.
내부적으로 비동기(Asynchronous) 방식으로 작동합니다.

4-2. 비동기(Asynchronous)의 핵심: 왜 let response = fetch()는 안 될까?

// ❌ 초보자들이 흔히 생각하는 잘못된 동기식 코드 발상
let response = fetch("https://api.example.com/posts");
console.log(response); // 서버 데이터가 아니라 Promise 객체가 출력됨!

왜 바로 변수에 담을 수 없을까?

서버 통신은 물리적으로 시간이 걸리는 작업:
인터넷 네트워크를 타고 저 멀리 있는 서버까지 요청이 갔다가, 서버가 DB를 조회하고 데이터를 돌려주는 데는 수백 밀리초에서 수 초의 시간이 걸립니다.
자바스크립트의 싱글 스레드(Single Thread) 특성:
자바스크립트는 한 번에 한 줄씩 코드를 실행합니다. 만약 fetch()가 완료될 때까지 그 자리에서 멈춰서 기다린다면(블로킹 / 동기 방식), 서버 응답이 올 때까지 웹페이지의 모든 화면 렌더링, 마우스 클릭, 스크롤이 **꽁꽁 얼어붙는 현상(렉/프리즈)**이 발생합니다.
비동기 처리의 철학:
자바스크립트는 *"서버에 요청을 일단 던져놓고, 기다리는 동안 아래에 있는 다른 코드와 UI 상호작용을 계속하고 있을게! 서버 응답이 도착하면 그때 등록해 둔 .then() 콜백을 깨워서 처리해 줘!"*라는 방식으로 동작합니다.

4-3. .then() 체이닝의 진실: "순서대로 실행되는데 왜 100% 비동기인가?"

Q. .then() 체이닝 코드를 보면 1번이 끝나야 2번이 실행되는 순서 구조인데, 이건 동기 아닌가요?
A. 결론부터 말하면 코드 외형만 순서대로 적혀있을 뿐, 실제 내부 메커니즘은 100% 비동기(Asynchronous)입니다!

외형 (코드 모양새):
개발자의 가독성과 로직 흐름을 위해 .then()으로 순서대로 체이닝(Chaining)하여 작성하므로 마치 동기처럼 읽힙니다.
실제 내부 동작:
fetch()를 실행하자마자 자바스크립트는 자리를 비켜주고 다른 일을 하다가, 서버 응답이 도착하는 그 특정 타이밍에 맞춰서만 큐에 들어가 차례대로 실행되므로 명백한 **비동기 흐름 제어(Asynchronous Control Flow)**입니다.

4-4. 만약 통신이 '동기(Synchronous)'였다면 벌어지는 끔찍한 일

만약 자바스크립트 통신이 동기 방식이었다면:
- 서버 응답에 3초가 걸릴 경우, 그 3초 동안 웹 브라우저 전체가 멈춥니다.
- 사용자가 버튼을 클릭해도 눌리지 않고, 스크롤도 안 되며, 브라우저는 "페이지가 응답하지 않습니다" 경고창을 띄우게 됩니다.
비동기 통신 덕분에 데이터를 백그라운드에서 가져오는 동안에도 사용자는 로딩 스피너를 보거나 다른 페이지 요소를 자유롭게 조작할 수 있습니다.

5. Fetch API 기본 사용법 (GET 요청 & DOM 렌더링)

5-1. GET 요청 4단계 라이프사이클

fetch("https://jsonplaceholder.typicode.com/posts")
  // 1단계: 서버에 HTTP GET 요청을 보내고 응답 객체(response) 수신
  .then(response => {
    // 2단계: 응답 객체에서 본문 데이터만 JSON 형태로 추출(파싱)
    return response.json(); 
  })
  // 3단계: JSON 변환이 완료된 순수 자바스크립트 데이터(data) 수령
  .then(data => {
    // 4단계: 받아온 실제 데이터를 콘솔에 출력하거나 화면(DOM)에 렌더링!
    console.log(data);
  });

5-2. [실습 3] 버튼 클릭 시 게시글 5개 조회하여 리스트 렌더링

과제: "불러오기" 버튼을 누르면 JSONPlaceholder API에서 게시글 데이터를 받아와, 상위 5개의 title을 <ul> 목록 안에 <li> 태그로 동적 출력하세요.

HTML

<button id="load">불러오기</button>
<ul id="list"></ul>

JavaScript

const button = document.querySelector("#load");
const list = document.querySelector("#list");

button.addEventListener("click", function () {
  fetch("https://jsonplaceholder.typicode.com/posts")
    .then(res => res.json())
    .then(posts => {
      // 1. 기존 목록 초기화
      list.innerHTML = "";

      // 2. 전체 데이터 중 0~4번째(5개)만 잘라서 반복문 순회
      for (const post of posts.slice(0, 5)) {
        const li = document.createElement("li"); // <li></li> 생성
        li.textContent = post.title;             // <li>게시글 제목</li>
        list.appendChild(li);                    // <ul> 안에 추가
      }
    });
});

6. 데이터 렌더링 최적화 & 얼리 리턴 (Early Return)

6-1. 중복 출력 문제 발생과 4가지 해결 방법

문제 발생:
위 코드에서 '불러오기' 버튼을 계속 누르면, posts.slice(0, 5)로 똑같은 0~4번 데이터가 리스트 밑으로 끝없이 중복 추가되는 문제가 발생합니다.

4가지 해결 전략 비교:

해결 방법 코드 예시 장점 및 평가

1. 이전 출력 내용 초기화	list.innerHTML = "";	구현은 단순하나, 버튼을 누를 때마다 매번 불필요한 서버 통신을 반복함 (낭비 발생)
2. Early Return (조기 반환)	if (list.innerHTML !== "") return;	가장 우수한 방법! 이미 데이터가 있으면 함수를 즉시 종료하여 네트워크 요청 자체를 차단
3. 버튼 비활성화 (Disable)	button.disabled = true;	클릭 1회 완료 후 버튼을 비활성화하여 추가 클릭을 물리적으로 방지
4. 페이지네이션 (Sliding Window)	start += 5; end += 5; posts.slice(start, end)	누를 때마다 중복이 아닌 다음 5개(5~~9, 10~~14...)를 순차적으로 이어서 보여줌

6-2. 왜 1번(innerHTML="")보다 2번(Early Return)이 훨씬 뛰어난가?

button.addEventListener("click", () => {
  //   [2번 방법: 얼리 리턴 적용]
  // 리스트 안에 이미 글이 채워져 있다면? ➔ 즉시 함수 종료!
  if (list.innerHTML !== "") {
    return;
  }

  // 데이터가 비어있을 때만 단 1번 서버 통신 실행!
  fetch("https://jsonplaceholder.typicode.com/posts")
    .then(response => response.json())
    .then(posts => {
      for (const post of posts.slice(0, 5)) {
        const li = document.createElement("li");
        li.textContent = post.title;
        list.appendChild(li);
      }
    });
});

Tip

얼리 리턴(Early Return)이 압도적으로 좋은 이유:
1번 방식(list.innerHTML = "")은 화면상으로는 깔끔해 보이지만, 버튼을 누를 때마다 100개의 데이터를 서버에서 새로 다운로드하는 극심한 네트워크 대역폭 낭비와 서버 부하가 발생합니다.
반면 2번 방식은 조건 검사 후 즉시 return하여 불필요한 fetch 자체를 원천 차단하므로 성능, 비용, 안정성 모든 면에서 탁월합니다.

6-3. 한 걸음 더: 클라이언트 메모리 캐싱 (Client Caching) 고도화

기존 방식의 비효율: 버튼을 누를 때마다 매번 서버에 새로 요청. (100개를 다 받아와서 5개만 쓰고 버리는 낭비)
고도화된 새로운 방식 (Client Caching):
최초 1회만 서버에서 데이터를 통째로 받아와 자바스크립트 변수(브라우저 메모리)에 저장(Cache)해 두고, 이후 버튼을 누를 때는 서버 통신 없이 메모리에 저장된 배열에서 슬라이스(6~10, 11~15)하여 렌더링합니다!

let cachedPosts = null; // 서버에서 받아온 데이터를 보관할 캐시 변수
let startIndex = 0;
const PAGE_SIZE = 5;

button.addEventListener("click", async () => {
  // 1. 최초 1회만 서버에서 fetch로 가져와 캐시에 저장
  if (!cachedPosts) {
    const res = await fetch("https://jsonplaceholder.typicode.com/posts");
    cachedPosts = await res.json();
  }

  // 2. 이미 캐시된 데이터가 있으므로 서버 요청 없이 메모리에서 잘라서 출력!
  const currentSlice = cachedPosts.slice(startIndex, startIndex + PAGE_SIZE);
  
  currentSlice.forEach(post => {
    const li = document.createElement("li");
    li.textContent = `${post.id}. ${post.title}`;
    list.appendChild(li);
  });

  startIndex += PAGE_SIZE; // 다음 5개를 위해 인덱스 전진 (Sliding Window)
});

7. Fetch API: POST 요청으로 서버에 데이터 전송

7-1. POST 요청의 3대 필수 요소 (method, headers, body)

GET 요청과 달리, 서버에 새로운 리소스를 생성하거나 데이터를 보낼 때는 두 번째 인자로 설정 객체를 전달합니다.

method: "POST" 지정
headers: 전송하는 데이터 포맷이 JSON임을 서버에 알림 ({ "Content-Type": "application/json" })
body: 자바스크립트 객체를 전송 가능한 JSON 문자열로 직렬화 (JSON.stringify({ ... }))

7-2. [실습 4] 이메일 전송 및 JSON 응답 가독성 출력 (null, 2)

과제: 이메일 입력창의 값을 서버에 POST 방식으로 전송하고, 서버가 반환한 응답 데이터를 <pre> 태그 안에 들여쓰기가 적용된 JSON 형태로 출력하세요.

HTML

<input type="email" id="email" placeholder="이메일 입력">
<button id="send">전송</button>
<pre id="result"></pre>

JavaScript

const input = document.querySelector("#email");
const button = document.querySelector("#send");
const result = document.querySelector("#result");

button.addEventListener("click", function () {
  fetch("https://jsonplaceholder.typicode.com/posts", {
    method: "POST",
    headers: {
      "Content-Type": "application/json" // 내가 보내는 데이터는 JSON입니다!
    },
    body: JSON.stringify({
      email: input.value // 객체를 JSON 문자열로 변환하여 전송
    })
  })
    .then(res => res.json())
    .then(data => {
      // JSON.stringify의 3번째 인자 2는 들여쓰기 공백 수 (가독성 향상)
      result.textContent = JSON.stringify(data, null, 2);
    });
});

8. 종합 최종 실습: To-do 앱 & 모던 프레임워크 상태 관리

8-1. Web API 삼총사(DOM + Storage + Fetch)의 융합

현대 웹 애플리케이션의 핵심인 To-do 앱은 지금까지 배운 Web API들이 유기적으로 결합되어 동작합니다.

8-2. 바닐라 JS의 한계와 프레임워크(React, Next.js, Vue.js)로의 확장

순수 바닐라 자바스크립트의 한계:
- 데이터가 변경될 때마다 개발자가 직접 document.querySelector로 요소를 찾고, createElement와 appendChild를 일일이 명령형(Imperative)으로 호출해야 합니다.
- 규모가 커지면 "어떤 코드가 화면의 어떤 부분을 바꾸고 있는지" 추적하기가 매우 어려워집니다 (스파게티 코드).
모던 프레임워크(React, Vue, Next.js)의 상태 관리(State Management):
- "데이터(상태)가 바뀌면 화면은 알아서 자동으로 다시 그려져라!" 하는 선언형(Declarative) UI 패러다임 도입.
- 복잡한 DOM 수동 조작에서 벗어나 비즈니스 로직과 데이터 상태 관리에만 집중할 수 있게 됩니다.

9. 실전 핵심 요약 치트시트

┌────────────────────────────────────────────────────────────────────────┐
│              Web API 심화 (Timer & Storage & Fetch) 치트시트           │
├──────────────────────────────┬─────────────────────────────────────────┤
│ API / 문법                   │ 핵심 요약 및 사용 공식                  │
├──────────────────────────────┼─────────────────────────────────────────┤
│ setInterval(fn, ms)          │ ms 간격으로 fn 함수 무한 반복 실행       │
├──────────────────────────────┼─────────────────────────────────────────┤
│ clearInterval(timerId)       │ 실행 중인 setInterval 반복 즉시 중단    │
├──────────────────────────────┼─────────────────────────────────────────┤
│ if (timerId !== null) return;│ 타이머 중복 실행 방지 가드 클로즈       │
├──────────────────────────────┼─────────────────────────────────────────┤
│ localStorage                 │ 브라우저 닫아도 영구 유지 (동일 도메인) │
├──────────────────────────────┼─────────────────────────────────────────┤
│ sessionStorage               │ 현재 탭 닫으면 즉시 삭제 (탭 간 격리)   │
├──────────────────────────────┼─────────────────────────────────────────┤
│ Storage.setItem("k", "v")    │ Key - Value 데이터 저장 (문자열만 가능) │
├──────────────────────────────┼─────────────────────────────────────────┤
│ JSON.stringify(obj)          │ JS 객체를 스토리지 저장용 JSON 문자열로 │
├──────────────────────────────┼─────────────────────────────────────────┤
│ JSON.parse(str)              │ 스토리지의 JSON 문자열을 JS 객체로 복원 │
├──────────────────────────────┼─────────────────────────────────────────┤
│ fetch(url)                   │ 서버와 비동기 HTTP 통신 수행            │
├──────────────────────────────┼─────────────────────────────────────────┤
│ 왜 비동기인가?               │ 서버 응답 대기 중 화면 멈춤(렉) 방지    │
├──────────────────────────────┼─────────────────────────────────────────┤
│ .then(res => res.json())     │ 서버 응답 바디를 JSON 파싱하여 전달     │
├──────────────────────────────┼─────────────────────────────────────────┤
│ if (list.innerHTML !== "")   │ 렌더링 중복 방지 & 불필요한 fetch 차단  │
│ return;                      │ (얼리 리턴 최적화)                      │
├──────────────────────────────┼─────────────────────────────────────────┤
│ Client Caching               │ 최초 1회만 fetch 후 메모리에 저장       │
│                              │ 이후 slice()로 서버 요청 횟수 절약      │
├──────────────────────────────┼─────────────────────────────────────────┤
│ fetch POST 필수 3속성        │ method: 'POST',                         │
│                              │ headers: {'Content-Type': 'app/json'},  │
│                              │ body: JSON.stringify({...})             │
├──────────────────────────────┼─────────────────────────────────────────┤
│ JSON.stringify(d, null, 2)   │ 2칸 들여쓰기로 보기 좋게 JSON 출력      │
└──────────────────────────────┴─────────────────────────────────────────┘

HTML/CSS & Javascript 7일차

write31991 — Mon, 19 Oct 2026 16:49:01 +0900

JavaScript DOM 조작, 이벤트 & Web API 완벽 정리 노트

브라우저 화면을 동적으로 제어하는 **함수의 반환값 규칙(return 생략 시 undefined)**부터 DOM의 본질과 트리 구조, HTML vs JS의 명확한 역할 분담, DOM 선택 & 스타일·속성 조작, 이벤트 리스너 & 화살표 함수, 얼리 리턴(Early-Return) 패턴, 그리고 브라우저가 제공하는 **Web API 5대 분류와 Timer API(카운트다운 실습)**까지 총정리한 실전 가이드

1. 함수의 반환 규칙: return을 생략하면 무슨 일이 일어날까?

1-1. 모든 함수는 "반드시" 값을 반환한다

자바스크립트의 함수는 호출되면 **어떤 상황에서든 반드시 결과값 하나를 반환(Return)**하도록 언어 차원에서 설계되어 있습니다.
개발자가 코드 내에서 return 키워드를 명시하지 않더라도, 자바스크립트 엔진은 내부적으로 **return undefined;**를 자동으로 붙여서 실행을 마칩니다.

1-2. return 생략과 undefined (JavaScript vs Python 비교)

// 'Hello' 를 출력하는 함수
function sayHello() {
  console.log("hello");
  // ⚠️ return을 명시하지 않았지만, 내부적으로 아래 코드가 숨겨져 있음!
  // return undefined;
}

// sayHello()의 반환값을 변수 hello에 할당
let hello = sayHello(); // 1) 콘솔에 "hello"가 출력됨

// hello 변수에 무엇이 담겼는지 확인
console.log(hello);     // 2) undefined 가 출력됨!

언어별 return 생략 시 반환값 비교

언어 return 생략 시 자동 반환값 설명

JavaScript	undefined	"값이 아직 정의되지 않음"을 나타내는 JS 기본 원시 타입
Python	None	파이썬의 NoneType 객체를 기본 반환 (def foo(): pass 호출 시 None 리턴)

Important

콘솔 출력(console.log)과 반환(return)의 차이:

console.log()는 단순히 개발자 모니터(화면)에 글자를 띄워주는 **"출력 행위"**일 뿐입니다.
return은 함수를 호출한 자리에 데이터를 쥐어주는 **"값의 전달"**입니다.
return이 없는 함수는 외부 변수에 담았을 때 언제나 undefined가 할당됩니다.

2. JavaScript는 어떻게 화면을 바꾸는가? (DOM의 탄생)

2-1. HTML을 직접 수정하는 것이 아니다!

많은 입문자들이 *"자바스크립트가 .html 텍스트 파일을 직접 열어서 코드를 수정하나?"*라고 오해합니다.
하지만 자바스크립트는 하드디스크나 서버에 있는 HTML 파일을 직접 수정하는 것이 아닙니다.

Unable to render rich display
Parse error on line 3:
...JavaScript"] -->|조작 (Modify)| B B --
-----------------------^
Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND', 'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'PS'

For more information, see https://docs.github.com/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams

graph LR
    A["  index.html<br/>(정적 파일)"] -->|브라우저가 읽고 파싱| B["  DOM (객체 트리)<br/>(메모리 상의 객체 구조)"]
    C["⚡ JavaScript"] -->|조작 (Modify)| B
    B -->|화면 렌더링| D["  사용자 모니터 화면"]

브라우저가 원본 HTML 파일을 읽어서 컴퓨터 메모리 안에 DOM(Document Object Model) 객체 트리를 생성합니다.
JavaScript는 이 메모리 상에 존재하는 DOM 객체를 조작합니다.
브라우저는 변경된 DOM 객체를 감지하고 화면을 즉시 다시 그려냅니다(Re-rendering).

2-2. DOM(Document Object Model)의 정의와 트리 구조

DOM이란?: 브라우저가 HTML 문서를 해석하여, JavaScript와 같은 프로그래밍 언어가 제어하고 다룰 수 있도록 만든 객체(Object) 구조입니다.
웹 페이지 = 거대한 트리(Tree) 구조:
- 가장 꼭대기(뿌리): document
- 부모 노드: <html>
- 자식 노드: <head>, <body>
- 잎사귀(Leaf) 노드: <h1>, <p>, <button>, 텍스트, 속성 등

2-3. 웹 페이지의 '상태'와 새로고침(Reload)의 의미

**DOM은 '웹 페이지의 현재 상태'**입니다.
JavaScript로 글자 색을 빨간색으로 바꾸고 글씨를 바꿨더라도, 그것은 오직 브라우저 메모리 안의 DOM에만 반영된 상태입니다.
사용자가 웹 브라우저에서 **새로고침(F5 / reload)**을 누르면:
1. 메모리에 있던 기존 DOM이 완전히 소멸합니다.
2. 원본 index.html 파일을 서버나 로컬에서 다시 읽어옵니다.
3. 새로운 DOM을 처음부터 다시 생성하므로 모든 화면 조작 상태가 초기화됩니다.

3. 역할 분담의 대원칙: HTML vs JavaScript

"어떤 코드를 HTML에 넣고, 어떤 코드를 JavaScript에 넣어야 할까?"

3-1. HTML: 정적 & 공통적인 뼈대

역할: 웹 페이지의 뼈대와 공통적인 구조를 담당.
특징:
- 사용자가 누구든, 버튼을 어떻게 누르든 변하지 않고 항상 그 자리에 그대로 있는 공통적이고 정적인 부분은 HTML 파일에 작성합니다.
- 예시: 헤더, 사이드바 틀, 기본 입력 양식 태그(<input>, <button>), 푸터 레이아웃.

3-2. ⚡ JavaScript: 동적 & 변경되는 상태·로직

역할: 사용자의 행동(클릭, 키 입력, 마우스 이동 등)에 따라 변화를 가하는 동적 제어와 비즈니스 로직을 담당.
특징:
- 사용자의 인터랙션에 따라 실시간으로 바뀌거나(상태 변화), 개발자가 조건문/반복문/연산 로직으로 제어해야 하는 부분은 JavaScript(DOM 조작 및 이벤트)에 작성합니다.
- 예시: 로그인 버튼 클릭 시 글자 색상 변경, 비밀번호 입력값 실시간 자릿수 검사, 5초 카운트다운 타이머 등.

3-3. 역할 분담 한 줄 요약 법칙

Note

골든 룰 (Golden Rule):
"화면의 기본 틀과 공통 속성은 HTML에! 사용자의 행동이나 상황에 따라 동적으로 변하는 상태와 로직은 JS(DOM)에!"
이 기준을 잡으면 컴포넌트나 웹 코드를 작성할 때 역할이 명쾌해집니다.

4. DOM 요소 선택하기 (Selector Methods)

JavaScript가 화면 요소를 바꾸려면, 가장 먼저 **"어떤 요소를 바꿀 것인가?"**를 지정(선택)해야 합니다.

4-1. 3대 핵심 선택자 메서드 비교

메서드명 인자 형식 반환값 매칭 대상 x 주요 특징 및 권장 용도

document.getElementById()	"아이디명" (ex: "text")	단일 Element	null	고유 ID로 1개 요소를 빠르게 찾을 때 사용
document.querySelector()	CSS 선택자 (ex: "#text", ".item", "p")	단일 Element	null	실무 최다 사용! 가장 첫 번째로 일치하는 요소 1개 반환
document.querySelectorAll()	CSS 선택자 (ex: ".item", "ul > li")	NodeList (유사 배열)	빈 NodeList ([])	조건에 맞는 모든 요소를 그룹으로 선택 (forEach 순회 가능)

4-2. querySelector vs querySelectorAll 실전 문법

<!-- HTML 구조 예시 -->
<h1 id="text">Hello</h1>
<div class="item">사과</div>
<div class="item">바나나</div>
<div class="item">포도</div>

// 1. querySelector: 단 1개의 요소만 선택
const singleHeading = document.querySelector("#text");  // id가 text인 요소
const firstItem     = document.querySelector(".item");  // 클래스가 item인 것 중 '첫 번째' (사과)

console.log(singleHeading.textContent); // "Hello"
console.log(firstItem.textContent);     // "사과"

// 2. querySelectorAll: 일치하는 모든 요소를 NodeList로 선택
const allItems = document.querySelectorAll(".item");

console.log(allItems.length); // 3 (사과, 바나나, 포도)

// NodeList는 forEach 메서드로 간편하게 순회 가능!
allItems.forEach((el, index) => {
  console.log(`${index + 1}번째 과일:`, el.textContent);
});
// 1번째 과일: 사과
// 2번째 과일: 바나나
// 3번째 과일: 포도

5. DOM 조작 (내용, 스타일, 속성, 동적 요소 생성)

요소를 선택했다면, 그 요소의 텍스트, HTML 구조, CSS 디자인 스타일, 속성을 마음대로 변경할 수 있습니다.

5-1. 텍스트와 HTML 내용 변경 (textContent vs innerHTML)

const el = document.getElementById("text");

// 1. textContent: 순수한 텍스트만 읽거나 변경 (보안상 안전, XSS 방지)
el.textContent = "Hello, JavaScript"; 
console.log(el.textContent.trim()); // 공백 제거 후 텍스트 출력

// 2. innerHTML: HTML 태그까지 포함하여 파싱하고 화면을 변경
// 기존 내부 요소를 비우거나 새 태그를 통째로 주입할 때 사용
el.innerHTML = "<span style='color: blue;'>Hello, Blue JS!</span>";

// 요소 내부를 깨끗이 비울 때도 자주 활용:
// el.innerHTML = "";

5-2. 인라인 스타일 변경 (style.color, style.fontSize 등)

선택한 요소의 .style 객체 속성에 접근하여 CSS 스타일을 직접 변경합니다.
CSS 속성명에 하이픈(-)이 있는 속성은 JavaScript에서 **카멜 표기법(camelCase)**으로 작성합니다.
- font-size ➔ fontSize
- background-color ➔ backgroundColor
- border-radius ➔ borderRadius

const el = document.querySelector("#text");

el.textContent = "Hello, DOM";
el.style.color = "red";             // 글자색 변경
el.style.fontSize = "20px";          // 폰트 크기 변경
el.style.backgroundColor = "yellow"; // 배경색 변경
el.style.border = "1px solid red";   // 테두리 추가

5-3. 태그 속성(Attribute) 변경 (link.href, img.src 등)

HTML 태그가 가진 고유 속성(href, src, placeholder, disabled, type 등)을 직접 변경할 수 있습니다.

// <a> 태그의 링크 목적지 변경
const link = document.querySelector("a");
link.href = "https://google.com";
link.target = "_blank"; // 새 탭에서 열기

// <input> 태그의 속성 변경
const input = document.querySelector("#name-input");
input.placeholder = "새로운 이름을 입력해주세요";

5-4. 동적 요소 생성과 문서 추가 (createElement & appendChild)

새로운 태그 요소를 자바스크립트로 메모리상에 생성하고, 원하는 부모 태그 아래에 자식으로 이어 붙입니다.

// 1. 메모리 상에 새로운 <p> 태그 노드 생성
const p = document.createElement("p"); // <p></p>

// 2. 생성한 요소에 내용 채우기
p.textContent = "새롭게 생성된 문단입니다."; // <p>새롭게 생성된 문단입니다.</p>

// 3. 실제 DOM 트리(화면)에 붙이기
// document.body 또는 특정 부모 컨테이너(result 등)에 appendChild 실행
const resultBox = document.querySelector("#result");
resultBox.appendChild(p);

6. 이벤트(Event)와 이벤트 리스너(Event Listener)

6-1. 이벤트(Event)란? (사용자 행동 vs 브라우저 동작)

이벤트(Event): 웹 페이지 안에서 일어나는 모든 상태 변화나 사건.
주로 사용자의 상호작용 행동에 의해 발생하지만, 브라우저 자체의 라이프사이클 동작도 포함됩니다.

6-2. 이벤트 리스너를 사용하는 이유와 동작 메커니즘

이벤트 리스너(Event Listener): 특정 요소에서 지정한 이벤트가 언제 발생하는지 귀 기울여 감시하다가, 해당 사건이 발생하면 지정해 둔 함수(콜백 함수)를 자동으로 호출해 주는 시스템입니다.
사용하는 3대 이유:
1. 사용자의 행동을 감지하여 실시간 상호작용(Interaction) 구현.
2. 죽어있는 정적인 HTML 문서를 살아 숨 쉬는 동적 웹 애플리케이션으로 변환.
3. 화면(UI)과 비즈니스 로직을 상황에 맞춰 동적으로 제어.

// 기본 문법: 타겟요소.addEventListener("이벤트종류", 실행할함수);
const btn = document.querySelector("button");

btn.addEventListener("click", function () {
  console.log("버튼이 클릭됨!");
});

6-3. 초보자가 가장 많이 하는 치명적 실수: func vs func()

function buttonAlert() {
  alert("버튼이 클릭됨");
}

const btn = document.querySelector("button");

// ✅ 올바른 코드: 함수 '이름(참조)'만 전달!
btn.addEventListener("click", buttonAlert);
// 설명: "클릭이라는 사건이 발생했을 때, 그때 buttonAlert 함수를 실행해줘!"

// ❌ 치명적인 실수 코드: 함수 뒤에 괄호 ()를 붙여 호출해버림!
btn.addEventListener("click", buttonAlert());

Warning

왜 buttonAlert()로 작성하면 안 되는가?
buttonAlert()처럼 괄호를 붙이면, 이벤트 리스너가 등록되는 시점(코드 로딩 즉시)에 함수가 바로 1회 실행되어 버립니다!
게다가 buttonAlert 함수는 return 값이 없으므로 반환값인 undefined가 addEventListener의 두 번째 인자로 전달됩니다.
즉, 브라우저는 내부적으로 btn.addEventListener("click", undefined)로 인식하여, 실제 버튼을 클릭했을 때 아무런 동작도 하지 않게 됩니다.

6-4. 이벤트 핸들러 작성법의 진화 (기명함수 ➔ 익명함수 ➔ 화살표 함수)

const btn = document.querySelector("button");

// 1단계: 외부 기명 함수 전달 (재사용할 때 적합)
function handleClick() {
  alert("클릭됨");
}
btn.addEventListener("click", handleClick);

// 2단계: 단독 사용 시 안에서 익명 함수 정의
btn.addEventListener("click", function () {
  alert("클릭됨");
});

// 3단계: 화살표 함수 (Arrow Function)로 전환
btn.addEventListener("click", () => {
  alert("클릭됨");
});

// 4단계: 실행할 코드가 한 줄이면 중괄호 { } 생략 (최종 모던 스타일)
btn.addEventListener("click", () => alert("클릭됨"));

7. 모던 자바스크립트: 화살표 함수 (Arrow Function)

7-1. 화살표 함수의 탄생 배경과 기본 문법

ES6(2015)에서 도입된 문법으로, 길고 번거로운 function 키워드 대신 => 기호를 사용하여 함수를 더 짧고 간결하게 정의할 수 있습니다.
특히 이벤트 리스너나 배열 순회 메서드(forEach, map, filter)의 콜백 함수로 압도적으로 많이 사용됩니다.

7-2. 화살표 함수 문법 축약 3단계

// [기존 전통적 함수 선언]
function add(a, b) {
  return a + b;
}

// 1단계: function 대신 화살표(=>) 기본 표기
const add1 = (a, b) => {
  return a + b;
};

// 2단계: 본문이 '단일 return 문'인 경우 중괄호 { }와 return 키워드 동시 생략!
const add2 = (a, b) => a + b;

// 3단계: 매개변수가 1개뿐인 경우 소괄호 ( )도 생략 가능!
const double = x => x * 2;

이벤트 리스너에서의 화살표 함수 활용 비교:

// 기본 익명 함수
btn.addEventListener("click", function () {
  console.log("클릭됨");
});

// 화살표 함수
btn.addEventListener("click", () => {
  console.log("클릭됨");
});

// 한 줄 축약 화살표 함수
btn.addEventListener("click", () => console.log("클릭됨"));

8. 얼리 리턴 (Early-Return, 조기 반환) 디자인 패턴

8-1. 얼리 리턴의 정의와 머신러닝 데이터 전처리 비유

정의: 함수나 이벤트 핸들러가 본격적인 핵심 로직을 실행하기 전, 가장 앞단에서 데이터 유효성 검사(Data Validation)를 수행하여 조건에 맞지 않는 잘못된 입력값을 사전에 차단하고 함수를 즉시 종료(return;)하는 패턴입니다.

Note

머신러닝(AI) 관점에서의 비유:
머신러닝 모델에 학습 데이터를 주입하기 전, **데이터 전처리(Data Preprocessing)**를 거쳐 결측치(Null)나 이상치(Outlier)를 먼저 걸러내는 것과 완벽히 동일합니다.
쓰레기 데이터(비정상 값)가 핵심 모델에 들어가서 계산 에러나 오작동을 일으키는 것을 입구에서 원천 봉쇄하는 것입니다.

8-2. 왜 얼리 리턴을 써야 하는가? (안정성 & Deep Nesting 탈출)

안정성 확보 (Bug Prevention):
- 빈 문자열(""), null, 음수, 비정상 포맷 값이 메인 로직으로 흘러 들어가 화면이 깨지거나 런타임 오류가 터지는 현상을 사전에 방지합니다.
가독성 향상 (Deep Nesting 방지):
- 조건마다 안쪽으로 깊숙이 들여쓰기(if { if { if { ... } } })하는 '피라미드 지옥(Pyramid of Doom)' 대신, 예외 상황을 초반에 잘라내어 코드의 깊이(Indent Level)를 1단계로 평탄하게 유지합니다.

8-3. 실전 Before vs After 코드 비교

❌ Before: if-else 중첩 방식 (코드가 오른쪽으로 계속 밀려남)

function handleSubmit() {
  if (input.value !== "") {
    if (input.value.length >= 4) {
      // 핵심 로직 실행...
      console.log("저장 성공!");
    } else {
      alert("4자리 이상 입력해주세요.");
    }
  } else {
    alert("값을 입력해주세요.");
  }
}

✅ After: 얼리 리턴(Early-Return) 패턴 (평탄하고 읽기 쉬움)

function handleSubmit() {
  // 1. 빈 값 예외 처리 ➔ 즉시 종료
  if (input.value.trim() === "") {
    alert("이름을 입력하세요.");
    return; // 함수 강제 종료! 아래 코드는 거들떠보지도 않음
  }

  // 2. 글자수 예외 처리 ➔ 즉시 종료
  if (input.value.length < 4) {
    alert("4자리 이상 입력하세요.");
    return;
  }

  // 3. 모든 검문을 통과한 안전한 데이터만 핵심 로직 수행!
  console.log("저장 성공:", input.value);
}

9. Web API란 무엇인가?

9-1. JavaScript 언어와 Web API의 차이점

순수 JavaScript 언어 스펙(ECMAScript): 변수, 조건문, 함수, 객체, 배열 등 순수한 문법과 계산 엔진 기능만 가지고 있습니다.
Web API: **웹 브라우저 환경이 자바스크립트 엔진에게 선물로 제공하는 도구 상자(기능 모음)**입니다.
- 브라우저가 제공하므로 웹 페이지가 브라우저 기능(화면 그리기, 타이머, 로컬 저장소, 서버 네트워크 통신 등)과 상호작용할 수 있습니다.

9-2. 브라우저 제공 Web API 5대 핵심 분류

API 분류 대표 메서드 / 객체 주요 역할 및 사용 목적

1. DOM API	document.querySelector, element.textContent, createElement	HTML 요소를 선택하고, 내용을 바꾸고, 새 요소를 화면에 조작
2. Event API	element.addEventListener	클릭, 입력, 키보드, 마우스 등 사용자의 모든 인터랙션 감지
3. Timer API	setTimeout, setInterval, clearTimeout, clearInterval	시간 지연 후 실행, 주기적 반복 실행 등 시간 제어
4. Storage API	localStorage, sessionStorage	브라우저에 데이터를 반영구적 또는 세션 동안 보관
5. Fetch API	fetch("https://api.example.com/data")	새로고침 없이 백엔드 서버와 비동기로 데이터(JSON)를 송수신

10. Timer API 완벽 이해 (setTimeout, setInterval, timerId)

10-1. 1회성 타이머: setTimeout

역할: 지정한 시간(밀리초, 1000ms = 1초)이 지난 뒤에, 지정한 콜백 함수를 딱 한 번만 실행합니다.

// 3초(3000ms) 뒤에 콘솔 출력
setTimeout(function () {
  console.log("3초 후 실행");
}, 3000);

// 화살표 함수 한 줄 축약형
setTimeout(() => console.log("3초 후 실행"), 3000);

11. 강의 슬라이드 실전 실습 과제 풀이 모음

강의 슬라이드에 등장한 모든 실습 과제의 문제, HTML 뼈대, JavaScript 완성 코드, 핵심 해설을 완벽하게 정리했습니다.

실습 1: 버튼 클릭 이벤트 콘솔 출력

과제: 버튼을 클릭하면 브라우저 콘솔에 "버튼 클릭됨"을 출력하세요.

HTML

<button id="btn">클릭</button>

JavaScript

const btn = document.querySelector("#btn");

btn.addEventListener("click", function () {
  console.log("버튼 클릭됨");
});

//   모던 화살표 함수 버전:
// btn.addEventListener("click", () => console.log("버튼 클릭됨"));

실습 2: 버튼 클릭 시 텍스트 및 색상 변경

과제: 버튼을 클릭하면 h1 태그의 텍스트를 "Hello JavaScript"로 바꾸고, 글자 색상은 빨간색으로 변경하세요.

HTML

<h1 class="text">Hello</h1>
<button id="change">변경</button>

JavaScript

const h1 = document.querySelector(".text");
const button = document.querySelector("#change");

button.addEventListener("click", function () {
  // 1. 텍스트 내용 변경
  h1.textContent = "Hello JavaScript";
  // 2. 인라인 글자 색상 스타일 변경
  h1.style.color = "red";
});

실습 3: 비밀번호 실시간 길이 감지 및 유효성 피드백

과제: 사용자가 비밀번호를 입력할 때마다 실시간으로 길이를 체크하여, 4자리 미만이면 빨간색으로 "4자리 이상 입력하세요.", 4자리 이상이면 파란색으로 "사용 가능한 비밀번호입니다."를 출력하세요.

HTML

<input type="password" id="pw-input" placeholder="비밀번호 입력">
<p id="result"></p>

JavaScript

const input = document.querySelector("#pw-input");
const result = document.querySelector("#result");

function validatePassword() {
  if (input.value.length < 4) {
    result.textContent = "4자리 이상 입력하세요.";
    result.style.color = "red";
  } else {
    result.textContent = "사용 가능한 비밀번호입니다.";
    result.style.color = "blue";
  }
}

// input 이벤트: 키를 누르거나 입력값이 변할 때마다 실시간 호출
input.addEventListener("input", validatePassword);

실습 4: 마우스 감지 이벤트 (호버 시 색상 전환)

과제: 박스 위에 마우스를 올리면 텍스트가 오렌지색(또는 배경이 skyblue), 마우스를 밖으로 내리면 원래대로 복구되게 만드세요.

HTML

<p id="box">마우스를 올려보세요</p>

JavaScript (버전 A: 텍스트 및 테두리 변경)

const box = document.querySelector("#box");

function highlightText() {
  box.style.color = "orange";
  box.style.border = "1px solid orange";
}

function resetText() {
  box.style.color = "black";
  box.style.border = "none";
}

box.addEventListener("mouseover", highlightText);
box.addEventListener("mouseout", resetText);

JavaScript (버전 B: 화살표 함수를 활용한 배경색 변경)

const box = document.querySelector("#box");

function changeBackgroundColor(color) {
  box.style.backgroundColor = color;
}

box.addEventListener("mouseover", () => changeBackgroundColor("skyblue"));
box.addEventListener("mouseout", () => changeBackgroundColor("orange"));

실습 5: 동적 입력값 처리 및 화면 렌더링 (DOM 추가)

과제: 사용자가 텍스트를 입력하고 확인 버튼을 누르면 환영 문구를 담은 <p> 태그를 동적으로 생성하여 결과 영역에 추가하세요. (빈 값 입력 시 얼리 리턴 처리)

HTML

<input type="text" id="name-input" placeholder="이름을 입력하세요">
<button id="submit-btn">확인</button>
<div id="result"></div>

JavaScript (얼리 리턴 & createElement 결합)

const input = document.querySelector("#name-input");
const button = document.querySelector("#submit-btn");
const result = document.querySelector("#result");

function printName() {
  // 1. [얼리 리턴] 빈 값 검증: 공백 제거 후 빈 문자열이면 즉시 차단
  if (input.value.trim() === "") {
    alert("이름을 입력하세요");
    return;
  }

  // 2. 기존 결과 영역 초기화
  result.innerHTML = "";

  // 3. 동적으로 새 <p> 태그 생성 및 내용 주입
  const welcomeText = "환영합니다, " + input.value + " 님";
  const p = document.createElement("p");
  p.textContent = welcomeText;

  // 4. 화면(DOM)에 자식 요소로 추가
  result.appendChild(p);

  // 5. 사용 편의를 위해 입력창 비우기
  input.value = "";
}

button.addEventListener("click", printName);

실습 6: Timer API 5초 카운트다운 타이머 완성

과제: "카운트다운 시작" 버튼을 누르면 5부터 1초마다 1씩 감소하고, 0이 되는 순간 카운트를 멈추고 화면에 "끝"을 출력하는 타이머를 만드세요. (중복 클릭 방지 포함)

HTML

<button id="start">카운트다운 시작</button>
<p id="result"></p>

JavaScript (중복 방지 가드 & 타이머 클리어)

const startBtn = document.querySelector("#start");
const timeEl = document.querySelector("#result");

let time = 5;
let timerId = null; // 실행 중인 타이머 번호를 보관하는 변수

startBtn.addEventListener("click", function () {
  //   1. 중복 실행 방지 가드 클로즈:
  // 이미 타이머가 실행 중(timerId !== null)이면 추가 클릭을 완벽히 무시!
  if (timerId !== null) return;

  // 초기 시작 숫자 화면에 즉시 표시
  timeEl.textContent = time;

  // 2. 1초(1000ms)마다 동작하는 인터벌 등록
  timerId = setInterval(function () {
    time--; // 1초마다 1씩 감소

    if (time === 0) {
      // 0초 도달 시 종료 처리
      timeEl.textContent = "끝";
      clearInterval(timerId); // 타이머 반복 중단!
      timerId = null;         // 상태를 초기화하여 다시 시작할 수 있게 함
      time = 5;               // 다음 실행을 위해 시간 리셋
    } else {
      // 아직 시간이 남아있으면 남은 초 표시
      timeEl.textContent = time;
    }
  }, 1000);
});

12. 실전 핵심 요약 치트시트

┌────────────────────────────────────────────────────────────────────────┐
│                      DOM & Event & Web API 치트시트                    │
├────────────────────────────────┬───────────────────────────────────────┤
│ 개념 / 메서드                  │ 핵심 기능 및 설명                     │
├────────────────────────────────┼───────────────────────────────────────┤
│ return 생략                    │ 모든 JS 함수는 return 없으면          │
│                                │ 자동으로 undefined 를 반환한다!       │
├────────────────────────────────┼───────────────────────────────────────┤
│ DOM (Document Object Model)    │ 브라우저가 HTML을 파싱해 JS가 다룰 수 │
│                                │ 있게 만든 메모리 상의 '객체 트리'     │
├────────────────────────────────┼───────────────────────────────────────┤
│ HTML vs JS 역할 분담           │ 뼈대/공통 틀 = HTML                  │
│                                │ 동적 상태/인터랙션/로직 = JS(DOM)     │
├────────────────────────────────┼───────────────────────────────────────┤
│ document.querySelector(selector)│ CSS 선택자로 일치하는 첫 번째 요소 반환│
├────────────────────────────────┼───────────────────────────────────────┤
│ document.querySelectorAll(...) │ 일치하는 모든 요소를 NodeList로 반환  │
├────────────────────────────────┼───────────────────────────────────────┤
│ el.textContent = "내용"        │ 태그 내부 순수 텍스트 안전하게 변경   │
├────────────────────────────────┼───────────────────────────────────────┤
│ el.style.camelCase = "값"      │ 인라인 CSS 스타일 실시간 조작         │
├────────────────────────────────┼───────────────────────────────────────┤
│ document.createElement("태그") │ 메모리 상에 새로운 DOM 태그 객체 생성 │
├────────────────────────────────┼───────────────────────────────────────┤
│ parent.appendChild(child)      │ 생성한 태그를 화면(부모 노드)에 부착  │
├────────────────────────────────┼───────────────────────────────────────┤
│ addEventListener("click", fn)  │ 이벤트 발생 시 실행할 콜백 함수 등록   │
│                                │ ⚠️ 절대 fn() 처럼 괄호 붙이지 말 것! │
├────────────────────────────────┼───────────────────────────────────────┤
│ () => { ... } (화살표 함수)   │ function 키워드를 줄인 모던 간결 문법 │
├────────────────────────────────┼───────────────────────────────────────┤
│ Early-Return (조기 반환)       │ 입구에서 유효성 검사 후 즉시 return;  │
│                                │ (Deep Nesting 방지 및 안정성 극대화)  │
├────────────────────────────────┼───────────────────────────────────────┤
│ Web API 5대장                  │ DOM, Event, Timer, Storage, Fetch     │
├────────────────────────────────┼───────────────────────────────────────┤
│ setTimeout(fn, ms)             │ ms(밀리초) 뒤에 fn 함수 딱 1회 실행   │
├────────────────────────────────┼───────────────────────────────────────┤
│ setInterval(fn, ms)            │ ms(밀리초) 간격으로 fn 함수 무한 반복 │
├────────────────────────────────┼───────────────────────────────────────┤
│ clearInterval(timerId)         │ 실행 중인 setInterval 반복 즉시 중단  │
├────────────────────────────────┼───────────────────────────────────────┤
│ if (timerId !== null) return;  │ 버튼 연타 시 타이머 중복 생성 방지    │
└────────────────────────────────┴───────────────────────────────────────┘

HTML/CSS & Javascript 6일차

write31991 — Fri, 16 Oct 2026 17:53:10 +0900

⚡ JavaScript 핵심 기초 문법 완벽 정리 노트

웹의 심장 **JavaScript의 정의와 4가지 실행 방법(Node.js 포함)**부터 변수(let vs const), 5대 기본 자료형과 Falsy 6대장, 엄격한 비교(===), 조건문 & 논리 연산 실전 과제, 그리고 **반복문과 배열 순회(for...of)**까지 총정리한 실전 가이드

1. JavaScript란 무엇인가?

1-1. 웹의 3대 요소 (HTML, CSS, JS의 역할)

JavaScript: 웹 브라우저에서 동적으로 살아 숨 쉬는 기능을 구현하는 인터프리터 프로그래밍 언어.
사용자의 버튼 클릭 감지, 폼 입력값 검증, 서버와의 실시간 데이터 교환, 애니메이션 등 **"동적 상호작용(Behavior)"**을 전담합니다.

1-2. JavaScript 실행 방법 4가지

방법 실행 위치 및 방식 코드 예시 주요 용도

1. 브라우저 콘솔 (Console)	크롬 개발자 도구(F12) ➔ Console 탭	console.log(1 + 2);	즉시 실행, 빠른 문법 연습, 에러 확인
2. 인라인 <script> 태그	HTML 문서 내부 <head> 또는 <body>	<script> console.log("Hello"); </script>	HTML과 한 파일에서 간단한 스크립트 실행
3. 외부 JS 파일 분리	별도의 .js 파일을 생성해 HTML에 링크	<script src="app.js"></script>	실무 표준! 코드의 모듈화와 유지보수성 극대화
4. Node.js 터미널 실행	터미널 CLI 환경에서 직접 실행	$ node app.js	브라우저 없이 백엔드/컴퓨터 환경에서 JS 단독 실행

1-3. Node.js란? & 터미널 환경의 4대 장점

Node.js: 웹 브라우저 안에서만 갇혀 살던 JavaScript를 **컴퓨터 OS(운영체제) 환경에서 독립적으로 실행할 수 있게 꺼내준 런타임 엔진(V8 기반)**입니다.
Node.js의 4대 장점:
1. 환경이 단순: HTML, CSS 파일 없이 순수 JavaScript 문법만 집중 실행 가능.
2. 실행이 초간단: 터미널에서 node app.js 한 줄로 즉시 실행.
3. 에러 추적 명확: 터미널에 스택 트레이스(Stack Trace)가 출력되어 몇 번째 줄에서 왜 에러가 났는지 원인 파악이 쉬움.
4. 초보자에게 친절: 문법적 오류를 브라우저 새로고침 없이 즉각 확인 가능.

Note

프로그램을 설치(Install)한다는 것의 본질:
웹에서 다운로드 ➔ 내 하드디스크에 저장 ➔ 실행 파일(바이너리)을 OS에 등록(이식) ➔ 터미널에서 명령어로 실행 시 컴퓨터 CPU가 코드를 한 줄씩 해석하여 동작!
설치 확인 명령어: node -v, npm -v, git --version

2. 변수 (Variable)와 메모리: let vs const

2-1. 변수의 본질과 값 저장

변수(Variable): 데이터를 컴퓨터 메모리 공간에 저장하고, 그 공간에 **이름(식별자)**을 붙여 나중에 언제든 재사용할 수 있도록 하는 상자.

let age = 20;            // age라는 이름의 상자에 숫자 20을 저장
const username = "Alex"; // username이라는 상자에 문자열 "Alex"를 고정 저장

console.log(age);        // 20 출력
console.log(username);   // Alex 출력

2-2. let vs const 핵심 비교

// 1. let: 값 변경(재할당) 가능
let count = 1;
count = 2; // ✅ 정상 작동

// 2. const: 값 변경(재할당) 절대 불가 (상수 / Constant)
const pi = 3.14;
pi = 3.15; // ❌ TypeError: Assignment to constant variable!

Tip

실무 꿀팁:
기본적으로 모든 변수는 const를 기본값으로 사용하고, 오직 반복문의 카운터(i)나 상태가 명확히 바뀌어야 하는 변수만 **let**을 사용하세요. (과거의 var는 스코프 오염 문제로 절대 사용하지 않습니다!)

2-3. 변수 선언 방식 비교 (JavaScript vs Python)

언어 값 없이 변수 선언만 하는 문법 값 생략 시 초기 상태

Python	email ❌ (에러 발생! 무조건 email = None처럼 값을 줘야 함)	초기값 필수 요구
JavaScript	let email; ⭕ (선언만 가능!)	자동으로 undefined가 할당됨

3. 기본 자료형 (Data Types) & null vs undefined

3-1. 5대 핵심 기본 자료형

// 1. number: 정수와 실수 구분 없이 모두 number 타입
let a = 10;
let b = 3.14;
console.log(typeof a); // "number"

// 2. string: 큰따옴표(" ")나 작은따옴표(' ')로 감싼 문자열
let username = "Alex";
console.log(typeof username); // "string"

// 3. boolean: 참(true) 또는 거짓(false)
let isStudent = true;
console.log(typeof isStudent); // "boolean"

// 4. null: 값이 의도적으로 비어 있음을 개발자가 명시한 상태
let selectedUser = null;
console.log(typeof selectedUser); // ⚠️ "object" (자바스크립트 초기 설계의 역사적 버그)

// 5. undefined: 변수 선언 후 아직 값이 할당되지 않아 비어있는 상태
let score;
console.log(typeof score); // "undefined"

3-2. null vs undefined의 명확한 차이

┌────────────────────────────────────────────────────────┐
│  let a = null;        ──▶ "개발자가 의도적으로 비워둠"    │
│  let b;               ──▶ "아직 값을 안 정해서 자동으로 빔" │
└────────────────────────────────────────────────────────┘

비교 항목nullundefined

의미	의도적인 빈 값 (휴지가 다 써서 빈 휴지걸이)	아직 정의되지 않음 (휴지걸이 자체가 없음)
할당 주체	개발자가 직접 코드에 대입	자바스크립트 엔진이 자동으로 부여
typeof 결과	"object"	"undefined"

let a = null;
let b; // undefined

console.log(a == b);  // true  (느슨한 비교: 둘 다 빈 값이므로 같다고 인정)
console.log(a === b); // false (엄격한 비교: 타입이 object vs undefined로 다름!)

4. 연산자 (Operators) & 타입 변환의 함정

4-1. 산술 & 비교 & 논리 연산자

// 1. 산술 연산자 (+, -, *, /)
let x = 10, y = 3;
console.log(x + y); // 13 (더하기)
console.log(x - y); // 7  (빼기)
console.log(x * y); // 30 (곱하기)
console.log(x / y); // 3.3333... (나누기)

// 2. 비교 연산자 (>, <, >=, <=) ➔ 결과는 무조건 boolean
console.log(10 > 5);   // true
console.log(10 <= 9);  // false

// 3. 논리 연산자 (&&, ||, !)
let age = 20, hasId = true;
console.log(age >= 19 && hasId); // true (AND: 둘 다 참이어야 함)
console.log(age < 19 || hasId);  // true (OR: 둘 중 하나만 참이면 됨)
console.log(!hasId);             // false (NOT: 참/거짓 반전)

// 4. 문자열 연산자 (+)
let firstName = "Alex", lastName = "Kim";
console.log(firstName + " " + lastName); // "Alex Kim"

4-2. 동등(==) vs 일치(===) 연산자 (왜 ===를 써야 할까?)

== (동등 연산자): 비교할 때 자바스크립트가 스스로 타입을 강제로 일치시킨 후 값만 비교합니다 (위험!).
=== (일치 연산자 - 권장): **값과 데이터 타입이 모두 같아야만 true**로 판정합니다.

console.log(10 == "10");  // true  ⚠️ (숫자 10과 문자열 "10"을 같다고 판정!)
console.log(10 === "10"); // false ✅ (타입이 number vs string으로 다르므로 다름!)

4-3. 암묵적 타입 변환 (JavaScript vs Python)

문자열 + 숫자 덧셈 시:
- JavaScript: 숫자를 자동으로 문자열로 바꿔서 연결해 버립니다! ("10" + 1 ➔ "101")
- Python: 서로 다른 타입 덧셈을 허용하지 않고 TypeError를 발생시킵니다!

5. 조건문 (if / else) & Truthy vs Falsy

5-1. if / else 기본 문법

let age = 20;

if (age >= 19) {
  console.log("성인입니다.");
} else {
  console.log("미성년자입니다.");
}

5-2. Falsy 6대장 (무조건 암기!) & Truthy 값

자바스크립트 조건문(if) 괄호 안에 boolean이 아닌 일반 값을 넣었을 때, 자동으로 false로 취급되는 값은 전 우주에서 딱 6개뿐입니다:

❌ Falsy 값 (거짓으로 평가되는 6가지):

false
0 (숫자 영)
"" (빈 문자열)
null
undefined
NaN (Not a Number)

⭕ Truthy 값 (Falsy 6개를 제외한 세상의 모든 값!):

⚠️ 빈 배열 []은 Truthy! (배열 객체는 존재하므로 참!)
⚠️ 빈 객체 {}도 Truthy!
⚠️ 문자열 "0"도 Truthy! (글자가 1개 들어있는 문자열이므로 참!)

5-3. 실전 실습 1: 콘솔 사칙연산 계산기

요구사항: 숫자 두 개와 연산자 기호(+, -, *, /)를 변수로 받아 결과 출력하기

let a = 10;
let b = 5;
let operator = "+"; // "+", "-", "*", "/" 중 선택

if (operator === "+") {
  console.log(a + b);
} else if (operator === "-") {
  console.log(a - b);
} else if (operator === "*") {
  console.log(a * b);
} else if (operator === "/") {
  console.log(a / b);
} else {
  console.log("지원하지 않는 연산자입니다.");
}

5-4. 실전 실습 2: 복합 조건 합격 판정 프로그램

합격 조건:
- 점수(score) 70 이상
- 출석률(attendance) 80 이상
- 과제 제출 여부(submitted) true
- [단서 조항]: 단, 점수가 90점 이상이면 출석률은 미달이어도 합격!

let score = 88;
let attendance = 75;
let submitted = true;

// 과제는 필수 제출 + (기본 기준 통과 또는 90점 이상 슈퍼패스)
if (submitted && ((score >= 70 && attendance >= 80) || score >= 90)) {
  console.log("최종 합격");
} else {
  console.log("불합격");
}

6. 반복문 (Loop: for vs while) & 배열 (Array)

6-1. for 반복문과 while 반복문 비교

// 1. for 반복문 (반복 횟수가 정해져 있을 때 표준 사용)
// for (초기값; 조건식; 증감식)
for (let i = 1; i <= 3; i++) {
  console.log(i); // 1, 2, 3 출력
}

// 2. while 반복문 (특정 조건이 true인 동안 계속 반복 / 무한루프 주의!)
let i = 0;
while (i < 3) {
  console.log(i); // 0, 1, 2 출력
  i++;
}

6-2. 배열(Array)의 구조와 at(-1) 최신 인덱싱

여러 개의 값을 하나의 변수에 순서(0부터 시작하는 Index)대로 묶어 보관하는 자료형.
요소마다 서로 다른 타입을 담을 수도 있습니다.

let numbers = [10, 20, 30];

console.log(numbers[0]);      // 10 (첫 번째 요소)
console.log(numbers.at(-1));   // 30 (⭐ 맨 마지막 요소를 가리키는 모던 JS 문법!)
console.log(numbers[3]);       // undefined (존재하지 않는 4번째 인덱스 접근 시)

6-3. 현대적 배열 순회: for...of

배열 안의 알맹이 데이터를 하나씩 꺼내어 순서대로 처리할 때 가장 간결하고 직관적인 반복문:

let scores = [80, 90, 70];

for (const score of scores) {
  console.log(score); // 80 -> 90 -> 70 순차 출력
}

7. 기출 개념 점검 퀴즈 4선 풀이

Q1. 다음 중 Node.js의 역할로 가장 적절한 것은?

① HTML을 꾸민다
② JavaScript를 브라우저에서만 실행한다
③ 브라우저 없이 JavaScript를 실행한다 (정답 ✅)
④ CSS를 컴파일한다

해설: Node.js는 브라우저 외부 환경(컴퓨터 콘솔/서버)에서 JS를 독자적으로 실행할 수 있게 해주는 런타임 환경입니다.

Q2. 다음 코드의 출력 결과는? console.log(10 + "5");

① 15
② "15"
③ "105" (정답 ✅)
④ 에러 발생

해설: 숫자와 문자열을 + 연산하면 자바스크립트는 숫자를 문자열로 변환하여 두 문자열을 결합("10" + "5" = "105")합니다.

Q3. 다음 중 Falsy(거짓 같은 값)가 아닌 것은?

① 0
② ""
③ [] (정답 ✅)
④ null

해설: Falsy 6가지는 false, 0, "", null, undefined, NaN입니다. 빈 배열 []과 빈 객체 {}는 메모리에 객체 상자가 생성된 상태이므로 Truthy로 평가됩니다!

Q4. == 와 === 의 차이로 옳은 설명은?

① 차이가 없다
② == 는 타입까지 비교한다
③ === 는 값만 비교한다
④ === 는 값과 타입을 모두 비교한다 (정답 ✅)

해설: ==는 자동 형변환이 일어나 값만 비교하지만, ===는 데이터 타입까지 일치해야만 참으로 처리하는 엄격한 일치 연산자입니다.

8. 실전 핵심 요약 치트시트

1. 변수 선언 공식
   - 기본은 무조건 const 사용!
   - 값이 나중에 바뀌는 경우(카운터 등)에만 let 사용

2. 엄격 비교 원칙
   - (X) if (a == b)   --> 암묵적 형변환 버그 위험
   - (O) if (a === b)  --> 값 + 타입 완벽 일치 검사

3. Falsy 6대장 외우기
   false, 0, "", null, undefined, NaN
   (⚠️ [], {} 은 Falsy가 아니라 Truthy다!)

4. 배열 마지막 원소 접근
   arr.at(-1)  // arr[arr.length - 1]의 세련된 현대식 표현

5. 배열 순회 표준
   for (const item of items) { ... }

HTML/CSS & Javascript 5일차

write31991 — Thu, 15 Oct 2026 16:19:32 +0900

CSS Grid & 부트스트랩(Bootstrap) UI 프레임워크 완벽 정리 노트

2차원 바둑판 레이아웃 **CSS Grid(fr 단위·grid-template-areas·호버 효과)**부터 트위터의 오픈소스 UI 프레임워크 부트스트랩 5(12칸 그리드·반응형 Navbar·모달 팝업), 그리고 실무 한계점과 VS Code 팁까지 총정리한 실전 가이드

1. CSS Grid 레이아웃: 2차원 구조 설계

1-1. Grid의 정의와 레이아웃 기술별 비교

CSS Grid: **행(Row, 가로 줄)**과 **열(Column, 세로 줄)**을 동시에 제어하는 2차원 바둑판식 레이아웃 시스템.
페이지 전체의 거대한 골격 구조(뼈대) 자체를 설계할 때 가장 강력합니다.

기술. 차원 주요 목적 한계 및 적합한 상황

position	-	배지, 고정 헤더, 모달 팝업 등 특정 좌표 배치	요소 간의 관계가 끊어지므로 전체 페이지 틀을 잡기엔 부적합
flexbox	1차원	네비게이션 바 메뉴, 카드 내부 아이템 등 한 줄 정렬	가로와 세로 줄을 동시에 맞추는 격자 바둑판 구조에는 비효율적
Grid	2차원	대시보드, 매거진 갤러리, 쇼핑몰 상품 목록 격자	화면 전체 구조를 행과 열로 구획화할 때 최적

1-2. Grid Container (부모)와 Grid Item (자식)

Grid Container: display: grid;가 선언된 부모 요소 (바둑판 틀).
Grid Item: 컨테이너 바로 아래의 직계 자식 요소들 (바둑알).
원칙: 모든 배치와 칸 나누기는 부모(Container)의 CSS 속성을 기준으로 결정됩니다.

<div class="container"> <!-- Grid Container -->
  <div class="item">A</div> <!-- Grid Item -->
  <div class="item">B</div> <!-- Grid Item -->
  <div class="item">C</div> <!-- Grid Item -->
  <div class="item">D</div> <!-- Grid Item -->
  <div class="item">E</div> <!-- Grid Item -->
  <div class="item">F</div> <!-- Grid Item -->
</div>

2. Grid 핵심 문법 & 단위 정복

2-1. 열(Column) 만들기: repeat()과 fr 단위

grid-template-columns: 세로 열의 개수와 너비를 지정합니다.

.container {
  display: grid;

  /* 방법 1: 백분율로 4칸 분할 (25%씩 4개) */
  grid-template-columns: 25% 25% 25% 25%;

  /* 방법 2: repeat(반복횟수, 크기) 함수 사용 (위와 완벽히 동일) */
  grid-template-columns: repeat(4, 25%);

  /* 방법 3: fr(Fraction, 비율) 단위 사용 (1 : 2 : 1 비율로 유연 분할) */
  grid-template-columns: 1fr 2fr 1fr;
}

< Note >

fr(Fraction) 단위란?
그리드 컨테이너의 남은 여백 공간을 **비율(분수)**대로 나누어 갖는 그리드 전용 유연 단위입니다.
1fr 2fr 1fr은 전체 가로폭을 1 + 2 + 1 = 4등분하여 25% : 50% : 25%로 유연하게 배분합니다.

2-2. 행(Row) 만들기 & gap 간격 설정

grid-template-rows: 가로 행의 높이를 지정.
grid-auto-rows: 명시되지 않고 자동으로 늘어나는 행들의 기본 높이 지정.
gap: 그리드 아이템 사이의 여백 간격.

.container {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  
  /* 1행과 2행의 높이를 각각 80px로 고정 */
  grid-template-rows: 80px 80px;

  /* 아이템이 많아져 3행, 4행이 생길 때의 자동 높이 설정 */
  grid-auto-rows: 80px;

  /* 가로세로 아이템 사이 간격 10px */
  gap: 10px;
}

2-3. [추천] Grid 실전 연습 게임: Grid Garden

당근에 물을 주고 잡초를 뽑으며 Grid 속성을 단계별로 마스터하는 유명 학습 게임:
링크: https://cssgridgarden.com/#ko

3. 실전 프로젝트 1: grid-template-areas 반응형 갤러리

3-1. 직관적인 영역 배치 (grid-template-areas)

숫자 선 번호 대신, **눈에 보이는 문자열 지도(ASCII Art 형태)**로 각 영역의 이름을 배치하는 가장 직관적인 그리드 기법입니다:

.container {
  display: grid;
  gap: 0.8rem;
  grid-template-columns: 1fr 1fr 1fr;         /* 3열 구조 */
  grid-template-rows: repeat(4, 200px);       /* 4행 (각 200px 높이) */

  /* 직관적인 바둑판 영역 지도 정의 */
  grid-template-areas:
    "img1 img3 img3"
    "img1 img4 img6"
    "img2 img2 img6"
    "img5 img5 img5";
}

/* 각 아이템에 해당 영역 이름 부여 */
.img1 { grid-area: img1; }
.img2 { grid-area: img2; }
.img3 { grid-area: img3; }
.img4 { grid-area: img4; }
.img5 { grid-area: img5; }
.img6 { grid-area: img6; }

┌───────────┬───────────────────────┐
│   img1    │         img3          │  (img3은 2칸 차지)
├───────────┼───────────┬───────────┤
│   img1    │   img4    │   img6    │  (img1은 세로로 2칸)
├───────────┴───────────┼───────────┤
│         img2          │   img6    │  (img2는 가로 2칸, img6 세로 2칸)
├───────────────────────┴───────────┤
│               img5                │  (img5는 가로 전체 3칸 차지)
└───────────────────────────────────┘

3-2. object-fit: cover와 감성 흑백 호버 인터랙션

1) object-fit: cover;

이미지의 가로세로 비율이 제각각이어도, 원본 비율을 왜곡(찌그러짐) 없이 유지하며 지정된 박스에 꽉 채워주는 마법의 속성 (넘치는 영역은 자연스럽게 잘림).

2) container:hover img:not(:hover) (포커스 호버 기법)

컨테이너에 마우스를 올렸을 때, **"마우스가 올라가지 않은 나머지 모든 이미지들(:not(:hover))"**에게만 흑백 필터와 투명도를 적용하여, 마우스가 닿은 사진 하나만 화려하게 돋보이게 만듭니다!

/* 기본 이미지 세팅 */
img {
  width: 100%;
  height: 100%;
  object-fit: cover;
  border-radius: 0.6rem;
  transition: 0.5s ease; /* 부드러운 전환 효과 */
}

/* 갤러리에 호버 시, 호버되지 않은 다른 이미지들은 흑백 + 반투명 처리 */
.container:hover img:not(:hover) {
  filter: grayscale(1); /* 100% 흑백 처리 */
  opacity: 0.5;         /* 반투명 처리 */
}

3-3. 갤러리 완성 전체 코드 분석

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>CSS Grid Gallery</title>
  <style>
    .container {
      padding: 5% 10%;
      display: grid;
      gap: 0.8rem;
      grid-template-columns: 1fr 1fr 1fr;
      grid-template-rows: repeat(4, 200px);
      grid-template-areas:
        "img1 img4 img4"
        "img1 img6 img3"
        "img2 img2 img3"
        "img5 img5 img5";
    }

    img {
      width: 100%;
      height: 100%;
      object-fit: cover;
      border-radius: 0.6rem;
      transition: 0.5s;
    }

    .container:hover img:not(:hover) {
      filter: grayscale(1);
      opacity: 0.5;
    }

    .img1 { grid-area: img1; }
    .img2 { grid-area: img2; }
    .img3 { grid-area: img3; }
    .img4 { grid-area: img4; }
    .img5 { grid-area: img5; }
    .img6 { grid-area: img6; }
  </style>
</head>
<body>
  <div class="container">
    <div class="item img1"><img src="https://images.unsplash.com/photo-1787676560679-c6aefbac8767?w=900" alt="사진1"></div>
    <div class="item img2"><img src="https://images.unsplash.com/photo-1791921597945-adcedaed3115?w=900" alt="사진2"></div>
    <div class="item img3"><img src="https://images.unsplash.com/photo-1790274742524-5cc9cb0c10c3?w=900" alt="사진3"></div>
    <div class="item img4"><img src="https://images.unsplash.com/photo-1791889785364-39e79a18cd41?w=900" alt="사진4"></div>
    <div class="item img5"><img src="https://plus.unsplash.com/premium_photo-1791721702449-0db98c16f694?w=900" alt="사진5"></div>
    <div class="item img6"><img src="https://images.unsplash.com/photo-1791826119443-1bbbc2e35929?w=900" alt="사진6"></div>
  </div>
</body>
</html>

4. 부트스트랩 (Bootstrap 5) UI 프레임워크

4-1. 부트스트랩이란?

트위터(Twitter)에서 개발한 오픈소스 CSS & JavaScript UI 라이브러리 프레임워크.
버튼, 카드, 팝업, 반응형 네비게이션 바 등 자주 쓰이는 UI 컴포넌트가 미리 다 만들어져 있어 **"클래스 이름만 붙이면 완성도 높은 디자인이 완성"**됩니다.
➔ "개발자가 복잡한 CSS를 직접 처음부터 작성하지 않아도 된다!"

4-2. CDN 설치 및 환경 설정 (CSS & JS 번들)

별도의 npm 설치 없이 <head>와 <body> 끝에 링크 한 줄씩만 추가하면 즉시 가동됩니다:

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8">
  <title>Bootstrap 실습</title>
  <!-- 1. 부트스트랩 CSS CDN (스타일 적용) -->
  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body>

  <!-- 본문 내용 -->

  <!-- 2. 부트스트랩 JS 번들 CDN (모달 팝업, 햄버거 토글 등 동적 기능 필수) -->
  <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/js/bootstrap.bundle.min.js"></script>
</body>
</html>

4-3. 핵심 유틸리티: Flex, Badge, Button

<!-- 1. Flex & 배지 (알림 뱃지) -->
<div class="d-flex justify-content-center align-items-center gap-2">
  <div>알림 목록</div>
  <span class="badge bg-danger">5</span>
</div>

<!-- 2. 사전 정의된 컬러풀 버튼들 -->
<button class="btn btn-primary">확인 (파란색)</button>
<button class="btn btn-danger">취소 (빨간색)</button>
<button class="btn btn-info">보류 (하늘색)</button>
<button class="btn btn-secondary">닫기 (회색)</button>

4-4. 부트스트랩의 12칸 Grid 시스템 (container ➔ row ➔ col)

부트스트랩 그리드는 **화면 가로를 무조건 12개의 균등한 칸(Column)**으로 분할하여 계산합니다:

┌────────────────────────────────────────────────────────────────────────┐
│                   container (중앙 정렬 컨테이너)                         │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                        row (행)                                  │  │
│  │  ┌───────────────────────────┬────────────────────────────────┐  │  │
│  │  │      col-6 (6칸 = 50%)    │       col-6 (6칸 = 50%)        │  │  │
│  │  └───────────────────────────┴────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────┘

공식: 한 줄의 col 숫자 합이 12가 되도록 조합합니다. (예: col-6 + col-6, col-4 + col-4 + col-4)
반응형 접두사: col-md-4 ➔ 중간 화면(태블릿/PC) 이상에서는 4칸(3개씩), 작은 모바일에서는 12칸(1개씩 100%) 자동 전환!

5. 실전 프로젝트 2: 부트스트랩 핵심 컴포넌트 3선

5-1. 실습 1: 3단 카드(Card) 레이아웃 (col-md-4)

한 줄에 카드가 3개씩 나란히 놓이는 반응형 대시보드 카드 레이아웃:

<div class="container mt-5">
  <div class="row">
    <!-- 카드 1 (12칸 중 4칸 차지 = 1/3 크기) -->
    <div class="col-md-4 mb-3">
      <div class="card p-3 shadow-sm">
        <div class="card-body">
          <h5 class="card-title">기본 카드 1</h5>
          <p class="card-text">설명 텍스트가 들어가는 본문 영역입니다.</p>
          <a href="#" class="btn btn-primary">상세보기</a>
        </div>
      </div>
    </div>

    <!-- 카드 2 -->
    <div class="col-md-4 mb-3">
      <div class="card p-3 shadow-sm">
        <div class="card-body">
          <h5 class="card-title">기본 카드 2</h5>
          <p class="card-text">설명 텍스트가 들어가는 본문 영역입니다.</p>
          <a href="#" class="btn btn-primary">상세보기</a>
        </div>
      </div>
    </div>

    <!-- 카드 3 -->
    <div class="col-md-4 mb-3">
      <div class="card p-3 shadow-sm">
        <div class="card-body">
          <h5 class="card-title">기본 카드 3</h5>
          <p class="card-text">설명 텍스트가 들어가는 본문 영역입니다.</p>
          <a href="#" class="btn btn-primary">상세보기</a>
        </div>
      </div>
    </div>
  </div>
</div>

5-2. 실습 2: 반응형 햄버거 메뉴 Navigation Bar

자바스크립트 코드를 직접 한 줄도 작성하지 않고, 오직 data-bs-* 속성만으로 모바일 햄버거 메뉴 열림/닫힘을 구현합니다:

<nav class="navbar navbar-expand-lg navbar-dark bg-dark">
  <div class="container">
    <!-- 브랜드 로고 -->
    <a class="navbar-brand text-white" href="#">MySite</a>

    <!-- 모바일용 햄버거 토글 버튼 -->
    <button
      class="navbar-toggler"
      type="button"
      data-bs-toggle="collapse"
      data-bs-target="#navMenu"
    >
      <span class="navbar-toggler-icon"></span>
    </button>

    <!-- 메뉴 리스트 (화면 작을 땐 접히고, PC에선 펼쳐짐) -->
    <div class="collapse navbar-collapse" id="navMenu">
      <ul class="navbar-nav ms-auto">
        <li class="nav-item"><a class="nav-link active" href="#">Home</a></li>
        <li class="nav-item"><a class="nav-link" href="#">About</a></li>
        <li class="nav-item"><a class="nav-link" href="#">Contact</a></li>
      </ul>
    </div>
  </div>
</nav>

5-3. 실습 3: 인터랙티브 Modal (모달 팝업창)

버튼을 누르면 화면 중앙에 뜨는 다이얼로그 팝업의 3단계 구조입니다:

<!-- 1. 모달을 띄우는 트리거 버튼 -->
<div class="container mt-5 text-center">
  <button
    class="btn btn-primary"
    data-bs-toggle="modal"
    data-bs-target="#exampleModal"
  >
    삭제 확인 모달 열기
  </button>
</div>

<!-- 2. 모달 팝업 본체 -->
<div class="modal fade" id="exampleModal" tabindex="-1">
  <div class="modal-dialog modal-dialog-centered">
    <div class="modal-content">
      
      <!-- 헤더 (제목 + 닫기 X 버튼) -->
      <div class="modal-header">
        <h5 class="modal-title">경고 알림</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
      </div>

      <!-- 바디 (본문 메시지) -->
      <div class="modal-body">
        정말로 영구 삭제하시겠습니까?
      </div>

      <!-- 푸터 (취소/확인 버튼) -->
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">취소</button>
        <button type="button" class="btn btn-danger">삭제 확정</button>
      </div>

    </div>
  </div>
</div>

6. 부트스트랩의 실무적 한계 & 개발 환경 꿀팁

6-1. 부트스트랩의 단점과 Tailwind CSS 전환 트렌드

클래스 남용과 HTML 가독성 저하: 수많은 클래스가 태그에 덕지덕지 붙어 HTML 구조 파악이 어려워질 수 있습니다.
디자인 커스텀의 한계: 이미 만들어진 스타일이 확고하여, 기업만의 개성 넘치는 독창적인 UI를 만들려면 부트스트랩의 기본 CSS를 강제로 덮어써야 하는 번거로움이 있습니다.
최신 트렌드: 최근 실무 웹 서비스에서는 부트스트랩 대신 훨씬 자유도가 높고 최적화된 Tailwind CSS를 채택하는 경우가 매우 많습니다.

6-2. VS Code 필수 설정: Format On Save (자동 들여쓰기 정렬)

코드를 작성하고 저장(Ctrl + S / Cmd + S)할 때마다 삐뚤빼뚤한 들여쓰기와 태그 닫기를 에디터가 자동으로 칼같이 정렬해 주는 필수 설정입니다:

VS Code에서 Ctrl + , (Mac은 Cmd + ,) 단축키를 눌러 설정(Settings) 창을 엽니다.
검색창에 **format on save**를 입력합니다.
Editor: Format On Save 항목의 체크박스를 **체크(✅)**합니다!

7. 실전 핵심 요약 치트시트

1. CSS Grid 핵심
   - 2차원(가로/세로 동시) 레이아웃 시스템
   - repeat(3, 1fr) ➔ 3등분 자동 배분
   - gap: 10px ➔ 칸 사이 간격
   - grid-template-areas ➔ 시각적 바둑판 지도 배치
   - object-fit: cover ➔ 이미지 비율 찌그러짐 방지

2. Bootstrap 5 핵심
   - 12칸 그리드: container ➔ row ➔ col-md-4 (3칸씩)
   - data-bs-toggle="collapse/modal" ➔ JS 없이 팝업/토글 제어
   - 모달 구조: modal ➔ modal-dialog ➔ modal-content (header/body/footer)

3. 개발 꿀팁
   - Grid 연습 게임: https://cssgridgarden.com/#ko
   - VS Code 저장 시 자동 정렬: Settings ➔ 'Format On Save' 체크

HTML/CSS & Javascript 4일차

write31991 — Wed, 14 Oct 2026 16:04:15 +0900

CSS 레이아웃 & 반응형 웹 마스터: Position, Flexbox & Media Query 완벽 정리 노트

Normal Flow의 한계 극복부터 Position 4대 속성(static/relative/absolute/fixed), Flexbox 1차원 레이아웃(주축·교차축·flex: 1), Media Query 반응형 디자인, 그리고 실전 반응형 네비게이션 바(Navbar) 구현까지 총정리한 실전 가이드

1. Normal Flow (기본 문서 흐름)와 레이아웃의 필요성

1-1. Normal Flow란?

CSS에서 아무런 위치/레이아웃 속성도 적용하지 않았을 때 브라우저가 요소를 자동으로 배치하는 기본 규칙입니다.
웹 문서의 가장 자연스러운 원시적 흐름(Normal Flow)입니다.

1-2. Normal Flow의 배치 규칙과 한계점

Inline 요소: 텍스트를 쓸 때처럼 왼쪽에서 오른쪽으로 나열되며, 공간이 꽉 차면 자동으로 다음 줄로 넘어갑니다 (span, a, strong).
Block-level 요소: 블록처럼 위에서 아래로 한 줄 전체를 독점하며 벽돌을 쌓듯 차례로 배치됩니다 (div, p, h1).

Warning

Normal Flow의 치명적 한계:
기본 흐름만으로는 현대 웹의 필수 요소인 좌우 가로 정렬, 상하좌우 완전한 정가운데 정렬, 유연한 간격(gap) 조절, 특정 위치 고정(헤더/배지) 등을 구현하기가 극도로 어렵습니다.
➔ 따라서 우리는 **position**과 **flexbox**를 통해 Normal Flow를 의도적으로 벗어나거나 제어합니다!

2. CSS position 속성: 자유로운 위치 제어

2-1. position 속성의 개념과 오프셋 4대장

역할: 요소를 어디에(Where), 무엇을 기준(Reference)으로 배치할지 결정하는 핵심 속성.
오프셋 프로퍼티: 기준점으로부터 얼마나 떨어질지 거리를 지정합니다.
- top, bottom, left, right (px, rem, % 등)

2-2. position: static (기본값)

모든 HTML 요소의 태생적 기본값.
Normal Flow를 그대로 유지하며 일반적인 문서 흐름에 따라 배치됩니다.
⚠️ top, left, right, bottom 오프셋 좌표를 적어도 완전히 무시되어 적용되지 않습니다!

2-3. position: relative (원래 자기 자리 기준)

기준점: **"내가 원래 있었어야 할 본래 위치"**가 기준점(0, 0)이 됩니다.
특징:
1. Normal Flow 유지: 요소가 시각적으로 이동하더라도, 원래 자리는 빈 공간(유령 자리)으로 그대로 보존됩니다.
2. 다른 인접 요소들의 레이아웃 배치에 전혀 영향을 주지 않습니다 (margin과 다른 점!).
3. 자식의 absolute를 가두는 기준 조상 역할로 가장 많이 사용됩니다.

.box {
  position: relative;
  top: 30px;  /* 원래 위치에서 아래로 30px 이동 */
  left: 30px; /* 원래 위치에서 오른쪽으로 30px 이동 */
}

2-4. position: absolute (기준 조상 기준) & 실무 공식

기준점: "가장 가까운 position이 지정된 조상 요소" (즉, static이 아닌 relative, absolute, fixed를 가진 부모).
특징:
1. Normal Flow에서 완전 제거: 붕 떠오르면서(부유) 원래 차지하던 자리가 사라집니다. 주변 요소들이 빈자리를 메우기 위해 당겨집니다.
2. 기준이 될 포지셔닝 부모가 없으면 **브라우저 화면(Viewport / 초기 컨테이닝 블록)**을 기준으로 배치됩니다.

실무 100% 필수 공식: "부모 relative + 자식 absolute"

<div class="container">
  <div class="box">BOX</div>
</div>

/* 1. 부모에게 기준점 부여 */
.container {
  width: 200px;
  height: 200px;
  border: 3px solid #333;
  position: relative; /* 자식의 absolute 좌표 기준점이 됨! */
}

/* 2. 자식은 부모 안에서 자유자재로 이동 */
.box {
  width: 100px;
  height: 100px;
  background: #4caf50;
  position: absolute;
  top: 0px;
  left: 0px; /* 부모 컨테이너의 좌상단(0, 0)에 정확히 밀착 */
}

실전 활용 예제: 우상단 링크/배지 고정

.korean-link {
  position: absolute;
  top: 10px;
  right: 10px; /* 부모의 오른쪽 위 모서리에 고정 */
  color: darkcyan;
  font-size: small;
}

2-5. position: fixed (화면 뷰포트 기준 영구 고정)

기준점: 부모가 누구든 상관없이 무조건 **브라우저 화면 전체(Viewport)**가 기준점.
특징:
1. Normal Flow에서 완전히 제거됨.
2. 페이지를 아무리 길게 스크롤해도 화면의 지정된 그 위치에 못 박힌 듯 영구 고정됩니다.
3. 주요 사용처: 상단 고정 헤더(Navigation Bar), 화면 우하단 맨 위로 가기 플로팅 버튼, 챗봇 상담 아이콘.

.fixed-header {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%; /* 화면 상단 전체를 덮는 고정 바 */
}

2-6. position 4대 속성 한눈에 비교하기

속성값기준점 (Reference)Normal Flow 이탈 여부원래 자리 보존 여부스크롤 시 동작

static	일반적인 문서 흐름	❌ (유지)	⭕ (보존)	함께 스크롤됨 (위치 이동 불가)
relative	자신의 본래 위치	❌ (유지)	⭕ (원래 자리 비어있음)	함께 스크롤됨
absolute	포지셔닝된 가장 가까운 조상	⭕ (완전 제거)	❌ (자리 사라짐)	함께 스크롤됨
fixed	브라우저 화면 (Viewport)	⭕ (완전 제거)	❌ (자리 사라짐)	화면에 영구 고정 (스크롤 무시)

3. Flexbox (Flexible Box Layout): 1차원 정렬 시스템

3-1. Flexbox의 탄생 배경과 핵심 특징

목적: 복잡한 계산 없이 여러 박스를 한 방향(가로 or 세로)으로 유연하게 배치하고 정렬하기 위한 최신 CSS 레이아웃 시스템.
핵심 특징:
1. 1차원 레이아웃: 가로(Row) 또는 세로(Column) 중 한 방향 축을 기준으로 정렬.
2. 부모 중심 제어: 부모(Container)에게 속성을 주면 자식(Items)들의 배치가 일괄 통제됨.
3. 직관적인 간격과 정렬: gap, justify-content, align-items로 손쉬운 여백 제어.

3-2. Flex Container (부모) vs Flex Item (자식)

부모 요소에 display: flex;를 선언하는 순간, 즉시 Flex 환경이 가동됩니다:

<div class="container"> <!-- Flex Container (부모) -->
  <div class="item">A</div> <!-- Flex Item (자식) -->
  <div class="item">B</div> <!-- Flex Item (자식) -->
  <div class="item">C</div> <!-- Flex Item (자식) -->
</div>

.container {
  display: flex; /* 자식들이 기본적으로 가로(row) 방향으로 나란히 정렬됨 */
  gap: 10px;     /* 자식 아이템 사이의 간격을 10px로 균등 배치 */
}

3-3. 주축(Main Axis) vs 교차축(Cross Axis)

Flexbox는 항상 두 개의 직교하는 축을 기준으로 요소를 정렬합니다:

[기본값: flex-direction: row 인 경우]

  주축 (Main Axis: 가로) ➔ justify-content 로 정렬
  ────────────────────────────────────────────────────────►
 │ [Item A]   [Item B]   [Item C]
 │
 │ 교차축 (Cross Axis: 세로) ➔ align-items 로 정렬
 ▼

주축 (Main Axis): 아이템들이 배치되는 기본 진행 방향 (기본값: 가로 방향 row).
교차축 (Cross Axis): 주축과 90도로 교차하는 수직 방향 (기본값: 세로 방향 column).

3-4. Flexbox 정렬 3단계 핵심 프로퍼티

1) 1단계: 주축의 방향 결정 (flex-direction)

flex-direction: row; (기본값) ➔ 왼쪽에서 오른쪽으로 가로 배치
flex-direction: column; ➔ 위에서 아래로 세로 배치 (모바일 반응형에서 필수!)

2) 2단계: 주축 방향의 정렬 결정 (justify-content)

flex-start (기본값): 시작 지점으로 정렬
center: 주축 기준 가운데 정렬
flex-end: 끝 지점으로 정렬
space-between: 양 끝을 벽에 붙이고, 아이템 사이 간격을 균등하게 배분 (네비게이션 바 필수!)
space-around / space-evenly: 아이템 둘레/사이를 균등 분배

3) 3단계: 교차축 방향의 정렬 결정 (align-items)

stretch (기본값): 부모의 높이만큼 아이템을 늘림
center: 교차축 기준 수직 가운데 정렬
flex-start / flex-end: 상단 또는 하단 정렬

3-5. 실무 마법의 코드: 정가운데 정렬 & flex: 1 스티키 푸터

마법 1: 박스 안의 글자/요소를 상하좌우 완전 정가운데 놓기

.item {
  display: flex;
  justify-content: center; /* 가로(주축) 가운데 */
  align-items: center;     /* 세로(교차축) 가운데 */
}

마법 2: flex: 1 ➔ 남은 공간 혼자 다 차지하기 (Sticky Footer 패턴)

콘텐츠가 적은 페이지에서도 푸터(Footer)가 화면 중간에 뜨지 않고 항상 브라우저 맨 바닥에 달라붙게 만드는 실무 표준 기법:

body {
  min-height: 100vh;       /* 화면 전체 높이 보장 */
  display: flex;
  flex-direction: column;  /* 세로 방향으로 쌓기 */
}

main {
  flex: 1;                 /* ⭐ 메인 콘텐츠가 화면의 남은 여백을 전부 차지하여 푸터를 맨 밑으로 밀어냄! */
}

footer {
  margin-bottom: 2rem;
}

3-6. [추천] Flexbox 실전 연습 게임: Flexbox Froggy

개구리를 연잎 위에 올려놓으며 Flexbox 정렬 속성을 직관적으로 마스터하는 세계적인 학습 게임:
링크: https://flexboxfroggy.com/#ko

4. 반응형 웹 디자인 (Responsive Design) & Media Query

4-1. 반응형 디자인의 필요성

스마트폰, 태블릿, 데스크톱 모니터 등 사용자의 화면 크기(Viewport)와 디바이스 환경이 다양화됨에 따라, 화면에 맞춰 레이아웃과 폰트 크기가 자연스럽게 재배치되는 웹을 구축해야 합니다.

4-2. 반응형의 3대 핵심 요소 & rem 크기 단위

유연한 레이아웃: Flexbox, Grid
유연한 상대 크기 단위: %, vw, vh, rem
조건부 스타일: Media Query (@media)

Note

rem 단위란?
rem(Root em)은 최상위 <html> 태그의 기본 폰트 크기(보통 16px)를 기준으로 비례하는 상대 단위입니다.

1rem = 16px
2.4rem = 약 38.4px (대제목)
0.9rem = 약 14.4px (작은 본문/라벨)
모바일이나 사용자 설정에 따라 기본 글꼴이 커지면 모든 요소가 아름답게 함께 확대/축소됩니다.

4-3. Media Query (미디어 쿼리) 문법과 분기점

정의: **"화면이 이 조건(크기)에 부합하면, 아래 스타일을 덮어써서 적용하라!"**는 조건부 CSS 규칙.

/* 화면 너비가 400px 이하인 작은 스마트폰 화면일 때만 실행 */
@media (max-width: 400px) {
  .container {
    flex-direction: column; /* 가로 나열을 세로 쌓기로 변경 */
  }
  .box {
    background: orange;     /* 배경색 변경 */
  }
}

5. 실전 종합 프로젝트: 반응형 네비게이션 바 (Responsive Navbar)

강의 슬라이드에서 완성한 PC에서는 가로 1줄, 모바일(400px 이하)에서는 세로로 깔끔하게 떨어지는 반응형 상단 메뉴바의 완성 코드입니다:

5-1. 시맨틱 HTML 구조 설계 (navbar.html)

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8" />
  <title>반응형 Navigation Bar</title>
  <!-- Font Awesome CDN 및 외부 스타일시트 연결 -->
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.1/css/all.min.css" />
  <link rel="stylesheet" href="navbar_style.css" />
</head>
<body>
  <nav class="navbar">
    <!-- 1. 좌측 로고 -->
    <div class="navbar__logo">
      <i class="fa-brands fa-dev"></i>
      <a href="#">qu3vipon</a>
    </div>

    <!-- 2. 중앙 메뉴 링크 -->
    <ul class="navbar__menu">
      <li><a href="#">About</a></li>
      <li><a href="resume.html">Resume</a></li>
      <li><a href="#">Gallery</a></li>
    </ul>

    <!-- 3. 우측 SNS 아이콘 -->
    <ul class="navbar__icons">
      <li><i class="fa-brands fa-github"></i></li>
      <li><i class="fa-brands fa-x-twitter"></i></li>
    </ul>
  </nav>
</body>
</html>

5-2. 데스크톱 기본 스타일 (navbar_style.css)

/* 기본 리셋 및 폰트 */
body {
  margin: 0;
  font-family: "BBH Bogle", sans-serif;
}

a {
  text-decoration: none;
  color: black;
}

/* 네비게이션 컨테이너: flex 3등분 좌우 분배 */
.navbar {
  display: flex;
  justify-content: space-between; /* 로고 - 메뉴 - 아이콘을 양 끝과 중앙에 고루 배치 */
  align-items: center;            /* 수직 가운데 정렬 */
  background-color: beige;
  padding-left: 0.5rem;
  padding-right: 0.5rem;
}

.navbar__logo {
  font-size: 1.4rem;
}

/* 메뉴 리스트: 가로 flex 배치 */
.navbar__menu {
  display: flex;
  list-style: none;
  padding: 0;
}

.navbar__menu li {
  padding: 8px 12px;
}

.navbar__menu li:hover {
  background-color: white;
  border-radius: 8px;
}

/* SNS 아이콘 리스트: 가로 flex 배치 */
.navbar__icons {
  display: flex;
  list-style: none;
  padding: 0;
}

.navbar__icons li {
  padding: 8px 4px;
}

5-3. 모바일 반응형 미디어 쿼리 (@media (max-width: 400px))

화면 너비가 좁아지면 가로 정렬을 **세로 1열(column)**로 전환하여 화면 찌그러짐을 방지합니다:

@media (max-width: 400px) {
  /* 1. 전체 바를 세로로 쌓고 왼쪽 정렬 */
  .navbar {
    flex-direction: column;
    align-items: flex-start;
    padding: 16px;
  }

  /* 2. 메뉴 항목을 가로폭 100% 차지하게 늘리고 텍스트 중앙 정렬 */
  .navbar__menu {
    flex-direction: column;
    width: 100%;
    text-align: center;
  }

  /* 3. 아이콘 모음도 중앙 정렬 */
  .navbar__icons {
    justify-content: center;
    width: 100%;
  }
}

6. 실전 핵심 요약 치트시트

1. position 핵심 공식
   - static   : 기본 흐름 (top/left 무시)
   - relative : 원래 내 자리 기준 (부모 기준점 잡기용)
   - absolute : 가장 가까운 포지셔닝 부모 기준 (자식 부유 배치)
   - fixed    : 화면 창(viewport) 기준 (스크롤해도 영구 고정)
     공식: 부모에 position: relative 주고 자식에 position: absolute 주기!

2. Flexbox 정렬 공식
   - display: flex;                     (가로 정렬 가동)
   - justify-content: center;           (주축 가로 가운데)
   - align-items: center;               (교차축 세로 가운데)
   - justify-content: space-between;    (양 끝 벌리기)
   - flex: 1;                           (남은 빈 공간 다 차지하기)

3. 반응형 Media Query 공식
   @media (max-width: 768px) {
     /* 모바일/태블릿용 스타일 작성 (flex-direction: column 등) */
   }

HTML/CSS & Javascript 3일차

write31991 — Wed, 14 Oct 2026 16:02:28 +0900

CSS 핵심 마스터: 선택자(Selector), 우선순위, 박스 모델 & 디스플레이 완벽 정리 노트

CSS 적용 방식(Internal vs External)부터 모든 종류의 선택자(기본·결합·속성·가상 클래스), 선택자 우선순위 점수표, 박스 모델(Box Model)과 box-sizing 계산 공식, 그리고 Inline vs Block vs Inline-Block 디스플레이 성질까지 완벽 가이드

1. CSS 적용 3가지 방식 (적용 위치에 따른 분류)

방식작성 위치문법 예시장단점 및 특징

1. Inline Style	HTML 태그 안 style=""	<p style="color: red;">	특정 태그 하나에만 즉시 적용되나 유지보수가 어렵고 우선순위가 너무 높아 실무 지양
2. Internal CSS	HTML <head> 안 <style> 태그	<style> div { text-align: center; } </style>	한 HTML 파일 안에서 일괄 관리 가능, 단 여러 페이지에 걸쳐 재사용 불가
3. External CSS	별도 분리된 .css 파일	<link rel="stylesheet" href="style.css">	실무 표준! HTML과 스타일을 완벽히 분리하고 여러 페이지에서 공통 재사용 가능

Internal CSS 예시 코드

<head>
  <style>
    div { text-align: center; }
    header { font-size: x-large; font-weight: bold; }
    main { font-size: medium; }
    footer { font-size: xx-small; }
  </style>
</head>

External CSS 예시 코드

<head>
  <!-- 별도의 style.css 파일을 불러와 연결 -->
  <link rel="stylesheet" href="style.css">
</head>

2. CSS 선택자 (Selectors) 완전 정복

선택자(Selector)란? 어떤 HTML 요소에 CSS 스타일을 적용할지 대상을 지정하는 규칙

2-1. 기본 선택자 4종

/* 1. 전체 셀렉터 (*): 페이지 내의 모든 HTML 요소를 일괄 선택 */
* {
  margin: 0;
  padding: 0;
}

/* 2. 태그 셀렉터: 지정한 태그 이름을 가진 모든 요소 선택 */
div {
  color: blue;
}

/* 3. 클래스 셀렉터 (.class): 특정 클래스명을 가진 요소 그룹 선택 */
.class {
  font-size: 16px;
}

/* 4. ID 셀렉터 (#id): 페이지에 단 하나뿐인 고유 ID를 가진 요소 선택 */
#id {
  font-weight: bold;
}

2-2. 결합자 (관계) 선택자 4종

부모, 자식, 형제 관계를 기반으로 대상을 정밀하게 조준합니다:

┌──────────────────────────────────────────────┐
│ <div class="parent">                         │
│     <p>1번 문단 (div의 직계 자식이자 자손)</p>   │
│     <section>                                │
│         <p>2번 문단 (div의 자손)</p>          │
│     </section>                               │
│ </div>                                       │
│ <p>3번 문단 (div 바로 다음 인접 형제)</p>        │
│ <p>4번 문단 (div 뒤에 오는 일반 형제)</p>        │
└──────────────────────────────────────────────┘

선택자 종류문법공백/기호설명 및 선택 범위

자손 선택자	div p	공백 ( )	div 안에 들어있는 모든 p 요소 (자식이든 손자든 깊이 상관없이 전부)
자식 선택자	div > p	꺾쇠 (>)	div의 바로 아래 직계 자식 p만 선택 (손자/증손자는 제외)
인접 형제 선택자	div + p	더하기 (+)	div 바로 뒤에 딱 붙어서 뒤따라오는 첫 번째 p 하나만 선택
일반 형제 선택자	div ~ p	물결 (~)	div 뒤에 오는 모든 형제 p 요소들을 전부 선택

2-3. 속성 선택자 (Attribute Selectors)

태그가 가진 속성(Attribute)과 그 값을 조건으로 요소를 선택합니다:

/* 1. href 속성을 가지고 있는 모든 a 태그 선택 */
a[href] {
  color: green;
}

/* 2. type 속성값이 정확히 "text"인 input 태그만 선택 */
input[type="text"] {
  border: 1px solid #ccc;
}

/* 3. target 속성이 "_blank"인 링크만 선택 */
a[target="_blank"] {
  font-weight: bold;
}

2-4. 가상 클래스 선택자 (Pseudo-class Selectors)

요소의 **특정한 상태(마우스 오버, 포커스 등)**나 위치 순서를 기준으로 선택합니다:

/* 1. :hover ➔ 마우스 커서를 요소 위에 올렸을 때 */
a:hover {
  text-decoration: underline;
  color: red;
}

/* 2. :focus ➔ 입력창(input) 등을 클릭하여 포커스를 가졌을 때 */
input:focus {
  outline: 2px solid skyblue;
}

/* 3. :active ➔ 마우스 버튼을 꾹 누르고(클릭 중) 있는 그 순간 */
button:active {
  background-color: darkgray;
}

/* 4. :nth-child(n) ➔ 부모 기준으로 n번째 자식 요소 선택 */
li:nth-child(1) { color: red; }       /* 1번째 항목 */
li:nth-child(even) { background: #eee; } /* 짝수 번째 항목 */
li:nth-child(2n+1) { background: #fff; } /* 홀수 번째 항목 */

2-5. [추천] 선택자 실전 연습 사이트: CSS Diner

CSS 선택자의 원리를 직관적인 식탁 접시 게임으로 실습할 수 있는 최고의 연습 사이트:
링크: https://flukeout.github.io/

3. 선택자 우선순위 (Specificity / 캐스케이딩 규칙)

여러 스타일이 동일한 요소에 충돌할 때, 브라우저가 어떤 스타일을 최종 채택할지 결정하는 계급 체계입니다:

[최강] !important (무조건 1순위 강제 적용)
  ▲
  │   inline style (HTML 태그 안 style="")  ── [1000점]
  │   id 선택자 (#id)                       ── [100점]
  │   class / 속성 / 가상 클래스 (.c, [t], :h)── [10점]
  │   태그 선택자 (div, p)                   ── [1점]
  │   * (전체 선택자)                        ── [0점]
[최약] 상속된 부모 스타일

황금 요약 규칙

✅ !important > inline style > id (#) > class (.) > tag > *

점수가 같으면 **"가장 나중에(아래쪽에) 작성된 코드"**가 최종 승리합니다!

4. CSS 박스 모델 (Box Model - 꼭 암기하자!)

박스 모델이란? 브라우저가 모든 HTML 요소를 네모난 사각형 박스로 취급하고, 그 크기와 여백을 계산하는 규칙입니다.

┌────────────────────────────────────────────────────────┐
│                        MARGIN                          │  ◀── 바깥쪽 여백
│   ┌────────────────────────────────────────────────┐   │
│   │                    BORDER                      │   │  ◀── 테두리 선
│   │   ┌────────────────────────────────────────┐   │   │
│   │   │                PADDING                 │   │   │  ◀── 안쪽 여백
│   │   │   ┌────────────────────────────────┐   │   │   │
│   │   │   │                                │   │   │   │
│   │   │   │            CONTENT             │   │   │   │  ◀── 실제 콘텐츠 내용
│   │   │   │         (글자, 이미지 등)        │   │   │   │      (width x height)
│   │   │   │                                │   │   │   │
│   │   │   └────────────────────────────────┘   │   │   │
│   │   └────────────────────────────────────────┘   │   │
│   └────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────┘

4-1. 박스 모델의 4대 구성 요소

Content (콘텐츠): 텍스트나 이미지가 들어있는 실제 알맹이 영역.
Padding (패딩): 콘텐츠와 테두리(Border) 사이의 안쪽 여백.
Border (테두리): 패딩 바깥을 감싸는 시각적 테두리 경계선.
Margin (마진): 테두리 바깥에 생기는 다른 요소와의 간격(바깥쪽 여백).

4-2. 실제 화면 크기 계산과 content-box의 함정

<div class="box">BOX</div>

.box {
  width: 100px;
  padding: 50px;
  border: 5px solid black;
  margin: 20px;
}

기본값(box-sizing: content-box) 상태에서는 width: 100px이 오직 Content 영역만의 크기를 의미합니다:

실제 차지하는 가로 폭=width(100)+padding 양쪽(50×2)+border 양쪽(5×2)=210px

Warning

개발자는 박스 크기를 100px로 만들려고 했으나, 패딩과 테두리가 더해져 실제 크기가 210px로 2배 이상 뚱뚱해지는 대참사가 발생합니다!

4-3. 해결책: box-sizing: border-box 필수 초기화

box-sizing: border-box로 설정하면, 지정한 width 안에 Padding과 Border의 두께가 자동으로 포함되어 계산됩니다:

전체 가로 폭=100px 안에 Padding과 Border가 모두 들어감! (크기 유지)

/* 실무 필수 표준 리셋 코드: 모든 요소에 border-box 일괄 적용 */
*, *::before, *::after {
  box-sizing: border-box;
}

5. 주요 CSS 스타일링 프로퍼티

5-1. background-color & margin/border/padding

header {
  font-size: x-large;
  font-weight: bold;
  background-color: red;
  margin-top: 20px;       /* 위쪽 바깥 여백 20px */
  border: 2px solid blue; /* 2px 두께 실선 파란 테두리 */
}

main {
  font-size: medium;
  background-color: green;
  padding: 50px;          /* 사방 안쪽 여백 50px */
}

footer {
  font-size: xx-small;
  background-color: yellow;
}

5-2. font-family & font 단축 속성(Shorthand)

1) font-family: 글꼴과 대체 폰트(Fallback)

header {
  /* 1순위: Times New Roman, 없으면 2순위 Times, 둘 다 없으면 기본 명조(serif) */
  font-family: 'Times New Roman', Times, serif;
}

2) font 단축 속성 (순서 주의!)

작성 순서: font-weight ➔ font-size ➔ font-family
필수 포함 규칙: font-size와 font-family는 반드시 생략 없이 포함되어야 단축 문법이 유효합니다.

header {
  /* font-weight(bold) + font-size(x-large) + font-family */
  font: bold x-large 'Times New Roman', Times, serif;
}

5-3. 링크 스타일링 (text-decoration & hover)

기본 밑줄을 지우고, 마우스를 올렸을 때만 밑줄이 나타나게 하는 깔끔한 링크 스타일:

.github-link {
  font-size: small;
  color: gray;
  text-decoration: none; /* 파란 기본 밑줄 제거 */
}

.github-link:hover {
  text-decoration: underline; /* 마우스 올렸을 때만 밑줄 표시 */
}

5-4. 웹 폰트 아이콘 라이브러리: Font Awesome 활용

웹에서 사용하는 다양한 브랜드/시스템 아이콘을 글자(Font)처럼 제공하는 대표 라이브러리:

<head>에 CDN 링크 연결:

<link
  rel="stylesheet"
  href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.1/css/all.min.css"
/>

태그로 아이콘 출력 (예: GitHub 고양이 로고):

<a class="github-link" href="https://github.com/qu3vipon">
  <i class="fa-brands fa-github"></i> GitHub
</a>

6. 공간 배치와 성질: Inline vs Block vs Inline-block

화면에서 공간을 차지하고 줄바꿈되는 방식에 따라 요소는 크게 나뉩니다:

6-1. Inline 요소 vs Block-level 요소 비교

구분Block-level (블록 요소)Inline (인라인 요소)

줄바꿈	항상 새로운 줄에서 시작	줄바꿈 없이 같은 줄에 나란히 배치
너비(Width)	기본값으로 부모 가로 폭 100% 전부 차지	텍스트/콘텐츠의 내용물 크기만큼만 차지
크기 지정	width, height 지정 가능	width, height 지정 불가 (무시됨)
상하 여백	margin-top/bottom 완벽 적용	margin-top/bottom 제대로 적용 안 됨
대표 태그	<div>, <p>, <h1>~<h6>, <section>, <article>, <header>, <footer>	<span>, <a>, <strong>, <em>, <img>

6-2. display 속성으로 성질 전환하기

CSS의 display 속성을 사용하면 요소의 본래 태생적 성질을 마음대로 변경할 수 있습니다:

<!-- 1. 기본 블록 요소: 한 줄 전체를 차지함 -->
<div style="background-color: skyblue;">Block 1</div>

<!-- 2. display: inline ➔ 글자 취급되므로 width: 100px이 무시됨! -->
<div style="display: inline; width: 100px; background-color: orange;">Inline 1</div>

<!-- 3. display: inline-block ➔ 옆으로 나란히 붙으면서도 width: 100px 크기가 온전히 적용됨! -->
<div style="display: inline-block; width: 100px; background-color: orange;">Inline 2</div>

<!-- 4. 다시 블록 요소: 새 줄에서 시작 -->
<div style="background-color: skyblue;">Block 2</div>

7. 실전 핵심 요약 치트시트

1. 선택자 우선순위 점수
   !important > inline style(1000점) > #id(100점) > .class/[attr]/:hover(10점) > tag(1점) > *(0점)

2. 결합자(관계) 기호 구분
   - div p   : 모든 자손
   - div > p : 바로 아래 자식
   - div + p : 바로 뒤에 붙은 인접 형제 1개
   - div ~ p : 뒤따라오는 모든 형제

3. 박스 크기 계산 표준 공식
   *, *::before, *::after { box-sizing: border-box; }
   (지정한 width 안에 padding과 border를 자동 포함시켜 레이아웃 깨짐 방지)

4. font 단축 속성 필수 순서
   font: [font-weight] [font-size] [font-family];
   (font-size와 font-family는 필수!)

5. display 3대장 핵심
   - block        : 한 줄 독점 (width/height 가능)
   - inline       : 나란히 배치 (width/height 불가)
   - inline-block : 나란히 배치 + width/height 크기 지정 가능

write31991 님의 블로그

FastAPI 4일차

⚡ FastAPI & asyncio 비동기 프로그래밍, 의존성 주입(DI) & 스레드 풀 완벽 정리 노트

목차

1. 자원 관리의 진화: try-finally에서 Context Manager까지

1-1. try-except-finally 예외 처리 3대 블록의 역할

1-2. DB 세션에서 finally가 필수적인 이유 (return보다 늦게 닫히는 문제 해결)

1-3. Context Manager (with SessionFactory() as session:)의 자동 뒷정리 마법

⚙ with 문 동작 메커니즘:

2. FastAPI 라우팅과 클라이언트 요청-응답 4단계 라이프사이클

2-1. 라우팅(Routing)의 본질: 도로 표지판과 HTTP Method + URL 매핑

2-2. 요청부터 응답까지의 4단계 라이프사이클 전체 흐름도

3. 의존성 주입 (Dependency Injection, DI): with 구문마저 지우는 비결

3-1. 의존성 주입(DI)이란 무엇인가? (자원 생성과 렌탈 개념)

3-2. yield 키워드를 활용한 세션 팩토리 제너레이터 (get_session())

3-3. Depends(get_session) 실전 적용과 엔드포인트 극단적 단순화

4. Background Tasks (백그라운드 태스크)

4-1. 요청-응답 이후 실행의 의미와 체감 응답 속도 극대화

4-2. 실전 코드: 회원가입 후 5초 이메일 발송 비동기 처리

4-3. Background Tasks 사용 시 주의점 (무거운 작업과 Celery/Redis 비교)

5. 비동기 프로그래밍 (asyncio)의 본질과 컴퓨터 구조

5-1. 동기(Synchronous)의 한계와 I/O Bound 작업의 비효율

5-2. 컴퓨터 구조로 보는 속도 차이 (빛처럼 빠른 CPU/RAM vs 목 빠지는 Disk/Network I/O)

5-3. 비동기의 일상 비유: 라면 끓이기와 주문 접수

5-4. 파이썬 표준 라이브러리 asyncio

6. 코루틴(Coroutine)과 협력적 멀티태스킹

6-1. 코루틴의 정의: "너 한 번, 나 한 번" 협력(co-routine)하는 함수

6-2. 코루틴 함수(async def) vs 코루틴 객체 (왜 바로 실행되지 않는가?)

6-3. asyncio.run()과 asyncio.gather()를 통한 동시 실행 패키징

6-4. 동기 vs 비동기 실행 시간 벤치마크 (4초 ➔ 2초 단축)

7. await 키워드와 양보(Yield Control)의 미학

7-1. await: "여기서 잠깐 멈추고 제어권을 넘겨라!"

7-2. ⭐ await를 사용하는 2가지 절대 조건

7-3. 어떤 작업이 Awaitable한가? (판단 3단계 공식)

7-4. [실습] 코루틴 체이닝 퍼즐 (출력 순서 제어 완성)

풀이 분석 및 완성 코드:

8. 이벤트 루프(Event Loop)와 블로킹(Blocking) 금지의 법칙

8-1. 이벤트 루프란? ("세 쌍둥이 밥 먹이기" 완벽 비유)

8-2. 절대 규칙: 이벤트 루프를 블로킹하면 서버 전체가 얼어붙는다!

9. FastAPI 내부 동작의 비밀: 동기 함수(def)와 스레드 풀(Thread Pool)

9-1. "FastAPI는 비동기인데 왜 우린 지금까지 def 일반 함수를 썼을까?"

9-2. 스레드 풀(Thread Pool)의 대리 실행 메커니즘 (run_endpoint_function)

9-3. 스레드 풀 크기 조절과 Lifespan 컨텍스트 매니저 (기본 40개 ➔ 200개 상향)

10. 실전 핵심 요약 치트시트

FastAPI 3일차

️ FastAPI & SQLAlchemy ORM 데이터베이스 연동과 실전 영속 CRUD 완벽 정리 노트

목차

1. 왜 데이터베이스(DB)가 필요한가? (메모리 CRUD의 한계)

1-1. 메모리(list) 기반 CRUD의 2대 치명적 한계

1-2. 데이터베이스의 3대 핵심 역할 (영속성, 동시성, 신뢰성)

2. SQL 직접 작성(Raw SQL)의 한계와 ORM의 탄생

2-1. 클라이언트 - FastAPI - SQLite 전체 아키텍처

2-2. "SQL을 코드 안에 직접 적었을 때"의 2대 문제점

2-3. ORM(Object-Relational Mapping)이란?

2-4. ORM 3대 매핑 공식 (테이블=클래스, 행=인스턴스, 열=속성)

3. SQLAlchemy: Python 표준 ORM 라이브러리

3-1. SQLAlchemy를 사용하는 이유와 프레임워크별 ORM 비교

Python 웹 프레임워크별 ORM 스타일 비교:

3-2. 패키지 설치 (pip install SQLAlchemy)

4. SQLAlchemy 기초 3대 요소 (Engine, Session, Model)

4-1. Engine (엔진): DB 물리적 연결의 관문

4-2. Session (세션): 작업 단위와 트랜잭션 관리

4-3. Model (모델): 파이썬 클래스로 표현한 테이블

4-4. 엔진을 통한 데이터베이스 요청/실행 전체 흐름

5. SQLAlchemy 2.0 모던 모델 정의와 테이블 자동 생성

5-1. DeclarativeBase를 상속한 Base 선언

5-2. Mapped와 mapped_column을 활용한 Item 모델 정의

5-3. 왜 DB 컬럼의 타입을 고정해야 하는가? (일관성 & 저장 효율성)

5-4. Base.metadata.create_all(bind=engine) 테이블 자동 생성

6. 세션의 라이프사이클과 데이터 저장 (Staging ➔ Commit)

6-1. 객체 생성 vs session.add() (Staging 상태의 의미)

6-2. session.commit()과 session.close()

6-3. 다중 데이터 일괄 등록과 RETURNING id의 원리

7. SQLAlchemy 데이터 조회(SELECT)와 Result 객체의 비밀

7-1. select() 쿼리문 빌드와 session.execute()

7-2. 왜 print(result) 해도 데이터가 안 보일까? (Iterator/Result 커서)

7-3. 3대 데이터 추출 메서드 비교 (mappings, all, scalars)

7-4. 치명적 주의점: Result 커서의 일회성 소모(Consumption) 특성

해결책:

7-5. 특정 데이터 단일 조회: .where()와 session.scalar()