b1e16be25d
- 重构LanguageUtils为LanguageService，实现ILanguageService接口 - 移除自定义验证管道和装饰器，使用标准NestJS验证 - 集成框架ValidatorService进行业务验证 - 简化目录结构，移除不必要的子目录 - 支持模块化语言包加载（common、user、order等） - 统一API响应格式（code、msg、data、timestamp） - 添加ValidationExceptionFilter处理多语言验证错误 - 完善多语言示例和文档
4.5 KiB
4.5 KiB
🚀 工具快速开始指南
📋 核心功能
- Dry-run 模式 - 预览生成结果，不实际修改文件
- Quality Gate - 自动化质量检查（TypeScript + ESLint）
- 模块化生成器 - 12个专用生成器，职责清晰
⚡ 快速命令
1. 完整迁移（推荐）
# 正常执行
node tools/migration-coordinator.js
# Dry-run 模式（仅预览）
DRY_RUN=true node tools/migration-coordinator.js
2. 单独运行生成器
# 实体生成器
node tools/generators/entity-generator.js
# 实体生成器 (dry-run)
DRY_RUN=true node tools/generators/entity-generator.js
# 控制器生成器
node tools/generators/controller-generator.js --dry-run
3. 质量检查
# 完整质量检查
node tools/generators/quality-gate.js
# 快速检查（仅核心层）
node tools/generators/quality-gate.js quick
4. 验证修复
# 验证所有修复是否正确
node tools/test-fixes.js
🎯 典型工作流
场景1: 首次迁移
# 步骤1: 发现PHP文件
node tools/php-file-discovery.js
# 步骤2: 预览迁移结果（dry-run）
DRY_RUN=true node tools/migration-coordinator.js
# 步骤3: 确认无误后执行实际迁移
node tools/migration-coordinator.js
# 步骤4: 质量检查
node tools/generators/quality-gate.js
场景2: 单独生成某个模块
# 步骤1: 预览实体生成
DRY_RUN=true node tools/generators/entity-generator.js
# 步骤2: 实际生成实体
node tools/generators/entity-generator.js
# 步骤3: 生成控制器
node tools/generators/controller-generator.js
# 步骤4: 生成服务
node tools/generators/service-generator.js
# 步骤5: 生成模块文件
node tools/generators/module-generator.js
场景3: 验证和质量检查
# 验证修复
node tools/test-fixes.js
# 质量检查
node tools/generators/quality-gate.js
# 如果有错误，查看详细输出
VERBOSE=true node tools/generators/quality-gate.js
🔧 环境变量
| 变量 | 作用 | 示例 |
|---|---|---|
DRY_RUN |
启用 dry-run 模式 | DRY_RUN=true node tools/... |
VERBOSE |
详细输出模式 | VERBOSE=true node tools/... |
📁 核心文件
| 文件 | 作用 | 何时使用 |
|---|---|---|
migration-coordinator.js |
主协调器 | 完整迁移流程 |
base-generator.js |
基础生成器 | 被其他生成器继承 |
quality-gate.js |
质量门禁 | 质量检查 |
test-fixes.js |
验证脚本 | 验证修复是否正确 |
💡 小技巧
1. 使用 dry-run 避免误操作
始终先用 dry-run 模式预览结果：
DRY_RUN=true node tools/migration-coordinator.js
2. 详细输出帮助调试
遇到问题时启用详细输出：
VERBOSE=true node tools/generators/entity-generator.js
3. 组合使用
# 同时启用 dry-run 和详细输出
DRY_RUN=true VERBOSE=true node tools/migration-coordinator.js
4. 快速质量检查
开发过程中频繁运行快速检查：
node tools/generators/quality-gate.js quick
⚠️ 注意事项
-
首次运行前备份
- 建议先用 dry-run 模式预览
- 确认结果正确后再实际执行
-
Quality Gate 可能失败
- TypeScript 编译错误
- ESLint 规范问题
- 可以先生成代码，后续修复
-
生成器顺序建议
实体 → 验证器 → 服务 → 控制器 → 模块 -
遇到错误时
- 查看错误日志
- 使用 VERBOSE 模式
- 检查 PHP 源文件是否存在
🆘 常见问题
Q: Dry-run 模式不生效？
检查环境变量设置：
# macOS/Linux
DRY_RUN=true node tools/...
# Windows PowerShell
$env:DRY_RUN="true"; node tools/...
# Windows CMD
set DRY_RUN=true && node tools/...
Q: Quality Gate 一直失败？
可能原因：
- TypeScript 配置问题
- ESLint 配置问题
- npm script 未配置
检查 package.json:
{
"scripts": {
"type-check": "tsc --noEmit",
"lint": "eslint src --ext .ts"
}
}
Q: 生成的文件不符合预期？
- 检查 PHP 源文件是否存在
- 使用 VERBOSE 模式查看详细日志
- 检查 php-discovery-result.json 数据
📚 更多信息
- 完整文档: README.md
- 迁移规则: MIGRATION-RULES.md
- 修复总结: FIX-SUMMARY.md
- 基础设施指南: INFRASTRUCTURE-USAGE-GUIDE.md
祝你使用愉快！ 🎉