feat: Wiki 지식 자산 업데이트 - UX Scenarios, Frontend, Game Design, Topics 추가 [2026-05-08]
This commit is contained in:
@@ -1,13 +1,26 @@
|
||||
---
|
||||
category: Unified
|
||||
id: wiki-2026-0508-외부-라이브러리-api-설계
|
||||
title: 외부 라이브러리 API 설계
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
canonical_id: self
|
||||
aliases: []
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.92
|
||||
tags: [auto-consolidated, technical-documentation]
|
||||
title: [[API 응답 및 에러 핸들링 아키텍처|API 응답 및 에러 핸들링 아키텍처]]
|
||||
last_updated: 2026-05-02
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-08
|
||||
github_commit: pending
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
---
|
||||
|
||||
# [[API 응답 및 에러 핸들링 아키텍처|API 응답 및 에러 핸들링 아키텍처]]
|
||||
|
||||
## 📌 Brief Summary
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> API 응답 및 에러 핸들링 아키텍처는 시스템 내에서 발생하는 에러를 예상 가능한 것과 그렇지 않은 것으로 구분하고, 이를 클라이언트에게 일관되고 예측 가능한 형태로 전달하기 위한 설계 방식입니다. 주로 '예외 던지기(throw exceptions)' 대신 명시적인 결과 객체(Result 타입)나 식별 가능한 유니온([[Discriminated Unions|Discriminated Unions]])을 활용하여 타입 안전성을 확보하고, 컨트롤러 계층에서 응답의 제어 흐름을 명확히 관리하는 것을 목표로 합니다.
|
||||
|
||||
---
|
||||
@@ -34,7 +47,7 @@ last_updated: 2026-05-02
|
||||
|
||||
> 웹 브라우저 그래픽 API 호환성은 [[WebGL|WebGL]] 및 [[WebGPU|WebGPU]]와 같은 웹 기반 3D 그래픽 기술이 다양한 웹 브라우저, 운영 체제, 하드웨어 환경에서 일관되게 작동하고 최적화되는 정도를 의미합니다 [1-3]. WebGL은 폭넓게 지원되지만 OS별 그래픽 계층 변환 오버헤드와 브라우저 보안 제약의 영향을 크게 받으며, 차세대 표준인 WebGPU는 최신 하드웨어 기술을 활용하나 브라우저별 파편화가 존재하고 WebGL과 하위 호환되지 않습니다 [4-6]. 따라서 성능 최적화를 위해서는 대상 하드웨어 아키텍처와 브라우저별 API 지원 범위를 고려한 플랫폼 교차적 설계가 필수적입니다 [7, 8].
|
||||
|
||||
## 📖 Core Content
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
* **에러의 분류와 처리 철학**
|
||||
에러는 애플리케이션 관점에서 '예상 가능한 에러(Expected errors)'와 '예상치 못한 에러(Unexpected errors/Defects)'로 나뉩니다 [1, 2]. 400 Bad Request나 504 Gateway Timeout 같은 예상 가능한 에러는 예외(Exception)로 던지기보다는 명시적인 에러 타입으로 반환하여 시스템이 복구 가능하도록 제어해야 합니다 [1].
|
||||
* **Result 패턴을 통한 명시적 에러 반환**
|
||||
@@ -104,7 +117,7 @@ last_updated: 2026-05-02
|
||||
- **WebGPU의 브라우저 지원 파편화 및 비호환성:** 차세대 API인 WebGPU는 [[Vulkan|Vulkan]], [[Metal|Metal]], Direct3D 12 등의 네이티브 GPU API를 공통된 구조로 브라우저에 제공하지만, 기존 WebGL과는 하위 호환성을 전혀 지원하지 않아 프레임워크 사용자들에게 "업그레이드 충격"을 유발합니다 [5, 6, 24]. 2025년 및 2026년 기준, Chrome과 Edge는 데스크톱에서 안정적으로 지원되는 반면, Safari는 macOS 26 및 iOS 26부터 기본 지원이 도입되었고, Firefox는 Windows(버전 141) 등 특정 플랫폼에서만 작동하거나 불안정한 오류가 보고되는 등 브라우저와 모바일 OS별 지원 수준에 아직 큰 차이가 존재합니다 [3, 25, 26].
|
||||
- **크로스 플랫폼 하드웨어 스케줄링의 제약:** WebGPU는 범용 컴퓨팅([[Compute Shader|Compute Shader]]s)을 웹에 도입했으나, 크로스 플랫폼 호환성 유지를 위해 특정 하드웨어 스케줄링 순서나 세밀한 전역 원자성(Global atomics)을 보장하지 않습니다 [7, 27]. 따라서 CUDA 등 기존 네이티브 환경에서 사용되던 동기화 방식(예: 작업 그룹 간 Spin-wait)을 WebGPU에 그대로 이식할 경우, Apple M1과 같은 특정 칩셋 환경에서 무한 대기(Busy-wait)를 유발하여 심각한 성능 저하나 실행 실패를 일으킬 수 있습니다 [7, 28].
|
||||
|
||||
## ⚖️ Trade-offs & Caveats
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
|
||||
- **정책 변화:** Programming & Language 분야의 자동 자산화 수행.
|
||||
|
||||
@@ -138,7 +151,7 @@ last_updated: 2026-05-02
|
||||
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
|
||||
- **정책 변화:** Graphics & Performance 분야의 자동 자산화 수행.
|
||||
|
||||
## 🔗 Knowledge Connections
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- **Related Topics:** [[Result Type|Result Type]], [[Discriminated Unions|Discriminated Unions]], Exception Handling
|
||||
- **Projects/Contexts:** [[TypeScript API Development|TypeScript API Development]], [[Server Architecture|Server Architecture]]
|
||||
- **Contradictions/Notes:** 전역 예외 처리기(Global Exception Handler)를 두고 컨트롤러에서 예외를 발생시키는 방식이 코드가 깔끔해진다고 선호하는 개발자들도 있지만, Result 패턴을 지지하는 개발자들은 예외를 던지는 방식이 제어 흐름을 끊고 타입 시스템으로 에러를 파악할 수 없게 하므로 예상 가능한 에러는 명시적인 타입으로 반환해야 한다고 반대합니다 [7, 14-16].
|
||||
@@ -213,3 +226,52 @@ last_updated: 2026-05-02
|
||||
*Last updated: 2026-04-19*
|
||||
|
||||
---
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
Reference in New Issue
Block a user