모듈러 모놀리스에서 마이크로서비스로: 경계 설계가 서비스 추출의 성패를 가른다

// ❌ 전통적 모놀리스 — 다른 모듈의 내부를 직접 참조
import { OrderRepository } from '../order/repositories/order.repository';
import { inventoryDb } from '../inventory/db/connection';
 
class UserService {
  constructor(private orderRepo: OrderRepository) {}
  
  async getUserWithOrders(userId: string) {
    const inventory = await inventoryDb.query(
      `SELECT * FROM inventory WHERE user_id = ?`, [userId]
    );
    return { user: await this.orderRepo.findByUser(userId), inventory };
  }
}

// ✅ 모듈러 모놀리스 — Facade를 통한 명시적 인터페이스만 허용
 
// order/order.facade.ts (공개 인터페이스)
export class OrderFacade {
  constructor(private orderService: OrderService) {}
  
  async getOrderSummaryByUser(userId: string): Promise<OrderSummaryDto> {
    return this.orderService.getSummary(userId);
  }
}
 
// user/user.service.ts
import { OrderFacade } from '../order/order.facade'; // ✅ Facade만 import
 
class UserService {
  constructor(private orderFacade: OrderFacade) {}
  
  async getUserDashboard(userId: string) {
    const orderSummary = await this.orderFacade.getOrderSummaryByUser(userId);
    return { user: await this.findById(userId), orderSummary };
  }
}

// libs/order-module/src/index.ts — 공개 API만 export
export { OrderSummaryComponent } from './components/OrderSummary';
export { useOrderStatus } from './hooks/useOrderStatus';
export type { OrderDto } from './types';
// 내부 구현체는 절대 export하지 않음

// nx.json — 모듈 간 허용된 의존성만 통과시키는 경계 규칙
{
  "pluginsConfig": {
    "@nx/eslint-plugin": {
      "rules": {
        "enforce-module-boundaries": [
          "error",
          {
            "depConstraints": [
              {
                "sourceTag": "scope:app",
                "onlyDependOnLibsWithTags": ["scope:feature", "scope:ui", "scope:util"]
              },
              {
                "sourceTag": "scope:feature",
                "onlyDependOnLibsWithTags": ["scope:ui", "scope:util"]
              },
              {
                "sourceTag": "scope:ui",
                "onlyDependOnLibsWithTags": ["scope:util"]
              }
            ]
          }
        ]
      }
    }
  }
}

# /etc/nginx/conf.d/strangler-fig.conf
 
upstream monolith {
    server legacy-app:3000;
}
 
upstream new-payment-service {
    server payment-service:3001;
}
 
server {
    listen 80;
    
    # 새 서비스가 준비된 경로만 신규 서비스로 라우팅
    location /api/v2/payments {
        proxy_pass http://new-payment-service;
        proxy_set_header X-Migration-Phase "strangler-fig";
    }
    
    # 나머지는 여전히 레거시 모놀리스로
    location / {
        proxy_pass http://monolith;
    }
}

// payment-service/src/acl/legacy-order.adapter.ts
 
interface LegacyOrderModel {
  order_id: number;       // 레거시는 숫자 ID + snake_case
  user_id_fk: number;
  total_amount: string;   // 문자열로 저장된 금액
  created_dt: string;
}
 
interface PaymentOrderDto {
  orderId: string;        // 신규 서비스는 UUID + camelCase
  userId: string;
  amount: Money;          // dinero.js 같은 금액 라이브러리로 구현 가능
  createdAt: Date;
}
 
export class LegacyOrderAdapter {
  translate(legacy: LegacyOrderModel): PaymentOrderDto {
    return {
      orderId: `order-${legacy.order_id}`,
      userId: `user-${legacy.user_id_fk}`,
      amount: Money.fromString(legacy.total_amount, 'KRW'),
      createdAt: new Date(legacy.created_dt),
    };
  }
}

// shared/events/order-events.ts
export interface OrderPlacedEvent {
  eventType: 'ORDER_PLACED';
  orderId: string;
  userId: string;
  items: { productId: string; quantity: number; price: number }[];
  placedAt: Date;
}
 
// order/order.service.ts
export class OrderService {
  constructor(
    private readonly orderRepo: OrderRepository,
    private readonly eventBus: EventBus,  // 인터페이스에만 의존
  ) {}
 
  async placeOrder(dto: PlaceOrderDto): Promise<Order> {
    const order = await this.orderRepo.save(Order.create(dto));
    
    // 직접 InventoryService를 호출하지 않고 이벤트 발행
    await this.eventBus.publish<OrderPlacedEvent>({
      eventType: 'ORDER_PLACED',
      orderId: order.id,
      userId: dto.userId,
      items: order.items,
      placedAt: new Date(),
    });
    
    return order;
  }
}
 
// inventory/inventory.event-handler.ts
@EventHandler('ORDER_PLACED')
export class InventoryEventHandler {
  constructor(private inventoryService: InventoryService) {}
 
  async handle(event: OrderPlacedEvent): Promise<void> {
    await this.inventoryService.decreaseStock(event.items);
  }
}

// shared/events/in-process-event-bus.ts (모놀리스 단계)
export class InProcessEventBus implements EventBus {
  private handlers = new Map<string, EventHandler[]>();
 
  async publish<T>(event: T & { eventType: string }): Promise<void> {
    const handlers = this.handlers.get(event.eventType) ?? [];
    await Promise.all(handlers.map(h => h.handle(event)));
  }
}
 
// shared/events/kafka-event-bus.ts (서비스 추출 후 교체)
export class KafkaEventBus implements EventBus {
  async publish<T>(event: T & { eventType: string }): Promise<void> {
    await this.kafkaProducer.send({
      topic: event.eventType,
      messages: [{ value: JSON.stringify(event) }],
    });
  }
}

# 경계 위반 시 이런 오류가 납니다
ESLint: A project tagged with 'scope:feature' can only depend on libs
tagged with 'scope:ui', 'scope:util' (@nx/enforce-module-boundaries)

// src/test/java/com/example/ArchitectureTest.java
// @AnalyzeClasses: 분석할 패키지 지정 / @ArchTest: JUnit처럼 동작하는 아키텍처 검증 테스트
@AnalyzeClasses(packages = "com.example")
public class ArchitectureTest {
 
    @ArchTest
    static final ArchRule order_should_not_access_inventory_internals =
        noClasses()
            .that().resideInAPackage("..order..")
            .should().accessClassesThat()
            .resideInAPackage("..inventory.internal..")
            .because("모듈 간 통신은 반드시 Facade를 통해야 합니다");
}