7.4 最佳实践与设计模式总结

7.4 最佳实践与设计模式总结

哪些经验值得记

本节在全册位置：沉淀可复用的纪律。图式编排最易犯的错是「把控制流塞进 prompt」与「状态塞太多」。下面给出一组经过验证的模式，照着做能少走弯路。这些模式不是教条，而是前面各章踩坑的抽象。

模式：五条可考核纪律

一、状态只放跨节点数据，临时变量留局部。二、循环必须配退出条件，防死循环。三、敏感/写操作前置 interrupt 人工确认。四、可序列化优先，密钥不进状态。五、结构优先声明式，流向数据驱动才用编程式。这些模式在前面章都有对应落点。类比物理：像工程规范，照做少出事故。纪律提前遵循，比事后返工省得多。

# 模式三的通用封装：任何写操作加人工闸
from langgraph.types import interrupt
from langgraph.graph import Command

def human_gate(s, action):
    decision = interrupt({"action": action, "preview": s})
    if decision != "allow":
        return Command(goto=END, update={"blocked": True})
    return {}
# 这是上线前最该加的一层
​

# 模式二的退出守卫：计数通道防死循环
from typing import TypedDict, Annotated
import operator
class S(TypedDict):
    round: Annotated[int, operator.add]
def guard(s):
    return END if s["round"] >= 5 else "loop"
# 软上限（模型自报）加硬上限（计数），双保险
​

案例：一次返工复盘

背景：初版把整个流程写进一个超长 prompt，常跑飞且无审计。

操作：按上面五条重构成图：状态瘦身、循环加守卫、写操作加闸。

结果：稳定性与可维护性明显提升，排障时间大幅下降。

解读：模式的价值在「提前避坑」，而非事后补救，复盘的意义是把它变成团队习惯。

变式：把模式固化成团队内部节点模板库，新图直接套，一致性也更好。

工程清单

• 状态只放跨节点数据，临时变量留局部，这是状态设计的第一纪律。

• 循环必须配退出条件，敏感写操作前置 interrupt 人工确认，密钥不进状态。

• 结构优先声明式，流向数据驱动才用编程式，这五条在前面章都有对应落点。

常见误区

初版把整个流程写进一个超长 prompt，常跑飞且无审计；按五条重构成图后稳定性与可维护性明显提升，复盘的意义是把它变成团队习惯，比事后返工省得多。

模式落地检查单

五条纪律若只停留在文档，等于没写；把它变成「提交前可跑的检查」，团队才会真的遵守。

# 极简图结构体检（示意）
def lint(graph):
    problems = []
    if not graph.checkpointer:
        problems.append("缺检查点：状态不可恢复")
    if any(n.has_side_effect and not n.has_gate for n in graph.nodes):
        problems.append("写节点缺人工闸")
    if not graph.has_loop_guard:
        problems.append("循环缺退出守卫")
    return problems
# 纪律从「人记得」变成「机器拦」
​

⚠️ 常见坑：五条写成 wiki 就结束，没人回看，事故照旧；纪律要落到 CI 检查或节点模板，强制生效才有意义。

💡 关键直觉：设计模式的价值不在「知道」，而在「每次新建图都自动符合」；把模式固化进模板与检查，是最省心的方式。

补充：检查单别只给开发看，运维与产品也该参与评审——安全与可恢复性往往是他们最先感知到问题，跨职能过一遍比开发自审更稳。

新项目建图的脚手架模板

五条纪律要落地，最直接的方式是把它固化进建图模板，让每张新图从第一行起就符合纪律：

# 新图脚手架：状态、守卫、人工闸一起到位
class S(TypedDict):
    msgs: Annotated[list, add_messages]          # 消息通道
    round: Annotated[int, operator.add]          # 循环计数（守卫用）
    errors: Annotated[list, operator.add]        # 错误记录（降级用）

def build():
    b = StateGraph(S)
    b.add_node("agent", call_model)              # 主体节点
    b.add_conditional_edges("agent", route)      # 路由 + 循环守卫
    return b.compile(checkpointer=MemorySaver())
​

脚手架的要点是「三件套默认在场」：消息通道、循环计数、错误记录。业务加节点时在这套骨架上填，而不是每次从零想状态。模板不是限制，是让团队里每个人写的图都长一个样子——结构统一了，互相 review 的成本就低。

常见反模式的警示表

五条纪律的反面就是常见事故，列成对照表，评审时逐条对：

评审时不用背条款，对照这张表看新图踩了几条就行。反模式之所以顽固，是因为它们写起来快、报错晚——违反纪律的代价通常在一周后才显现。把表放进评审模板，让检查发生在写代码时而不是出事时。

设计评审的提问清单

评审一张新图时，用下面六问代替泛泛的「你觉得怎么样」：

1. 每个节点的职责是不是一句话能说清？
2. 状态里每个字段，有没有第二个人知道它是干嘛的？
3. 循环的退出条件在图上画出来了吗？
4. 所有写操作前面，都能找到人工闸或去重键吗？
5. 这张图跑飞了，能定位到具体节点吗？
6. 下一个接手的人，能只看结构图就说出流程吗？

六问里只要有一问答不上来，就先别合代码。这些问题本身比答案更重要——它们迫使作者把图当「设计文档」而非「实现代码」来审视。把提问清单和脚手架一起放进团队的建图规范，五条纪律就从「记得」变成了「默认」。