code-migration

代码迁移

通过渐进式策略、破坏性变更分析、兼容性测试和自动化迁移工具，指导框架和库的迁移，帮助代码库安全地切换版本、框架和架构，同时最大限度降低风险并保持功能正常。

何时使用

在以下情况下使用此技能：

• 在主要框架版本之间升级（React、Angular、.NET 等）
• 在不同框架之间迁移（Angular 迁移到 React、jQuery 迁移到 Vue 等）
• 转换架构模式（单体架构转向微服务）
• 采用新的语言版本或运行时环境
• 使用现代替代方案替换已弃用的库
• 整合多个代码库或技术栈
• 为技术生命周期结束和弃用做好准备
• 实施渐进式迁移策略
• 自动化重复的迁移模式
• 验证迁移的正确性和完整性

我能做什么

1. 迁移规划

• 迁移策略选择：选择合适的迁移方式（大爆炸式、渐进式、并行式、绞杀者模式）
• 依赖项分析：梳理所有依赖项和兼容性约束
• 风险评估：评估迁移的技术和业务风险
• 工作量估算：估算迁移所需的时间、资源和复杂度
• 分阶段计划制定：定义分阶段推出和验证步骤

2. 破坏性变更分析

• API 表面对比：分析源 API 与目标 API 之间的差异
• 行为变更检测：识别功能和行为变更
• 弃用映射：跟踪已弃用功能及其替代方案
• 兼容性矩阵创建：构建全面的兼容性参考
• 迁移需求识别：确定需要变更的内容

3. 渐进式迁移支持

• 并行运行能力：支持旧版本和新版本同时运行
• 功能标志集成：实施功能开关，逐步推出变更
• 数据迁移规划：规划数据库和数据结构迁移
• 集成桥接层创建：构建兼容层和适配器
• 回滚策略制定：创建安全的回滚流程

4. 自动化迁移工具

• 代码转换生成：创建自动修改代码的脚本
• 测试迁移自动化：迁移并更新测试套件
• 配置迁移：自动更新配置文件
• 构建系统迁移：更新构建工具和流水线
• 部署自动化：自动化部署流程变更

5. 测试与验证

• 兼容性测试：验证功能是否保留
• 性能对比：比较迁移前后的性能
• 集成测试：测试与其他系统的接口
• 回归测试：确保现有功能没有回归
• 验收验证：验证迁移是否满足业务需求

6. 文档与培训

• 迁移指南编写：编写全面的迁移文档
• 团队培训材料：为新技术创建培训材料
• 知识传递规划：规划知识共享会议
• 支持文档：更新支持和运维文档
• 经验教训记录：记录迁移见解和最佳实践

涵盖的迁移类型

框架版本升级

• 前端：React 16 → 18、Angular 12 → 16、Vue 2 → 3
• 后端：.NET Framework → .NET Core/5/6/7/8、Spring Boot 主要版本升级
• 移动端：React Native 版本升级、Flutter SDK 升级
• 数据库：MySQL 5.7 → 8.0、PostgreSQL 11 → 16、MongoDB 3.6 → 7.0

框架间迁移

• 前端：Angular → React、jQuery → Vue、Backbone → React
• 后端：PHP → Node.js、Ruby on Rails → Django、.NET → Go
• 移动端：原生 iOS/Android → React Native/Flutter
• 数据库：MySQL → PostgreSQL、SQL Server → MySQL、Oracle → PostgreSQL

架构迁移

• 单体架构到微服务：拆分单体应用
• 服务端到客户端：从服务端渲染迁移到 SPA
• 本地部署到云端：迁移到云原生架构
• 同步到异步：迁移到事件驱动架构

语言迁移

• JavaScript 到 TypeScript：为 JavaScript 代码库添加类型安全
• Python 2 到 Python 3：升级 Python 版本
• Java 8 到 Java 17+：使 Java 代码库现代化
• PHP 5 到 PHP 8：升级 PHP 应用

分析技术

迁移策略选择算法

def select_migration_strategy(project_characteristics):
    """
    Select appropriate migration strategy based on project characteristics.
    """
    strategies = {
        'big_bang': {
            'score': 0,
            'conditions': ['small_codebase', 'low_complexity', 'minimal_dependencies']
        },
        'incremental': {
            'score': 0,
            'conditions': ['large_codebase', 'high_complexity', 'many_dependencies']
        },
        'parallel_run': {
            'score': 0,
            'conditions': ['business_critical', 'zero_downtime', 'high_availability']
        },
        'strangler_pattern': {
            'score': 0,
            'conditions': ['monolithic', 'legacy_system', 'gradual_replacement']
        }
    }
    
    # Score each strategy based on project characteristics
    for characteristic in project_characteristics:
        for strategy_name, strategy_info in strategies.items():
            if characteristic in strategy_info['conditions']:
                strategy_info['score'] += 1
    
    # Select highest scoring strategy
    selected_strategy = max(strategies.items(), key=lambda x: x[1]['score'])
    
    return {
        'strategy': selected_strategy[0],
        'score': selected_strategy[1]['score'],
        'rationale': generate_strategy_rationale(selected_strategy[0], project_characteristics)
    }

def generate_strategy_rationale(strategy, characteristics):
    """Generate rationale for selected migration strategy."""
    rationales = {
        'big_bang': "Complete migration in single phase suitable for small, simple codebases",
        'incremental': "Gradual migration reducing risk for large, complex systems",
        'parallel_run': "Maintain both old and new systems during transition for critical systems",
        'strangler_pattern': "Gradually replace legacy system components while maintaining functionality"
    }
    
    return rationales.get(strategy, "Standard migration approach")

破坏性变更分析

class BreakingChangeAnalyzer:
    def __init__(self, source_api, target_api):
        self.source_api = source_api
        self.target_api = target_api
        
    def analyze_breaking_changes(self):
        """Comprehensive breaking change analysis."""
        analysis = {
            'api_removals': self.find_removed_apis(),
            'signature_changes': self.find_signature_changes(),
            'behavior_changes': self.find_behavior_changes(),
            'deprecations': self.find_deprecations(),
            'new_requirements': self.find_new_requirements()
        }
        
        # Calculate migration complexity score
        analysis['complexity_score'] = self.calculate_complexity_score(analysis)
        analysis['migration_effort'] = self.estimate_migration_effort(analysis)
        
        return analysis
    
    def find_removed_apis(self):
        """Find APIs removed in target version."""
        removed = []
        
        for api in self.source_api:
            if api not in self.target_api:
                removed.append({
                    'api': api,
                    'type': 'removed',
                    'impact': 'high',
                    'migration_action': 'find_replacement_or_rewrite'
                })
        
        return removed
    
    def find_signature_changes(self):
        """Find APIs with changed signatures."""
        changed = []
        
        for api in self.source_api:
            if api in self.target_api:
                source_sig = self.source_api[api]['signature']
                target_sig = self.target_api[api]['signature']
                
                if source_sig != target_sig:
                    changed.append({
                        'api': api,
                        'type': 'signature_change',
                        'source_signature': source_sig,
                        'target_signature': target_sig,
                        'impact': 'medium',
                        'migration_action': 'update_calls'
                    })
        
        return changed

增量迁移规划器

def create_incremental_migration_plan(codebase, migration_strategy):
    """
    Create incremental migration plan with phases.
    """
    phases = []
    
    # Phase 1: Preparation
    phases.append({
        'phase': 1,
        'name': 'Preparation & Setup',
        'tasks': [
            'Set up new framework/project structure',
            'Configure build and deployment pipelines',
            'Implement feature flags for migration control',
            'Create compatibility layer/adapters',
            'Set up monitoring and observability'
        ],
        'success_criteria': [
            'New project builds successfully',
            'Feature flags operational',
            'Monitoring configured',
            'Rollback procedures tested'
        ]
    })
    
    # Phase 2: Dependency Migration
    phases.append({
        'phase': 2,
        'name': 'Dependency Migration',
        'tasks': [
            'Migrate shared libraries and utilities',
            'Update build dependencies',
            'Create shared interfaces and contracts',
            'Test library compatibility'
        ],
        'success_criteria': [
            'All dependencies compatible with both versions',
            'Shared libraries functioning',
            'Build system supports both versions'
        ]
    })
    
    # Phase 3: Component Migration
    components = identify_migration_components(codebase)
    for i, component_group in enumerate(chunk_components(components, 5), 3):
        phases.append({
            'phase': i,
            'name': f'Component Migration Group {i-2}',
            'components': component_group,
            'tasks': [
                f'Migrate {len(component_group)} components',
                'Update integration tests',
                'Perform component-level testing',
                'Enable via feature flags'
            ],
            'success_criteria': [
                'All components migrated successfully',
                'Integration tests passing',
                'Feature flags controlling migration',
                'No performance regressions'
            ]
        })
    
    # Final Phase: Cleanup
    phases.append({
        'phase': len(phases) + 1,
        'name': 'Cleanup & Optimization',
        'tasks': [
            'Remove old code and dependencies',
            'Clean up feature flags',
            'Optimize new implementation',
            'Update documentation',
            'Train team on new system'
        ],
        'success_criteria': [
            'Old code completely removed',
            'Performance meets targets',
            'Documentation updated',
            'Team trained and proficient'
        ]
    })
    
    return {
        'total_phases': len(phases),
        'estimated_duration': calculate_duration(phases),
        'phases': phases,
        'risk_mitigation': create_risk_mitigation_plan(phases)
    }

示例

# Analyze migration from Angular 12 to 16
npm run code-migration:analyze -- --source angular --source-version 12 --target angular --target-version 16 --codebase src/

# Create incremental migration plan
npm run code-migration:plan -- --strategy incremental --framework react --from 16 --to 18 --output migration-plan.json

# Generate automated migration scripts
npm run code-migration:generate -- --framework .net --from 4.8 --to 8.0 --codebase . --output migration-scripts/

# Test migration compatibility
npm run code-migration:test -- --source-code src/ --target-framework vue-3 --tests tests/ --output compatibility-report.json

# Execute phased migration
npm run code-migration:execute -- --plan migration-plan.json --phase 2 --dry-run

# Monitor migration progress
npm run code-migration:monitor -- --plan migration-plan.json --metrics coverage,performance,errors --dashboard

# Validate migration completeness
npm run code-migration:validate -- --source src/ --target dist/ --validation-tests tests/validation/

# Create rollback plan
npm run code-migration:rollback -- --plan migration-plan.json --trigger error-rate --threshold 1%

# Generate migration documentation
npm run code-migration:docs -- --plan migration-plan.json --template comprehensive --output docs/migration-guide.md

# Train team on migrated codebase
npm run code-migration:train -- --new-framework react-18 --training-modules all --output training-materials/

输出格式

代码迁移分析报告：

Code Migration Analysis Report
──────────────────────────────
Source: Angular 12 Application
Target: Angular 16
Analysis Date: 2026-02-26
Codebase Size: 45,328 lines, 247 files

Migration Strategy Recommendation: INCREMENTAL MIGRATION
Rationale: Large codebase with complex dependencies and business-critical functionality

Breaking Changes Analysis:
❌ Critical Changes: 12
⚠️ Medium Changes: 28
ℹ️ Minor Changes: 45
✅ Compatible: 320 APIs

Critical Breaking Changes:
1. ❌ Ivy Compiler Required (Impact: High)
   • Current: View Engine compiler
   • Required: Ivy compiler (Angular 13+)
   • Migration: Update angular.json and tsconfig.json
   • Effort: 8 hours

2. ❌ RxJS 7 Required (Impact: High)
   • Current: RxJS 6.6.7
   • Required: RxJS 7.8.0+
   • Breaking Changes: Operator function changes, observable creation
   • Effort: 16 hours

3. ❌ TypeScript 4.7+ Required (Impact: High)
   • Current: TypeScript 4.2.4
   • Required: TypeScript 4.7.2+
   • Migration: Update tsconfig.json, fix type errors
   • Effort: 12 hours

Dependency Analysis:
┌──────────────────────┬────────────┬────────────┬────────────┐
│ Dependency          │ Current    │ Required   │ Status     │
├──────────────────────┼────────────┼────────────┼────────────┤
│ @angular/core       │ 12.2.16    │ 16.2.0     ❌ Upgrade    │
│ @angular/cli        │ 12.2.18    │ 16.2.0     ❌ Upgrade    │
│ rxjs                │ 6.6.7      │ 7.8.0      ❌ Upgrade    │
│ typescript          │ 4.2.4      │ 4.7.2      ❌ Upgrade    │
│ zone.js             │ 0.11.4     │ 0.13.0     ⚠️ Compatible │
│ @angular/material   │ 12.2.13    │ 16.2.0     ❌ Upgrade    │
└──────────────────────┴────────────┴────────────┴────────────┘

Code Impact Assessment:
• Components affected: 142 (57% of total)
• Services affected: 45 (92% of total)
• Directives affected: 18 (75% of total)
• Pipes affected: 12 (100% of total)
• Tests affected: 245 (98% of total)

Migration Complexity Score: 78/100 (High Complexity)
Estimated Effort: 120-160 hours (3-4 weeks)

Incremental Migration Plan:
Phase 1: Foundation (1 week)
  • Update build system and dependencies
  • Configure Ivy compiler
  • Set up feature flags for migration

Phase 2: Core Libraries (1 week)
  • Migrate RxJS to version 7
  • Update TypeScript to 4.7+
  • Update zone.js compatibility

Phase 3: Angular Core (2 weeks)
  • Update @angular/core to v16
  • Migrate @angular/cli
  • Update component lifecycle methods

Phase 4: UI Libraries (1 week)
  • Update @angular/material
  • Migrate custom UI components
  • Update CSS and theming

Phase 5: Testing & Validation (1 week)
  • Update test utilities
  • Run comprehensive tests
  • Performance benchmarking

Risk Assessment:
• Technical Risk: HIGH (multiple breaking changes)
• Business Risk: MEDIUM (downtime during migration)
• Schedule Risk: MEDIUM (complex dependency chain)
• Team Risk: LOW (Angular expertise available)

Risk Mitigation Strategies:
1. Implement feature flags for gradual rollout
2. Maintain parallel branches during migration
3. Extensive automated testing
4. Regular stakeholder updates
5. Rollback procedures defined

Testing Strategy:
• Unit Tests: Update all 245 test files
• Integration Tests: Test component interactions
• E2E Tests: Verify user workflows
• Performance Tests: Compare before/after metrics
• Compatibility Tests: Verify browser support

Success Criteria:
1. All tests passing in new environment
2. Performance within 10% of baseline
3. Zero breaking changes in production
4. Team proficient with Angular 16 features
5. Documentation updated and complete

Tooling Recommendations:
1. Angular Update Guide (ng update)
2. RxJS upgrade helper
3. TypeScript migration scripts
4. Automated test migration tools
5. Performance monitoring setup

Next Steps:
1. Approve migration plan and timeline
2. Allocate development resources
3. Schedule migration window
4. Set up monitoring and alerting
5. Begin Phase 1 implementation

Migration Dashboard:
Status: PLANNING_COMPLETE
Current Phase: Preparation
Progress: 0%
Estimated Completion: 2026-03-26
Risks: 3 high, 2 medium, 1 low

JSON 输出格式：

{
  "analysis": {
    "source": "Angular 12 Application",
    "target": "Angular 16",
    "analysis_date": "2026-02-26",
    "codebase_size": {
      "lines": 45328,
      "files": 247,
      "components": 250,
      "services": 49,
      "directives": 24,
      "pipes": 12
    },
    "recommended_strategy": "incremental",
    "complexity_score": 78,
    "estimated_effort_hours": 140
  },
  "breaking_changes": {
    "critical": [
      {
        "id": "bc-angular-001",
        "description": "Ivy Compiler Required",
        "type": "compiler_change",
        "impact": "high",
        "current": "View Engine compiler",
        "required": "Ivy compiler (Angular 13+)",
        "migration_action": "Update angular.json and tsconfig.json",
        "estimated_effort_hours": 8
      },
      {
        "id": "bc-angular-002",
        "description": "RxJS 7 Required",
        "type": "dependency_change",
        "impact": "high",
        "current": "RxJS 6.6.7",
        "required": "RxJS 7.8.0+",
        "breaking_changes": "Operator function changes, observable creation",
        "estimated_effort_hours": 16
      }
    ],
    "medium": 28,
    "minor": 45,
    "compatible": 320
  },
  "dependencies": [
    {
      "name": "@angular/core",
      "current": "12.2.16",
      "required": "16.2.0",
      "status": "upgrade_required",
      "impact": "high"
    },
    {
      "name": "@angular/cli",
      "current": "12.2.18",
      "required": "16.2.0",
      "status": "upgrade_required",
      "impact": "high"
    }
  ],
  "impact_assessment": {
    "components_affected": 142,
    "components_percentage": 57,
    "services_affected": 45,
    "services_percentage": 92,
    "directives_affected": 18,
    "directives_percentage": 75,
    "pipes_affected": 12,
    "pipes_percentage": 100,
    "tests_affected": 245,
    "tests_percentage": 98
  },
  "migration_plan": {
    "phases": [
      {
        "phase": 1,
        "name": "Foundation",
        "duration_weeks": 1,
        "tasks": [
          "Update build system and dependencies",
          "Configure Ivy compiler",
          "Set up feature flags for migration"
        ],
        "success_criteria": [
          "New project builds successfully",
          "Feature flags operational",
          "Monitoring configured"
        ]
      },
      {
        "phase": 2,
        "name": "Core Libraries",
        "duration_weeks": 1,
        "tasks": [
          "Migrate RxJS to version 7",
          "Update TypeScript to 4.7+",
          "Update zone.js compatibility"
        ],
        "success_criteria": [
          "RxJS migration complete",
          "TypeScript compilation successful",
          "Zone.js compatibility verified"
        ]
      }
    ],
    "total_phases": 5,
    "total_duration_weeks": 6,
    "estimated_completion_date": "2026-03-26"
  },
  "risk_assessment": {
    "technical_risk": "high",
    "business_risk": "medium",
    "schedule_risk": "medium",
    "team_risk": "low",
    "mitigation_strategies": [
      "Implement feature flags for gradual rollout",
      "Maintain parallel branches during migration",
      "Extensive automated testing",
      "Regular stakeholder updates",
      "Rollback procedures defined"
    ]
  },
  "testing_strategy": {
    "unit_tests": {
      "count": 245,
      "action": "update_all"
    },
    "integration_tests": {
      "focus": "component interactions",
      "coverage": "high"
    },
    "e2e_tests": {
      "focus": "user workflows",
      "automation": "full"
    },
    "performance_tests": {
      "metrics": ["response_time", "memory_usage", "bundle_size"],
      "comparison": "before_after"
    }
  },
  "tooling_recommendations": [
    "Angular Update Guide (ng update)",
    "RxJS upgrade helper",
    "TypeScript migration scripts",
    "Automated test migration tools",
    "Performance monitoring setup"
  ],
  "next_steps": [
    "Approve migration plan and timeline",
    "Allocate development resources",
    "Schedule migration window",
    "Set up monitoring and alerting",
    "Begin Phase 1 implementation"
  ]
}

迁移仪表板：

Code Migration Dashboard
───────────────────────
Project: E-commerce Platform
Migration: Angular 12 → 16
Status: IN_PROGRESS
Current Phase: 3/5 (Angular Core Migration)

Progress Summary:
┌──────────────────────┬──────────┬────────────┬────────────┐
│ Phase                │ Status   │ Progress   │ Timeline   │
├──────────────────────┼──────────┼────────────┼────────────┤
│ 1. Foundation        │ ✅ Done  │ 100%       │ Feb 19-26  │
│ 2. Core Libraries    │ ✅ Done  │ 100%       │ Feb 26-Mar 5│
│ 3. Angular Core      │ 🔄 Active│ 65%        │ Mar 5-19   │
│ 4. UI Libraries      │ ⏳ Pending│ 0%        │ Mar 19-26  │
│ 5. Testing & Validation│ ⏳ Pending│ 0%        │ Mar 26-Apr 2│
└──────────────────────┴──────────┴────────────┴────────────┘

Current Phase Details:
• Components migrated: 92/142 (65%)
• Services migrated: 28/45 (62%)
• Tests passing: 78% (191/245)
• Performance: Within 5% of baseline
• Issues: 12 open (3 critical, 5 medium, 4 low)

Recent Activity:
• Mar 12: Migrated checkout component (critical path)
• Mar 11: Fixed RxJS operator compatibility issue
• Mar 10: Updated authentication service
• Mar 9: Performance regression detected and fixed

Upcoming Tasks:
1. Migrate product catalog component (priority: high)
2. Update shopping cart service (priority: high)
3. Fix remaining TypeScript errors (priority: medium)
4. Update remaining unit tests (priority: medium)

Risks & Issues:
• ⚠️ Critical: Product image component migration delayed
• ⚠️ Medium: CSS theming inconsistencies
• ✅ Resolved: RxJS migration completed successfully
• ✅ Resolved: Build system configuration fixed

Metrics:
• Code Coverage: 78% (target: 85%)
• Performance: 95% of baseline (target: 90%+)
• Test Pass Rate: 92% (target: 95%+)
• Migration Velocity: 12 components/week

Next Milestone: Complete Phase 3 by Mar 19
Overall Progress: 42%
Estimated Completion: Apr 2, 2026

注意事项

• 开始迁移前，先进行全面分析
• 根据风险承受能力和复杂度选择迁移策略
• 对大型复杂系统实施增量迁移
• 为业务关键型系统保留并行运行能力
• 全面测试对迁移成功至关重要
• 记录所有迁移决策及其理由
• 规划知识转移和团队培训
• 在迁移期间及之后密切监控性能
• 为意外问题准备回滚流程
• 通过庆祝里程碑，在漫长的迁移过程中保持团队士气