UI 视觉设计 / 系统课时

解析引用链并检测循环依赖

解析引用链并检测循环依赖

按钮背景可能先引用语义色,再引用基础色。JSON 能解析并不代表 Token 能构建:目标可能不存在,最终类型可能与声明冲突,引用也可能绕一圈回到自身。本文用三层 Token 和可运行的 Python 解析器复现这些情况,并为构建失败定义可定位的错误信息。

学习目标

  • 沿多级别名追踪到最终 $value,同时确定 Token 类型。
  • 用访问栈发现直接或间接循环,区分未找到目标与类型冲突。
  • 为错误报告和发布前校验制定可以执行的规则。

多级引用怎样得到最终值

在 DTCG 2025.10 中,整 Token 别名可以写成 $value 中的 "{semantic.brand}";花括号内是用句点分隔的 Token 路径,不是颜色字面值。对于 button.bg,解析顺序是:

  1. 读取 button.bg 的 {semantic.brand},定位语义 Token。
  2. 读取 semantic.brand 的 {base.blue},继续定位基础 Token。
  3. 取得 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 实现。

python
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}")

预期输出:

text
正常: 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 进入环的情况,要区分进入环的调用路径与环内成员,避免误报无辜上游节点为环节点。

在发布前验证整张依赖图

演示程序为了展示四种结果,主动捕获了异常,所以结束状态不会自动代表构建失败。接入构建流水线时应执行以下验收:

  1. 枚举输入文件中每一个带 $value 的 Token,而不是只解析当前页面使用的 button.bg;逐一检查,才能发现未被消费的孤立环。
  2. 对每条别名检查路径存在且终点是 Token;完成解析后,检查显式或继承类型与最终值结构是否一致。正式校验器需要覆盖 JSON Pointer $ref、复合属性引用和 $extends 的循环。
  3. 一旦发现缺失、无效目标、类型不兼容或回环,保留出错源路径和引用链;构建命令返回非零退出码,不发布 CSS、Android 或 iOS Token 产物。
  4. 用“无环共享基础色”“直接自引”“三节点成环”“引用不存在的路径”“显式类型不兼容”五类测试验证实现;前一种必须成功,后四种必须失败。

实际排查时先根据 source 或 path 找到引用起点,再沿 target 或 chain 检查。修复后重新解析全部 Token,只有错误集合为空且类型校验通过,才能进入代码生成阶段。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

解析引用链并检测循环依赖

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通