填坑 Anchorpy：我如何让 Python 无缝支持最新的 Anchor IDL 格式

填坑 Anchorpy：我如何让 Python 无缝支持最新的 Anchor IDL 格式

最近，我投入了不少精力在开发一个名为 "Codama" 的 Python 代码生成器。这个过程让我不得不深入研究 Solana 的各种数据格式、编码解码机制，也让我对 anchorpy 这个库有了全新的认识。正所谓“不写不要紧，一写吓一跳”，在重度使用和剖析 anchorpy 的过程中，我发现了一个足以劝退许多 Python Solana 开发者的“大坑”，并最终决定亲手把它填上。

这篇文章，就是记录我如何通过两个 Pull Request，让 anchorpy 彻底告别了对单一、老旧 IDL 格式的依赖，实现了对新、旧两种 Anchor IDL 格式的无缝支持。

缘起：从代码生成器到 Anchorpy 的“历史遗留问题”

我的项目 Codama，在某种程度上可以说是 anchorpy 的一个“复刻加强版”。它的核心目标是根据 Solana 程序的 IDL (Interface Description Language) 文件，自动生成 Python 客户端代码。要做好这件事，精准地解析 IDL 文件是第一步，也是最关键的一步。

在之前的一篇文章《Python 调用 Solana 的一些麻烦事》中，我就吐槽过 anchorpy 的一些不便之处。而这次，我遇到的问题则更为底层和致命：anchorpy 无法解析最新版的 Anchor 生成的 IDL 文件。

问题的根源在于：

1. Anchor IDL 格式的演进：Anchor IDL 格式本身也在演进。新旧版本的 IDL 在结构上存在差异（例如，新版 IDL 拥有 version 字段，且整体结构更为规范）。
2. anchorpy 的“内功”落后了：anchorpy 依赖一个名为 anchorpy-core 的内部库来解析 IDL。然而，anchorpy-core 的代码是为 旧版 IDL “硬编码” 的，完全不认识新格式。

这导致一个非常尴尬的局面：如果你用较新版本的 Anchor 工具链开发 Solana 程序，生成的 IDL 文件 anchorpy 根本无法使用。这无疑给 Python 开发者造成了巨大的障碍。

幸运的是，社区里已经有人意识到了这个问题。开发者 kevinheavey 创建了一个新库 anchorpy-idl，它专门用于解析新版的 Anchor IDL。

既然找到了症结所在，又有了现成的解决方案，我便决定动手，把这个坑彻底填平。

填坑三部曲：让 Anchorpy 重获新生

我的计划分为三步，清晰而直接：

1. 依赖替换：废除只支持旧格式的 anchorpy-core，让 anchorpy 主库全面转向支持新格式的 anchorpy-idl。
2. 向后兼容：在新库 anchorpy-idl 中增加对老版本 Anchor IDL 的转换支持，确保现有项目不受影响。
3. 全面测试：确保所有改动都通过测试，保证库的稳定性和可靠性。

第一步：依赖切换，核心引擎的“心脏移植”

这是整个手术的核心。我需要修改 anchorpy 的项目配置，将对 anchorpy-core 的依赖，彻底更换为对 anchorpy-idl 的依赖。

这不仅仅是修改一行 pyproject.toml 文件那么简单，还需要调整 anchorpy 内部调用 IDL 解析部分的代码，使其与 anchorpy-idl 的 API 对齐。

这个改动最终体现在我的第一个 PR 中：

• PR: feat: Switch to anchorpy-idl #163

通过这个 PR，anchorpy 的 IDL 解析能力得到了根本性的升级，从此具备了理解最新 Anchor IDL 格式的能力。

第二步：向后兼容，为“老用户”保驾护航

解决了新问题，但不能引入老问题。新的 anchorpy-idl 库虽然优秀，但它只支持新版 Anchor IDL。如果我们粗暴地切换过去，那么所有正在使用 anchorpy 的、基于旧版 IDL 的项目都会立刻崩溃。一个优秀的开源库升级，必须考虑到向后兼容性。

因此，我的第二个任务是让 anchorpy-idl 变得更“聪明”。我需要给它增加识别并转换旧版 IDL 的能力。

我的实现思路是： 在 anchorpy-idl 的加载函数中，增加一个判断逻辑。通过检查 IDL JSON 中是否存在 version 这样的新版特有字段，来判断其版本。如果判断为旧版 IDL，就在内存中将其动态转换成新版 IDL 的结构，然后再交给后续的解析器处理。

这样一来，无论用户传入的是新版还是旧版 Anchor IDL，anchorpy-idl 都能统一处理，输出标准的、可用的解析结果。

这个兼容性改造，就是我的第二个 PR：

• PR: feat: Add support for legacy IDL format #2

这个改动虽然代码量不大，但意义重大。它确保了 anchorpy 的升级对存量用户是无感、平滑的，避免了生态的割裂。

第三步：全面测试，确保万无一失

对于基础库的修改，再怎么强调测试的重要性也不为过。我使用了 rye test 命令来运行项目自带的测试套件。

我的测试策略覆盖了以下两个核心场景，这恰好对应了我的两个PR所要解决的问题：

1. 使用最新版的 Anchor IDL 文件进行测试，验证客户端生成和指令调用一切正常。这确保了我们切换到 anchorpy-idl 的主要目标得以实现。
2. 使用旧版的 Anchor IDL 文件进行测试，验证我添加的向后兼容转换逻辑能够正确生效，并且其功能与之前完全一致。

经过反复调试和验证，所有的测试用例都顺利通过（All tests pass!）。这标志着 anchorpy 的升级改造工作成功完成。

总结：从使用者到贡献者

这次经历对我而言，不仅仅是完成了一个技术任务。

1. 深化理解：通过亲手编写 Codama 生成器和改造 anchorpy，我对 Solana 的程序交互、数据编码（如 Borsh）以及 IDL 的本质有了前所未有的深入理解。
2. 开源贡献：从一个抱怨工具不好用的“使用者”，转变为一个动手解决问题的“贡献者”，这种感觉非常棒。当你发现一个问题，并且有能力去修复它，这不仅能帮助自己，更能惠及整个开发者社区。
3. Python & Solana 生态：anchorpy 是连接 Python 世界和 Solana Anchor 框架的关键桥梁。这次升级，清除了一个长期存在的开发障碍，让 Python 开发者可以更流畅、更舒心地构建 Solana 应用，无疑对整个生态是件大好事。

如果你也是一名挣扎在 Python 和 Solana 技术栈中的开发者，希望我的经历能给你带来一些启发。当我们遇到工具的“坑”时，除了绕道而行，或许也可以选择拿起铲子，亲手把它填平。这不仅是技术的修行，也是一种开源精神的体现。