알림 파이프라인에서 발신자 표시명 분리 정규화로 채널별 오발송 해결

v3.1 릴리스 — senderDisplay 필드 추가하다 만난 알림 파이프라인 이슈

API 스펙 작은 변경 하나가 알림 파이프라인 전체를 흔드는 경험을 또 함. 파트너 쪽에서 "발신자 표시명을 별도로 받고 싶다"는 요청이 왔고, 기존 sender 외에 senderDisplay 를 추가했음.

처음엔 단순 nullable 문자열 추가라 30분이면 끝날 줄 알았는데, 외부 메시징 채널 템플릿 변수랑 묶이니까 얘기가 달라짐.

무엇이 꼬였나

• 기존 sender = 내부 식별자 (영문, 길이 제약 없음)
• 신규 senderDisplay = 사용자 노출용 (한글, 이모지 허용)
• 알림 수집 레이어가 둘을 헷갈려서 채널마다 다른 값이 나감
• 메시징 채널 템플릿은 변수 글자수 제한이 빡세고 이모지를 못 받음

결정한 원칙

1. API는 두 필드 모두 받되 senderDisplay 는 optional
2. 채널별 정규화는 알림 수집 레이어에서만 수행
3. 발송 모듈은 정규화된 값만 신뢰 (재가공 금지)

이렇게 정리하니 채널이 추가돼도 정규화 규칙을 한 곳에서만 관리하면 됨. 처음엔 "API 게이트웨이에서 잘라서 내려주자"는 의견도 있었는데 채널마다 제약(이메일 60자, 메시징 14자, SMS 20자)이 달라 단일 기준을 못 잡음. 호출처가 길이를 알 필요 없게 하는 게 핵심이었음.

fallback 처리

senderDisplay 가 비면 sender 로 떨어뜨리는데, 이때 sender 가 영문 식별자라 사용자한테 그대로 노출되면 곤란함. 그래서 fallback 시점에 한 번 더 "노출 가능한 형태인지" 검사하는 가드를 넣음. 결과적으로 분기는 늘었지만 운영 들어간 뒤 "왜 abc_corp_03 이 카톡으로 오냐" 같은 문의가 안 옴.

남은 교훈

• nullable 필드 추가는 결코 단순 추가가 아님 — 의미가 분기되면 호출처가 다 영향받음
• 표시용/식별용 분리는 처음 설계할 때부터 했어야 했음. v3 까지 끌고 온 게 미안함
• 채널별 정규화 규칙은 코드보다 표로 먼저 합의해야 의견 충돌이 줄어듦
• v3.1 마이너 버전인데 fallback 로직 때문에 PR 라인이 +320 됨. 마이너가 아닌 듯 마이너인 듯

다음