# 命令式 vs 声明式（进阶）

本页补全你在入门页看不到的“工程化细节”：什么时候该选哪种范式、如何写得更稳、更可维护、也更利于 Visualizer 解析与调试。

> 入门对照示例见：[声明式 vs 命令式（入门）](/zh/start/declarative_vs_imperative)

---

## 1) 声明式 vs 命令式

| 维度 | 声明式（Declarative） | 命令式（Imperative） |
| --- | --- | --- |
| 更适合 | 拓扑结构稳定、希望结构一眼可读 | 拓扑需要按配置/运行时动态拼装 |
| 代码形态 | “描述结构是什么” | “一步步把结构搭出来” |
| 区别 | 更直观，代码更加简洁 | 更灵活，方便设置超参数和封装成复合组件 |
| visualizer | 可视化预览更稳定 | 遇到复杂的控制接口可能导致visualizer失效 |
| 灵活性 | 中（依赖声明表达能力） | 高（可以写任何 Python 逻辑） |

---

## 2) 声明式开发范式

声明式开发范式主要优势在于：

1) **结构集中**：拓扑变更主要体现在 `nodes/edges`；  
2) **装配稳定**：节点参数通过 `NodeTemplate` 管理，避免位置参数带来的维护风险。

关于 `NodeTemplate` 的完整机制（含 `Shared/Factory` 与 `template_*` 作用域覆写）请单独阅读：  
[NodeTemplate（模板、作用域与依赖生命周期）](/zh/guide/node_template)。

---

## 3) 命令式开发范式

命令式开发范式主要优势在于：

1) **结构灵活**：拓扑需要按配置/运行时动态拼装；
2) **参数集中**：在命令式中，`NodeTemplate` 常用于集中管理 `model / formatters / memories / retrievers` 等默认配置，再在具体节点上覆写少量差异参数。


## 4) 可以混用两种范式吗？

可以，而且我们建议您这样做。

- 对于复杂的子图，建议用命令式范式开发，然后用 `Graph` 封装成一个复合组件，再在主图中声明式引用。
- 对于静态的子图，建议使用声明式范式直接开发，方便维护。

---
