WSDL — 기계가 읽는 서비스 계약으로 통합을 시작하는 법

REST API는 코드부터 짜고 스펙 문서를 나중에 붙이는 경우가 흔하지만, 금융·통신 코어 시스템 연계에서는 순서가 반대다. 인터페이스를 먼저 문서로 고정하고, 그 문서에서 코드를 뽑아낸다. 이 계약 문서의 역할을 하는 것이 WSDL(Web Service Description Language)이다. 서비스가 무엇을 하고(operations), 어떤 메시지를 주고받으며(types/messages), 어떤 프로토콜로 전송되고(bindings), 어디서 접근 가능한지(services/ports)를 기계가 읽을 수 있는 XML로 못 박는다.

1.1이 표준, 2.0은 정교하지만

WSDL 1.1은 산업계에서 사실상 표준으로 광범위하게 쓰이고, WSDL 2.0은 모델을 정교화하고 HTTP 바인딩을 개선했지만 채택률은 제한적이다. SOAP, WS-Security, WS-Policy, WS-Addressing 같은 WS-* 사양과 결합해 강한 형식과 정책 기반 상호운용성을 제공하는 생태계를 이룬다.

여러 요소로 나뉜 계약

Types는 XML Schema로 서비스 메시지의 데이터 타입을 정의해 강한 형식을 보장하고, 네임스페이스를 나눠 대규모 도메인 모델을 관리할 수 있게 한다. PortType/Interface와 Operations는 서비스가 제공하는 작업의 시그니처(요청/응답, 단방향 등)를 정의하고, 메시지 교환 패턴과 SOAP Fault로 표현되는 예외 계약을 명시한다. Binding은 PortType을 실제 전송 규약, 주로 SOAP/HTTP(S)에 매핑하고 인코딩 스타일·헤더 처리·동기/비동기 패턴 같은 운용 세부를 정한다. Service/Port는 실제 엔드포인트 URL과 네트워크 접근 속성을 정의해 개발·스테이징·운영 환경을 포트 단위로 분리한다. 마지막으로 wsdl:import와 extensibility element가 모듈화와 버전 발전을 뒷받침하고, WS-Policy 첨부로 보안·신뢰성·트랜잭션 같은 교차 관심사를 정책화할 수 있다.

요구사항에서 배포까지, 계약이 흘러가는 길

입력은 비즈니스 요구, 데이터 사전, 표준 코드 체계다. 처리 단계는 XSD 도메인 모델링 → WSDL 인터페이스/바인딩 설계 → 코드 생성기(stub/skeleton) → 정책/보안 적용 순으로 이어지고, 출력은 서버/클라이언트 산출물, 테스트 케이스, 버전·변경 이력 같은 거버넌스 산출물이다.

⤢✕

스키마 검증에 실패하면 SOAP Fault가 반환되고 보통 HTTP 500으로 매핑된다. 재시도 정책, idempotency 키, 타임아웃, 회로 차단기를 함께 구성해야 실패가 연쇄로 번지지 않는다.

계약이 실제로 걸리는 자리

대규모 엔터프라이즈 통합에서는 코어 뱅킹, 보험 청구, 통신 과금계 시스템 사이의 상호운용을 강한 스키마 기반 메시지 검증으로 지탱한다. B2B 연계와 규제 준수 영역에서는 전자세금계산서, 공공기관 표준 인터페이스, HL7/NIEM 같은 표준 스키마와 연계하고 WS-Security/WS-Policy로 감사 추적과 정책을 집행한다. 레거시 시스템 보호를 위해서는 메인프레임·ESB 앞단에 SOAP/WSDL 페사드를 두고, 네임스페이스 버전 전략으로 변경을 최소화하며 호환성을 유지한다. 테스트 자동화·거버넌스 측면에서는 계약 기반 테스트(Contract Test), 스키마 퍼징, WSDL diff 기반 영향분석을 레지스트리·리포지토리와 CI 파이프라인에 연결해 배포를 통제한다.

설계에서 남는 트레이드오프

계약 우선 설계와 xsd:import를 통한 도메인 모델 분리, 명확한 네임스페이스 버전 관리가 기본이지만, 강한 형식과 정책의 이점은 초기 설계 비용과 학습 곡선 증가로 상쇄된다. 대용량 바이너리는 MTOM/XOP로 최적화하고 Keep-Alive/풀링을 활성화하지만, WS-Security 서명·암호화는 오버헤드를 늘리고 헤더 크기에 따라 지연이 커진다. 보안은 TLS와 WS-Security(서명·암호화·Timestamp), 시계 동기화, 재생 공격 방지가 기본이며 키 관리와 정책 호환성 시험, 상호 TLS 적용 시 운영 복잡성 증가를 감수해야 한다. 운영에서는 코릴레이션 ID, 메시지 샘플링, 스키마/정책 버전 메타데이터 로깅으로 관측성을 확보하고, 타임아웃·재시도·회로 차단기로 장애 전파를 막는다. 호환성은 WS-I Profile 기반 상호운용 테스트와 SOAP 1.1/1.2, 바인딩 옵션 차이 검증, 타 벤더 스택과의 정책·헤더 정합성 사전 테스트로 확보한다.

Apache CXF로 계약을 코드로 바꾸기

환경은 Java 17, Apache CXF 3.5.x, Maven 3.9.x를 전제로 한다. 아래는 WSDL 스켈레톤 예시다.

<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
             xmlns:tns="http://example.com/hello"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             targetNamespace="http://example.com/hello"
             name="HelloService">
  <types>
    <xsd:schema targetNamespace="http://example.com/hello">
      <xsd:element name="SayHelloRequest" type="xsd:string"/>
      <xsd:element name="SayHelloResponse" type="xsd:string"/>
    </xsd:schema>
  </types>
  <message name="SayHelloInput">
    <part name="parameters" element="tns:SayHelloRequest"/>
  </message>
  <message name="SayHelloOutput">
    <part name="parameters" element="tns:SayHelloResponse"/>
  </message>
  <portType name="HelloPortType">
    <operation name="SayHello">
      <input message="tns:SayHelloInput"/>
      <output message="tns:SayHelloOutput"/>
    </operation>
  </portType>
  <binding name="HelloBinding" type="tns:HelloPortType">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
    <operation name="SayHello">
      <soap:operation soapAction="urn:SayHello"/>
      <input><soap:body use="literal"/></input>
      <output><soap:body use="literal"/></output>
    </operation>
  </binding>
  <service name="HelloService">
    <port name="HelloPort" binding="tns:HelloBinding">
      <soap:address location="https://api.example.com/hello"/>
    </port>
  </service>
</definitions>

이 계약에서 클라이언트 스텁과 서버 스켈레톤을 동시에 뽑아내려면 Maven 플러그인이나 CLI를 쓴다.

# 클라이언트 스텁/서버 스켈레톤 동시 생성
cxf-codegen-plugin # Maven 플러그인 권장
# 또는 CLI
wsdl2java -d src/main/java -p com.example.hello -client -server src/main/resources/Hello.wsdl

테스트 단계에서는 스키마 검증(javax.xml.validation)을 활성화하고, SOAP Fault 매핑을 확인하며, WS-Policy로 부착한 보안 정책까지 상호운용 테스트로 검증한다.

WSDL(SOAP)과 OpenAPI(REST)를 나란히 보면

항목	WSDL(SOAP)	OpenAPI(REST)
성능	XML 파싱 및 WS-Security로 오버헤드 증가 경향	JSON/HTTP로 경량, 지연·CPU 부담 낮음
확장성	스키마/정책로 대규모 거버넌스 유리	수평 확장 쉬우나 계약 강제력은 상대적으로 약함
일관성	강한 형식·정책 기반 일관성 확보	관례 중심, 일관성은 팀 규율에 좌우
안정성	트랜잭션/신뢰성 메시징 옵션 제공	단순·경량, 안정성은 별도 설계로 보완
운영 편의	코드 생성·정책 관리 체계적이나 복잡도 존재	툴링 광범위, 디버깅·운영 단순

결함률과 리드타임으로 본 도입 효과

스키마 검증과 계약 테스트를 도입하면 통합 결함률이 30~~50% 줄어드는 품질 향상 효과가 보고된다. 코드 생성 자동화는 초기 통합 개발 리드타임을 20~~40% 단축시키고, 표준화된 변경관리는 회귀 영향을 최소화한다. 강한 형식과 정책 일관성은 다벤더 환경의 상호운용성을 보장하고, 표준화된 모니터링·로깅은 진단 시간을 줄인다.

레거시 보호와 규제 준수가 걸렸을 때

WSDL은 표준 기반 계약 우선 통합의 핵심 도구다. 강한 형식, 정책 부착, 상호운용성이 중요한 엔터프라이즈 환경에 잘 맞고, 초기 복잡도와 성능 오버헤드는 도구·정책·아키텍처 표준화로 상쇄할 수 있다. 레거시 보호, 규제 준수, 대규모 B2B 연계가 걸린 통합이라면 여전히 우선 고려 대상이다.