一个给中学物理老师用的实验报告工具,上线半年后被一位老师指出:学生算出来的光子能量,和教材答案差 0.06%。查了两天,追到一行常量定义——普朗克常数写成了 6.63e-34,那是几十年前的教材取整值。更麻烦的是,同一个常数在另外两个仓库里各有一份拷贝,三份里有两份是旧值。修完这一行,我开始认真考虑:这类常数到底该存在哪。
下面拿数据鱼API的「科学计算」服务当例子。它有两个端点,一个给常数表,一个做公式计算,正好代表两种存法。
自建的做法通常是新建一个 constants.ts,把常数抄进去,再在注释里写明单位。问题不在抄的当下,而在第三次修改:有人改了主仓库,忘了另一个服务;有人为了省事先写在业务函数里;有人把 e 的位数截到四位。数据鱼这个接口的 constants 端点只做一件事,把八个基本常数连同中文名和单位一起返回:
符号 | 名称 | 值 | 单位 |
|---|---|---|---|
c | 光速 | 299792458 | m/s |
h | 普朗克常数 | 6.62607015e-34 | J s |
e | 元电荷 | 1.602176634e-19 | C |
G | 万有引力常数 | 6.6743e-11 | m^3 kg^-1 s^-2 |
k | 玻尔兹曼常数 | 1.380649e-23 | J/K |
NA | 阿伏伽德罗常数 | 6.02214076e+23 | mol^-1 |
R | 摩尔气体常数 | 8.314462618 | J mol^-1 K^-1 |
g | 标准重力加速度 | 9.80665 | m/s^2 |
对照一下就知道旧值的差距有多大:h 精确到小数点后八位,e 和 NA 都是定义值,精确到末位。你要抄的不是一个数,而是一个版本,版本会变,散在三个仓库里的拷贝不会自己变。
calculate 收两个参数:formula 必填,params 是变量对象。它不是一个能解析任意算式的求值器,源码里只认三个公式键:
formula | 计算 | params | 返回单位 |
|---|---|---|---|
force | F = m × a | m、a | N |
energy_mass | E = m × c² | m | J |
ideal_gas | P = nRT / V | n、T、V | Pa |
传这三个之外的字符串,接口不会报错,result 会是 0、unit 为空。这个坑要提前跟调用方讲清楚,别把它当万能公式引擎。像开头那种光子能量 E = hν,不在白名单里,我们仍然用 constants 拿到的 h 在业务层算;只有落在这三条里的计算,才走 calculate。
params 文档标的是字符串,实际要按对象传,键就是公式里的变量名;传成字符串会被当成数字键,取不到 m、a 这些值,结果会静默算成 0。对这三条内置公式,接口会把 formula、params、result、unit、calculated_at 一起返回。输入原样回显,等于附带一条审计线索:把整段响应写进报告记录,半年后有人质疑某个结果,翻记录就能复现。自建要补这段,得另外设计日志格式。缺 formula 返回 4001;计算本身没有别的参数校验,params 少键时按 0 参与运算,调用前要自己把变量补齐。
接口返回的 unit 是 m^3 kg^-1 s^-2 这种写法,不是结构化的量纲对象。有人觉得不够优雅,想解析成指数对的数组,我不建议:这类写法在物理里是通用记法,解析器写起来不难,写错很难发现,而且一旦接口哪天把单位改成 N m^2 kg^-2,你的解析器就崩了。当字符串原样展示,量纲换算在业务层用白名单做,稳妥得多。
还有一点值得记下:未知公式不报错、直接给 0,比抛错更危险。实验工具里我们加了一层白名单,只放行 force、energy_mass、ideal_gas 三个键,其余一律在业务层拦掉;否则一个拼错的公式名会安安静静地生成一份 result: 0 的报告,学生照着写结论,比看到报错难受多了。
写完这版,我把三个仓库的常数表删了,改成构建时拉一次 constants 做快照;三个内置公式走 calculate,光子能量这类不在白名单里的,用快照里的 h 在业务层算。常数这件事,抄一次是疏忽,抄三次就是流程问题。数据鱼这套端点把版本、单位、留痕三件事捆在一起,省下的不是几行代码,是以后每次被质疑"这个数怎么来的"时的排查时间。
以上端点、参数与常数取值,整理自数据鱼API「科学计算」接口的公开文档;文中场景为虚构示例,计算结果的适用条件请以教材与实验规范为准。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。