Static AST 분석을 통한 OpenAPI Spec-Implementation 간 Semantic Drift 원천 차단

Your OpenAPI spec says `object`. Your code returns `array`. Spectral won't catch it.

HAYATO YOKOSHIMA2026년 4월 17일6분intermediate

AI 요약

Context

Spectral, Prism 등 기존 도구는 Spec 간의 일관성만 검증하여 실제 구현 코드와의 불일치를 발견하지 못하는 한계 존재. Spec은 Object로 정의했으나 코드가 Array를 반환하는 식의 Semantic Drift 발생 시 런타임 TypeError 유발 및 테스트 누락 위험 상존.

Technical Solution

Python AST(Abstract Syntax Tree) 분석 기반의 Static Analysis 구조 설계
OpenAPI Spec 내 2xx Response의 type 필드를 추출하여 기대 Shape 정의
소스 코드 내 Flask/FastAPI Route Decorator를 식별하여 핸들러 함수 매핑
return 문 내부의 데이터 구조를 분석하여 실제 반환 Shape를 Object 또는 Array로 분류
정의된 Spec Shape와 추출된 Implementation Shape 간의 불일치를 비교하여 D1 Shape Divergence 검출
분석 결과의 재현성 보장을 위해 Spec과 소스 코드 아카이브에 대한 SHA-256 해시값 기록

실천 포인트

- API 변경 시 Spec 업데이트 누락 여부를 검증하는 Static Analysis 단계 도입 검토 - 런타임 에러 방지를 위해 Return Shape(Object vs Array)의 일치 여부를 우선적으로 검증 - 복잡한 조건문이나 DB 쿼리 결과로 인한 'Indeterminate' 상태를 구분하여 분석 범위 설정 - CI/CD 파이프라인 내 Pre-merge 체크 단계에 Spec-Code 정합성 검사 추가

태그

#Semantic Drift #Python #OpenAPI #AST #Static Analysis

원문 읽기