서론: 오늘의 문제 프로세스가 실행 중이라는 사실과 요청을 안전하게 받을 수 있다는 사실은 다르다. startup, readiness, liveness probe와 종료 절차를 서비스 생명주기의 명시적 계약으로 설계한다. 1. startup probe의 역할 기동이 느린 애플리케이션은 초기화 중 liveness 실패로 재시작 루프에 빠질 수 있다...

서론: 오늘의 문제 클러스터가 충분히 커도 요청량과 제한이 부정확하면 Pod는 잘못 배치되고 중요한 워크로드가 축출된다. requests, limits, QoS, 스케줄링 제약을 하나의 용량 계약으로 묶는다. 1. requests는 예약이자 배치 입력 CPU와 메모리 requests는 스케줄러가 노드 적합성을 판단하는 기준이다. 평균 사용량을 그...

서론: 오늘의 문제 Kubernetes에서 운영 단위는 직접 만든 Pod 한 개가 아니라 원하는 상태를 선언한 워크로드다. Deployment와 ReplicaSet의 책임을 구분하고, 배포 변경을 되돌릴 수 있는 상태 전이로 다룬다. 1. 원하는 상태와 컨트롤 루프 매니페스트는 실행 절차가 아니라 최종 상태를 표현한다. 컨트롤러는 현재 상태와 원...

서론: 문서와 구현 사이의 거리를 없애기 API 문서가 실제 응답과 다르면 클라이언트는 결국 트래픽을 캡처하거나 서버 코드를 읽는다. 계약은 사람이 읽는 설명이면서 CI가 검증할 수 있는 산출물이어야 한다. OpenAPI, 소비자 계약 테스트, 프로덕션 관측을 하나의 피드백 루프로 연결한다. 1. OpenAPI가 담아야 할 것 paths: /...

서론: 서버 배포가 끝나도 클라이언트는 남아 있다 모바일 앱, 외부 파트너, 다른 팀 서비스는 서버와 동시에 배포되지 않는다. 이미 배포된 클라이언트가 수개월간 남을 수 있어 API 변경은 코드 리팩터링과 다르다. 먼저 비파괴 변경으로 진화하고, 정말 필요할 때만 새 버전을 만든다. 1. 일반적으로 안전한 변경과 위험한 변경 대체로 안전: 응...

서론: 목록 응답은 데이터가 커질수록 계약이 된다 초기에는 findAll() 결과를 배열로 반환해도 된다. 데이터가 늘면 응답 크기, DB 정렬, 페이지 사이 중복·누락이 문제가 된다. 페이지네이션은 단순 성능 옵션이 아니라 순서와 다음 위치를 클라이언트에 약속하는 계약이다. 1. Offset Pagination GET /orders?page=3...

서론: 타임아웃 뒤 클라이언트는 결과를 모른다 결제 생성 요청이 서버에서 성공했지만 응답이 유실되면 클라이언트는 재시도할 수밖에 없다. API가 중복 요청을 구분하지 못하면 이중 결제가 발생한다. 오류 계약은 사람이 읽는 메시지만이 아니라 호출자가 다음 행동을 결정할 수 있는 프로토콜이어야 한다. 1. 안정적인 오류 본문 Problem Detai...

서론: URL 모양보다 행동의 의미 REST API 설계 논의는 복수형 명사나 하이픈 규칙에 머물기 쉽다. 더 중요한 것은 클라이언트가 메서드·상태 코드·헤더만 보고 요청의 안전성, 재시도 가능성, 캐시 조건을 예측할 수 있는가다. HTTP의 의미를 지키면 프록시·브라우저·SDK와 자연스럽게 협력할 수 있다. 1. 리소스는 업무 개념이다 좋은 후...

서론: 전체 재작성은 아키텍처 전략이 아니다 기존 Service와 JPA Entity가 얽힌 시스템을 한 번에 헥사고날 구조로 바꾸면 오랜 기간 기능 개발이 멈추고 회귀 위험이 커진다. 가장 많이 변하고 테스트가 어려운 업무 흐름 하나를 골라 경계를 만들고, 새 기능부터 그 경계를 따르게 하는 방식이 현실적이다. 1. 전환 대상 선택 좋은 첫 후...

서론: 테스트 속도는 구조의 결과다 업무 규칙 하나를 검증하는데 Spring Context와 실제 DB가 항상 필요하다면 의존성 경계가 안쪽까지 들어온 신호다. 헥사고날 구조는 테스트를 위해 만든 것은 아니지만, Port를 기준으로 외부를 바꿔 끼울 수 있어 빠른 테스트와 현실적인 통합 테스트를 분리하기 쉽다. 1. Domain 테스트 @Test...