利用 Crossplane Composition 自动化集成 Rollup 与 React Testing Library 的前端项目初始化

Prettier Crossplane React Testing Library Rollup
平台工程
文章字数:   3.5k
阅读时长:   14 分

我们团队的前端项目初始化流程一度陷入混乱。每个新项目启动，都是一次对开发者耐心和规范意识的考验。package.json 里的脚本命令五花八门，CI/CD 配置文件需要从旧项目里小心翼翼地复制粘贴，稍有不慎就会引入错误的依赖或过时的配置。代码格式化工具、测试框架、打包工具的版本在不同项目间漂移，导致团队成员在切换项目时需要重新适应一套截然不同的本地环境和工作流。这种混乱不仅消耗了大量时间，也为后续的维护和统一升级埋下了隐患。

核心痛点在于，一个“前端项目”从来不只是代码本身，它是一个包含了版本控制、持续集成、质量门禁和构建流程的完整生态系统。我们需要的不是一份又一份的 Wiki 文档或者项目模板仓库，而是一个能将整个生态系统作为原子单元进行管理的平台能力。我们希望开发者能像申请云资源一样，通过一个简单的声明，就能获得一个配置完整、遵循团队最佳实践的、生产就绪的前端项目环境。

初步构想是构建一个内部开发者平台（IDP）的核心组件：一个项目自动售货机。开发者只需提供项目名称和归属团队等少量元数据，平台就能自动完成以下所有工作：

  1. 在内部代码托管平台（如 GitLab/Gitea）上创建新的代码仓库。
  2. 向仓库中推送一个标准的、包含 React、Rollup、React Testing Library 和 Prettier 的基础模板。
  3. 自动创建并配置好一套 CI/CD 流水线，该流水线强制执行代码格式检查、单元测试和生产构建。

这个构想的技术关键点在于如何将这些分散的、异构的操作（API 调用、Git 操作、CI 配置生成）统一到一个声明式的模型中。这正是 Crossplane 发挥作用的地方。

技术选型决策：为何是 Crossplane？

在真实项目中，我们评估过几种方案。

方案A：自定义脚本 + Web UI
通过编写一堆 Shell 或 Python 脚本，封装 Git 和 CI/CD 平台的 API 调用，然后提供一个简单的 Web 界面。这种方式实现起来快，但问题也显而易见：

  • 过程式而非声明式: 脚本执行的是一步步的命令。一旦中间某一步失败，状态就会不一致，需要复杂的重试和回滚逻辑。
  • 状态维护困难: 脚本是无状态的，它不知道哪些项目已经被创建，也不知道这些项目的当前状态。我们需要额外的数据库来追踪这一切。
  • 可扩展性差: 每增加一种项目类型或一个新的集成，都需要修改核心脚本，很快会变得难以维护。

方案B：Terraform
Terraform 是 IaC 领域的佼佼者，也有相应的 GitLab/GitHub Provider。我们可以用 HCL 来定义一个项目所需的所有资源。这比脚本好得多，因为它是声明式的。但它也有局限：

  • 抽象能力有限: Terraform 的 Module 提供了一定程度的抽象，但我们很难创建一个名为 FrontendProject 的一级 API。开发者仍然需要理解底层的 gitlab_project、gitlab_ci_variable 等资源。我们想要的是更高层次的封装。
  • 持续协调的缺失: Terraform 主要在 apply 时刻工作。如果有人手动更改了 GitLab 上的项目配置，Terraform 在下一次执行前是不会感知的。我们想要一个能持续监控并纠正偏差的控制循环。

最终选择：Crossplane
Crossplane 完美地解决了上述问题。它基于 Kubernetes 控制平面，允许我们用 CRD (Custom Resource Definitions) 来定义自己的高级抽象 API。

  1. 自定义抽象 (Composition): 我们可以定义一个 CompositeResourceDefinition (XRD)，名为 FrontendProject。这个 API 只暴露开发者需要关心的几个字段，如 projectName。然后，我们通过 Composition 将这个高级 API “翻译”成一组底层的、由 Provider 管理的资源，例如 gitea.Repository、kubernetes.Secret 和 kubernetes.ConfigMap。
  2. 持续协调 (Reconciliation Loop): Crossplane 的 Provider 不仅负责创建资源，还会持续监控这些资源的实际状态是否与期望状态一致。如果有人手动删除了 CI 配置，Crossplane 会自动将其恢复。
  3. GitOps 原生集成: 所有的声明都可以是 YAML 文件，完美融入现有的 GitOps 工作流。开发者通过向 Git 仓库提交一个 FrontendProject 的 YAML 文件来申请新项目。

于是，我们决定采用 Crossplane 作为平台底座，将前端项目的标准化工具链（Rollup, Prettier, React Testing Library）作为平台提供的“标准配置”固化到自动化流程中。

步骤化实现

整个实现的核心是定义 FrontendProject 这个抽象，并编排它所包含的具体资源。

1. 定义顶层抽象：CompositeResourceDefinition (XRD)

这是我们暴露给开发者的 API。我们希望它尽可能简洁。开发者只需要提供项目名，所有其他的配置，如 CI/CD 流水线内容、代码模板等，都应该由平台在后端封装好。

# xfrontendproject.yaml
apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xfrontendprojects.platform.acme.io
spec:
  group: platform.acme.io
  names:
    kind: XFrontendProject
    plural: xfrontendprojects
  claimNames:
    kind: FrontendProject
    plural: frontendprojects
  versions:
  - name: v1alpha1
    served: true
    referenceable: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              owner:
                type: string
                description: The team or individual owning this project.
            required:
            - owner

这里的 XRD 定义了一个新的 GVK (Group/Version/Kind): platform.acme.io/v1alpha1/FrontendProject。它只有一个必需的参数 owner。项目名称将直接从 metadata.name 获取。

2. 编排底层资源：Composition

Composition 是整个方案的灵魂。它描述了一个 FrontendProject 应该由哪些具体的“Managed Resources”组成。在我们的场景中，它由三部分组成：

  1. 一个 Gitea 代码仓库。
  2. 一个包含 CI/CD 流水线定义的 Kubernetes ConfigMap。
  3. 一个用于存放初始代码模板的 Kubernetes ConfigMap。

为了让 Crossplane 能够管理 Gitea，我们假设已经安装了相应的 Provider，例如 provider-gitea。

# composition.yaml
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: frontendproject.gitea.platform.acme.io
  labels:
    provider: gitea
spec:
  writeConnectionSecretsToNamespace: crossplane-system
  compositeTypeRef:
    apiVersion: platform.acme.io/v1alpha1
    kind: XFrontendProject
  resources:
    - name: gitea-repository
      base:
        apiVersion: gitea.crossplane.io/v1alpha1
        kind: Repository
        spec:
          forProvider:
            owner: "frontend-projects" # All repos are created under this org
            description: "Managed by Crossplane Platform"
            private: true
      patches:
        - fromFieldPath: "metadata.name"
          toFieldPath: "spec.forProvider.name"
        - fromFieldPath: "metadata.name"
          toFieldPath: "metadata.name"
          
    - name: ci-pipeline-configmap
      base:
        apiVersion: v1
        kind: ConfigMap
        metadata:
          namespace: cicd-pipelines
        data:
          # .gitlab-ci.yml content goes here. It defines the stages for lint, test, and build.
          # This is the core of enforcing our standards.
          ".gitlab-ci.yml": |
            stages:
              - quality
              - test
              - build

            # Cache node_modules to speed up subsequent jobs
            cache:
              key:
                files:
                  - package-lock.json
              paths:
                - .npm/

            before_script:
              - npm ci --cache .npm --prefer-offline

            prettier-check:
              stage: quality
              image: node:18-slim
              script:
                - echo "Checking code formatting with Prettier..."
                - npx prettier --check .
            
            unit-test:
              stage: test
              image: node:18-slim
              script:
                - echo "Running unit tests with React Testing Library..."
                - npm test -- --watchAll=false
              artifacts:
                when: always
                reports:
                  junit: junit.xml

            build-app:
              stage: build
              image: node:18-slim
              script:
                - echo "Building application with Rollup..."
                - npm run build
              artifacts:
                paths:
                  - dist/
      patches:
        - fromFieldPath: "metadata.name"
          toFieldPath: "metadata.name"
          transforms:
            - type: string
              string:
                fmt: "%s-pipeline"

    - name: initial-code-template-configmap
      base:
        apiVersion: v1
        kind: ConfigMap
        metadata:
          namespace: project-templates
        data:
          "package.json": |
            {
              "name": "placeholder-name",
              "version": "1.0.0",
              "type": "module",
              "scripts": {
                "dev": "vite",
                "build": "rollup -c",
                "test": "vitest",
                "preview": "vite preview",
                "format": "prettier --write ."
              },
              "devDependencies": {
                "@rollup/plugin-commonjs": "^25.0.0",
                "@rollup/plugin-node-resolve": "^15.0.0",
                "@rollup/plugin-terser": "^0.4.0",
                "@testing-library/jest-dom": "^6.1.4",
                "@testing-library/react": "^14.0.0",
                "jsdom": "^22.1.0",
                "prettier": "^3.0.3",
                "react": "^18.2.0",
                "react-dom": "^18.2.0",
                "rollup": "^3.20.0",
                "rollup-plugin-postcss": "^4.0.2",

                "vitest": "^0.34.6"
              }
            }
          "rollup.config.js": |
            import resolve from '@rollup/plugin-node-resolve';
            import commonjs from '@rollup/plugin-commonjs';
            import terser from '@rollup/plugin-terser';
            
            export default {
              input: 'src/main.jsx',
              output: {
                file: 'dist/bundle.js',
                format: 'iife',
                sourcemap: true,
              },
              plugins: [
                resolve(),
                commonjs(),
                process.env.NODE_ENV === 'production' && terser(),
              ],
            };
          # Minimal React component for testing
          "src/App.jsx": |
            import React from 'react';
            
            function App() {
              return <h1>Hello, Platform!</h1>;
            }
            
            export default App;
          # Corresponding test file using React Testing Library
          "src/App.test.jsx": |
            import React from 'react';
            import { render, screen } from '@testing-library/react';
            import App from './App';
            import { describe, it, expect } from 'vitest';
            
            describe('App', () => {
              it('renders headline', () => {
                render(<App />);
                const headline = screen.getByText(/Hello, Platform!/i);
                expect(headline).toBeInTheDocument();
              });
            });
      patches:
        - fromFieldPath: "metadata.name"
          toFieldPath: "metadata.name"
          transforms:
            - type: string
              string:
                fmt: "%s-template"
        - fromFieldPath: "metadata.name"
          toFieldPath: "data['package.json']"
          transforms:
            - type: "match"
              match:
                pattern: '"name": "placeholder-name"'
                input: '{"name": "placeholder-name", ...}' # Simplified for clarity
              result: '{"name": "%s", ...}' # Not a direct feature, pseudo-code for patching file content

这里的 Composition 有几个关键点：

  • Patches: 使用 patches 从 FrontendProject Claim 中提取 metadata.name，并将其应用到 Gitea 仓库的名称、ConfigMap 的名称等字段上。这是实现动态配置的核心。
  • CI Pipeline as Data: 我们将 .gitlab-ci.yml 的内容直接嵌入到 ConfigMap 中。这个配置文件是标准化的，它定义了三个阶段：quality (运行 Prettier 检查)、test (运行 npm test，背后是 Vitest 和 React Testing Library) 和 build (运行 Rollup)。
  • Code Template as Data: 同样，项目的骨架代码，包括 package.json、rollup.config.js 和一个简单的 React 测试用例，也作为数据存储在 ConfigMap 中。

一个常见的错误是： 试图在 Composition 中执行过程式逻辑。例如，我们没有一个“执行 git push”的资源。Crossplane 是声明式的，它只负责创建最终状态的资源。将代码和配置推送到 Git 仓库的这一步，需要一个外部的自动化组件（比如一个简单的 Kubernetes Job 或者 Tekton Task）来完成。这个组件可以被设计为监听 FrontendProject 资源的创建事件，然后从 ConfigMap 中拉取代码模板和 CI 配置，并推送到新创建的 Gitea 仓库中。这是一个事件驱动的补充，完善了整个工作流。

为了可视化这个关系，我们可以用 Mermaid 来表示：

graph TD
    A[Developer commits
FrontendProject Claim] -->|GitOps Controller| B(Kubernetes API Server)
    B -->|Crossplane| C{XFrontendProject XR}
    C -->|Composition Selector| D[Composition]
    D -->|Reconciles| E[Managed Resources]
    E --> F[gitea.Repository]
    E --> G[ConfigMap for CI]
    E --> H[ConfigMap for Template]

    subgraph External Automation
        I(Project Initializer Job) -- Watches --> B
        I -- On Create --> J{1. Read ConfigMaps G & H}
        J --> K{2. Git Push to Repository F}
    end

    style D fill:#f9f,stroke:#333,stroke-width:2px
    style C fill:#bbf,stroke:#333,stroke-width:2px

3. 触发流程：创建一个 FrontendProject Claim

现在，开发者需要做的就是创建一个非常简单的 YAML 文件，然后提交到他们的 GitOps 配置仓库。

# my-new-app.yaml
apiVersion: platform.acme.io/v1alpha1
kind: FrontendProject
metadata:
  name: awesome-new-feature-app
  namespace: team-phoenix
spec:
  owner: team-phoenix

当 ArgoCD 或 FluxCD 将这个 YAML 文件同步到集群中时，Crossplane 的魔法就开始了。

  1. Crossplane 创建一个 XFrontendProject 复合资源（XR）。
  2. Composition 被选中，并开始创建其定义的所有底层资源。
  3. 一个名为 awesome-new-feature-app 的 Gitea 仓库被创建。
  4. 两个 ConfigMap (awesome-new-feature-app-pipeline 和 awesome-new-feature-app-template) 在指定的命名空间中被创建。
  5. 我们前面提到的“外部自动化 Job”被触发，它读取这两个 ConfigMap，将代码和 CI 配置推送到新仓库的 main 分支。

最终，开发者在 Gitea 上会看到一个全新的、功能完备的项目。他们只需要 git clone，然后就可以立即开始编写业务代码，而所有的工程化配置——代码风格、测试环境、打包流程——都已经由平台保证是一致且最优的。

最终成果与价值

我们实现了一个闭环的、自服务的项目初始化系统。从开发者的角度看，整个体验从数小时甚至数天的手动配置，缩减为提交一个几十行的 YAML 文件。

  • 一致性: 所有新项目都使用同一套经过审查的 Rollup 配置、React Testing Library 测试设置和 Prettier 规则。
  • 效率: 消除了重复性的环境搭建工作。
  • 治理: 平台团队可以通过更新 Composition 来统一升级所有新项目的技术栈或 CI 流程，而无需通知每个团队手动修改。
  • 声明式与 GitOps: 整个基础设施的期望状态都被记录在 Git 中，有完整的变更历史，易于审计和回滚。

在真实项目中，这个模式的威力巨大。它将平台工程团队的知识和最佳实践，固化成了可复用的、自动化的能力，直接赋能给业务开发团队。

局限性与未来迭代路径

当前这套方案只是一个起点，它解决了项目“从0到1”的问题，但仍有几个方面值得深入。

首先，代码模板和 CI 配置目前是硬编码在 Composition 的 ConfigMap 中的。这种方式对于简单的场景来说足够，但当模板变得复杂或需要支持多种项目类型（例如，React vs. Vue）时，维护巨大的 YAML 字符串会成为噩梦。一个更成熟的方案是引入一个专门的“模板化引擎”。Composition 可以只负责创建一个指向某个 Git 模板仓库的资源，然后由一个专用的控制器（Operator）来完成模板的拉取、变量替换和推送到新仓库的操作。

其次，对于 CI/CD 的集成还比较初级。我们只是创建了一个 .gitlab-ci.yml 文件。一个更深入的集成应该包括自动在 CI/CD 系统中注册这个项目、配置 Webhooks、设置受保护的分支规则等。这可以通过为 Crossplane 编写或使用更强大的 CI/CD Provider 来实现。

最后，此方案只覆盖了项目初始化。一个完整的开发者平台还需要考虑后续的生命周期管理，例如：自动创建预览环境、管理不同环境的配置、项目归档和删除等。这些都可以通过扩展我们的 FrontendProject XRD，并在 Composition 中添加更多资源（如 Kubernetes.Deployment、Database.Claim 等）来逐步实现，最终形成一个全面的应用级抽象。

Prettier Crossplane React Testing Library Rollup
  目录