react-native-update-cli/example/README.zh-CN.md

自定义模块和工作流示例

这个目录包含了 React Native Update CLI 自定义模块和工作流的完整示例，演示如何扩展 CLI 的功能。

📁 目录结构

example/
├── modules/                    # 自定义模块示例
│   ├── custom-deploy-module.ts # 自定义部署模块
│   └── analytics-module.ts     # 分析统计模块
├── workflows/                  # 自定义工作流示例
│   └── custom-workflows.ts     # 复杂工作流集合
├── scripts/                    # 执行脚本示例
│   ├── register-modules.ts     # 模块注册和执行
│   ├── provider-api-example.ts # Provider API 使用示例
│   └── workflow-demo.ts        # 工作流演示脚本
└── README.md                   # 本文档

🚀 快速开始

1. 运行模块注册和执行示例

# 编译TypeScript (如果需要)
npm run build

# 运行模块示例
npx ts-node example/scripts/register-modules.ts

2. 运行Provider API示例

npx ts-node example/scripts/provider-api-example.ts

3. 运行工作流演示

# 运行所有工作流演示
npx ts-node example/scripts/workflow-demo.ts

# 交互式执行特定工作流
npx ts-node example/scripts/workflow-demo.ts interactive canary-deployment --version 1.0.0 --initialRollout 5

# 多环境部署工作流
npx ts-node example/scripts/workflow-demo.ts interactive multi-env-deploy --version 1.0.0

# 回滚工作流
npx ts-node example/scripts/workflow-demo.ts interactive rollback-workflow --targetVersion 0.9.5

📦 自定义模块示例

1. 自定义部署模块 (custom-deploy-module.ts)

这个模块演示了如何创建一个完整的部署管理模块，包含：

命令：

• deploy-dev: 部署到开发环境
• deploy-prod: 部署到生产环境
• rollback: 回滚到指定版本

工作流：

• full-deploy: 完整部署流程（开发 → 测试 → 生产）
• hotfix-deploy: 热修复快速部署流程

使用示例：

import { moduleManager } from 'react-native-update-cli';
import { customDeployModule } from './modules/custom-deploy-module';

// 注册模块
moduleManager.registerModule(customDeployModule);

// 执行开发部署
await moduleManager.executeCommand('deploy-dev', {
  args: [],
  options: { platform: 'ios', force: true }
});

// 执行完整部署工作流
await moduleManager.executeWorkflow('full-deploy', {
  args: [],
  options: { version: '1.2.3' }
});

2. 分析统计模块 (analytics-module.ts)

演示如何创建分析和统计功能：

命令：

• track-deployment: 记录部署统计信息
• deployment-report: 生成部署报告

工作流：

• deploy-with-analytics: 带统计的部署流程

🔄 自定义工作流示例

1. 灰度发布工作流 (canary-deployment)

实现完整的灰度发布流程：

• ✅ 准备灰度发布环境
• ✅ 初始小范围部署
• ✅ 监控关键指标
• ✅ 基于指标自动扩大发布范围
• ✅ 最终验证

await moduleManager.executeWorkflow('canary-deployment', {
  args: [],
  options: {
    version: '2.1.0',
    initialRollout: 10,    // 初始10%用户
    autoExpand: true       // 自动扩大范围
  }
});

2. 多环境发布工作流 (multi-env-deploy)

实现标准的多环境发布流程：

• ✅ 部署到开发环境
• ✅ 运行集成测试
• ✅ 部署到预发布环境
• ✅ 运行端到端测试
• ✅ 部署到生产环境
• ✅ 部署后验证

await moduleManager.executeWorkflow('multi-env-deploy', {
  args: [],
  options: {
    version: '2.1.0',
    skipProduction: false,     // 不跳过生产部署
    forceProduction: false     // 测试失败时不强制部署
  }
});

3. 回滚工作流 (rollback-workflow)

安全的应用回滚流程：

• ✅ 验证目标版本
• ✅ 备份当前状态
• ✅ 执行回滚操作
• ✅ 验证回滚结果
• ✅ 通知相关人员

await moduleManager.executeWorkflow('rollback-workflow', {
  args: [],
  options: {
    targetVersion: '2.0.5',
    skipVerification: false
  }
});

🛠️ Provider API 使用示例

Provider API 提供了编程式接口，适合在应用程序中集成：

基本使用

import { moduleManager } from 'react-native-update-cli';

const provider = moduleManager.getProvider();

// 打包应用
const bundleResult = await provider.bundle({
  platform: 'ios',
  dev: false,
  sourcemap: true
});

// 发布版本
const publishResult = await provider.publish({
  name: 'v1.0.0',
  description: 'Bug fixes',
  rollout: 100
});

// 上传文件
const uploadResult = await provider.upload({
  filePath: 'app.ipa',
  platform: 'ios'
});

应用管理

// 创建应用
await provider.createApp('MyApp', 'ios');

// 获取当前应用
const { appId, platform } = await provider.getSelectedApp('ios');

// 列出版本
const versions = await provider.listVersions(appId);

// 更新版本
await provider.updateVersion(appId, versionId, {
  name: 'v1.1.0',
  description: 'New features'
});

自动化服务类

class DeploymentService {
  private provider = moduleManager.getProvider();
  
  async buildAndPublish(platform: Platform, version: string) {
    // 1. 打包
    const bundleResult = await this.provider.bundle({
      platform, dev: false, sourcemap: true
    });
    
    // 2. 发布
    const publishResult = await this.provider.publish({
      name: version, rollout: 100
    });
    
    return { bundleResult, publishResult };
  }
}

🎯 高级特性

1. 工作流验证

const workflow: CustomWorkflow = {
  name: 'my-workflow',
  steps: [...],
  validate: (context) => {
    if (!context.options.version) {
      console.error('必须指定版本号');
      return false;
    }
    return true;
  }
};

2. 条件执行

const step: WorkflowStep = {
  name: 'conditional-step',
  execute: async (context) => { /* ... */ },
  condition: (context) => {
    return context.options.environment === 'production';
  }
};

3. 错误处理

try {
  const result = await moduleManager.executeCommand('deploy-prod', {
    args: [],
    options: {} // 缺少必需参数
  });
} catch (error) {
  console.error('执行失败:', error.message);
}

4. 自定义工作流注册

const provider = moduleManager.getProvider();

provider.registerWorkflow({
  name: 'custom-workflow',
  description: '自定义工作流',
  steps: [
    {
      name: 'step1',
      execute: async (context, previousResult) => {
        // 执行逻辑
        return { step1: 'completed' };
      }
    }
  ]
});

// 执行工作流
await provider.executeWorkflow('custom-workflow', {
  args: [],
  options: {}
});

📝 最佳实践

1. 模块设计

• 单一职责: 每个模块专注于特定功能领域
• 清晰命名: 使用描述性的命令和选项名称
• 完整文档: 为所有命令和选项提供描述
• 错误处理: 提供清晰的错误信息和恢复建议

2. 工作流设计

• 原子操作: 每个步骤应该是原子的，可独立执行
• 状态传递: 合理使用 previousResult 传递状态
• 错误恢复: 考虑失败时的清理和恢复机制
• 进度反馈: 提供清晰的进度信息给用户

3. 开发建议

• 类型安全: 充分利用 TypeScript 类型系统
• 测试覆盖: 为自定义模块编写测试
• 文档维护: 保持示例和文档的同步更新
• 版本管理: 为模块设置合适的版本号

🐛 故障排除

常见问题

1. 模块注册失败

   // 确保模块符合 CLIModule 接口
   const module: CLIModule = {
     name: 'my-module',
     version: '1.0.0',
     commands: [...],
     workflows: [...]
   };
   

2. 命令执行失败

   // 检查命令名称和参数
   await moduleManager.executeCommand('correct-command-name', {
     args: [],
     options: { requiredParam: 'value' }
   });
   

3. 工作流验证失败

   // 确保提供所有必需的选项
   await moduleManager.executeWorkflow('workflow-name', {
     args: [],
     options: { version: '1.0.0' } // 必需参数
   });
   

📖 相关文档

• 主项目 README
• 模块化架构文档
• API 参考文档
• 贡献指南

🤝 贡献

欢迎提交更多示例和改进建议！请查看主项目的贡献指南。