docs: [standards] 외부 API Fake 서비스 정책 문서 추가
- Fake 서비스 구현 표준 (네이밍, 상속, 바인딩, 데이터 품질) - 환경별 적용 전략 (운영 금지, 데모/개발 권장) - 바로빌 참조 구현 연결 - INDEX.md 등록
This commit is contained in:
김보곤
2
INDEX.md
2
INDEX.md
@@ -55,6 +55,7 @@
|
||||
| 서버 접근/백업 | `system/server-access-management.md` | 계정, 권한, 백업, 리플리케이션 |
|
||||
| 이관 작업 | `system/migration-status.md` | MNG→API+React 이관 현황, 우선순위, 로드맵 |
|
||||
| API 개선 로드맵 | `system/api-analysis-report.md` | API 구조 분석, 기술 부채 8건, P1~P3 개선 계획 |
|
||||
| 외부 API Fake | `dev/standards/fake-service-policy.md` | 외부 API Fake 서비스 구현 표준 (네이밍, 바인딩, 데이터 품질) |
|
||||
| MES | `projects/mes/README.md` | MES 프로젝트 |
|
||||
|
||||
---
|
||||
@@ -159,6 +160,7 @@ DB 도메인별:
|
||||
| [email-policy.md](dev/standards/email-policy.md) | 멀티테넌시 이메일 발송 정책 |
|
||||
| [blade-react-policy.md](dev/standards/blade-react-policy.md) | Blade + React(JSX) 혼용 시 이중 중괄호 충돌 방지 정책 |
|
||||
| [bending-item-code-policy.md](standards/bending-item-code-policy.md) | 절곡 재공품 품목코드 체계 (BD-XX-nn, 2계층 구조) |
|
||||
| [fake-service-policy.md](dev/standards/fake-service-policy.md) | 외부 API Fake 서비스 정책 (네이밍, 바인딩, 데이터 품질, 영업 시연) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
327
dev/standards/fake-service-policy.md
Normal file
327
dev/standards/fake-service-policy.md
Normal file
@@ -0,0 +1,327 @@
|
||||
# 외부 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 서비스를 상속한다
|
||||
|
||||
```php
|
||||
// ✅ 올바른 패턴
|
||||
class BarobillFakeSoapService extends BarobillSoapService
|
||||
{
|
||||
// Real의 모든 public 메서드를 오버라이드
|
||||
}
|
||||
|
||||
// ❌ 금지: 별도 인터페이스나 독립 클래스로 구현
|
||||
class BarobillFakeService implements BarobillInterface { ... }
|
||||
```
|
||||
|
||||
**이유:** 상속 방식은 Real 서비스에 새 메서드가 추가되어도 Fake에서 오버라이드하지 않으면 Real 메서드가 호출된다. 인터페이스 방식은 모든 메서드를 구현해야 하므로 유지보수 부담이 크다.
|
||||
|
||||
### R3. 환경변수 및 설정 규칙
|
||||
|
||||
```php
|
||||
// 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 바인딩
|
||||
|
||||
```php
|
||||
// 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 필수
|
||||
|
||||
```php
|
||||
/**
|
||||
* 바로빌 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 여부를 반환한다:
|
||||
|
||||
```php
|
||||
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` |
|
||||
|
||||
---
|
||||
|
||||
## 관련 문서
|
||||
|
||||
- [바로빌 시스템](../../features/barobill/README.md) — SOAP 연동, 테스트/운영 모드
|
||||
- [바로빌 API SOAP](../../features/barobill/api-soap-reference.md) — 49+7 메서드 레퍼런스
|
||||
- [API 개발 규칙](api-rules.md) — Service-First 아키텍처
|
||||
- [데모 테넌트](../../projects/demo-tenant/) — 3-Tier 데모 시스템 (해당 시)
|
||||
|
||||
---
|
||||
|
||||
**최종 업데이트**: 2026-03-22
|
||||
Reference in New Issue
Block a user