“FreeCAD没有齿轮工具”这句社区热评我关注了很久。乍一听是吐槽往深了想其实点中了FreeCAD和传统商业CAD最根本的差异它不愿意把每一个你需要的形状都做成现成命令而是把“让模型自己长出来”的能力交给你。支撑这个能力的底层就是表达式框架——Expression Framework。这篇文章不是什么UI操作教程而是直接从src/App目录下的ExpressionParser.y、ExpressionLexer.l、Expression.cpp、ObjectIdentifier.cpp这些源码文件出发把一条表达式从用户输入到最终驱动属性数值的完整生命周期拆开讲清楚。你会发现表达式框架在FreeCAD里承担的远不只是“公式计算器”它是参数化关联的脐带、单元系统的检票口、循环依赖的哨兵也是二次开发者扩展新函数的第一站。准备啃FreeCAD源码的、想给FreeCAD写插件的人、纯粹好奇参数化CAD内核怎么组织的人这篇应该能帮你省下不少翻代码的时间。1. 为什么我要专门读一下Expression Framework1.1 表达式框架到底解决了什么问题先聊一个很实际的场景你建了一个标准件库长度L改了宽度W必须跟着变成L/2孔径D要变成W*0.618。如果没有表达式你只能手动同步三个参数有了表达式你只需要在宽度属性里写Length/2在孔径里写Width*0.618。但“写公式”这四个字的背后对内核而言是一整套工程问题解析字符串要处理运算符优先级、要区分数字和单位、要知道cube1.Length这种跨对象引用的语法、检查sin()参数能不能带毫米、表达式的值该以什么单位写回目标属性、两个对象互相引用时怎么报警。Expression Framework就是FreeCAD对这套问题的完整回答它横跨词法分析、语法解析、抽象语法树、单元推理、依赖图五块内容。很多人第一次接触FreeCAD表达式时只把它当Excel用输入Length*2完事。但源码摆在那里你会发现这套系统的设计目标远远不止“能算”它要做的是让文档里所有参数在数学上和量纲上都能够被验证、被追踪、被安全地联动。你可以把它理解为FreeCAD参数化建模的心脏而文档里那些Property不过是心脏泵出去的血液。1.2 源码地图别把整个FreeCAD都拖进来FreeCAD的源码体量不算小如果对着整个仓库硬啃大概率一周后就放弃了。读Expression Framework你只需要把目光锁定在src/App目录下的这么几个文件ExpressionLexer.lFlex词法文件负责把字符串切成tokenExpressionParser.yBison语法文件负责把token流组合成语法树ExpressionParser.cpp/h解析器工厂对外提供parse()和validate()入口Expression.cpp/hAST节点定义所有表达式节点类都在这里ExpressionVisitor.h访问者模式接口遍历AST时用ObjectIdentifier.cpp/h对象路径标识也就是对象.路径这个引用语的模型ExpressionBinding.cpp0.20版本之后新增的表达式绑定层负责表达式与属性生命周期之间的协调在0.19及更老的版本里ExpressionBinding还不存在表达式求值和依赖管理的代码分散在Expression.cpp和Property.cpp里。等看到0.21的dev分支你会发现整个表达式系统已经往面向“多个求值入口”的方向重构成了两层一层是纯粹的解析和求值算法另一层是跟DocumentObject打交道的事件绑定。我建议直接以0.20或0.21的源码为准来读省得被老版本里的历史包袱带偏。还有个技巧读这套源码时请暂时忘掉src/Mod下面的那些模块Part、PartDesign、Sketcher都是表达式框架的用户不是实现者。框架本身的边界非常干净App层不依赖任何Mod模块这也就保证了表达式可以在零件、装配、电子设计工作台里通用。2. 一条公式从输入到求值的完整链路2.1 UI入口与文档级挂载FreeCAD里给属性填表达式最常见的方式是在属性编辑器里点那个蓝色圆球图标输入一段文本。文本先被收集到PropertyExpression或者ExpressionBinding然后调用ExpressionParser::parse()。这个入口函数接收一个std::string返回一个Expression*指针如果解析失败直接抛异常界面上会显示红字错误。这里有个容易忽略的设计表达式对象最终是挂在Property层而不是挂在DocumentObject层。也就是说表达式不是简单“算出一个值塞回去”而是变成属性自身的元数据。这样做的好处很明显——如果表达式失效了属性仍然保留最后算出来的缓存值文档不会被破坏等依赖对象恢复后表达式又能自动重新生效。这个“缓存值失效标记”的思路在PropertyExpression::getValue()里体现得很直接每当依赖的属性变了表达式会被标成dirty但不会立刻强行重算只有在你真正读取这个属性时才触发求值。这就引出一个调试要点如果你改了一个被多处引用的参数FreeCAD并不会在同一帧把下游全部刷一遍它是懒求值的。想验证求值有没有发生可以直接看ExpressionBinding::execute()的调用时机或者给表达式加一个副作用函数比如print()看看它什么时候被触发。2.2 解析器Flex负责认字Bison负责断句词法这一层ExpressionLexer.l做的事情不多但很关键。数字、标识符、运算符、括号、逗号都被定义成正则表达式最有趣的token是OBJECT它匹配...这种写法。之所以要用双尖括号把对象名包起来是为了让表达式解析器能明确区分“当前文档里哪个对象”和“属性路径”因为对象名本身可能包含空格、点号甚至中文。词法文件里有一类专门处理单位字面量的模式像mm、deg、kg这些单位词会被识别出来后面跟数字组合成带单位的量。这也是表达式框架和普通公式计算器最本质的分野10mm 5mm在词法阶段就已经带着“毫米”这个身份了而不是先解析成10 5再回头猜单位。Bison语法文件ExpressionParser.y定义的优先级和结合性完全遵循数学直觉^高于* /* /高于 -一元负号单独处理。你如果读过别的计算器实现看这个文件会很轻松。往底层看几个关键产生式expression: NUMBER | OBJECT : : OBJECT | OBJECT . IDENTIFIER | expression expression | expression - expression | expression * expression | expression / expression | expression ^ expression | FUNCTION ( args ) ...语法分析做完生成的就是一棵由Expression子类组成的AST。值得注意的是Bison动作代码里几乎不碰任何业务逻辑它只是负责按规则new出节点并组装。真正的检查全部推迟到validate()阶段这保持了语法文件的纯粹性也让后续新增语法规则的回归成本低很多。2.3 从AST到Quantity拿到AST之后求值函数evaluate()接收一个std::mapObjectIdentifier, Quantity作为变量表。这个map就是求值时的“环境”它把文档对象属性路径映射到具体的带单位数值。为什么不用全局变量硬编码属性因为表达式要在不同上下文中复用比如同一个公式可能被用于计算Length也可能被用于计算Placement.Base.x变量表自然要作为参数传进来。每个节点求值都返回Quantity。Quantity是FreeCAD的一个基础类型内部就是一个double值加一个Unit对象。这个返回类型是整个表达式框架最强势的约束不管你是数字字面量、单元表达式、函数调用还是对象引用最终都必须给出一个带单位的量。于是“单位检查”就被天然地嵌进了AST的每个节点里而不是等所有计算完了再统一处理。3. AST节点体系与ObjectIdentifier3.1 七类核心节点打开Expression.h你会看到七种直接继承Expression的节点类它们是整套AST的积木NumberExpression数字字面量内部存一个Quantity比如5、3.14mmUnitExpression纯单位表达式比如mm单独作为操作数时使用OperatorExpression二元运算符节点承载 - * / ^UnaryExpression一元运算目前主要是负号FunctionExpression函数调用内部存函数指针和参数节点列表ConditionalExpression三元条件表达式cond ? true_expr : false_exprObjectIdentifierExpression对象引用指向文档里其他属性每个节点必须实现evaluate()和getReferences()这两个虚函数是核心协议。前者负责求值后者负责收集当前节点引用了哪些外部对象。你可以把getReferences()理解成AST的“依赖声明”它让FreeCAD不用分析字符串也能知道这个表达式跟谁有牵连。我读这套节点设计时印象最深的是contains()方法。它递归判断一个表达式是否包含另一个表达式作为子树用来检测类似“自己引用自己”这种问题。你在源码里会看到很多看似简单却到处用的基础方法它们是整个框架健壮性的地基。3.2 ObjectIdentifier模型里的“路径语法”ObjectIdentifier可能是这套框架里最容易被低估的类。它不只是一个字符串而是一个结构化的对象路径。一个ObjectIdentifier由两部分组成指向哪个DocumentObject的指针加上一串Component序列。一个Component有name和index两个字段index用来支持数组和序列化取值。举个例子Sketch.Constraints[3].Value会被拆成对象指针指向Sketch组件依次为Constraints、[3]、Value。这样设计的意义在于表达式系统不需要自己去字符串解析属性路径它可以直接用结构化的组件去查询文档对象图。更妙的是Component可以表示“范围的开始”和“范围的结束”虽然大多数用户感知不到但内部处理数组区间运算时非常省力。这个类还提供了depth()方法用来判断一个路径在多维张量里的深度。配合高版本的Quantity矩阵扩展表达式框架其实已经能处理带方向的量了只是普通机械零件设计用到矩阵运算的场景不多。读到这里你就会明白FreeCAD的表达式并不是为了“算数”而生的它是为了成为文档对象图的一等公民。3.3 访问者模式在表达式框架里的作用ExpressionVisitor提供了一套遍历接口。你要做类型检查、要收集依赖、要序列化返回字符串都可以通过实现一个visitor来解决而不是在每个节点类里塞乱七八糟的逻辑。源码里的ExpressionPrinter就是典型例子它把一棵AST重新打印成字符串用来在错误信息里回显用户公式。如果你想开发第三方功能visitor也是你扩展的最佳接入点。比如做一个“检索所有表达式中使用了atan2函数”的工具只要实现一个visitor去遍历每个FunctionExpression节点比对函数名就行。不需要改动任何核心代码。面向对象设计里这套玩法很经典但真正把visitor用在语法树上的开源项目并不多FreeCAD算是用得挺纯粹的一个。4. 单元系统表达式框架最出彩的设计4.1 Quantity把数字和单位绑在一起FreeCAD很早就把Quantity引入src/Base/Unit.h了。Quantity本质上就是带单位的数值它支持加减乘除和幂运算并且自动做单位换算。比如1m 50cm得到的是1.5m如果你设置显示单位是mm界面上会显示1500mm。表达式框架算是Quantity的最大客户。每一个NumberExpression在构造时就会把自己的单位存进Quantity里OperatorExpression在evaluate()里直接调用Quantity的运算符重载让底层单位逻辑去处理换算。这种高度复用的设计非常聪明表达式框架本身不关心单位换算算法它只负责“用什么单位去算”和“算完的单位是不是合法”脏活累活全抛给Base层。4.2 编译期单元检查是怎么做到的我说的“编译期”不是C编译器而是表达式从字符串变成AST之后的validate()阶段。这一步发生在求值之前框架会先做一次“无损试跑”也就是不真正执行业务逻辑只检查量纲是否兼容。比如1mm 1s这个表达式两个操作数一个长度单位一个时间单位OperatorExpression::validate()会让基类Expression::isValid()去做量纲检验。如果单位不兼容直接抛异常界面会告诉你“units do not match”。这就是为什么你在FreeCAD里写错单位时报错会出现在你点“确定”那一刻而不是等模型重算到一半才炸出来。这个设计跟我见过的其他CAD软件很不一样。不少软件是等所有依赖全部算完再做量纲检查那会污染文档的数据流排错也困难。FreeCAD把检查前置从根上保证了进入系统表达式树的任何公式都是单位自洽的。这一点非常值得学习——建立领域特定语言的“静态检查”阶段比在运行时反复报错要体面得多。4.3 从函数签名看单元推导规则FunctionExpression内部维护了一个函数指针表所有内置函数都有明确的参数个数和单位签名。比如sin()要求参数是无量纲数返回无量纲数pow(x, y)要求第一个参数可以带任意单位第二个参数必须是纯数最终单位是第一个参数单位的“y次方”。这就是为什么你可以写pow(2mm, 2)得到面积单位却不能写pow(2mm, 3mm)。读FunctionExpression::validate()会发现每个函数通过一个检查函数指针来声明自己的参数校验逻辑。新增一个函数时你不仅要提供求值函数最好也提供一个校验函数否则框架会默认使用“要求所有参数无量纲”的保守规则。这不只是源码设计也是一条插件开发者的实用建议带好单位声明你的函数才真正适合CAD环境而不是像Excel那样什么都当纯数字算。5. 依赖追踪与循环依赖检测5.1 getReferences与依赖图的建立参数化建模最怕的就是牵一发动全身时的不可控连锁反应。FreeCAD解决这个问题的第一步是让每个表达式都能报告自己引用哪些节点。getReferences()会遍历AST把所有ObjectIdentifierExpression节点引用的路径收集起来放到一个std::mapObjectIdentifier, int里整数表示“这个引用出现了几次”。有了这份引用清单表达式绑定层就可以构建依赖图。ExpressionBinding内部维护一个从“属性A”到“依赖它的所有属性B列表”的关系表。这个关系表不是静态的每次表达式被编辑、对象被重命名、属性被删除时都会增量更新。这解释了为什么你在FreeCAD里把Length改名为Height后引用它的表达式居然还能自己跟上——因为依赖关系不是文本匹配而是挂在对象和属性指针上的结构化引用。依赖图也是所有“自动重算”的调度依据。一个属性变化时框架沿着依赖边找到下游所有需要更新的属性把它们标记为dirty。你可以在源码里搜touch()函数看看一个属性被标记后是如何顺着依赖边传播的。5.2 循环依赖检测的DFS算法循环依赖是参数化系统的经典噩梦。A引用了BB又引用了A如果没有任何保护最终会无限重算或者栈溢出。FreeCAD的循环检测实现放在表达式绑定层的isLoop相关逻辑里用的是一种非常标准的深度优先遍历加状态标记算法。简单说遍历依赖图时每个节点有三个状态未访问白色、访问中灰色、访问完成黑色。从一个节点出发沿依赖边走如果遇到一个灰色节点说明存在环。算法可以把“环上的关键路径”也提取出来错误信息里会直接告诉你是ObjectA和ObjectB之间循环。这个错误提示我以前觉得挺神秘读完源码才知道就是标准图的DFS着色法只是FreeCAD把节点的状态和依赖边的构造方式封装得好。有意思的是FreeCAD判断循环依赖并不是“完全不让你建”而是禁止会形成环的那个操作并给出明确提示。编辑器更新的场景里如果临时形成的循环比如先给A加了引用B的表达式还没改B存在系统会在验证阶段拦截不会去尝试“算出一个稳定解”。CAD不是方程组求解器它追求的是依赖关系始终可解释这一点设计取舍很清晰。5.3 touch机制与重算时机你还得理解“重算”的粒度。FreeCAD里一个表达式依赖的属性变化并不会立刻重新执行所有下游求值它只是把下游属性标记为“需要重算”。真正触发execute()的是读取这个属性或者用户手动按刷新按钮。这个懒求值配合文档重启之后的恢复机制使得FreeCAD即使有成千上万条表达式也不至于在做一个小改动时卡死。源码里你能看到Property::hasSetValue()和DocumentObject::touch()这些方法的互动。touch()本质上是把自身版本的Revision加一然后通知依赖自己的下游属性“你缓存的值可能过期了”。这其实是一种基于版本的脏标记机制。理解了这个你就能快速定位“为什么我改了参数模型没变”这种高频问题——八成是你改的是一个没有被引用的属性或者下游已经被手动标成“不自动重算”状态了。6. 给FreeCAD写一个自定义表达式函数6.1 注册入口与API演进老版本里如果要自定义表达式函数通常得去改ExpressionParser.y里的函数表那对普通二次开发用户来说门槛很高。但从0.20、0.21开始FreeCAD提供了正式的运行时注册接口App::ExpressionParser::addFunction()你可以把C函数直接挂进表达式解析器的函数名表里。注册的本质是往解析器内部的FunctionExpression函数映射表插入一条记录。映射表的键是函数名统一转小写值是一个函数指针签名大致是typedef Quantity (*FuncPtr)(const std::vectorQuantity args);解析器在解析myFunc(1mm, 2)时会在内置函数表里查找myFunc找到后生成一个FunctionExpression节点节点内部保存这个函数指针。求值时直接调用指针省去了switch-case式分发。这套设计让函数扩展从“改源码重编译”退化成“写个插件注册一下”对二次开发非常友好。6.2 一个带单位检查的自定义函数实例假设你想加一个“闭区间镜像”函数把输入值映射到某个区间内比如mirror(x)返回abs(x)的符号翻转版本或者做一个更实用的bounded(x, min, max)。以一个带单位检查的函数为例#include App/ExpressionParser.h #include Base/Quantity.h static App::Quantity bounded_func(const std::vectorApp::Quantity args) { if (args.size() ! 3) throw App::Expression::Exception(bounded(): expects 3 arguments); if (args[1].getUnit() ! args[2].getUnit()) throw App::Expression::Exception(bounded(): min and max must share unit); // 这里可以自己决定单位策略我建议以第一个参数的单位为准 double x args[0].getValue(); double lo args[1].getValue(); double hi args[2].getValue(); if (lo hi) std::swap(lo, hi); double clamped std::max(lo, std::min(x, hi)); return App::Quantity(clamped, args[0].getUnit()); } // 在插件初始化时注册 App::ExpressionParser::addFunction(bounded, bounded_func);注册之后你在FreeCAD表达式里就能直接写bounded(Length, 10mm, 100mm)。这里的关键是单位检查我故意让min和max必须同单位但允许x的单位不同因为函数内部只取数值裁剪最后单位按x返回。如果你想严格限制三者完全同单位把条件写成三个getUnit()全等即可。这个例子虽然小但完整展示了“解析期函数签名校验求值期单位推导”两条规则是怎么落到一行代码里的。还要提醒一点如果你是给内置模块比如Part加函数需要确保模块在初始化时调用注册代码而不是等到用户真的输入表达式时才注册。否则解析器会报“Unknown function”。注册时机的问题我在做自定义宏时踩过好几次坑后来习惯在模块构造器里集中注册所有函数省心很多。7. 源码阅读的几条实用心得7.1 版本差异0.19和0.21看起来完全不一样如果你先去读0.18、0.19的源码再翻开0.21的最大的感觉就是“这俩真的是同一个项目吗”。0.19及以前表达式求值和属性更新基本都在Property.cpp里内联处理逻辑紧凑但边界模糊0.20之后拆出ExpressionBinding把“绑定表达式到属性”和“执行表达式求值”分离代码结构清晰了一大截。所以如果你刚上手请直接看新版本。看到老代码里那些getExpression()、setExpression()的散落调用也不要慌它们只是新架构的前身。读源码时建议把git blame和提交信息结合起来看。比如搜ExpressionBinding能看到这个文件是什么时候引入的、解决了哪个issue这比从头到尾读代码更能帮助你理解设计动机。源码分析不只是读最终状态看它怎么演进过来同样重要。7.2 调试表达式解析的最快方法想验证一个表达式解析成什么AST最快的办法是在源码里加日志比如在ExpressionParser::parse()返回之前把toString()打出来。不过更推荐的方式是用gdb在Expression::evaluate()里下一处断点观察调用栈。FreeCAD的Debug构建类型支持得很好CMake配置时选-DCMAKE_BUILD_TYPEDebug就行。在FreeCAD自带的Python控制台里你也可以直接实验很多表达式函数。虽然ExpressionParser的Python绑定在不同版本里开放程度不一样但至少有App.ExpressionParser.parse这类接口可以快速试错。真正常备的调试套路是构造一个最小的单文档场景删除其他所有无关对象只保留两个互相引用的立方体然后手动修改表达式观察错误信息。源码分析的问题多半是“这个代码怎么走到的”而最小复现能帮你把范围压缩到十几个文件以内。7.3 读这个框架的正确顺序我的建议是别一上来就啃Expression.cpp的几百行核心实现。先从词法文件开始看看token怎么定义然后过一遍语法文件搞清楚产生式如何组装接着打开ExpressionVisitor把visitor接口扫一眼最后再回到实现类逐类看evaluate()和getReferences()。这个顺序跟着“一条字符串变成数值”的自然流动方向走每前进一步都在已有心智上叠加新知比从中间某个类倒着读舒服得多。读的过程中多留意异常消息。FreeCAD表达式框架的异常信息写得相当友好比如“Unknown variable”或“Incompatible units”这些字符串本身就是理解系统边界的地图。我在读Expression.cpp时经常先用IDE全文搜索某个错误提示字符串然后定位到抛异常的位置顺藤摸瓜看完整条检查链效率非常高。实际跟完整个框架之后我对FreeCAD的“开源但有序”有了更具体的感受。它的表达式框架不是那种炫技式的代码而是围绕“参数化建模”这一件事做了大量朴实而稳健的设计AST节点职责单一、单元系统贯穿始终、依赖图管理规范、循环检测算法经典。如果你打算在FreeCAD之上做二次开发尤其是写参数化工作台或者模板库我强烈建议先把这里读透。很多你以为是“功能缺失”的问题其实在这个框架里都能找到自己的答案。
“FreeCAD没有齿轮工具”这句社区热评我关注了很久。乍一听是吐槽往深了想其实点中了FreeCAD和传统商业CAD最根本的差异它不愿意把每一个你需要的形状都做成现成命令而是把“让模型自己长出来”的能力交给你。支撑这个能力的底层就是表达式框架——Expression Framework。这篇文章不是什么UI操作教程而是直接从src/App目录下的ExpressionParser.y、ExpressionLexer.l、Expression.cpp、ObjectIdentifier.cpp这些源码文件出发把一条表达式从用户输入到最终驱动属性数值的完整生命周期拆开讲清楚。你会发现表达式框架在FreeCAD里承担的远不只是“公式计算器”它是参数化关联的脐带、单元系统的检票口、循环依赖的哨兵也是二次开发者扩展新函数的第一站。准备啃FreeCAD源码的、想给FreeCAD写插件的人、纯粹好奇参数化CAD内核怎么组织的人这篇应该能帮你省下不少翻代码的时间。1. 为什么我要专门读一下Expression Framework1.1 表达式框架到底解决了什么问题先聊一个很实际的场景你建了一个标准件库长度L改了宽度W必须跟着变成L/2孔径D要变成W*0.618。如果没有表达式你只能手动同步三个参数有了表达式你只需要在宽度属性里写Length/2在孔径里写Width*0.618。但“写公式”这四个字的背后对内核而言是一整套工程问题解析字符串要处理运算符优先级、要区分数字和单位、要知道cube1.Length这种跨对象引用的语法、检查sin()参数能不能带毫米、表达式的值该以什么单位写回目标属性、两个对象互相引用时怎么报警。Expression Framework就是FreeCAD对这套问题的完整回答它横跨词法分析、语法解析、抽象语法树、单元推理、依赖图五块内容。很多人第一次接触FreeCAD表达式时只把它当Excel用输入Length*2完事。但源码摆在那里你会发现这套系统的设计目标远远不止“能算”它要做的是让文档里所有参数在数学上和量纲上都能够被验证、被追踪、被安全地联动。你可以把它理解为FreeCAD参数化建模的心脏而文档里那些Property不过是心脏泵出去的血液。1.2 源码地图别把整个FreeCAD都拖进来FreeCAD的源码体量不算小如果对着整个仓库硬啃大概率一周后就放弃了。读Expression Framework你只需要把目光锁定在src/App目录下的这么几个文件ExpressionLexer.lFlex词法文件负责把字符串切成tokenExpressionParser.yBison语法文件负责把token流组合成语法树ExpressionParser.cpp/h解析器工厂对外提供parse()和validate()入口Expression.cpp/hAST节点定义所有表达式节点类都在这里ExpressionVisitor.h访问者模式接口遍历AST时用ObjectIdentifier.cpp/h对象路径标识也就是对象.路径这个引用语的模型ExpressionBinding.cpp0.20版本之后新增的表达式绑定层负责表达式与属性生命周期之间的协调在0.19及更老的版本里ExpressionBinding还不存在表达式求值和依赖管理的代码分散在Expression.cpp和Property.cpp里。等看到0.21的dev分支你会发现整个表达式系统已经往面向“多个求值入口”的方向重构成了两层一层是纯粹的解析和求值算法另一层是跟DocumentObject打交道的事件绑定。我建议直接以0.20或0.21的源码为准来读省得被老版本里的历史包袱带偏。还有个技巧读这套源码时请暂时忘掉src/Mod下面的那些模块Part、PartDesign、Sketcher都是表达式框架的用户不是实现者。框架本身的边界非常干净App层不依赖任何Mod模块这也就保证了表达式可以在零件、装配、电子设计工作台里通用。2. 一条公式从输入到求值的完整链路2.1 UI入口与文档级挂载FreeCAD里给属性填表达式最常见的方式是在属性编辑器里点那个蓝色圆球图标输入一段文本。文本先被收集到PropertyExpression或者ExpressionBinding然后调用ExpressionParser::parse()。这个入口函数接收一个std::string返回一个Expression*指针如果解析失败直接抛异常界面上会显示红字错误。这里有个容易忽略的设计表达式对象最终是挂在Property层而不是挂在DocumentObject层。也就是说表达式不是简单“算出一个值塞回去”而是变成属性自身的元数据。这样做的好处很明显——如果表达式失效了属性仍然保留最后算出来的缓存值文档不会被破坏等依赖对象恢复后表达式又能自动重新生效。这个“缓存值失效标记”的思路在PropertyExpression::getValue()里体现得很直接每当依赖的属性变了表达式会被标成dirty但不会立刻强行重算只有在你真正读取这个属性时才触发求值。这就引出一个调试要点如果你改了一个被多处引用的参数FreeCAD并不会在同一帧把下游全部刷一遍它是懒求值的。想验证求值有没有发生可以直接看ExpressionBinding::execute()的调用时机或者给表达式加一个副作用函数比如print()看看它什么时候被触发。2.2 解析器Flex负责认字Bison负责断句词法这一层ExpressionLexer.l做的事情不多但很关键。数字、标识符、运算符、括号、逗号都被定义成正则表达式最有趣的token是OBJECT它匹配...这种写法。之所以要用双尖括号把对象名包起来是为了让表达式解析器能明确区分“当前文档里哪个对象”和“属性路径”因为对象名本身可能包含空格、点号甚至中文。词法文件里有一类专门处理单位字面量的模式像mm、deg、kg这些单位词会被识别出来后面跟数字组合成带单位的量。这也是表达式框架和普通公式计算器最本质的分野10mm 5mm在词法阶段就已经带着“毫米”这个身份了而不是先解析成10 5再回头猜单位。Bison语法文件ExpressionParser.y定义的优先级和结合性完全遵循数学直觉^高于* /* /高于 -一元负号单独处理。你如果读过别的计算器实现看这个文件会很轻松。往底层看几个关键产生式expression: NUMBER | OBJECT : : OBJECT | OBJECT . IDENTIFIER | expression expression | expression - expression | expression * expression | expression / expression | expression ^ expression | FUNCTION ( args ) ...语法分析做完生成的就是一棵由Expression子类组成的AST。值得注意的是Bison动作代码里几乎不碰任何业务逻辑它只是负责按规则new出节点并组装。真正的检查全部推迟到validate()阶段这保持了语法文件的纯粹性也让后续新增语法规则的回归成本低很多。2.3 从AST到Quantity拿到AST之后求值函数evaluate()接收一个std::mapObjectIdentifier, Quantity作为变量表。这个map就是求值时的“环境”它把文档对象属性路径映射到具体的带单位数值。为什么不用全局变量硬编码属性因为表达式要在不同上下文中复用比如同一个公式可能被用于计算Length也可能被用于计算Placement.Base.x变量表自然要作为参数传进来。每个节点求值都返回Quantity。Quantity是FreeCAD的一个基础类型内部就是一个double值加一个Unit对象。这个返回类型是整个表达式框架最强势的约束不管你是数字字面量、单元表达式、函数调用还是对象引用最终都必须给出一个带单位的量。于是“单位检查”就被天然地嵌进了AST的每个节点里而不是等所有计算完了再统一处理。3. AST节点体系与ObjectIdentifier3.1 七类核心节点打开Expression.h你会看到七种直接继承Expression的节点类它们是整套AST的积木NumberExpression数字字面量内部存一个Quantity比如5、3.14mmUnitExpression纯单位表达式比如mm单独作为操作数时使用OperatorExpression二元运算符节点承载 - * / ^UnaryExpression一元运算目前主要是负号FunctionExpression函数调用内部存函数指针和参数节点列表ConditionalExpression三元条件表达式cond ? true_expr : false_exprObjectIdentifierExpression对象引用指向文档里其他属性每个节点必须实现evaluate()和getReferences()这两个虚函数是核心协议。前者负责求值后者负责收集当前节点引用了哪些外部对象。你可以把getReferences()理解成AST的“依赖声明”它让FreeCAD不用分析字符串也能知道这个表达式跟谁有牵连。我读这套节点设计时印象最深的是contains()方法。它递归判断一个表达式是否包含另一个表达式作为子树用来检测类似“自己引用自己”这种问题。你在源码里会看到很多看似简单却到处用的基础方法它们是整个框架健壮性的地基。3.2 ObjectIdentifier模型里的“路径语法”ObjectIdentifier可能是这套框架里最容易被低估的类。它不只是一个字符串而是一个结构化的对象路径。一个ObjectIdentifier由两部分组成指向哪个DocumentObject的指针加上一串Component序列。一个Component有name和index两个字段index用来支持数组和序列化取值。举个例子Sketch.Constraints[3].Value会被拆成对象指针指向Sketch组件依次为Constraints、[3]、Value。这样设计的意义在于表达式系统不需要自己去字符串解析属性路径它可以直接用结构化的组件去查询文档对象图。更妙的是Component可以表示“范围的开始”和“范围的结束”虽然大多数用户感知不到但内部处理数组区间运算时非常省力。这个类还提供了depth()方法用来判断一个路径在多维张量里的深度。配合高版本的Quantity矩阵扩展表达式框架其实已经能处理带方向的量了只是普通机械零件设计用到矩阵运算的场景不多。读到这里你就会明白FreeCAD的表达式并不是为了“算数”而生的它是为了成为文档对象图的一等公民。3.3 访问者模式在表达式框架里的作用ExpressionVisitor提供了一套遍历接口。你要做类型检查、要收集依赖、要序列化返回字符串都可以通过实现一个visitor来解决而不是在每个节点类里塞乱七八糟的逻辑。源码里的ExpressionPrinter就是典型例子它把一棵AST重新打印成字符串用来在错误信息里回显用户公式。如果你想开发第三方功能visitor也是你扩展的最佳接入点。比如做一个“检索所有表达式中使用了atan2函数”的工具只要实现一个visitor去遍历每个FunctionExpression节点比对函数名就行。不需要改动任何核心代码。面向对象设计里这套玩法很经典但真正把visitor用在语法树上的开源项目并不多FreeCAD算是用得挺纯粹的一个。4. 单元系统表达式框架最出彩的设计4.1 Quantity把数字和单位绑在一起FreeCAD很早就把Quantity引入src/Base/Unit.h了。Quantity本质上就是带单位的数值它支持加减乘除和幂运算并且自动做单位换算。比如1m 50cm得到的是1.5m如果你设置显示单位是mm界面上会显示1500mm。表达式框架算是Quantity的最大客户。每一个NumberExpression在构造时就会把自己的单位存进Quantity里OperatorExpression在evaluate()里直接调用Quantity的运算符重载让底层单位逻辑去处理换算。这种高度复用的设计非常聪明表达式框架本身不关心单位换算算法它只负责“用什么单位去算”和“算完的单位是不是合法”脏活累活全抛给Base层。4.2 编译期单元检查是怎么做到的我说的“编译期”不是C编译器而是表达式从字符串变成AST之后的validate()阶段。这一步发生在求值之前框架会先做一次“无损试跑”也就是不真正执行业务逻辑只检查量纲是否兼容。比如1mm 1s这个表达式两个操作数一个长度单位一个时间单位OperatorExpression::validate()会让基类Expression::isValid()去做量纲检验。如果单位不兼容直接抛异常界面会告诉你“units do not match”。这就是为什么你在FreeCAD里写错单位时报错会出现在你点“确定”那一刻而不是等模型重算到一半才炸出来。这个设计跟我见过的其他CAD软件很不一样。不少软件是等所有依赖全部算完再做量纲检查那会污染文档的数据流排错也困难。FreeCAD把检查前置从根上保证了进入系统表达式树的任何公式都是单位自洽的。这一点非常值得学习——建立领域特定语言的“静态检查”阶段比在运行时反复报错要体面得多。4.3 从函数签名看单元推导规则FunctionExpression内部维护了一个函数指针表所有内置函数都有明确的参数个数和单位签名。比如sin()要求参数是无量纲数返回无量纲数pow(x, y)要求第一个参数可以带任意单位第二个参数必须是纯数最终单位是第一个参数单位的“y次方”。这就是为什么你可以写pow(2mm, 2)得到面积单位却不能写pow(2mm, 3mm)。读FunctionExpression::validate()会发现每个函数通过一个检查函数指针来声明自己的参数校验逻辑。新增一个函数时你不仅要提供求值函数最好也提供一个校验函数否则框架会默认使用“要求所有参数无量纲”的保守规则。这不只是源码设计也是一条插件开发者的实用建议带好单位声明你的函数才真正适合CAD环境而不是像Excel那样什么都当纯数字算。5. 依赖追踪与循环依赖检测5.1 getReferences与依赖图的建立参数化建模最怕的就是牵一发动全身时的不可控连锁反应。FreeCAD解决这个问题的第一步是让每个表达式都能报告自己引用哪些节点。getReferences()会遍历AST把所有ObjectIdentifierExpression节点引用的路径收集起来放到一个std::mapObjectIdentifier, int里整数表示“这个引用出现了几次”。有了这份引用清单表达式绑定层就可以构建依赖图。ExpressionBinding内部维护一个从“属性A”到“依赖它的所有属性B列表”的关系表。这个关系表不是静态的每次表达式被编辑、对象被重命名、属性被删除时都会增量更新。这解释了为什么你在FreeCAD里把Length改名为Height后引用它的表达式居然还能自己跟上——因为依赖关系不是文本匹配而是挂在对象和属性指针上的结构化引用。依赖图也是所有“自动重算”的调度依据。一个属性变化时框架沿着依赖边找到下游所有需要更新的属性把它们标记为dirty。你可以在源码里搜touch()函数看看一个属性被标记后是如何顺着依赖边传播的。5.2 循环依赖检测的DFS算法循环依赖是参数化系统的经典噩梦。A引用了BB又引用了A如果没有任何保护最终会无限重算或者栈溢出。FreeCAD的循环检测实现放在表达式绑定层的isLoop相关逻辑里用的是一种非常标准的深度优先遍历加状态标记算法。简单说遍历依赖图时每个节点有三个状态未访问白色、访问中灰色、访问完成黑色。从一个节点出发沿依赖边走如果遇到一个灰色节点说明存在环。算法可以把“环上的关键路径”也提取出来错误信息里会直接告诉你是ObjectA和ObjectB之间循环。这个错误提示我以前觉得挺神秘读完源码才知道就是标准图的DFS着色法只是FreeCAD把节点的状态和依赖边的构造方式封装得好。有意思的是FreeCAD判断循环依赖并不是“完全不让你建”而是禁止会形成环的那个操作并给出明确提示。编辑器更新的场景里如果临时形成的循环比如先给A加了引用B的表达式还没改B存在系统会在验证阶段拦截不会去尝试“算出一个稳定解”。CAD不是方程组求解器它追求的是依赖关系始终可解释这一点设计取舍很清晰。5.3 touch机制与重算时机你还得理解“重算”的粒度。FreeCAD里一个表达式依赖的属性变化并不会立刻重新执行所有下游求值它只是把下游属性标记为“需要重算”。真正触发execute()的是读取这个属性或者用户手动按刷新按钮。这个懒求值配合文档重启之后的恢复机制使得FreeCAD即使有成千上万条表达式也不至于在做一个小改动时卡死。源码里你能看到Property::hasSetValue()和DocumentObject::touch()这些方法的互动。touch()本质上是把自身版本的Revision加一然后通知依赖自己的下游属性“你缓存的值可能过期了”。这其实是一种基于版本的脏标记机制。理解了这个你就能快速定位“为什么我改了参数模型没变”这种高频问题——八成是你改的是一个没有被引用的属性或者下游已经被手动标成“不自动重算”状态了。6. 给FreeCAD写一个自定义表达式函数6.1 注册入口与API演进老版本里如果要自定义表达式函数通常得去改ExpressionParser.y里的函数表那对普通二次开发用户来说门槛很高。但从0.20、0.21开始FreeCAD提供了正式的运行时注册接口App::ExpressionParser::addFunction()你可以把C函数直接挂进表达式解析器的函数名表里。注册的本质是往解析器内部的FunctionExpression函数映射表插入一条记录。映射表的键是函数名统一转小写值是一个函数指针签名大致是typedef Quantity (*FuncPtr)(const std::vectorQuantity args);解析器在解析myFunc(1mm, 2)时会在内置函数表里查找myFunc找到后生成一个FunctionExpression节点节点内部保存这个函数指针。求值时直接调用指针省去了switch-case式分发。这套设计让函数扩展从“改源码重编译”退化成“写个插件注册一下”对二次开发非常友好。6.2 一个带单位检查的自定义函数实例假设你想加一个“闭区间镜像”函数把输入值映射到某个区间内比如mirror(x)返回abs(x)的符号翻转版本或者做一个更实用的bounded(x, min, max)。以一个带单位检查的函数为例#include App/ExpressionParser.h #include Base/Quantity.h static App::Quantity bounded_func(const std::vectorApp::Quantity args) { if (args.size() ! 3) throw App::Expression::Exception(bounded(): expects 3 arguments); if (args[1].getUnit() ! args[2].getUnit()) throw App::Expression::Exception(bounded(): min and max must share unit); // 这里可以自己决定单位策略我建议以第一个参数的单位为准 double x args[0].getValue(); double lo args[1].getValue(); double hi args[2].getValue(); if (lo hi) std::swap(lo, hi); double clamped std::max(lo, std::min(x, hi)); return App::Quantity(clamped, args[0].getUnit()); } // 在插件初始化时注册 App::ExpressionParser::addFunction(bounded, bounded_func);注册之后你在FreeCAD表达式里就能直接写bounded(Length, 10mm, 100mm)。这里的关键是单位检查我故意让min和max必须同单位但允许x的单位不同因为函数内部只取数值裁剪最后单位按x返回。如果你想严格限制三者完全同单位把条件写成三个getUnit()全等即可。这个例子虽然小但完整展示了“解析期函数签名校验求值期单位推导”两条规则是怎么落到一行代码里的。还要提醒一点如果你是给内置模块比如Part加函数需要确保模块在初始化时调用注册代码而不是等到用户真的输入表达式时才注册。否则解析器会报“Unknown function”。注册时机的问题我在做自定义宏时踩过好几次坑后来习惯在模块构造器里集中注册所有函数省心很多。7. 源码阅读的几条实用心得7.1 版本差异0.19和0.21看起来完全不一样如果你先去读0.18、0.19的源码再翻开0.21的最大的感觉就是“这俩真的是同一个项目吗”。0.19及以前表达式求值和属性更新基本都在Property.cpp里内联处理逻辑紧凑但边界模糊0.20之后拆出ExpressionBinding把“绑定表达式到属性”和“执行表达式求值”分离代码结构清晰了一大截。所以如果你刚上手请直接看新版本。看到老代码里那些getExpression()、setExpression()的散落调用也不要慌它们只是新架构的前身。读源码时建议把git blame和提交信息结合起来看。比如搜ExpressionBinding能看到这个文件是什么时候引入的、解决了哪个issue这比从头到尾读代码更能帮助你理解设计动机。源码分析不只是读最终状态看它怎么演进过来同样重要。7.2 调试表达式解析的最快方法想验证一个表达式解析成什么AST最快的办法是在源码里加日志比如在ExpressionParser::parse()返回之前把toString()打出来。不过更推荐的方式是用gdb在Expression::evaluate()里下一处断点观察调用栈。FreeCAD的Debug构建类型支持得很好CMake配置时选-DCMAKE_BUILD_TYPEDebug就行。在FreeCAD自带的Python控制台里你也可以直接实验很多表达式函数。虽然ExpressionParser的Python绑定在不同版本里开放程度不一样但至少有App.ExpressionParser.parse这类接口可以快速试错。真正常备的调试套路是构造一个最小的单文档场景删除其他所有无关对象只保留两个互相引用的立方体然后手动修改表达式观察错误信息。源码分析的问题多半是“这个代码怎么走到的”而最小复现能帮你把范围压缩到十几个文件以内。7.3 读这个框架的正确顺序我的建议是别一上来就啃Expression.cpp的几百行核心实现。先从词法文件开始看看token怎么定义然后过一遍语法文件搞清楚产生式如何组装接着打开ExpressionVisitor把visitor接口扫一眼最后再回到实现类逐类看evaluate()和getReferences()。这个顺序跟着“一条字符串变成数值”的自然流动方向走每前进一步都在已有心智上叠加新知比从中间某个类倒着读舒服得多。读的过程中多留意异常消息。FreeCAD表达式框架的异常信息写得相当友好比如“Unknown variable”或“Incompatible units”这些字符串本身就是理解系统边界的地图。我在读Expression.cpp时经常先用IDE全文搜索某个错误提示字符串然后定位到抛异常的位置顺藤摸瓜看完整条检查链效率非常高。实际跟完整个框架之后我对FreeCAD的“开源但有序”有了更具体的感受。它的表达式框架不是那种炫技式的代码而是围绕“参数化建模”这一件事做了大量朴实而稳健的设计AST节点职责单一、单元系统贯穿始终、依赖图管理规范、循环检测算法经典。如果你打算在FreeCAD之上做二次开发尤其是写参数化工作台或者模板库我强烈建议先把这里读透。很多你以为是“功能缺失”的问题其实在这个框架里都能找到自己的答案。
