시스템 간 인터페이스 설계·정의 단계에서 알아야 할 원칙과 개념

1. 인터페이스 정의 단계의 목적

구현에 들어가기 전에 송신 측과 수신 측이 지켜야 할 약속을 문서로 확정하는 단계

1.1 이 단계에서 확정하는 것

• 연동 방식 : 동기·비동기, 단건·배치, Push·Pull 중 무엇을 쓸지 결정함
• 데이터 계약 : 주고받는 필드의 이름, 타입, 길이, 필수 여부, 코드값을 정의함
• 오류 규약 : 실패 응답의 형태와 재시도 가능 여부를 정의함
• 운영 기준 : 처리량, 타임아웃, 재처리 횟수, 보안 방식을 정의함

1.2 인터페이스 정의서 구성 항목

정의서 기본 항목

구분	내용
개요	인터페이스 ID, 명칭, 목적, 송신·수신 시스템, 담당자
연동 방식	프로토콜(HTTP 등), 메서드, 엔드포인트, 동기·비동기 여부
전송 주기·건수	실시간 또는 배치 주기, 1회 최대 건수, 일 예상 건수
요청·응답 명세	필드 정의, 예시 JSON, 응답 코드
오류 처리	오류 코드, 재시도 정책, 최종 실패 시 처리
보안	인증 방식, 암호화, 개인정보 포함 여부
이력 관리	정의서 버전, 변경 일자, 변경 사유

정의서는 구현 문서이기 전에 양측이 합의한 계약서이므로, 구현 후에 맞추는 것이 아니라 구현 전에 확정해야 한다

---

2. 연동 방식 결정

연동 방식은 이후 모든 설계의 전제가 되므로 가장 먼저 정함

2.1 동기와 비동기

• 동기 : 요청 후 처리 결과를 응답으로 바로 돌려받음. 구현이 단순하지만 수신 측 지연이 송신 측으로 전파됨
• 비동기 : 접수만 확인하고 처리는 별도로 진행함. 장애 격리에 유리하지만 처리 결과 확인 수단이 따로 필요함
• 선택 기준 : 결과를 즉시 알아야 하는지, 수신 측 처리 시간이 길어질 수 있는지로 판단함

2.2 단건과 배치

• 단건 전송 : 건마다 요청을 보냄. 구조는 단순하지만 건수가 많으면 요청 오버헤드가 커짐
• 배치 전송 : 여러 건을 JSON 배열 같은 형태로 묶어 한 번에 보냄. 효율적이지만 일부만 실패했을 때의 처리 규칙이 필요함
• 부분 실패 규칙 : 배치 중 일부가 실패하면 전체를 실패로 볼지, 건별 결과를 응답에 담을지 미리 정해야 함
• 단건·다건 혼용 시 : 요청 형태를 항상 배열로 통일하면 1건이든 여러 건이든 같은 구조로 처리할 수 있음

2.3 Push와 Pull

• Push : 송신 측이 수신 측 엔드포인트로 보냄. 지연이 적지만 수신 측 가용성에 영향을 받음
• Pull : 수신 측이 주기적으로 가져감. 수신 측이 속도를 조절할 수 있으나 폴링 주기만큼 지연됨

방식별 비교

구분	장점	주의점
동기	결과 즉시 확인	지연·장애 전파
비동기	장애 격리	결과 확인 수단 필요
배치	처리 효율	부분 실패 규칙 필요
Push	낮은 지연	수신 측 가용성 의존
Pull	수신 측 속도 제어	폴링 지연

---

3. 데이터 계약 정의

필드 단위로 의미와 형식을 명확히 정해 해석 차이로 인한 오류를 없앰

3.1 필드 정의 항목

• 필드명 : 명명 규칙(snake_case 등)을 하나로 통일함
• 타입과 길이 : 문자열 최대 길이, 숫자 범위와 정밀도를 명시함
• 필수 여부 : 필수 필드와 선택 필드를 구분함
• null 처리 : null, 빈 문자열, 필드 생략을 같은 의미로 볼지 다르게 볼지 정함
• 기본값 : 값이 없을 때 수신 측이 채울 값을 정의함
• 설명과 예시값 : 필드 의미와 실제 값 예시를 함께 적음

3.2 형식 표준

• 인코딩 : UTF-8로 통일하고 Content-Type 헤더에 charset을 명시함. JSON의 \uXXXX 이스케이프는 정상 표현이므로 파서 기준으로는 동일한 값임
• 날짜·시간 : ISO 8601 형식(2026-10-16T09:30:00+09:00)을 권장하며 타임존을 반드시 명시함
• 금액·정밀 숫자 : 부동소수점 오차가 있으므로 문자열이나 정수(최소 단위)로 전달하는 방식을 검토함
• 불리언 : true/false, Y/N, 1/0 중 하나로 통일함
• 직렬화 불가 타입 : DB의 날짜, Decimal 같은 타입은 전송 전에 문자열로 변환하는 규칙을 정함

3.3 코드값 정의

• 코드 정의서 : 상태 코드 같은 값은 코드와 의미를 표로 관리함
• 예시 : 처리 전, 처리 중, 완료, 실패처럼 코드별 의미와 전이 가능한 방향을 함께 정의함
• 확장 여지 : 새 코드가 추가될 수 있으므로 수신 측이 모르는 코드를 만났을 때의 처리 규칙을 정함

3.4 버전 관리와 하위 호환성

• 하위 호환 변경 : 선택 필드 추가는 기존 수신 측에 영향이 없는 변경임
• 비호환 변경 : 필드 삭제, 이름·타입 변경, 필수 필드 추가는 기존 연동을 깨뜨림
• 원칙 : 수신 측은 모르는 필드를 무시하고, 송신 측은 기존 필드의 의미를 바꾸지 않음
• 버전 표기 : 비호환 변경이 불가피하면 URL이나 헤더에 버전을 두어 신구 버전을 병행함

필드는 추가하기는 쉽고 바꾸기는 어렵기 때문에 처음 정의할 때 이름과 타입을 신중하게 정해야 한다

---

4. 식별자와 멱등성

네트워크 환경에서는 같은 요청이 두 번 이상 전달될 수 있다는 전제로 설계함

4.1 전송 보장 수준

전송 보장 수준 비교

수준	의미	특징
at-most-once	최대 한 번 전달	유실 가능, 중복 없음
at-least-once	최소 한 번 전달	유실 없음, 중복 가능
exactly-once	정확히 한 번	구현 비용이 큼

• 현실적 선택 : 대부분 at-least-once로 구성하고 수신 측에서 중복을 걸러 결과적으로 한 번 처리한 효과를 만듦

4.2 멱등성

• 정의 : 같은 요청을 여러 번 처리해도 결과가 한 번 처리한 것과 같은 성질
• 멱등키 : 건마다 고유 식별자(uuid 등)를 부여하고 수신 측이 이미 처리한 키는 건너뜀
• 랜덤 UUID의 한계 : 재전송할 때마다 새 값이 생성되면 같은 데이터가 다른 키로 중복됨
• 결정적 UUID : 원본 PK 같은 안정적인 값에서 UUID를 만들면 재처리해도 같은 키가 나와 중복 제거가 가능함
• 정의 항목 : 식별자 필드명, 생성 주체(송신·수신), 생성 규칙, 중복 수신 시 응답 방식을 정의서에 포함함

---

5. 오류와 재처리 규약

실패를 어떻게 알리고 누가 다시 시도할지를 사전에 약속함

5.1 응답 코드 구분

HTTP 응답 코드별 처리

응답	의미	송신 측 처리
2xx	정상 접수	완료 처리
4xx	요청 자체의 오류(형식, 검증 실패)	재시도해도 같은 결과이므로 재시도 제외
5xx	수신 측 내부 오류	재시도 대상
타임아웃	처리 여부 불명	재시도 대상, 멱등성으로 중복 방어

• 타임아웃의 특수성 : 응답을 못 받았다고 처리가 안 된 것은 아니므로 중복 전달 가능성을 항상 염두에 둠

5.2 오류 응답 본문

• 오류 코드 : HTTP 상태와 별도로 업무 오류 코드를 정의함
• 메시지 : 사람이 읽을 수 있는 설명을 함께 제공함
• 상세 위치 : 검증 실패라면 어떤 필드가 문제인지 알려줌

5.3 재처리 정책

• 재시도 횟수 한도 : 무한 재시도를 막기 위해 최대 횟수를 정함
• 재시도 간격 : 일정 간격 또는 점진적으로 늘리는 백오프를 적용해 같은 장애에 연속으로 부딪히지 않게 함
• 최종 실패 처리 : 한도를 넘은 건의 보관 위치, 알림, 수동 복구 절차를 정의함
• 상태 관리 : 처리 전, 처리 중, 완료, 실패 상태와 재처리 횟수를 컬럼으로 관리함
• 처리 중 고착 건 : 장애로 처리 중 상태에 멈춘 건을 일정 시간 후 복구하는 규칙이 필요함

재시도 가능한 실패와 불가능한 실패를 구분하는 기준이 정의서에 있어야 재처리 로직이 일관된다

---

6. 흐름 제어와 용량

처리량을 사전에 산정해 어느 한쪽이 과부하로 무너지지 않게 함

• 처리량 산정 : 일 평균, 피크 시간대 건수, 건당 크기를 예측함
• 배치 크기 : 1회 전송 최대 건수와 요청 본문 크기 상한을 정함
• 타임아웃 : 연결 타임아웃과 응답 타임아웃을 구분해 정의함
• 백프레셔 : 수신 측이 느려질 때 송신 측이 쌓이는 데이터를 어디까지 버틸지(큐 크기, 임계값)를 정함
• 속도 제한 : 수신 측이 감당 가능한 초당 요청 수를 합의함
• 순서 보장 : 건 간 처리 순서가 중요한지 확인함. 재처리가 있으면 순서가 뒤바뀔 수 있으므로 순서 의존 여부를 명시함

---

7. 보안과 추적성

데이터 보호와 문제 발생 시 원인 추적이 가능하도록 정의함

7.1 보안

• 인증 : API 키, 토큰, 상호 TLS 등 방식을 정함
• 전송 구간 암호화 : TLS 적용 여부를 명시함
• 개인정보 최소화 : 수신 측이 필요한 필드만 전송하고, 민감 필드는 마스킹이나 암호화 여부를 정함
• 로그 정책 : 로그와 실패 보관 데이터에 원문 개인정보가 남지 않도록 기준을 정함

7.2 추적성

• 상관 ID : 요청마다 추적용 ID를 부여해 송신·수신 로그를 연결함
• 처리 이력 : 건별 상태 변화와 실패 사유를 기록할 컬럼이나 테이블을 둠
• 모니터링 지표 : 전송 건수, 성공률, 재처리 건수, 최종 실패 건수를 관측 대상으로 정의함

---

8. 변경 관리와 검증

정의서가 확정된 뒤에도 약속이 유지되도록 절차와 검증 수단을 마련함

• 정의서 버전 관리 : 변경 이력을 남기고 양측이 같은 버전을 보고 있는지 확인함
• 변경 절차 : 비호환 변경은 사전 공지와 협의를 거친 뒤 적용함
• 샘플 데이터 : 정상 케이스, 경계값, 오류 케이스 예시를 정의서에 포함함
• 계약 테스트 : 정의서의 스키마를 기준으로 송신 데이터가 규칙을 만족하는지 자동 검증함
• 연동 테스트 : 실제 연동 전에 테스트 환경에서 정상·오류·재시도·중복 시나리오를 확인함

---

요약

인터페이스 설계 체크리스트

영역	확정할 내용
연동 방식	동기·비동기, 단건·배치, Push·Pull
데이터 계약	필드 타입·길이·필수·null, 인코딩, 날짜 형식, 코드값
버전 관리	하위 호환 규칙, 비호환 변경 시 버전 병행
멱등성	식별자 규칙, 중복 수신 처리, 전송 보장 수준
오류·재처리	응답 코드별 처리, 재시도 한도와 간격, 최종 실패 절차
흐름 제어	처리량, 배치 크기, 타임아웃, 백프레셔, 순서 보장
보안·추적	인증, 암호화, 개인정보 최소화, 상관 ID, 모니터링 지표
변경·검증	정의서 버전, 변경 절차, 샘플 데이터, 계약·연동 테스트

인터페이스 정의의 핵심은 정상 흐름이 아니라 중복, 실패, 변경 같은 예외 상황의 규칙을 미리 합의해 두는 것이다