Biff.graph 可将 Clojure 代码库转化为可查询图结构

背景

在Clojure生态中，随着项目规模增长，如何清晰组织数据模型并高效查询数据库与业务逻辑层，一直是开发者面临的挑战。Pathom 是一个成熟的图数据建模与查询库，能够将数据模型统一为可查询的图，但其复杂的查询规划机制和较高的学习曲线，对小型项目的开发者来说可能过于沉重。Biff 框架的作者为了在默认组件中引入轻量级替代方案，开发了 biff.graph——一个仅为 600 行代码的微型库，旨在保留 Pathom 核心思想的易理解版本。

核心内容

biff.graph 是一个 Clojure 库，允许你将数据模型（包括数据库表与业务逻辑/派生数据）结构化为一个统一、可扩展的图。它的工作方式如下：

• 开发者定义“resolver”（解析器）——每个 resolver 是一个带有输入查询和输出查询的函数。输入查询描述 resolver 期望接收的数据形状，输出查询描述它返回的数据形状。resolver 可以访问数据库（例如通过主键获取实体），也可以从已有数据中派生新属性（例如过滤表情符号）。
• 所有 resolver 注册到 biff.graph 的上下文（ctx）中，之后你可以通过 com.biffweb.graph/query 提交任意形状的查询，引擎会自动组合所需的 resolver 来返回结果。调用者无需知道哪些数据来自数据库、哪些是派生数据。
• biff.graph 使用 EQL / Datomic pull 模式的简化子集来描述数据形状。它支持可选属性（用 [:? ...] 表示）和嵌套连接（用 map 表示外键关系）。
• 与 Pathom 不同，biff.graph 没有查询规划阶段，因此某些查询的执行效率可能不如 Pathom，但它支持批量 resolver 和缓存（通过 :batch true 及中间件实现）。核心查询执行代码仅约 200 行，整个库约 600 行。
• 为了进一步降低使用门槛，biff.graph 推荐自动生成基于数据库 schema 的 resolver（使用 com.biffweb.graph/resolver 而非 defresolver）。自动生成规则：每个表一个 resolver，输入为主键，输出包含所有列及外键连接的子查询，并开启 :batch true。
• 开发者还可以自定义额外的派生 resolver，将辅助函数中的逻辑逐步迁移到 resolver 中，从而保持代码清晰可测。
• 异常处理方面，com.biffweb.graph/query 抛出的异常会在异常数据中包含 :biff.graph/trace 键，标明查询引擎在图遍历中失败的位置，便于快速定位问题并生成最小复现用例。
• 集成支持：可直接在 Ring 请求处理器中调用查询；若使用 biff.fx 事件系统，可将 com.biffweb.graph/fx-handlers 合并到 handlers 中，通过 :biff.graph.fx/query 键进行查询；defresolver 也支持将 resolver 体定义为 biff.fx 机器。

关键要点

• 轻量替代 Pathom：biff.graph 是 Pathom 的精简版，专注于可理解性，移除查询规划阶段，代码规模极小（~600 行）。
• 统一查询：无论数据源自数据库还是派生逻辑，均通过统一图查询接口获取，无需在应用代码中拼接数据库调用与业务函数。
• Resolver 模式：每个 resolver 声明输入输出形状，引擎自动组合。批量 query 时通过 :batch true 支持一次获取多个实体。
• 标准查询语法：使用 EQL / Datomic pull 的简化子集，支持可选属性（[:? attr]）和嵌套连接（{:attr [:sub-attr]}）。
• 自动生成基础 resolver：根据数据库 schema 自动生成每个表的批量 resolver，大幅减少样板代码。
• 调试友好：异常中带有图遍历踪迹（:biff.graph/trace），可快速定位失败 resolver 和查询路径。
• Biff 框架深度集成：作为 Biff 2 的一部分，与 biff.fx 事件系统、Ring 请求处理、模块化配置无缝衔接。
• 测试方便：resolver 函数存储在 :biff.graph/resolve-fn 键下，可直接传入输入进行单元测试。

意义与影响

biff.graph 的出现为 Clojure 特别是 Biff 生态中的开发者提供了一条更平滑的学习路径。它降低了图数据建模模式的门槛——对于尚未接触 Pathom 的小项目开发者，可以先用 biff.graph 理解核心概念（如何将代码分解为 resolver、如何声明数据依赖），待项目变大或遇到更复杂查询需求时，再无缝迁移到完整的 Pathom。同时，biff.graph 本身的简洁性也使其代码易于审查和调试，适合作为 Biff 框架的默认组件。长远来看，这种“先轻后重”的设计思路可能会影响其他 Clojure 库或框架处理数据层的方式，推动函数式项目在保持灵活性的同时降低认知负担。