[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -1,100 +1,342 @@
|
||||
---
|
||||
id: wiki-2026-0508-api-응답-모델링-및-상태-머신-state-machine
|
||||
title: API 응답 모델링 및 상태 머신(State Machine) 설계
|
||||
title: API Response Modeling + State Machine
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [P-Reinforce-AUTO-9FD5CF]
|
||||
aliases: [State Machine design, XState, FSM, async state]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.9
|
||||
tags: [auto-reinforced]
|
||||
source_trust_level: B
|
||||
confidence_score: 0.85
|
||||
verification_status: applied
|
||||
tags: [state-machine, xstate, fsm, typescript, async-state, discriminated-union]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-04-20
|
||||
github_commit: "[P-Reinforce] Continuous Worker - API 응답 모델링 및 상태 머신([[State|State]] Machine) 설계"
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
last_reinforced: 2026-05-09
|
||||
github_commit: pending
|
||||
---
|
||||
|
||||
# [[API 응답 모델링 및 상태 머신(State Machine) 설계|API 응답 모델링 및 상태 머신(State Machine) 설계]]
|
||||
# API Response Modeling + State Machine
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> TypeScript에서 API 응답과 상태 머신을 설계할 때는 식별 가능한 유니온([[Discriminated Unions|Discriminated Unions]]) 패턴이 핵심적으로 활용된다 [1, 2]. 이 패턴은 공통 판별자(Discriminant) 속성을 통해 데이터의 다양한 상태를 구분하며, 유효하지 않은 상태가 코드에 표현되는 것을 원천적으로 차단한다 [1, 3, 4]. 결과적으로 네트워크 요청의 다양한 결과나 복잡한 UI 상태 전이를 컴파일 단계에서 안전하게 모델링하고 관리할 수 있도록 보장한다 [2, 5, 6].
|
||||
## 📌 한 줄 통찰
|
||||
> **Discriminated union 의 baseline + state machine (XState) 의 complex flow**. 매 invalid state + invalid transition 의 prevent. 매 actor model 의 modern.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
- **상태 머신(State Machine) 패턴 모델링**:
|
||||
애플리케이션 내의 복잡한 상태(예: `Idle`, `Fetching`, `Success`, `Failure`, `Retry` 등)는 식별 가능한 유니온을 통해 상태 머신으로 완벽하게 모델링할 수 있다 [2]. 이 방식은 폼 제출 워크플로우(예: `validating`, `submitting`, `success`, `error`)나 비동기 작업 패턴을 명확히 정의하는 데 뛰어나며, 호환되지 않는 잘못된 상태들의 조합이 발생하는 것을 원천적으로 불가능(Impossible)하게 만든다 [3, 5].
|
||||
## 📖 핵심
|
||||
|
||||
- **API 응답 데이터 구조화**:
|
||||
API 응답은 성공, 실패, 대기 등 여러 형태를 취할 수 있으므로 식별 가능한 유니온을 통해 구조화하는 것이 효과적이다 [2]. 예를 들어, `NetworkState`라는 유니온 타입 내에 `NetworkLoadingState`, `NetworkFailedState`, `NetworkSuccessState`를 정의하고 `state`라는 리터럴 필드를 공유 판별자로 설계할 수 있다 [6]. 컴파일러는 이 판별자를 바탕으로 `code`나 `response`와 같은 고유 페이로드(Payload) 속성에 안전하게 접근하도록 타입을 좁혀준다(Narrowing) [6, 7].
|
||||
### 매 spectrum
|
||||
|
||||
- **완전성 검사(Exhaustiveness Checking) 적용**:
|
||||
상태 머신과 API 응답을 분기 처리할 때 `switch` 문과 `never` 타입을 활용하면, 개발자가 실수로 누락한 상태나 새롭게 추가된 API 응답 형태가 있을 경우 TypeScript 컴파일러가 에러를 발생시킨다 [3, 7-9]. 이는 모든 분기 및 상태가 빠짐없이 처리되도록 강제하는 강력한 안전장치가 되어 런타임 버그를 방지한다 [10-12].
|
||||
#### Simple state (1-3 state)
|
||||
- Discriminated union 충분.
|
||||
- React useState.
|
||||
|
||||
- **외부 데이터 런타임 검증과의 결합**:
|
||||
외부 API에서 전달받은 응답은 TypeScript의 컴파일 타임 시스템만으로는 런타임에서의 완벽한 안전성을 보장할 수 없다 [12, 13]. 따라서 Zod와 같은 런타임 검증 라이브러리와 식별 가능한 유니온을 결합하여 사용하면, 예기치 않은 형태의 API 데이터로 인해 상태 머신이 망가지는 것을 방어할 수 있다 [12, 13].
|
||||
#### Medium (4-6 state, parallel)
|
||||
- useReducer / Zustand.
|
||||
- Manual transition.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
|
||||
- **정책 변화:** AI 분야의 자동 자산화 수행.
|
||||
#### Complex (10+ state, hierarchy)
|
||||
- XState / Robot.
|
||||
- Visual editor.
|
||||
- Statecharts.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- **Related Topics:** 식별 가능한 유니온(Discriminated Unions), [[완전성 검사(Exhaustiveness Checking)|완전성 검사(Exhaustiveness Checking)]], [[타입 좁히기(Type Narrowing)|타입 좁히기(Type Narrowing)]]
|
||||
- **Projects/Contexts:** 비동기 데이터 패칭(Async Data Fetching), 상태 머신 기반 UI 폼 및 라우터 관리
|
||||
- **Contradictions/Notes:** API 응답 데이터를 변환할 때 타입 캐스팅(`as`)을 사용하면 잉여 속성이 존재하거나 형태가 잘못되어도 컴파일러가 이를 조용히 허용하여 안전성이 떨어질 수 있다. 따라서 엄격한 타입 계약을 강제하기 위해서는 `as` 대신 `satisfies` 키워드를 활용하는 것이 권장된다 [14, 15].
|
||||
### 매 statechart concept (Harel)
|
||||
|
||||
---
|
||||
*Last updated: 2026-04-18*
|
||||
|
||||
---
|
||||
|
||||
## 🤖 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
|
||||
#### Hierarchical state
|
||||
```
|
||||
Authenticated:
|
||||
- Browsing
|
||||
- Editing
|
||||
- Submitting
|
||||
Unauthenticated:
|
||||
- LoggingIn
|
||||
- SigningUp
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
→ 매 sub-state 의 share parent transition.
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
#### Parallel state
|
||||
```
|
||||
[Editing] || [Saving]
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
→ 매 simultaneously.
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
#### History state
|
||||
- 매 last state 의 remember.
|
||||
- 매 modal close → previous state.
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
#### Guard
|
||||
- 매 transition 의 condition.
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
#### Action
|
||||
- 매 transition 의 side effect.
|
||||
|
||||
### XState (TS)
|
||||
|
||||
#### Machine definition
|
||||
```ts
|
||||
import { createMachine, assign } from 'xstate';
|
||||
|
||||
const fetchMachine = createMachine({
|
||||
id: 'fetch',
|
||||
initial: 'idle',
|
||||
context: { data: null, error: null },
|
||||
states: {
|
||||
idle: {
|
||||
on: { FETCH: 'loading' }
|
||||
},
|
||||
loading: {
|
||||
invoke: {
|
||||
src: 'fetchData',
|
||||
onDone: { target: 'success', actions: assign({ data: ({ event }) => event.output }) },
|
||||
onError: { target: 'error', actions: assign({ error: ({ event }) => event.error }) },
|
||||
}
|
||||
},
|
||||
success: {
|
||||
on: { REFETCH: 'loading' }
|
||||
},
|
||||
error: {
|
||||
on: { RETRY: 'loading' }
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
#### Usage (React)
|
||||
```tsx
|
||||
import { useMachine } from '@xstate/react';
|
||||
|
||||
function Component() {
|
||||
const [state, send] = useMachine(fetchMachine, {
|
||||
services: { fetchData: () => api.fetch() }
|
||||
});
|
||||
|
||||
if (state.matches('loading')) return <Spinner />;
|
||||
if (state.matches('error')) return <Error msg={state.context.error} />;
|
||||
if (state.matches('success')) return <Data data={state.context.data} />;
|
||||
return <button onClick={() => send({ type: 'FETCH' })}>Load</button>;
|
||||
}
|
||||
```
|
||||
|
||||
### 매 advantage
|
||||
|
||||
#### Visual
|
||||
- 매 state diagram 의 generate.
|
||||
- 매 stakeholder 의 communicate.
|
||||
|
||||
#### Test
|
||||
- 매 state + transition 의 explicit.
|
||||
- 매 path 의 enumerate.
|
||||
|
||||
#### Documentation
|
||||
- 매 code 의 self-documenting.
|
||||
|
||||
#### Refactor safety
|
||||
- 매 invalid transition 의 compile fail.
|
||||
|
||||
### 매 limit
|
||||
|
||||
#### Learning curve
|
||||
- 매 statechart 의 unfamiliar.
|
||||
- 매 boilerplate.
|
||||
|
||||
#### Over-engineering
|
||||
- 매 simple state 의 useState 의 enough.
|
||||
|
||||
#### XState 의 specific syntax
|
||||
- 매 vendor lock-in.
|
||||
|
||||
### Alternative
|
||||
|
||||
#### Robot
|
||||
- 매 lighter weight.
|
||||
- 매 simpler API.
|
||||
|
||||
#### useReducer (React)
|
||||
- 매 native.
|
||||
- 매 simple state machine.
|
||||
|
||||
#### Zustand + slice
|
||||
- 매 store-based.
|
||||
- 매 manual transition.
|
||||
|
||||
### 매 use case
|
||||
|
||||
#### Complex form
|
||||
- 매 multi-step.
|
||||
- 매 validation per step.
|
||||
- 매 conditional branching.
|
||||
|
||||
#### Authentication flow
|
||||
- 매 login → 2FA → success.
|
||||
- 매 multiple path.
|
||||
|
||||
#### Game state
|
||||
- 매 menu / playing / paused / game-over.
|
||||
|
||||
#### Real-time (chat, video call)
|
||||
- 매 connecting / connected / disconnected / reconnecting.
|
||||
|
||||
#### Workflow
|
||||
- 매 multi-stage approval.
|
||||
|
||||
## 💻 Code
|
||||
|
||||
### Discriminated union (simple)
|
||||
```ts
|
||||
type State =
|
||||
| { status: 'idle' }
|
||||
| { status: 'loading' }
|
||||
| { status: 'success'; data: User }
|
||||
| { status: 'error'; message: string };
|
||||
|
||||
function reducer(state: State, action: Action): State {
|
||||
switch (action.type) {
|
||||
case 'FETCH':
|
||||
return { status: 'loading' };
|
||||
case 'SUCCESS':
|
||||
return { status: 'success', data: action.payload };
|
||||
case 'ERROR':
|
||||
return { status: 'error', message: action.error };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### useReducer
|
||||
```tsx
|
||||
function Component() {
|
||||
const [state, dispatch] = useReducer(reducer, { status: 'idle' });
|
||||
|
||||
useEffect(() => {
|
||||
dispatch({ type: 'FETCH' });
|
||||
api.fetch()
|
||||
.then(data => dispatch({ type: 'SUCCESS', payload: data }))
|
||||
.catch(e => dispatch({ type: 'ERROR', error: e.message }));
|
||||
}, []);
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### XState (full)
|
||||
```ts
|
||||
import { setup, createMachine } from 'xstate';
|
||||
|
||||
const machine = setup({
|
||||
types: { context: {}, events: {} as { type: 'NEXT' } | { type: 'PREV' } },
|
||||
guards: {
|
||||
canProceed: ({ context }) => context.formValid === true,
|
||||
},
|
||||
}).createMachine({
|
||||
id: 'wizard',
|
||||
initial: 'step1',
|
||||
context: { formValid: false },
|
||||
states: {
|
||||
step1: {
|
||||
on: { NEXT: { target: 'step2', guard: 'canProceed' } }
|
||||
},
|
||||
step2: {
|
||||
on: { NEXT: 'step3', PREV: 'step1' }
|
||||
},
|
||||
step3: {
|
||||
on: { PREV: 'step2', SUBMIT: 'submitting' }
|
||||
},
|
||||
submitting: {
|
||||
invoke: {
|
||||
src: 'submitForm',
|
||||
onDone: 'success',
|
||||
onError: 'step3',
|
||||
}
|
||||
},
|
||||
success: { type: 'final' },
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Hierarchical
|
||||
```ts
|
||||
const auth = createMachine({
|
||||
id: 'auth',
|
||||
initial: 'unauthenticated',
|
||||
states: {
|
||||
unauthenticated: {
|
||||
initial: 'login',
|
||||
states: {
|
||||
login: { on: { SIGNUP: 'signup' } },
|
||||
signup: { on: { LOGIN: 'login' } },
|
||||
},
|
||||
on: { AUTHENTICATED: 'authenticated' }
|
||||
},
|
||||
authenticated: {
|
||||
initial: 'browsing',
|
||||
states: {
|
||||
browsing: { on: { EDIT: 'editing' } },
|
||||
editing: { on: { SAVE: 'saving' } },
|
||||
saving: { on: { DONE: 'browsing' } },
|
||||
},
|
||||
on: { LOGOUT: 'unauthenticated' }
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Visual (XState VS Code extension)
|
||||
- 매 .machine.ts file 의 visual.
|
||||
- 매 state + transition 의 graphical.
|
||||
|
||||
### Testing
|
||||
```ts
|
||||
import { createActor } from 'xstate';
|
||||
|
||||
test('login flow', () => {
|
||||
const actor = createActor(authMachine).start();
|
||||
|
||||
actor.send({ type: 'SIGNUP' });
|
||||
expect(actor.getSnapshot().value).toBe('unauthenticated.signup');
|
||||
|
||||
actor.send({ type: 'LOGIN' });
|
||||
expect(actor.getSnapshot().value).toBe('unauthenticated.login');
|
||||
|
||||
actor.send({ type: 'AUTHENTICATED' });
|
||||
expect(actor.getSnapshot().value).toBe('authenticated.browsing');
|
||||
});
|
||||
```
|
||||
|
||||
## 🤔 결정 기준
|
||||
|
||||
| Complexity | Tool |
|
||||
|---|---|
|
||||
| < 4 state | useState + discriminated union |
|
||||
| 4-8 simple | useReducer |
|
||||
| 4-8 complex | XState (lite) |
|
||||
| 10+ hierarchical | XState (full) |
|
||||
| Cross-component | XState actor |
|
||||
| Workflow / multi-step | XState 추천 |
|
||||
|
||||
**기본값**: Discriminated union + useReducer. 매 complex flow 의 XState.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[State-Management]] · [[API-Design]]
|
||||
- 변형: [[State Modeling and API Responses]] · [[XState]] · [[Robot]]
|
||||
- 응용: [[Statechart-Harel]] · [[Actor-Model]] · [[FSM]]
|
||||
- Adjacent: [[Discriminated-Union]] · [[useReducer]] · [[Zustand]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: 매 complex async flow. 매 multi-step form / wizard. 매 game state.
|
||||
**언제 X**: 매 simple toggle. 매 trivial component state.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **Boolean explosion** (isLoading, isError, isSuccess separate): invalid combination.
|
||||
- **No state machine + complex flow**: bug 폭발.
|
||||
- **State machine + simple state**: over-engineer.
|
||||
- **No exhaustive check**: missed transition.
|
||||
- **Mixed concerns (UI + business)**: 매 separate.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (XState docs, Statecharts.dev).
|
||||
- 신뢰도 B.
|
||||
- Related: [[State Modeling and API Responses]] (closely related).
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-09 | Cleanup — XState code + statechart + 결정 기준 |
|
||||
|
||||
Reference in New Issue
Block a user