ADR011: 플러그인 패키지 구조
Backstage의 핵심 기능은 플러그인을 통한 확장성입니다. 핵심 기능조차 대부분 플러그인으로 구현됩니다.
출처: 문서
본문
맥락
Backstage의 핵심 기능은 플러그인을 통한 확장성입니다. 핵심 기능의 대부분도 플러그인으로 구현됩니다. 플러그인은 plugins/ 디렉토리의 하나 또는 여러 패키지로 구성됩니다. 지금까지 우리는 플러그인 패키지 이름에 대한 간단한 규칙을 가졌습니다. 플러그인은 x라는 이름을 가지며, 관련 백엔드 플러그인은 x-backend(여기서 x는 catalog 또는 techdocs 같은 플러그인 이름)라는 옵션을 가질 수 있습니다. 플러그인의 프론트엔드와 백엔드 간에, 백엔드 플러그인 간에, 또는 서로 다른 프론트엔드 플러그인 간에 구성 요소와 훅을 공유해야 할 필요가 있습니다(일부 예시). 이로 인해 packages/catalog-client 또는 packages/techdocs-common 같은 공유 코드를 가진 플러그인 패키지가 생겨나고 있습니다.
소프트웨어 개발에는 흔한 말이 있습니다. 이름 짓기는 어렵다(Naming things is hard)
기여된 플러그인을 일관되게 유지하기 위해, 이 ADR은 플러그인 패키지 이름에 대한 규칙을 제공합니다.
결정
모든 플러그인 관련 코드를 plugins/ 디렉토리에 배치할 것입니다. packages/ 디렉토리는 Backstage의 핵심 패키지 전용으로 예약됩니다.
플러그인 패키지에 대해 다음 구조를 따릅니다(여기서 x는 catalog 또는 techdocs 같은 플러그인 이름).
-
x: 플러그인의 주요 프론트엔드 코드를 포함합니다. -
x-module-<name>: 프론트엔드 플러그인 패키지와 관련된 선택적 모듈을 포함합니다. -
x-backend: 플러그인의 주요 백엔드 코드를 포함합니다. -
x-backend-module-<name>: 백엔드 플러그인 패키지와 관련된 선택적 모듈을 포함합니다. -
x-react: 플러그인 자체(x)와 서드파티 프론트엔드 플러그인이 모두 의존할 수 있는 공유 위젯, 훅 등을 포함합니다. -
x-node: 플러그인 백엔드 자체(x-backend)와 서드파티 백엔드 플러그인이 모두 의존할 수 있는 백엔드용 유틸리티를 포함합니다. -
x-common: 위의 모든 패키지 또는 어떤 서드파티 플러그인 패키지든 의존할 수 있는 플랫폼에 구애받지 않는 모델, 클라이언트, 유틸리티를 가진 동형(isomorphic) 패키지입니다.
패키지 이름에 @backstage/plugin- 접두사를 붙입니다.
이 구조는 issue #3655의 제안에 기반합니다.
결과
우리는 플러그인의 일부인 기존 패키지들을 plugins/ 폴더로 적극적으로 마이그레이션할 것입니다. 이는 다음과 같은 패키지에 영향을 미칩니다.
-
packages/techdocs-common은plugins/techdocs-node로 이동해@backstage/plugin-techdocs-node로 명명해야 합니다. -
packages/catalog-client는 향후plugins/catalog-common의 일부가 되어@backstage/plugin-catalog-common으로 명명될 것입니다. -
packages/catalog-model의 새 위치는plugins/catalog-common이어야 하지만, 매우 중심적인 패키지이므로 여기서는 예외를 두고 싶을 수 있습니다.
우리는 백엔드 플러그인의 선택적 기능들을 예를 들어 카탈로그 백엔드의 더 특수화된 프로세서처럼 별도의 x-backend-module-<name> 패키지로 적극적으로 마이그레이션할 것입니다.
제한된 규칙 집합이 미래에는 충분하지 않을 수 있습니다. 추가 패키지가 필요하면 이 결정을 재검토하고 패턴을 확장할 것입니다.
가능하다면 lint 규칙 같은 도구를 추가해 패키지 이름과 패키지 간 의존성을 강제하거나, 이 패키지들을 생성하는 CLI 명령을 도울 것입니다.
핵심 패키지와 플러그인의 구분은 저장소에서 CODEOWNERS를 설정하는 데 도움이 됩니다. packages/ 폴더의 코드 소유자를 핵심 팀으로 설정하고, 플러그인 관리자를 위한 추가 규칙(예: plugins/x*)을 만들 수 있습니다.