命令式 vs 声明式（进阶）
本页补全你在入门页看不到的“工程化细节”：什么时候该选哪种范式、如何写得更稳、更可维护、也更利于 Visualizer 解析与调试。
入门对照示例见：声明式 vs 命令式（入门）
1) 声明式 vs 命令式
| 维度 | 声明式（Declarative） | 命令式（Imperative） |
|---|---|---|
| 更适合 | 拓扑结构稳定、希望结构一眼可读 | 拓扑需要按配置/运行时动态拼装 |
| 代码形态 | “描述结构是什么” | “一步步把结构搭出来” |
| 区别 | 更直观，代码更加简洁 | 更灵活，方便设置超参数和封装成复合组件 |
| visualizer | 可视化预览更稳定 | 遇到复杂的控制接口可能导致visualizer失效 |
| 灵活性 | 中（依赖声明表达能力） | 高（可以写任何 Python 逻辑） |
2) 声明式开发范式
声明式开发范式主要优势在于：
- 结构集中：拓扑变更主要体现在
nodes/edges； - 装配稳定：节点参数通过
NodeTemplate管理，避免位置参数带来的维护风险。
关于 NodeTemplate 的完整机制（含 Shared/Factory 与 template_* 作用域覆写）请单独阅读：
NodeTemplate（模板、作用域与依赖生命周期）。
3) 命令式开发范式
命令式开发范式主要优势在于：
- 结构灵活：拓扑需要按配置/运行时动态拼装；
- 参数集中：在命令式中，
NodeTemplate常用于集中管理model / formatters / memories / retrievers等默认配置，再在具体节点上覆写少量差异参数。
4) 可以混用两种范式吗？
可以，而且我们建议您这样做。
- 对于复杂的子图，建议用命令式范式开发，然后用
Graph封装成一个复合组件，再在主图中声明式引用。 - 对于静态的子图，建议使用声明式范式直接开发，方便维护。