---
id: platform-web-development
title: "웹 개발 가이드"
category: "Platform_Engineering"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["web development", "웹 개발", "frontend", "SPA", "프런트엔드 아키텍처"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.86
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["platform", "web", "frontend", "guide", "platform-independent"]
raw_sources: ["일반 웹 공학 지식"]
applied_in: []
github_commit: ""
---

# [[웹 개발 가이드]]

## 🎯 한 줄 통찰 (One-line insight)
웹 개발의 본질은 프레임워크가 아니라 "**상태·비동기·데이터 흐름·에러·계층 분리**" 라는 반복 문제를 푸는 것 — 도구는 바뀌어도 원리는 [[패턴 카탈로그 인덱스]] 의 cross-cutting 패턴으로 수렴한다.

## 🧠 핵심 개념 (Core concepts)
선언형 UI, 컴포넌트, 단방향 데이터, 서버/클라 상태 분리, 라우팅, 번들링/코드 분할.

## 📖 세부 내용 (Details · 12-field)
- **Problem:** 다양한 디바이스/브라우저에서 반응적이고 유지보수 가능한 UI 와 데이터 동기화.
- **Recommended Architecture:** 컴포넌트 기반 + 단방향 데이터 + 서버 상태 라이브러리(react-query) + 기능별 폴더(feature-sliced). 무거운 로직은 도메인 계층으로 분리.
- **Folder Structure:** `src/{features/<feature>/{ui,api,model}, shared/{ui,lib,api}, app/(라우팅·프로바이더)}`. 기능 슬라이스 + 공유 계층.
- **Core Components:** 라우터, 데이터 페칭 계층([[API Client Pattern]]), 상태 store([[State Management Pattern]]/[[React State Pattern]]), 디자인 시스템, 에러 바운더리.
- **State Management:** 지역=useState, 서버=쿼리 캐시, 공유 도메인=가벼운 store, 공유 가능 상태=URL. (SSOT·단방향)
- **Error Handling:** 에러 바운더리(렌더 에러), 쿼리 에러/리트라이, 사용자 친화 메시지([[Error Handling Pattern]]).
- **Testing Strategy:** 단위(순수 로직)·컴포넌트(Testing Library)·E2E(Playwright). 피라미드(단위 多, E2E 少).
- **Scaling Strategy:** 코드 분할/지연 로드, 가상화([[Infinite Scroll Pattern]]), CDN/캐시, SSR/SSG(초기 로드·SEO), 이미지 최적화.
- **Common Mistakes:** 서버 데이터를 로컬 상태에 복사(stale), 전역 store 남용(리렌더), prop drilling, 거대 컴포넌트, 무분별 useEffect.
- **Refactoring Patterns:** 거대 컴포넌트 분해, 로직→커스텀 훅 추출, 페칭→쿼리 계층 이동, prop drilling→context/store.
- **Real-world Tradeoffs:** SSR(성능·SEO ↔ 복잡도), 전역 상태(편의 ↔ 결합), 마이크로프런트엔드(독립 배포 ↔ 운영 부담).
- **Design Heuristics:** "상태는 가장 낮은 곳, 공유되면 올린다", "서버 상태와 UI 상태 분리", "파생은 계산", "경계에서 검증".

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
프레임워크(React/Vue/Svelte)는 수단 — 채용/생태계로 고르되, 위 원리는 공통. "최신 프레임워크" 추종보다 상태/데이터 흐름 설계가 품질을 가른다.

## 🛠️ 적용 사례 (Applied in summary)
일반 SPA/웹앱. AstraAI 웹뷰 UI 도 상태/메시지 원리는 동일.

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[플랫폼 개발 가이드 인덱스]]
- **관련 개념:** [[State Management Pattern]], [[React State Pattern]], [[API Client Pattern]], [[JWT Authentication Pattern]], [[Infinite Scroll Pattern]]
- **참조 맥락:** 작은 모델이 웹 프로젝트를 설계/구현할 때 상위 가이드로 참조.

## 📚 출처 (Sources)
- [S1] 일반 웹/프런트엔드 공학 지식

## 📝 변경 이력 (Change history)
- 2026-06-13: 플랫폼 독립 웹 개발 가이드 초안.