wwjcloud-nest-v1/wwjcloud/docs/TOOLS-MIGRATION-USAGE.md

迁移工具使用指南

概述

迁移工具模块提供了从 PHP/Java 项目迁移到 NestJS 的完整解决方案。该模块基于 common 层的代码生成器，提供了多种调用方式。

架构设计

tools/
├── migration/
│   ├── migration.module.ts           # 迁移模块
│   ├── services/
│   │   ├── php-migration.service.ts  # PHP 迁移服务
│   │   ├── java-migration.service.ts # Java 迁移服务
│   │   └── generator-cli.service.ts  # 生成器 CLI 服务
│   └── controllers/
│       └── migration.controller.ts   # 迁移控制器
└── tools.module.ts                   # 工具模块入口

使用方式

1. 直接使用 common 层生成器

import { GeneratorService } from '@/common/generator';

@Injectable()
export class SomeBusinessService {
  constructor(private generatorService: GeneratorService) {}
  
  async createModule() {
    return this.generatorService.generate({
      tableName: 'sys_user',
      generateType: 1,
      generateController: true,
      generateService: true,
      generateEntity: true,
      generateDto: true,
      generateMapper: true,
      generateEvents: true,
      generateListeners: true,
    });
  }
}

2. 使用 tools 迁移服务

import { PhpMigrationService } from '@/tools/migration';

@Injectable()
export class MigrationService {
  constructor(private phpMigrationService: PhpMigrationService) {}
  
  async migrateFromPHP() {
    // 迁移单个表
    const result = await this.phpMigrationService.migrateTable('sys_user');
    
    // 批量迁移
    const tables = ['sys_user', 'sys_menu', 'sys_config'];
    const results = await this.phpMigrationService.migrateTables(tables);
    
    // 生成迁移报告
    const report = await this.phpMigrationService.generateMigrationReport(tables);
    
    return { result, results, report };
  }
}

3. 使用 CLI 服务

import { GeneratorCliService } from '@/tools/migration';

@Injectable()
export class CliService {
  constructor(private generatorCliService: GeneratorCliService) {}
  
  async generateFromCommandLine() {
    return this.generatorCliService.generateFromCLI({
      tableName: 'sys_user',
      moduleName: 'user',
      className: 'SysUser',
      author: 'NiuCloud Team',
      generateController: true,
      generateService: true,
      generateEntity: true,
      generateDto: true,
      generateMapper: true,
      generateEvents: true,
      generateListeners: true,
      outputDir: './generated',
    });
  }
}

API 接口

PHP 迁移接口

接口	方法	说明
/adminapi/migration/php/tables	GET	获取 PHP 项目表列表
/adminapi/migration/php/migrate	POST	迁移单个 PHP 表
/adminapi/migration/php/batch-migrate	POST	批量迁移 PHP 表
/adminapi/migration/php/report	POST	生成 PHP 迁移报告

Java 迁移接口

接口	方法	说明
/adminapi/migration/java/tables	GET	获取 Java 项目表列表
/adminapi/migration/java/migrate	POST	迁移单个 Java 表
/adminapi/migration/java/batch-migrate	POST	批量迁移 Java 表
/adminapi/migration/java/report	POST	生成 Java 迁移报告

通用生成器接口

接口	方法	说明
/adminapi/migration/tables	GET	获取所有表列表
/adminapi/migration/table/:tableName	GET	获取表信息
/adminapi/migration/generate	POST	生成代码
/adminapi/migration/preview	POST	预览代码
/adminapi/migration/batch-generate	POST	批量生成代码

请求示例

迁移单个表

POST /adminapi/migration/php/migrate
Content-Type: application/json

{
  "tableName": "sys_user",
  "options": {
    "generateController": true,
    "generateService": true,
    "generateEntity": true,
    "generateDto": true,
    "generateMapper": true,
    "generateEvents": true,
    "generateListeners": true
  }
}

批量迁移

POST /adminapi/migration/php/batch-migrate
Content-Type: application/json

{
  "tableNames": ["sys_user", "sys_menu", "sys_config"],
  "options": {
    "generateController": true,
    "generateService": true,
    "generateEntity": true,
    "generateDto": true,
    "generateMapper": true,
    "generateEvents": true,
    "generateListeners": true
  }
}

生成迁移报告

POST /adminapi/migration/php/report
Content-Type: application/json

{
  "tableNames": ["sys_user", "sys_menu", "sys_config"]
}

响应格式

成功响应

{
  "code": 200,
  "message": "迁移成功",
  "data": [
    {
      "filePath": "src/common/sysUser/controllers/adminapi/sysUser.controller.ts",
      "content": "...",
      "type": "controller"
    }
  ]
}

错误响应

{
  "code": 500,
  "message": "错误信息",
  "data": null
}

迁移报告格式

{
  "totalTables": 3,
  "successCount": 2,
  "failedCount": 1,
  "details": [
    {
      "tableName": "sys_user",
      "status": "success",
      "fileCount": 8,
      "analysis": {
        "tableName": "sys_user",
        "fields": [],
        "relations": [],
        "indexes": []
      }
    }
  ]
}

配置选项

GeneratorOptions

参数	类型	必填	说明
tableName	string	✅	数据库表名
moduleName	string	❌	模块名，默认从表名转换
className	string	❌	类名，默认从表名转换
addonName	string	❌	插件名，用于插件开发
author	string	❌	作者信息
generateType	number	✅	生成类型：1-预览，2-下载，3-同步
outputDir	string	❌	输出目录，默认项目根目录
generateController	boolean	❌	是否生成控制器，默认true
generateService	boolean	❌	是否生成服务，默认true
generateEntity	boolean	❌	是否生成实体，默认true
generateDto	boolean	❌	是否生成DTO，默认true
generateMapper	boolean	❌	是否生成数据访问层，默认false
generateEvents	boolean	❌	是否生成事件，默认false
generateListeners	boolean	❌	是否生成监听器，默认false
generateTest	boolean	❌	是否生成测试文件，默认false

最佳实践

1. 渐进式迁移: 先迁移核心表，再迁移业务表
2. 批量处理: 使用批量迁移接口提高效率
3. 预览模式: 先使用预览模式检查生成结果
4. 报告分析: 定期生成迁移报告分析进度
5. 错误处理: 妥善处理迁移过程中的错误

扩展开发

添加新的迁移源

1. 创建新的迁移服务类
2. 实现相应的接口方法
3. 在 migration.module.ts 中注册服务
4. 在 migration.controller.ts 中添加 API 接口

自定义生成逻辑

1. 继承 GeneratorService
2. 重写相关方法
3. 在迁移服务中使用自定义生成器

故障排除

常见问题

1. 表不存在: 检查表名是否正确
2. 权限不足: 检查数据库连接权限
3. 生成失败: 查看错误日志定位问题
4. 文件冲突: 检查输出目录是否已存在文件

调试技巧

1. 使用预览模式检查生成内容
2. 查看迁移报告了解详细状态
3. 检查数据库连接和表结构
4. 查看应用日志获取错误信息