☁️
Spring Cloud & MSA 치트시트

Spring Boot 3.2+ 및 Spring Cloud 2023.x/2024.x 최신 완전 가이드: Eureka 서비스 디스커버리, Spring Cloud Gateway 동적 라우팅 및 JWT 글로벌 필터, OpenFeign 선언적 서비스 간 통신, Resilience4j 서킷 브레이커 & Fallback, Spring Cloud Config 중앙 집중 설정 관리, Micrometer Tracing/Zipkin 분산 추적 및 MSA 분산 트랜잭션 Saga 패턴
#spring-cloud#msa#microservices#spring-boot#eureka#gateway#openfeign#resilience4j#config-server#distributed-tracing#backend#java최종 업데이트: 2026-10-10
Spring Cloud & MSA 치트시트 핵심 명령어 및 실전 가이드

## 1. 사전 요건 & 프로젝트 빌드 구성 (Prerequisites & Setup)

### 💻 시스템 설치 및 실행 요구사양 (System Requirements)

| 항목 | 최소 사양 (Minimum) | 권장 사양 (Recommended) | 참고 및 비고 |
| :--- | :--- | :--- | :--- |
| **운영체제 (OS)** | Windows 10/11, macOS, Linux | Ubuntu 22.04 LTS+, macOS Sonoma, Windows 11 (WSL2) | Java 가상 머신(JVM) 지원 64-bit OS |
| **CPU** | 4 코어 이상 (로컬 다중 서비스 구동 시) | 8 코어 ~ 16 코어 이상 | Eureka, Gateway, 비즈니스 서비스 2~3개 동시 실행 |
| **메모리 (RAM)** | 4 GB 이상 (개발/테스트) | 8 GB ~ 16 GB 이상 | 서비스 노드 1개당 JVM 힙 약 512MB~1GB 필요 |
| **디스크 (Storage)** | 2 GB 이상의 여유 공간 | 20 GB 이상의 고속 NVMe SSD | 빌드 아티팩트, 의존성 JAR 캐시 및 Git Config 스토리지 |
| **네트워크 / 런타임** | Java 17 LTS / Spring Boot 3.2+ / Spring Cloud 2023.0+ | Java 21 LTS / Spring Boot 3.3+ / Spring Cloud 2024.0+ | 포트 8761(Eureka), 8080(Gateway), 8888(Config) |

---

### 📦 Spring Cloud BOM 및 핵심 의존성 설정 (Dependencies)

Spring Cloud는 Spring Boot 버전과 정확히 일치하는 **BOM(Bill of Materials)**을 import하여 의존성 간의 버전 충돌을 원천 방지합니다.

#### ① Gradle (`build.gradle`)
```groovy
plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.4'
    id 'io.spring.dependency-management' version '1.1.6'
}

ext {
    // Spring Boot 3.3.x 호환 Spring Cloud 2023.0.x (Leyton) BOM
    set('springCloudVersion', "2023.0.3")
}

dependencies {
    // [1] 마이크로서비스 공통 클라이언트 (Eureka 등록 & 로드밸런싱)
    implementation 'org.springframework.cloud:spring-cloud-starter-netflix-eureka-client'
    
    // [2] 선언적 HTTP 클라이언트 (서비스 간 통신)
    implementation 'org.springframework.cloud:spring-cloud-starter-openfeign'
    
    // [3] 서킷 브레이커 & 내결함성
    implementation 'org.springframework.cloud:spring-cloud-starter-circuitbreaker-resilience4j'
    
    // [4] 관측성 & 분산 추적 (Micrometer Tracing + Zipkin)
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'io.micrometer:micrometer-tracing-bridge-brave'
    implementation 'io.zipkin.reporter2:zipkin-reporter-brave'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
    }
}
```

#### ② Maven (`pom.xml`)
```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2023.0.3</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

---

## 2. Spring Cloud MSA 핵심 멘탈 모델 & 아키텍처 (Architecture)

마이크로서비스 아키텍처(MSA)에서는 수십~수백 개의 독립 서비스가 동적으로 확장(Scale-out)되므로, **단일 진입점(Gateway)**, **동적 주소 검색(Eureka)**, **장애 격리(Resilience4j)**, **중앙 설정(Config)**이 필수적입니다.

### 📐 MSA 패킷 흐름 및 컴포넌트 아키텍처 (ASCII Diagram)

```text
[ Client Request ] (외부 모바일/웹 클라이언트 요청)
       │
       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    Spring Cloud Gateway (Port 8080)                         │
│                                                                             │
│  - 단일 진입점 (Single Entry Point) & SSL/TLS 종단                          │
│  - JWT 글로벌 인증 필터 (Authentication Filter)                             │
│  - 로드밸런싱 라우팅 (lb://ORDER-SERVICE, lb://PAYMENT-SERVICE)             │
└──────────────┬──────────────────────────────────────────────┬───────────────┘
               │                                              │
               ▼ 서비스 주소 질의(Discovery)                   │ 라우팅(Routing)
┌──────────────────────────────┐                              │
│ Eureka Server (Port 8761)    │                              │
│  - 서비스 레지스트리         │                              │
│  - 하트비트 상태 감시 (UP)   │                              │
└──────────────▲───────────────┘                              │
               │                                              │
        ┌──────┴──────────────────────┬───────────────────────┴──────┐
        │ 주기적 등록/하트비트        │ 주기적 등록/하트비트         │
        ▼                             ▼                              ▼
┌─────────────────────────┐   OpenFeign 통신   ┌─────────────────────────┐
│ Order Service (8081)    │ ─────────────────► │ Payment Service (8082)  │
│  - 주문 생성            │   (동기 HTTP 호출) │  - 결제 승인            │
│  - Resilience4j 서킷차단│ ◄───────────────── │  - 결제 데이터베이스    │
└───────────┬─────────────┘   Fallback 안전응답└────────────┬────────────┘
            │                                               │
            └───────────────────────┬───────────────────────┘
                                    │ 분산 트랜잭션 이벤트 발행
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Kafka / RabbitMQ (비동기 이벤트 브로커 - Saga Choreography 분산 트랜잭션)   │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 🧩 6대 핵심 컴포넌트 역할 비교

| 컴포넌트 | 핵심 역할 | 주요 어노테이션 / 설정 |
| :--- | :--- | :--- |
| **Eureka Server / Client** | 마이크로서비스 동적 등록(Registry) 및 IP/포트 자동 검색 | `@EnableEurekaServer`, `@EnableDiscoveryClient` |
| **Spring Cloud Gateway** | API 단일 진입점, URL 경로 라우팅, 인증 필터, Rate Limiting | `spring.cloud.gateway.routes`, `GlobalFilter` |
| **OpenFeign** | 인터페이스 선언만으로 다른 서비스의 REST API를 호출하는 HTTP 클라이언트 | `@EnableFeignClients`, `@FeignClient(name = "...")` |
| **Resilience4j** | 연쇄 장애 전파를 차단하는 서킷 브레이커, 타임아웃, 재시도, 벌크헤드 | `@CircuitBreaker`, `@Retry`, fallbackMethod |
| **Spring Cloud Config** | Git 또는 볼륨 기반 분산 환경설정 중앙 집중 관리 및 핫 리프레시 | `@EnableConfigServer`, `@RefreshScope`, Actuator |
| **Micrometer Tracing** | 다중 서비스를 가로지르는 요청에 Trace ID/Span ID를 부여하여 병목 추적 | `io.micrometer:micrometer-tracing`, Zipkin 대시보드 |

---

## 3. [초보자 1단계] 3분 헬로월드: Eureka 서비스 등록 & 검색 (Service Discovery)

마이크로서비스 생태계의 중앙 전화번호부 역할을 하는 **Eureka Server**를 띄우고, 실제 비즈니스 서비스(**Order Service**)가 자동으로 자신을 등록하는 최소 동작 예제입니다.

### ① Eureka Server 프로젝트 (`EurekaServerApplication.java`)

```java
package com.example.eurekaserver;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.server.EnableEurekaServer;

@SpringBootApplication
@EnableEurekaServer // [1] Eureka 서비스 레지스트리 서버 활성화
public class EurekaServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(EurekaServerApplication.class, args);
    }
}
```

```yaml
# eureka-server/src/main/resources/application.yml
server:
  port: 8761

spring:
  application:
    name: eureka-server

eureka:
  instance:
    hostname: localhost
  client:
    # 서버 자신이 클라이언트로 등록되거나 다른 레지스트리를 긁어올 필요가 없음
    register-with-eureka: false
    fetch-registry: false
    service-url:
      defaultZone: http://${eureka.instance.hostname}:${server.port}/eureka/
```

---

### ② 마이크로서비스 클라이언트 (`OrderServiceApplication.java`)

```java
package com.example.orderservice;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@EnableDiscoveryClient // [2] Eureka 클라이언트 등록 활성화
public class OrderServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderServiceApplication.class, args);
    }
}

@RestController
@RequestMapping("/orders")
class OrderController {
    @GetMapping("/hello")
    public String getHello() {
        return "주문 서비스가 정상 가동 중입니다 (Port: 8081)";
    }
}
```

```yaml
# order-service/src/main/resources/application.yml
server:
  port: 8081

spring:
  application:
    name: order-service # Eureka에 대문자 ORDER-SERVICE로 등록됨

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/
  instance:
    prefer-ip-address: true
    instance-id: ${spring.application.name}:${server.port}:${random.value}
```

### ③ 실행 및 검증 결과

1. **Eureka Server 실행**: `http://localhost:8761` 웹 브라우저 접속
   - **Instances currently registered with Eureka** 표에 `ORDER-SERVICE`가 녹색 `UP (1) - 192.168.x.x:order-service:8081:...` 상태로 등록된 것을 확인.
2. **REST API 호출 검증**:
```bash
curl http://localhost:8081/orders/hello
# 출력: 주문 서비스가 정상 가동 중입니다 (Port: 8081)
```

---

## 4. [2단계] 핵심 기능: Spring Cloud Gateway 라우팅 & JWT 글로벌 필터 (Gateway)

외부의 모든 트래픽을 단일 포트(8080)로 수신하여 Eureka에 등록된 서비스명(`lb://ORDER-SERVICE`)으로 자동 분산 라우팅하고, JWT 토큰을 사전 검증하는 핵심 관문입니다.
> ⚠️ **주의**: Gateway는 논블로킹 비동기인 **Spring WebFlux(Netty)** 기반입니다. `spring-boot-starter-web`(Tomcat)과 절대 함께 빌드하지 마세요!

### ① 선언적 라우팅 설정 (`application.yml`)

```yaml
# gateway-service/src/main/resources/application.yml
server:
  port: 8080

spring:
  application:
    name: gateway-service
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true      # Eureka 서비스 목록 기반 자동 라우팅 활성화
          lower-case-service-id: true
      routes:
        # [1] 주문 서비스 라우트 규칙
        - id: order-service-route
          uri: lb://ORDER-SERVICE    # lb:// -> 로드밸런서 연동 서비스명
          predicates:
            - Path=/api/orders/**    # 클라이언트 요청 URL 패턴
          filters:
            - StripPrefix=1          # /api를 제거하고 백엔드 /orders/**로 전달

        # [2] 결제 서비스 라우트 규칙
        - id: payment-service-route
          uri: lb://PAYMENT-SERVICE
          predicates:
            - Path=/api/payments/**
          filters:
            - StripPrefix=1

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/
```

---

### ② JWT 검증 글로벌 필터 (`JwtAuthenticationGlobalFilter.java`)

```java
package com.example.gatewayservice.filter;

import org.springframework.cloud.gateway.filter.GatewayFilterChain;
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.core.Ordered;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.server.reactive.ServerHttpRequest;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;

@Component
public class JwtAuthenticationGlobalFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        String path = request.getURI().getPath();

        // 1. 회원가입 및 로그인 등 공개 엔드포인트는 인증 제외
        if (path.contains("/auth/") || path.contains("/public/")) {
            return chain.filter(exchange);
        }

        // 2. Authorization 헤더 존재 여부 확인
        if (!request.getHeaders().containsKey(HttpHeaders.AUTHORIZATION)) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete(); // 401 즉시 종료
        }

        String authHeader = request.getHeaders().getFirst(HttpHeaders.AUTHORIZATION);
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete();
        }

        String token = authHeader.substring(7);

        // 3. 토큰 검증 로직 (실무에서는 JwtParser로 파싱)
        if (!isValidToken(token)) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete();
        }

        // 4. 검증 통과 시 백엔드 서비스로 요청 인계
        return chain.filter(exchange);
    }

    private boolean isValidToken(String token) {
        return token != null && !token.isBlank(); // 예제용 검증
    }

    @Override
    public int getOrder() {
        return -1; // 최우선 실행
    }
}
```

---

## 5. [2단계] 핵심 기능: OpenFeign 선언적 서비스 간 통신 (Declarative HTTP)

마이크로서비스 간(A ➔ B) 내부 동기 REST API 호출 시 복잡한 `RestTemplate`이나 `WebClient` 대신, **자바 인터페이스** 선언만으로 다른 서비스와 통신합니다.

### ① 메인 클래스 Feign 활성화
```java
@SpringBootApplication
@EnableDiscoveryClient
@EnableFeignClients // [1] Feign 클라이언트 스캔 활성화
public class OrderServiceApplication { ... }
```

---

### ② Feign 클라이언트 인터페이스 정의 (`PaymentClient.java`)

```java
package com.example.orderservice.client;

import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;

// [2] Eureka에 등록된 서비스 이름(payment-service) 지정
@FeignClient(name = "payment-service")
public interface PaymentClient {

    // payment-service의 GET /payments/{orderId} 엔드포인트 호출
    @GetMapping("/payments/{orderId}")
    PaymentResponse getPaymentInfo(@PathVariable("orderId") Long orderId);

    // payment-service의 POST /payments/process 엔드포인트 호출
    @PostMapping("/payments/process")
    PaymentResponse processPayment(@RequestBody PaymentRequest request);
}

// DTO 정의
record PaymentRequest(Long orderId, Long amount, String paymentMethod) {}
record PaymentResponse(Long paymentId, String status, Long amount) {}
```

---

### ③ 비즈니스 서비스에서 주입 및 호출
```java
@Service
public class OrderService {

    private final PaymentClient paymentClient;

    public OrderService(PaymentClient paymentClient) {
        this.paymentClient = paymentClient;
    }

    public void createOrder(Long orderId, Long amount) {
        // 일반 로컬 자바 메서드를 호출하듯 다른 마이크로서비스 호출!
        PaymentResponse response = paymentClient.processPayment(new PaymentRequest(orderId, amount, "CREDIT_CARD"));
        System.out.println("결제 처리 결과: " + response.status());
    }
}
```

---

## 6. [2단계] 핵심 기능: Resilience4j 서킷 브레이커 & Fallback (Fault Tolerance)

호출 대상 서비스(Payment Service)가 과부하나 장애로 다운되었을 때, 요청이 계속 쌓여 호출자(Order Service)까지 연쇄적으로 멈추는 **캐스케이딩 장애(Cascading Failure)**를 원천 차단합니다.

### 🛡️ 서킷 브레이커 3대 상태 전이 (State Machine)
- **CLOSED (정상)**: 모든 트래픽이 목적지로 통과. 실패율을 모니터링.
- **OPEN (차단)**: 실패율이 임계치(예: 50%)를 넘으면 즉시 회로를 열고, 원격 호출 없이 **즉시 Fallback 안전 응답** 반환.
- **HALF_OPEN (시험)**: 설정된 시간(10초) 경과 후 일부 요청만 보내 서버가 회복되었는지 테스트.

---

### ① 어노테이션 기반 서킷 브레이커 적용
```java
package com.example.orderservice.service;

import com.example.orderservice.client.PaymentClient;
import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker;
import io.github.resilience4j.retry.annotation.Retry;
import org.springframework.stereotype.Service;

@Service
public class OrderPaymentService {

    private final PaymentClient paymentClient;

    public OrderPaymentService(PaymentClient paymentClient) {
        this.paymentClient = paymentClient;
    }

    // [1] 서킷 브레이커 및 재시도 등록
    @CircuitBreaker(name = "paymentCircuit", fallbackMethod = "fallbackPaymentProcess")
    @Retry(name = "paymentRetry")
    public String executePayment(Long orderId, Long amount) {
        return paymentClient.processPayment(new PaymentRequest(orderId, amount, "CARD")).status();
    }

    // [2] 원격 서비스 장애 또는 서킷 OPEN 시 대신 호출되는 Fallback 메서드
    // 중요: 원래 메서드와 동일한 파라미터 목록 뒤에 반드시 Throwable 인자를 추가해야 함!
    public String fallbackPaymentProcess(Long orderId, Long amount, Throwable ex) {
        System.err.println("결제 서비스 장애 감지! Fallback 실행 사유: " + ex.getMessage());
        return "PAYMENT_PENDING_OFFLINE"; // 결제 보류 상태로 안전 반환
    }
}
```

---

### ② `application.yml` 서킷 브레이커 정밀 튜닝
```yaml
resilience4j:
  circuitbreaker:
    instances:
      paymentCircuit:
        sliding-window-type: COUNT_BASED       # 호출 횟수 기반 슬라이딩 윈도우
        sliding-window-size: 10                # 최근 10번의 호출 통계 측정
        failure-rate-threshold: 50             # 실패율 50% 이상 시 서킷 OPEN
        wait-duration-in-open-state: 10s       # OPEN 후 HALF_OPEN 전환 대기 시간
        permitted-number-of-calls-in-half-open-state: 3 # HALF_OPEN 시 테스트 호출 수
        automatic-transition-from-open-to-half-open-enabled: true
```

---

## 7. [3단계] 실무 응용: 분산 설정(Config Server) & 핫 리프레시 (Config)

Git 저장소에 각 환경(dev, prod)별 YAML 설정을 모아두고, 서비스 재기동 없이 설정을 실시간 변경합니다.

### ① 마이크로서비스에서 `@RefreshScope` 적용
```java
package com.example.orderservice.controller;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RefreshScope // [1] /actuator/refresh 호출 시 해당 빈의 필드값을 동적으로 재주입
public class ConfigTestController {

    @Value("${order.discount-rate:0.1}")
    private double discountRate;

    @GetMapping("/orders/discount")
    public String getDiscountRate() {
        return "현재 적용 할인율: " + (discountRate * 100) + "%";
    }
}
```

### ② 런타임 무중단 설정 리프레시 호출
Git에서 `order.discount-rate: 0.25`로 커밋 후, 재부팅 없이 마이크로서비스에 HTTP POST 요청 전송:
```bash
curl -X POST http://localhost:8081/actuator/refresh
# 응답: ["order.discount-rate"] (변경된 설정 키 목록 반환)

curl http://localhost:8081/orders/discount
# 출력: 현재 적용 할인율: 25.0% (즉시 반영 확인!)
```

---

## 8. [3단계] 실무 응용: 분산 추적(Micrometer Tracing) & Saga 패턴 (Tracing & Saga)

### 🕵️ 분산 추적 (Distributed Tracing with Zipkin)

단일 사용자 클릭이 Gateway ➔ Order ➔ Payment ➔ Delivery 서비스로 이어질 때, 전체 경로를 하나의 **Trace ID**로 묶어 성능 병목 지점을 시각화합니다.

```yaml
# application.yml
management:
  tracing:
    sampling:
      probability: 1.0  # 개발 환경: 100% 샘플링 (운영 환경은 0.1 권장)
  zipkin:
    tracing:
      endpoint: http://localhost:9411/api/v2/spans
logging:
  pattern:
    # 로그 포맷에 [서비스명, TraceID, SpanID] 자동 출력
    level: "%5p [${spring.application.name:},%X{traceId:-},%X{spanId:-}]"
```

```text
# 콘솔 로그 출력 예시: 동일한 Trace ID(65a4c9b1d03e)가 전 서비스에 걸쳐 유지됨
INFO [order-service,65a4c9b1d03e,e450b281f012] : 주문 생성 요청 수신
INFO [payment-service,65a4c9b1d03e,99a01f56a12b] : 결제 승인 완료
```

---

### 🔄 분산 트랜잭션 Saga 패턴 (Orchestration vs Choreography)

마이크로서비스는 서로 다른 DB를 가지므로 전통적인 2단계 커밋(2PC)이 불가능합니다. 각 서비스가 로컬 트랜잭션을 실행하고, 실패 시 **보상 트랜잭션(Compensating Transaction)**을 실행하여 데이터 정합성을 맞춥니다.

```text
[ 정상 흐름 (Happy Path) ]
주문 서비스 (주문생성) ──► 결제 서비스 (결제완료) ──► 재고 서비스 (재고차감) ──► 완료!

[ 실패 시 보상 트랜잭션 (Compensating Flow) ]
주문 서비스 (주문생성) ──► 결제 서비스 (결제완료) ──► 재고 서비스 (❌ 재고부족 에러!)
                                                          │
                      ┌───────────────────────────────────┘
                      ▼ 보상 이벤트 발행 (Kafka)
            결제 서비스 (결제 취소/환불)
                      │
                      ▼ 보상 이벤트 발행
            주문 서비스 (주문 취소 상태 갱신)
```

---

## 9. 실무 트러블슈팅 & 프로덕션 운영 체크리스트 (Best Practices)

### ⚠️ 초보자가 가장 흔히 겪는 5대 실수 및 해결책

| 증상 및 문제점 | 원인 분석 | 확실한 해결 가이드 |
| :--- | :--- | :--- |
| **Gateway 실행 시 `Spring MVC found on classpath` 에러** | Gateway는 WebFlux 전용인데 Tomcat 의존성이 섞임 | `build.gradle`에서 `spring-boot-starter-web`을 제거하고 `spring-cloud-starter-gateway`만 단독 유지 |
| **Eureka에 `EMERGENCY! ... CLAIMING INSTANCES ARE UP` 경고** | Eureka 자기보존 모드(Self-Preservation) 작동 | 네트워크 일시 단절 시 무분별한 인스턴스 축출을 방지하는 정상 방어 기제. 로컬 테스트 시 `enable-self-preservation: false`로 끄기 가능 |
| **OpenFeign 호출 시 `Read timed out` 500 에러** | 기본 HTTP 소켓 타임아웃이 1000ms(1초)로 매우 짧음 | `feign.client.config.default.read-timeout: 5000` 설정으로 타임아웃 상향 조정 |
| **서비스 간 Feign 통신 시 로그인 JWT 토큰 유실** | Feign은 기본적으로 인바운드 헤더를 전달하지 않음 | `RequestInterceptor` 빈을 등록하여 `RequestContextHolder`에서 토큰을 추출해 Feign 요청 헤더에 주입 |
| **OpenFeign 순환 의존성(Circular Dependency) 빌드 에러** | A 서비스와 B 서비스가 서로를 `@FeignClient`로 참조 | 비동기 메시지 큐(Kafka/RabbitMQ) 이벤트 기반 통신으로 결합도를 분리 |

---

### 🚀 프로덕션 운영 체크리스트

1. **Eureka 하트비트 주기 튜닝**:
   기본값(30초) 대신 운영 환경에서는 `lease-renewal-interval-in-seconds: 10`, `lease-expiration-duration-in-seconds: 30`으로 조정하여 다운된 인스턴스를 빠르게 감지.
2. **Spring Cloud Gateway CORS 설정**:
   글로벌 필터 앞단에서 브라우저 Preflight(OPTIONS) 요청이 401로 차단되지 않도록 Gateway 설정 레벨에서 `globalcors.cors-configurations`를 명시.
3. **OpenFeign 요청 인터셉터(RequestInterceptor)**:
   인증 토큰(`Authorization: Bearer ...`)이 서비스 간 홉(Hop)을 넘어갈 때 유실되지 않도록 공통 인터셉터 구성 필수.
💬
Spring Cloud & MSA 치트시트

의견 및 질문

댓글 수정

댓글 삭제
