PayStream 알림 API 연동 시행착오 기록
PayStream 프론트엔드(PayStream-web)를 백엔드와 처음 연결하는 과정에서, 알림 서비스를 기준으로 게이트웨이 연동을 검증해 봤다. 이번 글은 그 과정에서 겪은 시행착오와, 지금 시점에서의 완료 기준을 정리한 기록이다.
배경
백엔드는 포크한 PayStream을 사용한다. Kafka, Spring Cloud, API Gateway로 구성된 MSA 구조이고, 프론트는 Next.js 15 기반의 PayStream-web이다. 도메인은 숙소·특가 쪽으로 UI와 목 데이터를 먼저 맞춰 둔 상태였다.
연동은 알림 서비스부터 시작했다. 우선 GET으로 연결 여부를 확인하고, 이어서 로그인 토큰을 붙인 POST /api/notifications 호출까지를 1차 목표로 잡았다.
알림 연동 단계
1. 경로 이해
브라우저에서는 각 마이크로서비스 포트를 직접 호출하지 않는다. API Gateway 한 주소만 사용한다. 로컬 환경 기준으로는 http://localhost:8000이다.
알림 API는 /api/notifications/... 프리픽스로 들어오면, 게이트웨이가 notification 서비스의 /notifications/...로 라우팅한다.
2. 헬스 확인 (GET …/ping)
인증 없이 열어 둔 패턴(/api/*/ping 등)을 이용해 GET /api/notifications/ping을 먼저 호출했다.
응답에 service, status: UP, timestamp 등이 포함되면 게이트웨이와 알림 서비스까지 정상적으로 연결된 것으로 볼 수 있다.
3. 프론트에서 재현
NEXT_PUBLIC_API_GATEWAY_URL을 사용하는 fetch 헬퍼를 만들고, 관리자 화면에 ping·POST를 눌러볼 수 있는 간단한 프로브 UI를 추가했다. 터미널에서 확인한 결과를 브라우저에서도 동일하게 재현할 수 있는지 검증하는 단계다.
4. POST /api/notifications
게이트웨이 보안 설정상 일반 API는 JWT가 필요하다. 로그인 후 받은 액세스 토큰을 Authorization: Bearer … 헤더에 붙이고, 요청 본문은 백엔드 DTO(userId, channel, title, body 등) 형식에 맞춘다.
시행착오와 해결
게이트웨이가 떠 있지 않을 때
처음에는 curl 요청이 연결 거부로 실패했다. 코드 문제가 아니라, 로컬에서 Eureka, Gateway, notification-service가 모두 기동되지 않은 상태였다.
관련 서비스를 순서대로 올린 뒤 동일 URL로 다시 호출하니 HTTP 200과 JSON 응답을 확인할 수 있었다.
.env.local 설정 관련 안내가 뜰 때
관리자 화면에 “.env.local에 … 설정” 같은 문구가 표시되는 경우가 있었다.
NEXT_PUBLIC_* 환경변수는 next dev 또는 next build 시점에 클라이언트 번들에 포함된다. .env.local이 없거나, 파일을 추가한 뒤 dev 서버를 재시작하지 않으면 브라우저에서는 빈 값으로 보일 수 있다.
로컬 개발 환경에서는 .env가 없을 때 http://localhost:8000을 폴백으로 두어 ping 테스트를 바로 진행할 수 있게 했다. 다만 프로덕션 빌드에는 반드시 실제 URL을 환경변수로 주입해야 한다.
CORS
게이트웨이에서 localhost 계열 origin을 허용해 두었다면, localhost:3000에서 실행 중인 프론트의 fetch는 차단되지 않는다. 연동 초기에 백엔드 CORS 설정을 한 번 확인해 두는 것이 좋다.
DTO와 API 문서 확인
“DTO를 어디서 확인해야 하지?”라는 질문이 처음에는 생각보다 자주 나온다. 실무에서는 아래 세 가지면 충분하다.
- Java Response/Request 클래스
- Swagger
v3/api-docs curl또는 Postman으로 실제 요청·응답 확인
현재까지의 완료 기준
완료한 것: 게이트웨이를 경유한 알림 ping 연동 및 검증. 프론트와 터미널 모두에서 200 응답을 확인할 수 있는 상태다.
다음 단계: 로그인 플로우와 토큰 저장 방식을 확정한 뒤, POST /api/notifications를 실사용자·실제 userId 기준으로 안정화한다. DB 제약이나 비즈니스 규칙에 따른 4xx 응답은 별도 트러블슈팅 글로 정리할 예정이다.
마무리
Next.js 프론트에서 Spring Cloud API Gateway 뒤의 알림 서비스를 연결하면서, 헬스 ping으로 먼저 통신 경로를 검증했다. NEXT_PUBLIC_ 환경변수와 dev 서버 재시작 이슈를 겪은 뒤, 로컬 폴백과 운영 환경 설정을 분리해 정리했다. 다음 목표는 JWT를 붙인 알림 생성 API 연동이다.