Optistream은 1,000개의 공개 페이지 중 어느 것도 SEO를 잃지 않으면서 12개의 커스텀 WordPress 플러그인을 하나의 코드베이스로 통합했습니다.

통합이 중요했던 이유

일반적인 WordPress 사이트는 몇 개의 플러그인을 사용하지만, 규모가 큰 사이트는 마치 전선이 가득한 작업실처럼 보입니다. 각 전선은 작동 중이지만 어느 것도 쉽게 뽑을 수 없는 상태죠. Optistream의 사이트는 스트리머 프로필, e스포츠 팀, 게임 데이터를 처리하는 12개의 맞춤형 플러그인을 실행하고 있었습니다. 이 플러그인들은 1,000개의 인덱싱 가능한 페이지를 생성했습니다. 이러한 URL을 그대로 유지하는 것은 타협할 수 없는 조건이었습니다. 작은 변화라도 발생했다면 마이그레이션은 실패했을 것입니다.

기존 설정의 모습

12개의 플러그인은 각각 별도의 폴더에 존재하며, 자체적인 커스텀 포스트 타입(custom post type)을 등록하고 WordPress의 서로 다른 지점에 훅(hook)을 걸고 있었습니다. 다음과 같은 문제들이 쌓여갔습니다:

  • 훅(hook)과 에셋(asset)이 흩어져 있어 어떤 코드가 언제 실행되는지 예측하기 어려웠습니다.
  • 라우팅 로직이 여러 별개의 파일에 나뉘어 있어, 단일 URL이 여러 플러그인의 영향을 받을 수 있었습니다.
  • CSS 파일이 예측할 수 없는 순서로 로드되어 스타일 충돌이 발생했습니다.
  • 디버깅을 위해 12개의 서로 다른 디렉토리를 열어야 했으며, 이는 개발자에게 큰 시간 낭비였습니다.

목표는 파일 수를 줄이는 것이 아니었습니다. 시스템 전체에 단일 라이프사이클을 부여하고 의존성을 관리할 수 있는 단일 지점을 만드는 것이었습니다.

마이그레이션 계획 수립 방식

팀은 공개 인터페이스(URL, 템플릿, 메타데이터)를 깨뜨려서는 안 되는 '계약'으로 간주했습니다. 프론트엔드에서 무엇이라도 변경된다면 그것은 실패를 의미했습니다. 이 규칙을 염두에 두고, 매 단계마다 실행할 체크리스트를 작성했습니다.

1. 공개 계약 목록 작성

모든 URL 경로를 포스트 타입, rewrite slug, 템플릿 파일, 그리고 의존하는 메타 키(meta key)와 함께 기록했습니다. 이 스프레드시트는 규칙서가 되었습니다. 모듈 이동 후 URL이 변경되면 마이그레이션을 롤백했습니다.

2. 단순한 로더 구축

아주 작은 부트스트랩(bootstrap) 파일을 생성했습니다. 기존의 각 플러그인은 이제 예측 가능한 함수 이름을 통해 단일 "콘텐츠 도메인(content domain)"을 등록합니다. 로더는 복잡한 기능을 수행하지 않습니다. 필요할 때 적절한 모듈을 WordPress로 불러오는 기능만 수행합니다. 단순함 덕분에 오류가 발생하면 즉시 파악할 수 있습니다.

3. 데이터 보호

메타 키의 이름을 변경하는 것은 코드 변경을 데이터 마이그레이션으로 변질시켜 불필요한 리스크를 초래할 수 있었습니다. 기존 키는 그대로 유지하고, 새로운 헬퍼 함수(helper function)로 이를 감싸 데이터베이스 스키마를 안정적으로 유지했습니다.

4. CSS 소유권 해결

스타일 충돌은 세 가지 조치를 통해 해결했습니다:

  • 모듈 CSS 파일은 가장 마지막에 로드되도록 높은 우선순위로 인큐(enqueue)합니다.
  • 모든 셀렉터(selector)는 각 모듈의 고유한 래퍼 클래스(wrapper class)로 스코프(scope)를 지정합니다.
  • 스타일시트가 변경될 경우 브라우저 캐시를 무효화하기 위해 인큐 시 filemtime()을 사용합니다.

5. 안전한 루프 사용

마이그레이션은 한 번에 하나의 모듈씩 진행되었습니다. 모듈을 이동한 후, 다음 모듈로 넘어가기 전에 포스트 타입 등록, 라우팅 및 모바일 레이아웃을 검증했습니다. 기존 플러그인들은 설치된 상태로 비활성화해 두어, 즉각적인 롤백 경로를 확보했습니다.

운영 체크리스트

각 모듈 교체 후 팀은 다음 사항을 확인했습니다:

  • 모든 콘텐츠 타입 URL이 200 HTTP 상태 코드를 반환하는지 확인합니다.
  • canonical URL 헤더가 원래 URL과 일치하는지 확인합니다.
  • 페이지 제목과 메타 설명이 변경되지 않았는지 확인합니다.
  • 모든 이미지가 깨진 링크 없이 로드되는지 확인합니다.
  • 모바일 화면에서 가로 스크롤(horizontal overflow)이 발생하지 않는지 확인합니다.
  • 브라우저 콘솔에 JavaScript 또는 CSS 오류가 없는지 확인합니다.

체크리스트를 모두 통과한 후에야 팀은 기존 플러그인을 영구적으로 비활성화했습니다.

새로운 플러그인이 제공하는 가치

결과적으로 탄생한 단일 플러그인은 코드베이스의 크기를 줄이지 않았습니다. 대신 경계를 명확하게 시각화했습니다. 이제 12개의 모든 기능 영역이 하나의 라이프사이클, 하나의 훅 세트, 그리고 하나의 의존성 관리 지점을 공유합니다. 새로운 플러그인은 시스템을 작게 만든 것이 아니라, 경계를 보이게 만들었습니다. 이는 단순히 플러그인 개수를 줄이는 것보다 훨씬 유용하다는 것이 증명되었습니다.

리스크 및 반론

Optistream 사례는 규율 있는 '계약 우선(contract-first)' 접근 방식과 단계별 배포가 리스크를 효과적으로 제어할 수 있음을 보여줍니다.

향후 주의 사항

유사한 통합을 고려하고 있다면, 다음 두 가지 핵심 원칙부터 시작하십시오:

  1. URL 안정성 – 코드를 한 줄이라도 쓰기 전에 모든 공개 경로를 매핑하십시오.
  2. 데이터 안정성 – 전체 마이그레이션을 수행할 준비가 되어 있지 않다면 데이터베이스 필드 이름을 변경하지 마십시오.

그다음, 아주 작은 로더를 구축하고, CSS 스코프를 유지하며, 엄격한 운영 체크리스트를 실행하면서 모듈을 하나씩 이동하십시오.