mock-server/mockserver-monorepo

MockServer – 유연한 모킹, 프록시, 혼돈 공학 서버

무엇인가요 – MockServer는 자체적으로 작동하는 HTTP(S) 서버이자 프록시로도 작동할 수 있습니다. 실제 하류 서비스가 실행 중이지 않아도, 들어오는 요청에 대한 기대 조건(규칙)을 정의하고 원하는 응답을 반환할 수 있습니다. 또한 실제 트래픽을 기록하고 실시간으로 편집할 수 있으며, 의도적으로 지연, 연결 끊기, 오류 코드를 주입하여 애플리케이션의 회복성(resilience)을 테스트할 수 있습니다.

AI/ML 프로젝트에서 중요한 이유 – 현대의 AI 서비스(예: LLM 챗 완성 API, 벡터 스토어 백엔드, 데이터 파이프라인 엔드포인트 등)는 일반적으로 HTTP/gRPC를 통해 접근됩니다. 개발 중에는 이러한 외부 서비스에 대한 안정적이고 제어 가능한 대체물이 필요할 때가 많습니다. 특히 다음의 경우에 유용합니다:

• 실제 서비스가 레이트 제한, 비용이 크거나 아직 배포되지 않았을 때.
• 오류 처리, 타임아웃, 잘못된 응답을 테스트하고 싶을 때.
• 재현 가능한 CI 테스트를 위해 기록된 요청/응답 흐름을 재생하고 싶을 때.
• OpenAI, Anthropic, Gemini, Bedrock, Azure OpenAI, Ollama, 또는 커스텀 MCP 기반 코딩 어시스턴트와 통신하는 AI 기반 애플리케이션을 개발 중일 때 – MockServer는 이러한 엔드포인트를 모방할 수 있으며, 스트리밍 응답까지 지원합니다.

주요 기능 (README에 설명됨)

기능	할 수 있는 일
다중 프로토콜 지원	HTTP/1.1, HTTPS, HTTP/2, 실험적 HTTP/3 (QUIC), gRPC, gRPC-Web, WebSockets, Raw TCP, JSON-RPC, Kafka 및 MQTT와 같은 메시지 브로커 프로토콜까지 지원. 연결의 첫 바이트에서 자동 감지됩니다.
모킹	메서드, 경로, 쿼리, 헤더, 쿠키, 본문(JSON, XML, JSONPath, XPath, 정규식, OpenAPI) 기반으로 기대 조건을 정의. 정적 본문, 템플릿 응답(Velocity, Mustache, JavaScript), 사용자 정의 콜백/웹훅을 반환할 수 있습니다.
프록시 및 기록	실제 트래픽을 전달하고, 요청/응답을 캡처하며, TLS 암호화된 트래픽을 검사하고, 인터랙티브 브레이크포인트에서 요청을 편집하거나 중단할 수 있습니다. 네트워크 트래픽용 디버거와 유사합니다.
혼돈 공학	지연, 느린 또는 끊어진 연결, 오류 상태 코드를 주입하여 시스템이 장애 상황에서 어떻게 동작하는지 확인할 수 있습니다.
LLM/AI 모킹	OpenAI, Anthropic, Gemini, Bedrock, Azure OpenAI, Ollama 등의 인기 챗 완성 API용 내장 모킹 엔드포인트(스트리밍 모드 포함)와 AI 코딩 어시스턴트 통합을 위한 MCP 서버 제공.
검증	테스트 실행 후 특정 요청이 수신되었는지, 어떤 순서로, 몇 번 수신되었는지 확인할 수 있습니다.
라이브 대시보드	/mockserver/dashboard에서 실시간 UI를 통해 기대 조건, 수신된 요청, 로그를 확인할 수 있습니다.
클라이언트 라이브러리	Java, JavaScript/Node, Python, Ruby, Go, PHP, .NET, Rust 공식 클라이언트 제공. JUnit, Spring, Testcontainers 통합도 지원.
배포 옵션	Docker 컨테이너, Homebrew (mockserver CLI), 일반 JAR/WAR, Kubernetes용 공식 Helm 차트, 또는 유닛 테스트에 Netty 기반 서버를 직접 내장할 수 있습니다.

일반 워크플로우 (60초 빠른 시작)

1. 시작 – 서버 실행 (docker run -d -p 1080:1080 mockserver/mockserver).
2. 기대 조건 생성 – 컨트롤 플레인 엔드포인트 /mockserver/expectation에 간단한 curl POST로 설정 – 예: GET /hello를 200 응답(“Hello World” 포함)으로 매핑.
3. 호출 – 모킹된 엔드포인트 호출 (curl http://localhost:1080/hello)하여 설정된 응답 수신.

이 모든 작업은 스크립트로 자동화 가능하며, CI 파이프라인에서 제어하거나 Postman, Bruno, 커뮤니티 제작 React 관리자 UI와 같은 UI 도구로 관리할 수 있습니다.

AI 개발 파이프라인에서의 활용 예시

• OpenAI의 /v1/chat/completions을 호출하는 코드의 유닛/통합 테스트 – 실제 서비스를, 결정론적인 JSON 페이로드 또는 스트리밍 청크 시퀀스를 반환하는 MockServer 기대 조건으로 대체.
• 성능/회복성 테스트 – 모든 LLM 요청에 5초 지연을 주입하여 프론트엔드가 느린 응답을 어떻게 처리하는지 확인.
• 기록 및 재생 – 프로덕션 LLM 게이트웨이에서의 실제 트래픽을 캡처한 후, 로컬에서 디버깅을 위해 재생.
• 계약 검증 – 자신의 AI 마이크로서비스의 OpenAPI 사양에서 기대 조건을 자동 생성하고, 구현이 사양을 따르는지 검증.

설치 및 생태계

• Docker – docker run -d --rm -p 1080:1080 mockserver/mockserver
• Homebrew – brew install mockserver && mockserver run --port 1080
• Kubernetes – Helm 차트 mockserver/mockserver (OCI 호스팅)를 사용해 클러스터 배포 가능.
• 언어 클라이언트 – Maven/Gradle 아티팩트 (mockserver-netty-no-dependencies, mockserver-client-java 등), NPM 패키지 (mockserver-node, mockserver-client), PyPI (mockserver-client), RubyGems, Go 모듈, NuGet, crates.io.

프로젝트 건강 상태 – 활발히 유지 관리 중 (최신 버전 7.6.0은 2026년 6월 출시), Buildkite를 통한 CI, 오픈 이슈 트래커, 디스커션 포럼, GitHub의 로드맵 프로젝트 존재. Java 17+ 필요 (Docker 이미지에는 런타임이 포함됨).

---

결론 – MockServer는 프로덕션 수준의, 프로토콜에 종속되지 않는 모킹 및 프록시 서버로, HTTP 기반의 모든 API(급속도로 확장되는 LLM 챗 완성 서비스군 포함)를 시뮬레이션, 기록, 스트레스 테스트하는 데 매우 유용합니다. AI 기반 애플리케이션을 개발, 테스트, 벤치마크하는 모든 사람에게 강력한 도구입니다.