3.2 图的编译与验证

3.2 图的编译与验证

编译期能拦下什么

本节在全册位置：compile 不是走过场。它做拓扑检查：是否有孤立节点、START/END 是否连通、条件边返回值是否都有去处。错误在编译期抛出，比运行时炸图便宜得多。我们把编译当成「图的单元测试」，每次改完都 compile 一次。

验证：连通性与孤儿节点

编译会校验每个被 add_node 的节点都能从 START 到达、且能到 END；条件边路由返回的键必须在映射中。Pydantic 状态还会校验字段类型。常见报错：GraphValueError（边指向不存在节点）、状态字段缺失。把这些在编译期修掉，运行时更稳。类比物理：编译像出厂质检，连通性像管路打压测试。我们主张把编译写进 CI，图结构变更自动阻断。

from typing import TypedDict
from langgraph.graph import StateGraph, START, END

class S(TypedDict):
    v: int

def a(s: S):
    return {"v": 1}

b = StateGraph(S)
b.add_node("a", a)
b.add_edge(START, "a")
#  3.2 图的编译与验证
b.add_edge("a", END)
g = b.compile()
print("编译通过", g.invoke({"v": 0}))
​

# 条件边返回值必须可映射
def route(s):
    return "ok" if s["v"] else "bad"
b.add_conditional_edges("a", route, {"ok": END, "bad": "a"})
# 这比运行时跑到一半发现无去处要友好得多
​

案例：抓出孤儿节点

背景：重构时删除某节点却忘了清边，留下悬空引用，图看起来连着其实跑不通。

操作：compile 立即报错指出边指向未知节点。

结果：在本地就发现，而非线上崩溃，省一次回滚。

解读：把图当一等数据结构，编译器替你做静态检查，是图式编排的隐形红利。

变式：配合类型检查（mypy）可进一步在编辑期发现状态字段 misuse，把错误左移。

工程清单

• 编译期做连通性与类型检查，错误比运行时便宜，值得写进 CI 自动阻断图结构变更。

• 条件边返回值必须都能在映射里找到去处，否则编译期报键缺失，比运行中途无去处友好。

• Pydantic 状态还会校验字段类型，提前发现字段 misuse，比运行时 AttributeError 更早。

常见误区

跳过编译直接 invoke 未连 END 的图，线上跑飞才定位，把静态检查的钱省成了事故的钱；编译器替你做的连通性检查是隐形红利。

常见编译错误一览

报错信息第一次看会慌，其实类型很有限。把这几种记熟，看到报错就能直接定位：

定位顺序推荐「从结构到字段」：先看是不是节点名、边的问题（大多数），再看是不是状态字段问题。编译器输出通常带了节点名，先搜代码里有没有这个节点，比通读报错快。

把编译检查写进自动化

编译期检查的价值要在团队里放大，最直接的做法是让 CI 跑一次「编译 + 冒烟」，任何图结构改动都会阻断合并：

# tests/test_graphs.py：每个图编译一次并跑最小输入
import pytest
from myapp.graphs import build_research_graph

def test_research_graph_compiles():
    g = build_research_graph()
    g.compile()                          # 结构错误在这里暴露
    out = g.invoke({"messages": []})     # 冒烟：空输入也能跑通
    assert out is not None
​

冒烟输入的选取有个原则：能覆盖到每一条条件边。空输入跑通只证明主干，边界值（如分数 59/60 分界、空列表）才证明分支。图结构每变化一次，测试里的输入矩阵也该跟着长，把「结构正确」变成可回归的资产，而不是靠人肉回忆。

TypedDict 与 Pydantic 的校验差异

状态 schema 两种写法，编译期行为不一样：

实践建议：原型期用 TypedDict 最少摩擦；一旦状态里出现「可空、有默认值、嵌套约束」的需求，直接切 Pydantic。切过去以后记得给字段加类型和默认值，编译器会在错误字段进入状态之前就拦住，比运行时 AttributeError 早得多。

条件边映射里的 END 与去重细节

编译验证对条件边特别严格，有两个细节常被忽略：END 必须出现在映射里才能作为合法去向，返回值集合里有重复项会被编译器拒绝。

# 正确：END 在映射中显式声明
b.add_conditional_edges("judge", judge,
    {"pass": "passed", "fail": "retry", "end": END})

# 错误：返回列表里出现重复节点名，编译直接报错
# b.add_conditional_edges("judge", judge, ["a", "a", "b"])
​

这意味着想表达「两个分支都去同一个节点」时，合并键而不是写重复值。编译期把这些边界检查做完，运行时就不用为「跑了一半发现去向不存在」买单。把条件边视为图里最需要编译验证的部位——它的返回值是动态的，唯一能提前拦截的只有这一步。

最后补一个工程习惯：把「编译通过」作为每次改图的收尾动作。无论改动多小，加一个节点、改一个边，都立刻 compile 一次再继续。编译失败时的报错上下文是最新鲜的，当场修比堆到最后一起排要省得多。这和我们前面说的「把编译当单元测试」是同一件事的两个说法，本质都是让错误在离源头最近的地方暴露。