作者：Antonio Zapater
2026年8月21日
英文原文：https://blogs.embarcadero.com/migrate-to-firedac-in-a-day-with-refind-and-kai/
如果你维护的 Delphi 应用程序仍然通过 BDE、ADO、IBX 或 dbExpress 与数据库通信，你可能已经（不止一次）考虑过迁移到 FireDAC。通常阻碍迁移的不是对 FireDAC 的疑虑，而是担心迁移意味着数周的机械性重命名、损坏的 DFM 文件以及在数百个单元中反复编译修复。
RAD Studio 已经内置了一个名为 reFind 的批量迁移引擎。它包含了 BDE、ADO、dbExpress 和 IBX 的规则模板（以及 AnyDAC 和 API 重命名套件），配合 IDE 内的智能 AI 助手 Kai，你可以分析大型代码库，针对你的项目轻度定制这些模板，运行 reFind 并让 Kai 进入修复循环模式，直到应用程序成功使用 FireDAC 构建。对于典型的业务应用程序，这通常只需要一天的工作量，而手工操作则需要数周。
本文是该工作流程的实用操作指南。
reFind.exe 位于你的 RAD Studio bin 文件夹中。它是一个支持 Perl 兼容正则表达式和 Delphi 迁移指令的命令行搜索替换工具：
Embarcadero 还在 FireDAC Samples 目录下提供了现成的规则文件（如果还没有，你必须通过 RAD Studio 安装 "Samples"）：
C:\Users\Public\Documents\Embarcadero\Studio\\Samples\Object Pascal\Database\FireDAC\Tool\reFind
将 替换为 C:\Users\Public\Documents\Embarcadero\Studio\ 下的 Studio 版本文件夹（每个主要版本都会变化。例如，Florence 对应 37.0）。如果该目录不存在，说明你在安装时没有安装 Samples。
预定义的迁移套件包括：
如果你曾经打开过这些规则文件又立刻关掉了，你并不孤单。其语法非常强大但有些晦涩，容易误用。因此大多数发现 reFind 的团队都会做同一件事：在项目副本上运行默认模板，为批量重命名欢呼，然后在模板无法处理的一切问题上陷入停滞：连接定义、不受支持的 API、缺失的 FireDAC 基础组件，或者围绕 TQuery 或 TADOConnection 自行封装的包装类。
这正是 Kai 发挥作用的地方。它可以检查项目特定的代码，建议对迁移规则进行补充，然后帮助处理 reFind 无法自动处理的任何问题。
重要的区别在于，reFind 负责的是机械性的转换工作。它不应该决定你的应用程序应该如何架构。Kai 则在需要理解现有代码的部分发挥作用：识别模式、建议对迁移规则进行小幅修改，以及处理批量转换后的遗留问题。
没有必要让 Kai 在执行任何操作之前先消化一个包含上千个单元的应用程序。从数据模块、连接设置和具有代表性的窗体选择开始。这为它提供了足够的上下文来识别主要的迁移模式，而不会将整个工作变成 AI 驱动的重写。
在做任何事情之前首先要做的是：在分支上工作，如果你还没有使用版本控制，请务必使用。一个名为 MyApp_backup 的 zip 文件不算数，无论这个文件名听起来多么令人放心。版本控制为你提供了唯一的事实来源、对你所做的每一次更改的完整时间回溯能力，以及与团队轻松共享进度的方式，而不会破坏生产环境或需要共享 zip 文件。
Kai 对使用 BDE 的项目进行首次分析
让 Kai 首先查看数据模块和打开数据库的单元。让它统计旧版组件类型的出现次数，并识别应用程序如何建立连接。BDE 别名、dbxconnections.ini、ADO 连接字符串、硬编码的 DFM 参数等等。还值得让它标记明显的自定义派生类，如 TAppQuery 或 TMyConnection。
你需要一份简短的迁移摘要：使用了哪个数据库库、大约有多少代码受到影响，以及风险点在哪里。
从已安装的 Samples 目录中选择匹配的规则文件，例如：
C:\Users\Public\Documents\Embarcadero\Studio\\Samples\Object Pascal\Database\FireDAC\Tool\reFind\BDE2FDMigration\FireDAC_Migrate_BDE.txt
（或对应的 ADO / dbExpress / IBX 文件）。与上述相同的 替换提示。记住：如果该文件夹不存在，说明你没有安装 Samples。
这些文件已经包含了许多常见 BDE 到 FireDAC 变更的映射，包括 TQuery ➜ TFDQuery、DatabaseName ➜ ConnectionName、事务枚举、#remove SessionName 等。它们还在注释中记录了不直接支持的内容。将这些注释视为你的风险检查清单。
将模板和你的分析结果提供给 Kai。让 Kai 根据你的具体项目调整 reFind 规则：如有需要，将你自己的包装类映射到对应的 FireDAC 类型，一些项目特有的属性重命名，也许为你已知已移除的单元添加额外的 #unuse 或 #remove 行。审查提议的规则行。优先选择简单朴素的规则而非复杂的正则表达式。然后将类似 FireDAC_Migrate_BDE_MyApp.txt 的文件保存在官方文件旁边。
当你对分析结果满意且 Kai 已找到所有潜在问题后，让它将计划保存到硬盘上以备将来参考。这将帮助你在未来的提示中使用该计划文件，以防出现问题，同时节省 token 和时间。
在你全新的分支中运行它。在 samples 文件夹中，migrate.bat 文件遵循以下模式：
reFind.exe MyApp_FireDAC\*.pas MyApp_FireDAC\*.dfm /S /X:FireDAC_Migrate_BDE_MyApp.txt
Kai 可以从 IDE 代理工作流中为你组装并运行该命令，但我建议在它对大型目录树执行之前先确认路径和规则文件。
reFind 执行后，你可能会面临遗留工作。这是正常的，而这正是过去看起来需要“数月”的部分。典型的遗留问题：
在 RAD Studio 中打开迁移后的项目，将 Kai 指向构建错误，让它迭代处理：修复 ➜ 编译 ➜ 读取消息 ➜ 再次修复。留在 IDE 中操作。这个循环正是“从聊天中粘贴迁移建议”与“真正能完成项目的代理”之间的区别。
从 BDE 完全迁移到 FireDAC 后的遗留问题分析
目标不是保证在一天内完成迁移。目标是在一天内将一个相当常规的应用程序从“到处都是旧版数据访问”转变为可编译的 FireDAC 基线。
非常大的项目（数千个单元、深层自定义数据层、大量使用 ADO 记录集）在第一天之后可能仍需要一个短暂的加固冲刺。即便如此，收获是一样的：机械性的批量工作和第一个可编译基线不再是持续数周的无底洞。
Embarcadero 的 FireDAC 工具演示（在上述已安装的 Samples 路径下）是最安全的演练：
运行本地的 migrate.bat，打开生成的 FireDAC 副本，然后练习 Kai 的收尾工作：连接定义、等待光标、注释掉过时的 ini 加载代码，构建直到没有错误。一旦你理解了工作流程，就可以着手处理自己的应用程序了。
工作流程更容易交付而非描述，因此我们将其作为一个小工具包发布，你可以将其作为基础使用，同时更好地理解整个过程。
该仓库包含两个代理技能和七个提示词：
技能是一个包含 SKILL.md 文件的文件夹。在工具包根目录下：
.\install-skills.ps1
这会将两个技能复制到 %USERPROFILE%\.agents\skills，这通常是技能存放的位置（取决于具体的代理）。之后开始新的聊天以便它们被加载。其他代理的路径以及当你的代理不支持技能时的备选方案，都在仓库的 README 中。
这些提示词故意设计得通用：你需要将自己的基类添加到搜索列表中，并在结构化步骤中添加自己的连接辅助类。
技能不会替代官方的 reFind 模板。它们教会代理如何使用这些模板，以及在模板说明某个 API 没有 FireDAC 对应项时停止。
如果你正在维护一个 BDE、ADO、dbExpress 或 IBX 应用程序，你不一定需要将 FireDAC 迁移视为重写。从现有的 reFind 模板开始，使用 Kai 识别项目特有的差距，在分支上运行转换，然后让 Kai 分析并处理编译器错误。
对于一个相当常规的业务应用程序，这可以将一个看似需要数周机械性工作的迁移转变为一天内就能获得可用基线的工作。
将 TQuery 迁移到 TFDQuery 的同一引擎还可以驱动其他批量现代化工作：跨 RAD Studio 版本的 API 重命名、移除过时的 DFM 属性、强制执行内部命名规则，或使用经过仔细审查的规则文件替换第三方模式。如果你对更多类似的博客文章感兴趣，涵盖现代化和重构工作流程或代码迁移，请在评论中告诉我们你想看到什么内容，我们会着手准备这些主题。
