refactor: 문서 개선 중

2026-09-21 14:30:55 +09:00
parent c93cdea150
commit 805a18f486
1497 changed files with 525837 additions and 59152 deletions
@@ -0,0 +1,45 @@
+---
+kind: PROJECT_DECISION
+slug: an-unrecognised-sqlstate-is-not-guessed
+title: 인식하지 못한 SQLSTATE 는 추측하지 않는다
+topic: http-failure-classification
+topicName: HTTP 실패 분류와 재시도 안전성
+project: clean-architecture-backend-template
+status: 게시 전
+decisionStatus: ADOPTED
+source:
+  - final/document.md#a05
+  - final/document.md#10-2
+  - final/document.md#5-1
+  - final/document.md#a05 §7.1
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+---
+
+# 인식하지 못한 SQLSTATE 는 추측하지 않는다
+
+매트릭스에 등록되지 않은 SQLSTATE를 이름이나 class prefix가 비슷하다는 이유로 기존 failure category에 넣지 않는다.
+
+## 근거
+
+- **실패 어휘 세 층과 그 사이를 잇는 SQLState 매트릭스**
+  공급자 오류와 애플리케이션 범주 사이에 명시적 번역 계층을 둔다.
+- **같은 SQLState 를 둘이 등록하면 값이 같아도 시작을 실패시킨다**
+  매핑의 값과 소유권을 둘 다 명시적으로 유지한다.
+
+## 결정문
+
+등록되지 않은 SQLSTATE는 기존 category로 추측해 분류하지 않는다. 정책에 필요한 상태라면 매트릭스에 명시적으로 등록하고 해당 매핑의 소유자를 정한다.
+
+## 판단 이유
+
+SQLSTATE의 접두사나 주변 예외가 비슷해도 operation semantics와 retry 안전성이 같다는 보장은 없다. 추측 분류는 새로운 데이터베이스 상태를 기존 정책에 조용히 편입시킨다.
+
+명시 등록을 요구하면 새 상태를 지원하는 순간 코드 리뷰와 테스트에 변경점이 생긴다. 알 수 없는 값을 아는 값처럼 다루지 않는 쪽을 선택한다.
+
+## 영향
+
+감수하는 것 : 새로운 SQLSTATE가 나타나면 매핑을 추가하기 전까지 자동 복구 정책을 적용하지 못할 수 있다.
+
+얻는 것 : 미지의 오류가 retryable 또는 permanent로 조용히 오분류되지 않는다.
+
+얻는 것 : 매핑 추가 시 어떤 모듈이 그 의미를 소유하는지 함께 검토할 수 있다.
@@ -21,15 +21,15 @@ source:

 # 재시도 안전성은 증거에 기반해 판정한다

-재시도 여부는 무엇이 실패했는지가 아니라 무엇이 관측됐는지로 판정한다. 요청이 서버에 닿지 않았으면 재시도는 첫 시도이고 닿았을지도 모르면 중복인데, 예외 타입은 그 구분을 담지 않는다.
+전송 여부와 commit ambiguity는 관측 evidence로 판정한다. 다만 최종 재시도 eligibility는 그 evidence만으로 정하지 않고 failure category, operation의 멱등성·의미, deadline·retry budget·policy를 함께 본다.

 ## 결정문

-재시도 여부는 무엇이 실패했는지가 아니라 무엇이 관측됐는지로 판정한다.
+전송 여부 판정은 evidence에 기반하고, 최종 재시도 여부는 evidence와 failure category, operation semantics, retry budget을 함께 보고 정한다.

 ## 판단 이유

-같은 예외라도 요청이 서버에 닿았는지에 따라 재시도의 의미가 완전히 달라진다. 닿지 않았으면 재시도는 첫 시도이고, 닿았을지도 모르면 재시도는 중복이다. 예외 타입은 그 구분을 담지 않으므로, 관측된 진행 정도를 별도의 값으로 기록하고 그것을 판정 입력으로 삼는다.
+같은 예외라도 요청이 서버에 닿았는지에 따라 재시도의 의미가 달라진다. 닿지 않았다는 evidence가 있으면 transmission ambiguity가 줄고, 닿았을 가능성이 있으면 중복 실행 위험을 고려해야 한다. 예외 타입만으로는 그 구분이 부족하므로 관측된 진행 정도를 별도의 값으로 기록한다. 그 값은 최종 결정의 한 축이며 failure category와 멱등성·operation semantics, 남은 deadline과 retry budget도 함께 입력으로 들어간다.

 이 판정을 보수적으로 유지하는 것이 핵심이다. 전송되지 않았다는 판정은 단계 실패가 그것을 증명할 때만 쓰고, 일반적인 엔진 입출력 실패는 결코 그 판정으로 승격되지 않는다. 모호한 것을 전송되지 않음으로 추측하는 것이 타임아웃을 중복 결제로 바꾸는 경로다.

@@ -49,7 +49,7 @@ source:

 같은 실패에 대해 Apache JDK Reactor Netty Jetty 가 동일한 재시도와 관측 동작을 낸다.

-재시도 정책이 HTTP 메서드 같은 간접 신호에 기대지 않는다.
+재시도 정책이 HTTP 메서드 하나 같은 간접 신호에만 기대지 않고 전송 evidence와 operation semantics를 함께 사용한다.

 ## 근거