에러 처리

Akan의 에러 처리는 단순한 규칙 하나로 시작합니다. 서버 코드는 타입 안전한 dictionary key를 던지고, 클라이언트는 그 key를 번역해서 보여줍니다.

사용자에게 보여줄 에러는 module dictionary에 선언합니다.
비즈니스 규칙이 실패하면 document나 service 코드에서 `Err`를 던집니다.
fetch가 응답을 `Err`로 복원하게 두고, UI에서는 `msg.error()`로 보여줍니다.

에러 선언하기

먼저 dictionary에서 시작합니다. 여기서 선언한 key만 `Err`에 넣을 수 있으므로 오타는 TypeScript가 잡아줍니다.

order.dictionary.ts

Err 던지기

사용자가 이해하고 해결할 수 있는 비즈니스 규칙에는 `Err`를 사용합니다. 상태 규칙은 모든 service가 같은 규칙을 쓰도록 document method에 두기 좋습니다.

order.document.ts

상태 코드 고르기

`new Err()`는 기본으로 400을 사용합니다. HTTP 의미가 중요할 때만 이름 있는 helper를 고르세요. 이렇게 하면 모든 규칙을 장황하게 만들지 않으면서 응답 의미를 분명히 할 수 있습니다.

`Err.NotFound`: 요청한 record가 없습니다.
`Err.Conflict`: 현재 상태에서는 이 동작을 받을 수 없습니다.
`Err.Forbidden`: 사용자는 확인됐지만 이 동작을 할 수 없습니다.

order.service.ts

Data 사용하기

번역 메시지에 값이 필요하면 `data`를 넘깁니다. 서버는 dictionary key를 `error`로 유지하고, 치환에 쓸 값을 `data`로 함께 보냅니다.

order.document.ts

클라이언트 처리

Akan fetch는 에러 응답을 `Err`로 복원합니다. UI 코드에서는 catch한 뒤 key와 data를 `msg.error()`에 넘기면 됩니다.

Order.Util.tsx

응답 형태

HTTP와 websocket 에러는 같은 단순한 형태를 사용합니다. 앱 코드에서 직접 만들 필요는 거의 없지만, 알아두면 디버깅이 쉬워집니다.

Error response

꿀팁

사용자에게 보여줄 도메인 실패에는 `Err`를 사용하세요. 개발 실수, 설정 누락, 일어나면 안 되는 상태에는 일반 `Error`를 사용합니다.
반복되는 상태 규칙은 document method에 두세요. 여러 모델을 읽거나 비교하는 로직은 service에 둡니다.
key는 도메인과 이유가 보이게 지으세요. 예: `order.error.notDraft`, `order.error.stockNotEnough`, `user.error.wrongPassword`.
서버에서 번역하지 마세요. key와 data를 보내고, 클라이언트가 사용자의 언어로 번역하게 둡니다.

에러 처리

Akan의 에러 처리는 단순한 규칙 하나로 시작합니다. 서버 코드는 타입 안전한 dictionary key를 던지고, 클라이언트는 그 key를 번역해서 보여줍니다.

사용자에게 보여줄 에러는 module dictionary에 선언합니다.
비즈니스 규칙이 실패하면 document나 service 코드에서 `Err`를 던집니다.
fetch가 응답을 `Err`로 복원하게 두고, UI에서는 `msg.error()`로 보여줍니다.

에러 선언하기

먼저 dictionary에서 시작합니다. 여기서 선언한 key만 `Err`에 넣을 수 있으므로 오타는 TypeScript가 잡아줍니다.

order.dictionary.ts

Err 던지기

order.document.ts

상태 코드 고르기

`Err.NotFound`: 요청한 record가 없습니다.
`Err.Conflict`: 현재 상태에서는 이 동작을 받을 수 없습니다.
`Err.Forbidden`: 사용자는 확인됐지만 이 동작을 할 수 없습니다.

order.service.ts

Data 사용하기

번역 메시지에 값이 필요하면 `data`를 넘깁니다. 서버는 dictionary key를 `error`로 유지하고, 치환에 쓸 값을 `data`로 함께 보냅니다.

order.document.ts

클라이언트 처리

Akan fetch는 에러 응답을 `Err`로 복원합니다. UI 코드에서는 catch한 뒤 key와 data를 `msg.error()`에 넘기면 됩니다.

Order.Util.tsx

응답 형태

HTTP와 websocket 에러는 같은 단순한 형태를 사용합니다. 앱 코드에서 직접 만들 필요는 거의 없지만, 알아두면 디버깅이 쉬워집니다.

Error response

꿀팁

사용자에게 보여줄 도메인 실패에는 `Err`를 사용하세요. 개발 실수, 설정 누락, 일어나면 안 되는 상태에는 일반 `Error`를 사용합니다.
반복되는 상태 규칙은 document method에 두세요. 여러 모델을 읽거나 비교하는 로직은 service에 둡니다.
key는 도메인과 이유가 보이게 지으세요. 예: `order.error.notDraft`, `order.error.stockNotEnough`, `user.error.wrongPassword`.
서버에서 번역하지 마세요. key와 data를 보내고, 클라이언트가 사용자의 언어로 번역하게 둡니다.