💁🏻‍♀️ Gato GraphQL이 모노레포를 필요로 하는 이유와 최적화 방법

며칠 전, Hosting all your PHP packages together in a monorepo 라는 글을 게시했습니다. 그 글에서는 PHP 코드베이스 관리에 모노레포를 활용하고 싶은 이유와, Monorepo Builder를 통해 이를 실현하는 방법을 설명했습니다.

여기서는 그 글을 보완하는 형태로, GatoGraphQL/GatoGraphQL 코드베이스（Gato GraphQL, 그 기반이 되는 GraphQL 엔진, 그리고 그 위에 구축된 컴포넌트 모델 아키텍처를 호스팅하고 있습니다）가 모노레포에서 호스팅되어야 하는 이유와, 제가 수행한 최적화에 대해 좀 더 자세히 설명하겠습니다.

​

Gato GraphQL이 모노레포를 필요로 하는 이유

CMS 비종속성을 지원하기 위해, Gato GraphQL 및 관련 프로젝트의 코드베이스는 Composer로 관리되는 수많은 패키지로 분리되었습니다. 총 100개 이상의 패키지가 생성되었습니다！（현재는 200개 이상입니다.）

패키지 수가 많아도 Composer로 모두 조합하는 데 추가적인 복잡함은 없습니다. composer install을 실행하기만 하면 모든 것이 작동합니다. 그러나 각 패키지가 개별 저장소에 존재하면 버전 관리 문제로 인해 개발이 어려워집니다.

각 패키지는 버전 관리가 필요하며, 어떤 패키지의 모든 버전은 다른 패키지의 특정 버전에 의존합니다. 이렇게 많은 패키지가 있으면, PR 생성 시 모든 버전이 서로 어떻게 의존하는지 설정하는 것은 악몽이 될 수 있으며, 마치 스파게티 코드 한 접시처럼 면의 한쪽 끝은 보이지만 어디서 끝나는지는 알 수 없는 상태가 됩니다.

실제로, 관련된 모든 저장소의 여러 브랜치에 걸친 버전을 모두 연결하는 것이 너무 어려워져서, 이 과정을 완전히 건너뛰고 각 저장소의 master 브랜치에 코드를 직접 푸시하고 각각에서 dev-master 버전에 의존하게 되었습니다.

이는 적절하지 않았습니다. 모든 코드를 GatoGraphQL/GatoGraphQL에 호스팅하는 모노레포 모델로 전환함으로써, 그 문제가 효과적으로 해결되었습니다.

​

환영할 만한 부작용: 기여의 진입 장벽 낮추기

글에서도 언급했듯이, 프로젝트가 패키지마다 하나의 저장소를 사용하던 시절, 한 기여자가 개발 환경 설정에 실패하여 참여하기도 전에 프로젝트를 떠난 일이 있었습니다.

모노레포로 전환하기 전에는 개발 환경 설정이 매우 어려웠습니다. 저는 작성자였기 때문에, 모든 저장소를 클론하고 단일 VSCode 워크스페이스에 모두 추가하여 어떻게든 작동시킬 수 있었습니다.

잠재적인 기여자들이 동일한 환경을 설정하기 쉽도록 이 bash 스크립트를 통해 시도했습니다. 하지만 솔직히, 그것은 처음부터 불가능한 일이었고, 아무도 프로젝트에 기여를 시작할 수 없었습니다.

모노레포 덕분에, 누군가가 참여하고 싶을 때 불합리한 관료주의로 기여자를 거부하지 않을 것이라는 확신을 가지고 밤에 편안히 잠들 수 있게 되었습니다.

​

모노레포 최적화

글에서 언급했듯이, 대안들과 비교하여 Monorepo Builder 라이브러리를 사용하는 장점은 PHP로 구축되어 있어 확장 가능하다는 것입니다.

예를 들어, master에 푸시하고 모노레포를 분할할 때, GitHub Action의 매트릭스는 일반적으로 각 패키지에 대해 하나의 러너 인스턴스를 생성하여 해당 코드를 자체 저장소와 동기화합니다（Packagist를 통한 배포를 위해）.

GatoGraphQL/GatoGraphQL에는 200개 이상의 패키지가 포함되어 있어, 200개 이상의 러너 인스턴스가 실행되고 있었습니다.

여기서 문제는 GitHub가 병렬로 실행 가능한 작업 수를 20개로 제한하고 있다는 점입니다. 모든 액션이 큐에 배치되므로, 다른 액션을 계속 실행하려면 완료될 때까지 기다려야 했습니다.

게다가, GitHub가 러너를 즉시 프로비저닝하지 않고 나중으로 미루는 경우도 종종 있었습니다:

이 모든 것이 대기 시간으로 이어집니다. 200개 이상의 패키지가 있으면, 단 하나의 PR을 병합하는 데 최대 1시간이 걸릴 수 있었습니다！ 이는 해결이 필요한 문제였습니다.

커스텀 명령으로 모노레포를 확장하면 이 문제를 해결할 수 있습니다.

​

Monorepo Builder 확장하기

일반적으로 다음 명령을 실행하면 저장소의 모든 패키지 목록을 가져올 수 있습니다:

vendor/bin/monorepo-builder packages-jsonCopy

그런데 이런 생각이 들었습니다: 모든 패키지를 동기화할 필요는 없고, PR에서 변경된 코드가 포함된 패키지만 동기화하면 된다고요.

변경된 파일 목록을 파악할 수 있다면, 해당 파일을 포함하는 변경된 패키지를 특정할 수 있습니다. 즉, git diff를 실행하고 그 결과를 filter 입력으로 packages-json 명령에 전달하는 것입니다. 다음과 같이:

vendor/bin/monorepo-builder packages-json --filter=modified_file_1 --filter=modified_file_2 --filter=...Copy

그런데 Monorepo Builder에 포함된 packages-json 명령은 filter 입력을 지원하지 않습니다. 바로 이 부분이 커스텀 명령으로 확장해야 하는 곳입니다.

Monorepo Builder는 Symfony의 DependencyInjection을 사용하므로, 컨테이너에 새 서비스를 주입하여 확장할 수 있습니다. 실제로, 설정 파일 monorepo-builder.php는 이미 서비스 컨피규레이터입니다.

그래서 저는 filter 입력을 지원하는 package-entries-json이라는 새 명령으로 Monorepo Builder를 확장했습니다:

final class PackageEntriesJsonCommand extends AbstractSymplifyCommand
{
  private PackageEntriesJsonProvider $packageEntriesJsonProvider;
 
  public function __construct(PackageEntriesJsonProvider $packageEntriesJsonProvider)
  {
    $this->packageEntriesJsonProvider = $packageEntriesJsonProvider;
 
    parent::__construct();
  }
 
  protected function configure(): void
  {
    $this->setDescription('Provides package entries in json format. Useful for GitHub Actions Workflow');
    $this->addOption(
      Option::FILTER,
      null,
      InputOption::VALUE_OPTIONAL | InputOption::VALUE_IS_ARRAY,
      'Filter the packages to those from the list of files. Useful to split monorepo on modified packages only',
      []
    );
  }
 
  protected function execute(InputInterface $input, OutputInterface $output): int
  {
    /** @var string[] $fileFilter */
    $fileFilter = $input->getOption(Option::FILTER);
 
    $packageEntries = $this->packageEntriesJsonProvider->providePackageEntries($fileFilter);
 
    // must be without spaces, otherwise it breaks GitHub Actions json
    $json = Json::encode($packageEntries);
    $this->symfonyStyle->writeln($json);
 
    return ShellCode::SUCCESS;
  }
}Copy

서비스 컨테이너에는 다음과 같이 주입됩니다:

return static function (ContainerConfigurator $containerConfigurator): void {
    $services = $containerConfigurator->services();
    $services->defaults()->autowire()->autoconfigure();
    $services->set(PackageEntriesJsonCommand::class);
}Copy

이제 package-entries-json이라는 새 명령을 GitHub Action 워크플로에서 사용할 수 있게 됩니다.

​

GitHub Action에서 변경된 파일 목록 가져오기

이제 워크플로를 업데이트하는 방법을 살펴보겠습니다.

저는 편리하게도 technote-space/get-diff-action 액션을 사용합니다. 이 액션은 PR에서 변경된 모든 파일의 git diff를 제공합니다:

# git diff to generate matrix with modified packages only
- uses: technote-space/get-diff-action@v4
  with:
    PATTERNS: layers/*/*/*/**Copy

이 결과（${{ env.GIT_DIFF }}에 저장됩니다）로부터 커스텀 명령 package-entries-json 호출을 생성하고, 출력으로 설정합니다:

- id: output_data
  name: Calculate matrix for packages
  run: |
    quote=\'
    clean_diff="$(echo "${{ env.GIT_DIFF }}" | sed -e s/$quote//g)"
    packages_in_diff="$(echo $clean_diff | grep -E -o 'layers/[A-Za-z0-9_\-]*/[A-Za-z0-9_\-]*/[A-Za-z0-9_\-]*/' | sort -u)"
    echo "[Packages in diff] $(echo $packages_in_diff | tr '\n' ' ')"
    filter_arg="--filter=$(echo $packages_in_diff | sed -e 's/ / --filter=/g')"
    echo "::set-output name=matrix::$(vendor/bin/monorepo-builder package-entries-json $(echo $filter_arg))"Copy

결과로 얻은 패키지는 매트릭스 생성에 사용됩니다:

outputs:
  matrix: ${{ steps.output_data.outputs.matrix }}Copy

정말 잘 작동합니다！ 이 예시에서는 변경된 패키지가 2개뿐이었기 때문에, 매트릭스에서 실행된 인스턴스도 2개뿐이었습니다:

이제 PR 병합이 1시간에서 단 몇 분으로 줄어들어, 다시 행복한 개발자가 되었습니다.

​

추가 최적화 및 과제

GitHub Action에서 시간을 줄일 수 있는 또 다른 경우가 있습니다: PHPUnit 테스트 실행 시입니다.

현재는 새 코드가 업로드될 때마다 모든 패키지의 전체 테스트 배터리가 실행됩니다. 하지만 이 역시 최적화할 수 있습니다.

모노레포에 A, B, C 세 개의 패키지가 있고, B가 A에 의존하며 C가 B에 의존한다고 가정해 봅시다.

이 경우, 단일 패키지의 코드를 변경하면 실행이 필요한 테스트가 다음과 같이 달라집니다:

• A의 코드를 변경한 경우: A, B, C를 테스트해야 합니다
• B의 코드를 변경한 경우: B와 C를 테스트해야 합니다
• C의 코드를 변경한 경우: C만 테스트해야 합니다

최적화는 변경된 패키지 목록（앞선 최적화와 동일）을 가져와서, 해당 패키지들과 그것들에 의존하는 모든 패키지의 테스트를 실행하는 것에 달려 있습니다.

그런데 현재 저는 모노레포 내 각 패키지가 서로 어떻게 의존하는지에 대한 정보를 가지고 있지 않습니다.

루트 composer.json에는 모든 로컬 패키지가 포함되어 있지만, require가 아닌 replace 섹션에 정의되어 있기 때문에 composer info ${ package_name }을 실행하여 Composer를 통해 의존성을 가져올 수 없습니다.

대안으로, 각 패키지의 서브폴더로 이동하여 composer install을 실행한 후 composer info를 실행하는 방법도 있습니다. 하지만 composer install을 200번 이상 실행하는 것은 완전히 비현실적입니다.

따라서 이 시나리오는 아직 최적화하지 못했습니다. 지금까지 이슈를 생성해 두었으며, 언젠가 해결책을 찾기를 바라고 있습니다.

​

마치며

Monorepo Builder를 발견한 것이 정말 기쁩니다. 이것 없이는 Gato GraphQL의 코드베이스를 관리할 수 없었을 것이라고 생각합니다.

모든 프로젝트가 이것을 사용해야 한다고 말하는 것이 아닙니다. 하지만 저처럼 200개 이상의 패키지가 있거나, 아마도 20개 이상인 경우라면, 분명히 삶이 훨씬 편해집니다.

모노레포 관리에는 설정과 유지에 약간의 시간과 노력이 필요하지만, 일상적인 개발만으로도 그 시간과 노력을 몇 배로 돌려받을 수 있습니다.