开发

设置 PCU 进行开发并学习如何为项目做出贡献。本指南涵盖项目设置、架构和开发工作流程。

先决条件

在开始开发 PCU 之前，请确保您拥有所需的工具：

开发需要 Node.js >= 22.0.0 和 pnpm >= 10.0.0。
node --version  # 应该是 >= 22.0.0
pnpm --version  # 应该是 >= 10.0.0

项目设置

克隆并设置开发环境：

# 克隆仓库
git clone https://github.com/houko/pnpm-catalog-updates.git
cd pnpm-catalog-updates

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 运行测试验证设置
pnpm test

项目架构

PCU 遵循清洁架构原则，关注点清晰分离：

├── apps/
│   ├── cli/                    # CLI 应用层
│   │   ├── src/cli/           # CLI 接口
│   │   │   ├── commands/      # 命令处理器
│   │   │   ├── formatters/    # 输出格式化器
│   │   │   ├── interactive/   # 交互式提示
│   │   │   ├── themes/        # 颜色主题
│   │   │   └── validators/    # 输入验证
│   │   └── bin/               # 可执行二进制文件
│   └── docs/                  # 文档站点
├── packages/
│   ├── core/                  # 核心业务逻辑
│   │   └── src/
│   │       ├── application/   # 应用服务
│   │       ├── domain/        # 领域模型 (DDD)
│   │       └── infrastructure/# 基础设施层
│   └── utils/                 # 共享工具
└── scripts/                   # 构建和部署

架构层

  • Name
    CLI 层
    Type
    apps/cli
    Description

    用户界面、命令解析、输出格式化

  • Name
    应用层
    Type
    packages/core/application
    Description

    业务逻辑编排、用例

  • Name
    领域层
    Type
    packages/core/domain
    Description

    核心业务实体、值对象、仓库接口

  • Name
    基础设施层
    Type
    packages/core/infrastructure
    Description

    外部 API 客户端、文件系统访问、仓库实现

  • Name
    工具层
    Type
    packages/utils
    Description

    共享工具、配置、日志记录、错误处理

开发工作流程

进行更改

  1. 创建功能分支：

    git checkout -b feature/amazing-feature

  2. 按照编码标准进行更改

  3. 为您的更改添加测试：

    pnpm test:watch  # 以监视模式运行测试

  4. 确保质量检查通过：

    pnpm lint        # 检查代码风格
pnpm typecheck   # 类型检查
pnpm test        # 运行所有测试

  5. 提交更改：

    git commit -m 'feat: add amazing feature'

测试策略

PCU 使用综合测试方法：

# 运行单元测试
pnpm test

# 运行覆盖率测试
pnpm test:coverage

# 测试特定包
pnpm --filter @pcu/core test

代码质量

PCU 保持高代码质量标准：

# 检查代码风格
pnpm lint

# 修复代码检查问题
pnpm lint:fix

# 格式化代码
pnpm format

# 检查 TypeScript 类型
pnpm typecheck

添加功能

创建新命令

  1. 在 apps/cli/src/cli/commands/ 创建命令处理器：
import { Command } from 'commander';
import { GlobalOptions } from '../options';

export function createNewCommand(): Command {
  return new Command('new')
    .description('新命令描述')
    .option('-f, --format <type>', '输出格式', 'table')
    .action(async (options: NewCommandOptions) => {
      // 命令实现
    });
}

interface NewCommandOptions extends GlobalOptions {
  format: string;
}

  1. 在 packages/core/src/application/services/ 添加业务逻辑

  2. 为 CLI 和核心逻辑创建测试

  3. 更新文档

添加新输出格式

  1. 在 apps/cli/src/cli/formatters/ 创建格式化器：

xmlFormatter.ts

import { OutputFormatter, FormattedOutput } from './outputFormatter';

export class XmlFormatter implements OutputFormatter {
  format(data: any): FormattedOutput {
    // XML 格式化逻辑
    return {
      content: xmlContent,
      type: 'xml',
    };
  }
}

  1. 在主格式化器注册表中注册格式化器

  2. 添加测试和更新文档

贡献指南

提交消息约定

PCU 使用约定式提交：

feat: 新功能
fix: 错误修复
docs: 仅文档更改
style: 代码风格更改（格式化等）
refactor: 既不修复错误也不添加功能的代码更改
test: 添加缺失测试或更正现有测试
chore: 构建过程或辅助工具的更改

拉取请求流程

  1. Fork 仓库并创建功能分支
  2. 按照开发工作流程进行更改
  3. 确保所有测试通过和代码质量检查成功
  4. 如需要更新文档
  5. 提交拉取请求包含：
    • 更改的清楚描述
    • 相关问题的链接
    • UI 更改的屏幕截图
    • 如适用的破坏性更改说明

代码审查检查清单

  1. 所有测试通过
  2. 代码覆盖率保持（>85%）
  3. TypeScript 类型正确
  4. 代码风格遵循项目标准
  5. 文档已更新
  6. 破坏性更改已记录
  7. 考虑性能影响

调试

开发调试

# 使用 Node.js 检查器调试
node --inspect-brk ./apps/cli/bin/pcu.js --help

# 使用 VS Code 调试
# 使用 .vscode/launch.json 中的启动配置

测试调试

# 调试特定测试
npm test -- --grep "specific test name"

# 使用 Node 检查器调试
node --inspect-brk node_modules/.bin/vitest run

构建和发布

本地测试

# 构建并本地测试
pnpm build
pnpm --filter @pcu/cli start --help

# 测试安装
npm pack apps/cli
npm install -g pcu-*.tgz

发布流程

  1. 使用 changesets 更新版本：

    pnpm changeset
pnpm changeset version

  2. 构建和测试：

    pnpm build
pnpm test
pnpm test:e2e

  3. 发布（仅维护者）：

    pnpm publish -r

获取帮助

  • 📖 文档：查看此文档获取详细指南
  • 🐛 问题：通过 GitHub Issues 报告错误
  • 💬 讨论：在 GitHub Discussions 中提问
  • 🔧 开发：加入 Issues 和 PRs 中的开发讨论

高级架构细节

核心领域模型

基于领域驱动设计（DDD）原则，PCU 的核心领域包括：

// packages/core/src/domain/entities/
├── catalog.ts          // 目录聚合根
├── package.ts          // 包实体
└── workspace.ts        // 工作空间聚合根

// 关键领域概念：
interface Catalog {
  readonly id: CatalogId;
  readonly name: string;
  packages: PackageCollection;
  addPackage(packageInfo: Package): void;
  updatePackage(name: string, version: Version): void;
}

interface Package {
  readonly name: string;
  readonly currentVersion: Version;
  readonly latestVersion: Version;
  readonly updateType: UpdateType;
}

服务层架构

应用层通过服务编排业务逻辑：

// packages/core/src/application/services/
├── catalogUpdateService.ts  // 主要编排
└── workspaceService.ts      // 工作空间操作

// 服务职责：
class CatalogUpdateService {
  async checkForUpdates(options: CheckOptions): Promise<UpdateReport>;
  async updateCatalog(options: UpdateOptions): Promise<UpdateResult>;
  async analyzeImpact(catalog: string, package: string): Promise<ImpactAnalysis>;
}

CLI 层设计

CLI 层为核心领域提供清洁的接口：

// apps/cli/src/cli/commands/
├── checkCommand.ts     // 检查命令实现
├── updateCommand.ts    // 带验证的更新命令
├── analyzeCommand.ts   // 影响分析命令
├── workspaceCommand.ts # 工作空间管理
├── themeCommand.ts     # 主题配置
├── securityCommand.ts  # 安全扫描
└── initCommand.ts      // 工作空间初始化

// 每个命令遵循一致的模式：
export class CheckCommand {
  constructor(
    private readonly catalogService: CatalogUpdateService,
    private readonly validator: CommandValidator,
    private readonly formatter: OutputFormatter
  ) {}

  async execute(options: CheckCommandOptions): Promise<void> {
    const validation = this.validator.validateCheckOptions(options);
    if (!validation.isValid) {
      throw new ValidationError(validation.errors);
    }

    const result = await this.catalogService.checkForUpdates(options);
    const formatted = this.formatter.format(result, options.format);
    console.log(formatted);
  }
}

测试架构

跨所有层的全面测试策略：

├── packages/core/src/**/__tests__/     # 单元测试
├── packages/utils/src/**/__tests__/    # 工具测试
├── apps/cli/src/**/__tests__/         # CLI 单元测试
├── tests/
│   ├── e2e/                          # 端到端测试
│   ├── integration/                  # 集成测试
│   └── fixtures/                     # 测试夹具
└── .github/workflows/
    └── test.yml                      # CI 测试管道

性能考虑

PCU 针对大型 monorepo 的性能进行了优化：

// 智能缓存减少 API 调用
class Cache<T> {
  constructor(
    private readonly options: {
      ttl: number; // 生存时间
      maxSize: number; // 内存限制
      persistToDisk: boolean; // 文件缓存
      strategy: 'lru' | 'fifo' | 'lfu'; // 驱逐策略
    }
  ) {}

  async get(key: string): Promise<T | null>;
  async set(key: string, value: T): Promise<void>;
  getStats(): CacheStats; // 命中率、内存使用
}

此页面对您有帮助吗？