7988cd8078
- Fake 서비스 구현 표준 (네이밍, 상속, 바인딩, 데이터 품질) - 환경별 적용 전략 (운영 금지, 데모/개발 권장) - 바로빌 참조 구현 연결 - INDEX.md 등록
11 KiB
11 KiB
외부 API Fake 서비스 정책
작성일: 2026-03-22 상태: 설계 확정
1. 개요
1.1 목적
외부 API(SOAP, REST 등)와 연동하는 서비스에 대해, 실제 외부 호출 없이 동일한 응답을 시뮬레이션하는 Fake 서비스 구현 표준을 정의한다.
1.2 배경
SAM은 바로빌(전자세금계산서), 택배조회, 전자결제 등 외부 API 연동이 점점 늘어나고 있다. 모든 외부 연동에 대해 다음 상황이 발생한다:
- 데모 테넌트에서 영업 시연 시 실제 계정/인증서가 없음
- React 프론트엔드 개발 시 외부 서비스 의존 없이 UI 흐름 테스트 필요
- 자동화 테스트에서 외부 API 호출은 비용과 불안정성 유발
- 바로빌처럼 테스트 모드가 있는 서비스도 있지만, API 프로젝트에서는 SOAP 연결 자체가 불필요한 경우가 있음
1.3 핵심 원칙
✅ 외부 API 연동 서비스는 반드시 Fake 대체 가능하도록 설계한다
✅ Fake 서비스는 실제 서비스를 상속(extends)하여 동일한 인터페이스를 보장한다
✅ 환경변수 한 줄로 Real ↔ Fake 전환이 가능해야 한다
✅ Fake 데이터는 현실적이어야 한다 (영업 시연에 사용 가능한 수준)
2. 용어 정의
소프트웨어 엔지니어링의 Test Double 분류에서 SAM이 채택하는 패턴:
| 용어 | 설명 | SAM 적용 |
|---|---|---|
| Fake | 실제 동작하는 간소화된 구현 (현실적 데이터 반환) | ✅ 채택 |
| Stub | 고정된 응답만 반환 (입력과 무관) | 미채택 |
| Mock | 호출 여부·횟수까지 검증 (테스트 전용) | 미채택 |
SAM에서는 "Fake"를 표준 용어로 사용한다. 클래스명, 설정키, 문서 모두
Fake로 통일한다.
3. 아키텍처
3.1 구조 다이어그램
┌─────────────────────────────────────────────────────┐
│ AppServiceProvider (Laravel 서비스 컨테이너) │
│ │
│ if (config('services.xxx.fake_mode')) │
│ bind(RealService → FakeService) │
│ │
│ Controller / 다른 Service │
│ └── DI 주입: RealService (타입힌트) │
│ └── 실제로는 FakeService가 주입됨 │
└─────────────────────────────────────────────────────┘
┌──────────────────┐ ┌──────────────────┐
│ RealService │ │ FakeService │
│ │ │ extends Real │
│ 실제 외부 API │ │ │
│ 호출 (SOAP/REST)│ │ 샘플 데이터 반환 │
│ │ │ (외부 호출 없음) │
└──────────────────┘ └──────────────────┘
3.2 전환 메커니즘
.env 파일 config/services.php AppServiceProvider
┌──────────────────┐ ┌──────────────────────┐ ┌──────────────────┐
│ XXX_FAKE_MODE= │───→ │ 'xxx' => [ │───→ │ if (fake_mode) │
│ true / false │ │ 'fake_mode' => │ │ bind(Real→Fake)│
└──────────────────┘ │ env('XXX_FAKE_ │ └──────────────────┘
│ MODE', false), │
│ ], │
└──────────────────────┘
4. 구현 규칙
R1. 파일 구조 및 네이밍
app/Services/
{ServiceName}/
{ServiceName}Service.php ← 실제 외부 API 호출
{ServiceName}FakeService.php ← Fake (extends Real)
예시:
app/Services/
Barobill/
BarobillSoapService.php ← 실제 SOAP 호출
BarobillFakeSoapService.php ← Fake SOAP 응답
Delivery/
DeliveryService.php ← 실제 택배 API
DeliveryFakeService.php ← Fake 배송 추적
Payment/
PaymentService.php ← 실제 결제 API
PaymentFakeService.php ← Fake 결제 응답
R2. Fake 서비스는 Real 서비스를 상속한다
// ✅ 올바른 패턴
class BarobillFakeSoapService extends BarobillSoapService
{
// Real의 모든 public 메서드를 오버라이드
}
// ❌ 금지: 별도 인터페이스나 독립 클래스로 구현
class BarobillFakeService implements BarobillInterface { ... }
이유: 상속 방식은 Real 서비스에 새 메서드가 추가되어도 Fake에서 오버라이드하지 않으면 Real 메서드가 호출된다. 인터페이스 방식은 모든 메서드를 구현해야 하므로 유지보수 부담이 크다.
R3. 환경변수 및 설정 규칙
// config/services.php
'barobill' => [
// ... 기존 설정 ...
'fake_mode' => env('BAROBILL_FAKE_MODE', false), // ✅ 기본값 false
],
'delivery' => [
// ... 기존 설정 ...
'fake_mode' => env('DELIVERY_FAKE_MODE', false),
],
네이밍 규칙:
- 환경변수:
{SERVICE_NAME}_FAKE_MODE(대문자 스네이크) - config 키:
services.{name}.fake_mode - 기본값:
false(운영 환경에서 실수로 Fake가 활성화되지 않도록)
R4. AppServiceProvider 바인딩
// app/Providers/AppServiceProvider.php → register()
// 바로빌 Fake 모드
if (config('services.barobill.fake_mode')) {
$this->app->bind(
\App\Services\Barobill\BarobillSoapService::class,
\App\Services\Barobill\BarobillFakeSoapService::class
);
}
// 택배 Fake 모드 (향후)
if (config('services.delivery.fake_mode')) {
$this->app->bind(
\App\Services\Delivery\DeliveryService::class,
\App\Services\Delivery\DeliveryFakeService::class
);
}
주의: 바인딩은 반드시
register()메서드에 작성한다 (boot()아님).
R5. Fake 데이터 품질 기준
| 기준 | 설명 | 예시 |
|---|---|---|
| 현실적 | 실제 데이터와 유사한 형태·값 | 은행명: "신한은행", 계좌: "110-123-456789" |
| 다양성 | 최소 2건 이상의 샘플 | 계좌 2개, 카드 2개, 거래내역 복수 건 |
| 일관성 | 연관 데이터 간 정합성 유지 | 카드 거래의 합계 = 월 사용액 |
| 날짜 반응 | 조회 기간에 따라 동적 데이터 생성 | 요청한 날짜 범위 내 거래 생성 |
| 한글 | 한국 비즈니스 맥락에 맞는 데이터 | 상호: "(주)테스트상사", 품목: "블라인드 외 1건" |
❌ 빈 배열 반환: return [];
❌ 의미 없는 더미: 'name' => 'test', 'amount' => 0
✅ 현실적 샘플: 'name' => '(주)테스트상사', 'amount' => 125000
R6. Fake 서비스 DocBlock 필수
/**
* 바로빌 Fake SOAP 서비스
*
* 실제 SOAP 호출 없이 현실적인 샘플 데이터를 반환한다.
* .env에서 BAROBILL_FAKE_MODE=true 설정 시 자동 전환.
*
* 용도:
* - 바로빌 계정/인증서 없이 전체 API 흐름 테스트
* - React 프론트엔드 독립 개발
* - 데모 테넌트 시연
* - 자동화 테스트
*/
class BarobillFakeSoapService extends BarobillSoapService
5. 사용 전략
5.1 환경별 Fake 적용 가이드
| 환경 | Fake 설정 | 이유 |
|---|---|---|
| 운영 서버 | false (절대 금지) |
실제 데이터 처리 필수 |
| 개발 서버 | 서비스별 판단 | 테스트 모드가 있으면 Real 사용 가능 |
| 로컬 개발 | true 권장 |
외부 의존 없이 개발 |
| 데모 테넌트 | true |
영업 시연용 |
| 자동화 테스트 | true |
비용 절감, 안정성 |
5.2 데모 테넌트와의 연계
SAM의 데모 테넌트 3-Tier 시스템과 결합하면:
데모 테넌트 (샘플 데이터)
+ Fake 바로빌 (계좌/카드/세금계산서)
+ Fake 택배 (배송 추적)
+ Fake 결제 (PG 결제)
─────────────────────────
= 완전한 영업 시연 환경
고객 입장에서는 모든 외부 연동이 실제 동작하는 것처럼 보인다.
5.3 Real vs Fake 판단 기준
새로운 외부 API 연동 추가 시:
외부 API 연동 추가
│
├─ 무료 테스트 모드 제공? ──→ Real 사용 가능 (Fake 선택적)
│ 예: 바로빌 테스트 모드
│
├─ 호출당 과금? ──→ Fake 필수
│ 예: SMS 발송, 우편 발송
│
├─ 인증서/계약 필요? ──→ Fake 필수
│ 예: 공인인증, 전자서명
│
└─ 네트워크 의존? ──→ Fake 권장
예: 외부 REST API
6. 운영 안전장치
6.1 운영 환경 보호
❌ 운영 서버 .env에 FAKE_MODE=true 설정 금지
✅ config 기본값은 반드시 false
✅ 운영 배포 시 FAKE_MODE 관련 환경변수 미설정 확인
6.2 Fake 모드 감지 API
모든 Fake 서비스는 checkConfiguration() 등의 상태 확인 메서드에서 Fake 여부를 반환한다:
public function checkConfiguration(): array
{
return [
// ... 기존 설정 ...
'fake_mode' => true, // ✅ Fake 여부 명시
];
}
관리자 화면에서 현재 Fake 모드 여부를 확인할 수 있어야 한다.
7. 체크리스트
새 외부 API 연동 시
- Real 서비스 클래스 구현 (
{Name}Service.php) - Fake 서비스 클래스 구현 (
{Name}FakeService.php extends {Name}Service) config/services.php에fake_mode설정 추가AppServiceProvider::register()에 바인딩 조건 추가- Fake 데이터 품질 확인 (현실적, 다양성, 한글)
- 운영
.env에FAKE_MODE미설정 확인
기존 Fake 서비스 수정 시
- Real 서비스에 새 메서드 추가 → Fake에도 오버라이드 필요 여부 확인
- 샘플 데이터 현실성 유지
8. 참조 구현 (바로빌)
현재 구현된 바로빌 Fake가 이 정책의 참조 구현(Reference Implementation) 이다:
| 항목 | 파일 |
|---|---|
| Real 서비스 | api/app/Services/Barobill/BarobillSoapService.php |
| Fake 서비스 | api/app/Services/Barobill/BarobillFakeSoapService.php |
| 설정 | api/config/services.php → barobill.fake_mode |
| 바인딩 | api/app/Providers/AppServiceProvider.php → register() |
| 환경변수 | BAROBILL_FAKE_MODE=true |
관련 문서
- 바로빌 시스템 — SOAP 연동, 테스트/운영 모드
- 바로빌 API SOAP — 49+7 메서드 레퍼런스
- API 개발 규칙 — Service-First 아키텍처
- 데모 테넌트 — 3-Tier 데모 시스템 (해당 시)
최종 업데이트: 2026-03-22