이커머스 결제 연동 문서와 개발 환경 설정 한곳에 정비

문서 작업을 미루면 어떤 일이 생기는지는 이미 여러 번 경험했다. 새로 합류한 팀원이 결제 연동 흐름을 파악하는 데 며칠을 쓰거나, RBAC 권한 구조가 어떻게 돼 있는지 묻는 메시지가 반복되거나. 아이콘 가이드, RBAC, Redis, 이커머스 결제 연동 플랫폼 관련 문서를 한꺼번에 정리한 건 그런 맥락에서였다. 개발 환경 설정 파일 6개도 같이 손봤다.

결제 연동 문서를 지금 쓴 이유

문서는 "나중에"가 없다. 코드를 막 짠 사람이 가장 잘 설명할 수 있고, 시간이 지날수록 기억이 희미해진다. 결제 연동 쪽은 특히 그렇다. PG사마다 인증 방식, 웹훅 스펙, 환불 플로우가 조금씩 달라서, 구현은 했는데 왜 이렇게 됐는지를 나중에 다시 추적하면 시간이 두 배로 든다.

이커머스 결제 연동 문서를 쓰면서 뼈대로 잡은 구성은 이렇다:

• 결제 요청 흐름 - 클라이언트에서 서버로 어떤 파라미터를 넘기는지, 어느 시점에 주문이 생성되는지
• 검증 단계 - 결제 완료 후 금액 위변조 검증을 어디서 어떻게 하는지. 클라이언트단 금액을 그대로 신뢰하면 안 되는 이유
• 웹훅 처리 - 비동기 상태 업데이트 흐름과 멱등성 처리. 같은 웹훅이 두 번 오는 상황을 어떻게 다루는지
• 예외 케이스 - 네트워크 단절, 중복 결제 시도, 부분 환불 시나리오

이 네 가지가 빠지면 문서가 절반짜리가 된다. 특히 웹훅 멱등성은 처음 연동할 때 놓치기 쉬운 지점이라 명시적으로 적어뒀다. 정의가 없으면 운 좋게 한동안 괜찮다가, 어느 날 같은 주문이 두 번 처리되는 상황이 생긴다. 웹훅 수신 테이블에 idempotency_key를 두고 처리 여부를 체크하는 패턴이 가장 단순하고 안정적이다.

RBAC 문서는 역할별 접근 가능 리소스를 표로 정리하는 게 핵심이었다. 권한 구조는 코드 여기저기에 흩어져 있어서, 전체를 조망하는 문서가 없으면 "이 API는 누가 쓸 수 있지?"를 확인하려고 매번 코드를 뒤져야 한다. 역할이 추가될 때마다 이 표를 같이 업데이트하기로 정했다.

Redis 문서는 캐시 키 네이밍 컨벤션과 TTL 정책 위주로 썼다. 파일마다 제각각이었던 키 패턴을 통일하는 게 주 목적이었고, 어떤 데이터를 얼마 동안 캐시하는지 근거도 같이 남겨뒀다. TTL을 왜 그렇게 잡았는지를 안 쓰면, 나중에 숫자만 보고 "이게 맞나?" 싶어서 건드렸다가 캐시 일관성 문제가 생기는 일이 나온다.

환경 설정 파일 6개를 건드린 이유

개발 환경 설정이 분산돼 있거나 정리가 안 돼 있으면 온보딩이 사고 대기 상태가 된다. "로컬에서 이 서비스 띄우려면 뭐 해야 해요?"라는 질문에 열 줄짜리 구두 답변이 나온다면, 그 내용이 코드와 문서로 자동화돼 있어야 한다는 신호다.

이번에 손댄 핵심은 프로파일 분리 구조를 명확하게 정리하는 것이었다.

# 환경 분리 기본 패턴
# dev  : 로컬 DB, 로컬 Redis, 상세 로그, 결제 샌드박스 엔드포인트
# prod : 운영 자원, 최소 로그, 실 결제 엔드포인트
spring.profiles.active=dev

# 환경별로 달라지는 값은 application-{profile}.yml 에만
# application.yml 에는 공통 설정만
# 이 선이 흐려지면 언젠가 prod 에 dev 설정이 타고 올라간다

설정 파일을 나눌 때 자주 범하는 실수가 application.yml에 환경 의존적인 값을 섞어두는 거다. 처음엔 별거 아닌 것 같은데, 프로파일이 세 개 네 개로 늘어나면서 오버라이드 관계가 꼬이기 시작한다. 어떤 값이 최종적으로 어느 파일에서 오는지 추적이 안 되면, 설정 하나 바꾸는 것 자체가 두려운 작업이 된다. 이번에 그 경계를 다시 그었다.

반복 작업 스크립트화는 주로 설정 검증 쪽이었다. 로컬 환경 구동 전에 필수 환경 변수 누락 여부를 체크하는 스크립트를 추가했다. 없어도 앱이 뜨긴 뜨는데, 결제 모듈처럼 외부 키가 없으면 런타임에 엉뚱한 지점에서 터지는 케이스는 시작 시점에 걸러내는 게 낫다.

이런 작업을 미루면 생기는 일

의존성이든 문서든 환경 설정이든, 미뤄서 좋아지는 게 없다. 이 말이 진부하게 들리는 건 알겠는데, 체감이 다르다.

의존성 업데이트를 반년 묵히면 나중에 한꺼번에 올려야 하는데, 그때는 breaking change가 두세 개 겹쳐서 어디서 문제가 생기는지 추적하기 어렵다. 패치 하나하나 올릴 때는 5분이면 되는 게, 쌓이면 반나절짜리 디버깅이 된다. 결제 연동 문서도 마찬가지다. 연동 직후에는 세부 흐름이 머릿속에 다 있어서 굳이 써야 하나 싶지만, 6개월 후에 같은 흐름을 다시 확인해야 할 때 값어치를 한다.

자동화가 실질적으로 도움 되는 영역:

• 의존성 버전 알림 - 새 버전 나오면 PR로 받아서 주기적으로 머지. 한 번에 몰아치는 것보다 작게 나눠서 올리는 게 훨씬 안전하다
• 보안 취약점 스캔 - 수동으로 챙기는 건 한계가 있음. 파이프라인에 걸어두면 놓칠 일이 없다
• 빌드 상태 모니터링 - 설정 파일 건드린 직후 빌드가 깨지는지 빠르게 확인하는 루프
• 환경 변수 누락 감지 - 새 서비스를 추가하거나 설정 항목이 늘어나는 시점에 특히 놓치기 쉽다

이번 작업은 파일 6개 수정에 문서 몇 개 추가라 겉보기엔 작다. 그런데 팀원이 늘거나 이커머스 쪽 기능을 확장할 때, 결제 연동 문서가 있냐 없냐는 체감 차이가 크다. 문서 없이 구현을 이해하려면 코드 읽기, 질문, 테스트를 다 거쳐야 하는데, 문서 한 페이지가 그 사이클을 줄여준다.

개발 환경 투자는 복리처럼 돌아온다는 걸 이번에도 다시 느꼈다. 처음엔 귀찮은 작업이 맞다. 다음에 같은 질문을 받지 않게 되는 게 그 귀찮음의 대가다. 이번 작업을 계기로 이 부분 정기 점검 루틴을 만들기로 했다.