Monorepo架构实践——项目管理策略

// Monorepo典型项目结构
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ],
  "devDependencies": {
    "@nx/workspace": "^16.0.0",
    "nx": "^16.0.0"
  },
  "scripts": {
    "build": "nx run-many --target=build --all",
    "test": "nx run-many --target=test --all",
    "lint": "nx run-many --target=lint --all"
  }
}

# .github/workflows/monorepo-ci.yml
name: Monorepo CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16.x, 18.x]

    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # 获取完整的提交历史以支持增量构建

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: Cache node modules
        uses: actions/cache@v3
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

      - name: Install dependencies
        run: npm ci

      - name: Run affected tests
        run: npx nx affected --target=test --parallel=3

      - name: Run affected lint
        run: npx nx affected --target=lint --parallel=3

// Monorepo优势示例
class MonorepoAdvantages {
  constructor() {
    this.benefits = {
      // 代码共享
      codeSharing: {
        benefit: 'Centralized reusable components',
        example: `
// packages/shared/src/utils/date-utils.ts
export const formatDate = (date: Date): string => {
  return date.toLocaleDateString('en-US', {
    year: 'numeric',
    month: 'long',
    day: 'numeric'
  });
};

// apps/web/src/components/UserCard.tsx
import { formatDate } from '@my-org/shared/utils';
        `,
        impact: 'Eliminates code duplication across projects'
      },

      // 原子性提交
      atomicCommits: {
        benefit: 'Cross-project changes in single commit',
        example: `
git commit -m "feat: update API interface and UI components
- packages/api/src/models/User.ts: add new fields
- packages/ui/src/components/UserCard.tsx: support new fields
- packages/backend/src/services/UserService.ts: update logic"
        `,
        impact: 'Ensures consistency across related changes'
      },

      // 依赖管理
      dependencyManagement: {
        benefit: 'Unified dependency versions',
        example: `
// packages/shared/package.json
{
  "dependencies": {
    "react": "^18.0.0",        // Shared React version
    "typescript": "^4.9.0"     // Shared TS version
  }
}
        `,
        impact: 'Reduces dependency conflicts and maintenance overhead'
      },

      // 构建优化
      buildOptimization: {
        benefit: 'Incremental builds and caching',
        example: `
# Nx can skip building unchanged packages
> nx build web --with-deps
Affected projects: 3
Cached: 2
Building: 1
        `,
        impact: 'Significantly improves build times'
      }
    };
  }

  getTradeoffs() {
    return {
      monorepo: {
        advantages: [
          'Better code sharing',
          'Atomic cross-project changes',
          'Unified tooling',
          'Simplified dependency management',
          'Improved developer experience'
        ],
        disadvantages: [
          'Larger repository size',
          'More complex tooling setup',
          'Potential for tight coupling',
          'Requires sophisticated CI/CD'
        ]
      },
      multirepo: {
        advantages: [
          'Simpler project boundaries',
          'Independent release cycles',
          'Smaller clone sizes',
          'Easier access control'
        ],
        disadvantages: [
          'Code duplication',
          'Harder cross-project coordination',
          'Version conflicts',
          'Inconsistent tooling'
        ]
      }
    };
  }
}

// nx.json - Nx配置文件
{
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx/tasks-runners/default",
      "options": {
        "cacheableOperations": ["build", "test", "lint", "e2e"]
      }
    }
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["{projectRoot}/dist"]
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["default", "^default"]
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "sharedGlobals": ["{workspaceRoot}/package.json"],
    "production": [
      "default",
      "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)",
      "!{projectRoot}/tsconfig.spec.json",
      "!{projectRoot}/.eslintrc.json"
    ]
  }
}

// apps/web/project.json
{
  "name": "web",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "apps/web/src",
  "projectType": "application",
  "targets": {
    "build": {
      "executor": "@nrwl/webpack:webpack",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/web",
        "main": "apps/web/src/main.tsx",
        "tsConfig": "apps/web/tsconfig.app.json",
        "webpackConfig": "apps/web/webpack.config.js"
      },
      "configurations": {
        "production": {
          "fileReplacements": [
            {
              "replace": "apps/web/src/environments/environment.ts",
              "with": "apps/web/src/environments/environment.prod.ts"
            }
          ]
        }
      }
    },
    "test": {
      "executor": "@nrwl/jest:jest",
      "outputs": ["{workspaceRoot}/coverage/apps/web"],
      "options": {
        "jestConfig": "apps/web/jest.config.ts"
      }
    }
  },
  "tags": ["type:app", "platform:web"]
}

// 生成Nx应用和服务
// apps/web/src/app/services/user.service.ts
import { Injectable } from '@nestjs/common';
import { UserRepository } from '@my-org/repositories';
import { UserDto } from '@my-org/dtos';

@Injectable()
export class UserService {
  constructor(private userRepository: UserRepository) {}

  async getUsers(): Promise<UserDto[]> {
    const users = await this.userRepository.findAll();
    return users.map(user => new UserDto(user));
  }
}

// libs/repositories/src/lib/user.repository.ts
import { Injectable } from '@nestjs/common';
import { User } from '@my-org/entities';

@Injectable()
export class UserRepository {
  private users: User[] = [
    { id: 1, name: 'John', email: 'john@example.com' }
  ];

  async findAll(): Promise<User[]> {
    return this.users;
  }

  async findById(id: number): Promise<User | undefined> {
    return this.users.find(user => user.id === id);
  }
}

// 生成库的命令示例
// nx generate @nrwl/angular:library --name=user-management --directory=feature
// nx generate @nrwl/nest:library --name=data-access --directory=user

// turbo.json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": [],
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts", "test/**/*.tsx"]
    },
    "lint": {
      "outputs": [],
      "inputs": ["src/**/*.ts", "src/**/*.tsx"]
    },
    "dev": {
      "cache": false
    }
  },
  "globalDependencies": ["tsconfig.base.json"]
}

// package.json (root)
{
  "name": "my-turbo-workspace",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ],
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev --parallel",
    "test": "turbo run test",
    "lint": "turbo run lint"
  },
  "devDependencies": {
    "turbo": "^1.9.0"
  },
  "engines": {
    "node": ">=16.0.0"
  },
  "packageManager": "pnpm@8.6.0"
}

// apps/web/package.json
{
  "name": "@my-org/web",
  "private": true,
  "version": "1.0.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "next": "^13.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "@my-org/shared": "workspace:*",
    "@my-org/ui": "workspace:*"
  },
  "devDependencies": {
    "@types/node": "^18.0.0",
    "@types/react": "^18.0.0",
    "typescript": "^4.9.0"
  }
}

// lerna.json
{
  "version": "independent",
  "npmClient": "yarn",
  "useWorkspaces": true,
  "command": {
    "publish": {
      "ignoreChanges": [
        "*.md",
        "test/**"
      ],
      "message": "chore(release): publish %s"
    },
    "bootstrap": {
      "hoist": true
    }
  },
  "packages": [
    "packages/*",
    "apps/*"
  ]
}

// lerna最佳实践配置
const LernaConfig = {
  versioningStrategies: {
    // 独立版本控制 - 每个包独立发布
    independent: {
      config: {
        version: 'independent',
        publish: {
          ignoreChanges: ['*.md', 'docs/**', 'tests/**']
        }
      },
      benefits: ['granular releases', 'independent dependency management'],
      useCase: 'multiple teams managing different packages'
    },

    // 统一版本控制 - 所有包一起发布
    fixed: {
      config: {
        version: '1.0.0', // 手动指定版本
        publish: {
          exact: true
        }
      },
      benefits: ['atomic releases', 'consistent versions'],
      useCase: 'tightly coupled packages'
    }
  },

  // 发布策略
  publishingStrategies: {
    conventionalCommits: {
      enabled: true,
      changelog: true,
      requireUpgraded: true
    },

    selectivePublish: {
      // 选择性发布变更的包
      command: 'lerna publish --conventional-commits --since=main'
    }
  }
};

# Monorepo推荐结构
my-monorepo/:
  apps/:
    web/:
      src/
      package.json
      project.json
    mobile/:
      src/
      package.json
      project.json
    api/:
      src/
      package.json
      project.json
  packages/:
    ui/:
      src/
      package.json
      project.json
    shared/:
      src/
      package.json
      project.json
    entities/:
      src/
      package.json
      project.json
    dtos/:
      src/
      package.json
      project.json
    repositories/:
      src/
      package.json
      project.json
    services/:
      src/
      package.json
      project.json
  tools/:
    generators/:
    scripts/:
  docs/:
  .github/:
  package.json
  nx.json (or turbo.json)
  tsconfig.base.json
  jest.config.ts

// 包间的依赖管理策略
class DependencyManagement {
  // 包的类型分类
  packageTypes = {
    // 基础设施包
    infrastructure: {
      name: 'infrastructure',
      description: 'Shared infrastructure components',
      dependencies: {
        dev: ['typescript', '@types/node'],
        prod: []
      }
    },

    // 共享工具包
    shared: {
      name: 'shared',
      description: 'Common utilities and functions',
      dependencies: {
        dev: ['@types/jest', 'jest'],
        prod: []
      }
    },

    // UI组件库
    ui: {
      name: 'ui',
      description: 'Reusable UI components',
      dependencies: {
        dev: ['@storybook/*', '@types/react'],
        prod: ['react', 'react-dom', '@my-org/shared']
      }
    },

    // 业务组件
    feature: {
      name: 'feature',
      description: 'Business feature implementations',
      dependencies: {
        dev: [],
        prod: ['@my-org/shared', '@my-org/ui', '@my-org/entities']
      }
    }
  };

  // 依赖版本策略
  versionStrategies = {
    // 固定版本 - 所有项目使用相同版本
    fixed: {
      approach: '^1.2.3',
      useCase: 'tight integration required',
      pros: ['consistent behavior', 'easier debugging'],
      cons: ['less flexible', 'potential conflicts']
    },

    // 工作区协议 - 使用工作区版本
    workspaceProtocol: {
      approach: 'workspace:*',
      useCase: 'internal packages only',
      pros: ['automatic linking', 'easy development'],
      cons: ['not for public publishing', 'requires workspace manager']
    },

    // 兼容版本 - 允许补丁和次要版本更新
    compatible: {
      approach: '~1.2.3',
      useCase: 'balanced approach',
      pros: ['controlled updates', 'backward compatibility'],
      cons: ['potential fragmentation', 'maintenance overhead']
    }
  };

  // 依赖图分析工具
  analyzeDependencies() {
    const dependencyGraph = {
      nodes: [],
      edges: [],
      cycles: [],

      validate() {
        // 检查循环依赖
        const cycles = this.detectCycles();
        if (cycles.length > 0) {
          throw new Error(`Circular dependencies detected: ${cycles.join(', ')}`);
        }

        // 检查非法依赖（如UI包依赖业务逻辑）
        this.validateLayeredArchitecture();
      },

      detectCycles() {
        // 使用拓扑排序检测循环
        return [];
      },

      validateLayeredArchitecture() {
        // 确保依赖方向正确：apps -> feature -> shared -> infrastructure
      }
    };

    return dependencyGraph;
  }
}

// Nx构建配置
class BuildStrategy {
  pipeline = {
    build: {
      dependsOn: ['^build'],
      outputs: ['{projectRoot}/dist', '{projectRoot}/build'],
      cache: true
    },

    test: {
      dependsOn: [],
      outputs: [],
      inputs: [
        '{projectRoot}/src/**/*',
        '{projectRoot}/test/**/*',
        '{workspaceRoot}/jest.config.ts'
      ]
    },

    lint: {
      dependsOn: [],
      outputs: [],
      inputs: [
        '{projectRoot}/src/**/*',
        '{projectRoot}/.eslintrc.json'
      ]
    },

    e2e: {
      dependsOn: ['build', 'test'],
      outputs: ['{projectRoot}/reports'],
      inputs: [
        '{projectRoot}/e2e/**/*',
        '{projectRoot}/dist/**/*'
      ]
    }
  };

  // 增量构建实现
  incrementalBuild = {
    affectedProjects: (changedFiles: string[]): string[] => {
      // 分析变更文件，找出受影响的项目
      return this.calculateAffectedProjects(changedFiles);
    },

    calculateAffectedProjects: (changedFiles: string[]): string[] => {
      const affected = new Set<string>();

      for (const file of changedFiles) {
        const project = this.getProjectOfFile(file);
        if (project) {
          affected.add(project.name);

          // 添加依赖于此项目的其他项目
          const dependents = this.getDependents(project.name);
          dependents.forEach(dep => affected.add(dep));
        }
      }

      return Array.from(affected);
    }
  };

  // 并行构建配置
  parallelBuild = {
    maxWorkers: require('os').cpus().length,
    queue: new Map<string, Promise<any>>(),

    executeInParallel(tasks: Array<() => Promise<any>>) {
      const promises = tasks.map(task => task());
      return Promise.allSettled(promises);
    }
  };
}

// 测试策略配置
class TestStrategy {
  configurations = {
    unit: {
      executor: '@nrwl/jest:jest',
      options: {
        jestConfig: 'jest.config.ts',
        runInBand: false,
        maxWorkers: '50%'
      }
    },

    integration: {
      executor: '@nrwl/jest:jest',
      options: {
        jestConfig: 'jest.integration.config.ts',
        testTimeout: 30000,
        maxWorkers: 2
      }
    },

    e2e: {
      executor: '@nrwl/playwright:playwright',
      options: {
        config: 'playwright.config.ts'
      }
    }
  };

  // 测试隔离策略
  isolation = {
    // 每个测试文件使用单独的Jest环境
    perFile: true,

    // 数据库测试隔离
    database: {
      beforeEach: async () => {
        // 创建测试数据库快照
        await this.createTestSnapshot();
      },
      afterEach: async () => {
        // 恢复到快照
        await this.restoreSnapshot();
      }
    },

    // 文件系统测试隔离
    filesystem: {
      beforeEach: async () => {
        // 创建临时目录
        this.tempDir = await this.createTempDir();
      },
      afterEach: async () => {
        // 清理临时目录
        await this.cleanupTempDir(this.tempDir);
      }
    }
  };

  // 覆盖率报告
  coverage = {
    thresholds: {
      lines: 80,
      functions: 80,
      branches: 80,
      statements: 80
    },

    reporters: ['json', 'lcov', 'text', 'html']
  };
}

# GitHub Actions - Monorepo CI/CD
name: Monorepo CI/CD

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  # 影响分析
  affected:
    runs-on: ubuntu-latest
    outputs:
      affected-apps: ${{ steps.affected.outputs.apps }}
      affected-packages: ${{ steps.affected.outputs.packages }}
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # 获取完整的提交历史

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Detect affected projects
        id: affected
        run: |
          # 使用Nx检测受影响的项目
          echo "apps=$(npx nx print-affected --target=build --select=projects)" >> $GITHUB_OUTPUT
          echo "packages=$(npx nx print-affected --target=build --select=projects)" >> $GITHUB_OUTPUT

  # 构建受影响的应用
  build-apps:
    needs: affected
    if: ${{ needs.affected.outputs.affected-apps != '' }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        app: ${{ fromJSON(needs.affected.outputs.affected-apps) }}
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Build ${{ matrix.app }}
        run: npx nx build ${{ matrix.app }}

      - name: Upload build artifacts
        uses: actions/upload-artifact@v3
        with:
          name: ${{ matrix.app }}-build
          path: dist/apps/${{ matrix.app }}

  # 测试
  test:
    needs: affected
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Run affected tests
        run: npx nx affected --target=test --parallel=3 --ci --code-coverage

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info

  # 发布（仅主分支）
  publish:
    needs: [affected, build-apps, test]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write
    steps:
      - uses: actions/checkout@v3
        with:
          token: ${{ secrets.PAT }}  # 需要推送权限的PAT

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: npm ci

      - name: Publish packages
        run: |
          # 使用Nx进行智能发布
          npx nx release --verbose
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

// 发布配置
class ReleaseStrategy {
  // 版本发布策略
  publishing = {
    // 自动化版本管理
    automated: {
      tools: ['nx-release', 'changesets'],
      workflow: `
      1. Analyze changes using conventional commits
      2. Determine version bumps automatically
      3. Generate changelogs
      4. Publish to registries
      5. Create GitHub releases
      `
    },

    // 手动版本管理
    manual: {
      workflow: `
      1. Review changes manually
      2. Determine version bumps
      3. Update package.json versions
      4. Create and push git tags
      5. Publish packages
      `
    }
  };

  // 发布配置示例
  nxRelease = {
    projects: {
      // 排除某些项目不发布
      exclude: ['web', 'mobile'], // 应用通常不发布

      // 包含的库项目
      include: [
        'packages/ui',
        'packages/shared',
        'packages/core'
      ]
    },

    changelog: {
      createRelease: 'github',
      projectChangelogs: true,
      workspaceChangelog: true
    },

    version: {
      conventionalCommits: true,
      granularity: 'project' // 每个项目独立版本
    }
  };

  // 预发布管理
  preRelease = {
    channels: {
      next: 'for unstable releases',
      beta: 'for testing releases',
      rc: 'for release candidates'
    },

    workflow: [
      'Create pre-release branch',
      'Update versions with prerelease suffix',
      'Publish with --tag next/beta/rc',
      'Test and validate',
      'Merge to main and publish stable version'
    ]
  };
}

// 权限管理策略
class AccessControl {
  // 代码所有权
  codeOwnership = {
    apps: {
      'web': ['frontend-team', 'ux-team'],
      'mobile': ['mobile-team', 'ios-team', 'android-team'],
      'api': ['backend-team', 'platform-team']
    },

    packages: {
      'ui': ['design-team', 'frontend-team'],
      'shared': ['architecture-team'],
      'core': ['platform-team']
    }
  };

  // 贡献指南
  contributionGuide = {
    branchNaming: {
      pattern: 'feature|bugfix|hotfix|release/<ticket-number>-<description>',
      example: 'feature/JIRA-123-add-user-authentication'
    },

    commitMessages: {
      format: 'type(scope): description',
      types: [
        'feat: new feature',
        'fix: bug fix',
        'docs: documentation',
        'style: formatting',
        'refactor: code restructuring',
        'test: adding tests',
        'chore: maintenance'
      ],
      scopes: ['web', 'mobile', 'api', 'shared', 'ui']
    },

    pullRequest: {
      template: {
        changes: 'Brief summary of changes',
        testing: 'How to test the changes',
        related: 'Related issues/tickets',
        reviewers: 'Suggested reviewers'
      },
      sizeLimit: 'less than 300 lines per PR',
      reviewPolicy: 'at least 1 approval required'
    }
  };

  // 项目标签策略
  projectTagging = {
    types: {
      'type:app': 'Application projects',
      'type:lib': 'Library projects',
      'type:util': 'Utility libraries',
      'type:test': 'Testing utilities'
    },

    platforms: {
      'platform:web': 'Web-specific code',
      'platform:mobile': 'Mobile-specific code',
      'platform:shared': 'Cross-platform code'
    },

    domains: {
      'domain:user': 'User-related functionality',
      'domain:payment': 'Payment-related code',
      'domain:analytics': 'Analytics code'
    }
  };
}

// 性能优化策略
class PerformanceOptimization {
  // 构建性能优化
  buildOptimization = {
    caching: {
      local: {
        directory: '.nx/cache',
        enabled: true
      },
      remote: {
        endpoint: process.env.NX_CACHE_ENDPOINT,
        token: process.env.NX_CACHE_TOKEN,
        enabled: process.env.CI === 'true'
      }
    },

    // 增量构建
    incremental: {
      // 仅构建受影响的项目
      affected: true,

      // 跳过未变更的项目
      skipUnchanged: true,

      // 并行构建
      parallel: 4
    },

    // 预构建优化
    prebuild: {
      // 预编译常用的库
      precompile: ['@my-org/shared', '@my-org/ui'],

      // 预拉取依赖
      prefetch: true
    }
  };

  // 存储优化
  storageOptimization = {
    // Git LFS for large files
    lfs: {
      patterns: ['*.psd', '*.zip', '*.log', '*.sql'],
      threshold: '100KB'
    },

    // Repository size management
    sizeManagement: {
      // Periodic cleanup of large objects
      cleanup: {
        frequency: 'monthly',
        threshold: '1GB'
      },

      // Shallow clones for CI
      shallowClone: {
        depth: 50,
        enabled: process.env.CI === 'true'
      }
    }
  };

  // 开发体验优化
  devExperience = {
    // Fast refresh
    fastRefresh: true,

    // Hot module replacement
    hmr: {
      enabled: true,
      preserveWatchOutput: true
    },

    // Selective project loading
    selectiveLoading: {
      enabled: true,
      pattern: process.env.SELECTED_PROJECTS || '*'
    }
  };

  // 监控和分析
  monitoring = {
    buildMetrics: {
      // Track build times
      timings: true,

      // Identify bottlenecks
      profiling: true,

      // Performance regression detection
      baseline: true
    },

    // Resource usage
    resourceUsage: {
      memory: true,
      cpu: true,
      disk: true
    }
  };
}