UI 视觉设计 / 系统课时
解析引用链并检测循环依赖
解析引用链并检测循环依赖
按钮背景可能先引用语义色,再引用基础色。JSON 能解析并不代表 Token 能构建:目标可能不存在,最终类型可能与声明冲突,引用也可能绕一圈回到自身。本文用三层 Token 和可运行的 Python 解析器复现这些情况,并为构建失败定义可定位的错误信息。
学习目标
- 沿多级别名追踪到最终
$value,同时确定 Token 类型。 - 用访问栈发现直接或间接循环,区分未找到目标与类型冲突。
- 为错误报告和发布前校验制定可以执行的规则。
多级引用怎样得到最终值
在 DTCG 2025.10 中,整 Token 别名可以写成 $value 中的 "{semantic.brand}";花括号内是用句点分隔的 Token 路径,不是颜色字面值。对于 button.bg,解析顺序是:
- 读取
button.bg的{semantic.brand},定位语义 Token。 - 读取
semantic.brand的{base.blue},继续定位基础 Token。 - 取得
base.blue的颜色对象,再逐层把同一个值返回给上游。
base.blue 明确声明 $type: color;semantic.brand 未声明类型时,采用其引用目标解析后的 color。button.bg 显式声明 color,因此必须与最终目标类型一致。非别名 Token 可从最近的父组继承 $type,但不能只看 $value 的形状猜类型。
DTCG 还要求工具支持使用 $ref 的 JSON Pointer,例如 #/base/blue/$value/components/0 定位颜色分量;它与花括号整 Token 别名的目标语义不同,不能简单套用句点拆分。详见 DTCG Format Module 2025.10。
用访问栈识别循环引用
深度优先解析时维护两个集合:正在访问的路径栈 active,以及已经完成的解析缓存 cache。目标不在两者中就继续下钻;在缓存中直接复用结果;如果目标已经在访问栈里,就截取重复位置至栈尾,报告完整回环。这样不会把多个 Token 合法共用同一基础色误判为循环。

下面是可直接运行的 Python 3.10+ 示例。它专注于单文件、整 Token 花括号别名,用四种输入展示成功、缺失目标、类型不匹配和循环;它不是覆盖 $ref、$extends、组级类型继承及复合值校验的完整 DTCG 实现。
import copy
import json
TOKENS = {
"base": {
"blue": {
"$type": "color",
"$value": {"colorSpace": "srgb", "components": [0, 0.4, 0.8]},
}
},
"semantic": {"brand": {"$value": "{base.blue}"}},
"button": {"bg": {"$type": "color", "$value": "{semantic.brand}"}},
}
def resolve(doc, start):
active = []
cache = {}
def visit(path, source="<entry>"):
# active 只存尚未完成的节点,重复出现即证明有环。
if path in active:
pos = active.index(path)
raise ValueError("REF_CYCLE chain=" + " -> ".join(active[pos:] + [path]))
if path in cache:
return cache[path]
node = doc
for part in path.split("."):
if not isinstance(node, dict) or part not in node:
raise ValueError(f"REF_MISSING source={source} target={path}")
node = node[part]
if not isinstance(node, dict) or "$value" not in node:
raise ValueError(f"REF_NOT_TOKEN source={source} target={path}")
active.append(path)
try:
raw = node["$value"]
if isinstance(raw, str) and ("{" in raw or "}" in raw):
if (
not (raw.startswith("{") and raw.endswith("}"))
or raw.count("{") != 1
or raw.count("}") != 1
):
raise ValueError(f"REF_SYNTAX path={path} value={raw}")
target = raw[1:-1]
if not target or any(not part for part in target.split(".")):
raise ValueError(f"REF_SYNTAX path={path} value={raw}")
value, actual = visit(target, path)
expected = node.get("$type")
# 显式类型不能与最终引用目标的类型冲突。
if expected is not None and expected != actual:
raise ValueError(
f"REF_TYPE_MISMATCH path={path} "
f"expected={expected} actual={actual}"
)
result = (value, actual)
else:
if "$type" not in node:
raise ValueError(f"TYPE_UNDETERMINED path={path}")
result = (raw, node["$type"])
cache[path] = result
return result
finally:
# 异常发生时也要清栈,避免污染下一条解析链。
active.pop()
return visit(start)
for mode in ("正常", "缺失", "类型", "循环"):
doc = copy.deepcopy(TOKENS)
if mode == "缺失":
doc["button"]["bg"]["$value"] = "{semantic.missing}"
elif mode == "类型":
doc["button"]["bg"]["$type"] = "dimension"
elif mode == "循环":
doc["semantic"]["brand"]["$value"] = "{button.bg}"
try:
value, kind = resolve(doc, "button.bg")
print(
f"{mode}: type={kind} "
f"value={json.dumps(value, ensure_ascii=False, separators=(',', ':'))}"
)
except ValueError as exc:
print(f"{mode}: {exc}")预期输出:
正常: type=color value={"colorSpace":"srgb","components":[0,0.4,0.8]}
缺失: REF_MISSING source=button.bg target=semantic.missing
类型: REF_TYPE_MISMATCH path=button.bg expected=dimension actual=color
循环: REF_CYCLE chain=button.bg -> semantic.brand -> button.bg错误信息至少要包含什么
不要仅显示“Token 解析失败”。构建日志应定位到出错的源 Token、被引用路径、错误类别和必要的类型或环信息,方便直接回到数据文件修改。
| 错误码(示例约定) | 触发条件 | 报告中的关键字段 | 对应修复 |
|---|---|---|---|
REF_MISSING |
{semantic.missing} 不存在 |
source、target |
修正拼写或补齐目标 |
REF_NOT_TOKEN |
引用指向没有 $value 的组 |
source、target |
改为具体 Token 路径 |
REF_TYPE_MISMATCH |
声明 dimension,目标实际为 color |
path、expected、actual |
修改引用或声明类型 |
REF_CYCLE |
A → B → A 或更长回环 | chain 中完整闭合路径 |
切断至少一条回边 |
REF_SYNTAX |
花括号不配对或路径段为空 | path、value |
修正别名语法 |
这些错误码属于本例的工程约定,不是 DTCG 强制规定的字符串。正式工具还应报告文件名以及可获得的 JSON Pointer 或行列位置;对于从其他 Token 进入环的情况,要区分进入环的调用路径与环内成员,避免误报无辜上游节点为环节点。
在发布前验证整张依赖图
演示程序为了展示四种结果,主动捕获了异常,所以结束状态不会自动代表构建失败。接入构建流水线时应执行以下验收:
- 枚举输入文件中每一个带
$value的 Token,而不是只解析当前页面使用的button.bg;逐一检查,才能发现未被消费的孤立环。 - 对每条别名检查路径存在且终点是 Token;完成解析后,检查显式或继承类型与最终值结构是否一致。正式校验器需要覆盖 JSON Pointer
$ref、复合属性引用和$extends的循环。 - 一旦发现缺失、无效目标、类型不兼容或回环,保留出错源路径和引用链;构建命令返回非零退出码,不发布 CSS、Android 或 iOS Token 产物。
- 用“无环共享基础色”“直接自引”“三节点成环”“引用不存在的路径”“显式类型不兼容”五类测试验证实现;前一种必须成功,后四种必须失败。
实际排查时先根据 source 或 path 找到引用起点,再沿 target 或 chain 检查。修复后重新解析全部 Token,只有错误集合为空且类型校验通过,才能进入代码生成阶段。