Implementing REST Integration Exactly to Spec

한국어 원문으로 표시합니다.

목표

인터페이스 정의서를 읽고 그대로 REST 클라이언트를 구현하며, 송신 전 검증·오류 코드 매핑·타임아웃 처리·연동 로그까지 갖출 수 있게 됩니다.

왜 중요한가

동기 REST 연동에서 진짜 어려운 것은 호출이 아니라 상대가 느리거나 이상할 때입니다. 연결 타임아웃을 길게 잡으면 상대 장애가 우리 장애가 되고, 오류 코드마다의 조치를 정하지 않으면 잘못된 데이터를 100번 재전송하거나 일시 장애에 업무가 멈춥니다. 그리고 송신 전 검증을 안 하면 상대 시스템 로그에 우리 오류가 쌓여 연동 담당자 간 감정 소모가 시작됩니다. '나쁜 데이터는 우리 쪽에서 막는다'는 연동 개발의 기본 예의입니다.

단계

/opt/lab/fixtures/eai/spec/IF-ORD-001.md 를 읽고 /root/eai/spec.csv 를 만듭니다. 첫 줄은 field,type,length,required. 정의서의 요청 항목을 필드명 오름차순으로 모두 옮깁니다. required 는 Y/N 입니다.
상대 시스템을 기동합니다. python3 /opt/lab/fixtures/eai/rest/partner_api.py 9200 (백그라운드) http://127.0.0.1:9200/health 응답을 /root/eai/health.json 에 저장합니다. status 값이 UP 이어야 합니다.
정의서대로 정상 주문 한 건을 POST /api/v1/orders 로 전송하고 응답을 /root/eai/res-ok.json 에 저장합니다. resultCode 가 0000 이어야 합니다.
/root/eai/validate.sh 를 만듭니다. 인자 하나(JSON 파일 경로)를 받아 정의서 기준으로 검증하고, 문제가 없으면 종료코드 0, 있으면 첫 줄에 사유를 출력하며 0 이 아닌 종료코드로 끝냅니다. 최소한 필수 누락 / 길이 초과 / 숫자 필드에 문자 세 가지를 잡아야 합니다.
/root/eai/errmap.csv 를 만듭니다. 첫 줄은 code,meaning,action. 정의서에 정의된 응답 코드를 모두 넣고, action 은 재시도, 중단, 통보 중 하나입니다.
http://127.0.0.1:9200/api/v1/slow 는 5초 지연 응답입니다. 2초 타임아웃으로 호출해 실패시키고, /root/eai/timeout.txt 를 만듭니다. 두 줄입니다.
```
exit_code=<curl 종료코드>
policy=<타임아웃 시 처리 방침 한 줄>
```
/root/eai/send.sh 를 만듭니다. 인자 하나(주문번호)를 받아 정의서대로 호출하고, 응답의 resultCode 를 첫 줄에 출력합니다. 0000 이면 종료코드 0, 그 외에는 0 이 아닌 종료코드로 끝냅니다.
/root/eai/if.log 를 만듭니다. 파이프(|)로 구분된 7개 필드, 3줄 이상입니다.
```
시각|인터페이스ID|송신시스템|수신시스템|응답코드|소요ms|추적ID
```
인터페이스 ID 는 IF-ORD-001 이고, 추적 ID 는 줄마다 서로 달라야 합니다.

참고

POST: curl -s -X POST -H 'Content-Type: application/json' -d @파일 <URL>
타임아웃: curl --max-time 2 ... / 종료코드는 $? 로 확인
소요 시간: curl -w '%{time_total}'
흔한 실수 1: HTTP 200 이면 성공이라고 판단하는 것. 업무 오류는 200 + resultCode 로 오는 경우가 많습니다.
흔한 실수 2: 길이 검증을 글자 수로 하는 것. 정의서가 바이트 기준이면 바이트로 세야 합니다.
흔한 실수 3: 추적 ID 를 고정값으로 쓰는 것. 호출마다 달라야 대조가 됩니다.

정의서에서 항목 추출

/opt/lab/fixtures/eai/spec/IF-ORD-001.md 를 읽고 /root/eai/spec.csv 를 만듭니다. 첫 줄은 field,type,length,required. 정의서의 요청 항목을 필드명 오름차순으로 모두 옮깁니다. required 는 Y/N 입니다.

정의서를 읽고 필수/선택, 타입, 길이를 표로 옮깁니다. 이 표가 다음 단계의 검증 로직 명세가 됩니다.

상대 시스템 기동과 확인

상대 시스템을 기동합니다. python3 /opt/lab/fixtures/eai/rest/partner_api.py 9200 (백그라운드) http://127.0.0.1:9200/health 응답을 /root/eai/health.json 에 저장합니다. status 값이 UP 이어야 합니다.

연동 개발의 첫 단계는 언제나 '상대가 살아 있는가'입니다. 헬스체크 엔드포인트가 있으면 그것부터 확인합니다.

정상 호출

정의서대로 정상 주문 한 건을 POST /api/v1/orders 로 전송하고 응답을 /root/eai/res-ok.json 에 저장합니다. resultCode 가 0000 이어야 합니다.

Content-Type 을 정확히 맞춰야 합니다. 응답 코드 필드가 HTTP 상태코드와 별개라는 점에 주의하세요 - 업무 오류는 HTTP 200 으로 오는 경우가 많습니다.

송신 전 검증 스크립트

/root/eai/validate.sh 를 만듭니다. 인자 하나(JSON 파일 경로)를 받아 정의서 기준으로 검증하고, 문제가 없으면 종료코드 0, 있으면 첫 줄에 사유를 출력하며 0 이 아닌 종료코드로 끝냅니다. 최소한 필수 누락 / 길이 초과 / 숫자 필드에 문자 세 가지를 잡아야 합니다.

나쁜 데이터는 우리 쪽에서 막는 것이 연동 개발의 기본입니다. 필수 누락, 길이 초과, 형식 불일치 세 가지를 구분해 사유를 출력하세요.

오류 코드 매핑표

/root/eai/errmap.csv 를 만듭니다. 첫 줄은 code,meaning,action. 정의서에 정의된 응답 코드를 모두 넣고, action 은 재시도, 중단, 통보 중 하나입니다.

각 코드에 '재시도/중단/통보' 중 무엇인지를 붙이는 것이 핵심입니다. 이 구분이 없으면 개발자가 전부 재시도하거나 전부 포기합니다.

타임아웃 재현

http://127.0.0.1:9200/api/v1/slow 는 5초 지연 응답입니다. 2초 타임아웃으로 호출해 실패시키고, /root/eai/timeout.txt 를 만듭니다. 두 줄입니다.

exit_code=<curl 종료코드>
policy=<타임아웃 시 처리 방침 한 줄>

curl 에는 전체 시간을 제한하는 옵션이 있습니다. 타임아웃 시 curl 이 어떤 종료코드를 내는지 확인해 두면 스크립트에서 분기할 수 있습니다.

연동 클라이언트 스크립트

/root/eai/send.sh 를 만듭니다. 인자 하나(주문번호)를 받아 정의서대로 호출하고, 응답의 resultCode 를 첫 줄에 출력합니다. 0000 이면 종료코드 0, 그 외에는 0 이 아닌 종료코드로 끝냅니다.

응답 코드에 따라 종료코드를 다르게 내야 호출한 쪽에서 판단할 수 있습니다. 성공과 실패를 모두 테스트해 보세요.

연동 로그 표준

/root/eai/if.log 를 만듭니다. 파이프(|)로 구분된 7개 필드, 3줄 이상입니다.

시각|인터페이스ID|송신시스템|수신시스템|응답코드|소요ms|추적ID

인터페이스 ID 는 IF-ORD-001 이고, 추적 ID 는 줄마다 서로 달라야 합니다.

추적 ID 는 상대 시스템 로그와 대조할 때 쓰는 유일한 열쇠입니다. 호출마다 달라야 하고, 요청에도 함께 실어 보내야 의미가 있습니다.