Refine 이관 작업 ( feat. 중고나라 - 셀러지원센터 )

 

📍 이관을 하게 된 배경

기존에 셀러지원센터는 Next.js, react-query, shadcn/ui 의 환경에서 개발을 진행했었다. 짧은 시간 안에 빠른 개발, 빌드 시간 단축, 확장 할 수 있는 커스텀 조건이 위 기술의 채택 이유이기도 했다. (참고 아티클)

 

1차,2차 배포까지만 해도 우리가 선택한 기술이 올바르다고 판단했다.

3차 오픈을 준비하기 전에, 이전에 빠른 개발로 인해 미뤄두었던 코드 개선작업을 시작한 것이 이관의 시초점이다.

 

1️⃣ 개발자마다 다른 코드 스타일

우리의 컨벤션을 정하긴 했지만, 페이지마다 작성한 개발 코드의 스타일이 온전히 일치하지는 않았다.

그래서 오류가 발생 했을때 해당 코드를 작성하지 않은 사람이 개선을 진행하려고 하면 개발 비용이 많이 필요했다. 

 

2️⃣ 직관적이지 않은 코드 베이스

테이블 자체에 대한 공통 컴포넌트는 직접 구현해 두었고, 외부에서 테이블 리스트 데이터를 불러오고 주입하는 방식으로 사용했었다. 

하지만, API마다 데이터를 변환하는 방식, 페이지 수를 가져오는 방식이 달라 페이지 내부에 단순히 리스트 컴포넌트만 보여주는 것이 아닌 데이터를 클라이언트 환경에 맞게 변환하는 로직들이 섞여 있어 페이지 동작을 직관적으로 파악하기 어려웠다.

 

3️⃣ API마다 다른 스펙에 맞춰 변환하는 과정의 분산화

셀러지원센터에서 호출하는 API 도메인은 아래와 같다.

• seller-api (셀러)
• partner-api (관리자)
• order-api (주문/결제 )
• main-api (중고나라 메인)
• edge-api (이미지)

해당 API를 개발한 팀들이 다르다 보니 데이터를 반환하는 형식이 다르게 설계되어 있었다.

그래서 클라이언트 내부적으로 공통 컴포넌트를 만들어놓았지만, 만약 한 페이지에 여러 도메인의 API를 호출했을 경우에는 이를 클라이언트 형식에 맞게 변환하는 과정이 페이지 내부에 여러 유틸이 들어감으로써 가독성이 떨어지는 현상이 발생하였다.

 

더불어 변환하는 과정을 모두 모듈로 관리하지 않았기 때문에,
해당 방식 또한 개발자마다 스타일이 달라져 코드의 흐름을 파악하기 어려웠다.

 

하지만, 어드민 시스템의 특성상 테이블을 사용하는 페이지, 정보를 보여주는 페이지는 일관성을 가지도록 구현되는 것이 필요했고

뷰의 요소만이 아닌 내부 코드 시스템도 동일하게 관리되어야 추가 기능에 대해 여러 페이지를 한 번에 대응하는 것이 가능해진다고 느껴졌다.

 

이 3가지의 이유로 나는 어떤 특정 규격에 따른 코드 베이스를 가지면서 확장성을 고려한 기술의 도입이 필요하다고 판단했다. 

---

🖤 Refine의 간략한 특징

그렇게 찾게 된 기술이 바로 Refine이다. 공식 문서에는 아래와 같이 설명되어 있다.

React 기반 내부 도구, 관리자 패널, 대시보드 및 엔터프라이즈급 비즈니스 애플리케이션을 구축하도록 설계된 오픈소스 프레임워크이다. CRUD, 상태 관리와 같은 일반적인 기능을 처리하기 위한 자동화 세트를 제공하여 개발 프로세스를 간소화한다.
이를 통해 개발자는 반복적인 코딩 작업을 피하고 프로젝트의 더 복잡한 측면에 집중할 수 있다.

 

기본적으로 해당 기술은 Ant Design, Material UI, Shadcn/ui와 같은 UI 프레임워크와 통합도 가능했다.

Next.js, React Router, Remix도 지원하는 강력한 tool로 사용되고 있었다.

 

그렇다면 어떤 반복적인 코딩 작업을 피할 수 있는 것일까?

refine이 제시하고 있는 컨셉은 Headless,  Resource, Provider, Hook 총 4가지이며 자세한 내용은 문서를 통해 확인할 수 있기에 핵심 컨셉인 provider와 resource만 살펴보겠다. 

 

1️⃣ Provider의 개념

provider에도 data-provider, authentication-provider, access control-provider, notification-provider등 다양한 provider가 존재한다. 핵심은 data-provider이며 이는 백엔드 데이터와 get, post, path, delete와 같은 데이터 작업을 처리하는 provider이다.

import { DataProvider } from '@refinedev/core';

export const provider = ({
  httpClient,
}: {
  httpClient: AxiosInstance;
}): DataProvider => ({
  getOne: async ({ resource, id, meta }) => {
    const url = `${apiUrl}${resource ? `/${resource}` : ''}${id ? `/${id}` : ''}`;

    try {
      const { data } = await httpClient[requestMethod](url, { headers });
      return { data: data.data || data.meta };
    } catch (error) {
      return Promise.reject(getHttpError(error));
    }
  },

  update: async ({ resource, id, variables, meta }) => {
    ...
  },

  create: async ({ resource, variables, meta }) => {
   ...
  },

  deleteOne: async ({ resource, id, variables, meta }) => {
   ...
  },

  getList: async ({ resource, pagination, sorters, filters, meta }) => {
   ...
  },

  getApiUrl: () => apiUrl || '',
});

 

이렇게 provider내부에는 getOne, update, create, deleteOne, getList, getApiUrl과 같은 메서드들이 정의되어 있으며

백엔드의 도메인에 따라 각 provider를 만들어 데이터를 관리하는 것이 가능한 구조이다.

 

2️⃣ Resource의 개념

리소스로 도메인별 entity를 정의하고, 해당 페이지에서 간단한 API 호출 방식으로 코드의 동작을 추상화하는 것이 가능해진다.

아래의 코드로 이해 해보자.

import { Refine } from "@refinedev/core";

export const App = () => {
  return (
    <Refine
      resources={[
        {
          name: "seller",
          list: "/account",
          show: "/account/:id",
          edit: "/account/:id/edit",
        },
      ]}
    >
      {/* ... */}
    </Refine>
  );
};

 

resource의 이름으로 seller를 정의해 두고, 셀러의 리스트를 불러오는 페이지의 경로를 list에 지정하고, 특정 셀러의 정보를 보여주는 페이지의 경로를 show에 지정하고, 특정 셀러의 정보를 편집하는 경로를 show에 지정하는 코드이다.

 

이렇게 되면, /account 페이지는 useList라는 훅을 호출하면 provider의 getList가 자동으로 호출되고

/account/:id 페이지에서는 useShow라는 훅을 호출하면 provider의 getOne이 자동으로 호출되고,

/accoun/:id/edit 페이지에서는 useUpdate라는 훅을 호출하면 provider의 update이 자동으로 호출된다.

 

즉, 내가 페이지에서 사용할 api의 자원을 미리 정의해 둠으로써 페이지 내부에서는 해당 과정을 구현할 필요 없이 응답 값에 대한 데이터 렌더링 및 사용자의 동작에만 집중할 수 있게 되는 것이다.

---

📃 우리가 검증한 내용들

refine의 기술 자체는 너무나 매력적으로 다가왔으나, Next.js , react-query, shadcn/ui와 같은 기본적인 툴로도 이미 셀러지원센터의 기능을 만들어갈 수 있는 능력이 있는 상태에서 해당 기술을 이관하는 것으로 앞선 3가지의 문제를 해결해 줄 수 있을까..? 에 대한 검증 절차는 필요하다고 생각했다. 

 

 

✅ interceptor 로직의 사용 가능 여부 및 데이터 변환 과정의 위치

먼저, 셀러와 관리자의 인증/인가 로직은 Axios의 interceptor의 내부에서 관리되고 있었기에 해당 모듈을 그대로 적용할 수 있는지 파악해 보았다. 해당 모듈을 적용하는 것이 가능했고, app router에서 server component와 client component에 따라 다르게 실행될 수 있도록 분리하는 것도 가능하였다. 

 

이를 기반으로 앞선 문제였던 데이터 변환 과정의 분산화를 해결하는 것이 가능한지 검증했다.

우선 data provider를 각 도메인으로 분리해 보았다.

• sellerProvider
• adminProvider
• orderProvider
• mainProvider
• edgeProvider

그리고 데이터를 반환하여 클라이언트에게 전달할 때는 동일한 규격을 가지도록 각 provider에 데이터 변환 과정을 도입하였다.

// sellerProvider
...
	getOne: async ({ resource, id, meta }) => {
        const url = `${apiUrl}${resource ? `/${resource}` : ''}${id ? `/${id}` : ''}`;
        const { headers, method } = meta ?? {};
        const requestMethod = (method as MethodTypes) ?? 'get';

        try {
          const { data } = await httpClient[requestMethod](url, { headers });
          return { data: data.data || data.meta };
        } catch (error) {
          return Promise.reject(getHttpError(error));
        }
  },
...

// orderProvider

...
	getList: async ({ resource, pagination, sorters, filters, meta }) => {
        const [countUrl] = resource.split('/list');
        const url = `${apiUrl}/${resource}`;

        const { headers: headersFromMeta, method, convertData } = meta ?? {};
       	
        ...
       
        try {
          const { data, headers } = await httpClient[requestMethod](
            `${url}?${queryString ? `${queryString}&` : ''}page=${pagination?.current}&size=${pagination?.pageSize}`,
            {
              headers: headersFromMeta,
            },
          );
          if (convertData) {
            const clientData = convertData({ data: data.data.results });
            return {
              data: clientData,
              total: data.data.page.totalCount,
            };
          }
          return {
            data: data.data.results || data.data,
            total: data.data.page.totalCount,
          };
        } catch (error) {
          return Promise.reject(getHttpError(error));
        }
      },
...

 

위의 코드처럼 셀러와 주문/결제 도메인에서 데이터를 가공하는 형식이 다르게 구현되어 있었지만, 데이터를 반환하는 구조를 객체 형식으로 통일시킴으로써 해당 데이터를 사용하는 곳에서는 data.{데이터타입} 으로 접근하여 사용하는 것이 가능해졌다.

 

이를 통해 분산된 코드들을 provider라는 객체 안에서 도메인별로 관리할 수 있게 되었다. 

 

✅ Data Table 호출 방식

기존에 table을 호출하는 구조는 아래와 같았다.

export default function AccountPage() {

  // 테이블 하단 페이지네이션 버튼 핸들러 커스텀 훅
  const { previousBtnInfo, handleNextBtn, handlePageSize } =
    useDataTableHandlers({ isNamePageSize: true });

  const filter = 테이블 필터 검색으로 API 호출 쿼리파라미터 받아오기;

  const { data: sellerList, error } = useQuery(셀러 리스트 불러오기);
  const { data: pageCount } = useQuery(리스트 관련 페이지 정보 불러오기);

  // 다음 페이지 네이션 버튼 이벤트 객체 
  const nextBtnInfo = {
    handleNextBtn,
    disabled: isNextBtnDisable({
      dataLength: sellerList?.length,
      pageCount,
      query,
    }),
  };

  return (
    <ContentLayout className="p-5">
      <Filter />
      <DataTable
        columns={columns}
        data={sellerList || []}
        previousBtnInfo={previousBtnInfo}
        nextBtnInfo={nextBtnInfo}
        pageCount={pageCount}
        pageSize={Number(query.pageSize) || 10}
        handlePageSize={handlePageSize}
      />
    </ContentLayout>
  );
}

 

Data Table을 사용하기 위해서는 테이블에 주입할 리스트 정보, 테이블 하단 페이지 네이션 버튼 정보 및 핸들러, 리스트 테이블의 페이지 사이즈 및 페이지 수들을 페이지 단에서 만드는 과정이 필요했다.

 

보안상 모든 코드를 공개할 수 없어 압축하였지만, 해당 페이지 내부에서는 useQuery 호출 시 select를 사용하는 과정도 포함되어 있었다.

더불어 filter의 검색 버튼 이벤트로 만들어진 query를 API 호출 시, 쿼리 파라미터로 전달하기 위한 과정과 테이블을 관리하는 페이지 네이션에 대한 정보를 외부에서 주입받아 사용하는 로직으로 인해 가독성이 떨어지는 상태였다.

 

refine에서는 React table을 활용한 useTable 훅을 제공하고 있었고, 해당 훅을 사용할 때, resource를 명시해 주면 해당 훅 내부에서 resource에 맞는 provider를 호출하여 반환한 데이터를 내부적으로 뿌려주도록 구현되어 있었다.

 

이를 적용한 코드이다.

export default function AccountPage() {
  const { params } = useParsed();
  return (
    <DataTable
      columns={columns}
      refineCoreProps={{
        resource: 셀러리스트정보,
        meta: params?.filters,
        dataProviderName: 셀러제공자,
        queryOptions: { refetchOnMount: true },
      }}
      FilterComponent={Filter}
    />
  );
}

 

같은 페이지를 구현한 내용인데, 이전 버전 보다 확실히 코드의 양의 줄어들었다는 것을 확인할 수 있다.

코드가 줄어들었다고 해서 좋은 코드라고는 보장할 수 없기에 직관성을 검증해 보자.

 

Data Table을 만들기 위해 refineCoreProps로 자원의 정보, 테이블 필터 정보를 params.filters로,  dataProvider의 이름을 명시적으로 작성하고, 원하는 queryOptions과 해당 페이지에서 필요한 Filter Component를 주입하였다.

 

어떤 자원으로, 어떤 API를 호출하고, 어떤 필터를 적용할 건지만
선언적으로 전달하면 테이블을 만들 수 있게 되었다.

 

이전보다 훨씬 개발자 경험이 개선되었음을 경험할 수 있었다.

 

✅ Filter Component 사용 방식

기존에 사용하고 있던 Filter component의 구조이다.

export default function Filter() {
  const { query } = useRouter();
  const methods = useForm<FormValues>({
    defaultValues: { ...defaultValues, ...query },
  });
  const { getValues, setValue } = methods;

  // 필터를 query로 전달하여 page에서 해당 query를 파싱하여 호출 파라미터로 전달하기위한 push
  const onSubmit = () => {
    push({ query: { ...query, ...getValues(), page: 1 } });
  };

 // api 마다 pageSize, size로 전달할지 파악하는 effect
  useEffect(
    function setPagesize() {
      if (query.pageSize) setValue('pageSize', Number(query.pageSize));
    },
    [query?.pageSize],
  );

  return (
    <Form {...methods}>
  	// ... 필터 요소들 렌더링
    </Form>
  );
}

 

필터들에 대한 검색 버튼의 submit함수로 push 이벤트를 발생시키며, 이를 통해 page에서는 path의 query 변화를 감지하여 API 호출 시, 해당 필터를 호출 파라미터로 변환하여 원하는 필터값에 해당하는 리스트를 다시 불러오는 구조로 설계되어 있었다.

 

추가로 도메인마다 페이지의 사이즈를 호출하는 파라미터의 key가 pageSize 또는 size로 나뉘어 있어 이를 검증하여 setValue를 진행하는 effect도 구현되어 있었다.

 

그러나 refine에서 제공하는 useTable과 data-provider를 사용하게 되면서 Filter component의 사용 방식도 바뀌게 되었다.

export default function Filter<TData>({ ids, getColumn }: FilterProps<TData>) {
  const methods = useForm<FormValues>({
    defaultValues: { ...defaultValues },
  });
  const { handleSubmit, reset, control, getValues } = methods;

  const onClickSearch = () => {
    const filterValues = getFilterValues({ formValue: getValues() });
    setFilterValue({
      ids,
      filters: [...filterValues] as LogicalFilter[],
      getColumn,
    });
  };
  
  return (
     <Form {...methods}>
      ...
    </Form>
  );
}

 

API 호출 시 pageSize인지, size인지 검증하는 내용은 provider 내부로 들어가게 되어
필터 컴포넌트에서는 필터 검색시 발생되는onClickSearch 이벤트에서 useTable에 검색 조건으로 주입할 filter의 값만 형식에 맞게
가공하여 setFilterValue의 과정만 거치게 되었다.

 

테이블을 만드는 방식도, 필터를 만드는 방식도 UI에만 집중할 수 있는 구조로 개선된 것을 확인할 수 있다.

 

+ 다른 라이브러리와의 호환성

셀러지원센터의 확장성을 고려했을 경우, 추후에 또 다른 기능들이 요구되었을 때 다른 기술들을 설치할 수 있는지 확인해 보는 과정도 진행했다. 확인 결과, refine에서 사용하고 있는 TanStack query의 버전을 5 이상으로 올리지만 않으면 다른 라이브러리는 수월하게 설치됨을 파악하였다.

 

이러한 근거를 기반으로 이전에 발견되었던 3가지의 문제를 해결해 주는 것으로 판단하여,

최종적으로 셀러지원센터의 개발 환경을 refine으로 이관하는 것으로 결정하였다...!!!!!!

 

📁 폴더구조도 개편하자..!

추가로 셀러지원센터 1차,2차 개발을 당시 폴더구조는 아래와 같았다.

├── 📁 src
│  ├── 📁 api
│  ├── 📁 components
│  ├── 📁 constants         
│  ├── 📁 hooks
│  ├── 📁 lib
│  ├── 📁 pages
│  ├── 📁 styles
│  ├──📁 types              
...
└── tsconfig.json

 

프론트엔드 개발자라면 익숙한 폴더구조일 것이다.

하지만, 1차, 2차 개발과 오류 개선 작업을 진행하면서 해당 작업을 위한 개발자 경험의 비효율을 체감하게 되었다.

 

과정은 아래와 같다.

1. 특정 페이지에서 오류 발생
2. 해당 페이지를 탐색하기 위해 src/pages/{페이지 이름} 접근
3. 오류 발생 컴포넌트 파악
4. 해당 컴포넌트 접근을 위해 components/{페이지 이름} 폴더로 이동
5. 내부적으로 api나 상수, 유틸 함수에서 오류가 발생했다면 다시 {api, constants, utils}/{페이지 이름} 폴더로 이동

모두가 알겠지만, 프로젝트에서 1개 또는 2개의 페이지만 있는 것이 아니기 때문에 해당 과정을 진행하기 위해서는 vscode 좌측에서 스크롤을 위아래로 진행하는 과정이 길고 오래 발생하게 되었다.

 

버그를 수정하는 것보다 폴더를 찾는 과정으로 인해 피로도가 증가하는 것을 느꼈다.

├── 📁 src
│  ├── 📁 identifier               
│  ├── 📁 resources                
│  ├── 📁 shared                //셀러 & 관리자 도메인에서 공유되는 폴더
│  │    ├── 📁 components             
│  │    ├── 📁 hooks
│  │    ├── 📁 api
...
│  ├── 📁 admin
│  │    ├── 📁 shared             // 관리자 도메인에서 공유되는 폴더
│  │    ├── 📁 account
...
│  ├── 📁 seller
│  │    ├── 📁 shared             // 셀러 도메인에서 공유되는 폴더
│  │    ├── 📁 info 
            ├── 📁 components       // 컴포넌트 👉 하위폴더명 (파스칼케이스.tsx)
            ├── 📁 hooks            // 커스텀훅 👉 하위폴더명 (카멜케이스.tsx)          
            ├── 📁 utils            // 유틸함수 👉 하위폴더명 (카멜케이스.tsx)
            ├── 📁 types     
            │     └── index.ts     // types, constants, models, zods 👉 하위폴더명 (index.ts)
            ├── 📁 constants
            │     └── index.ts
            ├── 📁 models
            │     └── index.ts   
            ├── 📁 zods
            │     └── index.ts     
            └──  📁 api               // api 통신 관련

...
│  ├── 📁 app
│  │    ├── 📁 admin
│  │    ├── 📁 seller 
│  │    ├── _app.tsx     
│  │    ├── _document.tsx
│  │    └── index.tsx
...
└── tsconfig.json

 

그래서, refine으로 이관 작업을 진행하면서 폴더 구조를 위와 같이 관심사별로 개편하는 작업도 함께 진행하여 개발자 경험을 개선하고자 했다. 참고했던 내용은 FSD 아키텍쳐이다. 

 

최상위 폴더들을 페이지 기반으로 나누면서, 내부적으로 components, hooks, types, utils, constants, zods, api 등과 같은 폴더를 만들어 특정 페이지 폴더에서 기능들을 탐색하고, 구현할 수 있도록 구조를 만들어 스크롤에 소요되는 시간을 단축했다.

 

물론 페이지가 늘어날수록 폴더의 깊이와 수가 늘어나는 것이 단점이 될 수도 있다고 생각한다.

하지만, 스크롤이 단축되는 이점이 있었기에 해당 구조를 사용하고자 했다.

---

🤔 그래서 이관 이후, 개발자 경험은 어떻게 달라졌을까..?

처음에는 refine이 제공하는 훅과 구조를 벗어나지 않게 코드를 작성해야 하는 것이 이전 버전에서는 존재하지 않았기에 불편함을 초래하기도 했었다.

 

하지만, 오히려 refine이라는 특정 규격에 맞게 작성해야 하는 것이 일관성 있는 코드를 만들어주었기 때문에 개발자마다 다른 코드 스타일이 대폭 축소되어 내가 구현한 코드가 아니어도 수정하는 것이 수월해졌다.

 

더불어 refine이 정해준 틀이 있지만, 그 안에서 컴포넌트와 로직을 커스텀하는 과정도 가능하다는 장점이 있었기에

개발자가 원하는 추상화 방식이 있다면 도입하는 것도 문제없이 진행할 수 있었다.

 

장기적으로 보았을 때, Refine 이관 작업으로 셀러지원센터의 확장과 유지/보수에 개발 생산성을 높일 수 있게 되었다.

---

👩🏻‍💻 개발적으로 내가 느꼈던 내용

셀러지원센터 웹 개발팀 리딩을 진행하며, 프로젝트를 개발하고 일정 관리를 하고 있는 경험도 새로운 도전의 차원에서 의미있는 경험이었다. 하지만, 프로젝트의 규모를 키워나가는 시점에서 좋은 DX를 제공하면서 빠르게 확장할 수 있는 방법을 코드베이스에서 고민할 수 있었다는 것이 개발자의 시야를 넓혀주게 된 시간이었던 것 같다.

 

특히, 이를 단순히 어떤 패턴을 도입하는 차원에서의 해결점이 아닌 기술적인 차원에서 방법을 모색하고 검증하는 과정이 흥미로웠던 순간이었다.