토스뱅크의 MSA 환경에서의 Enum 관리 전략: EnumString, ArchUnit, Meta-Expose를 활용한 Deserialize 오류 극복기

핵심 기술: 토스뱅크는 마이크로서비스 아키텍처(MSA) 환경에서 발생하는 Enum 역직렬화(Deserialize) 오류 문제를 해결하기 위해 Enum 자체의 유연성을 높이는 EnumString, 코드의 일관성을 강제하는 ArchUnit, 그리고 Enum 버전 동기화를 관리하는 Meta-Expose라는 세 가지 전략을 성공적으로 도입했습니다.

기술적 세부사항:

• MSA와 Enum의 복잡성: MSA 환경에서 Enum을 여러 서버가 공유할 때, 버전 불일치로 인한 정의되지 않은 Enum 값 수신 시 Deserialize 에러가 빈번하게 발생하며 이는 치명적인 문제로 이어질 수 있습니다.
• 제공자(Provider) vs 소비자(Consumer) 전략: 통신 주체에 따라 Enum 처리 방식을 다르게 정의했습니다.
  • 클라이언트(소비자) → 서버(제공자): 정의되지 않은 Enum 값 수신 시 400 Bad Request와 같은 클라이언트 오류로 즉시 응답하는 엄격한 검증 방식을 채택했습니다.
  • 서버(제공자) → 클라이언트(소비자): 새로운 Enum 값 추가 시 클라이언트가 이를 유연하게 처리할 수 있도록 (경고 후 무시, 기본값 처리, 명시적 오류 발생 등) 선택권을 부여하는 개방적인 구조를 설계했습니다.
• EnumString 도입: Enum 타입의 장점을 유지하면서도, 예상치 못한 값이 들어왔을 때 개발자가 원하는 동작을 직접 정의할 수 있는 유연한 접근법을 제공하는 전용 라이브러리를 제작했습니다.
  • toEnumOrNull(), toEnumOrElse(), toEnumOrThrow() 와 같은 메소드를 통해 상황에 맞는 Enum 역직렬화 처리를 지원합니다.
• ArchUnit을 통한 EnumString 전파: 제공자 → 소비자 패턴에서 EnumString 사용을 시스템적으로 강제하기 위해 ArchUnit을 활용했습니다.
  • 공용 레포에 ArchUnit 규칙을 적용하여 컨슈머 코드에서 Enum 사용을 감지하고 빌드 시점에 실패하도록 설정했습니다.
• Meta-Expose를 통한 Enum 배포 의존성 끊기: 서비스 간 Enum 버전 동기화 문제를 해결하기 위해 설계되었습니다.
  • 중앙 Meta-Expose-Hub가 Enum을 사용하는 모든 서버를 watch하고, 버전이 올라가지 않은 서버를 감지하여 관리자에게 알림을 제공합니다.
  • 자동으로 노출되는 Enum API, 중앙 Hub에서의 정합성 검증, ServiceDiscovery를 통한 동적 서비스 식별, Grafana를 통한 시각화 및 모니터링 기능을 포함합니다.

개발 임팩트:

• Enum 관련 Deserialize 오류를 거의 완전히 제거하여 서비스 안정성을 대폭 향상시켰습니다.
• 개발자의 주의에 의존하는 것이 아닌, 시스템적으로 오류를 예방하고 관리할 수 있게 되어 운영 효율성을 증대했습니다.
• 신규 구성원도 쉽게 Enum 관리 규칙을 따를 수 있도록 하여 개발 생산성을 높였습니다.
• 수백 번의 배포와 확장되는 MSA 환경 속에서도 단 한 번의 Enum 이슈 없이 안정적인 서비스 운영을 달성했습니다.