From 3098ffb2e1fc900ff0dce4072bb18b68d871423d Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Tue, 2 Dec 2025 02:18:53 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20HTTP=20=EC=83=81=ED=83=9C=20=EC=BD=94?= =?UTF-8?q?=EB=93=9C=EB=B3=84=20=EC=97=90=EB=9F=AC=20=EC=B2=98=EB=A6=AC=20?= =?UTF-8?q?=EA=B7=9C=EC=B9=99=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 404/504는 재시도 가능 에러로 처리 - 500은 즉시 중단 및 명확한 사용자 메시지 제공 - 동일 템플릿 메시지 사용 금지 원칙 추가 - HTTP 레벨 에러와 사용자 메시지 분리 원칙 명시 --- .../313_React_구조_원칙.md | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/book/300_architecture/313_React_구조_원칙.md b/book/300_architecture/313_React_구조_원칙.md index 23460fd..4d1b7d3 100644 --- a/book/300_architecture/313_React_구조_원칙.md +++ b/book/300_architecture/313_React_구조_원칙.md @@ -122,12 +122,31 @@ src/ ## 9. 에러 처리 일관성 원칙 -**핵심 원칙**: 환경별 일관된 에러 로깅 +**핵심 원칙**: 환경별 일관된 에러 로깅 및 HTTP 상태 코드별 처리 - `console.error` 대신 환경별 로깅 유틸리티 사용 - 프로덕션 환경에서도 에러 로그 기록 - 로깅 유틸리티는 개발/프로덕션 환경에 따라 적절히 처리 +### HTTP 상태 코드별 처리 규칙 + +**에러 메시지 디자인 원칙**: HTTP 레벨 에러와 사용자 메시지를 분리 + +- **404 Not Found**: 리소스가 아직 생성되지 않음 → 재시도/폴링 계속 (예: 평가 진행 중) +- **504 Gateway Timeout**: 게이트웨이 타임아웃 → 사용자에게 "분석 시간이 초과되었습니다" 또는 재시도 안내 +- **502 Bad Gateway**: 백엔드 연결 실패 → 사용자에게 "서버 연결 오류" 안내, 재시도 제안 +- **500 Internal Server Error**: 서버 오류 → 즉시 중단, 사용자에게 "서버 오류가 발생했습니다. 잠시 후 다시 시도해주세요" 안내 + +**금지 사항**: +- ❌ 모든 에러에 동일한 템플릿 메시지 사용 (예: "(템플릿) 평가 처리 중 오류가 발생했습니다") +- ❌ HTTP 상태 코드를 사용자에게 직접 노출 +- ❌ 에러 원인 파악 없이 일반적인 메시지만 표시 + +**권장 사항**: +- 에러 유형별로 명확한 사용자 메시지 제공 +- 원인 파악은 HTTP 상태 코드와 백엔드 로그로 교차 검증 +- 폴링/재시도 가능한 에러(404, 504)와 치명적 에러(500)를 구분하여 처리 + ## 10. 데이터 검증 원칙 **핵심 원칙**: 백엔드 응답 구조 검증 및 폴백 처리