# API 요청 생명주기 — Client API로 배우는 전체 흐름

> **작성일**: 2026-03-15
> **목적**: HTTP 요청이 JSON 응답이 되기까지 8단계를 코드 기반으로 해설
> **대상 독자**: API 구조를 처음 학습하는 개발자
> **예제 API**: `POST /api/v1/clients` (거래처 등록)

---

## 1. 전체 흐름도

```
클라이언트 (React/Postman)
  │
  │  POST /api/v1/clients
  │  Headers: X-API-KEY: xxx, Authorization: Bearer yyy
  │  Body: { "name": "삼성전자", "client_type": "SALES" }
  │
  ▼
┌──────────────────────────────────────────────────────┐
│ ① 미들웨어 체인 (4개 순차 실행)                        │
│    CORS → RateLimit → ApiKey검증 → API버전선택        │
│    → tenant_id, api_user를 app() 컨테이너에 바인딩     │
├──────────────────────────────────────────────────────┤
│ ② 라우팅                                             │
│    routes/api/v1/sales.php → ClientController@store   │
├──────────────────────────────────────────────────────┤
│ ③ FormRequest 검증                                   │
│    ClientStoreRequest → 30개 필드 규칙 자동 검증       │
│    실패 시 → 422 ValidationException (Controller 진입X)│
├──────────────────────────────────────────────────────┤
│ ④ Controller (3줄)                                   │
│    DI주입 → validated() 추출 → Service 호출           │
│    ApiResponse::handle()로 감싸서 예외 자동 포착       │
├──────────────────────────────────────────────────────┤
│ ⑤ Base Service                                       │
│    tenantId() → 없으면 400 예외                       │
│    apiUserId() → 없으면 401 예외                      │
├──────────────────────────────────────────────────────┤
│ ⑥ ClientService (비즈니스 로직)                       │
│    client_code 자동 생성 → Client::create()           │
├──────────────────────────────────────────────────────┤
│ ⑦ Model + Trait                                      │
│    $fillable 체크 → $casts 변환 → $hidden 제외        │
│    BelongsToTenant → 이후 쿼리에 tenant_id 자동 필터   │
│    Auditable → audit_logs 테이블에 생성 이력 기록      │
├──────────────────────────────────────────────────────┤
│ ⑧ ApiResponse                                        │
│    성공: { success: true, message: "...", data: {...} }│
│    실패: 예외 타입별 자동 분기 (422/400/404/500)       │
└──────────────────────────────────────────────────────┘
  │
  ▼
  200 OK  { "success": true, "data": { "id": 42, ... } }
```

---

## 2. 단계별 상세 해설

### 2.1 미들웨어 체인 — 모든 요청의 관문

`bootstrap/app.php`에서 전역 등록된 미들웨어가 순서대로 실행된다.

| 순서 | 미들웨어 | 역할 | 실패 시 |
|:----:|---------|------|--------|
| 1 | `CorsMiddleware` | `Access-Control-Allow-Origin` 헤더 추가 | 브라우저가 요청 차단 |
| 2 | `ApiRateLimiter` | 분당 요청 수 제한 | 429 Too Many Requests |
| 3 | `ApiKeyMiddleware` | `X-API-KEY` 검증 + Bearer 토큰 검증 | 401 Unauthorized |
| 4 | `ApiVersionMiddleware` | `Accept-Version` 헤더로 v1/v2 선택 | 기본값 v1 |

**ApiKeyMiddleware의 핵심 동작:**

```php
// 1. X-API-KEY로 api_keys 테이블 조회
$apiKey = ApiKey::where('key', $request->header('X-API-KEY'))->first();

// 2. Bearer 토큰으로 사용자 인증 (Sanctum)
$token = PersonalAccessToken::findToken($bearerToken);

// 3. tenant_id와 api_user를 앱 컨테이너에 바인딩
app()->instance('tenant_id', $tenantId);   // ← Service에서 읽음
app()->instance('api_user', $userId);       // ← Service에서 읽음
$request->attributes->set('tenant_id', $tenantId); // ← TenantScope에서 읽음
```

> **핵심**: 이후 모든 Service와 Model이 `app('tenant_id')`로 현재 테넌트를 알 수 있다.

---

### 2.2 라우팅 — URL을 Controller 메서드에 매핑

```php
// routes/api/v1/sales.php:27~37
Route::prefix('clients')->group(function () {
    Route::get('',       [ClientController::class, 'index']);   // 목록
    Route::post('',      [ClientController::class, 'store']);   // 생성 ← 이번 예제
    Route::get('/{id}',  [ClientController::class, 'show'])    // 상세
        ->whereNumber('id');  // ← id가 숫자인지 라우트 레벨에서 강제
    Route::put('/{id}',  [ClientController::class, 'update'])->whereNumber('id');
    Route::delete('/{id}', [ClientController::class, 'destroy'])->whereNumber('id');
    Route::patch('/{id}/toggle', [ClientController::class, 'toggle'])->whereNumber('id');
});
```

**RESTful 규칙:**

| HTTP 메서드 | URL | Controller | 의미 |
|:-----------:|-----|-----------|------|
| GET | `/clients` | `index()` | 목록 조회 |
| POST | `/clients` | `store()` | 신규 생성 |
| GET | `/clients/42` | `show(42)` | 단건 조회 |
| PUT | `/clients/42` | `update(42)` | 전체 수정 |
| DELETE | `/clients/42` | `destroy(42)` | 삭제 |
| PATCH | `/clients/42/toggle` | `toggle(42)` | 부분 수정 (활성/비활성) |

> **`whereNumber('id')`**: `/clients/abc` 같은 잘못된 요청을 라우트 레벨에서 404로 차단한다. Controller까지 도달하지 않는다.

---

### 2.3 FormRequest — Controller 진입 전 자동 검증

Laravel이 Controller 파라미터에서 `ClientStoreRequest` 타입힌트를 발견하면 **자동으로** 검증을 실행한다.

```php
// ClientStoreRequest.php — 3단계로 동작
class ClientStoreRequest extends FormRequest
{
    // [1단계] 권한 확인 — "이 사용자가 이 요청을 할 수 있는가?"
    public function authorize(): bool { return true; }

    // [2단계] 전처리 — 검증 전에 데이터를 정리/변환
    protected function prepareForValidation(): void
    {
        // "SALES"라는 문자열이 common_codes의 name인지 code인지 자동 판별
        $this->convertCommonCodeNameToCode('client_type');
    }

    // [3단계] 규칙 정의 — 각 필드의 검증 조건
    public function rules(): array
    {
        return [
            'name'           => 'required|string|max:100',      // 필수, 문자열, 100자 이하
            'email'          => 'nullable|email|max:100',        // 선택, 이메일 형식
            'client_type'    => ['nullable', Rule::exists(...)], // DB에 존재하는 코드만
            'tax_end_date'   => 'nullable|date|after_or_equal:tax_start_date',
            //                                ↑ 종료일이 시작일 이후인지 자동 검증
        ];
    }
}
```

**검증 실패 시 자동 응답 (Controller에 도달하지 않음):**

```json
{
    "success": false,
    "message": "입력값 검증에 실패했습니다.",
    "errors": {
        "name": ["name 필드는 필수입니다."],
        "email": ["email 필드는 올바른 이메일 주소여야 합니다."]
    }
}
```

---

### 2.4 Controller — 연결만 담당하는 3줄 코드

```php
// ClientController.php
class ClientController extends Controller
{
    // DI(의존성 주입): Laravel이 ClientService 인스턴스를 자동 생성하여 주입
    public function __construct(private ClientService $service) {}

    public function store(ClientStoreRequest $request)
    {
        return ApiResponse::handle(function () use ($request) {
            return $this->service->store($request->validated());
            //                              ↑ 검증 통과한 데이터만 추출
        }, __('message.client.created'));
        //  ↑ i18n 메시지 키 (lang/ko/message.php에 정의)
    }
}
```

**Controller가 하는 일 (3가지만):**
1. `ClientStoreRequest`로 검증 (자동)
2. `$request->validated()`로 안전한 데이터만 추출
3. `$this->service->store()`에 전달

**Controller가 하지 않는 일:**
- DB 쿼리 직접 실행
- 비즈니스 로직 (코드 생성, 중복 검사 등)
- try-catch 에러 처리 (ApiResponse::handle()이 대신함)
- 응답 포맷 조립

---

### 2.5 Base Service — 멀티테넌트 컨텍스트 강제

모든 Service가 상속하는 추상 클래스이다.

```php
// Service.php
abstract class Service
{
    // tenant_id가 없으면 400 Bad Request 예외
    protected function tenantId(): int
    {
        $id = app('tenant_id');  // ← ApiKeyMiddleware가 설정한 값
        if (! $id) {
            throw new BadRequestHttpException(__('error.tenant_id'));
        }
        return (int) $id;
    }

    // api_user가 없으면 401 Unauthorized 예외
    protected function apiUserId(): int
    {
        $uid = app('api_user');  // ← ApiKeyMiddleware가 설정한 값
        if (! $uid) {
            throw new AuthenticationException(__('auth.unauthenticated'));
        }
        return (int) $uid;
    }
}
```

> **역할**: "tenant_id 없이는 비즈니스 로직을 실행할 수 없다"는 규칙을 강제한다.

---

### 2.6 ClientService — 비즈니스 로직 집중

```php
// ClientService.php
class ClientService extends Service
{
    public function store(array $data)
    {
        $tenantId = $this->tenantId();  // ← 없으면 여기서 400 예외

        // 비즈니스 규칙 1: client_code 자동 생성
        $data['client_code'] = $this->generateClientCode($tenantId);

        // 비즈니스 규칙 2: 테넌트 귀속
        $data['tenant_id'] = $tenantId;

        // 비즈니스 규칙 3: 기본값 설정
        $data['is_active'] = $data['is_active'] ?? true;

        // DB 저장 (Model을 통해서만)
        return Client::create($data);
    }
}
```

**Service가 담당하는 것:**
- `tenantId()` 호출로 멀티테넌트 컨텍스트 확인
- 비즈니스 규칙 적용 (코드 생성, 기본값, 연관 데이터 처리)
- 예외 발생 (`NotFoundHttpException`, `BadRequestHttpException`)
- 트랜잭션 관리 (복잡한 작업 시 `DB::transaction()`)

---

### 2.7 Model — DB 테이블의 PHP 표현

```php
// Client.php
class Client extends Model
{
    use Auditable,          // → 생성/수정/삭제 시 audit_logs에 기록
        BelongsToTenant,    // → 모든 쿼리에 WHERE tenant_id = ? 자동 추가
        ModelTrait;         // → scopeActive(), 날짜 포맷

    // Mass Assignment 보호: 이 필드만 create()/update()로 설정 가능
    protected $fillable = ['tenant_id', 'name', 'client_code', ...];

    // PHP↔DB 타입 자동 변환
    protected $casts = [
        'is_active'    => 'boolean',    // DB: 0/1 → PHP: true/false
        'tax_amount'   => 'decimal:2',  // DB: 1000.5 → PHP: "1000.50"
        'tax_start_date' => 'date',     // DB: "2026-03-15" → Carbon 객체
    ];

    // JSON 직렬화 시 제외 (API 응답에 절대 노출되지 않음)
    protected $hidden = ['account_password'];

    // Eloquent Relationship 정의
    public function orders()    { return $this->hasMany(Order::class, 'client_id'); }
    public function badDebts()  { return $this->hasMany(BadDebt::class); }

    // 쿼리 스코프 (재사용 가능한 WHERE 조건)
    public function scopeActive($query) { return $query->where('is_active', true); }
}
```

**`Client::create($data)` 실행 시 내부 동작:**

```
① $fillable 체크 → 허용되지 않은 필드 무시 (Mass Assignment 방지)
② INSERT INTO clients (tenant_id, name, ...) VALUES (1, '삼성전자', ...)
③ $casts 적용 → is_active: 0 → true 변환
④ Auditable 트리거 → audit_logs에 "created" 이벤트 기록
⑤ 생성된 Model 인스턴스 반환 (id 포함)
```

**BelongsToTenant의 효과:**

```php
// 이 코드를 작성하면:
Client::where('is_active', true)->get();

// 실제 실행되는 SQL:
SELECT * FROM clients WHERE tenant_id = 1 AND is_active = 1;
//                         ↑ 자동 추가됨 (Global Scope)
```

---

### 2.8 ApiResponse::handle() — 통일된 응답 포맷

```php
// ApiResponse.php:203~300
public static function handle(callable $callback, string $responseTitle): JsonResponse
{
    try {
        $result = $callback();  // ← Service 호출 결과

        // 날짜 포맷 변환: "2026-03-15T00:00:00.000000Z" → "2026-03-15"
        $formattedData = self::formatDates($result);

        // 성공 응답 조립
        return response()->json([
            'success' => true,
            'message' => $responseTitle,
            'data'    => $formattedData,
        ], 200);

    } catch (\Throwable $e) {
        // 예외 타입별 자동 분기
    }
}
```

**예외 타입별 HTTP 응답:**

| 예외 클래스 | HTTP | 발생 상황 |
|-----------|:----:|---------|
| `ValidationException` | 422 | FormRequest 검증 실패 |
| `NotFoundHttpException` | 404 | Service에서 `find()` 결과 없음 |
| `BadRequestHttpException` | 400 | 비즈니스 규칙 위반 (주문 있는 거래처 삭제 등) |
| `AuthenticationException` | 401 | tenant_id/api_user 없음 |
| `DuplicateCodeException` | 400 | 중복 코드 (duplicate_id 포함) |
| 기타 `Throwable` | 500 | 예상치 못한 서버 에러 |

---

## 3. CRUD 전체 흐름 비교

| 작업 | HTTP | Controller | Service 핵심 로직 |
|------|------|-----------|------------------|
| 목록 | `GET /clients` | `index()` | 검색/필터/페이징 + 미수금 집계 |
| 생성 | `POST /clients` | `store()` | client_code 자동 생성 |
| 상세 | `GET /clients/42` | `show()` | 미수금/악성채권 정보 추가 |
| 수정 | `PUT /clients/42` | `update()` | client_code 변경 불가 + 악성채권 동기화 |
| 삭제 | `DELETE /clients/42` | `destroy()` | 주문 존재 시 삭제 거부 |
| 토글 | `PATCH /clients/42/toggle` | `toggle()` | is_active 반전 |
| 통계 | `GET /clients/stats` | `stats()` | 유형별/악성채권 집계 |
| 일괄삭제 | `DELETE /clients/bulk` | `bulkDestroy()` | 주문 있는 건 건너뛰기 |

---

## 4. 파일 역할 요약 (외울 것)

```
routes/api/v1/sales.php        "어디로 가는가" — URL → Controller 매핑
ClientStoreRequest.php          "올바른 데이터인가" — 입력 검증 (Controller 진입 전)
ClientController.php            "누구에게 시킬 것인가" — 연결만 (3줄)
Service.php (Base)              "자격이 있는가" — tenant_id 존재 강제
ClientService.php               "무엇을 할 것인가" — 비즈니스 로직
Client.php (Model)              "어떻게 저장하는가" — DB 매핑, 타입 변환, 관계
ApiResponse.php                 "어떻게 포장하는가" — 성공/실패 JSON 통일
```

---

## 관련 문서

| 문서 | 용도 |
|------|------|
| [api-rules.md](../standards/api-rules.md) | API 개발 규칙 (Service-First, i18n 등) |
| [api-code-quality-audit.md](../../system/api-code-quality-audit.md) | 정석 패턴 R1~R6, 보안 감사 |
| [api-structure.md](../../system/api-structure.md) | API 디렉토리 구조 현황 |
| [swagger-guide.md](swagger-guide.md) | Swagger 문서 작성법 |

---

**최종 업데이트**: 2026-03-15
