이전 포스팅에 이어서 아이디에이션 과정과 개발 과정을 포스팅해보려고 한다

1. XMLHttpRequest 인터셉트 구현

이전 포스팅에서 설명한 것과 같이 XMLHttpRequest 방식과 Fetch API 방식을 모두 구현해서 최대한 많은 환경을 커버하는 것을 목표로 하고 있다.

(XMLHttpRequest는 다른 블로거분의 포스팅을 참고하면 어떤 용도로 사용하는지 쉽게 이해할 수 있을 것 같다)

💡 어떻게 사용하도록 할까?

일단 필자가 생각한 Usage는 다음과 같다.

CustomMockService.get("/api/v1", mockData);
CustomMockService.get("/api/v1", params, mockData);
CustomMockService.post("/api/v1", requestBody, mockData);

위의 방식처럼 endpoint, reuqest, 그리고 반환할 mockData 를 전달받도록 하는게 좋을 것 같다.

다만, 위처럼 받을 경우에는 사용법에 대한 숙지가 덜되어있다면 문제가 발생할수도 있을 것 같았다.

그래서 다음과 같이 객체 형식으로 받는게 더 좋을 것 같다고 판단했다.

CustomMockService.get({endpoint : "api/v1", response : mockData});
CustomMockService.get({endpoint : "api/v1", params, response : mockData});
CustomMockService.post({endpoint : "api/v1", request : postRequest, response : mockData});

💡 구현 아이디어

구현 아이디어는 다음과 같다.

위처럼 사용하기 위해서는 CustomMockService라는 클래스를 생성하고, 그 내부에서 static으로 객체를 관리하려고 한다.

또한, get, post, patch, delete 는 모두 static으로 외부에 노출시키는게 지금 아이디어로는 적절하다고 생각한다.

따라서 다음과 같이 구현하려고 한다.

export class CustomMockService {
  private static getMockMapping = new Map<string, any>();
  private static postMockMapping = new Map<string, any>();
  private static patchMockMapping = new Map<string, any>();
  private static deleteMockMapping = new Map<string, any>();
  ...

  static post({
    endPoint,
    request = null,
    response,
  }: {
    endPoint: string;
    request?: any;
    response: any;
  }) {
    this.postMockMapping.set(`${endPoint}`, { request, response });
  }
}

이런식으로 내부에서 Map으로 각 모킹 데이터를 관리하고 키로는 endpoint를 사용하면 될 것 같다.

2. XHR 응답 추출하기

XMLHttpRequest를 활용한 API 호출을 Mock으로 대체하기 위해서는 XHR의 라이프사이클을 이해하고 적절한 시점에서 요청 정보를 추출해야 한다.

XHR 요청은 크게 두 단계로 나뉜다.

1. xhr.open(): 요청 준비 단계 - HTTP 메서드와 URL이 설정되는 단계 - 아직 실제 네트워크 요청은 발생하지 않음 2. xhr.send(): 요청 실행 단계 - 실제 네트워크 요청이 시작 - Request Body가 전송된다.

즉, httpMethod와 url, 그리고 params는 xhr.open 에서 추출해야하고 requestbody는 xhr.send 에서 추출해야 한다.

그래서 코드를 작성해보면 다음과 같다.

// XHR 데이터에서 추출
static patchXHR() {
  const OriginalXHR = window.XMLHttpRequest;
  (window.XMLHttpRequest as any) = function () {
    const xhr = new OriginalXHR();

    let httpMethod: string;
    let requestUrl: string;
    let urlParams: URLSearchParams;

    const originalOpen = xhr.open;
    xhr.open = function (
    m: string,
     u: string,
     async?: boolean,
     user?: string,
     password?: string
    ) {
      httpMethod = m;
      requestUrl = u;
      urlParams = new URLSearchParams(new URL(u).search);

      return originalOpen.call(this, m, u, async || true, user, password);
    };

    const originalSend = xhr.send;
    xhr.send = function (body?: any) {
      const requestBody = body; // 나중에 생각
      const mockData = CustomMockServer.findMockData(httpMethod, requestUrl);

      if (mockData) {
        console.log("Mock 데이터 존재 O -> 가짜 응답 반환", mockData);
        CustomMockServer.returnMockResponse(xhr, mockData);
      }

      console.log("Mock 데이터 X -> 실제 요청 진행");
      return originalSend.call(this, body);
    };

    return xhr;
  };
}

// 관련 함수
private static findMockData(httpMethod: string, requestUrl: string) {
  let mapping;

  switch (httpMethod) {
    case "GET":
      mapping = CustomMockServer.getMockMapping.get(requestUrl);
      break;
    case "POST":
      mapping = CustomMockServer.postMockMapping.get(requestUrl);
      break;
    case "PATCH":
      mapping = CustomMockServer.patchMockMapping.get(requestUrl);
      break;
    case "DELETE":
      mapping = CustomMockServer.deleteMockMapping.get(requestUrl);
      break;
  }
  return mapping;
}

private static returnMockResponse = (xhr: XMLHttpRequest, mockData: any) => {
  Object.defineProperty(xhr, "readyState", { value: 4 });
  Object.defineProperty(xhr, "status", { value: 200 });
  Object.defineProperty(xhr, "responseText", {
    value: JSON.stringify(mockData.response),
  });

  if (xhr.onreadystatechange) {
    xhr.onreadystatechange.call(xhr, new Event("readystatechange"));
  }
  if (xhr.onload) {
    xhr.onload.call(xhr, new ProgressEvent("load"));
  }
};

여기서 한가지 중요한 부분은 목데이터 응답을 생성하는 부분이다. xhr 객체는 기본적으로 ReadOnly이므로 defineProperty 속성을 통해 강제로 값을 변경해야한다.

물론 위에서 아직 완전한 완성본은 아니기 때문에, status 등의 값은 임의로 200으로 생성하도록 만들어놨다.

이처럼 defineProperty를 통해 목데이터 응답을 실제 서버 응답처럼 변경했다면 이벤트를 발생시킴으로써 다른 라이브러리가 이 변화를 인식할 수 있도록 해야한다.

xhr.onreadystatechange 과 xhr.onload 부분이 이에 해당한다.

(공식문서를 참고해보면 자세히 설명되어있다)

3. 테스트

이제 XHR 부분을 한번 테스트해보자

아쉽게도 일렉트론 환경에서 테스트를 진행해봤는데, 일렉트론에서 IPC 통신 방법을 사용하는 경우에는 API 모킹을 못할 것 같다..

(그 이유는 나중에 다루도록 하겠다)

그래서 일단 이전에 진행했던 웹 어플리케이션 환경에서 테스트를 진행해보자

async function startApp() {
  // Mock 데이터 등록 먼저 진행하고
  dataMocking();

  // 그 다음 MockServer 실행
  CustomMockServer.run();

  createRoot(document.getElementById("root")!).render(
    <StrictMode>
      <App />
    </StrictMode>,
  );
}

void startApp();

import { CustomMockServer } from "@sung-yeop/custom-mock-service";

export const dataMocking = () => {
  // POST /auth/login 모킹 (전체 URL)
  CustomMockServer.post({
    endPoint: "https://dev-api.ceo.popi.today/auth/login",
    response: {
      success: true,
      status: 200,
      data: {
        accessToken:
          "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJwb3BpX21hbmFnZXJfZGIiLCJzdWIiOiIxIiwicm9sZSI6IlVTRVIiLCJpYXQiOjE3NDYzODE4ODYsImV4cCI6MTc0NjM4NTQ4Nn0.ZIcwk29mLjMhMDHz6s_xzWTqN_Z8MXN8iMzu0IliePVlq7zaL_P5iNDwFWA8G7CCiRimFjZBnHgJJUF4IS6qVg",
      },
      timestamp: "2025-05-05T03:04:46.939793",
    },
  });

  console.log("Mock 데이터 등록 완료");
};

일단 사용해보니 endPoint 앞쪽에 prefix를 제거하는 로직을 추가하지 않아서 전체 엔드포인트로 맞춰놓고 모킹을 시도해봤다.

결과는 사진과 같이 제대로 API 요청을 인터셉트하여 네트워크 탭에는 요청이 생기지 않는 모습을 볼 수 있었다.

하지만, 라우팅이 제대로 되지 않는 모습을 볼 수 있었다.

const handleLogin = () => {
  login({ username, password })
    .then(() => navigate("/popup-list"))
    .catch(() => setIsOpenModal(true));
};

관련 로직을 살펴보면 다음과 같이 login이라는 요청이 성공하면 페이지 라우팅을 진행해야한다.

그래서 패키지 내부에서 로깅을 추가해보니 다음과 같이 콘솔 로그가 찍히는 모습을 볼 수 있었다.

즉, API 모킹은 정상적으로 되었으나 .then 이 작동하지 않는 문제였다.

const login = async ({ username, password }: LoginRequest) => {
  try {
    const response = await postLoginMutation.mutateAsync({
      username,
      password,
    });
    console.log("응답 : ", response);
    setLogin(response.data.accessToken);
  } catch (error) {
    throw new Error(`로그인 오류 ${ErrorMessage(error)}`);
  }
};

위 코드와 같이 내부 login 로직에서 응답을 확인하는 로깅을 찍어봤으나 이또한 로깅이 되지 않았다.

따라서, 비동기 문제라고 판단이 되었고 이를 해결할 방법을 찾아야했다.

4. 문제 해결

우리는 이벤트 드리븐 방식으로 목 데이터를 반환하도록 코드를 구성했다.

이전에 소개했던 목데이터 반환 방법을 보면 다음과 같다.

// 기존에 작성했던 코드
private static returnMockResponse = (xhr: XMLHttpRequest, mockData: any) => {
  Object.defineProperty(xhr, "readyState", { value: 4 });
  Object.defineProperty(xhr, "status", { value: 200 });
  Object.defineProperty(xhr, "responseText", {
    value: JSON.stringify(mockData.response),
  });

  if (xhr.onreadystatechange) {
    xhr.onreadystatechange.call(xhr, new Event("readystatechange"));
  }
  if (xhr.onload) {
    xhr.onload.call(xhr, new ProgressEvent("load"));
  }
};

XHR 동작 순서

1. readystatechange (readyState: 1) // OPENED
2. readystatechange (readyState: 2) // HEADERS_RECEIVED
3. readystatechange (readyState: 3) // LOADING
4. readystatechange (readyState: 4) // DONE
5. load // 성공 완료
6. loadend // 최종 완료 (성공/실패 무관)

우선 위 코드에서 Response를 반환하기 위해 defineProperty 를 통해 readyState를 4로 변경하여 DONE 상태로 변경한다.

이후, XHR 객체의 onreadystatechange, onload가 존재할 경우 각 메서드에 매칭되는 이벤트를 발행시키는 방법을 사용했다.

하지만, 위의 코드로는 동작하지 않아서 여러 방면으로 찾아보다가 다음과 같은 라이브러리를 확인할 수 있었다.

function onloadend() {
  if (!request) {
    return;
  }
  // Prepare the response
  var responseHeaders = 'getAllResponseHeaders' in request ? parseHeaders(request.getAllResponseHeaders()) : null;
  var responseData = !responseType || responseType === 'text' ||  responseType === 'json' ?
      request.responseText : request.response;
  var response = {
    data: responseData,
    status: request.status,
    statusText: request.statusText,
    headers: responseHeaders,
    config: config,
    request: request
  };

  settle(function _resolve(value) {
    resolve(value);
    done();
  }, function _reject(err) {
    reject(err);
    done();
  }, response);

  // Clean up request
  request = null;
}

위 코드는 Axios Adapter 구현 코드 중 일부인데, 모든 코드를 한번에 보고 이해할 수는 없었으나,onloadend 라는 이벤트가 발생하는 경우 settle 이라는 함수를 통해서 resolve 혹은 reject를 시키는 모습을 볼 수 있다.

그래서 코드를 다음과 같이 onloadend 이벤트를 발행시키도록 수정했다.

 private static returnMockResponse = (xhr: XMLHttpRequest, mockData: any) => {
    setTimeout(() => {
      Object.defineProperty(xhr, "readyState", {
        value: 4,
        configurable: true,
      });
      Object.defineProperty(xhr, "status", { value: 200, configurable: true });
      Object.defineProperty(xhr, "statusText", {
        value: "OK",
        configurable: true,
      });
      Object.defineProperty(xhr, "responseText", {
        value: JSON.stringify(mockData.response),
        configurable: true,
      });
      Object.defineProperty(xhr, "response", {
        value: JSON.stringify(mockData.response),
        configurable: true,
      });

      const readystateEvent = new Event("readystatechange");
      if (xhr.onreadystatechange)
        xhr.onreadystatechange.call(xhr, readystateEvent);

      const loadEvent = new ProgressEvent("load");
      if (xhr.onload) xhr.onload.call(xhr, loadEvent);

      const loadendEvent = new ProgressEvent("loadend"); // 추가된 부분
      if (xhr.onloadend) xhr.onloadend.call(xhr, loadendEvent);

      console.log("Mock 응답 완료");
    }, 50);
  };

그 결과 useAuth.ts 에서 response 결과가 잘 나오는 모습을 확인할 수 있었다.

즉, Axios는 Promise 객체를 사용하여 resolve 혹은 reject를 판단하는 과정에서 사용되는 이벤트가 XHR의 loadend 이벤트라는 의미이다.

여기서 개발하면서 느낀 것 중하나가 setTimeout을 이용한 비동기 설정을 추가해야만 실제 서버에서 응답을 받아오는 순서처럼 동작한다는 것이다.

실제 응답 순서를 생각해보면 다음과 같다.

xhr.open() (요청 설정) -> xhr.send() (서버로 요청 전송 / 함수 즉시 반환) -> 서버에서 처리 중 (시간 소요 / setTimeout으로 구현) -> 서버가 응답을 보냄 -> xhr.onloadend 등의 이벤트 핸들러 실행 -> 응답 데이터를 처리하여 클라이언트에 반환

즉, setTimeout을 이용하여 실제 서버 동작과 유사하게 개발하는게 중요하다는 것을 잊지말자

OUTRO

지금 생각해보면 목서비스 패키지를 만드는게 꽤 번거로운 작업들이 많은 것 같다.

부수적인 역할이지만 로컬 스토리지에 데이터를 저장하는 기능을 추가할 수도 있을 것 같고, endpoint도 쉽게 정의하여 사용할 수 있도록 수정해야하고, status, application 타입, 파일 통신 등의 기능을 제공하기 위해서는 가야할길이 꽤 먼 것 같다.

또한, 실제로 테스팅을 해보니 API 모킹 구현체들을 run이 실행된 이후에 등록되도록 호출해야한다.

관련 컴포넌트를 제공할지 아니면 run에다가 handler들을 모아둔 이후 실행시킬지 고민중이다.

일단 코드를 한쪽에 몰아써서 구현하느라 이해하기 어려운 것 같아서 리팩토링 작업부터 진행하고 XHR을 이용한 모킹부분부터 마무리하도록 해야겠다

웹 개발을 진행할때는 주로 MSW를 사용해서 서버 상태를 모킹시켜서 사용하곤 했었다.

하지만, POPI 프로젝트에서 사용자 어플리케이션을 개발할 때, 그리고 이번에 진행하는 Nextron 프로젝트를 진행하면서도 MSW는 동작하지 않았다.

물론 필자가 세팅을 제대로 못한 것일수도 있으나, 개인적으로는 레퍼런스를 많이 찾아봤고 그만큼 시간도 많이 쏟았기 때문에 이정도의 세팅 허들이 있는 것이 마음에 들지 않았다.

솔직히 될지는 모르겠지만, 그래서 API 모킹을 제공하는 라이브러리를 한번 만들어보려고 한다.

1. 어떻게 설계할 것인가?

일단 필자는 Usage를 먼저 생각해보는 것 같다.

즉, 내가 만든 라이브러리를 어떻게 호출해서 사용할 것인가? 를 생각해보는 것부터 시작해보려고 한다.

우선 아이디어는 다음과 같다.

💡 Mock Server 실행

사용자는 목서버를 일단 프로젝트 루트 디렉토리에서 실행하도록 설명서를 제공할 것이다.

MSW를 사용하다보니 아무래도 그 영향을 많이 받은 것 같기도하다.

프로젝트 루트에서는 다음과 같이 사용하도록 만들 것이다.

export default App() {
  CustomMockServer.run({isDevRun : true})

  return ...
}

• isDevRun은 개발환경에서만 실행할것인지를 설정하는 옵션으로 제공하는게 좋을 것 같다.
• Default는 True로 제공하여 CustomMockServer.run() 으로도 간단하게 실행할 수 있도록 만들어보려고 한다.

💡 네트워크 요청 가로채기

목서버를 동작시킨다면 당연히 네트워크 요청을 가로채서 실제 동작하는 것처럼 만들어야 할 것이다.

웹 애플리케이션에서 API 요청을 가로채는 방법은 크게 3가지가 있다. 각각의 방식은 서로 다른 장단점을 가지고 있으며, 프로젝트의 요구사항에 따라 적절한 방식을 선택해야 한다.

🔧 Service Worker 방식 (MSW가 사용하는 방식)

Service Worker는 브라우저의 네트워크 레이어에서 동작하는 별도의 워커 스레드를 활용한 방식이다.

// public/mockServiceWorker.js
self.addEventListener('fetch', (event) => {
 const { request } = event;
 if (shouldMock(request.url)) {
   event.respondWith(
     new Response(JSON.stringify(mockData), {
       status: 200,
       headers: { 'Content-Type': 'application/json' }
     })
   );
 }
});

이 방식의 가장 큰 특징은 Network 탭에서 실제 HTTP 요청처럼 확인 가능하다는 것이다.

즉, 디버깅이 용이하지만, MSW를 사용해본 사람이라면 별도의 .js 파일을 등록해줘야하는 번거로움이 있고, 필요시 세팅을 추가로 진행해야한다는 문제가 있다.

• 하지만 사용성은 제일 좋긴하다..

🔧 XMLHttpRequest Patching 방식

XMLHttpRequest 클래스를 교체하여 전통적인 AJAX 요청을 가로채는 방식이라고 한다.

const OriginalXHR = window.XMLHttpRequest;

window.XMLHttpRequest = function() {
  const xhr = new OriginalXHR();
  const originalOpen = xhr.open;
  const originalSend = xhr.send;

  xhr.open = function(method, url) {
    this._method = method;
    this._url = url;
    return originalOpen.apply(this, arguments);
  };

  xhr.send = function(data) {
    if (shouldMock(this._method, this._url)) {
      setTimeout(() => {
        this.readyState = 4;
        this.status = 200;
        this.responseText = JSON.stringify(mockData);
        if (this.onreadystatechange) this.onreadystatechange();
      }, 0);
      return;
    }
    return originalSend.apply(this, arguments);
  };

  return xhr;
};

찾아본 내용으로는 오래된 라이브러리나 jQuery와 같은 XHR 기반 코드와 호환에 용이하다고 한다.

하지만, Fetch API와는 호환이 되지 않는다고 한다.

필자가 만들려고하는 목서비스 패키지가 레거시까지 지원하는걸 고려한다면 이 코드를 참고해야할 것 같다.

코드를 보면 간단하게 xhr 인스턴스를 window.XMLHttpRequest 에서 받아온 다음, 해당 인스턴스의 xhr.open 과 xhr.send 를 내가 원하는 방식으로 조작해서 return하면 되는 것 같다.

• 찾아보니 해당 방법은 네트워크 탭에서 확인이 어렵다고 한다.
• 아마도 네트워크 레이어에서 바로 처리되기 때문인 것 같다.

🔧 Fetch API Patching 방식

브라우저의 전역 fetch 함수를 직접 교체하여 요청을 가로채는 방식이다.

const originalFetch = window.fetch;

window.fetch = function(url, options) {
  if (shouldMock(url, options?.method)) {
    return Promise.resolve(
      new Response(JSON.stringify(mockData), {
        status: 200,
        headers: { 'Content-Type': 'application/json' }
      })
    );
  }

  return originalFetch(url, options);
};

window.fetch 를 가로채서 originalFetch(url, options) 를 우리가 원하는대로 수정해서 보내주면 되는 것 같다.

어디선가 해본 것 같아서 코드가 낯설지는 않는 느낌이다.

마찬가지로 Fetch API를 가로채는 방식또한 네트워크 레이어에서 진행되기 때문에 네트워크 탭에서는 안보인다고 한다.

2. 아이디어

필자는 MSW의 번거로운 설정을 피하기 위해 별도의 패키지를 만들어보려고 하는 만큼, 간단한 사용성을 목표로 하고 있다.

따라서, Fetch API 와 XMLHttpRequest Patching 을 모두 지원하는 형태로 구현을 진행하지 않을까 싶다.

이 부분은 우선 만들어보고 테스트를 진행해본 이후, 변경될 수도 있을 것 같다.

💡 네트워크 탭은?

MSW를 사용하면서 가장 좋았던 부분은 네트워크 탭을 통한 디버깅이다.

실제 API를 호출한 것처럼 네트워크 탭을 통해서 자세한 API Request & Response를 확인할 수 있었던 경험은 그대로 가져가고 싶다.

ReactQueryDevTool 을 사용해보면 알겠지만, 캐시 상태를 보여주기 위해 해당 툴은 별도의 UI를 제공한다.

아마도 이런식으로 인터셉트한 네트워크 요청을 별도의 UI를 통해서 제공해주면 어떨까 싶다.

OUTRO

서비스 워커를 별도로 구현하는 것은 개발 공수가 엄청 들어가고, 냉정하게 그런 Low Level에서 동작하는 프로세스를 구현할 실력은 아직 없다고 생각한다.

그래서 우선 될지는 모르겠지만 목서비스 패키지를 한번 만들어보는 과정을 기록하면서 공부해보고, 실패하더라도 왜 실패했는지 원인분석을 해보는 것에 의의를 가지도록 하자 👊

최근에 커스텀 로깅 패키지를 만들면서 apiValidation 이라는 유틸리티를 구현하려고 했다.

아이디어는 간단했다. 제네릭으로 타입을 받고 매개변수로 response를 받아서 타입 체크를 통해 문제가 있는 경우에만 콘솔로그를 찍도록 하는 것이었다.

하지만 구현 과정에서 TypeScript의 아주 기본적인 동작을 놓치고 있었기에 포스팅을 통해 회고해보려고 한다.

1. 초기 아이디어

개발하다 보면 이런 상황들이 자주 발생한다

API 응답이 예상한 타입과 다른데 런타임에서야 발견됨 타입스크립트는 컴파일 타임에만 체크하고 런타임에서는 알 수 없음 매번 수동으로 응답 데이터를 검증하기 번거로움

export const postA = async (params: ApiRequest) => {
  const response = await api.post<ApiResponse>(
    "/sample",
    params
  );
  return response.data;
};

주로 이러한 방식으로 제네릭을 통해 타입 추론이 진행되도록 프론트에서 코드를 작성하는게 일반적이다.

하지만, 만약 백엔드에서 ApiResponse 타입에 맞지 않게 실수로 데이터를 넘겨주는 경우에는 postA 데이터를 사용하는 쪽에서 오류가 발생하게 된다.

(주로 사용하는쪽에서 undefined 가 발생하면 API를 잘못 넘겨주는 경우가 대부분이었다.)

경험상 네트워크 탭으로 API 응답 포맷을 명세와 비교하면서 찾았던 기억이 있다.

💡 원하는 기능

그래서 필자는 다음과 같은 기능을 구현해보고 싶었다.

간단한 제네릭 타입 검증

• Logger.apiValidation<User>(response) 이런 식으로 사용

• 자동 타입 체크*
• 런타임에서 실제 응답이 타입과 일치하는지 확인

• 문제 발생시에만 로깅*
• 타입이 맞으면 동작 X / 틀리면 상세한 에러 로그

2. 구현 아이디어 - 불가능

처음에는 정말 단순하게 생각했던거 같다.

위에도 적었지만 제네릭으로 타입을 받아서 런타임에 검증하면 되지 않을까? 라는 아이디어였다.

💡 이상적인 구현 (불가능)

class Logger {
 static apiValidation<T>(response: any): response is T {
   // T 타입의 구조를 알아서 response와 비교하고 싶었음
   const typeInfo = this.extractTypeInfo<T>();
   if(!Logger.validate(response, typeInfo)) {
     console.log("Api Response와 정의된 타입이 일치하지 않습니다.");
   };
 }
}

// 사용
const response = await api.get<ApiResponse>("/endpoint");
Logger.apiValidation<ApiResponse>(response)

하지만, 여기서 가장 중요한건 타입 스크립트는 컴파일시 타입 내용이 사라진다 이다.

즉, 타입 자체가 값이 아니기 때문에 컴파일 시점에서는 이 타입이 사라지게 된다.

따라서, 타입을 이용한 값 검증 자체가 불가능하다.

3. 그래서 스키마 정의가 필요한 이유

이 시점에서 Zod를 다시 살펴보게 되었다.

왜 이렇게 복잡하게 스키마를 정의해야 하는 걸까?

import { z } from 'zod';

// 런타임에 존재하는 실제 객체로 스키마 정의
const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email()
});

// 타입은 스키마에서 추출
type User = z.infer<typeof UserSchema>;

// 런타임 검증
const result = UserSchema.safeParse(response);

여기서 직접 구현해보니 핵심을 이해할 수 있었다.

Zod는 내가 생각했던 아이디어와 정반대 방향으로 접근한다.

즉, 타입에서 스키마를 만드는 것이 아니라, 스키마에서 타입을 만드는 것이다.

이렇게 하면 UserSchema는 런타임에 실제로 존재하는 JavaScript 객체이기 때문에 실제 데이터와 비교할 수 있게 된다.

💡 왜 스키마 정의가 필요한가?

결국 정리해보면 다음과 같다.

TypeScript 타입 !== 런타임 객체

• 컴파일 후에는 타입 정보가 완전히 사라진다
• 런타임 검증을 위해서는 실제 JavaScript 객체가 필요하다!

OUTRO

이번에 API 검증 유틸리티를 만들어보면서 TypeScript의 타입 시스템과 런타임의 차이점을 명확히 이해할 수 있었다.

타입스크립트는 개발 시점의 안전성을 보장해주지만, 런타임 검증은 별개의 문제였다.

결국 두 영역을 모두 커버하려면 스키마 정의는 필수적이었다...

요즘 개발하면서 디버깅할 때 console.log를 자주 사용하는데, 로깅을 너무 대충찍다보니 관리하는게 꽤 복잡했다

특히 복잡한 프로젝트에서 여러 파일에 걸쳐 로그가 흩어져 있으면, 어느 파일의 어느 함수에서 출력된 건지 추적하기가 쉽지 않았다.

그래서 이번에는 호출 위치를 자동으로 추적해주는 Logger 유틸리티를 만들어보기로 했다

1. 초기 아이디어

개발하다 보면 이런 상황들이 자주 발생한다

여러 곳에서 console.log를 찍어놨는데 어디서 나온 로그인지 모르겠음 시간순으로 로그를 추적하고 싶은데 타임스탬프가 없어서 불편함 로그 레벨을 구분해서 관리하고 싶음

그래서 다음과 같은 기능들이 있으면 좋겠다고 생각했다

💡 원하는 기능들

파일 위치 자동 추적

• 어느 파일에서 호출됐는지 알 수 있으면 좋겠음
• 타임스탬프*
• 언제 호출됐는지 시간 정보 제공
• 로그 레벨*
• INFO, ERROR, WARN으로 구분
• 일관된 포맷*
• 일관화된 로그 출력

2. Stack Trace 활용하기

사실 많은 삽질을 했는데, 결국 찾아보니까 JavaScript의 Error 객체를 사용하면 현재 호출 스택 정보를 가져올 수 있다고 한다.

이를 활용해서 Logger가 어디서 호출되었는지 추적할 수 있다는 레퍼런스를 통해 구현해보기로 했다.

💡 첫 번째 시도

우선 간단하게 스택 정보를 확인해보자.

import { LogProps } from "../types/Logger.type";

export class Logger {
  private static isDev = process.env.NODE_ENV === "development";

  private static getCallerInfo() {
    const stack = new Error().stack; // 스택 추적
    console.log("stack : ", stack);
    if (!stack) return null;
    const caller = stack[1];
    return { caller };
  }

  static log({ message, logLevel }: LogProps) {
    const timestamp = new Date().toISOString();
    const callerInfo = Logger.getCallerInfo();

    if (logLevel === "INFO") {
      console.log("==============================");
      console.log(
        "파일 위치:", callerInfo?.caller,
        "\n", "Message:", message,
        "\n", "TimeStamp:", timestamp
      );
    }
  }
}

로그 결과를 살펴보면 파일 위치는 stack[3]에 저장되는 모습을 볼 수 있었다.

3. 파일 위치 파싱 로직 구현

스택 정보를 파싱해서 읽기 쉬운 형태로 변환해보자

import { LogProps } from "../types/Logger.type";

export class Logger {
  private static isDev = process.env.NODE_ENV === "development";

  private static getCallerInfo() {
    const stack = new Error().stack; // 스택 추적
    console.log("stack : ", stack);
    if (!stack) return null;

    const caller = stack.split("\n");
    const parserLineArr = caller[3].replace(/:\d+:\d+\)/, "").split("/");
    const fileLocation =
      parserLineArr.length > 2
        ? parserLineArr[parserLineArr.length - 2].concat(
            "/",
            parserLineArr[parserLineArr.length - 1]
          )
        : parserLineArr[parserLineArr.length - 1];

    return {
      fileLocation,
    };
  }

  static log({ message, logLevel }: LogProps) {
    const timestamp = new Date().toISOString();
    const callerInfo = Logger.getCallerInfo();

    if (logLevel === "INFO") {
      console.log("==============================");
      console.log(
        "파일 위치:", callerInfo?.fileLocation,
        "\n", "Message:", message,
        "\n", "TimeStamp:", timestamp
      );
    }
  }
}

caller[3]에서 마지막 : 으로 시작하는 코드 라인은 제거하고 파일 위치만 가져오도록 구현했다.

로컬에서는 제대로 동작하는 모습을 확인하고 다른 프로젝트에서 적용해보니 다음과 같이 로그가 찍히는 문제가 있었다.

dist/ 는 패키지를 빌드하면서 생긴 빌드 결과물을 저장하는 디렉토리인데, 트레이싱을 제대로 못하고 있는 것 같았다.

4. 빌드 환경 대응하기

패키지로 배포했을 때 dist/index 같은 빌드된 파일 경로가 나오는 문제를 해결해야 했다.

💡 실제 호출 위치 찾기

Logger 자체의 스택이 아닌, 실제로 Logger를 호출한 위치를 찾아야 했다.

따라서, 다음과 같은 로직을 추가했다.

let targetCaller = caller[3];
for (let i = 3; i < caller.length; i++) {
  if (
    !caller[i].includes("Logger.util") &&
    !caller[i].includes("dist/index")
  ) {
    targetCaller = caller[i];
    break;
  }
}

기존에는 caller[3]만 추적했으나, 해당 로직을 추가해서 dist/index 와 Logger.util.ts 파일을 제외한 실제 호출 위치를 찾도록 수정했다.

제대로 호출되는 모습을 볼 수 있었다.

OUTRO

이번에 Logger 유틸리티를 만들어보면서 JavaScript의 스택 추적 기능을 활용하는 방법을 배울 수 있었다.

처음에는 단순히 로그에 파일 위치만 추가하려고 했는데, 패키지 빌드 환경까지 고려해야한다는 걸 앞으로는 생각해야겠다.

이제부터 이 패키지에서 Logger.api, Logger.state 와 같이 로깅을 조금 더 쉽게할 수 있도록 유틸을 추가해나가면 될 것 같다!

(만들고나서 생각해보니 파일 위치 추적이 필요한가..?)

이번에 운이좋게도 새로운 프로젝트를 진행하게 되었다.

UI를 Next.js 환경에서 App Router를 사용하여 개발을 진행하는 중이다.

이전에 POPI 프로젝트를 진행하면서 고민했던 부분 중 하나는 에러를 어디서 어떻게 처리하는게 적절할까? 였다.

간단하게 Toast UI를 사용해서 사용자에게 에러가 발생했음을 알려주고 끝내는 것이상으로 코드 베이스에서 조금더 체계적으로 관리해보고 싶은 욕심이 항상 있었다.

해당 프로젝트에서 에러를 조금 더 체계적으로 관리해보려고 했던 고민과 그로인해 패키지를 만들어본 경험을 포스팅을 통해 공유해보고자 한다!

1. 초기 아이디어

우선 프로젝트에서 피그마 시안을 살펴봤을 때, 특정 에러가 발생하면 아주 비슷한 UI의 에러 페이지가 나타나도록 하는 요구사항이 있었다.

조금더 자세히 말하자면, 다음과 같다

When Error Occured

• A 페이지 Error 발생 -> A` 문구 & A` 버튼 이벤트
• B 페이지 Error 발생 -> B` 문구 & B` 버튼 이벤트

즉, 필자가 판단하기에는 동일한 에러 페이지를 재사용하는게 좋다고 판단했다

하지만 다음과 같은 문제가 있었다.

💡 callback을 전달할 수 없다!

프로젝트는 Next의 App Router 세팅으로 되어있었기 때문에, 페이지 라우팅을 위해서는 useRouter 를 사용하게 된다.

문제는 useRouter 를 사용해서 페이지로 데이터를 넘기기 위해서는 쿼리 파라미터를 사용해야하며, 버튼을 누를 때 발생하는 callback 함수를 넘기기가 애매하다는 것이다.

💡 util 함수 사용

그래서 처음에는 Util함수를 정의해서 이를 해결하려고 했다.

간단하게 아이디어를 공유해보면, 다음과 같이 코드를 작성할 수 있을 것 같다.

Sample Code

"use client";
>
import { ErrorCodeType } from "@/constants/Error";
import { useRouter } from "next/navigation";
>
export const useErrorRouter = () => {
  const router = useRouter();
>
  const errorRouter = (errorCode: ErrorCodeType) => {
    router.push(`/error?errorCode=${errorCode}`);
  };
>
  return { errorRouter };
};

위처럼 에러페이지에 상수로 정의되어있는 errorCode 를 넘겨준다

다음으로 에러 페이지에서는 이 에러 코드를 기반으로 미리 정의되어있는 에러 메세지를 불러올 수 있다

Sample Code

"use client";
>
export default function ErrorPage() {
  const searchParams = useSearchParams();
  const errorCode = searchParams.get("errorCode") as ErrorCodeType;
>
  return (
    <div className="flex flex-col justify-center items-center h-screen">
      <Image src={failed} width={300} alt="실패 아이콘" />
      <p className="font-large-title-b mt-1 mb-6">
        {getErrorMessage(errorCode)}
      </p>
      <GlobalBtn
        title="Retry"
        onClick={() => {}}
        className="mt-16 py-4 px-[115.5px]"
      />
    </div>
  );
}

사용하는 곳에서는 다음과 같이 사용할 수 있을 것이다

Sample Code

 const { errorRouter, router } = useErrorRouter();
>
 const handle = () => {
    errorRouter(ERROR_CODES.AUTHENTICATION.INVALID_CREDENTIALS);
 };

여기서 발생하는 문제는 이전에도 언급한 것처럼 버튼을 클릭할 때 발생하는 callback을 넘겨줄 수 없다는 것이다.

커스텀 훅을 별도로 생성하는 경우에는 사용하는 곳마다 서로 다른 인스턴스가 생성되기 때문에 서로 다른 상태를 공유하게 된다.

따라서, 당연히 useErrorRouter 훅 내부에서 callback을 저장하는 상태변수를 선언하더라도 이를 사용하기란 어렵다.

간단하게 생각해보면, 에러를 핸들링하는 지점에서 정의된 callback을 전역상태에 저장하고 Error Page에서 사용하는 방식이 적절해보인다.

2. 전역 상태로 관리하는게 맞을까?

본 프로젝트에서는 전역 상태 관리툴로 Zustand 를 사용하고 있다.

아주 간단하게 코드를 작성한다면 Zustand로 Store를 하나 생성해서 에러발생시 callback을 store에 정의하고, Error Page에서 꺼내 사용하면 된다.

하지만 Zustand를 사용하게 되면, 개발자가 너무 쉽게 접근할 수 있을 것 같다는 생각을 했다.

예를 들어, 다른 개발자가 실수로 에러와 관련 없는 곳에서 해당 store에 접근해서 callback을 변경하거나 초기화할 수 있다는 우려가 있었다.

또한 에러 처리라는 특정 도메인에 대한 로직을 전역 상태에 노출시키는 것이 과연 좋은 설계인지에 대한 의문도 들었다.

에러 핸들링은 애플리케이션 전반에서 사용되지만, 그렇다고 해서 모든 컴포넌트에서 자유롭게 접근할 수 있어야 하는 것은 아니라고 생각했다.

그래서 좀 더 엄격하고 체계적으로 에러를 관리할 수 있는 방법이 없을까 고민하게 되었다.

뭔가 에러 처리만을 위한 독립적인 시스템을 만들고 싶었고, 이것이 패키지를 만들어보자는 아이디어로 이어졌다.

3. Error Handler 구현하기

본 프로젝트에서는 React Query 를 사용해서 서버 상태를 관리하고 있다.

React Query 를 세팅하는 방식을 살펴보면 children 을 매개변수로 전달받는데, 루트를 전달받도록 세팅한다.

또한, 세팅하기 이전에 queryClient 를 생성해서 매개변수로 전달한다.

필자는 이처럼 React Query를 세팅하는 방식에서 아이디어를 얻어 React Query 세팅하는 방식과 유사하게, Context API 를 사용해서 패키지를 구성하기로 결정했다.

💡 에러핸들러 구성하기

에러 핸들러에서 사용하는 타입 정의를 살펴보면 다음과 같다.

Sample Code - Type 정의

export interface Configure<T extends Record<string, ConfigDetail>> {
  errorCode: T;
  router: any;
}
>
export type ConfigDetail = {
  key: string;
  mainMsg: string;
  subMsg?: string[];
  icon?: string;
  router: string;
};
>
type Props<T extends Record<string, ConfigDetail>> = {
  children: ReactNode;
  config: Configure<T>;
};

ReactQueryProvider를 세팅할때처럼 최초 Config를 정의하고 받는 부분이 Configure 이다.

Configure에는 ConfigDetail이라는 타입이 정의되어있어야만 하고, 이를 처음으로 받아들인다.

Sample Code - Provider 구현

export const ErrorHandlerProvider = <T extends Record<string, ConfigDetail>>({
  children,
  config,
}: Props<T>) => {
  const [pendingCallback, setPendingCallback] = useState<Function | null>(null);
  const [btnLabel, setBtnLabel] = useState<string>("");
  const [errorConfig, setErrorConfig] = useState<ConfigDetail | null>(null);
>
  const handleError = (
    errorKey: string,
    callback?: Function,
    btnLabel?: string
  ) => {
    const errorConfig = config.errorCode[errorKey];
    if (!errorConfig) {
      throw new Error(`Error Key '${errorKey}'를 찾지 못했습니다.`);
    }
>
    setErrorConfig(errorConfig);
>
    if (callback) {
      setPendingCallback(() => callback);
    }
>
    if (btnLabel) {
      setBtnLabel(btnLabel);
    }
>
    config.router.push(errorConfig.router);
  };
>
  const executeCallback = () => {
    if (pendingCallback) {
      pendingCallback();
      setPendingCallback(null);
    }
  };
>
  const getMainMsg = () => {
    return errorConfig?.mainMsg ?? "";
  };
>
  const getSubMsg = () => {
    return errorConfig?.subMsg ?? [];
  };
>
  return (
    <ErrorHandlerContext.Provider
      value={{ handleError, executeCallback, btnLabel, getMainMsg, getSubMsg }}
    >
      {children}
    </ErrorHandlerContext.Provider>
  );
};

다음으로 구현된 내용을보면, 최초 세팅에서 받아온 데이터에서 다양한 유틸을 제공한다.

handlerError 는 에러를 발생시키는 지점에서, 그리고 executeCallback , btnLabel , getMainMsg , getSubMsg 등은 모두 Error Page에서 사용하려고 한다.

Sample Code - Router 구현

export const useErrorHandler = () => {
  const context = useContext(ErrorHandlerContext);
  if (!context) {
    throw new Error("useErrorHandler는 ErrorHandlerProvider안에서 사용하세요!");
  }
  return context;
};

이를 컨텍스트로 담아서 훅으로 사용할 수 있도록 제공한다.

Sample Code - Export

export { ErrorHandlerProvider } from "./ErrorHandlerProvider";
export { useErrorHandler } from "./useErrorHandler";
export type { Configure, ConfigDetail, ErrorHandlerContextType } from "./ErrorHandlerProvider";

다음으로 이를 export해준다.

사용하는 곳에서 여기서 정의한 타입을 사용할 수 있도록 타입도 같이 Export 해주도록 하자

4. Github Packages 사용하기

다음으로 개발한 패키지를 번들링하기 위해서 Rollup 을 사용해보기로 했다.

라이브러리나 패키지를 만들 때 특히 유용한데, Tree-shaking 이 기본으로 지원되어 불필요한 코드를 제거해주고, 번들 크기를 최소화할 수 있다는 장점이 있다.

이 부분은 다른분들이 진행했던 세팅을 열심히 참고해서 만들었다 😅

import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import typescript from '@rollup/plugin-typescript';
import peerDepsExternal from 'rollup-plugin-peer-deps-external';

export default {
  input: 'src/index.ts',
  output: [
    {
      file: 'dist/index.js',
      format: 'cjs',
      sourcemap: true,
    },
    {
      file: 'dist/index.esm.js',
      format: 'esm',
      sourcemap: true,
    },
  ],
  plugins: [
    peerDepsExternal(),
    resolve(),
    commonjs(),
    typescript({
      tsconfig: './tsconfig.json',
    }),
  ],
  external: ['react', 'react-dom'],
};

💡 Package.json 설정

패키지 배포를 위해서는 package.json도 적절히 설정해야 한다.

{
  "name": "@패키지명",
  "version": "1.0.0",
  "description": "Next.js App Router 환경에서 에러를 관리하는 패키지",
  "main": "dist/index.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "rollup -c",
    "prepublishOnly": "npm run build"
  },
  "peerDependencies": {
    "react": ">=18.0.0",
    "react-dom": ">=18.0.0"
  },
  "devDependencies": {
    "@rollup/plugin-commonjs": "^25.0.0",
    "@rollup/plugin-node-resolve": "^15.0.0",
    "@rollup/plugin-typescript": "^11.0.0",
    "rollup": "^4.0.0",
    "rollup-plugin-peer-deps-external": "^2.2.4",
    "typescript": "^5.0.0"
  }
}

특히 main, module, types 필드를 통해 각각 CommonJS, ES Module, TypeScript 타입 정의 파일의 진입점을 명시해주는 것이 중요하다.

💡 에러 핸들러를 사용하기

그래서 사용해보면 다음과 같다

Sample Code - 설정

import { ErrorHandlerProvider } from "@배포한 패키지";
>
export default function CustomErrorHandlerProvider({ children }: Props) {
  const router = useRouter();
>
  const config = useMemo(() => {
    return {
      router,
      errorCode: ERROR_HANDLER_CONFIG,
    };
  }, [router]);
>
  return (
    <ErrorHandlerProvider config={config}>{children}</ErrorHandlerProvider>
  );
}

이처럼 config를 설정한 이후 넘겨준다.

Sample Code - 에러 페이지

import { useErrorHandler } from "@배포한 패키지";
>
function ErrorContent() {
  const { getMainMsg, getSubMsg, btnLabel, executeCallback } =
    useErrorHandler();
>
  const mainMsg = getMainMsg();
  const subMsg = getSubMsg();
>
  return (
    <div className="flex flex-col justify-center items-center h-screen">
      <Image src={failed} width={180} alt="실패 아이콘" />
      <p className="font-large-title-b mt-1 mb-6">{mainMsg}</p>
      {subMsg.length > 0 &&
        subMsg.map((msg, index) => (
          <p key={index} className="font-title1-r">
            {msg}
          </p>
        ))}
      <div className="flex flex-col gap-[12px] mt-16">
        <GlobalBtn
          title={`${btnLabel}`}
          onClick={executeCallback}
          className="py-4 px-[115.5px]"
        />
      </div>
    </div>
  );
}

다음으로 패키지에서 정의했던 useErrorHandler 를 불러와서 에러페이지에서 사용하도록 수정해봤다.

실제로 에러를 발생시키는 지점에서는 다음과 같이 사용할 수 있다

Sample Code - 에러 발생

const { handleError } = useErrorHandler();
>
const handleLoginError = () => {
  handleError(
    'LOGIN_FAILED',
    () => router.push('/login'),
    'Retry'
  );
};

이렇게 구성하니 에러 코드와 콜백 함수, 버튼 라벨을 깔끔하게 전달할 수 있게 되었다.

OUTRO

이번 프로젝트를 통해 Next.js App Router 환경에서 에러를 관리하기 위한 패키지를 만들어봤다.

처음에는 단순히 콜백 함수를 페이지 간에 전달하는 문제에서 시작했지만, 결국 에러 핸들링 전용 패키지를 만들게 되었다 😅

Context API를 활용해서 에러 관련 상태를 캡슐화하고, 전역 상태 관리툴을 사용하지 않고도 에러 핸들링만을 위한 독립적인 시스템을 구축할 수 있다는 점이 개인적으로는 만족스러웠다.

Rollup을 사용한 번들링과 Github Packages를 통한 배포 과정도 새로운 경험이었고, 어쩌면 다른 프로젝트에서도 재사용할 수 있는 유용한 도구를 만든 것 같기도 하다.

현업에서는 모노레포 방식을 자주 사용한다고 하는데, 아무래도 하나의 팀에서 여러개의 어플리케이션을 만드는게 아니다보니까 접할기회가 없는게 조금 아쉽다.

스스로는 에러 핸들링 툴을 만들었다고 하지만, 물론 아직 개선할 점들이 많이 있다. (타입정의도 매끄럽게 되지 않았다)

더 나은 설계를 고민해봤다는데에 의의를 두자!

프로젝트에서 사용자 어플리케이션을 개발하고 실제로 사용해보니 약간의 UX 문제를 발견했다.

바텀시트에서 월을 변경할 때마다 로딩 인디케이터가 나타나서 사용자 경험이 매끄럽지 않았던 것이다.

이번 포스팅을 통해, 어떤 문제였고 어떻게 해결했는지 아주 간단하게 소개해보려고 한다!

1. Problem

문제 상황은 다음과 같다.

💡 문제 원인

바텀시트를 열고 월을 변경할 때마다 새로운 데이터를 불러오기 때문에 잠깐동안 로딩 인디케이터가 돌아가는 문제였다.

React Query를 사용하고 기본 캐싱 시간을 5분으로 설정해놨기 때문에 다음과 같이 동작하고 있었다.

동작 순서

1. 예약 페이지 접근
2. 현재 월 데이터 패치 (6월)
3. 바텀 시트 열기 (6월 데이터 저장되어있음)
4. 7월로 변경
5. 7월 데이터 API 요청
6. 인디케이터 발생
7. 7월 데이터 캐싱
8. 데이터가 변경되어 다시 Default 세팅인 6월로 이동
9. 8월로 이동 -> 1~8 과정 반복

매번 새로운 월로 이동할 때마다 로딩이 발생하니 UX가 정말 좋지 않았다..

2. Solve

찾아보니 React Query에서는 Prefetch 기능을 아주 간단하게 제공하고 있었다.

현재 월 데이터를 가져올 때 미리 전후 월 데이터도 함께 가져와서 캐시에 저장해두면, 사용자가 월을 변경해도 로딩 없이 바로 데이터를 보여줄 수 있다.

Sample Code

export const useGetReservationInfoApi = ({ popupId, yyyyMM }: GetReservationInfoRequest) => {
  const queryClient = useQueryClient();
>
  const query = useQuery({
    queryKey: ['reservationInfo', popupId, yyyyMM],
    queryFn: () => getReservationInfo({ popupId, yyyyMM }),
    staleTime: 5 * 60 * 1000,
    gcTime: 10 * 60 * 1000,
    refetchOnWindowFocus: false,
    refetchOnMount: false,
  });
>
  useEffect(() => {
    if (query.data && !query.isLoading) {
      const currentDate = new Date(yyyyMM + '-01');
>
      const nextMonth = new Date(currentDate);
      nextMonth.setMonth(nextMonth.getMonth() + 1);
      const nextYearMonth = `${nextMonth.getFullYear()}-${String(nextMonth.getMonth() + 1).padStart(2, '0')}`;
>
      const prevMonth = new Date(currentDate);
      prevMonth.setMonth(prevMonth.getMonth() - 1);
      const prevYearMonth = `${prevMonth.getFullYear()}-${String(prevMonth.getMonth() + 1).padStart(2, '0')}`;
>
      queryClient.prefetchQuery({
        queryKey: ['reservationInfo', popupId, nextYearMonth],
        queryFn: () => getReservationInfo({ popupId, yyyyMM: nextYearMonth }),
        staleTime: 5 * 60 * 1000,
      });
>
      queryClient.prefetchQuery({
        queryKey: ['reservationInfo', popupId, prevYearMonth],
        queryFn: () => getReservationInfo({ popupId, yyyyMM: prevYearMonth }),
        staleTime: 5 * 60 * 1000,
      });
    }
  }, [query.data, query.isLoading, popupId, yyyyMM, queryClient]);
>
  return {
    reservationInfo: query.data?.data,
    isLoading: query.isLoading,
    isError: query.isError,
  };
};

기존에는 useQuery만 있었지만, useEffect를 추가해서 데이터가 로드되면 prefetchQuery로 전후 월 데이터를 미리 가져오도록 수정했다.

사용자가 이전 달로 갈 수도 있고 다음 달로 갈 수도 있기 때문에, 현재 월 기준으로 ±1개월 데이터를 모두 prefetch하도록 했다.

결과는 다음과 같이 로딩 없이 매끄럽게 동작하는 모습을 확인할 수 있었다.

OUTRO

간단한 UX 개선이었지만 사용자 입장에서는 체감되는 차이가 꽤 컸다.

사용자가 다음에 할 행동을 예측해서 미리 데이터를 준비해두면, 마치 데이터가 이미 있었던 것처럼 즉시 보여줄 수 있다.

물론 불필요한 API 호출이 늘어날 수 있으니 적절히 사용하는 것이 중요하겠지만, 이번 경우처럼 사용자가 높은 확률로 접근할 데이터라면 충분히 활용할 만한 기능이라고 생각한다!

개발을 진행하면서 코드가 꽤 읽기 어려운 경우를 모두 경험해봤을 것이다.

필자의 경우에도 본 프로젝트에서 그런 경험을 가끔 느꼈는데, 그런 경우 대부분 조건문이 하나의 컴포넌트 내에서 많이 적용된 경우라는 것을 알게 되었다.

하나씩 따라가다 보면 물론 이해는 되지만, 어떻게 하면 조금 더 깔끔하게 코드를 작성할 수 있을지 고민했던 경험과 그 결과물을 한번 짤막하게 공유해보려고 한다 👀

1. 언제 코드가 읽기 힘든가?

이전에 말했던 것처럼 필자의 경우에는 조건문 분기가 하나의 컴포넌트 내부에서 많아지는 경우라고 생각한다.

다음 코드를 살펴보자

Sample Code - 1

export default function DashBoardConversionRate() {
  const { data } = useConversionApi();
  const isLowDataExist = data && data.low.length > 0;
  const isHighDataExist = data && data.high.length > 0;
>
  return (
    <div className="flex flex-col" data-testid="dashboard-conversionRate">
      <DashBoardTitle title="구매전환율" />
      <div className="flex justify-between">
        <div className="relative w-[660px] h-[510px] bg-gray02 rounded-[50px] px-6 flex justify-center">
          <div className="mt-7 flex text-gray09 font-medium text-[28px]">
            하위 상품 TOP 6
          </div>
          <div
            className={`absolute bottom-6 w-[612px] h-[394px] ${isLowDataExist ? "bg-gray01" : ""} rounded-[40px] flex justify-center`}
          >
            {isLowDataExist ? (
              <ConversionRateChart
                data={data.low}
                barColor="#FFDCEA"
                lineColor="#9F9FF8"
                tooltipColorClass={{
                  interested: "text-purple07",
                  purchased: "text-main03",
                  rate: "text-blue07",
                }}
                legendColors={{
                  interested: "#9F9FF8",
                  purchased: "#FFB4D1",
                }}
              />
            ) : (
              <div className="absolute bottom-6 w-[612px] h-[394px]">
                <NoDataCompt />
              </div>
            )}
          </div>
        </div>
        <div className="relative w-[660px] h-[510px] bg-gray02 rounded-[50px] px-6 flex justify-center">
          <div className="mt-7 flex text-gray09 font-medium text-[28px]">
            상위 상품 TOP 6
          </div>
          <div
            className={`absolute bottom-6 w-[612px] h-[394px] ${isHighDataExist ? "bg-gray01" : ""} rounded-[40px] flex justify-center`}
          >
            {isHighDataExist ? (
              <ConversionRateChart
                data={data.high}
                barColor="#C5EFE8"
                lineColor="#78B0FF"
                tooltipColorClass={{
                  interested: "text-blue07",
                  purchased: "text-mint07",
                  rate: "text-main04",
                }}
                legendColors={{
                  interested: "#78B0FF",
                  purchased: "#C5EFE8",
                }}
              />
            ) : (
              <div className="absolute bottom-6 w-[612px] h-[394px]">
                <NoDataCompt />
              </div>
            )}
          </div>
        </div>
      </div>
    </div>
  );
}

위 코드는 우리가 개발했던 대시보드 컴포넌트 중 하나인데, isLowDataExist , isHighDataExist 와 같은 조건을 확인하여 조건부 렌더링을 진행하고 있다.

물론 기능적으로는 문제없지만, 동일한 구조가 두 번 반복되고 있고 조건부 렌더링 로직이 JSX에 직접 포함되어 있어서 코드가 깔끔하지 않다는 느낌이 든다.

다른 예시를 살펴보면 다음과 같다.

Sample Code - 2

export default function EntireItemsScreen() {
  const { hotItems } = useLocalSearchParams<{ hotItems: string }>();
  const { selectedPopUpId } = usePopUpStore();
  const formattedPopularItems = ParseStringToJson(hotItems) as ItemUrlType[];
  const { searchResult, isLoading, hasMore, loadMore } = useSearch();
  const { keyword } = useSearchStore();
  const { allItems, isItemLoading, isItemError, allItemsQuery } = usePopUpDetailAllItemsApi({
    popupId: selectedPopUpId,
  });
>
  const isSearchMode = keyword.trim().length > 0;
>
  const renderSearchBar = useCallback(
    () => <SearchBarTextInput flag="ITEM" placeholder="찾으시는 굿즈가 있나요?" />,
    [],
  );
>
  const handleLoadMore = useCallback(() => {
    if (hasMore && !isLoading) {
      loadMore();
    }
  }, [hasMore, isLoading, loadMore]);
>
  const renderFooter = useCallback(() => {
    if (!isLoading || !hasMore) return null;
    return (
      <View style={{ padding: 20, alignItems: 'center' }}>
        <ActivityIndicator size="small" color="white" />
      </View>
    );
  }, [isLoading, hasMore]);
>
  const renderEmptyComponent = useCallback(() => {
    if (isLoading) {
      return (
        <View style={{ padding: 50, alignItems: 'center' }}>
          <ActivityIndicator size="large" color="white" />
        </View>
      );
    }
    return <NoItem title="검색 결과와 일치하는 상품이 없어요" />;
  }, [isLoading]);
>
  // ... 다른 useCallback 함수들
>
  const renderSearchContent = useCallback(
    () => (
      <FlatList
        data={searchResult as PostItemSearch[]}
        renderItem={renderSearchItem}
        numColumns={2}
        columnWrapperStyle={{ justifyContent: 'space-between', gap: 12 }}
        contentContainerStyle={{ paddingBottom: 100, paddingHorizontal: 12 }}
        showsVerticalScrollIndicator={false}
        onEndReached={handleLoadMore}
        onEndReachedThreshold={0.3}
        ListFooterComponent={renderFooter}
        ListEmptyComponent={renderEmptyComponent}
        keyExtractor={keyExtractor}
        ItemSeparatorComponent={itemSeperatorComponent}
        ListHeaderComponent={renderSearchHeader}
      />
    ),
    [/* 의존성 배열 */],
  );
>
  const renderDefaultContent = useCallback(
    () => (
      <FlatList
        data={allItems}
        style={{ flex: 1 }}
        renderItem={renderDefaultItem}
        numColumns={2}
        columnWrapperStyle={{ justifyContent: 'space-between', gap: 10 }}
        contentContainerStyle={{ gap: 20, paddingHorizontal: 12, paddingBottom: 100 }}
        showsVerticalScrollIndicator={false}
        keyExtractor={defaultKeyExtractor}
        ListHeaderComponent={renderDefaultHeader}
        onEndReached={handleDefaultLoadMore}
        onEndReachedThreshold={0.3}
        ListFooterComponent={renderDefaultFooter}
      />
    ),
    [/* 의존성 배열 */],
  );
>
  if (isItemLoading) {
    return <ActivityIndicator />;
  }
>
  if (isItemError || allItems?.length === 0) {
    return <Text>조회된 데이터가 없습니다.</Text>;
  }
>
  return (
    <View style={{ backgroundColor: 'black', flex: 1 }}>
      <View style={{ height: 50, marginBottom: 12 }}>{renderSearchBar()}</View>
      <View style={{ flex: 1 }}>
        {isSearchMode ? renderSearchContent() : renderDefaultContent()}
      </View>
    </View>
  );
}

두 번째 샘플 코드는 React Native 환경에서 작성된 내용으로, 컴포넌트의 모든 요소들을 useCallback으로 감싸 함수 재생성을 방지하기 위해 위처럼 작성되어 있다.

또한, 하나의 페이지에서 상품 리스트와 상품 검색 요소들을 모두 보여줘야 하다 보니, isSearchMode 라는 조건에 따라 renderSearchContent() 와 renderDefaultContent() 를 조건부 렌더링하고 있다.

(두 번째 코드는 당연히 컴포넌트 분리가 필요해 보인다.. 😅)

뿐만 아니라, 두 번째 샘플 코드에서는 React Query를 사용하여 로딩 상태 UI 등을 처리하고 있는데 이러한 부분에서도 조건부 렌더링이 계속해서 사용되는 모습을 볼 수 있다.

결국 이런 상황들이 반복되다 보니 코드를 읽기가 점점 어려워지고, 새로운 기능을 추가하거나 수정할 때도 실수할 가능성이 높아진다고 생각했다.

2. Conditional Component

그래서 ConditionalComponent 를 하나 만들어봤다.

이걸 만들게 된 계기는 React Native에서 제공하는 Flatlist 컴포넌트를 사용해보니 무한스크롤 관련 기능, 컴포넌트를 분리해서 추가하는 방법이 꽤 맘에 들었기 때문이다.

그래서 구현한 코드는 다음과 같다.

Sample Code

/**
 * @Description
 * 조건부 렌더링을 위한 컴포넌트입니다.
 * - `when` 값이 falsy하거나 빈 배열이면 `fallback`을 렌더링합니다.
 * - `children`이 함수일 경우, `when` 값을 인자로 호출해 렌더링합니다.
 * - 그 외에는 `children` 자체를 그대로 렌더링합니다.
 *
 * @Example
 * <ConditionalComponent when={data} fallback={<div>데이터 없음</div>}>
 *   {(validData) => <div>{validData.name}</div>}
 * </ConditionalComponent>
 */
>
import React from "react";
>
function ConditionalComponent<T>({
  when,
  fallback,
  children,
}: {
  when: T | undefined | null | false | boolean;
  fallback?: React.ReactNode;
  children: React.ReactNode | ((_data: T) => React.ReactNode);
}) {
  if (
    !when ||
    (Array.isArray(when) && when.length === 0) ||
    Object.keys(when).length === 0
  )
    return <>{fallback}</>;
>
  if (typeof children === "function" && typeof when !== "boolean") {
    return <>{children(when)}</>;
  }
>
  return <>{children}</>;
}
>
export default ConditionalComponent;

공통 컴포넌트를 만들때, 가장 중요한건 유연한 타입 추론 이라고 생각한다.

따라서, 제네릭을 사용하여 타입 추론이 제대로 될 수 있게끔 만들어보는데에 집중해봤다.

로직은 아주 간단한데, when 이라는 조건이 truthy이면 children 을 렌더링하고 when 이라는 조건이 falsy이면 fallback 컴포넌트를 렌더링한다.

한가지 도전적으로 만든 내용을 보면 children 이 ReactNode 뿐만 아니라 함수도 받을 수 있다는 것이다.

함수로 받는 경우, data라는 매개변수의 데이터 타입이 T로 추론되는 모습을 볼 수 있다.

이렇게 개발을 진행한 이유는, when이라는 조건에서 추론된 데이터를 children으로 사용하는 경우가 있기 때문이다.

다음 코드를 통해 사용 예시를 살펴보자

Sample Code - Example

const ItemListPage = () => {
  const popupId = usePopUpReadStore(state => state.popupId);
  const { data } = useItemListApi({ popupId });
  const navigate = useNavigate();
  const [isModalOpen, setIsModalOpen] = useState<boolean>(false);
>
  return (
    <div className="py-8 flex flex-col min-h-[calc(100vh-200px)]">
      <div className="flex justify-end gap-3 mb-10 px-10">
        <button
          className="cursor-pointer px-4 py-2 bg-gray01 border border-gray10 text-gray10 rounded-full text-[20px] font-semibold hover:bg-gray10 hover:text-gray01 transition-colors duration-300"
          onClick={() => setIsModalOpen(true)}
        >
          전체 상품 등록
        </button>
        <button
          id="item-create-button"
          onClick={() => navigate("/items/create")}
          className="cursor-pointer px-4 py-2 bg-gray01 border border-gray10 text-gray10 rounded-full text-[20px] font-semibold hover:bg-gray10 hover:text-gray01 transition-colors duration-300"
        >
          상품 등록
        </button>
      </div>
>
      {isModalOpen && (
        <ItemCreateExcelModal closeModal={() => setIsModalOpen(false)} />
      )}
>
      <ConditionalComponent
        when={data}
        fallback={
          <div className="flex flex-col items-center justify-center flex-grow">
            <p className="text-[32px] text-gray10 font-medium">
              등록된 상품이 아직 없습니다
            </p>
            <p className="mt-4 text-[20px] text-gray10">
              우측 상단 <span className="text-main06">상품 등록 버튼</span>을
              눌러 상품을 등록해주세요!
            </p>
          </div>
        }
      >
        {data =>
          Object.entries(data).map(([k, v]) => (
            <div key={k}>
              <ItemDisplay displayName={k.toUpperCase()} items={v} />
            </div>
          ))
        }
      </ConditionalComponent>
    </div>
  );
};
>
export default ItemListPage;

when 타입 추론

data 타입 추론

코드를 보면 등록된 상품이 이미 있는 경우, Object.entries(data).map((k, v]) => ...) 를 사용해서 ItemDisplay 컴포넌트들을 렌더링한다.

이처럼 when에서 조건으로 사용된 data 를 사용하여 하위 컴포넌트들을 렌더링하기 때문에 함수형으로도 받을 수 있도록 개발을 진행했다.

또한, 사진을 살펴보면 when에서는 data의 타입 추론이 GetItemListResponse | undefined 로 추론되지만, children쪽에서 data는 GetItemListResponse 로 추론된다.

그 이유는 ConditionalComponent 내부적으로 falsy한 경우에는 fallback을 렌더링하도록 했기 때문이다.

💡 이렇게 사용하면 뭐가 좋을까?

아마 코드를 살펴보면, 누군가는 조건부 렌더링을 사용하는게 더 깔끔하지 않나? 라는 생각을 할 수 있다.

하지만, 이런식으로 fallback 영역과 children 영역을 분리해서 코드를 작성해보면 어느 부분에서 컴포넌트를 분리해야할지 쉽게 눈으로 확인할 수 있다.

이런 방식으로 구조를 생각하면서 UI 레이어에서 작성되는 컴포넌트들을 나눈다면 분명 유지보수에서 이점을 얻을 수 있을거라고 생각한다

3. Query Component

필자는 본 프로젝트에서 모든 API 요청을 React Query를 사용해서 관리했다.

React Query에서 제공해주는 기능이 매력적이라고 생각했기 때문이다.

React Query를 사용해보면 알겠지만, 리액트 쿼리는 조건부 렌더링에 최적화되어있다.

가령 데이터 패치를 받을 때, isLoading, isError 의 boolean 값을 통해 조건부 렌더링을 쉽게 진행할 수 있기 때문이다.

필자는 위에서 작성한 Conditional Component 아이디어를 바탕으로 리액트 쿼리 전용 컴포넌트를 만들어보면 어떨까 생각하여 관련 컴포넌트 개발을 진행해봤다.

Sample Code

/**
 * @description
 * React Query 요청의 로딩, 에러, 빈 데이터 상태를 공통 처리하는 래퍼 컴포넌트입니다.
 * - `data`, `isLoading`, `isError` 상태에 따라 적절한 fallback UI를 렌더링하고,
 * - 데이터가 존재할 경우 `children` 함수로 실제 UI를 렌더링합니다.
 *
 * @example
 * <QueryComponent
 *   data={data}
 *   isLoading={isLoading}
 *   isError={isError}
 * >
 *   {(data) => <MyList data={data} />}
 * </QueryComponent>
 */
>
import React from "react";
import Skeleton from "../ui/Skeleton";
import NoDataComp from "../../pages/dashboardPage/views/@common/NoDataComp";
>
type Props<T> = {
  data: T | undefined;
  isLoading: boolean;
  isError: boolean;
  error?: Error | null;
  loadingFallback?: React.ReactNode;
  errorFallback?: React.ReactNode | ((_error: Error) => React.ReactNode);
  emptyFallback?: React.ReactNode;
  children: (_data: T) => React.ReactNode;
};
>
const QueryComponent = <T,>({
  data,
  isLoading,
  isError,
  loadingFallback = (
    <div className="h-[300px]">
      <Skeleton />
    </div>
  ),
  errorFallback,
  emptyFallback = <NoDataComp />,
  children,
}: Props<T>) => {
  if (isLoading) return <>{loadingFallback}</>;
  if (isError) return <>{errorFallback}</>;
  if (
    data === null ||
    data === undefined ||
    (Array.isArray(data) && data.length === 0)
  ) {
    return emptyFallback ? <>{emptyFallback}</> : null;
  }
  return <>{children(data)}</>;
};
>
export default QueryComponent;

기본 구조는 위에서 작성한 Conditional Component 와 동일하다

다만, isLoading과 isError에 대한 조건을 받고 그에 해당하는 컴포넌트를 추가로 입력받는다.

사용 예시는 다음과 같다.

Sample Code

type Props = {
  title: string;
  data: GetConversionItemResponse[] | undefined;
  isLoading: boolean;
  isError: boolean;
  barColor: string;
  lineColor: string;
  tooltipColorClass: {
    interested: string;
    purchased: string;
    rate: string;
  };
  legendColors: {
    interested: string;
    purchased: string;
  };
};
>
const ConversionRateCard = ({
  title,
  data,
  isLoading,
  isError,
  barColor,
  lineColor,
  tooltipColorClass,
  legendColors,
}: Props) => {
  return (
    <div className="relative w-[660px] h-[510px] bg-gray02 rounded-[50px] px-6 flex justify-center">
      <div className="mt-7 flex text-gray09 font-medium text-[28px]">
        {title}
      </div>
>
      <QueryComponent
        data={data}
        isLoading={isLoading}
        isError={isError}
        loadingFallback={
          <Skeleton
            className="absolute bottom-6"
            width="w-[612px]"
            height="h-[394px]"
          />
        }
        errorFallback={
          <NoDataComp
            className="absolute bottom-6"
            width="w-[612px]"
            height="h-[394px]"
          />
        }
      >
        {data => (
          <div className="absolute bottom-6 w-[612px] h-[394px] bg-gray01 rounded-[40px] flex justify-center">
            <ConversionRateChart
              data={data}
              barColor={barColor}
              lineColor={lineColor}
              tooltipColorClass={tooltipColorClass}
              legendColors={legendColors}
            />
          </div>
        )}
      </QueryComponent>
    </div>
  );
};
>
export default ConversionRateCard;

Conditional Component와 마찬가지로 포맷이 정해진 상태로 컴포넌트를 구조화시킬 수 있었다.

💡 QueryComponent와 Conditional Component 분리 이유

아마 누군가는 이전에 개발한 Conditional Component에 loading과 error에 대한 Props를 Optional로 추가하면 되는거 아닌가? 라고 질문할 수 있다.

물론, 그렇게 진행하게되면 모든 컴포넌트에서 Conditional Component만 사용하여 구조화시킬 수 있다.

하지만, 프론트 개발자라면 공통 컴포넌트를 한번쯤은 만들어봤을 것이다.

필자의 경우 공통으로 사용되는 Modal 컴포넌트를 사용하고 있었는데, 개발을 진행하면서 여러개의 옵션이 붙어야하는 경우를 경험해봤다.

결국 공통으로 사용되는 Modal 컴포넌트를 수정해야하는 상황이 발생했고, 그로인해 생각치도 못한 UI가 깨지는 상황을 겪어본적이 있다.

이러한 경험을 해보고 우연히 관련 Velog를 읽어보고 도메인별로 분리하는게 꽤 괜찮은 방법이라고 생각하게 되어 이처럼 나누게 되었다.

OUTRO

이번 글에서는 조건부 렌더링으로 인해 복잡해진 코드를 어떻게 개선할 수 있을지에 대한 고민과 해결 과정을 공유해봤다.

ConditionalComponent 와 QueryComponent 를 만들면서 느낀 점은, 단순히 코드의 길이를 줄이는 것보다는 일관된 구조를 만드는 것이 더 중요하다는 것이었다.

물론 이런 방식이 모든 상황에서 최선의 해답은 아닐 수 있다.

하지만 적어도 팀원들과 함께 개발할 때 "조건부 렌더링은 이런 식으로 처리하자"라는 공통된 규칙을 만들 수 있었던 것 같다.

앞으로도 이런 작은 개선들을 통해 조금 더 읽기 쉽고 유지보수하기 좋은 코드를 작성해보려고 한다!

프로젝트가 커지면서 React Query 쿼리키 관리가 점점 복잡해졌다.

여러 파일에 흩어진 쿼리키들을 찾아다니며 캐시를 무효화하는 작업이 어느순간부터 번거롭다고 느껴졌고, 이를 해결하기 위해 Query Key 모듈화 를 도입하게 되었다.

이번 포스팅에서는 실제 프로젝트에서 Query Key 모듈화를 어떻게 적용했는지, 그리고 어떤 개선 효과를 얻었는지 공유해보려고 한다!

1. 기존에는 어떻게 사용했는가?

우선 디렉토리 구조를 소개해보면 다음과 같다.

디렉토리 구조

우리팀은 React Query의 훅을 사용하여 API 요청을 처리하는 부분을 src/hooks/api 디렉토리에서 모두 관리하고 있다.

하나의 React Query 코드를 살펴보면 다음과 같다.

Sample Code

// useOrderListApi.ts
export const useGetOrderListApi = ({ size }: { size: number }) => {
  return useInfiniteQuery({
    queryKey: ["orderItem"],
    queryFn: ({ pageParam }) =>
      getOrderList({ lastOrderItemId: pageParam, size }),
    getNextPageParam: response => {
      const lastPage = response.data;
>
      if (lastPage.isLast) {
        return undefined;
      }
>
      const lastItem = lastPage.content[lastPage.content.length - 1];
      return lastItem.orderItemId;
    },
    initialPageParam: undefined as number | undefined,
  });
};
>
export const usePostChangeOrderItemStatus = () => {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: ({ orderItemId, qty, status }: PostChangeOrderItemRequest) =>
      postChangeOrderItemStatus({ orderItemId, qty, status }),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["orderItem"] }),
  });
};

우리는 도메인 혹은 기능 별로 파일을 분리하여 쿼리 훅들을 관리하고 있었다.

위 코드를 간단히 설명하면, useGetOrderListApi 는 발주 요청들을 무한 스크롤로 가져오는 훅이고, usePostChangeOrderItemStatus 는 발주 요청의 상태를 변경하는 훅이다.

💡 캐시 전략

기본적으로 우리는 Get 요청을 통해 받아온 모든 서버 상태(response)들을 5분동안 Stale한 상태로 관리하는 캐시 전략을 가지고 있었다.

Sample Image

여기서 usePostChangeOrderItemStatus 을 통해 포토카드 RETRO 상품의 상태가 승인 혹은 취소 로 변경된다면, 기존에 가지고 있던 발주 리스트 캐시 데이터를 무효화하고 다시 받아와야 한다.

Sample Code

onSuccess: () => queryClient.invalidateQueries({ queryKey: ["orderItem"] }),

우리는 mutation의 onSuccess 기능을 사용해서 특정 쿼리 데이터를 무시하는 방법을 사용하고 있었다.

💡 문제 인식

그런데 만약 요구사항이 변경되어서, 완전히 다른 기능의 A라는 mutation이 성공할 때마다 발주 리스트 캐시를 무효화해야 하는 상황이 생겼다고 가정해보자.

Sample Code

// useExampleApi.ts
export const useExampleApi = () => {
  const queryClient = useQueryClient();
>
  return useMutation({
    mutationFn: postSample(),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["a", "orderItem"] });
    },
  });
};

이런 상황에서 무효화할 캐시 데이터인 "orderItem"을 찾으려면 useOrderListApi.ts 파일을 일일이 찾아서 들어가야 한다는 문제가 있었다.

이처럼 React Query를 사용해서 쿼리키를 여러개 정의하다보면 여러 파일에 쿼리키가 흩어지기 때문에 유지보수를 하기 어려운 문제가 발생할 수 있다.

2. Query Key 모듈화

쿼리키 모듈화의 핵심은 쿼리키들을 함수로 만들어서 한 곳에서 관리하자는 것이다.

Sample Code

// queryKey.ts
type QueryParams = Record<string, string | number | boolean | undefined>;
>
export const queryKeys = {
  ...
  orderItem: {
    all: ["orderItem"] as const,
    lists: () => ["orderItem", "list"] as const,
    list: (popupId: string, params?: QueryParams) =>
      params
        ? (["orderItem", "list", popupId, params] as const)
        : (["orderItem", "list", popupId] as const),
    detail: (orderItemId: string) =>
      ["orderItem", "detail", orderItemId] as const,
  },
  ...
}
>
export const QUERY_KEYS = {
  ...
  ORDER_ITEM: {
    INDEX: queryKeys.orderItem.lists,
    LIST: (popupId: string, params?: QueryParams) =>
      queryKeys.orderItem.list(popupId, params),
    DETAIL: (orderItemId: string) => queryKeys.orderItem.detail(orderItemId),
  },
  ...
};

디렉토리 구조

queryKeys로 쿼리키의 기본 포맷을 정의하고, QUERY_KEYS로 실제 사용할 인터페이스를 제공하는 구조다.

(지금 생각해보면 기본 포맷 정의된 부분을 바로 인터페이스로 제공해도 상관없을 것 같다)

💡 어떻게 사용했는지?

적용한 코드를 살펴보면 다음과 같다.

Sample Code

export const useGetOrderListApi = ({
  size,
  popupId,
}: {
  size: number;
  popupId: number;
}) => {
  return useInfiniteQuery({
    queryKey: QUERY_KEYS.ORDER_ITEM.LIST(String(popupId), { size }),
    queryFn: ({ pageParam }) =>
      getOrderList({ lastOrderItemId: pageParam, size, popupId }),
    getNextPageParam: response => {
      const lastPage = response.data;
>
      if (lastPage.isLast) {
        return undefined;
      }
>
      const lastItem = lastPage.content[lastPage.content.length - 1];
      return lastItem.orderItemId;
    },
    initialPageParam: undefined as number | undefined,
  });
};
>
export const usePatchChangeOrderItemStatus = () => {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: ({ orderItemId, qty, status }: PatchChangeOrderItemRequest) =>
      patchChangeOrderItemStatus({ orderItemId, qty, status }),
    onSuccess: () =>
      queryClient.invalidateQueries({
        queryKey: QUERY_KEYS.ORDER_ITEM.INDEX(),
      }),
  });
};

이처럼 실제 쿼리키를 사용하는 곳에서는 QUERY_KEYS.ORDER_ITEM.INDEX() 와 같이 함수를 호출하여 쿼리키를 호출하는 방식으로 리팩토링을 진행할 수 있었다.

다시 돌아와서 이전에 가정했던 코드처럼 orderItem 을 캐시 무효화해야했다면, 디렉토리 내에서 여러 파일을 하나씩 찾아보는게 아니라 하나의 파일로 관리된 queryKey.ts 를 살펴보면 된다.

물론, 처음 정의하는 부분에서 쿼리키를 정의해야한다는 오버헤드가 있을 수 있으나 실제로 사용해보면 얻는 유지보수성이 더 높다고 생각한다.

OUTRO

처음에는 쿼리키를 정의하는 오버헤드가 있을 수 있지만, 실제로 사용해보니 얻는 유지보수성이 훨씬 높다고 느꼈다.

특히 중간 규모의 프로젝트에서 유지보수가 더 좋은 것 같다.

결국 엄청난 크기의 프로젝트가 된다면, 한 파일에서 관리한다고하더라도 당연히 복잡해지는건 똑같기 때문이다.

React Query를 사용하는 프로젝트라면 한 번쯤 고려해볼 만한 패턴이라고 생각한다!

참고

[React Query] querykey, mutationKey를 모듈화하여 관리하기

여러 개발 커뮤니티에서 진행되는 세션을 살펴보면 간혹 성능 개선 이라는 주제로 진행되는 세션을 볼 수 있다.

하지만, 그러한 세션들은 성능 개선 이라는 주제로 발표를 진행하기 때문에, 어떻게 성능 측정을 진행했는지는 간단하게 소개하거나 그냥 넘어가는 경우가 많다.

필자는 이번 프로젝트를 진행하면서 고민했던 성능 측정 방법 을 이번 포스팅을 통해 다뤄보고자 한다.

1. 무엇을 고려해야 했는가?

우리팀의 프론트엔드 인원은 총 3명으로 구성되어 있으며, 각자 서로 다른 페이지에 대해서 성능 개선을 진행해보고 결과를 공유하고 싶었다.

따라서 우리는 최소한 두 가지 조건을 만족해야 했다.

환경 일관성

• 프론트엔드 팀원들이 서로 다른 개발환경에서 측정을 진행해도 동일한 결과가 나와야 한다

측정 신뢰성

• 여러 번 실행해도 코드를 변경하지 않았다면 당연히 동일한 결과가 나와야 한다

이 조건을 만족하면서 의미 있는 성능 측정을 하기 위해서는 단순히 개발자 도구의 Network 탭 을 살펴보거나 Lighthouse 를 한 번 실행하는 것으로는 한계가 있다고 생각했다.

(여기서 환경 일관성이나 측정 신뢰성은 편의를 위해 나름대로 정의한 부분이다)

(이후에도 이 단어들을 재사용해서 포스팅을 진행할 예정이다!)

2. 생각해본 성능 측정 방법들

정리하자면, 서로 다른 환경에서 테스트를 진행하더라도 코드가 동일하다면 동일한 결과가 나오는 신뢰성 있는 지표를 원했던 상황이다.

이 요구를 만족하기 위해 여러가지로 찾아봤던 부분을 공유해보려고 한다.

💡 페이지 테스트 사이트 이용

https://www.webpagetest.org/

WebPageTest는 일관된 측정 환경을 제공하는 온라인 서비스이다.

전 세계 여러 지역의 실제 디바이스와 네트워크 환경에서 테스트할 수 있어서, 이전에 소개했던 환경 일관성 측면과 측정 신뢰성 측면 모두에서 제일 괜찮은 방법이라고 생각했다.

하지만 우리 프로젝트에는 치명적인 문제가 있었다.

로그인을 진행한 이후 AccessToken을 헤더에 추가해야 하는 페이지들이 대부분이었는데, 이를 위해서는 해당 사이트에서 별도의 스크립트를 작성해야 했다.

더 큰 문제는 실시간 피드백이 어렵다는 점이었다.

코드를 수정하고 바로바로 성능 변화를 확인하기에는 워크플로우가 너무 복잡했으며, 이전에 말한 스크립트를 작성하기 위해 요구하는 허들이 너무 높다고 판단했다.

💡 EC2 사용

두 번째로 고려했던 방법은 AWS EC2에 전용 성능 측정 환경을 구축하는 것이었다.

CPU 코어와 메모리를 제한하고, Docker에 Chrome을 설치해서 Lighthouse를 실행하는 방식을 고민해봤다.

이 방법의 장점은 완전히 통제 가능한 환경에서 측정할 수 있다는 것이었다.

네트워크 대역폭, CPU 성능, 메모리 등을 일정하게 유지할 수 있어서 가장 일관된 결과를 얻을 수 있을 것 같았다.

하지만 현실적인 문제들이 많았는데, 코드가 바뀔 때마다 CloudFront에 배포를 다시하고 EC2 내부에서는 측정만 진행하거나, 아니면 EC2 내부에 VSCode를 설치하여 EC2에서 개발을 진행할 수 있도록 구축해야 했다.

팀원 3명이 각자 다른 페이지를 담당하는 상황에서, 모든 사람이 EC2 환경에 접근해서 작업하기에는 복잡도가 너무 높다고 판단했다.

💡 GithubAction 사용

마지막으로 검토한 방법이 GitHub Actions를 활용하는 것이었다.

GitHub에서 제공하는 서버 리소스를 사용해서, 매번 동일한 Ubuntu 환경에서 Chrome을 설치하고 Lighthouse CI를 실행하는 방식이다.

이 방법이 가장 괜찮다고 판단한 이유는 다음과 같다.

** 1. 환경 일관성**

• 매번 새로운 Ubuntu 컨테이너에서 실행되기 때문에, 이전 테스트의 캐시나 상태가 영향을 주지 않는다.
• GitHub Actions의 runner 환경은 표준화되어 있어서 실행할 때마다 동일한 조건을 보장한다.

2. 자동화

• PR을 올리거나 특정 브랜치에 푸시할 때 자동으로 성능 테스트가 실행된다.
• 별도로 테스트 사이트에 접속하거나 명령어를 실행할 필요가 없다.

3. 비용

• GitHub의 public 저장소에서는 Actions를 무료로 사용할 수 있다.
• 성능 테스트가 몇 분 정도밖에 걸리지 않아서 사용량 제한에도 걸리지 않는다.

4. 접근성

• 팀원 누구나 PR만 올리면 성능 테스트 결과를 확인할 수 있어서 편하다!
• Lighthouse CI를 추가하는건 상대적으로 별로 어렵지 않은 상황이었다.

따라서, 우리팀은 GitHub Actions를 사용하는 것으로 결정하고 설정을 추가하여 Lighthouse CI를 도입했다!

3. Lighthouse CI 적용기

Lighthouse CI를 적용하기로 결정했지만, 여기서 다시 마주한 문제는 우리의 운영자 페이지에서는 로그인을 진행해야만 메인 페이지로 접근할 수 있다는 것이었다.

Lighthouse CI는 각 URL을 독립적으로 측정하기 때문에, 매번 새로운 브라우저 세션에서 실행된다.

인증이 필요한 페이지의 성능 측정 문제

1. Lighthouse CI 시작
2. 새 브라우저 세션
3. 로그인 페이지 접근
4. 인증 X
5. 메인 페이지 접근 불가

즉, 로그인이 필요한 페이지들을 측정하려면 각 측정마다 인증 과정을 거쳐야 한다는 의미이다.

💡 Puppeteer로 인증 자동화하기

이러한 문제를 해결하기 위해 여러 방법을 찾아본 결과, Puppeteer 를 사용하여 성능 측정 이전에 인증 과정을 자동화하는 방법을 선택했다.

Puppeteer vs Puppeteer-Core 처음에는 Headless 환경에서 puppeteer-core를 사용해야 하는지 고민했다 간단하게 Puppeteer와 Puppeteer-core를 비교하면 다음과 같다.

• puppeteer: Chrome 브라우저 번들 포함 (~300MB)
• puppeteer-core: 브라우저 없이 API만 제공 (~13MB)

하지만 CI 환경에서 Chrome을 별도로 설치하기로 했기 때문에, 필자는 puppeteer를 그대로 사용하기로 결정했다.

관련 내용은 이후에 조금 더 자세히 설명하려고 한다.

💡 어떻게 동작하나요?

우선 운영자 서비스는 로그인을 진행하면 AccessToken 이 발급된다.

필자는 로그인을 진행한 이후, AccessToken과 관련된 인증 정보를 auth-token.json 이라는 이름으로 파일을 저장하도록 auth-setup.js 를 작성했다.

1. 인증 정보 생성

// auth-setup.js
async function setupAuth() {
  try {
    const response = await fetch("https://dev-api.ceo.popi.today/auth/login", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        username: process.env.TEST_EMAIL,
        password: process.env.TEST_PASSWORD,
      }),
    });
>
    if (!response.ok) {
      throw new Error(`로그인 실패: ${response.status} ${response.statusText}`);
    }
>
    const data = await response.json();
    console.log("로그인 응답:", data);
>
    if (!data.success || !data.data || !data.data.accessToken) {
      console.log("전체 응답:", JSON.stringify(data, null, 2));
      throw new Error("로그인 실패 또는 토큰이 없습니다");
    }
>
    const accessToken = data.data.accessToken;
    console.log("=========== JWT 토큰 획득 성공 ===========");
>
    const authData = {
      accessToken,
      timestamp: new Date().toISOString(),
      expiresIn: data.data.expiresIn || 3600,
    };
>
    const authFilePath = path.join(__dirname, "auth-token.json");
    fs.writeFileSync(authFilePath, JSON.stringify(authData, null, 2));
    console.log(`토큰 저장 완료: ${authFilePath}`);
>
    return accessToken;
  } catch (error) {
    console.error("인증 설정 실패:", error.message);
    throw error;
  }
}

코드를 보면 알겠지만 로그인 API 호출 -> 응답에서 AccessToken 추출 -> auth-token.json 파일에 JSON 형태로 저장 순서로 동작한다.

이 부분은 CI 과정에서 하나의 Step으로 동작하여 미리 실행되도록 할 생각이다.

2. Puppeteer 스크립트 실행

module.exports = async (browser, context) => {
  console.log("=========== Puppeteer 스크립트 시작 ===========");
>
  // 토큰 파일에서 accessToken 로드
  const authFilePath = path.join(__dirname, "auth-token.json");
  let accessToken = "";
>
  if (fs.existsSync(authFilePath)) {
    const authData = JSON.parse(fs.readFileSync(authFilePath, "utf8"));
    accessToken = authData.accessToken;
    console.log("토큰 로드 완료");
  } else {
    throw new Error("토큰 파일이 없습니다. auth-setup.js를 먼저 실행하세요");
  }
>
  const page = await browser.newPage();
>
  try {
    // 먼저 onboarding에 가서 인증 상태 설정
    console.log("onboarding 페이지로 이동");
    await page.goto("http://localhost:4173/onboarding", {
      waitUntil: "domcontentloaded",
      timeout: 30000,
    });
>
    // localStorage에 인증 정보 설정
    console.log("localStorage에 인증 정보 설정");
    await page.evaluate(token => {
      const authStore = {
        state: {
          accessToken: token,
          isLogin: true,
        },
        version: 0,
      };
      localStorage.setItem("auth-store", JSON.stringify(authStore));
      console.log(
        "localStorage 설정 완료:",
        localStorage.getItem("auth-store"),
      );
    }, accessToken);
>
    await new Promise(resolve => setTimeout(resolve, 2000));
    await page.waitForSelector("body", { timeout: 10000 });
>
    console.log("=========== Puppeteer 스크립트 완료 ===========");
    return page;
  } catch (error) {
    console.error("Puppeteer 스크립트 실행 중 오류:", error);
    await page.close();
    throw error;
  }
};

다음으로 Puppeteer 스크립트를 실행시킬 예정이다.

이전 auth-setup.js 단계에서 생성된 auth-token.json 을 읽어와서 토큰 정보를 로컬 스토리지에 주입하는 과정이 포함되어있다.

여기서 주의할 점은 우리 서비스가 AccessToken을 auth-store 라는 이름으로 localStorage에서 관리하기 때문에, 동일한 방식으로 토큰을 설정해야 한다는 것이다.

당연히 AccessToken 관리 방식이 달라진다면 그에 맞춰서 코드를 수정해야한다!

Q. Puppeteer를 어디서 사용했나요?

위 코드를 언뜻보면 그냥 Javascript로 코드를 작성한것처럼 보일 수 있다.

필자도 처음에는 Puppeteer를 어떻게 사용해야하는지 많이 찾아봤다.

여기서는 이 두가지를 기억하면 될 것 같다.

1. Lighthouse는 내부적으로 Puppeteer를 지원한다. 2. 위 스크립트는 Lighthouse에게 넘겨줄 내용이다.

즉, puppeteer 관련 코드를 별도로 import를 하지 않아도 Lighthouse가 알아서 제공해줄거기 때문에 별도의 import가 필요없다.

여기서 puppeteer를 사용한 곳은 async (browser, context) 에서 browser이다.

이는 Lighthouse가 puppeteer.launch()로 만든 객체이며, 이후 const page = await browser.newPage(); 처럼 browser를 사용한 부분이 모두 puppeteer의 인스턴스를 사용한 부분이라고 이해하면 된다.

3. Lighthouse Config 생성

...
const lighthouseConfig = {
      ci: {
        collect: {
          url: ["http://localhost:4173/dashboard"],
          puppeteerScript: "./scripts/lighthouse-puppeteer.js",
          puppeteerLaunchOptions: {
            executablePath: chromePath,
            args: chromeFlags,
            headless: true,
          },
          settings: {
            preset: "desktop",
            throttlingMethod: "provided",
            throttling: {
              rttMs: 0,
              throughputKbps: 0,
              cpuSlowdownMultiplier: 1,
              requestLatencyMs: 0,
              downloadThroughputKbps: 0,
              uploadThroughputKbps: 0,
            },
          },
          numberOfRuns: 3,
        },
        assert: {
          assertions: {
            "categories:performance": ["warn", { minScore: 0.8 }],
            "categories:accessibility": ["error", { minScore: 0.8 }],
            "categories:best-practices": ["warn", { minScore: 0.8 }],
            "categories:seo": ["warn", { minScore: 0.8 }],
          },
        },
        upload: {
          target: "temporary-public-storage",
        },
      },
    };
>
    const configPath = path.join(process.cwd(), "lighthouserc.json");
    fs.writeFileSync(configPath, JSON.stringify(lighthouseConfig, null, 2));
...

마지막으로, 이전에 만든 스크립트들을 조합하여 lighthouserc.json 을 만드는 과정이다.

lighthouserc.json 이 실제로 Lighthouse CI를 동작할때 사용하는 설정 파일이며, 우리는 Puppeteer를 통해 인증 과정을 미리 세팅해야했기 때문에 javascript로 설정 파일을 생성하는 코드를 작성한거라고 이해하면 된다.

여기서 주목할 부분은 lighthouserc.json 속성에 puppeteerScript , puppeteerLaunchOptions 과 같이 puppeteer관련 속성이 있다는 것이다.

이를 통해 위에서 작성한 Puppeteer 스크립트가 실행된다.

4. Lighthouse CI

 - name: 인증 설정
    run: node scripts/auth-setup.js
        env:
            TEST_EMAIL: ${{ secrets.TEST_EMAIL }}
            TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
>
- name: Lighthouse 설정 생성
    run: node scripts/generate-lighthouse-config.js
        env:
            CHROME_PATH: /usr/bin/google-chrome-stable
>
- name: Lighthouse CI 실행
    run: lhci autorun
        env:
            LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
            CHROME_PATH: /usr/bin/google-chrome-stable

CI 단계의 일부를 가져와봤는데 이전에 설정한 auth-setup.js 실행 -> lighthouse config 생성 -> lighthouse CI 실행 순서로 동작한다.

4. Lighthouse CI 도입 후기

위와 같은 방법으로 Lighthouse CI를 우리 프로젝트에 도입할 수 있었다.

하지만, 여러가지 문제가 있었는데 이제부터 한번 다뤄보려고 한다.

💡 제대로 측정이 되고 있는가?

위 사진은 이전에 소개한 Lighthouse CI의 결과이다. 여기서 측정된 페이지를 살펴보면 localhost:4173/dashboard 인데, 해당 페이지는 로그인을 진행해야만 들어갈 수 있는 페이지이다.

첨부된 사진을 살펴보면 분명 대시보드 페이지에 대한 성능 측정이 완료된 것으로 보인다.

하지만, 실제 제공된 레포트를 들어가면 다음과 같다.

사진과 같이 /onboarding 페이지로 라우팅이 되어있는 모습을 볼 수 있으며, 캡처된 화면도 onboarding 화면이다.

하지만, 트리맵에 들어가보면 다음과 같이 타겟팅한 dashboard 페이지로 제대로 되어있는 모습을 볼 수 있다.

따라서, 필자가 생각하기에는 세션 정보에 저장된 인증 관련 정보가 성능 측정이 끝나면 사라지기 때문에, onboarding 페이지로 자동 라우팅되어 결과 레포트 주소는 onboarding 으로 보이는게 아닐까하고 추측해본다.

💡 성능 측정 결과가 일관되지 않다

Lighthouse CI를 선택하면서 고려했던 가장 큰 주안점은 환경 일관성 과 측정 신뢰성 이다.

즉, 서로 다른 팀원이 Github Action을 통해 성능 측정을 진행하더라도 동일한 결과가 측정되어야만 의미가 있는 상황이라는 것이다.

하지만, 결과는 다음 사진과 같았다.

보다시피 LCP와 CLS의 차이는 거의 무의미 할정도로 비슷하다. (여기서 Lighthouse CI는 3번의 측정 이후, 중앙값을 레포트로 제공해준다.)

하지만, 이 Performance 점수를 통해 알 수 있는건 Github 서버의 네트워크 상황에 따라서 성능 측정 결과가 달라질 수 있음을 의미한다.

만약, 그렇다면 Github 서버의 네트워크 환경은 우리가 제어할 수 없기 때문에 성능 측정에 대한 일관성을 보장하기 어렵다고 판단했다.

5. 그래서 도입한 방법은?

그래서 우리팀은 로컬 환경에서 연속으로 5번 Lighthouse를 통해 성능을 측정한 이후, 그 결과의 평균값을 사용하기로 결정했다.

실험적으로 진행해보니 이 방법이 가장 측정 신뢰성 이 높다고 판단했다.

💡 한계점

물론 이러한 방식으로 테스트를 진행하면서 얻은 결과를 다른 팀원들과 비교하면서 Performance 점수를 논하기는 어렵다.

왜냐하면 결국 테스트 환경이 다르기 때문에 A 팀원이 측정한 Performance 점수 90점과 B 팀원이 측정한 80점은 네트워크 환경이 같았다면 동일한 점수가 될 가능성이 있기 때문이다.

대안책

상대적 비교

• 동일한 환경에서 개선 전후를 비교하여 상대적인 성능 향상을 측정

일관된 측정 환경

• 팀 내에서 측정 방법과 환경을 표준화하여 최대한 일관성 확보

결국, 동일한 와이파이를 사용하는 환경에서 동일한 노트북으로 성능 측정을 진행한 이후 팀원끼리 논의하는 방식이 가장 적합하다고 생각한다!

OUTRO

성능 개선 측정이라는 주제로 여러가지를 시도해본 결과, 각각의 방법에는 장단점이 있으며, 프로젝트의 상황과 팀의 리소스를 고려하여 가장 적합한 방법을 선택하는 것이 중요하다는걸 몸소 깨달았다.

우리가 경험한 것처럼 이론적으로 완벽해 보이는 방법도 실제 적용해보면 예상치 못한 문제들이 발생할 수 있다는걸 오랜만에 느껴본 것 같다.

튜닝의 끝은 순정이다 라는 말이 참 적절한 것 같다..

나중에 다른 프로젝트를 진행한다면, Lighthouse CI는 퍼포먼스가 너무 떨어지지 않는지 검사하는 용도로만 사용해볼 것 같다! 👊

프로젝트를 진행하면서 E2E 테스트 코드를 작성하여 자동화를 시키기로 결정했다.

우리팀은 프로젝트에서 E2E 테스트를 진행하기 위해 Playwright를 도입하기로 결정했다.

따라서, 이번 포스팅에서는 Playwright를 적용하면서 어떤 고민이 있었고, 어떻게 해결했는지 정리해보려고 한다

1. Why Playwright?

E2E 테스트의 목적부터 정리하고 시작해야할 것 같다.

우리 프로젝트에서는 E2E 테스트의 목적을 다음과 같이 정의하고 시작했다.

E2E 테스트 목적 0. 실제 사용자가 사용하는 환경을 대전제로한다.

1. 예상한 시점에 API가 제대로 호출되는지 확인한다.
2. API의 응답이 우리가 예상한 것과 동일하게 넘어오는지 확인한다.
3. API의 응답이 발생한 이후, UI가 예상한 것과 동일하게 변화하는지 확인한다.
4. 예외 케이스도 제대로 동작하는지 확인한다.

이러한 목적을 가지고 테스트를 진행해야했기 때문에, 실제 Chromium 환경에서 동작하는 Playwright 를 도입하기로 결정했다.

💡 테스트 환경은 어떻게 구성했는가?

위에서 말한 것처럼 E2E 테스트는 실제 사용자가 사용하는 환경을 대상으로 진행해야한다.

하지만, 우리는 아직 프로덕션 환경의 배포가 진행되지 않았으며, 당연히 운영 서버에 테스트 코드를 날리는건 위험하다

따라서, 우리는 목데이터가 세팅된 개발 서버 를 대상으로 E2E 테스트를 진행했다.

(개발서버 목데이터는 항상 동일한 데이터로 세팅된다)

2. What Issue?

테스트해야할 대상이 관리자 서비스 라는 것에서부터 약간의 문제가 있었다.

우선 프로젝트의 메인 시나리오를 소개하면 다음과 같다.

프로젝트 메인 시나리오

1. 팝업 등록 시나리오
2. 상품 등록 시나리오
3. 상품 조회 시나리오
4. 대시보드 조회 시나리오
5. 발주 요청 조회 시나리오 & 발주 진행 시나리오

여기서 중요한건 이 모든 시나리오는 로그인 & 팝업 선택 이라는 동일한 Flow를 사전에 가지고 있다는 것이다

다시 말하면, 팝업 등록 시나리오를 진행하기 위해서는 로그인 을 진행해야한다.

상품 등록 시나리오를 진행하기 위해서는 로그인 & 팝업 선택 을 진행해야한다.

또한, 로그인을 제외한 모든 API 요청에는 헤더에 AccessToken이 필요한데 이를 어떻게 처리해야할지도 고민해야하는 상황이 되었다.

💡 global-setup 설정

로그인을 진행하면 AccessToken은 ResponseBody로, RefreshToken은 쿠키로 발급된다.

다른 모든 API 요청헤더에 AccessToken은 어떻게 추가해야하고, RefreshToken은 어떻게 관리해야할까?

다행히도 Playwright에서는 인증 정보를 사전에 세팅할 수 있도록 설정할 수 있는 방법을 제공하고 있었다.

찾아보니, 다른 분들도 global-setup.ts 라는 파일을 생성하여 맨 처음 실행되도록 설정하는 방법을 사용하는 것 같았다.

그래서 필자가 작성해본 global-Setup.ts 파일을 살펴보면 다음과 같다.

import { chromium, FullConfig } from "@playwright/test";
import fs from "fs";
import process from "process";

async function globalSetup(config: FullConfig) {
  const authFile = "tests/auth.json";

  if (fs.existsSync(authFile) && !process.env.CI) {
    return;
  }

  const browser = await chromium.launch();
  const page = await browser.newPage();

  const baseURL = config.projects?.[0]?.use?.baseURL;

  try {
    await page.goto(`${baseURL}/onboarding`);
    await page.waitForSelector('input[placeholder*="아이디를 입력해주세요"]', {
      timeout: 10000,
    });

    await page.getByPlaceholder("아이디를 입력해주세요").fill("manager1");
    await page.getByPlaceholder("비밀번호를 입력해주세요").fill("password1");
    await page.click('button:has-text("login")');

    await page.waitForTimeout(3000);
    await page.context().storageState({ path: authFile });
  } finally {
    await browser.close();
  }
}

export default globalSetup;

코드는 인증 정보를 tests/auth.json 에 파일 형식으로 저장한다. 이후, 현재 브라우저 컨텍스트의 모든 인증 정보를 위에서 생성한 auth.json 파일로 저장하는 코드를 추가하면 된다.

💡 playwright.config.ts

위에서 설정한 global-setup.ts 는 모든 테스트 코드가 실행되기 이전에 실행되어야한다.

이러한 실행 순서를 결정하는 작업은 설정 파일에서 진행할 수 있다.

필자가 세팅했던 설정 파일을 살펴보면 다음과 같다.

import { defineConfig, devices } from "@playwright/test";
import path from "path";
import process from "process";
import dotenv from "dotenv";

const isCI = !!process.env.CI;
dotenv.config();

export default defineConfig({
  testDir: "./tests",
  fullyParallel: true,
  forbidOnly: false,
  retries: isCI ? 2 : 0,
  workers: isCI ? 1 : undefined,
  reporter: "html",
  globalSetup: path.resolve("./tests/global-setup.ts"),

  use: {
    baseURL: `${isCI ? process.env.VITE_DNS_URL : "http://localhost:3000"}`,
    trace: "on-first-retry",
    storageState: "tests/auth.json",
  },

  projects: [
    {
      name: "setup",
      testMatch: /.*\.setup\.ts/,
    },
    {
      name: "default-helper-func",
      testMatch: /.*DefaultFlow\.spec\.ts/,
      use: {
        storageState: undefined,
      },
      dependencies: ["setup"],
    },
    {
      name: "core",
      testMatch: /^(?!.*DefaultFlow).*\.spec\.ts$/,
      use: {
        ...devices["Desktop Chrome"],
      },
      dependencies: ["default-helper-func"],
    },
  ],

  ...(isCI
    ? {}
    : {
        webServer: {
          command: "npm run dev",
          url: "http://localhost:3000",
          reuseExistingServer: true,
        },
      }),
});

여기서 playwright.config.ts 에는 globalSetup 이라는 옵션을 제공한다.

여기에 이전에 생성했던 global-setup.ts 를 추가하면 모든 프로젝트 워커가 실행되기 이전에 딱 한번 실행되어 인증 정보를 생성하고 auth.json 을 저장하게 된다.

다음으로 projects의 setup 부분을 살펴보면 중간에 setup이라는 이름을 가진 파일들을 실행하게 된다.

보다시피, 앞단에서 정의된 프로젝트에 의존성을 갖기 때문에 어떠한 설정이 필요하다면 *.setup.ts 파일을 생성하여 추가하면 된다.

💡 DefaultFlow.spec.ts

다음으로 공통 처리될 부분은 “팝업 리스트 선택”이다.

필자는 로그인 & 팝업 리스트 선택 을 진행하는 테스트 코드를 DefaultFlow.spec.ts 에 정의했고, 위에서 소개한 설정파일을 보면 이는 다른 테스트 코드가 실행되기 이전에 실행된다.

따라서, 이후 core 단계에 정의된 테스트 파일들은 모두 팝업 리스트 페이지까지 이동된 이후 실행됨을 보장한다.

3. Real Data vs Test Data - 어떻게 테스트할 것인가?

필자는 이번에 E2E 테스트 코드를 작성하면서 테스트 환경이라는 상황이라 발생하는 딜레마를 겪을 수 밖에 없었다.

💡 실제 데이터 환경의 딜레마

E2E 테스트를 작성하면서 가장 큰 고민 중 하나는 "실제 데이터 환경에서 어떻게 일관된 테스트를 작성할 것인가?" 였다.

우리 프로젝트는 개발 서버의 목데이터를 대상으로 테스트를 진행했는데, 이때 다음과 같은 문제가 발생했다

1. 팝업이 이미 등록된 상태 vs 팝업이 없는 상태
2. 상품이 등록된 상태 vs 상품이 없는 상태

예를들어, 개발 서버 DB에 이미 팝업이 하나라도 등록되어있는 상황이라면 팝업이 등록되지 않는 테스트 케이스를 작성하기가 매우 까다롭다.

개발한 UI를 살펴보면 다음과 같다.

등록된 팝업이 있는 상태

등록된 팝업이 없는 상태

팝업이 등록되지 않는 경우에 대한 테스트 케이스를 작성한다면, 등록된 팝업이 없습니다. 라는 문구가 발생되는지 여부를 통해 테스트 통과를 시킬 수 있을 것이다.

하지만, 등록된 팝업이 있는 상황에서 아무런 팝업이 등록되지 않는 상황을 테스트하기는 어렵다.

물론, 기존에 개발서버에 등록되어있던 모든 팝업을 삭제하고 그 결과를 확인하는 테스트 코드를 작성할수도 있겠으나 그렇게 진행하면 개발 서버 DB를 밀고 다시 세팅해야하는 번거로움이 있다.

💡 우리가 시도해본 해결 방법들

1. 별도 계정으로 분리

// 팝업이 있는 계정용 테스트
await loginAs('manager1'); // 팝업 등록된 계정

// 팝업이 없는 계정용 테스트  
await loginAs('manager2'); // 팝업 없는 계정

이 방법의 문제점은 각 상황별로 별도의 globalSetup이 필요하고, 테스트 케이스 관리가 복잡해진다는 것이었다.

또한, 해당 계정도 서버에 별도로 등록하는 번거로움이 있었다.

2.조건부 테스트 (우리가 선택한 방법)

test.describe("헬퍼함수 기능 테스트 - 팝업 리스트 조회 및 대쉬보드 이동", () => {
  test("팝업 리스트 조회가 가능하고 팝업이 있다면, 클릭시 대시보드 페이지로 이동한다. \n 만약 팝업이 없다면, 등록된 팝업이 없다는 문구가 보인다.", async ({
    page,
  }) => {
    // given & when - 팝업 리스트 이동시 조회 API 호출
    const [responsePromise] = await Promise.all([
      page.waitForResponse(response => {
        const url = response.url();
        return url.endsWith("/popups") && response.request().method() === "GET";
      }),
      page.goto("/popup-list"),
    ]);

    await page.waitForLoadState("networkidle"); // 네트워크가 안정화될 때까지 대기 -> waitFor과 동일한 효과 기대 가능

    // then - 조회 결과 검증
    expect(responsePromise.status()).toBe(200);
    const responseBody = await responsePromise.json();
    const numOfPopupFromAPI = responseBody.data.length;

    // 조회된 데이터가 있을 경우와 없을 경우를 if문을 통해 분기 처리
    if (numOfPopupFromAPI !== 0) {
      const allPopups = page.locator('span[data-testid^="popup-card-"]');
      await expect(allPopups.first()).toBeVisible();

      const numOfPopupOnScreen = await allPopups.count();

      expect(numOfPopupFromAPI).toBeGreaterThan(0);
      expect(numOfPopupFromAPI).toBe(numOfPopupOnScreen);

      const firstPopup = allPopups.first();
      await firstPopup.click({ timeout: 3000 });

      await expect(page).toHaveURL("/dashboard");
    } else {
      await expect(page.getByText("등록된 팝업이 없습니다.")).toBeVisible();
    }
    await page.waitForLoadState("networkidle");
  });
});

결국 우리는 테스트 케이스를 분리하지 않고 여러가지 조건(ex. 계정 추가 생성 등)을 추가해야하는 경우에는 분기처리로 없는 경우에대한 테스트 코드만 작성하기로 결정했다.

💡 테스트는 어떻게 작성하면 좋을까?

E2E 테스트를 어떤 방식으로 작성해야 할지 고민하던 중, 팀원의 코드 리뷰 과정에서 좋은 접근법을 발견하게 되었다.

이 방법이 꽤 괜찮은 것 같아서 PPT에 사용된 장표 일부를 소개하고자 한다.

여러가지 고민끝에 생각한 순서는 다음과 같다.

마지막 예외 케이스 작성 단계가 중요한 이유는, 실제 사용자 데이터와 운영 환경에서 발생할 수 있는 다양한 시나리오를 미리 검증할 수 있기 때문이라고 생각한다!

💡 테스트 데이터 관리의 고민

이런 방식으로 테스트를 작성하다 보니 "과연 이것이 올바른 E2E 테스트일까?" 라는 의문이 들었다.

결국, 정리해보면 E2E 테스트의 Pros and Cons 는 다음과 같다고 볼 수 있다.

Pros

• 실제 데이터 환경에서 테스트하므로 현실적이다.

Cons

• 테스트 케이스가 데이터 상태에 의존적이다.
• 예외 상황 테스트가 어려우며, 테스트 코드가 복잡해진다.

OUTRO

필자가 이번에 E2E 테스트 코드를 작성하면서 느낀점을 정리해보면 다음과 같다.

💡 E2E 테스트만으로는 부족하다

E2E 테스트를 작성하면서 느낀 점은 E2E 테스트만으로는 모든 상황을 커버하기 어렵다는 것이었다.

특히, 예외 상황 테스트(서버 에러, 네트워크 오류 등)를 진행하기 위해서는 테스트 코드양이 방대해지며, 이를 유지보수하는게 과연 프로덕션 환경에서 에러를 잘잡아줄지도 약간 의문이 들었다.

💡 우리가 내린 결론

따라서 앞으로 테스트 코드를 작성한다면 다음과 같이 작성하는게 더 예외 상황을 잘 잡아주고, 유지보수도 편해질 것이라고 생각한다.

• E2E 테스트: 핵심 사용자 플로우 검증
• 통합 테스트: API 레벨에서의 비즈니스 로직 검증
• 단위 테스트: 개별 컴포넌트/함수 검증

E2E 테스트는 "행복한 경로"를 중심으로, 나머지 예외 상황은 단위/통합 테스트에서 더 세밀하게 다루는 것이 효율적이라고 생각한다!

2차 프로젝트가 끝나고 3일이 지난 이제서야 회고록을 써보려고 한다 😅

프로젝트 기간 동안 많은 트러블 슈팅이 있었고, 이를 해결하기 위해 정말 많은 시간과 노력을 쏟았다.

짧은 기간이었지만 MSA 아키텍처와 클라우드 환경에서의 서비스 구축을 직접 경험하면서 의미 있는 기술적 도전을 할 수 있었다.

이제부터 필자가 프로젝트에서 어떤 파트를 담당했고, 어떤 작업을 했는지 소개해보려고 한다!

1. 어떤 역할을 맡았는지?

본 프로젝트의 주제는 1차 프로젝트에서 진행했던 다른 팀의 결과물에 MSA를 적용하는 것이었다.

여기서 필자는 AWS 클라우드 아키텍처 및 CI/CD 파이프라인 구축 이라는 DevOps 파트를 맡게 되었다.

사실 AWS와 CI/CD 모두 이번 수업에서 처음 접했던 내용이긴 했지만, 한번 해보면 좋은 경험이 될 것 같아 자진해서 지원해봤다.

하지만, 생각만큼 쉽지는 않았다..

2. CI/CD 구축

우선 CI/CD를 구축하기 위해 AWS EC2에 Jenkins를 직접 설치하는 방법을 사용했다.

수업 시간 중에, 강사님께서 Jenkins의 CI/CD 작업은 많은 프로젝트와 연결되어있고, 프로젝트 규모에 따라 자원을 많이 사용할 수 있기 때문에 별도로 관리하는게 좋다는 말씀해주셨기 때문이다.

💡 파이프라인 동작

백엔드 파트에서 도메인별로 나눈 프로젝트에는 이와 같은 파일 구조를 가지도록 설계했다.

이후, 파이프라인은 다음과 같은 순서로 동작하도록 설계해봤다.

동작 과정을 살펴보면, Git Clone 으로 가져온 프로젝트 파일을 사용해서 Docker Image Build 를 진행하기 때문에 프로젝트 내부에 Dockerfile 이 필요했고, 각 프로젝트마다 파이프라인이 다를 수 있기 때문에 별도의 Jenkinsfile 을 작성해서 추가하는 방법을 사용했다.

💡 문제점

CI/CD 파이프라인은 Git Webhook을 사용해서 동작한다.

따라서, 각 프로젝트마다 Git Webhook을 추가해주는데 여기서 Jenkins에서 기본적으로 제공하는 Webhook을 사용하면 상세한 설정이 불가하다.

한가지 예를 들자면, API Gateway Repo에 파이프라인을 작성해두고 AWS Cloud 환경에서 Eureka에 API Gateway가 등록되는 테스트를 진행하고 있었다.

이 과정에서 다른 팀원이 Develop 브랜치에 푸쉬를 하는 상황이 있었는데 파이프라인이 동작해서 재배포가 되는 과정이 꽤 있었다.

그래서 우리는 Generic Webhook Trigger 라는 별도의 플러그인을 사용해서 반자동화를 사용하는 방법을 택했다.

단순히 Develop 브랜치에 Push나 PR이 발생하는 모든 경우에 파이프라인이 동작하는것이 아닌, Deploy 라벨을 추가한 경우에만 파이프라인이 동작되도록 프로젝트를 구성하고 진행했다.

물론, 브랜치를 세세하게 나누고 특정 브랜치에 대해서는 완전 자동화를 사용하는 방법도 있겠으나 프로젝트 Rule을 세세하게 정할 시간이 별로 없었기 때문에 이러한 방식으로 해결해봤다.

💡 아쉬운점

본 프로젝트를 진행하면서 Jenkinsfile을 실제로 하나씩 모두 작성해서 프로젝트에 넣어줬는데, Groovy로 Jenkinsfile의 구조를 잡아주고 Github Scan을 사용하면 코드의 중복을 최소화해서 작업할 수 있다고 한다.

Groovy 언어를 사용해본적이 없어서 당시에는 적용해볼 엄두가 나지 않았으나, 이런 부분을 적용하지 못한게 아쉬워서 시간남으면 혼자 해보려고 한다

3. AWS Cloud Architecture

프로젝트를 진행하면서 가장 많이 했던 고민이 아키텍처에 대한 고민인 것 같다.

물론, 최종적으로 사용한 결과물이 완벽하진 않지만 어떤 내용을 고민했는지 공유해보려고 한다.

우선, 프로젝트의 초기 아키텍처를 살펴보면 다음과 같다.

💡 초기 아키텍처

위 사진과 같이 ECS에 서비스를 여러개 띄우고 ALB 하나가 정의된 Fargate에 대해서 로드 밸런싱을 모두 진행하는 구조로 설계했다.

하지만, 우리가 프로젝트에 MSA를 적용하는 과정에서 Spring Cloud API Gateway, Config Service, Eureka 등등을 사용하는데 이러한 서비스는 Outer Architecture에 속한다고 볼 수 있다.

실제로 사용자에게 서비스를 제공하기 위한 비즈니스 로직이 처리되는 부분이 아니기 때문이다.

중간에 강사님께 피드백을 받는 시간이 종종 있었는데, 이러한 Outer Architecture는 고가용성을 확보하기 위해 EC2에 배포한다고 피드백을 주셨다.

또한, 필자의 경우도 이미 Spring Cloud API Gateway를 사용하는 구조에서 ALB를 사용해 로드밸런싱을 하는게 과연 맞는 선택일까 하는 생각도 가지고 있었다.

그래서 구조를 다시 변경하기 시작했다..!

(이미 파이프라인까지 모두 만들어둔 상태였으나, 피드백을 받고 전체적으로 수정하기로 결정했다..........)

💡 최종 아키텍처

이미 Spring Cloud API Gateway를 사용하고 있으니 모든 요청을 API Gateway로 받도록 수정했다.

이후, 여러개의 서비스 인스턴스를 유레카에 등록했다면 라운드로빈 방식으로 라우팅을 진행하지만, 여기서 우리는 상대적으로 많은 트래픽이 몰릴 수 있다고 생각한 User-Service와 Track-Service에 ALB를 사용해서 로드 밸런싱과 오케스트레이션을 진행하도록 구조를 변경했다.

이렇게 구조를 작성한다면 User-Service와 Track-Service는 Eureka의 서비스 디스커버리 기능을 포기하게 된다.

조금 더 자세히 설명하자면 다음과 같다.

우선 우리는 Config 서버에서 API Gateway에 대한 라우팅 정보를 받아와서 동작하도록 설계했다.

그 라우팅 정보는 다음과 같다.

Sample Code

spring:
  config:
    activate:
      on-profile: "routes"
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/members/**
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/admin/**
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/auth/**
        - id: track-service
          uri: lb://track-service
          predicates:
            - Path=/tracks/**
        - id: recommendation-service
          uri: lb://recommendation-service
          predicates:
            - Path=/music/**

여기서 user-service와 track-service가 ALB를 사용하도록 하기 위해, prod 환경에서는 다음과 같은 라우팅 정보를 가져오도록 한다.

Sample Code

spring:
  config:
    activate:
      on-profile: "routes-prod"
  cloud:
    gateway:
      routes:
        - id: user-service
          # 실제 ALB URI 입력
          uri: http://user-service-alb.region.elb.amazonaws.com 
          predicates:
            - Path=/members/**
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/admin/**
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/auth/**
        - id: track-service
          # 실제 ALB URI 입력
          uri: http://track-service-alb.region.elb.amazonaws.com 
          predicates:
            - Path=/tracks/**
        - id: recommendation-service
          uri: lb://recommendation-service
          predicates:
            - Path=/music/**
      globalcors:
        corsConfigurations:
          '[/**]':
            allowedOrigins: "*"
            allow-credentials: false
            allowedHeaders:
              - x-requested-with
              - authorization
              - content-type
              - credential
              - X-AUTH-TOKEN
              - X-CSRF-TOKEN
            allowedMethods:
              - POST
              - GET
              - PUT
              - OPTIONS
              - DELETE

이렇게되면 User-Service와 Track-Service는 Eureka에 등록할 필요가 없고, ALB가 대신 ECS 서비스의 여러 태스크 간 로드 밸런싱을 담당하게 된다.

만약, 서비스 자체적인 트래픽에 대해서 로드밸런싱이 필요하다면 API Gateway 앞쪽에 ALB를 하나 더 추가하는 방법도 있을 것이다.

💡 문제점

가장 큰 문제점은 비용이다.

만약, 실무에서 Cloud Architecture를 구성해야한다면 불필요한 부분은 최대한 제거해서 아키텍처를 구성하는게 맞다.

실제 트래픽에 대한 테스트를 진행한게 아니기 때문에 위처럼 구조를 작성하는게 오히려 불필요한 관리를 더하는 일이 될 수 있으며, Fargate의 경우 메모리 설정을 서비스에 Fit하게 맞춘게 아니라면 메모리를 사용하지 않아도 그대로 비용이 청구된다.

실제로 비용청구 내용을 보니 메모리는 10%만 사용하면서 전체 비용을 청구하는 모습을 볼 수 있었다..

다른 팀의 경우 EC2에 도커를 사용해서 프로젝트를 관리하는 구조를 보여주기도 했는데, 비용과 관리를 생각하면 이번 프로젝트에서는 그러한 구조가 훨씬 더 적절하다는 생각이 들긴한다.

따라서, 본 프로젝트에서는 최대한 여러가지 방법을 시도해봤다는데에 의의를 두려고 한다 👊

4. EC2 (Eureka) & ECS

위에서 최종 아키텍처를 보면 알겠지만, EC2에 Eureka 프로젝트를 도커로 띄워서 사용하고 있다.

이때, 하나의 EC2에는 하나의 서비스만 띄우는 구조를 채택했기 때문에 각 EC2에 Spring 프로젝트를 띄우는 경우 Docker의 Host Network를 사용해서 포트를 뚫어줬다.

이런 구조를 사용해서 Spring Cloud의 Eureka, API Gateway, Config Server를 각 EC2에 띄웠다.

그리고 각 서비스는 ECS에서 클러스터를 도메인별로 분리해서, 단순히 컨테이너만 띄우는 Fargate를 사용했다.

그런데 우선 첫번째로 Eureka에 서비스가 등록되지 않는 문제가 발생했다.

로그를 살펴봤을 때, Config Server에서 설정 정보를 패치했음에도 자꾸 localhost에서 정보를 가져오려고 시도했기 때문에 발생한 문제였다.

그래서 bootstrap에 Eureka를 먼저 받도록 설정하여 해결했다.

💡 API Gateway 호출 문제

EC2에 Spring Cloud API Gateway를 띄우고, Gateway를 통해 ECS의 서비스를 호출하려고 시도해보니 호출이 안되는 문제를 발견했다.

로그를 살펴보니 API Gateway에도 아무런 로그가 찍히지 않는 모습을 볼 수 있었다.

보안정책으로 Gateway 포트를 열어놨음에도 요청이 안들어오는 문제였다.

사실 이 문제 때문에 엄청 고생했다.

관련 포스팅을 겨우겨우 찾아 Github Repo에 작성된 코드를 살펴보니 Global CORS 설정이 되어있는 모습을 볼 수 있었다.

그래서 본 프로젝트에도 API Gateway 설정 파일에 GlobalCORS 설정을 추가해서 문제를 해결할 수 있었다.

아무래도 로그가 찍히지 않았다는 것은 Gateway가 CORS 프리플라이트 요청 단계에서 차단되었다는 것을 의미한다고 생각한다.

Postman으로 요청을 넣었음에도 요청이 도달하지 않는다는 것은 API Gateway가 CORS 헤더를 확인하도록 설정되어 있었기 때문이다.

따라서, 이 부분을 모두 허용함으로써 해결할 수 있었다..!

💡 ECS 서비스 호출 문제

위 설정을 마치고 API Gateway의 로그를 보니 요청은 정상적으로 들어온다.

그런데 이제는 요청에서 404가 떠버리는 모습을 볼 수 있었다.

라우팅 테이블은 제대로 등록되어있다고 계속해서 로그가 찍히는데, 해당 라우트 정보로 요청을 진행해도 404가 뜨는 상황이었다.

필자는 이 문제가 Eureka에서 서비스 인스턴스의 정보를 제대로 받아오지 못해서 발생한다고 생각했다.

그래서 Eureka에 등록된 서비스 정보를 찾아보기 시작했다.

위 사진은 EC2로 옮기기 전에 Eureka에 API Gateway가 등록되는 모습이다. (관련 사진을 안찍어놔서 없다..)

보다시피 169. 으로 시작되는 IP가 등록되는 모습을 볼 수 있다.

이 정보는 우리가 띄운 ECS Fargate 컨테이너의 주소 이다.

즉, 우리의 실제 서빙하고 있는 서비스의 Private IP가 아니라 컨테이너에서 사용하는 주소이므로 위 정보를 다시 내려받는다고해도 API Gateway는 정상적으로 서비스에 라우팅을 할 수 없다.

Eureka의 경우 /eureka/apps 로 들어가면 실제 등록된 서비스 인스턴스의 정보를 더 상세하게 확인할 수 있다.

살펴보니 IP Address도 위에서 언급한 Fargate 컨테이너 주소로 등록되어있는 모습을 볼 수 있었다.

따라서, 별도의 코드를 작성해서 Spring 프로젝트가 구동될 때, AWS Private IP를 Eureka에 등록하도록 설정을 변경했다.

로그를 찍도록 코드를 작성했는데, 실제 Private IP로 등록되는 모습을 볼 수 있다.

위 사진이 바로 /eureka/apps 정보에서 확인할 수 있는 서비스 인스턴스의 정보인데, ipAddr 관련 정보가 원하는대로 서비스의 Private IP가 등록된 모습을 볼 수 있었다.

이후, 서비스를 호출하면 제대로 호출이 된다!

💡 문제점

이렇게 문제점을 해결해보면서 느낀 것은 AWS Cloud 환경에서 Spring Cloud를 적용하는게 꽤 까다롭다는 것을 느꼈다.

실제로 AWS에서도 Gateway 서비스를 제공하고 있기 때문에, 환경에 맞는 서비스를 사용하는게 더 낫다는 생각도 들었다.

다음 프로젝트 때, 기회가 된다면 AWS Gateway를 사용해서 플랫폼 친화적으로 아키텍처를 구성해보고 싶다.

5. 그 외의 트러블 슈팅...

사실 이것말고도 엄청 많은 문제를 겪었다.

아마 한 스텝을 나가는데 3시간씩 걸린것 같다...

💡 RabbitMQ

예를들어 RabbitMQ를 EC2에 설치하는 과정에서 4.0-management Docker 이미지를 가져와서 설치했는데, 이건 찾아보니까 linux/amd64 환경은 지원하지 않는다.

EC2의 환경을 linux/arm64 로 변경하여 RabbitMQ를 직접 설치할 수 있었다.

💡 Mac M3

필자의 노트북은 맥북 M3칩을 사용하는데, CPU를 M1/M2/M3로 사용하는 환경에서는 도커 이미지를 빌드할 때, 무조건 플랫폼을 명시해줘야 한다.

맥에서 빌드하는 이미지를 빌드하는 환경과 AWS Cloud 인스턴스 환경이 맞지 않는 경우가 대부분이기 때문이다.

따라서, CI/CD를 작성할 때 platform을 명시해주자..!

◉ 커맨드 docker build --platform linux/amd64 -t mini2/api-gateway .

OUTRO

이번 프로젝트는 AWS, Jenkins 등을 활용한 CI/CD 파이프라인 구축부터 클라우드 아키텍처 설계, 배포까지 전적으로 맡아서 진행한 값진 경험이었다.

처음 해보는 것들이 많아 수많은 삽질과 밤샘을 했지만, 그만큼 배움의 깊이도 남달랐다 진짜로..

특히 마지막에 제대로 API Call이 되는 순간은 너무 감격스러웠다.

비록 과정은 고통스러웠지만, 문제를 하나씩 해결해 나가는 과정에서 MSA 아키텍처와 클라우드 환경에 대한 이해도가 크게 높아졌다.

짧은 기간 동안 정말 많은 기술을 경험하고 성장할 수 있어서 힘들었지만 그만큼 보람찼던 프로젝트였다.

이 경험이 앞으로의 개발에서 큰 자산이 될 것이라 확신한다 👊

프로젝트 Github

📖 참고

트러블 슈팅 (feat. Eureka AWS 배포하기) [Jenkins CI/CD] 4. WebHook을 이용한 자동 배포 [CI/CD] Jenkins에서 특정 브랜치에 대한 GitHub Webhook만 처리

이전 포스팅에서는 서킷 브레이커 패턴을 이용하여 마이크로서비스 아키텍처에서 회복성을 확보하는 방법에 대해 살펴봤다.

이번 포스팅에서는 MSA 환경에서 또 다른 중요한 문제인 '디버깅과 모니터링'을 해결하는 분산 트레이싱 시스템인 Zipkin에 대해 알아보고, 실제로 적용해보자 👀

1. 분산 트레이싱이 필요한 이유

마이크로서비스 아키텍처에서는 하나의 요청이 여러 서비스를 거쳐 처리되기 때문에 문제가 발생했을 때 원인을 찾기가 매우 어렵다.

위 사진은 Order-Service에서 getOrders() 메서드를 호출하는 과정에서 에러가 발생하는 구조이다.

서킷 브레이커를 사용하는 이유가 사용자의 경험을 해치지 않기 위함이었다면, 분산 트레이싱을 사용하는 이유는 개발자의 경험을 해치지 않기 위함이라고 볼 수 있다.

실제로, 위 그림과 같이 여러 서비스가 연계되어 있는 환경에서 디버깅을 진행하려면 여러 가지 어려움이 있다.

디버깅 문제

여러 서비스의 로그를 동시에 확인해야 함

• 각기 다른 서비스에서 발생하는 로그를 한 번에 보기 어려움

요청의 흐름 추적이 어려움

• 어떤 서비스에서 어떤 순서로 요청이 처리되었는지 파악하기 힘듦

다양한 기술 스택

• 서로 다른 언어나 프레임워크로 개발된 서비스들을 모두 디버깅하기 어려움

이런 문제들을 해결하기 위해 분산 트레이싱이라는 개념이 등장했고, 이를 구현한 대표적인 도구 중 하나가 바로 Zipkin인 것이다.

💡 Zipkin이란?

그렇다면, Zipkin은 뭘까?

Zipkin은 트위터에서 개발한 오픈소스 분산 트레이싱 시스템으로, 마이크로서비스 아키텍처에서 요청의 흐름을 시각화하고 분석할 수 있게 해준다.

Zipkin의 주요 개념으로는 'Trace'와 'Span'이 있다.

Trace & Span

Trace

• 하나의 요청이 시스템을 통과하는 전체 경로를 나타내는 작업 그룹을 의미한다.

Span

• Trace를 구성하는 개별 작업 단위, 각 서비스에서 처리되는 하나의 작업을 의미한다.

위 그림에서 볼 수 있듯이, 하나의 Trace ID에 여러 개의 Span ID가 포함된다.

각 Span은 요청이 특정 서비스에서 어떻게 처리되었는지에 대한 정보를 담고 있으며, 개발자는 이를 추적하여 로그를 트레이싱할 수 있다.

2. Zipkin 설정하기

Spring 기반의 마이크로서비스에서는 Zipkin 의존성을 추가하여 분산 트레이싱을 구현할 수 있다.

우선 Zipkin을 설치하기 위해 공식 홈페이지로 접근하면 다음과 같은 화면을 볼 수 있다.

공식 홈페이지에서 알려주는 것과 같이 Docker에서 zipkin 컨테이너를 띄워서 사용할 수 있다.

하지만, 최근 Zipkin은 영구 저장소로 MySQL과 같은 데이터베이스를 사용하도록 변경되었다.

따라서 필자는 MySQL과 함께 Zipkin을 실행하기 위한 docker-compose 파일을 만들어서 사용해볼 예정이다.

💡 Zipkin 대쉬보드 접근

Zipkin 홈페이지에서 제공하는 명령어를 입력하여 도커 컨테이너를 띄운 상태라면, 사진과 같이 대쉬보드에 바로 접근해볼 수 있다.

포트바인딩에 사용된 9411 포트로 접근하면 Zipkin에서 제공하는 UI를 이용하여 요청을 추적할 수 있다.

💡 Docker Compose 파일 작성하기

우선 Docker Compose 파일을 살펴보자

Sample Code

version: '3'
services:
  zipkin:
    image: openzipkin/zipkin
    ports:
      - "9411:9411"
    environment:
      - STORAGE_TYPE=mysql
      - MYSQL_DB=zipkin
      - MYSQL_USER=zipkin
      - MYSQL_PASS=zipkin
      - MYSQL_HOST=mysql
  mysql:
    image: mysql:5.7
    platform: linux/amd64
    volumes:
      - ./initdb.d:/docker-entrypoint-initdb.d
    environment:
      MYSQL_DATABASE: zipkin
      MYSQL_USER: zipkin
      MYSQL_PASSWORD: zipkin
      MYSQL_ROOT_PASSWORD: root
    ports:
      - "3308:3306"

이 docker-compose 파일에서는 Zipkin 서버와 MySQL 데이터베이스를 함께 실행한다.

MySQL 컨테이너가 시작될 때 필요한 스키마를 자동으로 생성하기 위해 초기화 스크립트를 볼륨으로 마운트하고 있다.

초기화 스크립트(initdb.d 디렉토리에 저장)는 Zipkin이 필요로 하는 테이블 구조를 생성하는 쿼리가 작성되어있으며, zipkin 스키마에서 제공하는 쿼리를 포함한다.

💡 마이크로서비스에 Zipkin 클라이언트 설정하기

Zipkin을 이용해서 트레이싱을 하고싶은 서비스 설정 파일에서 다음과 같은 설정 정보를 추가하자

Sample Code

management:
  tracing:
    sampling:
      probability: 1.0    # 모든 요청에 대해 트레이싱 활성화
    propagation:
      consume: B3
      produce: B3
  zipkin:
    tracing:
      endpoint: http://localhost:9411/api/v2/spans    # Zipkin 서버 주소
  endpoints:
    web:
      exposure:
        include: health, httptrace, info, metrics, prometheus    # 모니터링 엔드포인트 노출

여기서 눈여겨볼만한 설정은 다음과 같다.

sampling.probability

• 트레이싱할 요청의 비율 (1.0은 모든 요청을 트레이싱)

propagation

• 트레이싱 정보를 전달하는 형식 (B3는 Zipkin의 기본 형식)

zipkin.tracing.endpoint

• Zipkin 서버의 주소
• 여기서는 도커로 띄워놓은 주소를 제공하면 된다.

이렇게 설정이 끝나면 실제로 서비스마다 Slf4j 를 사용하여 log를 찍어놓은 내용이 Zipkin에 등록된다.

별도로 코드를 추가하는 등의 작업은 필요없다.

💡 Micrometer 의존성 추가하기

Spring Boot 3.x부터는 기존에 사용되던 Spring Cloud Sleuth가 Micrometer Tracing으로 통합되었다.

따라서 분산 트레이싱을 구현하기 위해서는 Sleuth가 아닌 Micrometer 관련 의존성을 추가해야 한다.

Gradle을 사용한다면 다음과 같이 의존성을 추가하면 된다

Gradle 의존성 추가

implementation 'org.springframework.boot:spring-boot-starter-actuator'
implementation 'io.micrometer:micrometer-tracing-bridge-brave'
implementation 'io.zipkin.reporter2:zipkin-reporter-brave'

의존성을 추가한 후에는 로깅 패턴을 적용하여 로그에 Trace ID와 Span ID가 표시되도록 해야 한다.

이를 위해 application.yml 파일에 다음과 같은 설정을 추가한다

Sample Code

logging:
  pattern:
    level: '%5p [${spring.application.name:},%X{traceId:-},%X{spanId:-}]'

이 설정은 로그 메시지의 레벨 부분에 애플리케이션 이름, Trace ID, Span ID를 함께 표시해준다.

이렇게 하면 여러 서비스의 로그를 모아서 볼 때도 어떤 요청에 속하는 로그인지 쉽게 파악할 수 있다!

여기서 중요한 것은, 위의 의존성과 로깅 패턴을 모두 적용해야 Trace ID와 Span ID가 정상적으로 생성되고, 이 정보가 Zipkin 대시보드에 올바르게 등록된다는 것이다.

단순히 Zipkin 서버만 실행했다고 해서 데이터가 자동으로 수집되는 것이 아니라, 각 마이크로서비스에서 이러한 설정이 제대로 이루어져야 한다.

또한, 이렇게 로깅 패턴을 등록한다면 Zipkin에서 확인한 ID를 가지고와서 CLI 환경에서도 로그를 직접 찾아볼 수도 있을 것이다.

3. Zipkin으로 분산 트레이싱 확인하기

모든 설정을 마친 후 서비스들을 실행하면, Zipkin UI를 통해 트레이싱 정보를 확인할 수 있다.

여기서 각 요청을 상세히 확인하고 싶다면, SHOW 버튼을 클릭하면 된다.

그러면 사진과 같이 Trace ID, Span ID를 모두 확인할 수 있으며, 요청이 어떤 흐름으로 진행되고 있는지도 확인할 수 있다.

OUTRO

이번 포스팅에서는 마이크로서비스 환경에서 분산 트레이싱을 구현하기 위한 Zipkin 사용법에 대해 알아보았다.

분산 트레이싱은 시스템의 동작을 이해하고 최적화하는 데 필수적인 인사이트를 제공한다.

당연히, 호출 시간이 오래 걸리는 API를 발견한다면 해당 API를 리팩토링하여 성능을 개선시켜야한다는 근거로 사용할 수 있을 것이다.

MSA 환경에서는 서비스 간 통신이 많아질수록 이러한 추적 도구의 중요성이 더욱 커진다는 점을 기억하자 👊

이전 포스팅에서는 Kafka를 이용해서 마이크로서비스 간 데이터 일관성 문제를 해결하는 방법에 대해 살펴봤다.

이번 포스팅에서는 마이크로서비스 아키텍처에서 또 다른 중요한 패턴인 서킷 브레이커(Circuit Breaker)에 대해 알아보고, 실제로 적용해보자 👀

1. 마이크로서비스의 통신 연쇄 오류 문제

마이크로서비스 아키텍처에서는 위 그림처럼 여러 서비스가 API를 통해 통신하는 구조를 가진다.

이런 구조에서는 한 서비스의 장애가 다른 서비스로 전파되는 문제가 발생할 수 있다.

예를 들어 위 사진에서 Order-Service의 getOrders()라는 부분에서만 오류가 발생했다고 해보자.

하지만, 이 오류는 계속 서비스를 타고 올라가서 결국 사용자에게도 에러가 발생했음을 보여줘버린다.

우리는 내부적으로 에러가 발생했음에도 사용자에게는 보여주지 않아야한다.

먼저, 실제로 정상적인 데이터를 가져오지 못하는 에러가 발생하더라도 Fallback Method를 사용해서 사용자에게는 정상적인 응답을 보여주는 방법을 알아보자 👀

💡 오류가 발생했는데 어떻게 정상 응답을 줄 수 있을까?

위 내용만 들었을 때는 이런 의문이 들 수 있다.

실제로 정상적인 데이터를 가져오지 못한다면 어떻게 사용자에게 응답을 줄 수 있을까?

전략

대체 메시지 제공

• 오더 서비스를 일시적으로 가져올 수 없다는 안내 메시지를 보여준다. (예: "잠시 후에 다시 시도해주세요")

캐싱된 데이터 사용

• 유저 서비스에서 이전에 Order Service에서 데이터를 한번이라도 가져왔다면 그 데이터를 캐싱해놓고 사용한다. 최신 데이터는 아니지만, 사용자는 완전히 빈 응답보다는 약간 오래된 데이터라도 볼 수 있다.

기본값 반환

• 데이터를 가져오지 못할 경우 빈 리스트 같은 기본값을 반환한다.

중요한 것은 실제로 정상적인 데이터가 아니더라도 사용자에게 에러 메시지를 보여주는 것보다 대체 응답을 제공하는 것이 더 나은 사용자 경험을 제공한다는 점이다.

이러한 패턴을 MSA에서는 회복성(Resilience) 혹은 회복력(Fault Tolerance)이라고 부른다!

💡 간단한 Try-Catch로 구현하기

가장 기본적인 방법으로 try-catch 문을 사용해서 오류를 처리할 수 있다.

Sample Code

@Override
public UserDto getUserByUserId(String userId) {
    UserEntity userEntity = userRepository.findByUserId(userId);
>
    if (userEntity == null)
        throw new UsernameNotFoundException("User not found");
>
    UserDto userDto = new ModelMapper().map(userEntity, UserDto.class);
>
    log.info("Before call orders microservice");
    List<ResponseOrder> ordersList = new ArrayList<>();
>
    try {
        ordersList = orderServiceClient.getOrders(userId);
    } catch (FeignException ex) {
        log.error(ex.getMessage());
    }
>
    userDto.setOrders(ordersList);
>
    log.info("After called orders microservice");
>
    return userDto;
}

위 코드에서는 orderServiceClient.getOrders(userId) 호출이 실패하더라도 try-catch를 통해 예외를 잡아내고, 빈 ordersList를 사용하여 응답을 생성한다.

이렇게 하면 사용자는 주문 내역이 비어있는 응답을 받게 되지만, 서비스 자체는 정상적으로 작동한다.

하지만 이 방식은 매우 기본적인 방법이고, 더 복잡한 장애 상황에서는 당연히 부족할 수 있다.

이럴 때 서킷 브레이커 패턴을 사용할 수 있다.

2. 서킷 브레이커 패턴

서킷 브레이커는 다음 3가지 상태를 가진다

서킷 브레이커 상태

Closed (닫힘)

• 정상 상태로, 모든 요청이 대상 서비스로 전달된다.

Open (열림)

• 장애 상태로, 요청이 대상 서비스로 전달되지 않고 즉시 폴백(fallback) 메서드가 실행된다.

Half-Open (반열림)

• 일정 시간 후 서킷 브레이커가 오픈된 상태에서 일부 요청을 시험적으로 대상 서비스에 전달해보는 상태이다.
• 이 요청들이 성공하면 서킷 브레이커는 다시 Closed 상태로 돌아가고, 실패하면 다시 Open 상태가 된다.

즉, 에러가 임계치 이상으로 자주 발생하면 중간에 서킷브레이커가 동작하여 요청을 뒷단으로 넘기지 않고, 서킷브레이커 선에서 정리하는 방식으로 동작한다.

서킷 브레이커는 단순히 오류가 많이 발생하는 경우 요청을 모두 차단하는 것이 아니라, 실제로는 복구를 위해서 요청을 시험적으로 전달하며 서비스의 복구 여부를 판단한다.

현재 스프링 클라우드 생태계에서는 Resilience4j 가 많이 사용되고 있다.

기존에 사용되던 Netflix Hystrix 가 유지보수 모드로 전환되면서 Resilience4j가 새로운 대안으로 제시된 추세다.

Resilience4j 는 서킷 브레이커 외에도 Retry, Bulkhead, RateLimiter, TimeLimiter 등 다양한 회복성 패턴을 제공한다.

3. Resilience4j 적용하기

이제 실제로 Resilience4j 를 스프링 부트 프로젝트에 적용해보자

우선 위 사진과 같이 Resilience4j 의존성을 프로젝트에 추가하자

💡 서킷 브레이커 설정

우선, Resilience4j 서킷 브레이커를 설정하는 코드를 살펴보자

Sample Code

@Configuration
public class Resilience4JConfig {
    @Bean
    public Customizer<Resilience4JCircuitBreakerFactory> globalCustomConfiguration() {
        CircuitBreakerConfig circuitBreakerConfig = CircuitBreakerConfig.custom()
                .failureRateThreshold(4)
                .waitDurationInOpenState(Duration.ofMillis(1000))
                .slidingWindowType(CircuitBreakerConfig.SlidingWindowType.COUNT_BASED)
                .slidingWindowSize(2)
                .build();
>
        TimeLimiterConfig timeLimiterConfig = TimeLimiterConfig.custom()
                .timeoutDuration(Duration.ofSeconds(4))
                .build();
>
        return factory -> factory.configureDefault(id -> new Resilience4JConfigBuilder(id)
                .timeLimiterConfig(timeLimiterConfig)
                .circuitBreakerConfig(circuitBreakerConfig)
                .build()
        );
>
    }
>
    @Bean
    public Customizer<Resilience4JCircuitBreakerFactory> specificCustomConfiguration1() {
        CircuitBreakerConfig circuitBreakerConfig = CircuitBreakerConfig.custom()
                .failureRateThreshold(6).waitDurationInOpenState(Duration.ofMillis(1000))
                .slidingWindowType(CircuitBreakerConfig.SlidingWindowType.COUNT_BASED)
                .slidingWindowSize(3).build();
>
        TimeLimiterConfig timeLimiterConfig = TimeLimiterConfig.custom()
                .timeoutDuration(Duration.ofSeconds(4)).build();
>
        return factory -> factory.configure(builder -> builder.circuitBreakerConfig(circuitBreakerConfig)
                .timeLimiterConfig(timeLimiterConfig).build(), "circuitBreaker1");
    }
>
    @Bean
    public Customizer<Resilience4JCircuitBreakerFactory> specificCustomConfiguration2() {
        CircuitBreakerConfig circuitBreakerConfig = CircuitBreakerConfig.custom()
                .failureRateThreshold(8).waitDurationInOpenState(Duration.ofMillis(1000))
                .slidingWindowType(CircuitBreakerConfig.SlidingWindowType.COUNT_BASED)
                .slidingWindowSize(4).build();
>
        TimeLimiterConfig timeLimiterConfig = TimeLimiterConfig.custom()
                .timeoutDuration(Duration.ofSeconds(4)).build();
>
        return factory -> factory.configure(builder -> builder.circuitBreakerConfig(circuitBreakerConfig)
                        .timeLimiterConfig(timeLimiterConfig).build(),
                "circuitBreaker2");
    }
}

뭔가 복잡해보이지만, 실제로 서킷 브레이커 패턴을 2개 등록해서 그렇게 보이는 것 뿐이다.

코드를 살펴보면 다음과 같다.

간단하게 설정 정보를 정의하고, 이를 리턴할 때 적용해주는 것이다.

글로벌로 설정할 때는 리턴 과정에서 configureDefault 를 호출하여 설정하고, 특정 조건으로 사용할 서킷 브레이커는 configure 메서들르 호출하여 정의하고 id값을 추가한다는 것을 기억하자

보면 알겠지만, Global로 정의한 것과 Specific으로 등록한 서킷 브레이커 사이에는 이 차이점 말고는 다를게 없다.

💡 서킷 브레이커 사용하기

이제 서킷 브레이커를 서비스에 적용하는 코드는 다음과 같다.

Sample Code

@Service
@Slf4j
public class UserServiceImpl implements UserService {
    >
    private UserRepository userRepository;
    private OrderServiceClient orderServiceClient;
    private CircuitBreakerFactory circuitBreakerFactory;
    >
    @Autowired
    public UserServiceImpl(UserRepository userRepository, 
                          OrderServiceClient orderServiceClient,
                          CircuitBreakerFactory circuitBreakerFactory) {
        this.userRepository = userRepository;
        this.orderServiceClient = orderServiceClient;
        this.circuitBreakerFactory = circuitBreakerFactory;
    }
    >
    @Override
    public UserDto getUserByUserId(String userId) {
        UserEntity userEntity = userRepository.findByUserId(userId);
>
        if (userEntity == null)
            throw new UsernameNotFoundException("User not found");
>
        UserDto userDto = new ModelMapper().map(userEntity, UserDto.class);
>
        log.info("Before call orders microservice");
        List<ResponseOrder> ordersList = new ArrayList<>();
        >
        // CircuitBreaker 사용
        CircuitBreaker circuitBreaker = circuitBreakerFactory.create("circuitBreaker1");
        ordersList = circuitBreaker.run(() -> orderServiceClient.getOrders(userId),
                throwable -> new ArrayList<>());
>
        userDto.setOrders(ordersList);
>
        log.info("After called orders microservice");
>
        return userDto;
    }
    >
    // 다른 메서드들...
}

한가지 기억할 부분은 circuitBreakerFactory 라는 클래스를 의존성 주입받아 사용하고 있다는 것이다.

여기에는 우리가 이전에 설정한 정보들이 모두 저장된 상태이므로, 코드에서 확인할 수 있다시피 .create("Circuit Breaker ID"); 를 통해서 Circuit Breaker를 적용할 수 있다.

위 코드에서 circuitBreaker.run() 메서드의 첫 번째 인자는 실행할 코드, 두 번째 인자는 장애 발생 시 실행할 폴백 함수이다.

즉, 오더 서비스 호출이 실패하면 빈 리스트를 반환하도록 설정했다.

위 코드를 통해 어떻게 서킷 브레이커를 설정하고, 어떻게 호출해서 사용하는지를 알아두면 괜찮을 것 같다.

OUTRO

이번 포스팅에서는 마이크로서비스 아키텍처에서 회복성을 확보하기 위한 서킷 브레이커 패턴에 대해 알아보았다.

try-catch를 이용한 기본적인 오류 처리부터 Resilience4j를 활용한 서킷 브레이커 구현까지 다양한 방법을 살펴봤다.

서킷 브레이커 패턴은 MSA 환경에서 한 서비스의 장애가 다른 서비스로 전파되는 것을 방지하고, 사용자에게 더 나은 경험을 제공하는 중요한 패턴이다.

마이크로서비스 아키텍처를 설계할 때는 기능 구현뿐만 아니라 이런 회복성 패턴도 함께 고려하는 것이 중요하다는 것을 기억하자 👊

이전 포스팅에서는 Sink Connector만 사용해서 Kafka 토픽에 데이터를 저장하면 DB에 자동 저장되도록 구현을 해봤다.

이번 포스팅에서는 간단하게 Source Connector를 사용해보는 포스팅을 작성해보려고 한다 👀

1. Source Connecotor 사용 이유?

이전 포스팅에서 작성한 내용과 같이 Sink Connector만 사용해도 우리가 원하는 작업을 충분히 수행할 수 있다.

사용자가 주문을 요청하면 주문 정보를 Kafka Topic에 저장하도록 Producer 코드를 작성하고, Sink Connector가 Topic에서 변경 사항이 발생하면 DB에 데이터를 저장하는 식이다.

당연히 각 요청은 Kafka Topic에 저장되기 때문에 비동기 방식으로 데이터를 DB에 저장할 수 있다.

그렇다면 이와 같은 구조에서 Source Connector를 어떻게 사용할 수 있고, 만약 사용한다면 왜 Source Connector를 사용하는걸까?

💡 구조도

필자가 생각하는 구조는 다음과 같다.

만약, Catalog-Service가 SpringBoot 프레임워크 기반의 코드가 아닌 다른 언어로 작성된 API 서비스라고 생각해보자

여기서 개발자는 Catalog 정보는 중요한 정보라고 판단하기 때문에, 동기방식으로 JPA를 사용하여 DB에 데이터를 저장한다고 가정해보자

이때, 위 구조도에서 보다시피 Source Connector는 DB에서 변경된 내용을 감지하여 Kafka의 토픽으로 메세지를 가져온다.

여기서 만약, 개발자가 원한다면 토픽에 가져온 메세지를 이용하여 Order-Service와 관련된 DB에 무언가 작업을 진행할수도 있을 것이다.

이처럼, Source Connector는 특정 대상(ex. DB)에서 변화가 발생하면 Kafka Topic으로 메세지를 전송해주는 역할을 수행할 수 있으며, Sink Connector와 조합하여 다른 서비스와 연관된 여러가지 작업을 수행할 수 있을 것이다.

💡 양방향 구조

방금 가정한 내용처럼, Source Connector와 Sink Connector를 같이 사용하여 변화를 계속 감지하고 이를 기반으로 업데이트를 진행하는 구조를 양방향 구조 라고 한다.

이러한 구조를 채택한다면, 데이터 동기화를 자동화시킬 수 있다.

즉, 한쪽 DB의 변경이 다른 DB에도 자동으로 반영되는 방식으로 자동화를 구현할 수 있다는 장점이 있다.

또한, DB를 직접 수정하는 관리 도구나 백오피스 시스템이 있을 때, 그 변경사항을 마이크로서비스에 전파할 수 있을 것이다.

당연히 DB 동기화를 진행한다면, 서비스가 일시적으로 다운되어도 이전 작업 내용을 빠르게 복구할 수 있다는 장점이 있을 것이다.

2. Source Connector 사용해보기

필자는 이번 포스팅을 통해 간단하게 Source Connector를 등록해보고 동작하는 과정을 살펴보려고 한다.

우선, [LG CNS AM Inspire Camp 1기] MSA (6) - Kafka를 이용하여 MSA 데이터 일관성 문제 해결하기 (2) 에서 포스팅한 내용처럼 Kafka Connector 설치 및 JDBC 커넥터까지 다운로드 된 상태라고 판단하고 진행해보자

💡 Kafka Source Connector 등록

Sample Code

// [POST] localhost:8083/connectors 
{
 "name": "my-source-connect",
 "config": {
   "connector.class": "io.confluent.connect.jdbc.JdbcSourceConnector",
   "connection.url": "jdbc:mariadb://localhost:3307/mydb",
   "connection.user": "root",
   "connection.password": "개인 DB 비밀번호",
   "mode": "incrementing",
   "incrementing.column.name": "id",
   "table.whitelist": "users",
   "topic.prefix": "my_topic_",
   "tasks.max": "1"
 }
}

Result View

Sample Code로 제공된 JSON 데이터를 localhost:8083/connectors 로 POST 요청을 보내면 내가 지정한 Source Connector가 등록된다.

당연히 Kafka Connector가 켜져있는 상태여야 한다.

이후, 사진 처럼 등록한 커넥터의 상태를 확인했을 때, connector 와 tasks 모두 RUNNING 이 떠야 한다.

만약, Running이 뜨지 않았다면 DB가 제대로 동작하고 있는지, 아이디 비밀번호는 맞는지, 오타는 없었는지 등등.. 로그를 직접 확인하면서 에러를 잡아야한다.

이제 JSON으로 보낸 데이터를 한번 살펴보자

mode: "incrementing"

• 증가 방식으로 데이터 변경 감지
• 즉, ID 값이 증가하는 새 레코드를 감지

incrementing.column.name: "id"

• 증분 변경을 감지할 컬럼 이름

table.whitelist: "users"

• 모니터링할 테이블 이름

topic.prefix: "my_topic_"

• 생성될 Kafka 토픽의 접두사
• 따라서, 실제 토픽은 "my_topic_users"가 된다.

tasks.max: "1"

• 최대 태스크 수 (병렬 처리 정도)

만약, 여기서 감지해야할 대상 토픽인 my_topic_users 가 없다면 자동으로 생성된다.

💡 Users 테이블에서 쿼리 날려보기

사진과 같이 user 테이블에서 쿼리를 날려보자

Result View

{
 "schema": {
   "type": "struct",
   "fields": [
     {
       "type": "int32",
       "optional": false,
       "field": "id"
     },
     {
       "type": "string",
       "optional": true,
       "field": "user_id"
     },
     {
       "type": "string",
       "optional": true,
       "field": "name"
     }
   ],
   "optional": false,
   "name": "users"
 },
 "payload": {
   "id": 1,
   "user_id": "test_id1",
   "name": "TEST_USER_01"
 }
}

쿼리를 요청하면 my_topic_users 토픽이 생성되고, 해당 토픽에는 위 사진과 같이 메세지가 들어온다.

당연히 이전에 Producer 코드를 작성하면서 살펴봤던 포맷과 동일하게 schema와 payload 부분으로 나뉘어서 메세지가 등록되는 모습을 볼 수 있다!

이제 개발자가 원한다면 이 메세지를 이용해서 다른 DB에 데이터를 동기화시키는 등의 작업을 추가할 수 있을 것이다.

OUTRO

이번 포스팅에서는 간단하게 Source Connector를 등록하고 사용하는 과정을 정리해봤다.

필자가 진행하는 실습 코드에서는 Source Connector를 사용하지 않았기 때문에 직접 DB에 쿼리를 날리고, 토픽에 메세지가 등록되는 과정을 살펴봤다.

이렇게 Source Connector와 Sink Connector를 함께 활용하면 다양한 시스템 간의 데이터 동기화를 효과적으로 구현할 수 있다.

특히 마이크로서비스 아키텍처에서 데이터 일관성 문제를 해결하는 강력한 방법이 될 수 있으니 알아두자 👊

이전 포스팅에서는 Catalog Service에 Kafka를 적용하는 과정을 살펴봤다.

현재 진행과정을 간단하게 리마인드해보면 Kafka 도커 컨테이너를 9092 포트에 매핑해서 띄워둔 상태이고, Kafka를 사용하기 위한 명령어들을 다운로드 받은 상태이다.

이번 포스팅에서는 Order Service에 Kafka가 어떻게 적용되고 있는지 코드를 살펴보고 Kafka Connect를 이용해서 DB에 데이터가 자동으로 저장되도록 해보자 👀

1. Kafka 사용 이유

우선 목표부터 설정하면 다음과 같다.

위 구조는 API 통신 포스트에서 사용했던 구조인데, 현재 구조는 각 서비스마다 각기 다른 DB를 갖고 있다.

따라서, 주문 내역을 조회할 때마다 각 DB에 저장된 데이터를 보여주기 때문에 조회할 때마다 결과가 달라지는 문제가 있었다.

이를 해결하기 위해 하나의 DB를 사용할 수 있지만, 단순히 하나의 DB를 사용한다면 병목현상이 생겨 성능 저하가 발생하기 때문에 중간에 메세지 브로커인 Kafka를 사용하기로 결정했다.

따라서, 현재 필자가 만들려는 구조는 위 사진과 같다.

중간에 메세지 브로커인 Kafka를 이용해서 각 서비스에서 들어오는 메세지들을 토픽 단위로 적절하게 묶어서 관리하고자 한다.

이후, orders 토픽에 들어있는 메세지들을 DB에 넣고 메세지가 들어올 때마다 중간에 위치한 Sink Connector가 하나의 DB와 동기화 작업을 수행하도록 할 예정이다.

2. Kafka 설정하기 - Order Service

이전 포스팅에서 Order Service는 사용자가 주문한 내역(메세지)를 토픽에 저장하는 Producer의 역할을 수행한다고 정리했다.

따라서, Order Service에서는 Catalog Service에서 적용한 Consumer 설정이 아닌 Producer 설정을 진행해보자

💡 Kafka 설정 추가

우선 코드를 살펴보면 다음과 같다.

Sample Code

@EnableKafka
@Configuration
public class KafkaProducerConfig {
    @Bean
    public ProducerFactory<String, String> producerFactory() {
        Map<String, Object> properties = new HashMap<>();
        properties.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        properties.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class);
        properties.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class);
>
        return new DefaultKafkaProducerFactory<>(properties);
    }
>
    @Bean
    public KafkaTemplate<String, String> kafkaTemplate() {
        return new KafkaTemplate<>(producerFactory());
    }
}

Catalog-Service의 ConsumerConfig와 거의 유사한 모습을 보여준다.

다만, 설정 내용중에서 KEY_SERIALIZER_CLASS_CONFIG, VALUE_SERIALIZER_CLASS_CONFIG 는 StringDeserializer.class 가 아니라 StringSerializer.class 를 사용하고 있다.

즉, 전송가능한 바이트 배열로 바꾸는 데이터가 String임을 의미한다.

간단히 정리하면 다음과 같다.

직렬화 / 역직렬화 Producer : String → Byte 배열 (직렬화) 카프카 토픽에 Byte 배열 저장 Consumer : Byte 배열 → String (역직렬화)

또한, 빈으로 등록된 객체가 ConsumerFactory 가 아니라 ProducerFactory 임을 기억하자

💡 Kafka Producer - catalog 토픽

Order Service는 Producer 역할을 수행한다고 언급한 바 있다.

그렇다면 주문 내역 메세지를 단순히 하나의 토픽에만 발행하면 될까?

Kafka의 구조상 파티션 하위에 여러개의 토픽을 가질 수 있고, 여러개의 토픽에 메세지를 넣을 수 있다.

즉, 용도가 다르다면 다른 토픽을 사용하는 것이 유지보수에 더 좋을 것이다.

따라서, 주문내역을 DB에 저장할 orders 토픽과 이전 포스팅에서 살펴봤던 example-catalog-topic 2개에 주문 내역 메세지를 넣어주려고 한다.

여기서는 example-catalog-topic 에 메세지를 넣어주는 Producer 코드를 다뤄보려고 한다.

우선 코드를 살펴보자

Sample Code

@Service
@Slf4j
public class KafkaProducer {
    private KafkaTemplate<String, String> kafkaTemplate;
>
    @Autowired
    public KafkaProducer(KafkaTemplate<String, String> kafkaTemplate) {
        this.kafkaTemplate = kafkaTemplate;
    }
>
    public OrderDto send(String topic, OrderDto orderDto) {
        ObjectMapper mapper = new ObjectMapper();
        String jsonInString = "";
        try {
            jsonInString = mapper.writeValueAsString(orderDto);
        } catch(JsonProcessingException ex) {
            ex.printStackTrace();
        }
>
        kafkaTemplate.send(topic, jsonInString);
        log.info("Kafka Producer sent data from the Order microservice: " + orderDto);
>
        return orderDto;
    }
}

KafkaProducer는 단순하게 토픽에 데이터를 넣는 역할을 수행한다.

보다시피 Producer는 KafkaTemplate 를 의존성 주입받아 구현 한다.

간단하게 send 메서드를 살펴보면, topic 이름과 topic에 저장할 데이터인 OrderDto를 전달받는다.

과정에서 보다시피 직렬화를 String으로 진행하기 때문에 OrderDto를 String으로 변환한 이후, 이전에 주입받은 KafkaTemplate 을 사용하여 메세지를 발행한다.

send 메서드에서 OrderDto를 반환하고 있는데, void를 사용해도 로직 자체는 무관하다!

💡 Kafka Producer - orders 토픽

방금 설명한 것과 같이 orders 토픽에도 orderDto 메세지를 넣어줘야 한다.

다시말하지만 orders 토픽에 저장된 메세지는 DB에 저장하기 위해 사용되는 데이터이다.

우선 Producer 코드를 살펴보자

Sample Code

@Service
@Slf4j
public class OrderProducer {
    private KafkaTemplate<String, String> kafkaTemplate;
>
    List<Field> fields = Arrays.asList(
    new Field("string", true, "order_id"),
            new Field("string", true, "user_id"),
            new Field("string", true, "product_id"),
            new Field("int32", true, "qty"),
            new Field("int32", true, "unit_price"),
            new Field("int32", true, "total_price"));
    Schema schema = Schema.builder()
            .type("struct")
            .fields(fields)
            .optional(false)
            .name("orders")
            .build();
>
    @Autowired
    public OrderProducer(KafkaTemplate<String, String> kafkaTemplate) {
        this.kafkaTemplate = kafkaTemplate;
    }
>
    public OrderDto send(String topic, OrderDto orderDto) {
        Payload payload = Payload.builder()
                .order_id(orderDto.getOrderId())
                .user_id(orderDto.getUserId())
                .product_id(orderDto.getProductId())
                .qty(orderDto.getQty())
                .unit_price(orderDto.getUnitPrice())
                .total_price(orderDto.getTotalPrice())
                .build();
>
        KafkaOrderDto kafkaOrderDto = new KafkaOrderDto(schema, payload);
>
        ObjectMapper mapper = new ObjectMapper();
        String jsonInString = "";
        try {
            jsonInString = mapper.writeValueAsString(kafkaOrderDto);
        } catch(JsonProcessingException ex) {
            ex.printStackTrace();
        }
>
        kafkaTemplate.send(topic, jsonInString);
        log.info("Order Producer sent data from the Order microservice: " + kafkaOrderDto);
>
        return orderDto;
    }
}

@Data
@AllArgsConstructor
public class KafkaOrderDto implements Serializable {
    private Schema schema;
    private Payload payload;
}

@Data
@Builder
public class Schema {
    private String type;
    private List<Field> fields;
    private boolean optional;
    private String name;
}

@Data
@Builder
public class Payload {
    private String order_id;
    private String user_id;
    private String product_id;
    private int qty;
    private int unit_price;
    private int total_price;
}

마찬가지로 KafkaTemplate 을 의존성 주입받아 사용하고 있다.

여기서 한가지 차이점은 별도의 send 메서드에서 kafkaOrderDto 를 별도로 생성한 이후, 이를 String으로 만들고 있다.

그렇다면 왜 KafkaOrderDto 를 중간에 만들어주는걸까?

💡 Kafka Schema와 Payload 구조

예시 코드에서 볼 수 있듯이, orders 토픽에 메시지를 보낼 때 schema와 payload를 포함한 구조를 사용하고 있다.

이는 Kafka Connect와 Kafka Connect Sink Connector가 데이터를 처리할 때 주로 사용하는 정해진 형식이다.

이렇게 Kafka Connect가 정해진 형식을 사용하는 이유는 스키마를 통해 데이터 형식의 유효성을 검증할 수 있기 때문이다.

또한, Kafka Connect가 자동으로 데이터베이스 테이블 구조에 매핑할 수 있도록 하기 위해서 schema와 payload를 사용한다.

여기서 PayLoad와 Schema를 살펴보면 다음과 같다.

Payload

• 실제 데이터 값을 포함하며, 데이터베이스 테이블의 컬럼명과 정확히 일치하는 필드명을 사용해야 한다.
• 예시 코드에서 Payload 클래스의 필드들(order_id, user_id, product_id 등)이 실제 DB 테이블의 컬럼명과 일치한다.

Schema

• Kafka Connect가 데이터 타입을 이해하고 데이터베이스 스키마와 매핑하는 데 사용된다.
• type: 주로 "struct"를 사용하여 구조화된 데이터임을 나타낸다.
• fields: 각 필드의 데이터 타입과의 관계를 정의한다. 필드를 구성하는 리스트는 DB 테이블의 컬럼과 일치시킨다.
• name: 주로 대상 테이블명과 일치시킨다.

조금 더 나중에 살펴보겠지만, Kafka Connector에서 Sink를 추가할 때 JSON 형태로 POST 요청을 보낸다.

그때 사용하는 JSON의 프로퍼티 중에서 auto.create 와 auto.evolve 에서 정의된 스키마를 활용할 수 있다.

💡 Kafka Producer 사용

Kafka Producer는 로직 처리 과정에서 호출하여 사용하면 된다.

우리는 사용자가 주문을 했을 때 Kafka 토픽에 메세지를 저장하면 되기 때문에 createOrder 로직 내부에서 호출하면 된다.

Sample Code

@PostMapping("/{userId}/orders")
public ResponseEntity<ResponseOrder> createOrder(@PathVariable("userId") String userId,
                                                 @RequestBody RequestOrder orderDetails) {
    log.info("Before add orders data");
    ModelMapper mapper = new ModelMapper();
    mapper.getConfiguration().setMatchingStrategy(MatchingStrategies.STRICT);
>
    OrderDto orderDto = mapper.map(orderDetails, OrderDto.class);
    orderDto.setUserId(userId);
    orderDto.setOrderId(UUID.randomUUID().toString());
    orderDto.setTotalPrice(orderDetails.getQty() * orderDetails.getUnitPrice());
    ResponseOrder responseOrder = mapper.map(orderDto, ResponseOrder.class);
>
    /* send this order to the kafka */
    kafkaProducer.send("example-catalog-topic", orderDto);
    orderProducer.send("orders", orderDto);
>
    log.info("After added orders data");
    return ResponseEntity.status(HttpStatus.CREATED).body(responseOrder);
}

이제 example-catalog-topic 에 저장된 메세지는 catalog-service에서 리스닝하고 있는 메서드가 동작하여 JPA기반으로 DB를 업데이트할 것이다.

반면, orders 토픽에 들어있는 메세지는 아직 활용되지 않고 있다.

이제부터 orders 토픽에 있는 메세지를 기반으로 DB를 자동으로 업데이트하도록 Kafka Connector를 사용해보자

3. Kafka Connector 사용하기

이전 포스팅에서 살펴봤던 이미지를 다시한번 확인해보자

여기서 우리는 Kafka Cluster를 기준으로 데이터를 이동시키기 위해서는 Kafka Connect를 사용한다고 했다.

Kafka Connect를 사용하기 위해 우리는 confluent.io에서 현재 Kafka 버전에 맞는 Connector를 설치해야 한다.

호환 버전 사이트에 접근해서 자신이 사용하는 Kafka 버전과 호환되는 Connnector를 설치해야 한다.

필자는 kafka:latest 를 사용하기 때문에 7.9 버전을 다운로드해서 사용했다

💡 Kafka Connector 설치 (1)

사이트에 접근해서 다운로드해도 상관없지만, curl 명령어를 사용해서 간단하게 다운로드 해보자

◉ 명령어 - Kafka Connector 명령어 다운 curl -O http://packages.confluent.io/archive/7.9/confluent-community-7.9.0.tar.gz

◉ 명령어 - 압축 해제 tar xvf confluent-community-7.9.0.tar.gz

압축해제를 진행한 이후, 디렉토리를 확인해보면 이전에 Kafka에서 다운로드 받은 것처럼 쉘 스크립트가 저장된 모습을 확인할 수 있다.

💡 Kafka Connector 설치 (2)

이후, Kafka Connector Sink에서 사용할 JDBC Connector를 다운로드 받아야 한다.

여러가지 커넥터가 있겠지만, 필자는 DB에 데이터를 저장하기 위한 목적으로 사용하기 때문에 JDBC Connector를 설치한다.

JDBC Connector 설치 사이트에서 다운로드 받으면 된다.

필자는 Self-Hosted로 다운로드 받았다.

💡 Kafka Connector 연결 (1)

이전에 압축해제하면서 설치했던 confluent-7.9.0 디렉토리에서 다음 파일을 수정하자

수정 해야하는 파일 confluent-7.9.0/etc/kafka/connect-distributed.properties

해당 파일을 열고 맨 마지막으로 스크롤을 내리면 path를 설정하는 부분이 있다.

여기서 path를 우리가 방금 설치한 JDBC Connector/lib 경로로 수정하자

💡 Kafka Connector 연결 (2)

다음으로 필자는 orders 토픽에 저장된 데이터를 MariaDB에 저장할 예정이기 때문에 MariaDB 드라이버를 /share/java/kafka/경로에 저장해야 한다.

maven으로 프로젝트를 한번이라도 빌드했다면, m2 라는 디렉토리 하위에 사용한 DB 드라이버가 존재한다.

맥 OS를 사용한다면 open ~/m2 명령어를 입력해서 해당 디렉토리를 열고, ~/.m2/repository/org/mariadb/jdbc/mariadb-java-client/2.7.2/mariadb-java-client-2.7.2.jar 경로에 해당하는 드라이버를 복사하자

다음으로 커넥터 명령어가 있는 디렉토리에서 confluent-7.9.0/share/java/kafka 경로에 이전에 복사한 드라이버를 붙여넣기 해주면 된다.

💡 Kafka Connector 실행

이제 confluent-7.9.0/ 으로 이동하고 다음 명령어를 입력하자

◉ 커맨드 - Kafka Connector 실행 ./bin/connect-distributed ./etc/kafka/connect-distributed.properties

두 명령어를 동시에 실행시키기 때문에 /confluent-7.9.0 에서 명령어를 입력해야 한다.

이후, 토픽 리스트를 확인해보면 connect 관련 토픽이 3개 생긴 모습을 볼 수 있다.

위 사진과 같이 8083포트의 /connector-plugins 엔드포인트로 get 요청을 날리면 현재 등록된 커넥터들을 확인할 수 있다.

여기서 8083은 Kafka Connector가 자체적으로 제공해주는 포트이다.

화면에서 확인할 수 있다시피, 방금 등록한 JdbcSinkConnector와 JdbcSourceConnector가 제대로 등록된 모습을 볼 수 있다.

💡 Kafka Connector 등록

이제 위 커넥터를 이용해서 우리가 사용할 DB 정보를 세팅하여 커넥터를 등록해보자

Sample Code

{
    "name" : "my-order-sink-connect",
    "config" : {
        "connector.class" : "io.confluent.connect.jdbc.JdbcSinkConnector",
        "connection.url" : "jdbc:mysql://127.0.0.1:3307:mydb",
        "connection.user" : "root",
        "connection.password" :"개인 DB 비밀번호",
        "auto.create": "true",
        "auto.evolve" : "true",
        "delete.enabled" : "false",
        "tasks.max" : "1",
        "topics" : "orders"
    }
}

사진과 같이 8083 포트의 /connectors 엔드포인트로 위 JSON 데이터를 POST 날려주면 우리가 사용할 Sink Connector가 등록된다.

JSON 포맷에서 config쪽을 살펴보면 connector 관련 설정을 추가해주고 있다.

여기서 눈여겨봐야할 것은 topics 부분인데, 우리가 사용할 orders 토픽에서 메세지를 Sink 하겠다는 의미이다.

참고로 생성한 Connector를 삭제하길 원한다면 localhost:8083/connectors/my-order-sink-connect 엔드포인트에 DELETE 메서드로 요청을 보내면 된다.

4. Kafka 실습

이제 Connector 연결까지 완료했으니 실제로 서비스 인스턴스를 여러개 띄운 상태에서 실습을 진행해보자

💡 Order Service 실행

우선 실습을 위해 Order Service 인스턴스를 2개 띄우자

Gateway 설정에서 라운드 로빈 방식으로 라우팅이 진행되도록 설정했기 때문에, 각 요청은 서비스 인스턴스를 번갈아가면서 사용할 것이다.

💡 주문 요청

주문 요청

위 사진은 order-service에 catalog-001, 002, 003 주문을 3번 넣는 과정이다.

💡 orders 토픽 확인

사진이 잘 보일지 모르겠지만, 각각 요청한 catalog-001, 002, 003이 orders 토픽에 제대로 저장된 모습을 볼 수 있다.

(위에있는 메세지는 테스트하면서 생긴 더미 데이터다 😅)

💡 DB 확인

사진과 같이 주문이 자동으로 들어온 모습을 볼 수 있다!

💡 주의사항

필자는 해당 실습에서 Sink Connector만 등록해서 단방향 처리 (Kafka Topic -> DB)만 구현했다.

만약, JDBC Source Connector를 사용한다면 DB에서 변경사항이 감지되면 Kafka Topic으로 가져오는 기능도 구현할 수 있을 것이다.

하지만, 양방향을 구현하게 될 경우에는 무한 루프를 조심해야한다는 것을 기억하자

이 부분은 다음에 시간되면 별도의 포스팅으로 작성하도록 하겠다!

OUTRO

이번 포스팅에서는 Kafka Connector를 세팅하는 방법과 Producer 코드를 어떻게 작성해야하는지까지 살펴봤다.

실제로 필자가 테스트하는 과정에서는 Connector 버전이 맞지 않아서 마지막 DB에 데이터가 저장되지 않는 문제가 있었다.

이 부분에서 Kafka와 Connector 버전의 호환성이 중요하다는 것을 절감했다..😅

그래서 다시 처음부터 Connector를 설정했는데 여러번 하다보니까 막상 어려운 부분은 하나도 없었다.

한 번 익숙해지면 설정 과정이 꽤 직관적이라는 걸 알 수 있었다.

2편의 포스팅을 통해서 Kafka Consumer, Producer를 구성하는 방법과 이를 통해 데이터 일관성을 유지하는 방법에 대해서 기억하면 좋겠다!

특히 마이크로서비스 환경에서 각 서비스의 독립성을 유지하면서도 데이터 정합성을 확보하는 패턴으로 큰 도움이 될 것이다 👊

이전 포스팅에서 마이크로서비스 간 통신 방법에 대해 알아봤다.

특히 여러 서비스 인스턴스를 운영할 때 발생하는 데이터 일관성 문제를 다뤘는데, 이번에는 Kafka를 활용해 이 문제를 어떻게 해결할 수 있는지 알아보려고 한다 👀

1. 데이터 일관성 문제 리마인드

먼저 이전 포스팅에서 살펴본 문제를 다시 생각해보자

여러 인스턴스로 주문 서비스를 운영할 때, 각 인스턴스는 자체 DB를 가지게 된다.

이로 인해 사용자의 주문이 여러 DB에 분산되어 저장되면서 데이터 일관성 문제가 발생한다.

사용자가 총 3개의 주문을 했지만, 서비스를 호출할 때마다 로드 밸런싱에 의해 다른 인스턴스로 요청이 가기 때문에 모든 주문 정보를 한 번에 조회하기 어렵다.

이 문제를 해결하기 위해 메시지 큐를 활용한 이벤트 기반 아키텍처를 도입할 수 있다.

오늘은 그 중에서도 Apache Kafka를 활용한 방법을 알아보자.

2. Apache Kafka란?

Apache Kafka는 LinkedIn에서 개발한 분산 스트리밍 플랫폼이다.

여러 서비스 간에 메시지를 비동기적으로 주고받을 수 있게 해주며 RabbitMQ에 비해 높은 처리량을 보여준다.

💡 Kafka의 주요 개념

Topic : 메시지가 저장되는 카테고리 Producer : 토픽에 메시지를 발행하는 어플리케이션 Consumer : 토픽에서 메시지를 구독하는 어플리케이션 Broker : Kafka 서버 Partition : 토픽을 분할하여 병렬 처리를 가능하게 하는 단위

Kafka는 메시지를 순서대로 저장하고, 소비자가 원하는 시점부터 메시지를 읽을 수 있는 특징이 있다.

이러한 특성 때문에 MSA 환경에서 이벤트 소싱(Event Sourcing) 패턴을 구현하는 데 적합하다.

위 개념을 조금 더 자세히 살펴보면 다음과 같다.

Kafka는 공식 사이트에서 최소 3개 이상의 브로커를 사용하길 권장하고 있다.

왜냐하면 n개의 Broker 중에서 1대는 Controller의 기능을 수행하기 때문이다.

Controller 역할

• 각 Broker에게 담당 파티션 할당
• Broker 정상 동작 모니터링

이제 이렇게 여러개의 Broker로 구성된 Kafka Cluster는 Kafka를 구독하는 Kafka-Client Application과 데이터를 주고받게 된다.

Kafka-Client는 간단하게 Kafka Cluster와 데이터를 주고받는 대상이라고 보면 된다.

(필자가 진행하는 실습에서는 각 서비스가 Kafka-Client가 된다.)

💡 Kafka 설치 (1) - 명령어 다운

필자는 도커를 이용하여 Kafka 컨테이너를 띄워서 사용할 예정이다.

우선 Kafka 컨테이너에 명령을 보내기 위해서는 관련 쉘 스크립트를 다운받아야 한다.

Kafka 명령어 설치 사이트에서 다음 사진과 같이 Binary를 다운로드 받도록 하자

다운로드가 완료되면 여러 쉘 스크립트가 저장된 폴더가 하나 생긴다.

우리는 이제 이 폴더에서 쉘 스크립트를 실행하여 명령어를 실행할 예정이다.

💡 Kafka 설치 (2) - 컨테이너 실행

우선 Docker Hub에서 Kafka 이미지를 pull해야 한다.

필자는 latest 버전으로 pull을 받았다.

이후, 명령어를 입력하여 컨테이너를 실행시키자

Kafka 컨테이너 실행 명령어 docker run -d -p 9092:9092 --name broker apache/kafka:latest

Broker라는 이름으로 컨테이너를 실행시켰다.

Kafka는 내부적으로 9092 포트를 사용하기 때문에 localhost의 9092 포트와 바인딩을 시켜줬다.

3. Kafka 사용해보기

우선 지금 작성하는 내용은 Kafka를 실행시켜보고 동작을 확인하기 위함이다.

(프로젝트에 Kafka를 적용하는 부분은 좀있다가 다룰 예정이다.)

이전에 다운로드 받은 Kafka 쉘 스크립트가 위치한 디렉토리의 /bin 으로 이동하자

그리고 다음과 같은 명령어를 입력하면 토픽을 생성할 수 있다.

여기서 필자는 Mac OS를 사용하기 때문에 Window와는 명령어가 다를 수 있다.

사진과 같이 여러 명령어가 있는 모습을 볼 수 있다.

이제 메세지가 저장될 토픽을 다음 커맨드를 입력하여 실행해보자

💡 토픽 생성 및 확인

◉ 명령어 - 토픽 생성 ./kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092 --partitions 1

◉ 명령어 - 토픽 리스트 확인 ./kafka-topics.sh --bootstrap-server localhost:9092 --list

사진과 같이 quickstart-events 토픽이 생성되었음을 확인할 수 있다.

💡 토픽에 메세지 전송하기

◉ 명령어 - 메세지 발행 ./kafka-console-producer.sh --bootstrap-server localhost:9092 --topic quickstart-events

◉ 명령어 - 메세지 확인 ./kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic quickstart-events --from-beginning

아마 잘 안보일것 같긴한데, 아래는 메세지 발행 커맨드를 입력한 창이고 좌상단 커맨드창은 메세지 확인 창을 띄워놓은 상태이다.

실제로 메세지 발행 커맨드를 입력하여 가상 쉘 스크립트로 접근하고 메세지를 입력하면 위쪽 상단에서도 실시간으로 입력한 데이터가 저장되는 모습을 볼 수 있다.

여기서 메세지 확인 커맨드에서 --from-beginning 옵션은 메세지 브로커에 저장된 내용을 처음부터 읽어오겠다는 것을 의미한다.

만약 특정 범위부터 읽어오고 싶다면 다음과 같이 오프셋을 추가해주면 된다.

◉ 명령어 - 메세지 확인 - 특정 라인부터 ./kafka-console-consumer.sh --bootstrap-server localhost:9092 --partition 0 --offset 1 --topic quickstart-events

메세지 브로커에는 Hello, World 와 Hi, There! 메세지가 들어있으나 Hi, There! 만 확인되는 모습을 볼 수 있다.

4. Kafka 적용하기 - Catalog Service

이제부터 Kafka를 기존에 작업하던 프로젝트에 적용해보자

우선 구조를 보면 다음과 같다.

Kafka Cluster에 접근하기 위해서는 Kafka Connect의 Source, Sink가 필요하다.

간단하게 Source는 데이터를 Kafka Cluster에 집어넣을 때 사용되고, Sink는 Kafka Cluster에서 가져올 때 사용된다.

필자가 진행하는 프로젝트에서는 다음과 같이 동작해야 한다.

동작 순서

1. User가 상품을 주문한다.
2. 주문 내역이 Order-Service를 통해 Kafka Cluster에 메세지로 저장된다.
3. 주문 내역에 맞춰서 Catalog-Service에서 재고 수량을 차감한다.
4. Kafka Cluster에 저장된 주문 내역이 하나의 DB에 자동으로 저장된다.

즉, 위에서 설명한 내용을 참고했을 때, Kafka Cluster를 기준으로 Catalog-Service는 Consumer, Order-Service는 Producer가 될 것이다.

왜냐하면, Order-Service에서 주문 정보를 생성해서 Kafka Cluster에 메세지를 발행할 것이기 때문에 Producer로 볼 수 있다.

마찬가지로 Kafka Cluster에서 메세지를 가져와서 재고 수량을 차감시킬 것이기 때문에 Catalog-Service는 Consumer로 볼 수 있다.

우선, 이 개념을 이해하고 나머지 실습을 진행하는 것이 중요하다!

위와 같이 Kafka 의존성을 추가해서 프로젝트를 설정하자

💡 Kafka 설정 추가 - Catalog Service

다음으로 Kafka를 사용하기 위해 필요한 설정 정보를 추가해주자

우선 코드를 살펴보면 다음과 같다.

Sample Code

@EnableKafka
@Configuration
public class KafkaConsumerConfig {
    @Bean
    public ConsumerFactory<String, String> consumerFactory() {
        Map<String, Object> properties = new HashMap<>();
        properties.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        properties.put(ConsumerConfig.GROUP_ID_CONFIG, "consumerGroupId");
        properties.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
        properties.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
        properties.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
>
        return new DefaultKafkaConsumerFactory<>(properties);
    }
>
    @Bean
    public ConcurrentKafkaListenerContainerFactory<String, String> kafkaListenerContainerFactory() {
        ConcurrentKafkaListenerContainerFactory<String, String> kafkaListenerContainerFactory
                = new ConcurrentKafkaListenerContainerFactory<>();
        kafkaListenerContainerFactory.setConsumerFactory(consumerFactory());
>
        return kafkaListenerContainerFactory;
    }
}

해당 코드는 Catalog-Service에서 Kafka Consumer 설정을 진행하는 코드이다.

중요한 부분을 정리하면 다음과 같다.

@EnableKafka

• 이 어노테이션은 Spring Kafka 기능을 활성화하는 어노테이션이다.
• 이후에 살펴볼 @KafkaListener 어노테이션을 사용할 수 있게 해준다.

@Configuration

• 스프링 설정 클래스임을 의미한다.

BOOTSTRAP_SERVERS_CONFIG

• Kafka 브로커의 주소를 설정한다.
• 필자는 도커 컨테이너로 Kafka를 띄워놨는데 9092로 포트바인딩을 진행했다.
• 따라서, localhost:9092 로 설정한다.

GROUP_ID_CONFIG

• Consumer 그룹 ID를 설정한다.
• 여기서 같은 그룹에 속한 Consumer들은 메시지를 분산해서 처리한다.

AUTO_OFFSET_RESET_CONFIG

• Consumer가 처음 시작할 때 또는 오프셋이 없을 때 어디서부터 메시지를 읽을지 설정한다.
• earliest 는 토픽의 시작부터 읽는다는 의미이다.

KEY_DESERIALIZER_CLASS_CONFIG, VALUE_DESERIALIZER_CLASS_CONFIG

• Kafka 메시지의 키와 값을 역직렬화하는 방법을 설정한다.
• Kafka는 JVM 기반의 Scala라는 언어로 만들어져있기 때문에 Java와 호환성이 좋다.
• 여기서는 String 타입으로 역직렬화하도록 설정한다.
• 이 설정이 필요한 주된 이유는 Kafka가 바이트 배열로 메시지를 전송하기 때문이다.
• 따라서 송신자가 직렬화한 데이터를 수신자가 올바르게 해석하려면 역직렬화 방식을 지정해야 하며, 우리는 String으로 소비하겠다는 의미이다.

kafkaListenerContainerFactory() 메서드

• @KafkaListener 어노테이션이 붙은 메서드가 Kafka 메시지를 처리할 때 사용할 컨테이너 팩토리를 설정한다.
• 앞서 만든 consumerFactory를 사용하여 Consumer 속성을 설정한다.
• 마지막으로 ConcurrentKafkaListenerContainerFactory는 여러 개의 Consumer 인스턴스를 동시에 실행할 수 있게 해준다.

이제 설정이 마무리 되었으니 실제로 토픽을 리스닝하는 클래스를 만들어보자

💡 Kafka 토픽 리스닝 - Catalog Service

우선 코드를 살펴보면 다음과 같다.

Sample Code

@Service
@Slf4j
public class KafkaConsumer {
    CatalogRepository repository;
>
    @Autowired
    public KafkaConsumer(CatalogRepository repository) {
        this.repository = repository;
    }
>
    @KafkaListener(topics = "example-catalog-topic")
    public void updateQty(String kafkaMessage) {
        Map<Object, Object> map = new HashMap<>();
        ObjectMapper mapper = new ObjectMapper();
        try {
            map = mapper.readValue(kafkaMessage, new TypeReference<Map<Object, Object>>() {});
        } catch (JsonProcessingException ex) {
            ex.printStackTrace();
        }
>
        CatalogEntity entity = repository.findByProductId((String)map.get("productId"));
        if (entity != null) {
            entity.setStock(entity.getStock() - (Integer)map.get("qty"));
            repository.save(entity);
        }
    }
}

이 부분은 실제로 Kafka 토픽을 리스닝하고 변화가 감지되면 작동시킬 메서드를 정의한다.

위에서 @EnableKafka 어노테이션을 사용하여 Kafka 기능을 활성화했기 때문에 @KafkaListener 어노테이션을 사용하여 리스닝할 토픽을 지정한다.

여기서 우리는 토픽 이름을 example-catalog-topic 으로 지정할 예정이다.

다음으로 updateQty 메서드를 살펴보면 kafkaMessage라는 매개변수가 String으로 넘어오는 모습을 볼 수 있다.

그 이유는 우리가 이전에 KafkaConfig에서 역직렬화 방법을 String으로 선언했기 때문이다.

이제 해당 데이터를 가지고 Catalog DB에서 상품을 찾아보고 구매 수량에 맞춰 재고를 차감하는 로직이 작성되어 있다.

💡 주의사항

이전에 잠깐 설명했던 Kafka Connect는 실행되고 있지 않다.

즉, 위 로직은 CatalogRepository라는 JPA를 사용해서 동작하고 있는 것이다.

메세지 브로커에서 데이터 변경이 감지되면 자동으로 DB에 데이터를 저장하게끔하길 원한다면 다음 포스팅에서 다룰 Kafka Sink를 사용해야 한다.

OUTRO

분량 조절에 실패해서 아마 2개의 포스팅으로 Kafka 관련 내용을 정리해야할 것 같다.

물론, 코드를 계속 봐야겠지만 이번에 정리한 내용만으로는 아직 Kafka가 무엇인지 감이 잡히지 않을 수도 있다

그래서 다음 포스팅에서 Order Service에 적용되는 Kafka를 다시한번 살펴볼 예정이다.

이번 포스팅을 통해서 무엇을 위해 Kafka를 사용하고, Kafka는 어떻게 사용하고, 스프링 프로젝트에는 Kafka를 어떻게 적용하는지를 유념해서 다시 읽어보면 좋을 것 같다 👊

이전 포스팅에서는 Spring Cloud Config Server에 대해 알아봤다.

MSA를 채택했다면 서비스 사이에서 데이터를 주고받아야하는 경우가 대부분일 것이다.

따라서, 이번에는 MSA 환경에서 서비스 간 통신 방법에 대해 정리해보려고 한다 👀

1. 서비스 간 통신의 필요성

MSA 환경에서는 각 서비스가 독립적으로 동작하지만, 실제 비즈니스 로직을 처리하기 위해서는 서비스 간 데이터 교환이 필요하다.

예를 들어, 사용자 서비스에서 주문 정보를 조회하거나, 주문 서비스에서 상품 정보를 가져오는 등의 작업에서 서비스간의 통신이 필요할 것이다.

우리는 서비스 간 통신 방식을 크게 두 가지로 나눌 수 있다

동기 방식

• HTTP 기반의 REST API 호출 (REST Template, Feign Client)

비동기 방식

• 메시지 브로커를 사용한 통신 (AMQP, Kafka 등)

이번 포스팅에서는 우선 동기 방식의 통신 방법을 중심으로 알아보려고 한다.

2. RestTemplate을 이용한 통신

가장 기본적인 서비스 간 통신 방법은 RestTemplate을 사용하는 것이다.

Spring에서 제공하는 RestTemplate을 사용하면 HTTP 요청을 쉽게 만들 수 있다.

우선 코드를 살펴보자

💡 RestTemplate 빈 등록

Sample Code

@Bean
public RestTemplate getRestTemplate() {
    int TIMEOUT = 5000;
>
    RestTemplate restTemplate = new RestTemplateBuilder()
            .setConnectTimeout(Duration.ofMillis(TIMEOUT))
            .setReadTimeout(Duration.ofMillis(TIMEOUT))
            .build();
>
    return restTemplate;
}

DI를 통해 쉽게 RestTemplate를 사용하기 위해 빈으로 등록한 과정이다.

빈은 어디에서 등록해도 상관없기 때문에 각자 적절한 위치에서 등록하자

💡 RestTemplate 사용 예시 (1)

Sample Code

@Service
public class UserServiceImpl implements UserService {
    >
    private final RestTemplate restTemplate;
    private final Environment env;
    >
    public UserServiceImpl(RestTemplate restTemplate, Environment env) {
        this.restTemplate = restTemplate;
        this.env = env;
    }
    >
    @Override
    public UserDto getUserByUserId(String userId) {
        // 사용자 정보 조회
        UserEntity userEntity = userRepository.findByUserId(userId);
        >
        if (userEntity == null)
            throw new UsernameNotFoundException("User not found");
        >
        UserDto userDto = new ModelMapper().map(userEntity, UserDto.class);
        >
        // 주문 서비스에서 주문 정보 가져오기
        String orderUrl = String.format("http://127.0.0.1:8000/order-service/%s/orders", userId);
        ResponseEntity<List<ResponseOrder>> orderListResponse =
                restTemplate.exchange(orderUrl, HttpMethod.GET, null,
                        new ParameterizedTypeReference<List<ResponseOrder>>() {});
        >
        List<ResponseOrder> ordersList = orderListResponse.getBody();
        userDto.setOrders(ordersList);
        >
        return userDto;
    }
}

restTemplate은 exchange 메서드를 호출하여 HTTP 통신을 진행할 수 있다.

코드를 살펴보면 orderUrl을 Order Service에서 제공하는 엔드포인트에 맞춰서 설정하고 HTTP Method 등을 설정하여 요청을 보내고 있다.

여기서 우리가 눈여겨 봐야할 것은 바로 orderUrl을 세팅하는 부분이다.

💡 RestTemplate 사용 예시 (2)

위 코드에서 발생하는 문제점은 바로 OrderUrl이 하드코딩되어있다는 것이다.

이러한 하드코딩을 피하는 방법을 생각해보면 서비스 디스커버리에 등록된 인스턴스를 찾아서 Url을 세팅해주면 될 것이다.

Eureka에서 인스턴스 정보를 뽑아서 사용하기 위해서는 다음과 같은 설정이 필요하다.

Sample Code

@Bean
@LoadBalanced
public RestTemplate getRestTemplate() {
    int TIMEOUT = 5000;
>
    RestTemplate restTemplate = new RestTemplateBuilder()
                .setConnectTimeout(Duration.ofMillis(TIMEOUT))
                .setReadTimeout(Duration.ofMillis(TIMEOUT))
                .build();
>
    return restTemplate;
}

RestTemplate을 빈으로 등록하는 과정에서 @LoadBalanced 라는 어노테이션을 추가해주면 Eureka에 등록된 서비스 이름으로 API를 호출할 수 있다!

Sample Code

@Service
public class UserServiceImpl implements UserService {
    >
    private final RestTemplate restTemplate;
    private final Environment env;
    >
    public UserServiceImpl(RestTemplate restTemplate, Environment env) {
        this.restTemplate = restTemplate;
        this.env = env;
    }
    >
    @Override
    public UserDto getUserByUserId(String userId) {
        UserEntity userEntity = userRepository.findByUserId(userId);
        >
        if (userEntity == null)
            throw new UsernameNotFoundException("User not found");
        >
        UserDto userDto = new ModelMapper().map(userEntity, UserDto.class);
        >
        // 수정된 부분
        String orderUrl = String.format(env.getProperty("order-service.url"), userId);
        ResponseEntity<List<ResponseOrder>> orderListResponse =
                restTemplate.exchange(orderUrl, HttpMethod.GET, null,
                        new ParameterizedTypeReference<List<ResponseOrder>>() {});
        >
        List<ResponseOrder> ordersList = orderListResponse.getBody();
        userDto.setOrders(ordersList);
        >
        return userDto;
    }
}

spring:
  config:
    import: optional:configserver:http://127.0.0.1:8888/

필자는 실습 과정에서 Config Server에서 참조하는 Github Repository에서 Order-Service의 URL을 정의하고 있기 때문에 위처럼 order-service.url을 환경변수에 지정해주면 된다.

지정된 URL을 살펴보면 http://ORDER-SERVICE/order-service/%s/orders 로 정의되어있는데 여기서 우리는 한가지 차이점을 기억해야 한다.

@LoadBalanced 어노테이션을 사용하면 API Gateway가 아닌 Eureka에서 직접 인스턴스를 찾아서 접근한다는 것을 기억하자

따라서, ORDER-SERVICE 는 Eureka에 등록된 인스턴스 이름을 의미한다.

뒤에 있는 /order-service/%s/orders 는 API의 엔드포인트이다.

(필자는 order-service에서 /order-service라는 prefix를 사용하고 있기 떄문에 사용하는 것이다.)

이렇게 하면 ORDER-SERVICE라는 서비스 이름으로 Eureka에 등록된 서비스를 찾아 요청을 보낸다.

여러 인스턴스가 있을 경우 로드 밸런싱도 자동으로 처리된다는 것을 기억하자!

3. FeignClient를 이용한 통신

RestTemplate보다 더 선언적이고 간편한 방법으로 Feign Client가 있다.

OpenFeign 은 Netflix에서 개발한 HTTP 클라이언트로, 인터페이스와 어노테이션만으로 HTTP API 호출을 구현할 수 있다.

우선 OpenFeign을 사용하기 위해서는 해당 의존성을 추가해야 한다.

💡 Feign Client 활성화

Sample Code

@SpringBootApplication
@EnableFeignClients
public class UserServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(UserServiceApplication.class, args);
    }
}

위 코드처럼 BootApplication에서 @EnalbeFeignClients 어노테이션을 추가하여 Feign Client를 사용하겠다는 것을 명시적으로 선언해야 한다.

💡 Feign Client 정의

Sample Code

@FeignClient(name="order-service")
public interface OrderServiceClient {
>
    @GetMapping("/order-service/{userId}/orders")
    List<ResponseOrder> getOrders(@PathVariable String userId);
}

실제 /order-service/{userId}/orders 구현부

@GetMapping("/{userId}/orders")
public ResponseEntity<List<ResponseOrder>> getOrder(@PathVariable("userId") String userId) throws Exception {
    log.info("Before retrieve orders data");
    Iterable<OrderEntity> orderList = orderService.getOrdersByUserId(userId);
>
    List<ResponseOrder> result = new ArrayList<>();
    orderList.forEach(v -> {
        result.add(new ModelMapper().map(v, ResponseOrder.class));
    });
>
    log.info("Add retrieved orders data");
>
    return ResponseEntity.status(HttpStatus.OK).body(result);
}

이처럼 @FeignClient 어노테이션을 사용하여 Feign Client를 정의할 수 있다.

여기서 어노테이션 부분에서 사용된 name 속성은 Eureka에 등록된 서비스 인스턴스의 이름을 의미한다.

다음으로 @GetMapping 주소는 해당 서비스의 API 엔트포인트를 적어주면 된다.

실제로 Order-Service에서는 ResponseEntity 로 반환하고 있지만, Feign Client는 List<ResponseOrder> 를 반환타입으로 지정하고 있다.

ResponseEntity<List<ResponseOrder>> 를 반환하는 것 사이에 불일치가 있는 것처럼 보이지만, 사실 이것은 FeignClient의 동작 방식 때문에 가능한 것이다.

컨트롤러의 실제 반환 부분

return ResponseEntity.status(HttpStatus.OK).body(result);

위처럼 컨트롤러가 실제로 ResponseEntity를 반환하더라도 Feign Client는 두가지의 편의 기능을 모두 제공한다.

응답 본문만 원하는 경우

@FeignClient(name="order-service")
public interface OrderServiceClient {
>
    @GetMapping("/order-service/{userId}/orders")
    List<ResponseOrder> getOrders(@PathVariable String userId);
}

응답 전체를 원하는 경우

@FeignClient(name="order-service", configuration = FeignErrorDecoder.class)
public interface OrderServiceClient {
>
    @GetMapping("/order-service/{userId}/orders")
    ResponseEntity<List<ResponseOrder>> getOrders(@PathVariable String userId);
}

따라서, 개발자가 응답 코드도 원한다면 ResponseEntity 타입으로 Feign Client를 정의해주면 된다.

💡 Felign Client 사용 예시

Sample Code

@Service
public class UserServiceImpl implements UserService {
    >
    private final OrderServiceClient orderServiceClient;
    >
    public UserServiceImpl(OrderServiceClient orderServiceClient) {
        this.orderServiceClient = orderServiceClient;
    }
    >
    @Override
    public UserDto getUserByUserId(String userId) {
        UserEntity userEntity = userRepository.findByUserId(userId);
        >
        if (userEntity == null)
            throw new UsernameNotFoundException("User not found");
        >
        UserDto userDto = new ModelMapper().map(userEntity, UserDto.class);
        >
        // Feign Client를 통한 주문 정보 조회
        List<ResponseOrder> ordersList = orderServiceClient.getOrders(userId);
        userDto.setOrders(ordersList);
        >
        return userDto;
    }
}

여기서 OrderServiceCLient는 Feign Client를 정의한 부분이다.

💡 에러 헨들링

서비스 사이에서 오류가 발생한 경우, 당연히 개발자는 에러를 처리해야 한다.

간단하게 try-catch 블록을 추가해서 에러를 잡아서 해결할 수도 있겠으나, Feign Client를 사용하는 경우 ErrorDecoder 를 구현하여 등록하면 된다.

우선 코드를 살펴보자

Sample Code

@Component
public class FeignErrorDecoder implements ErrorDecoder {
    Environment env;
>
    @Autowired
    public FeignErrorDecoder(Environment env) {
        this.env = env;
    }
>
    @Override
    public Exception decode(String methodKey, Response response) {
        switch(response.status()) {
            case 400:
                break;
            case 404:
                if (methodKey.contains("getOrders")) {
                    return new ResponseStatusException(HttpStatus.valueOf(response.status()),
//                            "User's orders is empty");
                           env.getProperty("order-service.exception.order-is-empty"));
                }
                break;
            default:
                return new Exception(response.reason());
        }
>
        return null;
    }
}

ErrorDecode를 상속받아서 별도의 Decoder를 구현해주면 된다.

여기서 decode 메서드를 오버라이딩하여 어떻게 처리할지를 결정하면 된다.

methodKey에는 호출한 메서드명이 들어가게 되고, response는 호출 결과를 가져온다.

(status에 접근할 수 있다.)

다음으로 이전에 구현한 Feign Client에 해당 Decoder를 등록해주면 된다.

Sample Code

@FeignClient(name="order-service", configuration = FeignErrorDecoder.class)
public interface OrderServiceClient {
>
    @GetMapping("/order-service/{userId}/orders")
    List<ResponseOrder> getOrders(@PathVariable String userId);
}

이렇게 하면 Feign Client에서 발생하는 모든 예외가 ErrorDecoder를 통해 처리된다!

서비스 간 통신에서 발생하는 다양한 오류 상황을 중앙에서 관리할 수 있어 코드가 더 깔끔해진다는 장점이 있다.

6. 분산 환경에서 발생하는 통신 문제

간단하게 서비스만 구조도에 포함하면 다음과 같은 구조를 갖는다.

즉, 여러개의 서비스 인스턴스가 생기면 각 서비스에 매핑되는 DB가 생긴다.

이렇게 되면 다음과 같은 문제가 발생할 수 있다.

우선 위 구조와 동일하게 Order-Service 인스턴스를 2개 생성해보자

다음으로 User가 Catalog-001, Catalog-002, Catalog-003 상품을 주문했다.

이후, 주문 내역 조회를 시도해보면 다음과 같은 화면을 확인할 수 있다.

처음 조회에는 Catalog-002 상품만 조회되고 있다.

다시한번 동일한 path로 주문 내역 조회 요청을 날리면 다음과 같은 결과를 볼 수 있다.

Catalog-001과 Catalog-002 상품이 조회된다.

실제로 각 서비스의 h2-console에 접근하면 다음과 같은 내용을 확인할 수 있다.

사용자 서비스에서 RestTemplate이나 Feign Client를 통해 주문 정보를 조회하면 로드 밸런싱에 의해 두 인스턴스 중 하나에만 요청이 가게 된다.

따라서 첫 번째 인스턴스로 요청이 갔다면 첫 번째와 세 번째 주문만 보이고, 두 번째 인스턴스로 요청이 갔다면 두 번째 주문만 보이게 된다.

그렇다면 이러한 문제를 어떻게 해결할 수 있을까?

이 내용은 다음 포스팅에서 다뤄보려고 한다.

OUTRO

이번 포스팅에서는 RestTemplate과 FeignClient를 사용한 동기 방식의 통신에 대해서 살펴봤다.

FeignClient를 사용할 때는 ErrorDecoder를 통해 효율적인 예외 처리가 가능하다는 점도 알아봤다.

하지만, 여러 서비스 인스턴스에서 발생하는 데이터 일관성 문제는 동기 방식의 통신만으로는 해결하기 어려운 문제다.

이를 해결하기 위해서는 이벤트 기반의 비동기 통신 방식이 필요하다.

다음 포스팅에서는 Kafka를 활용한 이벤트 기반 아키텍처로 데이터 일관성 문제를 해결하는 방법에 살펴보려고 한다.

각 서비스 사이에서 통신을 어떻게 처리하는지는 잘 알아두도록 하자 👊

이전 포스팅에서는 API Gateway에 대해서 알아봤다.

API Gateway는 MSA와 같은 분산 시스템 환경에서 요청을 적절하게 라우팅을 해주기 위해 사용했었다.

앞으로도 계속해서 MSA 아키텍처에서 필요한 내용을 하나씩 정리해볼건데, 이번에는 여러가지 서비스의 설정 정보를 한군데에서 관리하도록 도와주는 Config Server에 대해서 정리해보려고 한다 👀

1. Config Server란?

Config Server는 MSA 환경에서 여러 서비스 인스턴스의 설정 정보를 중앙에서 관리하기 위한 컴포넌트이다.

분산 시스템에서는 각 서비스마다 다양한 환경(개발, 테스트, 운영)에 맞는 설정 정보가 필요한데, 이를 각 서비스에 직접 포함시키면 관리가 복잡해지는 문제가 있다.

예를들어서, JWT 생성과 검증에 사용되는 Secret Key가 변경된 상황을 생각해보자

만약, 모든 서비스에서 JWT 필터를 적용하고 있다면 다른 모든 서비스에서도 Secret Key 관련 설정 정보를 변경하고 다시 빌드하고 도커 허브에 올리고 배포해야하는 번거로운 작업이 될 수 있는 것이다.

💡 Config Server의 필요성

12factors라는 클라우드 네이티브 애플리케이션 개발 원칙 중 하나는 다음과 같다.

"개발, 테스트, 운영 환경이 일치하되, 간단한 조작으로 유연하게 변경할 수 있어야 한다"

여기서 Config Server는 하나의 중앙화된 저장소에서 구성 요소를 관리하는 기능을 제공하며, 각 서비스는 시작 시 Config Server로부터 설정 정보를 가져와서 사용한다.

이렇게 하면 설정 정보의 변경이 필요할 때 서비스를 다시 빌드하지 않고도 쉽게 변경할 수 있다.

즉, Config Server는 이런 원칙을 구현하는 데 도움을 준다!

2. Config Server의 동작 방식

Config Server는 일반적으로 Git Repository를 백엔드 저장소로 사용한다.

설정 파일을 Git에 저장함으로써 버전 관리가 가능하고, 여러 환경에 대한 설정을 비교적 체계적으로 관리할 수 있다는 장점이 있기 때문이다.

💡 계층 구조

Config Server는 계층 구조 를 사용하여 설정 정보를 관리한다.

조금 더 자세히 정리하면 다음과 같은 우선순위로 설정 정보를 찾는다고 볼 수 있다.

계층 구조

• application.yml
• application-{profile}.yml
• {application-name}.yml
• {application-name}-{profile}.yml

따라서 user-service-dev.yml 가 없다면 user-service.yml 을 가져오고, 그것도 없다면 application-dev.yml 을, 마지막으로 application.yml 에서 데이터를 가져온다.

간단하게 생각하면 서비스와 가장 가까운 정보(구체적인 설정 정보)부터 찾아서 가져오려고 시도한다고 이해하면 된다!

3. Config Server 구현

우선 위와 같이 Config Server 관련 의존성을 추가해야 한다.

의존성이 추가되었다면 application.yml에서 config server 설정을 진행해주면 된다.

코드를 살펴보자

💡 Config Server 설정

Sample Code

server:
  port: 8888
>
spring:
#  profiles:
#    active: native
  application:
    name: config-service
  cloud:
    config:
      server:
        native:
          search-locations: file:///Users/yeop/Desktop/LG_CNS_AM_Inspire_Camp/MSA
        git: #default
          uri: # 설정 정보를 관리하는 Github 주소 입력
          default-label: master # 해당 Github의 브랜치 설정
#          username: <github-id>
#          password: <gihub-accessToken>
        bootstrap: true
>
management:
  endpoints:
    web:
      exposure:
        include: health, busrefresh, refresh, metrics

설정 정보를 정리해보면 다음과 같이 정리할 수 있다.

즉, native 설정을 켜주면 search-locations로 지정한 디렉토리에서 설정 파일을 찾고, native 설정이 꺼져있다면 git으로 설정한 디렉토리에 접근하여 설정 파일을 찾는 것이다.

다음으로 BootApplication에서 다음 코드와 같이 @EnableConfigServer 어노테이션을 추가해주면 우선은 마무리 된다.

Sample Code

@SpringBootApplication
@EnableConfigServer
public class ConfigServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(ConfigServiceApplication.class, args);
    }
}

💡 Client 서비스 설정

Config Server를 사용하는 클라이언트 서비스는 다음과 같이 설정 정보를 작성해야 한다.

Sample Code

spring:
  config:
    import: optional:configserver:http://127.0.0.1:8888/
  cloud:
    config:
      name: user-service
      ...

위처럼 spring.config.import : ~~ 에서 Config Server를 찾아오는 모습이다.

여기서 필자는 configserver가 디스커버리 서비스에서 대상을 찾기 위해 사용하는 검색어인줄 알았으나 관련 내용을 정리해보면 다음과 같다.

optional:configserver:http://127.0.0.1:8888/ 정리

-optional:

• Config Server에 연결할 수 없더라도 애플리케이션이 시작할 수 있게 해주는 Prefix이다.

configserver:

• 이것은 Spring Cloud Config의 특별 구문으로, Config Server를 사용한다는 의미를 가진다.

http://127.0.0.1:8888/

• 실제 Config Server의 URL이다.
• 이전에 8888 포트를 Config Server로 지정했기 때문에 위와같은 URL을 사용한다.

즉, 여기서 configserver 는 Spring Cloud Config Client가 인식하는 특별한 접두사(prefix)인 것이다.

이 접두사는 Spring Boot가 Config Server에 연결해야 함을 알려주는 마커(marker)라고 이해하면 될 것 같다!

실제로 서비스를 실행시켜보면 Config Server에서 데이터를 패치받는 모습을 볼 수 있다.

4. 설정 변경 감지와 적용

Config Server의 한 가지 제한사항은 설정 정보가 변경되더라도 서비스를 재시작하지 않으면 변경 사항이 적용되지 않는다는 점이다.

즉, 편하게 사용하려고 Config Server를 사용하지만 위의 설정 그대로 사용한다면 설정 정보가 변경된 순간 서비스를 다시 실행해야하는 불편함이 그대로 존재하게 된다.

실제로 강의에서 실습하는 과정에서 대부분의 시간을 여기에 할애했다.. (MSA를 적용했기 때문에 서비스가 많아서 실습이 꽤 까다로웠다)

그래서 필자는 최종 결론만 정리해보려고 한다 😅

💡 Spring Cloud Bus를 이용한 자동 갱신

이전에 언급한 문제를 해결하기 위해 Spring Cloud Bus와 메시지 브로커(RabbitMQ, Kafka 등)를 사용할 수 있다.

설정이 변경되면 Config Server가 메시지 브로커를 통해 모든 서비스에 변경 사항을 알리고, 각 서비스는 자동으로 설정을 갱신하는 것이다.

우선 메세지 브로커를 이용하지 않았을 때의 구조를 살펴보면 다음과 같다.

위 사진과 같이 Github에서 토큰 정보를 변경하면 Config-Server에는 즉시 반영되지만, Config-Server에서 설정 정보를 받아오는 다른 서비스에는 refresh를 걸어주지 않는이상 기존 토큰 정보를 가지고 있게 된다.

그래서 이러한 문제를 해결하기 위해 메세지 브로커를 적용한 구조를 살펴보면 다음과 같다.

GitRepository에서 설정 정보가 변경되면 우선 Config-Server에는 바로 반영된다.

여기서 개발자는 /busrefresh 라는 엔드포인트를 호출하여 메세지 브로커에 메세지를 발행시킨다.

RabbitMQ에 메세지가 저장되면, 이를 구독하는 모든 서비스들에게 변경 내용을 알려주고 서비스들은 이 내용으로 설정 정보를 변경하게 된다.

(물론 설정이라는 특성상 모든 설정에 대하여 동적으로 변경이 가능한 것은 아니다.)

💡 Spring Cloud Bus & RabbitMQ 설정 추가

이제부터는 위에서 설명한 구조대로 동작할 수 있도록 설정 정보를 수정해보자

우선 메세지 브로커에 연결해야할 서비스들 (Config Server와 Config Server에서 설정 정보를 가져올 서비스들)에 한가지 의존성을 추가해야한다.

메세지 브로커를 사용할 서비스들에 위 의존성이 추가되었다면, 메세지 브로커로 사용할 RabbitMQ를 설치해야 한다.

간단하게 진행하기 위해 Docker Hub에 등록된 RabbitMQ 이미지를 사용하도록 하자

RabbitMQ 컨테이너 실행 docker run -d -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:4.0-management

• RabbitMQ 이미지는 먼저 Pull을 해야한다.
• 여기서 웹 서버 포트를 지정해줄 수 있는데 필자는 15672로 지정했다.

Config-Server 설정 추가

Sample Code

server:
  port: 8888
>
spring:
#  profiles:
#    active: native
  application:
    name: config-service
  cloud:
    config:
      server:
        native:
          search-locations: file:///Users/yeop/Desktop/LG_CNS_AM_Inspire_Camp/MSA
        git: #default
          uri: # Github 주소
          default-label: master
#          username: <github-id>
#          password: <gihub-accessToken>
        bootstrap: true
  rabbitmq:
    host: 127.0.0.1
    port: 5672
    username: guest
    password: guest
>
management:
  endpoints:
    web:
      exposure:
        include: health, busrefresh, refresh, metrics

사진과 같이 rabbitmq 관련 정보를 추가해주자

우선 로컬 환경에서 진행하기 때문에 127.0.0.1을 사용하고 도커 컨테이너를 띄울때 사용한 5672 포트를 사용하여 바인딩을 시켜준다.

기본 아이디와 비밀번호는 guest 이므로 이 정보도 넣어준다.

여기서 이전에 설명하지 않고 넘어갔던 부분인 management 는 Actuator 기능을 사용하기 위한 설정이다.

우리는 busrefresh 엔드포인트를 호출하여 메세지를 발행해야하기 때문에 사용한다고 일단 알아두자!

마찬가지로 메세지 브로커를 사용할 서비스들에도 위와 같은 rabbitmq 설정을 추가해주면 된다.

💡 RabbitMQ 접근 & 팁?

이전에 컨테이너 실행시 설정했던 웹포트 15672로 접근하면 다음과 같은 화면을 볼 수 있다.

이후, busrefresh 엔드포인트를 호출하면 메세지 브로커를 구독하는 서비스에도 변경된 설정 정보가 반영되게 된다!

여기서 다음 사진을 살펴보자

즉, 8888(Config-Server)가 아니라 메세지 브로커를 구독하는 8000(User-Service)에서 actuator/busrefresh를 호출해도 정상적으로 동작한다.

Config Server에 직접 /actuator/busrefresh를 호출하지 않아도, 메시지 브로커(RabbitMQ)에 연결된 어떤 서비스에서든 /actuator/busrefresh를 호출하면 설정 변경이 모든 서비스에 전파된다.

동작 과정을 살펴보면 다음과 같다.

메세지 브로커 동작 과정

1. GitHub에서 설정 변경 발생

2. Config Server는 변경 사항 감지

3. 어떤 서비스든(ex: user-service) /actuator/busrefresh 엔드포인트 호출

4. 해당 서비스는 Spring Cloud Bus를 통해 메시지 브로커에 메시지 발행

5. 메시지 브로커는 동일한 버스에 연결된 모든 다른 서비스(Config Server 포함)에게 이 메시지 전달

6. 각 서비스는 메시지를 받고 Config Server에서 새 설정을 가져와 적용

정리하면 동일한 메세지 버스에 각 서비스가 연결되어있기 때문에, busrefresh를 호출할 수 있으며, 한 서비스에서 보낸 메세지는 동일한 버스에 연결된 모든 서비스에 전달되기 때문에 user-service에서 호출해도 변경된 설정이 모두 반영될 수 있다는 것을 기억하자!

5. 암호화 / 복호화

우리는 Github Repository에서 비밀키와 같은 데이터를 관리한다면 아무래도 민감한 정보이기 때문에 암호화된 값으로 저장하는게 보안 측면에서 더 안전한 방법일 것이다.

따라서, Config Server에서 중요한 키들을 관리한다고 하면, 암호화 / 복호화 기능이 Config Server가 시작되는 초기 단계에서 제공되어야 할 것이다.

bootstrap.yml은 Spring Cloud 애플리케이션이 시작될 때 가장 먼저 로드되는 설정 파일이기 때문에, 이 파일을 별도로 생성해서 암호화 / 복호화를 진행해보도록 하자

💡 비대칭키 암호화

RSA 알고리즘을 사용하는 비대칭키 암호화를 구현하기 위해, JAVA의 keytool을 이용해서 key-store를 생성할 수 있다.

명령어는 다음과 같다.

KeyStore 생성 keytool -genkeypair -alias apiEncryptionKey -keyalg RSA -dname "CN=Config Server,OU=Spring Cloud,O=Organization" -keypass 1q2w3e4r -keystore apiEncryptionKey.jks -storepass 1q2w3e4r

-genkeypair : 공개키/개인키 쌍을 생성 -alias apiEncryptionKey : 키 쌍의 별칭 설정 -keyalg RSA : RSA 알고리즘 사용 -dname : 인증서 소유자 정보 -keypass 1q2w3e4r : 키 비밀번호 -keystore apiEncryptionKey.jks : 생성할 키스토어 파일 이름 -storepass 1q2w3e4r : 키스토어 비밀번호

위 명령어를 입력하면 사진과 같이 jks 확장자를 가진 파일이 하나 생성되는 모습을 볼 수 있다.

다음으로 Config Server에서 application.yml과 동일한 위치에 bootstrap.yml을 생성하고 다음과 같이 코드를 작성해주자

Sample Code

encrypt:
    key-store:
        location: file: # 방금 생성한 jks 파일 경로
        password: 1q2w3e4r
        alias: apiEncryptionKey

우리는 Config Server 설정 파일로 등록했기 때문에 8888번 포트에 encrypt 엔드포인트로 plain text를 날려주면 다음과 같은 사진을 볼 수 있다.

Result View

우리는 이 값을 깃허브에 저장해서 암호화된 키 값으로 사용하면 된다.

이렇게 사용할 수 있는 이유는 Config Server에서 Github에 저장된 암호화된 Key를 가져올 때, 이전에 생성한 KeyStore를 이용하여 복호화를 진행하기 때문에 결과적으로 decrypt된 값을 사용할 수 있다.

참고로 Github에 암호화된 값을 저장할 때는 {ciper} 라는 Prefix를 붙여서 저장하면 된다.

OUTRO

이번 포스팅에서는 Spring Cloud Config Server에 대해 자세히 알아봤다.

MSA 환경에서 여러 서비스의 설정을 중앙에서 관리하는 Config Server는 개발 생산성과 시스템 안정성을 크게 향상시키는 중요한 컴포넌트다.

Config Server와 메시지 브로커를 함께 사용하면 여러 서비스 간의 설정 정보를 효율적으로 관리하고 동기화할 수 있어, MSA의 복잡성을 줄이는 데 큰 도움이 된다는 것을 기억하자 👊

이전 포스팅에서 서비스 인스턴스의 정보를 관리하는 서비스 디스커버리에 대해서 정리해봤다.

이번에는 이 정보를 사용하여 여러가지 작업을 수행하는 API Gateway에 대해서 정리해보려고 한다 👀

1. API Gateway

API Gateway는 MSA 환경에서 클라이언트와 마이크로서비스 사이에 위치하여 모든 API 요청의 단일 진입점 역할을 하는 컴포넌트이다.

간단하게 구조도를 그려보면 다음과 같다.

즉, Client는 서비스 인스턴스의 실제 주소를 바라보는 것이 아니라 오직 API Gateway만 바라보게 된다.

이후, API Gateway는 Service Discovery(Eureka Server)로부터 서비스의 위치를 파악하고 API 요청을 적절하게 라우팅해주는 역할을 수행한다.

그렇다면 Gateway는 어떻게 사용할 수 있을까?

우선 사진과 같이 Gateway 의존성을 추가하여 프로젝트를 설정하면서 시작하자

💡 application.yml

Gateway도 마찬가지로 설정 파일에서 대부분의 작업이 수행된다.

설정 파일에서는 라우팅 정보를 관리하며, 필요시 필터 정보도 추가할 수 있다.

우선 설정 파일을 살펴보자

Sample Code

server:
  port: 8000
>
spring:
  application:
    name: api-gateway
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://USER-SERVICE
          predicates:
            - Path=/user-service/login
            - Method=POST
          filters:
            - RemoveRequestHeader=Cookie
            - RewritePath=/user-service/(?<segment>.*), /$\{segment}
        - id: user-service
          uri: lb://USER-SERVICE
          predicates:
            - Path=/user-service/users
            - Method=POST
          filters:
            - RemoveRequestHeader=Cookie
            - RewritePath=/user-service/(?<segment>.*), /$\{segment}
        - id: user-service
          uri: lb://USER-SERVICE
          predicates:
            - Path=/user-service/actuator/**
            - Method=GET,POST
          filters:
            - RemoveRequestHeader=Cookie
            - RewritePath=/user-service/(?<segment>.*), /$\{segment}
        - id: user-service
          uri: lb://USER-SERVICE
          predicates:
            - Path=/user-service/**
            - Method=GET
          filters:
            - RemoveRequestHeader=Cookie
            - RewritePath=/user-service/(?<segment>.*), /$\{segment}
            - AuthorizationHeaderFilter
>        
        - id: order-service
          uri: lb://ORDER-SERVICE
          predicates:
            - Path=/order-service/**
          filters:
            - RewritePath=/order-service/(?<segment>.*), /$\{segment}
>            
      default-filters:
        - name: GlobalFilter
          args:
            baseMessage: Spring Cloud Gateway Global Filter
            preLogger: true
            postLogger: true
>
eureka:
  client:
    register-with-eureka: true
    fetch-registry: true
    service-url:
      defaultZone: http://localhost:8761/eureka

샘플 코드가 조금 폭력적(?)일수도 있으나 천천히 살펴보자

우선, API Gateway 서버도 서비스 디스커버리에 정보를 추가하도록 eureka 관련 설정을 진행하고 있다.

다만, 여기서 eureka.client.fetch-registry 설정을 true로 해야만 라우팅이 가능하다는 것을 기억하자

그리고 이어서 중요한 설정 정보를 정리하면 다음과 같다.

server.port

• API Gateway가 사용할 포트 번호

spring.application.name

• 서비스 이름 (eureka에 등록될 때 사용)

spring.cloud.gateway.routes

• 실제 라우팅 규칙 정의 부분이다.

id

• 라우트의 고유 식별자이다.
• 동일한 식별자를 여러번 사용해도 실제로는 상관없다.

uri

• 요청을 전달할 대상 서비스를 의미한다.
• 여기서 lb://는 로드 밸런싱을 의미한다.
• 만약, 정적 주소 (ex. http://localhost:8080/~~ )를 사용한다면 여러개의 서비스를 등록하더라도 해당 주소로만 요청이 넘어가는 문제가 발생한다.
• 따라서, 특별한 경우가 아니면 lb:// 를 prefix로 사용하자

predicates

• 이 라우트에 적용할 조건을 정의하는 부분이다.
• 필터, 경로, HTTP 메소드 등이 여기서 정의된다.

filters

• 요청/응답 변환 필터를 의미한다.

RemoveRequestHeader

• 특정 헤더를 제거 (예: 쿠키)

RewritePath

• URL 경로를 재작성하는 부분이다.
• 정규표현식을 사용한다.

AuthorizationHeaderFilter

• 커스텀 인증 필터를 정의하는 부분이다.

spring.cloud.gateway.default-filters

• 모든 라우트에 적용되는 필터이다.

이렇게 정리해보니 아마 독자가 읽기 어려울 것 같다는 생각이 든다.

그래서 하나의 라우트 정보를 사진으로 정리하면 다음과 같다.

2. API Gateway의 역할 & 커스텀 필터

들어온 요청을 적절하게 라우팅을 해주는 것이 API Gateway의 목표이다.

이전에 모놀리식 서비스를 만들어봤다면, token filter를 만들어서 적절한 요청인지 권한 확인을 진행하는 Spring Security를 적용해본 경험이 있을 것이다.

모든 요청은 API Gateway로 들어오기 때문에, 각 서비스마다 필터를 적용해주는 것보다는 API Gateway에 필터를 적용해서 보안관련 작업을 수행하는 것이 더 효율적이다.

따라서, 위 설정 파일에서도 살펴봤다시피 filters 부분에 여러가지 커스텀 필터를 등록할 수 있다.

💡 Filter 동작 과정

Client가 요청을 보내면 그 요청에 대해서 우선 pre-filter가 동작한다. 이후, 서비스에서 요청을 모두 처리하고 response를 받게되면 API Gateway에서 설정해준 post-filter가 동작하게 된다.

순서를 작성해보면 다음과 같다.

Filter 동작 과정 - (1) request -> pre-filter -> 서비스 인스턴스에서 요청 처리 -> post-filter -> response

만약, GlobalFilter와 해당 라우트에 별도의 커스텀 필터도 적용된다면 다음과 같이 동작하게 된다.

Filter 동작 과정 - (2) request -> global-pre-filter -> custom-pre-filter -> 서비스 인스턴스에서 요청 처리-> custom-post-filter -> global-post-filter

필터, 인터셉터, AOP를 동시에 사용하는 경우 동작 과정과 비슷하게 진행된다는 것을 기억하자!

💡 CustomFilter

권한 확인과 같은 SecurityFilter를 적용하기 위해서는 커스텀 필터를 직접 구현하고 등록해야 한다.

커스텀 필터의 기본적인 구조는 다음과 같다.

Sample Code

@Component
@Slf4j
public class CustomFilter extends AbstractGatewayFilterFactory<CustomFilter.Config> {
    public CustomFilter() {
        super(Config.class);
    }
>
    @Override
    public GatewayFilter apply(Config config) {
        // Custom Pre Filter
        return (exchange, chain) -> {
            ServerHttpRequest request = exchange.getRequest();
            ServerHttpResponse response = exchange.getResponse();
>
            log.info("Custom PRE filter: request id -> {}", request.getId());
>
            // Custom Post Filter
            return chain.filter(exchange).then(Mono.fromRunnable(() -> {
                log.info("Custom POST filter: response code -> {}", response.getStatusCode());
            }));
        };
    }
>
    public static class Config {
        // Put the configuration properties
    }
}

여기서 스프링부트로 Spring Security를 사용해서 JWT 필터를 만들어봤다면 한가지 차이점을 발견했을수도 있다.

바로 OncePerRequestFilter 가 아닌 AbstractGatewayFilterFactory 를 상속한다는 것이다.

여기서 우리는 Spring MVC와 Spring WebFlux에 대해서 이해해야 한다.

💡 Spring MVC vs Spring WebFlux

Spring MVC는 이전에 많이 봐서 이해되지만, Spring WebFlux는 어떤 내용일까?

위에서 상속하는 필터의 내용이 다른 이유는 기반 기술 스택의 차이에서 비롯된다.

Spring MVC (서블릿 기반)

• 내장 서버: Tomcat (서블릿 컨테이너)
• 처리 방식: 동기식, 블로킹 I/O
• 필터 타입: OncePerRequestFilter, HandlerInterceptor
• 요청/응답 객체: HttpServletRequest, HttpServletResponse

Spring WebFlux (리액티브 기반)

• 내장 서버: Netty (비동기 이벤트 기반)
• 처리 방식: 비동기식, 논블로킹 I/O
• 필터 타입: WebFilter, AbstractGatewayFilterFactory
• 요청/응답 객체: ServerHttpRequest, ServerHttpResponse

Spring Cloud Gateway는 Spring WebFlux 기반으로 구축되어 있기 때문에, 모든 필터 로직이 리액티브 스타일로 작성되어야 한다.

이는 위 코드에서 apply 메서드를 살펴보면 HttpServlet이 아닌, ServerHttp를 사용하고 있는 모습을 볼 수 있다.

마찬가지로 chain.filter(exchange).then(...) 형식의 비동기 처리 방식으로 나타난다.

여기서 필터 체인이 Mono<Void> 타입을 반환하고 있는데, 이를 통해 비동기 처리를 가능하게 한다. (JavaScript의 Promise와 비슷한 개념이다)

그렇다면 왜 Spring Gateway는 WebFlux 기반으로 구현되었을까?

성능 이점

• 높은 동시성 처리: 적은 수의 스레드로 많은 요청을 처리할 수 있다.
• 자원 효율성: 스레드 블로킹이 적어 CPU와 메모리 사용이 효율적이다.

특히 API Gateway는 모든 요청의 진입점으로 높은 부하를 받기 때문에, 이러한 비동기 모델이 적합하다.

이러한 이유로 Spring Cloud Gateway에서는 OncePerRequestFilter 대신 AbstractGatewayFilterFactory를 상속받아 필터를 구현하며, 모든 필터 로직이 리액티브 방식으로 작성되어야 한다는 것을 기억하자 👊

💡 AuthorizationHeaderFilter

위 내용을 기반으로 Jwt를 검증하는 코드의 일부는 다음과 같다.

Sample Code

@Override
public GatewayFilter apply(Config config) {
    return (exchange, chain) -> {
        ServerHttpRequest request = exchange.getRequest();
>
        if (!request.getHeaders().containsKey(HttpHeaders.AUTHORIZATION)) {
            return onError(exchange, "No authorization header", HttpStatus.UNAUTHORIZED);
        }
>
        String authorizationHeader = request.getHeaders().get(HttpHeaders.AUTHORIZATION).get(0);
        String jwt = authorizationHeader.replace("Bearer ", "");
>
        if (!isJwtValid(jwt)) {
            return onError(exchange, "JWT token is not valid", HttpStatus.UNAUTHORIZED);
        }
>
        return chain.filter(exchange);
    };
}
>
private Mono<Void> onError(ServerWebExchange exchange, String err, HttpStatus httpStatus) {
    ServerHttpResponse response = exchange.getResponse();
    response.setStatusCode(httpStatus);
    log.error(err);
>
    byte[] bytes = "The requested token is invalid.".getBytes(StandardCharsets.UTF_8);
    DataBuffer buffer = exchange.getResponse().bufferFactory().wrap(bytes);
    return response.writeWith(Flux.just(buffer));
}

return chain.filter 반환 타입

JWT 검증 로직을 apply의 pre-filter 부분에 작성해주면 된다.

여기서 우리가 눈여겨 봐야할 것은 에러를 반환하기 위해 작성된 onError 메서드의 반환 타입이 Mono<Void> 라는 것이다.

또한, post-filter는 별도로 사용하지 않으며 마찬가지로 반환타입이 비동기 처리에 사용되는 Mono 타입이라는 것을 기억해두자!

💡 GlobalFilter

GlobalFilter는 사진으로 한번 정리해보자 위에서 커스텀 필터 관련 내용을 정리했기 때문에 크게 이해하는데 문제는 없을 것이다.

한가지 추가된 내용이라면 application.yml에 작성한 내용을 매개변수로 전달받아서 로그찍는데 사용했다는 것이다.

3. 테스트

우리가 이전에 API Gateway를 설정하는 과정에서 lb:// 를 사용하여 라우트의 uri를 정의했던 것을 기억할 것이다.

여기서 lb를 사용하게 되면 기본적으로 라운드 로빈 방식으로 로드밸런싱을 진행한다.

💡 인스턴스 띄우기

여러개의 인스턴스를 띄우고 한번 테스트해보자

우선 MY-FIRST-SERVICE 를 3개 띄워서 Eureka에 등록한 상황이다.

💡 동일한 Path로 동시에 3개 접속

다음으로 localhost:8000/first-service/check 로 접근하면 위와 같은 화면이 나온다.

여기서 8000은 Gateway Port Number이다.

서비스에 직접 접근하는게 아니라 Gateway에 접근하면 알아서 라우팅을 진행해줄 것이다.

또한, API Gateway에 first-service관련 설정은 다음과 같다.

- id: first-service
  uri: lb://MY-FIRST-SERVICE
  predicates:
    - Path=/first-service/**
  filters:
    - AddRequestHeader=first-request, first-request-header-by-yaml
    - AddResponseHeader=first-response, first-response-header-from-yaml
    - CustomFilter

따라서, first-service로 접근하면 API Gateway가 라우팅을 진행해줄 것이다.

위 사진과 같이 path로 들어갔더니 각자 다른 3개의 포트를 사용하고 있는 모습을 볼 수 있다.

실제로 하나의 페이지에서 계속해서 새로고침을 해보면 라운드 로빈 방식으로 로드밸런싱이 진행되기 때문에 포트번호가 번갈아가면서 바뀌는 모습을 볼 수 있다.

💡 인스턴스 하나 종료시키기

사진과 같이 인스턴스를 종료시키고 새로고침을 누르다보면 에러페이지가 뜨는 모습을 볼 수 있다.

즉, 다른 사람은 정상적인 페이지를 보고 있으나 특정 클라이언트는 에러 페이지를 보고 있는 모습을 상상할 수 있을 것이다.

이러한 문제가 발생하는 이유는 Service Discovery(Eureka)가 서비스가 종료되었음을 바로 확인하지 못해서 그런것이다.

즉, 풀링 작업을 30초마다 주기적으로 수행하지만, 서비스가 내려가고 풀링이 진행되지 않은 시간동안은 오류 페이지를 보여주는 것이다.

실제로 계속 새로고침을 하다보면 위 사진과 같이 다시 정상적으로 페이지 접속이 가능하다.

OUTRO

이번 포스팅에서는 API Gateway의 개념을 살펴보고 설정과 커스텀 필터 구현에 대해서 정리해봤다.

API Gateway는 MSA 환경에서 클라이언트와 서비스 인스턴스 사이의 중간 계층으로, 모든 API 요청의 단일 진입점 역할을 수행한다.

여기서 우리가 중요하게 기억해야 할 내용들을 다시 정리해보면

API Gateway는 lb:// 형식의 URI를 사용해 동적으로 라우팅이 가능하며, 기본적으로 라운드 로빈 방식의 로드 밸런싱을 제공한다는 것

Spring Cloud Gateway는 WebFlux 기반으로 동작하므로, 필터의 반환 타입은 Mono여야 하며, 비동기적인 처리가 가능하다는 것,

커스텀 필터를 구현할 때는 OncePerRequestFilter가 아닌 AbstractGatewayFilterFactory를 상속해야 한다는 것

정도가 있을 것 같다.

이번 포스팅을 통해 Gateway의 기본 개념과 설정 방법을 이해할 수 있으면 좋겠다 👊

오랜만에 포스팅을 쓰는 것 같다 😅

최근 MSA(마이크로서비스 아키텍처) 관련 강의를 들으면서 여러 흥미로운 개념들을 접하게 되었고, 이전보다 더 명확하게 이해하게 된 것 같아 이제부터 정리해보려고 한다.

이번 포스팅에서는 MSA의 기본 개념을 다시 한번 살펴보고, 이 아키텍처에서 핵심적인 역할을 하는 서비스 디스커버리(Service Discovery)에 대해 알아보자 👀

1. MSA 아키텍처

MSA 아키텍처는 알다시피, 하나의 서비스로 구현된 모놀리식 서비스와는 다르게 여러개의 서비스로 구성된 아키텍처를 의미한다.

물론, MSA 아키텍처가 모놀리식 아키텍처보다 항상 좋다는 것은 절대 아니다.

상황에 따라서, 모놀리식 아키텍처로 서비스를 구현해야하는 경우도 분명히 존재한다.

하지만, Cloud Native 환경에서 서비스를 구성하는 경우, 주로 MSA 아키텍처가 사용된다.

💡 MSA 구조도

위 그림에서 볼 수 있듯이, MSA 아키텍처는 각각의 독립적인 서비스(Instance 1, Instance n)들이 API를 통해 통신하며 전체 서비스를 구성한다.

MSA 아키텍처를 사용하면 서비스를 독립적으로 개발, 배포, 확장할 수 있다는 장점이 있다.

이러한 장점은 당연히 필요한 서비스만 선택적으로 스케일링할 수 있으므로 리소스 효율성이 높아진다는 것을 의미한다.

또한, 장애가 발생하더라도 전체 시스템으로 확산되지 않는다는 장점이 존재한다.

💡 MSA를 적용하려면..?

하지만 위에서 언급한 장점들 이면에는 다음과 같은 문제를 고려해야 한다.

고려해야할 내용

• 분산 시스템 복잡성: 서비스 간 통신, 일관성 유지 등의 문제가 발생한다.
• 네트워크 지연: 서비스 간 통신이 네트워크를 통해 이루어지므로 지연이 발생할 수 있다.
• 데이터 일관성: 각 서비스가 독립적인 데이터베이스를 가질 경우, 데이터 일관성 유지가 어려워진다.
• 운영 복잡성: 다수의 서비스를 모니터링하고 관리하는 것이 복잡해진다.

이는 하나의 서비스로 운영하는 모놀리식과 여러 개의 서비스로 운영하는 MSA 간에 발생할 수 있는 주요 차이점이다.

사실, 이런 문제들을 해결하기 위해 서비스 디스커버리, API 게이트웨이, 로드 밸런싱, 서킷 브레이커 등의 다양한 패턴과 기술이 등장하게 되었고, 위에서 살펴본 사진에는 이러한 솔루션들이 모두 포함되어 있는 것이다. (그래서 복잡해보일 수 있다)

이제부터 포스팅을 통해 이러한 기술들을 하나씩 정리해나갈 예정이다!

2. 서비스 디스커버리

이번 포스팅에서는 서비스 디스커버리라는 개념에 대해서 정리하고 코드로 살펴보려고 한다.

사진을 기준으로 보면 빨간색으로 표시된 부분이다.

그렇다면 서비스 디스커버리는 뭘까?

💡 Service Discovery란

MSA 아키텍처 특성상 여러개의 서비스가 클라우드 내에서 동작하고 있을 것이다.

만약, 클라이언트로부터 API 요청이 들어온다면 누군가는 이 요청을 어느 서비스로 보내야할지 알고있어야 한다.

여기서 알고 있어야하는 정보는 다시말하면 라우팅 정보(IP주소 + 포트넘버)를 의미하게 된다.

즉, 서비스 디스커버리는 현재 동작하는 서비스들의 라우팅 정보를 관리하는 역할을 수행하는 서비스이다.

3. Eureka Server

Spring 프레임워크에서 Service Discovery로는 Eureka를 사용한다.

Eureka는 Netflix에서 개발한 서비스 디스커버리 도구로, Spring Cloud에 통합되어 있어 Spring 기반 MSA에서 쉽게 사용할 수 있다.

Eureka를 사용하기 위해서는 우선 위 사진과 같이 Eureka Server 의존성을 추가해야 한다.

💡 application.yml

다음으로 Eureka Server의 설정 파일(application.yml)을 살펴보자

Sample Code

server:
  port: 8761
>
spring:
  application:
    name: discoveryservice
>
eureka:
  client:
    register-with-eureka: false
    fetch-registry: false

여기서 중요한 설정을 살펴보면 다음과 같다.

server.port

• Eureka 서버가 실행될 포트 번호이다.
• 기본적으로 8761 포트 번호를 사용한다.

spring.application.name

• 서비스의 이름을 설정하는 부분이다.

eureka.client.register-with-eureka

• Eureka 서버 자신을 Eureka에 등록할지 여부를 결정한다.
• 서버 자체는 등록할 필요 없으므로 false로 설정한다.

eureka.client.fetch-registry

• 레지스트리 정보를 로컬에 캐싱할지 여부를 결정한다.
• 서버 자체는 다른 서비스를 찾을 필요 없으므로 false로 설정한다.

물론 위 설정말고도 설정할 수 있는 옵션은 다양하다.

디스커버리 서버는 서비스들의 정보를 주기적으로 받아와서 정상적으로 동작하는 서비스인지 판단하는 풀링을 진행하게 된다.

이때, 사용할 수 있는 옵션이 client:registry-fetch-interval-seconds: 30 이 있는데 default로 30초마다 서비스의 정보를 계속해서 업데이트한다.

이처럼, 만약 커스텀하고 싶은 부분이 있다면 유레카 설정 정보 페이지를 살펴보고 커스텀하자!

💡 어노테이션 추가

마지막으로 해당 서비스가 명시적으로 Eureka 서버임을 알려주기 위해서는 다음과 같이 코드를 작성하면 된다.

Sample Code

@SpringBootApplication
@EnableEurekaServer
public class ServiceDiscoveryApplication {
    public static void main(String[] args) {
        SpringApplication.run(ServiceDiscoveryApplication.class, args);
    }
}

서비스의 BootApplication에 @EnableEurekaServer 라는 어노테이션을 명시적으로 추가해주면 Eureka 서버 설정은 마무리된다.

4. Eureka Client

위에서 살펴본 것은 Eureka Server이다.

이제부터는 Eureka Client에 대해서 살펴보자

Eureka Client는 Eureka Server에 자신의 정보를 등록하고, 다른 서비스의 정보를 조회하는 역할을 한다.

즉, MSA 환경에서 각 마이크로서비스는 Eureka Client로 동작하게 된다.

각 서비스의 정보를 Eureka Server에 등록하기 위해서는 위 사진과 같이 Eureka Discovery Client 의존성을 각 서비스마다 추가해야 한다.

💡 application.yml

우선 설정 정보를 살펴보자

Sample Code

server:
  port: 0
>
spring:
  application:
    name: order-service
  ...
>
eureka:
  instance:
    instance-id: ${spring.application.name}:${spring.application.instance_id:${random.value}}
  client:
    register-with-eureka: true
    fetch-registry: true
    service-url:
      defaultZone: http://127.0.0.1:8761/eureka

여기서 중요한 설정 정보를 정리해보면 다음과 같다.

server.port:0

• 랜덤 포트를 사용하도록 설정한다.
• 이렇게 하면 같은 서버에서 여러 인스턴스를 실행할 때 포트 충돌 문제를 방지할 수 있다.

spring.application.name

• 서비스의 이름을 지정한다.
• 이 이름은 Eureka에 등록될 때 사용되며, 다른 서비스에서 이 서비스를 찾을 때 사용된다.

eureka.instance.instance-id

• Eureka에 등록될 때 사용할 인스턴스 ID를 설정한다.
• ${random.value}를 사용하여 매번 고유한 ID가 생성되도록 한다.
• 이렇게 하면 동일한 서비스의 여러 인스턴스를 구분할 수 있다.

eureka.client.register-with-eureka

• true로 설정하여 이 서비스를 Eureka 서버에 등록한다.

eureka.client.fetch-registry

• true로 설정하여 Eureka 서버로부터 레지스트리 정보를 가져온다.
• 이를 통해 서비스 인스턴스에서도 디스커버리 서버의 정보를 가져오기 때문에다른 서비스의 위치를 알 수 있다.

eureka.client.service-url.defaultZone

• Eureka 서버의 위치를 지정한다.
• 여기서는 로컬 Eureka 서버(127.0.0.1:8761)를 사용한다.

이러한 설정을 통해 MSA 환경에서 서비스 디스커버리가 가능해지며, 같은 서비스의 여러 인스턴스를 쉽게 확장할 수 있게되는 것이다.

결국, 각 인스턴스는 랜덤 포트와 고유한 인스턴스 ID를 가지며, 모두 동일한 서비스 이름으로 Eureka에 등록되어 클라이언트에서는 논리적으로 하나의 서비스로 보이게 된다.

실제로 유레카 서버포트인 localhost:8761 로 접근하면 동일한 서비스가 2개 등록된 모습을 볼 수 있다!

(참고로 스프링부트에서 동일한 서비스를 여러개 띄우기 위해서는 빌드된 jar 파일을 별도로 실행시켜줘야 한다.)

💡 server.port:10000

만약 서버 포트를 10000으로 고정하면 어떻게될까?

어차피 서비스는 eureka.instance.instance-id 에서 설정한 바와 같이 랜덤 인스턴스 ID가 할당되어 Eureka 서버에 등록되기 때문에 문제가 없다.

하지만, 서버 포트를 10000으로 고정한다면 동일한 서비스를 동일한 서버에서 2개이상 띄우게 되는 경우 포트 충돌이 발생하게 된다.

따라서, 여러개의 인스턴스를 생성하는 서비스라면 포트 번호를 랜덤으로 설정해주는 0번을 주로 사용한다는 것을 기억하자!

OUTRO

이번 포스팅에서는 서비스 디스커버리의 역할을 수행하는 Eureka Server 설정과 인스턴스를 등록하기 위한 Eureka Client 서비스의 설정 파일을 살펴봤다.

이처럼 Eureka 서버와 클라이언트를 설정하면 서비스 간 자동 검색이 가능해지고, 동적으로 서비스 인스턴스 추가/제거가 가능한 MSA 환경을 구축할 수 있다.

막상 보면 크게 어려운 내용은 없으나, 설정 정보가 어떤 역할을 하는지는 기억해두자 👊