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