인터페이스 설계 확인

구현 전에 설계를 다시 보는 이유

소프트웨어 설계 과목에서 인터페이스 요구사항을 모으고(인터페이스 요구사항 확인), 연결 대상을 찾고(인터페이스 대상 식별), 송수신 방식과 데이터 모양을 정했습니다(인터페이스 상세 설계). 이제 소프트웨어 개발 과목에서는 그 설계를 실제로 만들고, 제대로 동작하는지 검증하는 쪽으로 넘어갑니다. 그 첫걸음이 인터페이스 설계 확인입니다.

설계를 다시 확인하는 이유는 간단합니다. 설계 문서는 대개 개발이 본격적으로 시작되기 전에 쓰이고, 그 사이에 상대 시스템의 사정이 바뀌거나, 문서에서 빠진 부분이 남아 있는 경우가 많습니다. 조립식 가구를 맞추기 전에 설명서와 부품 목록을 한 번 대조해 보는 것과 비슷합니다. 나사가 하나 모자란 것을 조립 중간에 알게 되면 이미 붙인 판을 다시 떼어야 합니다.

이 항목에서 확인하는 것은 두 가지입니다. 하나는 각 인터페이스가 무슨 일을 하는 연결인지(인터페이스 기능 확인), 다른 하나는 그 연결로 오가는 데이터가 양쪽에서 같은 기준으로 정의되어 있는지(데이터 표준 확인)입니다.

무엇을 보고 확인하나: 인터페이스 설계 문서

확인의 기준이 되는 문서는 설계 단계에서 만든 인터페이스 목록과 인터페이스 정의서(인터페이스 설계서라고도 부름)입니다. 목록은 전체 인터페이스를 한눈에 보여 주는 지도이고, 정의서는 인터페이스 하나하나의 송수신 시스템, 방식, 주기, 데이터 항목, 오류 처리를 자세히 적은 문서입니다.

문서를 읽을 때는 두 가지 측면을 나눠 보면 빠뜨리는 것이 줄어듭니다. 하나는 정적인 측면으로, 어떤 데이터 항목이 어떤 구조로 오가는지처럼 시간과 상관없이 정해진 모양입니다. 다른 하나는 동적인 측면으로, 누가 먼저 요청하고 누가 응답하며 어떤 순서로 처리가 이어지는지 같은 흐름입니다. 동적인 흐름은 시퀀스 다이어그램처럼 시간 순서를 보여 주는 그림으로 표현하면 이해하기 쉽습니다. 시험 자료에서는 인터페이스 설계서를 항목을 표로 정리한 일반적인 인터페이스 설계서와, 정적·동적 모형을 그림으로 보여 주는 인터페이스 설계서의 두 유형으로 나누기도 합니다.

구조만 보고 흐름을 안 보면 '데이터 모양은 맞는데 상대가 언제 받아 가는지 아무도 모르는' 상황이 생기고, 흐름만 보고 구조를 안 보면 순서는 맞는데 항목 길이가 어긋나는 상황이 생깁니다. 둘을 함께 봐야 설계의 빈틈이 드러납니다.

인터페이스 기능 확인: 이 연결은 무슨 일을 하나

인터페이스 기능 확인은 각 인터페이스가 맡은 역할을 구체적으로 확인하는 일입니다. 확인할 질문은 대략 이렇습니다. 어떤 업무를 위한 연결인가, 어느 시스템이 보내고 어느 시스템이 받는가, 실시간인가 배치인가, 얼마나 자주 오가는가, 무엇이 전송을 시작시키는가, 받은 쪽은 데이터를 받아 무엇을 하는가.

문서에 적힌 내용을 실제 시스템과 맞춰 보는 것도 중요합니다. 정의서에는 '수신 시스템이 주문 테이블에 반영한다'고 적혀 있는데, 실제 수신 시스템에는 그 테이블이 아직 없거나 이름이 바뀌어 있을 수 있습니다. 외부 시스템이라면 상대 담당자와 함께 정의서를 넘겨 보며 서로 이해한 내용이 같은지 확인합니다.

기능을 확인하다 보면 설계에 빠진 기능이 발견되기도 합니다. 예를 들어 데이터를 보내는 기능은 있는데, 같은 데이터를 두 번 받았을 때 어떻게 할지(중복 수신 처리)는 정해져 있지 않은 경우입니다. 이런 빈칸은 이 단계에서 채워 두어야 구현 중에 개발자마다 다른 방식으로 메우는 일을 막을 수 있습니다.

내부·외부 모듈이 함께 쓰는 공통 기능 찾기

인터페이스를 여러 개 살펴보면 겉모습은 달라도 하는 일이 겹치는 부분이 보입니다. 데이터를 약속한 형식으로 바꾸는 일, 전송 기록을 남기는 일, 실패하면 다시 보내는 일, 오류 코드를 만들어 알리는 일 등은 대부분의 인터페이스에 공통으로 필요합니다.

이런 기능은 인터페이스마다 따로 만들지 않고 공통 기능으로 묶어 한 번만 만드는 것이 좋습니다. 소프트웨어 설계 과목의 공통 모듈 설계에서 배운 재사용, 모듈화 원칙이 여기서도 그대로 적용됩니다. 공통으로 만들면 오류 처리 방식이 인터페이스마다 제각각이 되는 일도 막을 수 있습니다.

공통 기능을 찾을 때는 내부 모듈 사이의 연결과 외부 시스템과의 연결을 모두 놓고 봅니다. 외부 연결은 상대 규칙을 따라야 해서 형식이 다를 수 있지만, 로그 기록이나 재전송처럼 우리 쪽에서 처리하는 부분은 내부 연결과 같은 공통 기능을 쓸 수 있는 경우가 많습니다.

데이터 표준 확인: 같은 데이터는 같은 모양으로

데이터 표준은 인터페이스로 오가는 데이터 항목을 양쪽이 어떤 이름, 자료형, 길이, 허용 값으로 쓸지 정한 공통 기준입니다. 같은 '고객번호'라도 한쪽은 숫자 10자리, 다른 쪽은 문자 12자리로 다루고 있다면 그대로 연결할 수 없습니다. 데이터 표준 확인은 이런 차이를 찾아내고, 연결에 쓸 기준을 하나로 정하는 일입니다.

표준을 정할 때는 먼저 송신 쪽과 수신 쪽이 각각 쓰는 데이터를 나란히 놓고, 양쪽에 공통으로 있는 항목과 한쪽에만 있는 항목을 가려냅니다. 그다음 공통 항목마다 연결에 쓸 표준 이름, 자료형, 길이, 필수 여부, 허용되는 코드값을 정합니다. 날짜를 '20261012'처럼 쓸지 '2026-10-12'처럼 쓸지, 금액에 소수점을 둘지 같은 세부 형식도 이때 못 박아 둡니다.

주고받는 메시지 전체의 구조(공통부·개별부·종료부)와 표현 형식(JSON, XML 등)은 인터페이스 상세 설계의 데이터 명세화에서 정한 내용이니 그쪽을 참고하면 됩니다. 이 단계에서는 그렇게 정한 구조 안에 들어가는 항목 하나하나가 표준과 맞는지를 확인하는 데 집중합니다.

표준이 어긋날 때: 변환 규칙과 코드 매핑

현실에서는 양쪽 시스템을 모두 표준에 맞게 고칠 수 없는 경우가 많습니다. 특히 외부 시스템이나 오래 운영된 시스템은 내부 데이터 구조를 바꾸기 어렵습니다. 이럴 때는 각 시스템의 데이터는 그대로 두고, 인터페이스를 지나는 순간에만 표준 형식으로 바꿔 주는 변환 규칙을 정합니다.

코드값이 다른 경우에는 코드 매핑표를 만듭니다. 한쪽은 성별을 'M, F'로, 다른 쪽은 '1, 2'로 쓴다면 어떤 값이 어떤 값에 대응하는지 표로 정리해 두는 것입니다. 이때 한쪽에만 있는 코드값(예: '미확인')을 받았을 때 어떻게 처리할지도 함께 정해야 합니다. 이 부분이 빠지면 운영 중에 처음 보는 값이 들어와 연결이 멈추기 쉽습니다.

변환을 송신 쪽, 수신 쪽, 중계 서버 중 어디에서 할지도 정해 둡니다. 어디서 하든 한 곳에서만 하도록 정하는 것이 중요합니다. 양쪽에서 모두 변환하면 같은 값이 두 번 바뀌는 사고가 생길 수 있습니다.

확인 결과를 구현의 기준으로

확인 과정에서 고칠 점이 나오면 구두로 합의하고 넘어가지 않고 설계 문서에 반영합니다. 그래야 구현하는 사람, 테스트하는 사람, 상대 시스템 담당자가 모두 같은 문서를 보고 일할 수 있습니다.

이렇게 확정한 기능 정의와 데이터 표준은 다음 단계의 출발점이 됩니다. 인터페이스 기능 구현에서는 이 기준대로 실제 코드를 만들고 보안을 갖추며, 인터페이스 구현 검증에서는 만들어진 결과가 이 기준과 같은지 확인합니다. 결국 설계 확인은 뒤의 두 단계가 무엇을 기준으로 삼을지 미리 분명하게 해 두는 작업입니다.