Python实现安全公式编辑器：从AST解析到批量校验

简介一份基于Python的公式编辑器设计源码面向游戏数值策划、Python开发人员以及金融分析、科学计算等需要公式化调整数值的领域适合有Python基础、需要快速搭建公式编辑工具的开发者其核心价值在于用数学公式驱动游戏数值变化减少反复编码和手动调参。资源共71个文件、压缩包约955KB其中50个Python源文件构成公式解析、布尔求值、数学控制器、编辑器主界面等主体模块另有6个UI设计文件、5个XML配置文件、Markdown文档、图片与GIF动画可还原布局并辅助理解操作流程。配套示例涵盖PyQt组件演示、天气查询demo、LaTeX公式展示等模块便于学习界面控件用法和二次扩展方向。项目已有348人学习下载具备一定的参考热度。借助该源码可以快速搭建一套公式编辑器原型掌握PyQt界面开发、公式解析和数值联动修改的常见实现方式并将相关逻辑迁移到其他数值处理工具中。1. 策划改一个数值要等一次版本公式编辑器解决的是调参自由度我做数值系统那几年最怕的不是算错数是策划改一个伤害系数要排进版本里。公式在代码里、数值在配置表里两边隔着一次打包、一次提测调参窗口期早就过了。后来我把公式从代码里抽出来做成一个基于 Python 的公式编辑器策划在表里写ATK * 2.5 - DEF * 0.4系统加载时解析成语法树再求值改公式从此不用碰代码平衡性迭代快了一个量级。这套方案适合数值驱动的游戏项目也适合频繁调参的后台系统核心不是界面而是表达式解析、安全求值和缓存这条链路。下面按我实际落地的顺序拆开讲。2. 公式编辑器到底在编辑什么解析、语法树与求值三段式2.1 先看清处理链路别把 eval 直接当成公式编辑器公式编辑器这三个字容易让人以为难在界面其实难在「让一段人写的字符串变成游戏里可用的数值」。这条链路分成三段先把字符串切成长语法对象再组合成语法树最后对着上下文逐节点求值。你真正要交付的是中间那棵语法树而不是求值结果。拿ATK * 2.5 - DEF * 0.4这条公式举例用 Python 自带模块解析一下你能直接看到它的结构import ast tree ast.parse(ATK * 2.5 - DEF * 0.4, modeeval) print(ast.dump(tree, indent2))输出大致是这样Expression( bodyBinOp( leftBinOp( leftName(idATK), opMult(), rightConstant(value2.5)), opSub(), rightBinOp( leftName(idDEF), opMult(), rightConstant(value0.4))))看到这棵树你就明白了求值不是从字符串左边读到右边而是从叶子节点往上算。先读ATK这个变量名乘以 2.5再读DEF乘 0.4最后两个结果相减。这一段里每个节点都对外暴露了类型和内容所以你能在求值前做校验、在求值中打日志、在出错时指出「是第几个运算节点出了问题」。eval 之所以不能直接当公式编辑器用就是因为它是黑匣子你给它字符串它返回结果中间步骤你一概看不到更没法限制它只能做什么运算。公式编辑器要服务的对象是策划不是程序员报错必须说人话安全边界必须收得死这两点 eval 都给不了。2.2 为什么是 Python安全边界、批处理与团队门槛有人会问游戏端公式编辑器用 Lua 不是更顺手吗热更脚本确实灵活但 Lua 的设计哲学是「给你一个完整语言」策划在公式表里能写循环、能写全局变量、能不小心把状态改坏你要在语言层面收边界得自己踩一遍坑才发现到处都是洞。Python 这边有现成的ast模块天然把「能用的语法节点」和「不能用的语法节点」分得清清楚楚你只需要维护一张白名单。我对比过的三条路线按真实落地感受列在下面方案上手成本安全边界批量能力适合场景Lua 热更脚本策划要学一门完整语言边界难收容易写崩运行时一般重度热更需求的线上游戏Excel 公式策划最熟悉无注入问题但函数不可控需要装 Excel 或者用库模拟麻烦中小团队公式量少Python ast表达式子集极简单节点白名单可控到语法级pandas / csv / json 一条龙数值驱动项目需要批量调参与校验再往后看Python 生态是你做批量校验的底气。策划的公式表可能是 CSV、可能是 JSON、可能是后端接口吐出来的字段Python 标准库全覆盖不用引第三方框架。团队门槛也低——策划理解 python 基础语法里「表达式、函数调用、注释」这三样就够用了后端同学维护求值器更不费劲。2.3 什么时候不值得上公式编辑器两条反向判断标准不是所有项目都该上这套东西。我见过团队把公式编辑器做成半年工期的大系统最后公式只有十几条一年不改一次纯属过度设计。你判断值不值得做就看两条。第一条公式是不是高频变动。数值驱动的手游、赛季制的卡牌、有在线运营活动的项目策划每周都要试新数值公式编辑器收益极大单机项目数值定稿后基本不动公式硬编码在代码里完全可接受。第二条有没有非程序角色需要独立改公式。如果只有程序员自己调数值那直接改代码反而更快不值得为单人维护维护一套解析系统。如果你决定做尽量控制在「一个文件、一个求值器、一个校验脚本」的规模别上来就做可视化节点拖拽。可视化是锦上添花表达式文本 实时批量校验已经覆盖了绝大多数调参场景。3. 用 Python 搭核心求值器白名单节点、变量注入与表达式缓存3.1 二十来行实现安全求值节点白名单 运算符白名单核心求值器我一般控制在 60 行以内逻辑就一句话拿到语法树按节点类型分派只处理你白名单里的节点其余一律抛异常。下面这段是完整骨架Python 3.9 及以上直接能跑python 安装好之后开个 VSCode 配好解释器就能调试。import ast import operator as op # 运算符白名单只在映射表里列出的运算会被求值 _BIN_OPS { ast.Add: op.add, # ast.Sub: op.sub, # - ast.Mult: op.mul, # * ast.Div: op.truediv, # / 一律走真除法 ast.FloorDiv: op.floordiv, # // ast.Mod: op.mod, # % ast.Pow: op.pow, # ** } _UNARY_OPS { ast.UAdd: op.pos, # 一元正号 ast.USub: op.neg, # 一元负号 } # 只允许这些常量类型出现在公式里 _ALLOWED_CONSTS (int, float, bool, type(None)) def eval_node(node, env, funcs): 对单个语法树节点求值白名单之外全部拒绝 if isinstance(node, ast.Expression): return eval_node(node.body, env, funcs) if isinstance(node, ast.Constant): if not isinstance(node.value, _ALLOWED_CONSTS): raise ValueError(f常量类型 {type(node.value).__name__} 不在白名单) return node.value if isinstance(node, ast.Name): if node.id not in env: raise KeyError(f变量 {node.id} 不在数值上下文中) return env[node.id] if isinstance(node, ast.BinOp): fn _BIN_OPS.get(type(node.op)) if fn is None: raise NotImplementedError(f运算符 {type(node.op).__name__} 未开放) return fn(eval_node(node.left, env, funcs), eval_node(node.right, env, funcs)) if isinstance(node, ast.UnaryOp): fn _UNARY_OPS.get(type(node.op)) if fn is None: raise NotImplementedError(f一元运算符 {type(node.op).__name__} 未开放) return fn(eval_node(node.operand, env, funcs)) if isinstance(node, ast.Call): if not isinstance(node.func, ast.Name): raise NotImplementedError(只支持直接调用已注册函数不支持属性调用) fn funcs.get(node.func.id) if fn is None: raise KeyError(f函数 {node.func.id} 未注册) args [eval_node(a, env, funcs) for a in node.args] return fn(*args) raise NotImplementedError(f语法节点 {type(node).__name__} 不在白名单拒绝求值)这段代码的关键参数有三个调的时候要心里有数env是变量上下文策划写的每个字段名都得在这里找得到funcs是函数注册表公式里能调用的函数只有这里列出来的_BIN_OPS是运算边界没写进映射表的运算符比如位运算、比较运算在公式里一律报错而不是静默执行。注意最后那个兜底分支任何未列出的节点类型都会被拒。这就是 whitelist 和 blacklist 的本质区别——黑名单永远有漏网之鱼白名单只有你点头的东西才能跑。3.2 变量注入与函数注册让公式里出现策划看得懂的字段名求值器本身不认识ATK是什么需要你在调用前把战斗实体的属性整理成字典传进去。我一般要求字段命名统一大写加下划线这样公式里一眼能分清「这是数值字段」还是「这是函数名」。def build_env(attacker, defender): 把战斗双方属性整理成公式可见的变量上下文 return { ATK: attacker.attack, DEF: defender.defense, HP: attacker.max_hp, crit_rate: attacker.crit_rate, crit_dmg: attacker.crit_dmg, level: attacker.level, level_diff: attacker.level - defender.level, }函数注册用装饰器做最省事。游戏公式里常见的截断、取整、随机数每个都注册成独立函数求值器里只认注册过的名字import math import random _functions {} def register(nameNone): 装饰器把函数放进公式可调用的注册表 def decorator(f): _functions[name or f.__name__] f return f return decorator register(clamp) def clamp(value, low, high): 把数值裁剪到 [low, high] 区间伤害下限 1 这种需求全靠它 return max(low, min(value, high)) register(ceil) def ceil(value): return math.ceil(value) register(rand) def rand_range(low, high): 返回 [low, high) 内随机浮点用于暴击浮动区间 return random.uniform(low, high)组合起来调用的效果是这样clamp(ATK * 2.5 - DEF * 0.4, 1, 99999) rand(0, level)。策划想要什么样的读法就在build_env里定义什么字段名公式层永远不碰游戏对象本身。这里有个设计红线注册函数必须是无副作用的纯函数绝不能把save_to_db、send_event这类东西放进去否则公式表就成了后门的入口。3.3 表达式缓存怎么设计缓存的必须只是语法树不是结果公式在游戏里往往每帧会被调用毫秒级开销都不能接受。解析字符串成语法树是最贵的步骤所以把它缓存下来但缓存对象必须是语法树而不是计算结果否则变量一变数值就错了。from functools import lru_cache lru_cache(maxsize4096) def compile_expr(expr: str): 把公式字符串编译成语法树公式没变这棵树就不用重新解析 return ast.parse(expr, modeeval) def eval_formula(expr: str, env: dict, funcsNone): 对外统一入口编译一次求值多次 tree compile_expr(expr) return eval_node(tree, env, funcs or _functions)maxsize4096的意思是只缓存最近 4096 条不同公式。游戏里技能、Buff、怪物 AI 的公式总量一般是几十到几百条这个值够用如果做的是 UGC 内容生成公式可能上万条LRU 会自动把不常用的挤出去不用你操心内存。这套设计下有个反直觉的好处函数注册表随便增删语法树缓存完全不受影响。因为树里存的是函数名字符串而不是函数对象求值的时候才现查funcs。真正需要手动清缓存的场景只有一种——你改了运算符白名单映射比如给公式开放了新的运算符这时compile_expr.cache_clear()一次就好。4. 接进数值工作流公式表拆分、批量校验与未定义变量检查4.1 公式表用 TSV 而不是 CSV为什么以及目录怎么约定公式编辑器单独一个文件在代码库里跑不起来它得和数值表配套。我落地时的约定是把公式全部抽到独立的表里和角色属性表、技能表分开存放公式表每一行是一条公式用 Tab 分隔。为什么不用 CSV公式里到处都是逗号——clamp(1, 99999)、rand(0, level)——你用逗号做列分隔符解析器根本分不清哪个逗号是分隔符哪个逗号是参数。Tab 在公式里几乎不会出现天然安全。文件格式约定如下# config/formulas.tsv # 第一列是公式 ID第二列是公式表达式 skill_101_damage clamp(ATK * 2.5 - DEF * 0.4, 1, 99999) skill_102_damage ATK * 1.8 level_diff * 10 buff_301_heal HP * 0.15 200读文件的代码用标准库 csv 模块指定delimiter\t同时用utf-8-sig编码打开。后者是个老坑Windows 上 Excel 另存的 CSV/TSV 会带 BOM 头utf-8打开第一行第一个字段会多出一个\ufeff字符直接把你第一列 ID 搞坏。import csv def load_formulas(path): 读取公式表返回 [(行号, 公式ID, 表达式), ...] formulas [] with open(path, encodingutf-8-sig, newline) as f: reader csv.reader(f, delimiter\t) for line_no, row in enumerate(reader, start1): if not row or row[0].startswith(#): continue if len(row) ! 2: raise ValueError(f第 {line_no} 行格式错误必须只有两列) formulas.append((line_no, row[0].strip(), row[1].strip())) return formulas公式抽出来后Git diff 变得非常漂亮策划改一条公式diff 里就是一行字的增删代码评审的人一眼能看出改了哪个技能的哪个表达式。放在代码里的公式是没法这样审查的。4.2 写一个批量校验脚本1000 条公式一条命令跑完定位公式表到了几百条以后最大的风险不是单条写错而是批量改数值时连带出一串坏公式。校验脚本的做法是准备一份真实的战斗属性样本遍历公式表逐条求值任何一条抛异常就记下它的行号和公式 ID最后统一汇报。import json def validate_formulas(path, sample_env_path): 用一份样本上下文跑完全部公式失败逐条打印 with open(sample_env_path, encodingutf-8) as f: sample_env json.load(f) formulas load_formulas(path) errors [] for line_no, formula_id, expr in formulas: try: eval_formula(expr, sample_env, _functions) except Exception as e: errors.append(f第 {line_no} 行 [{formula_id}] 失败: {e}) if errors: print(\n.join(errors)) raise SystemExit(1) print(f全部通过共 {len(formulas)} 条公式)命令行调用方式python validate_formulas.py config/formulas.tsv sample_env.json样本上下文从哪里来我一般从线上真实战斗日志里抽一份属性快照导出成 JSON字段覆盖面要够全最好把冷门 Buff 的字段也带上。这样做有两个好处字段名和游戏里真实存在的一致不会出现校验通过、上线报错的尴尬数值也是真实量级顺手能看出公式结果是否离谱比如伤害算出来是负数、治疗量超过血量上限都是肉眼能发现的异常。4.3 静态检查未定义变量在进游戏之前就把拼写错误拦下运行期报错永远比静态检查慢一步。求值器在跑公式时发现atk不在env里抛一个 KeyError策划要等跑到这条公式才炸但如果你在加载阶段就把公式表里所有引用过的变量名扫一遍拼写错误当场就能拦住。用ast.walk遍历整棵树收集所有Name节点再和合法字段名集合做差集。import difflib def check_undefined_names(tree, valid_names, funcs): 找出公式里引用了但上下文里不存在的名字给出相似名提示 used_names { n.id for n in ast.walk(tree) if isinstance(n, ast.Name) } # 注意函数名也是 Name 节点要先从待检集合里剔除 undefined used_names - valid_names - set(funcs) if not undefined: return for name in sorted(undefined): guess difflib.get_close_matches(name, list(valid_names), n1) hint f你是不是想写 {guess[0]}? if guess else print(f未定义变量: {name}{hint}) raise SystemExit(1)这段代码值得注意两个细节ast.walk会走到树里所有节点函数名clamp本身也是Name节点所以要减去set(funcs)否则每个函数调用都会被误报成未定义变量difflib.get_close_matches能给出拼写建议策划把crit_dmg写成critdmg时报错信息里直接提示正确写法省去一轮来回确认。把校验脚本挂到 CI 或者提交前钩子里公式表的问题就永远不会流到游戏运行时。5. 公式编辑器避坑指南五个高频翻车现场的排查记录5.1 直用 eval 上线玩家给你递来一串对象链 payload现象开发期图省事求值直接写eval(expr, {__builtins__: {}}, env)上线后发现服务端能收到异常请求公式字符串里带一段().__class__.__mro__开头的代码就能顺着对象继承链摸到内存里其他对象。原因eval 的 globals 你永远封不干净。就算关了__builtins__类对象、元类之间的引用链仍然存在只要表达式里有办法拿到一个对象就能.__class__.__mro__一路往下挖。解决彻底放弃 eval改用第 3 章那套 ast 白名单求值器。节点白名单里没有Attribute属性访问和Subscript下标访问对象链这条路从语法层面就是死的。5.2 0.1 0.2 不等于 0.3伤害数字和策划文档对不上现象公式算出来的伤害是100.0000000001游戏界面显示整数看不出来但日志和策划文档对不上自动化测试直接断言失败。原因浮点数在二进制下没法精确表示 0.1多段 Buff 乘算叠加后误差会累积到肉眼可见。解决求值结果统一四舍五入我一般给eval_formula加一个ndigits4参数默认保留四位小数。写数值对比逻辑时用abs(a - b) 1e-6而不是a b。真需要精确结算的场景比如扣血必须精确到整数考虑把血量字段设计成整数最小单位存储公式层只做整数运算。5.3 DEF 被减到 0一场 Boss 战把战斗模块干崩溃现象某技能公式是ATK / DEF * 系数Boss 被挂上减防 Buff 后 DEF 归零除法直接抛ZeroDivisionError战斗进程当场崩。原因公式编辑器只管「能算」不管「算出来合不合理」分母没有下限保护。解决两道防线。第一道在环境侧注入前先清洗DEF下限强制max(1, value)第二道把除法也收进函数注册表注册一个带保护分母的safe_divregister(div) def safe_div(a, b, fallback0.0): 分母接近 0 时返回 fallback而不是让运行时崩溃 if abs(b) 1e-9: return fallback return a / b公式从ATK / DEF改成ATK / div(DEF, 1)行为显式化策划写公式时也能一眼看到这个除数有保护逻辑。5.4 公式里手滑写成小写 atk报错栈刷了一整屏现象策划在公式表里写atk * 2.5上下文只有ATK游戏跑起来后报错栈一层套一层连带战斗模块调用链全打出来非程序员根本看不懂。原因字段命名没有做强约束求值器的 KeyError 信息太干只有atk几个字符没告诉人该改成什么。解决三件事一起做。命名约定统一大写加下划线校验脚本加载公式时强制做静态检查未定义变量直接报错并给相似名建议4.3 的代码就是干这个的求值器里捕获 KeyError 后重写成「变量 missing 不存在可用字段见 sample_env.json」的提示别让原始堆栈裸奔到策划面前。5.5 表改了公式不生效先查 BOM 编码、再查打包、最后查缓存现象策划改了公式表服务器上跑的数值还是旧的第一反应怀疑缓存清了半天缓存发现没用。原因大多数情况不是缓存问题而是公式表文件没被正确替换。最常见是 Windows 下 Excel 另存把文件存成 GBK 编码脚本按utf-8读直接乱码或报错其次是打包流程漏了新表服务器还在跑旧资源。解决排查顺序固定为「编码 → 打包 → 缓存」。读表统一utf-8-sig能同时兼容带 BOM 和不带 BOM 的文件构建脚本里对公式表算一个哈希发布清单里带上哈希值线上比对不一致就拒绝启动最后才怀疑编译缓存——前面说了缓存 key 是公式原字符串字符串变了 key 自然变真正会因为缓存出问题的概率极低。6. 一个提升调试效率的技巧求值器加中间量日志公式不再是黑匣子公式编辑器用久了你会发现最难的从来不是解析是公式结果不对时你根本不知道它错在哪一步。普通求值器返回最终数值中间过程对你是黑匣子伤害少了 20%是ATK字段没取到还是clamp下限生效了你只能靠猜。我给求值器加过一个调试模式传入一个 logger在遍历语法树时把每个节点的中间结果记下来调试完一关线上零开销。def eval_formula_traced(expr, env, funcsNone): 调试专用打印每一步求值过程结果不对时一眼定位 funcs funcs or _functions tree compile_expr(expr) logs [] def walk(node): if isinstance(node, ast.Expression): return walk(node.body) if isinstance(node, ast.Constant): logs.append(f常量 {node.value}) return node.value if isinstance(node, ast.Name): val env.get(node.id, funcs.get(node.id)) logs.append(f读取 {node.id} {val}) return val if isinstance(node, ast.BinOp): left walk(node.left) right walk(node.right) val _BIN_OPS[type(node.op)](left, right) logs.append(f{left} {type(node.op).__name__} {right} {val}) return val if isinstance(node, ast.Call): args [walk(a) for a in node.args] val funcs[node.func.id](*args) logs.append(f{node.func.id}{args} {val}) return val return eval_node(node, env, funcs) result walk(tree) print(\n.join(logs)) return result跑一条clamp(ATK * 2.5 - DEF * 0.4, 1, 99999)的公式日志会打出一串类似「读取 ATK 1000读取 DEF 8002500 - 320 2180clamp[2180] 2180」的记录。哪一步出了偏差看日志比看堆栈快十倍。这个调试开关我用环境变量控制默认关闭只有排错时才临时打开。我现在的习惯是凡是给策划用的计算工具第一版就内置 trace 能力不等到出问题再补任何公式结果不对先打 trace 看中间量再下结论是公式问题还是数值问题。这个顺序帮我少加了很多班。希望帮到你。本文还有配套的精品资源点击获取