대규모 Laravel 앱을 위한 서비스/아키텍처를 어떻게 구조화하나요?

Question

Accepted Answer

Laravel 애플리케이션이 성장하면서 기본적인 "비대한 컨트롤러 / 비대한 모델" 접근법은 유지보수하기 어려워집니다. 대규모 앱은 비즈니스 로직을 체계적이고 테스트 가능하며 유지보수 가능하게 유지하기 위해 **추가적인 아키텍처 계층** — 서비스 클래스, 액션 클래스, 리포지토리, 폼 요청, 명확한 도메인 구성 — 의 혜택을 받습니다.

## 문제: 로직이 잘못된 곳에 끝남

```text
작은 앱: 컨트롤러와 모델의 로직은 괜찮음.
큰 앱: 컨트롤러가 비대해지고, 모델이 "갓 객체"가 되며, 로직이 중복됨
→ 테스트, 유지보수, 추론하기 어려움. 로직을 전용 계층으로 추출.
```

## 서비스 클래스 — 비즈니스 로직 캡슐화

```php
<?php
// 복잡한 비즈니스 로직을 컨트롤러에서 서비스로 옮김
class OrderService {
    public function __construct(
        private PaymentGateway $payments,
        private InventoryService $inventory,
    ) {}

public function placeOrder(User $user, array $items): Order {
        // 비즈니스 프로세스 조율 — 재사용 가능, 테스트 가능, 집중됨
        DB::transaction(function () use ($user, $items) { /* ... */ });
    }
}

// 컨트롤러는 가볍게 유지 — 단지 위임
public function store(StoreOrderRequest $request, OrderService $orders) {
    return $orders->placeOrder($request->user(), $request->validated());
}
```

**서비스 클래스**는 비즈니스 로직을 담아 컨트롤러를 가볍게(단지 HTTP 처리) 유지하고 모델을 데이터에 집중시키며 — 로직을 재사용 가능하고 독립적으로 테스트 가능하게 만듭니다.

## 대규모 앱을 위한 기타 유용한 패턴

```text
✓ 액션 클래스 — 유스케이스당 단일 클래스 (예: CreateUserAction) — 매우 집중됨
✓ 폼 요청 — 검증 + 권한 부여를 컨트롤러에서 추출
✓ API Resource — 응답 형태 제어, 모델과 분리
✓ 리포지토리 패턴 — 데이터 접근을 인터페이스 뒤로 추상화 (필요할 때;
  흔히 Eloquent로 충분하므로 반사적으로 추가하지 말 것)
✓ 이벤트/리스너 — 부작용을 핵심 로직에서 분리
✓ 도메인 지향 구성 — 코드를 단지 유형이 아닌 기능/도메인별로 그룹화
  (예: modules/ 구조) 앱이 성장함에 따라
✓ 의존성 주입 + 인터페이스 — 느슨한 결합과 테스트 가능성을 위해
```

## 지침 원칙

```text
✓ 가벼운 컨트롤러 (HTTP만) → 서비스/액션 (비즈니스 로직) → 모델 (데이터)
✓ 단일 책임 — 각 클래스는 한 가지 일을 함
✓ 테스트 가능성과 유연성을 위해 추상화 (인터페이스)에 의존
✗ 과도하게 설계하지 말 것 — 복잡성이 정당화될 때 계층 추가, 미리 하지 말 것
```

## 왜 중요한가

대규모 Laravel 애플리케이션을 어떻게 구조화하는지 이해하는 것은 중요한 시니어 수준의 지식입니다. 작은 앱에 적합한 관례(컨트롤러와 모델의 로직)가 규모에서 무너져 — 비대한 컨트롤러, "갓" 모델, 중복된 로직, 그리고 테스트하고 유지보수하기 어려운 코드로 이어지기 때문입니다.

추가적인 아키텍처 계층 — 특히 **서비스 클래스**(비즈니스 로직을 캡슐화하여 컨트롤러를 가볍게, 모델을 집중되게 유지하면서 로직을 재사용 가능하고 테스트 가능하게 만듦), 그리고 액션 클래스, 폼 요청(검증/권한 부여 추출), API Resource(출력 제어), 리포지토리 패턴(필요할 때 데이터 접근 추상화), 이벤트(부작용 분리), 그리고 **도메인 지향 구성**(앱이 성장함에 따라 기능별로 그룹화) — 을 아는 것이 유지보수 가능하고 확장 가능한 애플리케이션을 구축하게 합니다.

지침 원칙이 중요합니다: **가벼운 컨트롤러 → 서비스 → 모델** 계층화, 단일 책임, 그리고 테스트 가능성과 느슨한 결합을 위해 추상화(인터페이스)에 의존하는 것.

마찬가지로 중요한 것은 **과도하게 설계하지 않는** 판단입니다 — 미리가 아니라 복잡성이 진정으로 정당화될 때 계층을 추가하는 것입니다(Laravel의 기본값은 더 간단한 앱에 괜찮으며, 반사적으로 리포지토리/추상화를 추가하면 불필요한 복잡성이 더해짐).

이러한 아키텍처 패턴과 그것을 적용하는 원칙(과 절제)을 이해하는 것은 성장하면서도 유지보수 가능하고 테스트 가능하며 이해 가능한 상태를 유지하는 대규모의 오래 지속되는 Laravel 애플리케이션을 구축하는 데 가치가 있습니다 — 확장 가능한 애플리케이션을 설계할 수 있는 개발자를, 성장하는 앱이 뒤엉키고 유지보수하기 어려운 코드로 붕괴하는 개발자와 구별합니다.

이 아키텍처적 판단은 시니어 Laravel 개발의 특징이며 진지하게 성장하는 애플리케이션에 자주 관련되는 관심사입니다.