以下组件分层、依赖图与边均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。分层号 0/1/2 是讲解用的一种分层法,真实系统有自己的分层语义;但"反向依赖会被检出、循环依赖会被检出"这一条不变。
1.2 给了四个角色,但四个角色不是平等协作的:它们之间有明确的依赖方向。方向是架构里最容易被忽视的不变量。功能可以慢慢加,依赖方向一旦错了,后续每一个变更都在错误的地基上叠加。
这一节把依赖方向讲成三条规则:分层禁止反向依赖、禁止循环、可自动检查。实验用一个依赖图检查器,在三个"运行时系统"依赖图上演示违规边与环的检出,并回答一个反直觉的问题:为什么一条小小的反向边,往往直接就制造出一个环。
分层、反向依赖与循环
先定分层。一个 Agent 运行时大致分三层:
| 层号 | 层 | 组件 |
|---|---|---|
| 0 | 接入层 | api |
| 1 | 领域层 | orchestrator、worker |
| 2 | 基础设施层 | store、model_gateway |
不变量一:组件只能依赖同层或更低层。 api(层 0)可以依赖 orchestrator(层 1);orchestrator(层 1)可以依赖 store(层 2);worker(层 1)可以依赖 model_gateway(层 2)。反之不行:store(层 2)去依赖 api(层 0)就是反向边。
不变量二:依赖图无环。 有环意味着"先构建谁"无法回答,故障会绕回来传播,测试和发布顺序都变得不可推导。
这两条不变量为什么要自动检查?因为代码评审里它们最容易被忽略。反向边往往藏在一句"顺手 import"里,环往往藏在三次间接引用之后。人工 review 抓不全,必须让构建或 CI 在每次变更后自动跑检查器。
为什么反向依赖往往直接成环
这里有一个值得展开的观察。反向边不是"可能造成环",而是往往直接就成环。看这个例子:
api → orchestrator → store 是一条合法链(接入层依赖领域层,领域层依赖基础设施层)。现在加一条反向边 store → api。从 store 出发,可以走 store → api → orchestrator → store,绕一圈回到自己——一个环,包含 api、orchestrator、store 三个节点。
也就是说,在一条贯通低层的依赖链上,任何一条反向边都会与既有链路闭合。这不是巧合,而是方向律:合法方向从高层指向低层,反向边从低层指回高层,而链路上本来就有一条高层到低层的路径,两条拼在一起自然形成回路。
这个观察的工程含义是:不要以为"只加一条反向边没关系,没有环"。在结构上,加了反向边,环往往就跟着来了。下面的实验会证明这一点。
最小实验:依赖图检查器
实验提供一个依赖图检查器:backward_edges 检反向边,find_cycles 用强连通分量(Tarjan)找环,然后在三个图上跑。
# file: agp_lab/dependency_invariants.py | write
# tier: 3
# verify: python3 -m unittest tests.test_dependency_invariants
"""依赖方向与架构不变量:分层、反向依赖与循环。
依赖方向是一条架构不变量:组件只能依赖同层或更低层。
反向依赖(低层依赖高层)会让故障与变更沿错误方向传播,
循环依赖则让"先构建谁"无法回答。
本模块提供一个依赖图检查器:检测反向边与循环,并用一个
"运行时系统"依赖图演示违规修复前后的差别。
"""
from __future__ import annotations
from collections import defaultdict
from dataclasses import dataclass
from typing import Any
@dataclass(frozen=True)
class Component:
name: str
layer: int # 0=接入层, 1=领域层, 2=基础设施层
COMPONENTS: dict[str, Component] = {
"api": Component("api", 0),
"orchestrator": Component("orchestrator", 1),
"worker": Component("worker", 1),
"store": Component("store", 2),
"model_gateway": Component("model_gateway", 2),
}
def backward_edges(
edges: list[tuple[str, str]], components: dict[str, Component] | None = None
) -> list[tuple[str, str]]:
"""返回依赖高层的反向边。src 依赖 dst,若 src 层号 > dst 层号则违规。"""
comps = components or COMPONENTS
return [
(src, dst)
for (src, dst) in edges
if comps[src].layer > comps[dst].layer
]
def find_cycles(edges: list[tuple[str, str]]) -> set[str]:
"""返回处于至少一个环中的节点(基于强连通分量,SCC 大小>1 或自环)。
Kahn 拓扑排序会把环上游的悬挂链一并留下,不够精确;这里用
Tarjan 求 SCC,只有真正闭合的强连通分量才算环。
"""
adjacency: dict[str, list[str]] = defaultdict(list)
nodes: set[str] = set()
for src, dst in edges:
adjacency[src].append(dst)
nodes.add(src)
nodes.add(dst)
index: dict[str, int] = {}
lowlink: dict[str, int] = {}
on_stack: set[str] = set()
stack: list[str] = []
counter = 0
cyclic: set[str] = set()
def strongconnect(node: str) -> None:
nonlocal counter
index[node] = lowlink[node] = counter
counter += 1
stack.append(node)
on_stack.add(node)
for neighbor in adjacency[node]:
if neighbor not in index:
strongconnect(neighbor)
lowlink[node] = min(lowlink[node], lowlink[neighbor])
elif neighbor in on_stack:
lowlink[node] = min(lowlink[node], index[neighbor])
if lowlink[node] == index[node]:
scc: list[str] = []
while True:
member = stack.pop()
on_stack.discard(member)
scc.append(member)
if member == node:
break
if len(scc) > 1 or node in adjacency[node]:
cyclic.update(scc)
for node in nodes:
if node not in index:
strongconnect(node)
return cyclic
CLEAN: list[tuple[str, str]] = [
("api", "orchestrator"),
("orchestrator", "worker"),
("orchestrator", "store"),
("worker", "model_gateway"),
]
# 反向依赖往往直接成环:store→api 与 api→orchestrator→store 闭合。
VIOLATING: list[tuple[str, str]] = CLEAN + [
("store", "api"), # 反向:基础设施依赖接入层,随即制造环
]
CYCLIC: list[tuple[str, str]] = CLEAN + [
("worker", "orchestrator"), # 与 orchestrator → worker 构成环
]
def demo() -> dict[str, Any]:
"""打印三种依赖图的违规边与环。"""
return {
"clean_backward": backward_edges(CLEAN),
"clean_cycles": sorted(find_cycles(CLEAN)),
"violating_backward": backward_edges(VIOLATING),
"violating_cycles": sorted(find_cycles(VIOLATING)),
"cyclic_cycles": sorted(find_cycles(CYCLIC)),
}
if __name__ == "__main__":
for name, result in demo().items():
print(f"{name}: {result}")
运行:
cd private/labs/agp-lab
python3 -m agp_lab.dependency_invariants
输出:
clean_backward: []
clean_cycles: []
violating_backward: [('store', 'api')]
violating_cycles: ['api', 'orchestrator', 'store']
cyclic_cycles: ['orchestrator', 'worker']
三行输出对应三个图:
- clean:合法依赖图
api→orchestrator→worker/store→model_gateway,反向边为空,环为空。这是目标状态。 - violating:在 clean 基础上只加一条
store → api反向边。backward_edges立刻检出它;同时find_cycles检出['api', 'orchestrator', 'store']——正如上一节预言,一条反向边与既有链路直接闭合成了一个环。 - cyclic:另一处违规
worker → orchestrator,与orchestrator → worker构成['orchestrator', 'worker']这个环。它不涉及接入层,但同样是循环依赖,同样要被拦下。
两个值得注意的实现细节,也是教学点:
find_cycles不用 Kahn 拓扑排序,而用 Tarjan 求强连通分量。Kahn 会把环上游的悬挂链(比如 worker 挂着却因为别的边进出不平衡而没被删掉)一并留下,不够精确;强连通分量只返回真正闭合的节点集合。教学上这一点解释了"环的检测要用对算法"。violating_cycles恰好等于['api', 'orchestrator', 'store'],也就是store→api反向边参与的整个闭合链。环不是"某些坏边",而是"一组节点彼此可达"。
依赖不变量不是一次建好就永久有效。代码每变化一次,依赖图就可能漂移一次:新组件加了反向 import,重构改了分层,工具函数提升到了不该在的层。不变量要随每次变更重新验证,这正是为什么检查器要挂在 CI 而不是挂在手册里。
把检查器作为门禁也有成本:误报会消耗团队耐心,全量重算会拖慢提交。务实的做法是分层检查——变更涉及的子图先查,发布前再做全量;分层检查保速度,全量检查保完整,两件事分开跑。
依赖不变量还有一个部署层面的用法:分层部署的边界就是依赖的边界。 控制平面能独立发布,是因为它不依赖执行平面的内部实现;执行平面能弹性扩容,是因为它不反向依赖控制平面的进程。反过来,如果哪一层被迫联动发布,说明它悄悄建立了不该有的依赖——不变量检查要把"能不能独立部署"也算作约束。
架构判据
依赖不变量是否守住,用五条判据检查:
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 分层一致 | 组件分层号稳定,不随功能漂移 | 同一组件横跨多层语义 |
| 无反向边 | 底层不 import 高层 | 基础设施层里出现接入层引用 |
| 无环 | 依赖图强连通分量全为单点 | 检出任何长度 >1 的环 |
| 自动检查 | 每次变更后自动跑检查器 | 依赖问题靠人工评审把关 |
| 修复闭环 | 检出即修,不留豁免 | 违规长期挂着,检查器名存实亡 |
判据不是一次性达标。第一轮只要能"检出"就已经比人工强;但要警惕第五条:检查器一旦允许豁免,就退化成形式主义。 违规要么修,要么给出有理由的豁免并写进文档,不能静默吞掉。
小结
- 依赖方向是架构不变量:组件只能依赖同层或更低层,且依赖图无环。
- 在贯通低层的依赖链上,一条反向边往往直接与既有链路闭合成一个环。
- 环要用强连通分量(Tarjan)而不是 Kahn 拓扑排序检测,后者会留下环上游的悬挂链。
- 依赖检查必须自动化,不能靠人工 review;检出后要么修要么显式豁免。
阅读导航:上一节:1.2 引擎、服务、Worker、存储的职责 · 下一节:2.1 状态机:状态、转移、守卫 。
常见错误与边界
- 以为"一条反向边没关系"。 在既有链路上加反向边,环往往跟着就来;violating 图就是现成证据。
- 把"能编译"当"无环"。 Python 的 import 天然允许环,能编译不代表依赖健康;必须显式跑检查器。
- 用拓扑排序找环。 Kahn 会把环上游悬挂链一并留下,误报和漏报都有;强连通分量才是精确口径。
- 给检查器开豁免却不记账。 豁免必须显式、有理由、可追溯;静默豁免等于没有检查器。
- 把分层号当真理。 0/1/2 只是讲解用的一种分层;真实系统按自己的语义分层,但"反向依赖要被检出"不变。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。