Zenstack项目中Tanstack-Query插件自动清理生成目录的优化实践

在基于Zenstack框架的前端开发过程中，Tanstack-Query插件作为数据查询层的重要工具，能够自动生成与数据模型对应的React Hooks。但在实际使用中发现，当数据模型发生变更时，旧版本生成的Hooks文件会残留在目标目录中，这可能导致开发者误引用已失效的Hooks接口，进而引发运行时错误。

问题本质分析

该问题的核心在于生成机制缺乏自清理能力。传统代码生成工具通常采用两种策略：

1. 增量更新：仅修改有变动的文件，保留其他文件
2. 全量覆盖：每次生成前清空目标目录，重新生成全部文件

Tanstack-Query插件原先采用增量更新策略，这在模型结构稳定的场景下能提高生成效率。但当数据模型发生破坏性变更（如删除表、修改字段类型）时，残留的旧Hooks可能：

• 引用不存在的模型方法
• 包含类型不匹配的参数
• 导致TypeScript类型检查失效

技术解决方案演进

临时解决方案

开发者可以通过构建脚本在生成前手动清理目录：

npx rimraf ./src/hooks
npx zenstack generate

这种方式虽然有效，但存在明显缺陷：

• 增加开发流程复杂度
• 容易遗漏执行清理步骤
• 不同成员可能采用不同实现方式

框架级解决方案

Zenstack 2.0.0-beta.8版本在插件层面实现了自动清理机制，具有以下技术特性：

1. 原子性操作：在生成新Hooks前，先清空目标目录
2. 事务性保证：确保清理和生成操作作为一个完整事务
3. 版本兼容：与现有配置格式保持向后兼容

最佳实践建议

对于升级到新版本的用户，建议：

1. 移除项目中手动清理目录的脚本逻辑
2. 检查CI/CD流程中的生成步骤是否包含冗余操作
3. 在团队内部同步该变更说明

对于仍在使用旧版本的用户，可以通过pre-generate脚本实现类似效果：

{
  "scripts": {
    "pregenerate": "rimraf ./src/hooks",
    "generate": "zenstack generate"
  }
}

技术影响评估

该优化带来的直接收益包括：

• 消除模型变更导致的隐式错误
• 简化开发者工作流
• 提升团队协作一致性

长期来看，这种确定性的生成策略更符合现代前端工程化的原则，使生成的代码始终与数据模型保持严格同步，为类型安全提供了基础保障。