무제는 사용자의 다양한 페르소나를 존중하며, 기록의 가치를 보존하는 플랫폼을 지향합니다. 서비스가 성장함에 따라 기존에 작성된 파편화된 로직들은 유지보수의 복잡도를 높이고, 때때로 사용자 의도와 다른 결과를 초래하기도 합니다. 최근 진행된 업데이트를 통해 직면했던 기술적 문제들과 이를 해결하기 위해 시도한 구조적 개선 사항들을 공유하고자 합니다.

1. 폼 바인딩의 모호성 해결과 UI/UX 일관성 확보

기존의 게시물 에디터는 메인 페이지의 빠른 작성(Quick Compose) 도구와 서로 다른 사용자 경험을 제공하고 있었습니다. 특히 익명 작성 여부를 결정하는 체크박스는 단순한 형태에 머물러 있어, 서비스 전반의 시각적 언어와 일치하지 않는 문제가 있었습니다. 이를 개선하기 위해 에디터의 익명 설정을 스위치 형태의 토글 UI로 변경하고, ‘무명’과 ‘공개’라는 명확한 텍스트 피드백을 추가하였습니다.

UI 변경 과정에서 기술적으로 가장 중점을 두었던 부분은 데이터 바인딩의 무결성입니다. Thymeleaf의 th:field 속성을 사용할 경우, 스프링은 체크박스가 해제되었을 때 값이 누락되는 것을 방지하기 위해 _isAnonymous라는 히든 필드를 자동으로 생성합니다. 이때 개발자가 수동으로 정의한 name 속성과 자바스크립트에 의한 동적 값 변경이 겹치면서, 서버로 중복된 파라미터가 전송되어 불리언(Boolean) 값이 항상 true로 해석되는 결함이 발견되었습니다.

이를 해결하기 위해 상단의 스위치는 상태 표시를 위한 UI 컴포넌트로만 활용하고, 실제 데이터 전송은 자바스크립트에 의해 제어되는 별도의 히든 필드로 일원화하였습니다. 결과적으로 프론트엔드의 상태 변화가 백엔드 DTO(Data Transfer Object)로 정확히 매핑되는 안정적인 구조를 확보할 수 있었습니다.

2. 도메인 식별자의 일관성: 이메일에서 핸들로

게시물의 수정 및 삭제 권한을 검증하는 과정에서, 기존에는 사용자의 이메일 주소를 주요 식별자로 활용해 왔습니다. 하지만 도메인 모델에서 사용자를 고유하게 나타내는 페르소나는 ‘핸들(@handle)’입니다. 시스템 내부 식별자인 이메일과 대외적 식별자인 핸들이 검증 로직에서 혼용되는 것은 도메인 관점에서 의미론적 불일치를 야기하며, 향후 URL 라우팅이나 도메인 확장 시 오류를 유발할 가능성이 높았습니다.

이번 개선 작업에서는 서비스 내의 모든 소유권 검증 로직을 핸들 기반으로 변경하였습니다. 컨트롤러 계층에서 UserPrincipal로부터 핸들 정보를 추출하여 서비스로 전달하도록 구조를 변경함으로써, 도메인 모델의 일관성을 높이고 데이터 접근 권한 검증 절차를 보다 직관적으로 재정의하였습니다.

3. API 공통 예외 처리를 통한 견고한 오류 응답 설계

클라이언트와 서버 간의 통신에서 예외 상황에 대한 명확한 응답은 서비스의 신뢰도와 직결됩니다. @ControllerAdvice를 활용하여 RestController 전용 글로벌 예외 처리기인 ApiGlobalExceptionHandler를 구현하였습니다.

특히 @Valid 어노테이션을 통해 발생하는 MethodArgumentNotValidException을 가로채어, 유효성 검사에 실패한 필드와 에러 메시지를 LinkedHashMap에 담아 구조화된 JSON 형태로 반환하도록 설정하였습니다. 또한 IllegalArgumentException과 같은 런타임 예외에 대해서도 일관된 응답 규격을 적용함으로써, 클라이언트가 오류 원인을 즉각적으로 파악하고 대응할 수 있는 개발 환경을 구축하였습니다.

마치며

이번 작업은 겉으로 드러나는 화려한 기능의 추가는 아니었으나, 서비스의 근간이 되는 데이터 처리의 정확도를 높이고 내부 로직의 응집도를 강화하는 데 주력하였습니다. 코드 한 줄의 변경이 사용자에게는 더 나은 안정성으로 전달되기를 기대합니다.