{"componentChunkName":"component---src-templates-blog-post-js","path":"/springboot/마이크로서비스-아키텍처-완전정복-실전-구축-가이드/","result":{"data":{"site":{"siteMetadata":{"title":"Bottlehs Tech Blog","description":"웹·앱·AI 개발자 전병훈(bottlehs)의 기술 블로그. AI·LLM, JavaScript·Vue, Spring Boot, 알고리즘, 블록체인 실무 가이드를 다룹니다","siteUrl":"https://www.bottlehs.dev","author":{"name":"Jeon Byung Hun","summary":"개발을 즐기는 bottlehs - Engineer, MS, AI, FE, BE, OS, IOT, Blockchain, 설계, 테스트"},"social":{"github":"bottlehs","codepen":"bottlehs"}}},"markdownRemark":{"id":"e208e3dc-7ac4-58c8-9120-56a4e833b7ef","excerpt":"마이크로서비스 아키텍처 완전정복 - 실전 구축 가이드 마이크로서비스 아키텍처는 대규모 애플리케이션을 독립적으로 배포 가능한 작은 서비스들로 분해하는 아키텍처 패턴이다. 각 서비스는 자체 데이터베이스를 가지며, API…","html":"

마이크로서비스 아키텍처 완전정복 - 실전 구축 가이드

\n

마이크로서비스 아키텍처는 대규모 애플리케이션을 독립적으로 배포 가능한 작은 서비스들로 분해하는 아키텍처 패턴이다. 각 서비스는 자체 데이터베이스를 가지며, API를 통해 통신한다. 이 글은 마이크로서비스 아키텍처를 설계하고 구축하는 실전 가이드를 제공한다.

\n

1. 마이크로서비스 아키텍처 개요

\n

1-1. 마이크로서비스란?

\n

마이크로서비스는 다음과 같은 특징을 가진다:

\n\n

1-2. 모놀리식 vs 마이크로서비스

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
구분모놀리식마이크로서비스
배포전체 애플리케이션 배포서비스별 독립 배포
스케일링전체 스케일링서비스별 스케일링
기술 스택단일 기술 스택다양한 기술 스택
복잡도낮음높음
장애 격리어려움쉬움
개발 속도초기 빠름장기적으로 빠름
\n

1-3. 마이크로서비스 도입 시기

\n

마이크로서비스를 도입해야 하는 경우:

\n\n

도입을 피해야 하는 경우:

\n\n

2. 마이크로서비스 설계 원칙

\n

2-1. 도메인 주도 설계 (DDD)

\n

서비스를 비즈니스 도메인에 따라 분리한다.

\n
전자상거래 시스템 예시:\n\n- User Service (사용자 관리)\n- Product Service (상품 관리)\n- Order Service (주문 처리)\n- Payment Service (결제 처리)\n- Inventory Service (재고 관리)\n- Notification Service (알림)
\n

2-2. 데이터베이스 per 서비스

\n

각 서비스는 자체 데이터베이스를 가진다.

\n
# 서비스별 데이터베이스\nUser Service:\n  Database: PostgreSQL (사용자 정보)\n\nProduct Service:\n  Database: MongoDB (상품 카탈로그)\n\nOrder Service:\n  Database: PostgreSQL (주문 정보)\n\nAnalytics Service:\n  Database: ClickHouse (분석 데이터)
\n

2-3. API First 설계

\n

서비스를 설계할 때 먼저 API를 정의한다.

\n
# OpenAPI 스펙 예시\nopenapi: 3.0.0\ninfo:\n  title: User Service API\n  version: 1.0.0\n\npaths:\n  /users:\n    get:\n      summary: Get all users\n      responses:\n        '200':\n          description: List of users\n    post:\n      summary: Create user\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              $ref: '#/components/schemas/User'\n      responses:\n        '201':\n          description: User created
\n

3. 서비스 간 통신

\n

3-1. 동기 통신 (REST/gRPC)

\n

REST API

\n
// User Service\n@RestController\n@RequestMapping(\"/api/users\")\npublic class UserController {\n    \n    @GetMapping(\"/{userId}\")\n    public ResponseEntity<User> getUser(@PathVariable Long userId) {\n        User user = userService.getUser(userId);\n        return ResponseEntity.ok(user);\n    }\n}\n\n// Order Service에서 User Service 호출\n@Service\npublic class OrderService {\n    \n    @Autowired\n    private RestTemplate restTemplate;\n    \n    private static final String USER_SERVICE_URL = \"http://user-service/api/users\";\n    \n    public User getUser(Long userId) {\n        return restTemplate.getForObject(\n            USER_SERVICE_URL + \"/\" + userId,\n            User.class\n        );\n    }\n}
\n

gRPC

\n
// user.proto\nsyntax = \"proto3\";\n\npackage user;\n\nservice UserService {\n  rpc GetUser(GetUserRequest) returns (UserResponse);\n  rpc CreateUser(CreateUserRequest) returns (UserResponse);\n}\n\nmessage GetUserRequest {\n  int64 user_id = 1;\n}\n\nmessage UserResponse {\n  int64 id = 1;\n  string name = 2;\n  string email = 3;\n}
\n
// gRPC 클라이언트\n@Service\npublic class OrderService {\n    \n    @Autowired\n    private UserServiceGrpc.UserServiceBlockingStub userServiceStub;\n    \n    public User getUser(Long userId) {\n        GetUserRequest request = GetUserRequest.newBuilder()\n            .setUserId(userId)\n            .build();\n        \n        UserResponse response = userServiceStub.getUser(request);\n        return convertToUser(response);\n    }\n}
\n

3-2. 비동기 통신 (메시징)

\n

Kafka를 활용한 이벤트 기반 아키텍처

\n
// Order Service - 이벤트 발행\n@Service\npublic class OrderService {\n    \n    @Autowired\n    private KafkaTemplate<String, Object> kafkaTemplate;\n    \n    public void createOrder(Order order) {\n        // 주문 생성\n        orderRepository.save(order);\n        \n        // 이벤트 발행\n        OrderCreatedEvent event = new OrderCreatedEvent(\n            order.getId(),\n            order.getUserId(),\n            order.getTotalAmount()\n        );\n        \n        kafkaTemplate.send(\"order-created\", event);\n    }\n}\n\n// Payment Service - 이벤트 구독\n@Component\npublic class PaymentEventListener {\n    \n    @KafkaListener(topics = \"order-created\")\n    public void handleOrderCreated(OrderCreatedEvent event) {\n        // 결제 처리\n        processPayment(event.getOrderId(), event.getAmount());\n    }\n}\n\n// Inventory Service - 이벤트 구독\n@Component\npublic class InventoryEventListener {\n    \n    @KafkaListener(topics = \"order-created\")\n    public void handleOrderCreated(OrderCreatedEvent event) {\n        // 재고 차감\n        decreaseInventory(event.getOrderId());\n    }\n}
\n

4. API Gateway

\n

4-1. API Gateway의 역할

\n\n

4-2. Kong API Gateway 설정

\n
# kong.yml\n_format_version: \"3.0\"\n\nservices:\n  - name: user-service\n    url: http://user-service:8080\n    routes:\n      - name: user-route\n        paths:\n          - /api/users\n        methods:\n          - GET\n          - POST\n          - PUT\n          - DELETE\n\n  - name: product-service\n    url: http://product-service:8080\n    routes:\n      - name: product-route\n        paths:\n          - /api/products\n\nplugins:\n  - name: rate-limiting\n    config:\n      minute: 100\n      hour: 1000\n  \n  - name: cors\n    config:\n      origins:\n        - \"*\"\n      methods:\n        - GET\n        - POST\n        - PUT\n        - DELETE
\n

4-3. Spring Cloud Gateway

\n
@Configuration\npublic class GatewayConfig {\n    \n    @Bean\n    public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {\n        return builder.routes()\n            .route(\"user-service\", r -> r\n                .path(\"/api/users/**\")\n                .uri(\"lb://user-service\"))\n            .route(\"product-service\", r -> r\n                .path(\"/api/products/**\")\n                .uri(\"lb://product-service\"))\n            .route(\"order-service\", r -> r\n                .path(\"/api/orders/**\")\n                .filters(f -> f\n                    .addRequestHeader(\"X-Request-Id\", UUID.randomUUID().toString())\n                    .circuitBreaker(c -> c\n                        .setName(\"orderCircuitBreaker\")\n                        .setFallbackUri(\"forward:/fallback\")))\n                .uri(\"lb://order-service\"))\n            .build();\n    }\n    \n    @Bean\n    public GlobalFilter customGlobalFilter() {\n        return (exchange, chain) -> {\n            ServerHttpRequest request = exchange.getRequest();\n            // 로깅, 인증 등 전역 처리\n            return chain.filter(exchange);\n        };\n    }\n}
\n

5. Service Mesh (Istio)

\n

5-1. Istio 개요

\n

Service Mesh는 서비스 간 통신을 관리하는 인프라 레이어다.

\n

주요 기능:

\n\n

5-2. VirtualService와 DestinationRule

\n
# VirtualService - 트래픽 라우팅\napiVersion: networking.istio.io/v1beta1\nkind: VirtualService\nmetadata:\n  name: user-service\nspec:\n  hosts:\n    - user-service\n  http:\n    - match:\n        - headers:\n            version:\n              exact: v2\n      route:\n        - destination:\n            host: user-service\n            subset: v2\n          weight: 100\n    - route:\n        - destination:\n            host: user-service\n            subset: v1\n          weight: 90\n        - destination:\n            host: user-service\n            subset: v2\n          weight: 10\n\n---\n# DestinationRule - 서비스 버전 정의\napiVersion: networking.istio.io/v1beta1\nkind: DestinationRule\nmetadata:\n  name: user-service\nspec:\n  host: user-service\n  subsets:\n    - name: v1\n      labels:\n        version: v1\n    - name: v2\n      labels:\n        version: v2\n  trafficPolicy:\n    loadBalancer:\n      simple: ROUND_ROBIN\n    connectionPool:\n      tcp:\n        maxConnections: 100\n      http:\n        http1MaxPendingRequests: 10\n        http2MaxRequests: 10\n        maxRequestsPerConnection: 2
\n

5-3. Circuit Breaker

\n
apiVersion: networking.istio.io/v1beta1\nkind: DestinationRule\nmetadata:\n  name: order-service\nspec:\n  host: order-service\n  trafficPolicy:\n    connectionPool:\n      tcp:\n        maxConnections: 100\n      http:\n        http1MaxPendingRequests: 10\n        maxRequestsPerConnection: 2\n    outlierDetection:\n      consecutiveErrors: 3\n      interval: 30s\n      baseEjectionTime: 30s\n      maxEjectionPercent: 50
\n

6. 서비스 디스커버리

\n

6-1. Eureka (Netflix OSS)

\n
// Eureka Server\n@SpringBootApplication\n@EnableEurekaServer\npublic class EurekaServerApplication {\n    public static void main(String[] args) {\n        SpringApplication.run(EurekaServerApplication.class, args);\n    }\n}\n\n// application.yml\nserver:\n  port: 8761\n\neureka:\n  instance:\n    hostname: localhost\n  client:\n    registerWithEureka: false\n    fetchRegistry: false
\n
// Eureka Client (서비스)\n@SpringBootApplication\n@EnableEurekaClient\npublic class UserServiceApplication {\n    public static void main(String[] args) {\n        SpringApplication.run(UserServiceApplication.class, args);\n    }\n}\n\n// application.yml\nspring:\n  application:\n    name: user-service\n\neureka:\n  client:\n    serviceUrl:\n      defaultZone: http://localhost:8761/eureka/\n  instance:\n    preferIpAddress: true
\n

6-2. Consul

\n
# consul-config.yml\nservices:\n  - name: user-service\n    id: user-service-1\n    address: user-service\n    port: 8080\n    check:\n      http: http://user-service:8080/health\n      interval: 10s\n      timeout: 1s
\n

7. 분산 트레이싱

\n

7-1. Jaeger를 활용한 분산 트레이싱

\n
// Spring Cloud Sleuth + Zipkin/Jaeger\n@Configuration\npublic class TracingConfig {\n    \n    @Bean\n    public Sampler sampler() {\n        return Sampler.create(0.1f); // 10% 샘플링\n    }\n}\n\n// application.yml\nspring:\n  sleuth:\n    sampler:\n      probability: 0.1\n    zipkin:\n      base-url: http://jaeger:9411
\n
// 수동 트레이싱\n@Service\npublic class OrderService {\n    \n    @Autowired\n    private Tracer tracer;\n    \n    public void createOrder(Order order) {\n        Span span = tracer.nextSpan()\n            .name(\"create-order\")\n            .tag(\"order.id\", order.getId().toString())\n            .start();\n        \n        try (Tracer.SpanInScope ws = tracer.withSpanInScope(span)) {\n            // 주문 생성 로직\n            processOrder(order);\n        } finally {\n            span.end();\n        }\n    }\n}
\n

7-2. OpenTelemetry

\n
@Configuration\npublic class OpenTelemetryConfig {\n    \n    @Bean\n    public OpenTelemetry openTelemetry() {\n        return OpenTelemetrySdk.builder()\n            .setTracerProvider(\n                SdkTracerProvider.builder()\n                    .addSpanProcessor(\n                        BatchSpanProcessor.builder(\n                            OtlpGrpcSpanExporter.builder()\n                                .setEndpoint(\"http://jaeger:4317\")\n                                .build()\n                        ).build()\n                    )\n                    .setResource(\n                        Resource.getDefault()\n                            .merge(Resource.builder()\n                                .put(ResourceAttributes.SERVICE_NAME, \"order-service\")\n                                .build())\n                    )\n                    .build()\n            )\n            .build();\n    }\n}
\n

8. 데이터 일관성

\n

8-1. Saga 패턴

\n
// Saga 오케스트레이터\n@Component\npublic class OrderSagaOrchestrator {\n    \n    @Autowired\n    private OrderService orderService;\n    \n    @Autowired\n    private PaymentService paymentService;\n    \n    @Autowired\n    private InventoryService inventoryService;\n    \n    @SagaOrchestrationStart\n    public void createOrderSaga(CreateOrderCommand command) {\n        Order order = orderService.createOrder(command);\n        \n        try {\n            // 1. 재고 확인 및 차감\n            inventoryService.reserveInventory(order);\n            \n            // 2. 결제 처리\n            paymentService.processPayment(order);\n            \n            // 3. 주문 확정\n            orderService.confirmOrder(order.getId());\n            \n        } catch (Exception e) {\n            // 보상 트랜잭션\n            compensate(order);\n        }\n    }\n    \n    private void compensate(Order order) {\n        try {\n            if (order.getStatus() == OrderStatus.PAYMENT_PROCESSED) {\n                paymentService.refund(order);\n            }\n            if (order.getStatus() == OrderStatus.INVENTORY_RESERVED) {\n                inventoryService.releaseInventory(order);\n            }\n            orderService.cancelOrder(order.getId());\n        } catch (Exception e) {\n            // 보상 실패 로깅 및 알림\n            log.error(\"Compensation failed for order: {}\", order.getId(), e);\n        }\n    }\n}
\n

8-2. 이벤트 소싱과 CQRS

\n
// 이벤트 저장소\n@Entity\npublic class EventStore {\n    @Id\n    private String id;\n    private String aggregateId;\n    private String eventType;\n    private String eventData;\n    private LocalDateTime timestamp;\n}\n\n// 이벤트 발행\n@Service\npublic class OrderService {\n    \n    @Autowired\n    private EventStoreRepository eventStoreRepository;\n    \n    public void createOrder(Order order) {\n        // 이벤트 저장\n        OrderCreatedEvent event = new OrderCreatedEvent(\n            order.getId(),\n            order.getUserId(),\n            order.getItems()\n        );\n        \n        eventStoreRepository.save(EventStore.builder()\n            .id(UUID.randomUUID().toString())\n            .aggregateId(order.getId().toString())\n            .eventType(\"OrderCreated\")\n            .eventData(serialize(event))\n            .timestamp(LocalDateTime.now())\n            .build());\n        \n        // 이벤트 발행\n        eventPublisher.publish(event);\n    }\n}\n\n// CQRS - 읽기 모델 업데이트\n@Component\npublic class OrderReadModelUpdater {\n    \n    @EventListener\n    public void handle(OrderCreatedEvent event) {\n        // 읽기 모델 업데이트\n        orderReadRepository.save(OrderReadModel.builder()\n            .id(event.getOrderId())\n            .userId(event.getUserId())\n            .status(\"CREATED\")\n            .build());\n    }\n}
\n

9. 모니터링과 관찰 가능성

\n

9-1. Prometheus와 Grafana

\n
// 메트릭 수집\n@Service\npublic class OrderService {\n    \n    private final Counter orderCounter;\n    private final Timer orderProcessingTime;\n    \n    public OrderService(MeterRegistry meterRegistry) {\n        this.orderCounter = Counter.builder(\"orders.total\")\n            .description(\"Total number of orders\")\n            .register(meterRegistry);\n        \n        this.orderProcessingTime = Timer.builder(\"orders.processing.time\")\n            .description(\"Order processing time\")\n            .register(meterRegistry);\n    }\n    \n    public void createOrder(Order order) {\n        Timer.Sample sample = Timer.start();\n        try {\n            // 주문 처리\n            processOrder(order);\n            orderCounter.increment();\n        } finally {\n            sample.stop(orderProcessingTime);\n        }\n    }\n}
\n

9-2. 분산 로깅 (ELK Stack)

\n
// 로깅 설정\n@Configuration\npublic class LoggingConfig {\n    \n    @Bean\n    public CorrelationIdFilter correlationIdFilter() {\n        return new CorrelationIdFilter();\n    }\n}\n\n@Component\npublic class CorrelationIdFilter implements Filter {\n    \n    @Override\n    public void doFilter(ServletRequest request, ServletResponse response, \n                        FilterChain chain) throws IOException, ServletException {\n        String correlationId = UUID.randomUUID().toString();\n        MDC.put(\"correlationId\", correlationId);\n        \n        try {\n            chain.doFilter(request, response);\n        } finally {\n            MDC.clear();\n        }\n    }\n}\n\n// 로깅\n@Slf4j\n@Service\npublic class OrderService {\n    \n    public void createOrder(Order order) {\n        log.info(\"Creating order: {}\", order.getId(), \n                 kv(\"userId\", order.getUserId()),\n                 kv(\"amount\", order.getTotalAmount()));\n        \n        try {\n            processOrder(order);\n            log.info(\"Order created successfully: {}\", order.getId());\n        } catch (Exception e) {\n            log.error(\"Failed to create order: {}\", order.getId(), e);\n            throw e;\n        }\n    }\n}
\n

10. 보안

\n

10-1. mTLS (Mutual TLS)

\n
# Istio PeerAuthentication\napiVersion: security.istio.io/v1beta1\nkind: PeerAuthentication\nmetadata:\n  name: default\nspec:\n  mtls:\n    mode: STRICT\n\n---\n# Istio AuthorizationPolicy\napiVersion: security.istio.io/v1beta1\nkind: AuthorizationPolicy\nmetadata:\n  name: user-service-policy\nspec:\n  selector:\n    matchLabels:\n      app: user-service\n  rules:\n    - from:\n        - source:\n            principals: [\"cluster.local/ns/default/sa/order-service\"]\n      to:\n        - operation:\n            methods: [\"GET\", \"POST\"]
\n

10-2. JWT 인증

\n
// API Gateway에서 JWT 검증\n@Component\npublic class JwtAuthenticationFilter implements GatewayFilter {\n    \n    @Override\n    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {\n        ServerHttpRequest request = exchange.getRequest();\n        String token = extractToken(request);\n        \n        if (token != null && validateToken(token)) {\n            return chain.filter(exchange);\n        }\n        \n        ServerHttpResponse response = exchange.getResponse();\n        response.setStatusCode(HttpStatus.UNAUTHORIZED);\n        return response.setComplete();\n    }\n    \n    private boolean validateToken(String token) {\n        try {\n            Jwts.parser()\n                .setSigningKey(secretKey)\n                .parseClaimsJws(token);\n            return true;\n        } catch (JwtException e) {\n            return false;\n        }\n    }\n}
\n

11. 실전 배포 전략

\n

11-1. Blue-Green 배포

\n
# Kubernetes Deployment\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: user-service-blue\nspec:\n  replicas: 3\n  selector:\n    matchLabels:\n      app: user-service\n      version: blue\n  template:\n    metadata:\n      labels:\n        app: user-service\n        version: blue\n    spec:\n      containers:\n      - name: user-service\n        image: user-service:v1.0.0\n        ports:\n        - containerPort: 8080\n\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: user-service\nspec:\n  selector:\n    app: user-service\n    version: blue  # blue에서 green으로 전환\n  ports:\n  - port: 80\n    targetPort: 8080
\n

11-2. 카나리 배포

\n
# Istio VirtualService - 카나리 배포\napiVersion: networking.istio.io/v1beta1\nkind: VirtualService\nmetadata:\n  name: user-service\nspec:\n  hosts:\n    - user-service\n  http:\n    - match:\n        - headers:\n            canary:\n              exact: \"true\"\n      route:\n        - destination:\n            host: user-service\n            subset: v2\n          weight: 100\n    - route:\n        - destination:\n            host: user-service\n            subset: v1\n          weight: 90\n        - destination:\n            host: user-service\n            subset: v2\n          weight: 10
\n

12. 결론

\n

마이크로서비스 아키텍처는 복잡하지만 강력한 아키텍처 패턴이다. 이 글에서 다룬 내용:

\n
    \n
  1. 설계 원칙: DDD, 데이터베이스 per 서비스, API First
    2. \n
  2. 서비스 통신: REST, gRPC, 메시징 (Kafka)
    3. \n
  3. API Gateway: Kong, Spring Cloud Gateway
    4. \n
  4. Service Mesh: Istio를 활용한 트래픽 관리
    5. \n
  5. 서비스 디스커버리: Eureka, Consul
    6. \n
  6. 분산 트레이싱: Jaeger, OpenTelemetry
    7. \n
  7. 데이터 일관성: Saga 패턴, 이벤트 소싱
    8. \n
  8. 모니터링: Prometheus, Grafana, ELK
    9. \n
  9. 보안: mTLS, JWT
    10. \n
  10. 배포 전략: Blue-Green, 카나리
    11. \n
\n

이러한 기술들을 조합하면 확장 가능하고 견고한 마이크로서비스 시스템을 구축할 수 있다.

\n

참고 자료

\n","tableOfContents":"","wordCount":{"words":408},"fields":{"slug":"/springboot/마이크로서비스-아키텍처-완전정복-실전-구축-가이드/","image":null,"faq":[]},"frontmatter":{"title":"마이크로서비스 아키텍처 완전정복 - 실전 구축 가이드","date":"2025년 11월 15일","dateISO":"2025-11-15T00:00:00.000Z","updatedISO":null,"category":"springboot","description":"마이크로서비스 아키텍처의 설계 원칙부터 실전 구현까지. Service Mesh(Istio), API Gateway(Kong), 분산 트레이싱(Jaeger), 서비스 디스커버리, 이벤트 기반 아키텍처, 데이터 일관성, 모니터링까지 엔터프라이즈급 마이크로서비스 시스템 구축의 모든 것을 다룹니다.","tags":["마이크로서비스","Microservices","Service Mesh","API Gateway","분산 시스템","Istio","Kong","Jaeger","Kubernetes","이벤트 기반 아키텍처","Spring Cloud"]}}},"pageContext":{"slug":"/springboot/마이크로서비스-아키텍처-완전정복-실전-구축-가이드/","previous":{"fields":{"slug":"/ai/Responsible-AI-Operations-Part-2-위험-모니터링과-자동화-파이프라인/"},"frontmatter":{"title":"Responsible AI Operations Part 2 위험 모니터링과 자동화 파이프라인","tags":["Responsible AI","위험 모니터링","Observability","AI 레드팀","Alert Automation","Error Budget"]}},"next":{"fields":{"slug":"/python/FastAPI-완전정복-고성능-비동기-웹-API-개발-가이드/"},"frontmatter":{"title":"FastAPI 완전정복 - 고성능 비동기 웹 API 개발 실전 가이드","tags":["FastAPI","Python","비동기 프로그래밍","웹 API","REST API","asyncio","Pydantic","WebSocket","데이터베이스","백엔드 개발"]}}}},"staticQueryHashes":["213619243","3262363727"]}