선을 넘는 개발 로그

API 스타일 선택 가이드 — 8가지를 가르는 네 가지 질문

목차여덟 가지를 한 장에 놓기네 가지 질문으로 좁히기요청-응답 계열 — REST · GraphQL · gRPC · SOAP서버 주도 계열 — SSE · WebSocket · Long Polling · Webhooks함께 쓰는 구성과 이행 경로맺음말여덟 가지를 한 장에 놓기API 스타일을 고르는 자리에서 가장 자주 나오는 말은 "요즘은 뭘 쓰나요"입니다. 그런데 여덟 가지를 나란히 놓고 보면, 이들은 같은 문제의 경쟁자가 아니라 서로 다른 질문에 대한 답입니다.앞선 여덟 편에서 각각을 따로 다뤘습니다. 이 글은 그 결론만 모아 선택 앞에서 무엇을 물어야 하는지로 정리합니다.첫 갈림길은 성능도 유행도 아니고 "누가 먼저 말을 거는가"입니다. WebSocket만 양쪽에 걸쳐 있습니다.이 갈림길을 축으로 여덟 ..

Temporal Retry 정책 설계 — 백오프와 비재시도 오류 구분

목차재시도를 플랫폼에 맡긴다는 것RetryOptions 다섯 가지 값재시도하면 안 되는 오류 구분하기계층별로 재시도가 걸리는 자리재시도가 만드는 부작용맺음말재시도를 플랫폼에 맡긴다는 것분산 호출에 재시도를 붙이는 일은 어렵지 않습니다. 어려운 것은 재시도 상태를 프로세스 재시작 너머까지 들고 가는 일입니다. 애플리케이션 안의 재시도 루프는 프로세스가 죽는 순간 함께 사라지고, 그 요청이 몇 번째 시도였는지도 같이 사라집니다.Temporal에서 재시도는 코드가 아니라 선언한 정책입니다. 몇 번째 시도인지, 다음 시도가 언제인지는 서버가 기록하고, 워커가 전부 죽었다가 30분 뒤에 떠도 재시도는 이어집니다.직접 짠 재시도 코드가 안고 있는 것직접 구현감춰진 문제for 루프 + Thread.sleep대기 동안..

Long Polling 판단 기준 — 폴백으로 쓸 때의 조건과 비용

목차롱 폴링이 서 있는 자리요청 하나가 오래 머무는 구조유실 없는 이어받기자원과 한도언제 롱 폴링이 합리적인가맺음말롱 폴링이 서 있는 자리롱 폴링(long polling)은 클라이언트가 요청을 보내면 서버가 알려 줄 것이 생길 때까지 응답을 미루는 방식입니다. 응답을 받으면 클라이언트는 곧바로 다음 요청을 보냅니다.여덟 가지 방식 중 가장 오래됐고 가장 자주 "구식"으로 불립니다. 그런데도 아직 쓰이는 이유는 필요한 것이 평범한 HTTP 요청 하나뿐이기 때문입니다.항목짧은 폴링롱 폴링SSEWebSocket요청 형태주기적 요청보류되는 요청끝나지 않는 응답업그레이드 후 프레임빈 응답대부분이 빈 응답없거나 드묾없음없음지연최대 폴링 주기만큼거의 없음거의 없음가장 작음중간 계층 호환가장 좋음좋음버퍼링 설정 필요업..

Temporal Saga 구현 — 보상 트랜잭션을 코드로 다루는 법

목차분산 트랜잭션과 보상의 자리Temporal에서 Saga가 단순해지는 이유Saga 클래스로 구현하기보상 설계에서 어긋나는 지점오케스트레이션 방식의 한계맺음말분산 트랜잭션과 보상의 자리주문 하나가 결제·재고·배송 세 서비스를 건드리고 각 서비스가 자기 DB를 갖고 있다면, 하나의 트랜잭션으로 묶을 방법이 없습니다. 두 번째 단계에서 실패했을 때 첫 단계를 되돌리는 일을 애플리케이션이 직접 해야 하고, 이 되돌림의 집합을 Saga라고 부릅니다.Saga 패턴 자체의 개념과 설계 기준은 앞서 한 편으로 정리한 적이 있으니, 패턴을 처음 보신다면 그쪽을 먼저 읽는 편이 순서가 맞습니다.2026.03.11 - [프로그래밍 PROGRAMMING/아키텍쳐] - 분산 트랜잭션을 안전하게 처리하는 Saga 패턴 설계 가..

Webhooks 설계 기준 — 받는 쪽이 떠안는 재시도·중복·서명

목차웹훅이 뒤집는 것수신 엔드포인트 설계서명 검증과 신뢰 경계순서·유실·지연 다루기보내는 쪽이 되었을 때맺음말웹훅이 뒤집는 것웹훅(webhook)은 상대 서비스에서 사건이 생겼을 때 상대가 내 주소로 HTTP 요청을 보내는 방식입니다. 결제 승인, 배송 상태 변경, 저장소 푸시 알림이 모두 이 형태로 옵니다.기술적으로는 평범한 POST 요청 하나입니다. 그런데 방향이 뒤집히면서 책임 대부분이 받는 쪽으로 옮겨 옵니다.항목내가 호출할 때웹훅을 받을 때받는 쪽이 떠안는 것시작 시점내가 정함상대가 정함언제 올지 모르는 부하재시도내가 판단상대가 내 응답을 보고 판단응답 코드가 곧 제어 신호중복내가 안 보내면 없음재시도로 반드시 생김멱등 처리순서내가 부른 순서보장되지 않음순서 역전 처리인증내가 자격 증명을 실음상..

목차SSE가 맡는 좁은 일형식과 재연결 규약중간 계층이 스트림을 망가뜨리는 자리HTTP 버전과 동시 연결 한도SSE를 고를 조건맺음말SSE가 맡는 좁은 일서버 전송 이벤트(Server-Sent Events, SSE)는 끝나지 않는 HTTP 응답입니다. 클라이언트가 요청을 한 번 보내면, 서버가 그 응답 본문에 이벤트를 계속 이어 씁니다.핵심은 "새 프로토콜이 아니다"라는 점입니다. 요청도 응답도 평범한 HTTP이고, 그래서 얻는 것과 잃는 것이 모두 여기서 나옵니다.항목폴링SSEWebSocket연결요청마다 새로한 번 열고 유지한 번 열고 유지방향요청-응답서버 → 클라이언트만양방향프로토콜HTTPHTTP업그레이드 후 별도 프레임재연결클라이언트가 반복 요청브라우저가 자동 재연결직접 구현유실 복구매 요청이 최신..

목차액티비티가 맡는 일과 경계네 가지 타임아웃 고르기최소 한 번 실행과 멱등성하트비트로 긴 작업 다루기로컬 액티비티와 비동기 완료맺음말액티비티가 맡는 일과 경계워크플로우가 "무엇을 어떤 순서로"를 정한다면, 액티비티(Activity)는 실제로 바깥 세계를 건드리는 코드입니다. HTTP 호출, DB 쓰기, 파일 업로드, 메시지 발행이 전부 여기 들어갑니다.액티비티는 평범한 Java 메서드입니다. 결정성 제약도 없고, 스레드를 써도 되고, 현재 시각을 읽어도 됩니다. 대신 재시도와 타임아웃이라는 다른 규칙이 붙습니다. 이 글은 그 규칙을 어떤 기준으로 정하는지 정리합니다.경계를 어디에 긋는가액티비티를 잘게 쪼갤수록 재시도 단위가 정밀해지지만 히스토리 이벤트와 저장소 쓰기가 늘어납니다.나누는 기준예시판단외부 ..

목차WebSocket이 바꾸는 것연결 상태를 서버가 떠안는다는 뜻끊김을 전제로 설계하기자원 한도와 역압WebSocket을 고를 조건맺음말WebSocket이 바꾸는 것WebSocket은 HTTP 요청으로 시작해 같은 TCP 연결을 양방향 통로로 바꾸는 규약입니다. 한 번 열리면 양쪽 모두 언제든 메시지를 보낼 수 있습니다.이 설명만 보면 이득만 있는 것처럼 보입니다. 실제로 달라지는 것은 서버가 무엇을 기억해야 하는가입니다.항목HTTP 요청-응답WebSocket새로 떠안는 것연결 수명요청 단위로 끝남분·시간 단위로 유지연결 수만큼 메모리·파일 디스크립터상태 보관서버가 기억하지 않아도 됨어떤 노드에 누가 붙었는지 기억노드 간 메시지 전달 경로배포요청이 끝나면 교체 가능연결이 살아 있어 남음종료 신호와 재접속..

목차SOAP이 풀려던 문제봉투와 계약 — Envelope, WSDL, FaultWS-* 확장이 맡던 세 가지아직 SOAP이 남아 있는 자리기존 SOAP 서비스를 다루는 방법맺음말SOAP이 풀려던 문제SOAP은 XML 봉투에 담긴 메시지를 주고받아 원격 호출을 언어·플랫폼과 무관하게 만들려던 규약입니다. 2000년대 초 기업 시스템 연동의 기본값이었습니다.지금은 새 프로젝트에서 고를 일이 거의 없지만, 왜 밀려났는지를 정확히 알아 두면 REST·gRPC를 고를 때의 판단 기준이 함께 정리됩니다. 오늘날 당연하게 여기는 선택 대부분은 SOAP이 비쌌던 지점의 반작용이기 때문입니다.원격 호출을 언어 중립으로 만들려던 시도목표 자체는 gRPC와 같습니다. 계약을 먼저 정의하고 양쪽 언어의 코드를 생성한다는 발상..

목차gRPC가 옮겨 놓는 결정스키마 우선 계약을 지탱하는 규칙네 가지 호출 방식과 스트리밍의 대가운영에서 드러나는 비용어디까지 gRPC로 둘 것인가맺음말gRPC가 옮겨 놓는 결정gRPC는 .proto 파일에 정의한 서비스와 메시지를 양쪽 언어의 코드로 생성해, HTTP/2 위에서 이진 형식으로 주고받는 호출 방식입니다.빠르다는 점이 먼저 알려져 있지만, 성능은 도입 근거로 삼기에 약한 편입니다. 사내 호출 한 번의 직렬화 비용은 대개 데이터베이스 왕복에 묻힙니다. 실제로 달라지는 것은 계약을 관리하는 방식입니다.REST + JSON에서 있던 것gRPC 도입 후새로 떠안는 것계약이 문서·스키마 파일로 따로 존재계약이 빌드 산출물로 코드에 들어옴proto 저장소와 배포 순서를 관리해야 함필드 이름이 곧 호환..