인터페이스 정의서대로 REST 연동 구현하기

목표

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

왜 중요한가

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

단계

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

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

7. /root/eai/send.sh 를 만듭니다. 인자 하나(주문번호)를 받아
정의서대로 호출하고, 응답의 resultCode 를 첫 줄에 출력합니다.
0000 이면 종료코드 0, 그 외에는 0 이 아닌 종료코드로 끝냅니다.
8. /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 를 고정값으로 쓰는 것. 호출마다 달라야 대조가 됩니다.

단계 8개

정의서에서 항목 추출
상대 시스템 기동과 확인
정상 호출
송신 전 검증 스크립트
오류 코드 매핑표
타임아웃 재현
연동 클라이언트 스크립트
연동 로그 표준