· engineering· 约 28 分钟精读

读数不是一个数:端侧检测表单里,一条录入串在解析、判定与落盘三处的不同下场

核心要点速览 · TL;DR 概要

TagWorks 的三个测量读数在输入框里全是字符串,只有调用 Double(text) 的瞬间才成为数。本文实测一张完整解析表,核对判定层的三道门闩与一个死卫,并复现一条粘贴进去的 nan 如何让整本登记册的落盘与备份同时失效,而 CSV 与 PDF 照常外发。

读数不是一个数:端侧检测表单里,一条录入串在解析、判定与落盘三处的不同下场

一、输入框里没有数

电气检测现场的普通一幕:测试仪表显示接地回路电阻 150 mΩ,操作员用还戴着棉线手套的手指,往手机的输入框里敲一个读数。这个动作在 TagWorks 里到底发生了什么,很少有人停下来数一遍——本文就数一遍。

先把结论摆出来:这款应用的判定链只接收数字,但它的输入层从头到尾持有的是字符串。三个测量字段在 TestEntryView.swift 里的声明是这样的:

// Sources/TagWorks/Views/TestEntryView.swift:13-15
@State private var earth: String = ""
@State private var insulation: String = ""
@State private var loadCurrent: String = ""

三个都是 String,键盘一律 .decimalPad,没有 formatter,没有 onChange 过滤,也没有任何字符白名单。数字只在 Double(earth) 被调用的那一瞬间存在,而这一瞬间在一屏之内会发生很多次:测量判定是计算属性,界面每重绘一次就重解析一次;保存时又用同一个函数把字符串再解析一遍、填进 TestRecord 的 Double? 字段。同一个录入串在“看”和“存”两处各自解析,中间没有任何命名为“解析结果”的东西驻留。

用字符串而不是数值绑定,是一种有代价也有收益的选择。SwiftUI 的数值型 TextField(value:format:) 会“吃掉”非法输入——敲下去的字符不合法就回退到上一个有效值,操作员甚至不知道自己敲过什么。这款产品选择保留原始串,把“这是什么数”整个推迟给解析函数。推迟之后要看接住没有:解析不出来时,三个字段给了三种不同的答案,而落盘那一层根本没参与这个决定。

二、一次解析有多严格:实测解析表

本文把候选样本编成探针,连同产品真实的 TestRecord.swift 与 Domain.swift 一起,在 Swift 6.4.2 工具链上编译实测;iOS 与 macOS 的 Foundation 同源,以下结论按同一行为对待。

录入串Double(text)这一行在说什么
6262.0正常读数
1,5nil逗号不是小数点:解析只认句点
5、5、5nil首尾空格不跳过,整串作废
12 345nil千分位写法是整串的死因
+11.0正号合法
-1-1.0负号合法——解析放行,判定层管
1e31000.0科学计数法合法
1e400inf上溢不报错,变成无穷大
1e-4000.0下溢静默折成零
0x1p38.0十六进制浮点合法
nan、infnan、inf英文单词变成特殊数
١٢٣、1234nil阿拉伯-印度数字与全角数字都不认
1.2.3、..5、5\nnil第二个点、开头点、换行都是毒

三个容易被忽略的要点。

其一,键盘不是字符集的边界。.decimalPad 只约束软键盘的键帽:它没有空格键、没有减号、没有字母。但粘贴不看键盘脸色,iPad 外接键盘不看键盘脸色,从表格软件里复制一个单元格更不看脸色。录入框的真实字符集,是 Unicode 全集减掉解析器肯认的那一小撮。

其二,指数写法有两个方向,两个下场。1e400 解析成无穷大,它会一路走进第五节描述的落盘风暴;1e-400 解析成 0.0,下溢静默把数量级改写成一个合法的小数——绝缘字段里没人写 1e-400,但“从导出文件里粘一段科学计数法文本”正是它的产地。

其三,-1 能通过解析。负接地电阻在物理上不存在,但解析器不是物理老师,它的职责只有一个:这是不是一个数。“数合不合法”整个推给下游判定层。判定层接住了,但代价出现在更远处(第五节)。

三、三个字段,三种失败语义

同样是解析出 nil,三个字段各自的下场完全不同。这是全文最核心的一张对照表:

字段输入侧校验串解析失败时是否进判定函数是否进报告
接地 earth无记为 nil=未测量,表单照常可存是(仅 Class I)PDF 证据行与两份 CSV
绝缘 insulation无记为 nil=未测量,表单照常可存是(所有类别必需)PDF 证据行与两份 CSV
负载电流 loadCurrentisFinite && >= 0hasValidLoadCurrent 为 false,保存被整张表单拦下否,从不参与仅两份 CSV,PDF 没有它

hasValidLoadCurrent 的实现只有三行,值得原文抄出:

// Sources/TagWorks/Views/TestEntryView.swift:29-33
guard !loadCurrent.trimmingCharacters(
      in: .whitespacesAndNewlines).isEmpty else { return true }
guard let loadCurrentValue else { return false }
return loadCurrentValue.isFinite && loadCurrentValue >= 0

它制造了三种耐人寻味的状态。空串算“有效”——不填这个字段不会碍事;纯空格也算空、也算有效;而“空格加数字”会让整个表单存不下去,四类记录(test、repair、retest、release)的保存共用这一道 canSave 闸门。判断“是否为空”用的是 trim 之后的串,判断“是不是数”用的是没 trim 的原串——同一个字段,对“空”有两套口径,夹在两套口径之间的就是那条 5:trim 后非空,于是必须过解析;解析带空格的串返回 nil,于是整张表单被一条没填错只是没擦干净的负载电流拦停。界面亮出一行橙色提示(Load current must be a non-negative finite value)——可用户输入的不是负值也不是无穷,只是一个带空格的 5;把“解析失败”的文案写成“数值非法”,方向就错了。

接地字段里同一条 5 是另一回事:没有橙色提示、没有任何报错,这条测量就“不存在”了。Class I 资产还剩一线生机——接地为 nil 会把判定拖进 notMeasured,界面亮起 “No numeric measurement recorded”;但警示不说是哪个字段,也不说敲进去的串被丢掉了。在 Class II 资产上接地框根本不渲染,这个场景不存在;而在 repair、release 这类不要求判定结论的记录里,nil 连警示都换不来。

第三个不对齐最扎眼:全应用唯一一处输入侧量级校验(isFinite && >= 0),挂在唯一一个从不参与判定的字段上。两个真正决定 PASS/FAIL 的字段,输入侧零校验,它们的安危全系在判定函数最前面的三道门闩上。

四、判定层的三道门闩与一个死卫

判定函数是全应用最短的一段“法律”,原文照抄:

// Sources/TagWorks/Models/TestRecord.swift:233-237
static func evaluate(earthMilliohms: Double?,
                     insulationMegaohms: Double?,
                     requiresEarth: Bool = false) -> TestEvaluation {
  if let e = earthMilliohms,
     (!e.isFinite || e < 0 || e > earthBondMaxMilliohms) { return .fail }
  if let i = insulationMegaohms,
     (!i.isFinite || i < 0 || i < insulationMinMegaohms) { return .fail }
  if (requiresEarth && earthMilliohms == nil)
     || insulationMegaohms == nil { return .notMeasured }
  return .pass
}

两个门限常量:接地不大于 100 mΩ,绝缘不小于 1.0 MΩ,与 AS/NZS 3760:2022 的经典口径对齐。这一层的设计质量,是整条输入链路里最高的——但它的“高”体现在门闩的顺序里,而不是数量上。

第一,顺序即生死。IEEE 754 规定 NaN 与任何数做大小比较一律返回 false,两个比较都赢不了:

(NaN<0)  =  (NaN>100)  =  false(\mathrm{NaN} \lt 0)\;=\;(\mathrm{NaN} \gt 100)\;=\;\mathrm{false}

把 !e.isFinite 挪到第三个子句,或者整个删掉只留双侧检查,一条粘贴进来的 nan 就会穿过两道门闩、直落最后的 .pass。现行写法把有限性放在最前,短路在后,所以 inf 与 nan 一律 fail。契约被单元测试钉住:testNegativeAndNonFiniteMeasurementsFail(DomainTests.swift:200-204)断言 earth = .nan 与 insulation = .infinity 均返回 fail。

第二,绝缘行的负数门闩是死卫。i < 0 被后面的 i < insulationMinMegaohms(阈值 1.0)完全覆盖——负数本来就越不过“不小于 1 MΩ”这条线,删掉前者,函数的每个返回值都不变。而接地行的 e < 0 是活卫:上限判定拦不住负数,没有这一句,-1 就能进 pass。两行代码刻意写成对称形状,其中一句守卫其实从不单独起作用——对称是写代码的人的审美,不是读代码的人的信息,这类“看着安心”的冗余值得在评审里点名。

第三,nil 的三分语义。这个函数里 nil 表示“没有这个读数”,不是“读数为零”。对 Class I 资产,接地 nil 加绝缘 2.0 返回 notMeasured 而不是 fail;notMeasured 不能确立 PASS,手动选 Pass 也会被 canSave 拦(A manual PASS cannot replace missing or failed required measurements——这道闸的闭环在缺陷链专题已有专文,此处只取结论)。于是第三节那条被静默丢弃的脏串,在判定层的身份是“这台设备今天没测接地”,而不是“接地测坏了”。

还有一处顺带的后果值得记下:粘贴 nan 进接地框,判定给出 fail——这不是拦截,而是放行。FAIL 结论在满足目视与署名条件后可以保存(预测性 fail 甚至不强制备注),也就是说,判定层拦住了“nan 通过”,却放“nan”本身进了记录。记录一旦成形,真正拒绝它的地方在下一个环节,而那里的反应剧烈得多。

读数不是一个数:一条字符串,三种去向录入串1,512 3450x1p31e4001e-400nan一次解析Double(text)只认 ASCII 数字逗号不是小数点首尾带空格 整串归 nil1e-400 静默折成 01e400 与 nan 保留原形无报错界面 · 无字段提示有限数 → 进判定链isFinite → 非负 → 上限 三道守卫按顺序生效NaN 与任何数比较都是假 · 顺序颠倒就漏进 PASS解析失败(nil)→ 两个下场接地 / 绝缘:当作没测 表单照常保存负载电流:整张表单被拦 四类记录都存不下inf / NaN → 只进得了内存JSON 语法里没有这两个数 整本登记册落盘拒绝备份档案同时失能 CSV 与 PDF 却照常外发此后每一次改动都在保存 每一次都失败唯一会说话的是弹窗「Register storage needs attention」—— 它不说是哪一条记录冻住了整本册子实测环境:Swift 6.4.2 · 编译对象为产品真实模型文件

左右滑动查看完整图表

五、落盘拒绝:一条 nan 冻住整本登记册

保存的链路是这样串起来的:TestEntryView.save() 把 Double(earth) 塞进 TestRecord 追加进 records;@Published 的 didSet 调度一次 400 毫秒防抖保存;RegisterStore.write() 把资产数组加记录数组打包成 Snapshot,交给 JSONEncoder 整本编码,成功后以 .atomic 一次性落盘。

问题出在编码这一步的方言上。JSON 的数值文法(RFC 8259 第 6 节)由整数部分、小数部分、指数部分构成,NaN 与 Infinity 在语法上就不是数。Swift 的 JSONEncoder 对非有限 Double 的行为是抛出 EncodingError——实测报错文案:The data couldn’t be written because it isn’t in the correct format.。于是整条链路在最后一米炸出这样一个事故序列:

粘贴 nan → Double→NaN → 判定 fail → 记录进内存
→ 400 ms 防抖到期 → 整本 encode 遇到 NaN → 抛错
→ persistenceIssue = .saveFailed → 应用级弹窗

write() 的 catch 把所有异常折成一个 .saveFailed,界面在 App 层弹出一只标题为 “Register storage needs attention” 的告警框,正文建议“保持应用开启、清理存储空间后重试”。这其实是存储不足的救法;此刻的病因是编码,清出再多磁盘也不会变好。两个按钮各走各的死循环:Retry 调 retryPersistence,落回 flush 再到同一台编码器,再抛;OK 只是 acknowledgePersistenceIssue 把旗标抹掉,中毒记录原封不动留在内存。

从这一刻起,这台设备进入一种安静的分裂状态:每一次改动(加设备、做检验、删记录)仍然在内存里生效、仍然反映在界面上,也仍然触发 400 毫秒防抖——而每一次落盘都失败。切后台触发的冲刷同样失败;弹窗被点掉之后,下一次改动失败还会再把它请出来。整本编码是全有全无的交易,好处是磁盘上永远不会出现半本新账:编码失败发生在写文件之前,盘上的旧 register.json 一字节未动。代价是传染性——一本册子里一条记录有毒,就是一条也存不下去,而弹窗从不指出中毒的是哪条记录。

自愈通道只有一个:杀掉应用重启。启动时 load() 读回盘上的旧快照,中毒记录从未上过盘,随内存一起蒸发——连同它之后产生的所有改动。设备端没有任何“有改动未保存”的角标、清单或恢复提示;重启后的登记册看起来干净健康,唯一知道那段历史存在过的证据,只有刚才那只被点掉的弹窗。

备份通道同步阵亡:BackupService 的档案同样经 JSONEncoder 编码(含快照、照片与检验员档案),中毒期间导出备份直接失败。Settings 页的错误提示复用了恢复流程的 restoreError 字段,弹窗标题写着 “Restore failed”,正文却是 “Could not create backup: …”——用户在没有任何“恢复”动作的场景里,收到一只“恢复失败”标题的告警。文案错位不算事故,但它意味着备份失败在界面设计上没有自己的脸。

最没有动静的是外发件。两份 CSV 用 String(record.earthContinuityMilliohms) 拼接读数,String() 对 NaN 就印 nan;转义集只认逗号、引号与换行(这一族行为在 CSV 转义专文里数过家底,此处只补一句:它对 nan 这个词一视同仁)。PDF 报告的证据行用字符串插值直接拼 "Earth \($0) mΩ"——于是纸质报告上会印出 “Earth nan mΩ”。一条永远写不进设备登记册的记录,可以正常地随 PDF 与 CSV 走天下:公司名、资质号、签名都在它头顶。等这台手机重启之后,设备端的册子里再无此行,而那份报告已经躺在别处的归档夹里。端侧的账和纸上的账,就在这一条字符串上分家了。

同一读数三处渲染三种字面量:PDF 证据行走插值(62 印成 “62.0”)、CSV 走 String()、手册计算器一侧还有 %.2f——这条链路上没有一处规定“读数在纸面上长什么样”。

六、单位只活在占位文案里

把镜头拉回录入之前。接地框的占位文案写着 “Earth bond (mΩ)”,绝缘框写着 “Insulation (MΩ)”。单位的全部存在形式就是这串提示文字:字段名里缝着单位(earthContinuityMilliohms),判定常量是裸的 100.0,导出表头再缝一次单位——唯独从键入到判定的通路上,没有任何一处对数量级提问。

现场真实值操作员输入台账记为判定后果
接地 150 mΩ(应 FAIL)150150 mΩfail正确
接地 0.15 Ω=150 mΩ(应 FAIL)0.15(以为单位是 Ω)0.15 mΩpass开路设备按合格入账
绝缘 0.5 MΩ(应 FAIL)500(以为单位是 kΩ)500 MΩpass不良绝缘按合格入账
绝缘表头 999 MΩ 溢出读数999999 MΩpass无碍(本就合格)

规律一句话:接地只防大(上限 100),绝缘只防小(下限 1.0),而两类单位误写恰好都落在不设防的方向上。这不能归咎于判定函数——单侧阈值在数学上就买不来量级合理性,要拦住“0.15”,得知道这台设备接地回路的典型区间是多少,而这个信息不在设备上、不在台账里、AS/NZS 3760 也没写过。这是端侧工具诚实的能力边界:**判定层可以保证没有非有限数进 pass 分支,但不能保证你敲进去的就是仪表显示的那个数。**从仪表到手机,读数全程靠人手抄写,这条通道上没有任何软件能替你守门。

七、同一个列名,两本账

读数离开设备时的最后一段路,还藏着一个命名事故。两款 CSV 各自有一列,列名都叫 MeasurementState,含义却正好相反:

列出处值域取数逻辑
MeasurementState(登记册 CSV)CSVExporter.makeCSVPASS / FAIL / NOT MEASURED最近一次 test/retest 的 measurementEvaluation——判定口径
MeasurementState(历史 CSV)makeHistoryCSVRECORDED / NOT MEASURED该记录三字段是否有一个非 nil——measurementState——“填没填”口径

负载电流在这个矩阵里最后一次出场:它进 measurementState 的“填了”统计,不进判定。一条只填了负载电流 3.2 A 的放行记录,在历史 CSV 里的同一行会长成:MeasurementState=RECORDED,EvidenceState=NOT MEASURED——“已记录”与“未测量”肩并肩印在同一行里,两个都没说谎,因为它们量的是不同的东西。而 PDF 报告连核对这对矛盾的机会都不给:证据行打印判定、目视、Earth、Insulation、Tester 等十二项,唯独没有那个标签写着 “A, evidence only” 的字段。它被表单标记为证据,被判定层拒之门外,最后在唯一面向人的载体上不留痕迹,只剩 CSV 里一个孤零零的数值列。

八、对照:另一端的兄弟应用

SlingGuard 的检验表单走的是另一个极端:五个勾选布尔、一个三成员类型枚举、三个自由文本框、一个日期选择器——数值输入位是零。它不存在解析失败,因为无解析可失败;量级误写同样不存在,因为没有量级。它付出的对价在报废判据落位那头(五框对十七条判据的粒度损失,另有专文)。两款产品像是一条设计光谱的两端:要数值判定,就得养解析契约与它的一切边角语义;要输入面零风险,就得放弃数值。这条光谱本身没有正确答案,但它有一条底线:台账的输入面必须对“串解析不出来时算什么”回答一次。 回答可以不同,不回答不行——而 TagWorks 的三个字段,事实上给出了三种回答。

九、工程收口:五条改法与六条边界

改法五条,按投入产出排序。其一,把解析失败显式化:先 trim 再解析,trim 后非空而解析失败时,在出错字段就地报错、逐字段命名,终结 nil 与“用户没填”共用一副面孔的现状;负载电流的空判定与解析判定必须用同一个 trim 口径。其二,把有限性闸门从判定层提前到 save() 组记录之前:非有限值当场拒绝保存并指名道姓——入口拦截比落盘拦截便宜一个数量级,因为落盘处的异常是整本连坐。其三,落盘失败时区分“编码失败”与“写盘失败”两种病因(现在同折为一个 .saveFailed),并在告警里给出可疑记录的行数或编号;整本事务可以保留,但中毒面必须可定位。其四,两份 CSV 的 MeasurementState 一列改名分义:判定侧叫 EvaluationState,证据侧叫 HasReading,或者统一取判定口径。其五,若单位继续只活在占位文案里,就给两个字段各印一行典型区间(接地 10–90 mΩ、绝缘 1–999 MΩ 一类),并对落入典型区间外一个数量级的读数加一次软确认——不改变任何法定判定,只把量级误写的决定权还给操作员。

能力边界六条,写下来免得读者替本文乐观。第一,.decimalPad 约束软键盘,不约束剪贴板与外接键盘——一切输入面校验都要按“串可以是任意 Unicode”来设计。第二,Double(String) 的严格是语言特性不是产品设置:全角、阿拉伯-印度数字一律 nil 且不报错,换用数值绑定又会丢掉半输入的可见性,此题无全解。第三,判定层的有限性门闩只保证数不伤账,不保证数从仪表来——仪表到手机全程人抄,软件不可守。第四,JSON 拒绝非有限数是标准规定而非 Swift 缺陷;任何用 JSON 存数值的端侧台账,写入前的有限性检查都省不掉。第五,纸端与端侧的分家不可逆:告警弹出之前,外发件完全可能已经离开设备。第六,本文解析表与编码行为实测于 Swift 6.4.2 / macOS 27 的同源 Foundation,若苹果改变 Double(String) 的容错面,第二节表格需重测——但“字符串到数的边界必须有人显式回答”这条结论不随之作废。

十、一周之内的侧证

密评与检测行业这周的动作,恰好给“工具与原始记录”这对关系再添了两笔注脚:2026-11-16,国家密码管理局公示通过商用密码检测机构(商用密码应用安全性评估业务)资质申请材料审查的机构名单;同日,成都市特种设备检验检测研究院对“2026年度密改设备”项目发起调研公告。一边是评估机构的资质开始按名单管理,一边是检验检测机构自己的信息系统开始被要求改造——两头指向同一个事实:出报告的工具本身,正在成为被记录、被审查的对象。对一款端侧检测应用来说,它未必能被审进谁的名单,但它对一条 nan 的反应方式,已经原样写进了每台设备的弹窗里。

参考资料

  • [1] RFC 8259:JSON 数据交换格式,第 6 节数值文法。IETF
  • [2] IEEE 754-2019:浮点算术标准,NaN 的有序比较语义。IEEE SA
  • [3] Apple 开发者文档:UIKeyboardType.decimalPad 的键位定义。Apple
  • [4] Apple 开发者文档:Double 的字符串可失败初始化器。Apple
  • [5] 国家密码管理局:商用密码检测机构资质申请材料审查通过机构名单公示(2026-11-16)。OSCCA
  • [6] AS/NZS 3760:2022:在役电气设备检验、测试与认证指南条目页。SAI Global

本文代码事实取自 TagWorks 当前发布源码;解析表与编码行为对产品源文件实测,非文档转述。

Share:
Back to Blog