Swift로 앱을 만들다 보면 do-catch로 에러를 잡았는데, 정작 화면에 띄울 메시지가 영 시원찮았던 경험 있으실 거예요.
error.localizedDescription을 그대로 쓰면 “The operation couldn’t be completed…” 같은 정체불명의 문구가 사용자에게 그대로 노출되기 쉽거든요.
결론부터 말씀드릴게요.
Swift에서 사용자에게 보여줄 커스텀 에러 메시지를 정의하려면,
Error가 아니라LocalizedError프로토콜을 채택하고errorDescription프로퍼티를 구현하면 됩니다.
오늘은 이 방법을 예제와 함께 하나씩 풀어볼게요.
왜 그냥 Error로는 부족할까요?
많은 분들이 이렇게 에러를 정의하실 거예요.
enum LoginError: Error {
case invalidPassword
case userNotFound
}이렇게만 해두고 error.localizedDescription을 출력하면, 우리가 기대한 “비밀번호가 틀렸습니다”가 아니라 시스템이 만든 밋밋한 기본 문구가 나옵니다.
Error 프로토콜 자체에는 사람이 읽을 메시지를 정의하는 자리가 없기 때문이에요.
그래서 등장하는 게 바로 LocalizedError입니다.
Swift 커스텀 에러 메시지, 어떻게 정의하나요?
방법은 간단해요. LocalizedError를 채택하고 errorDescription을 구현하면 됩니다.
아래는 로그인 에러에 사용자용 메시지를 붙인 예제입니다.
extension LoginError: LocalizedError {
var errorDescription: String? {
switch self {
case .invalidPassword:
return "비밀번호가 올바르지 않습니다."
case .userNotFound:
return "존재하지 않는 사용자입니다."
}
}
}이제 error.localizedDescription을 호출하면 우리가 정해둔 문구가 그대로 나옵니다.
포인트는 errorDescription의 반환 타입이 String?, 즉 옵셔널이라는 거예요.
여기서 nil을 반환하면 다시 시스템 기본 메시지로 돌아가 버립니다. 그래서 모든 케이스에 값을 채워주는 게 중요해요.
errorDescription 말고 더 있나요? (failureReason·recoverySuggestion)
네, LocalizedError에는 선택적으로 구현할 수 있는 프로퍼티가 더 있어요.
역할을 표로 정리하면 이렇습니다.
| 프로퍼티 | 역할 | 예시 문구 |
|---|---|---|
errorDescription |
무엇이 잘못됐는지 | “로그인에 실패했습니다.” |
failureReason |
왜 발생했는지 | “비밀번호가 5회 틀렸습니다.” |
recoverySuggestion |
어떻게 해결할지 | “잠시 후 다시 시도해 주세요.” |
특히 recoverySuggestion은 사용자에게 다음 행동을 안내할 때 유용합니다.
실제로 SwiftUI의 Alert나 AppKit 환경에서는 이 값들을 자동으로 읽어 화면에 배치해 주기도 해요.
저는 사용자 대면 에러라면 최소한 errorDescription과 recoverySuggestion 두 개는 챙겨두는 편입니다.
개발용 로그와 사용자 메시지를 헷갈리지 마세요
한 가지만 덧붙일게요.
디버깅 로그에 찍고 싶은 개발자용 설명은 CustomStringConvertible(즉 description)로,
사용자에게 보여줄 번역된 메시지는 LocalizedError로 나누는 걸 추천해요.
둘의 목적이 다르니까요. 하나는 나를 위한 것이고, 다른 하나는 사용자를 위한 것이죠.
이렇게 역할을 분리해두면 나중에 다국어 대응을 할 때도 NSLocalizedString을 얹기 훨씬 수월합니다.
오늘 내용을 한 줄로 줄이면, “사용자에게 보여줄 에러라면 LocalizedError의 errorDescription부터 채우자”입니다.
작은 습관 하나로 사용자 경험이 확 달라지니, 다음 프로젝트에서 꼭 한번 적용해 보세요. 응원할게요! 🙌
참고 자료
- Create A Custom Swift Error [and override localizedDescription]
- Defining Custom Errors With Advanced Descriptions In Swift – SerialCoder.dev
- Alert and LocalizedError in SwiftUI – Augmented Code