· engineering· 约 28 分钟精读
Tagworks Reading Input String Three Fates — Technical Analysis | KeyRotate Technology
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) | 这一行在说什么 |
|---|---|---|
62 | 62.0 | 正常读数 |
1,5 | nil | 逗号不是小数点:解析只认句点 |
5、5、5 | nil | 首尾空格不跳过,整串作废 |
12 345 | nil | 千分位写法是整串的死因 |
+1 | 1.0 | 正号合法 |
-1 | -1.0 | 负号合法——解析放行,判定层管 |
1e3 | 1000.0 | 科学计数法合法 |
1e400 | inf | 上溢不报错,变成无穷大 |
1e-400 | 0.0 | 下溢静默折成零 |
0x1p3 | 8.0 | 十六进制浮点合法 |
nan、inf | nan、inf | 英文单词变成特殊数 |
١٢٣、1234 | nil | 阿拉伯-印度数字与全角数字都不认 |
1.2.3、..5、5\n | nil | 第二个点、开头点、换行都是毒 |
三个容易被忽略的要点。
其一,键盘不是字符集的边界。.decimalPad 只约束软键盘的键帽:它没有空格键、没有减号、没有字母。但粘贴不看键盘脸色,iPad 外接键盘不看键盘脸色,从表格软件里复制一个单元格更不看脸色。录入框的真实字符集,是 Unicode 全集减掉解析器肯认的那一小撮。
其二,指数写法有两个方向,两个下场。1e400 解析成无穷大,它会一路走进第五节描述的落盘风暴;1e-400 解析成 0.0,下溢静默把数量级改写成一个合法的小数——绝缘字段里没人写 1e-400,但“从导出文件里粘一段科学计数法文本”正是它的产地。
其三,-1 能通过解析。负接地电阻在物理上不存在,但解析器不是物理老师,它的职责只有一个:这是不是一个数。“数合不合法”整个推给下游判定层。判定层接住了,但代价出现在更远处(第五节)。
三、三个字段,三种失败语义
同样是解析出 nil,三个字段各自的下场完全不同。这是全文最核心的一张对照表:
| 字段 | 输入侧校验 | 串解析失败时 | 是否进判定函数 | 是否进报告 |
|---|---|---|---|---|
接地 earth | 无 | 记为 nil=未测量,表单照常可存 | 是(仅 Class I) | PDF 证据行与两份 CSV |
绝缘 insulation | 无 | 记为 nil=未测量,表单照常可存 | 是(所有类别必需) | PDF 证据行与两份 CSV |
负载电流 loadCurrent | isFinite && >= 0 | hasValidLoadCurrent 为 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,两个比较都赢不了:
把 !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”本身进了记录。记录一旦成形,真正拒绝它的地方在下一个环节,而那里的反应剧烈得多。
左右滑动查看完整图表
五、落盘拒绝:一条 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) | 150 | 150 mΩ | fail | 正确 |
| 接地 0.15 Ω=150 mΩ(应 FAIL) | 0.15(以为单位是 Ω) | 0.15 mΩ | pass | 开路设备按合格入账 |
| 绝缘 0.5 MΩ(应 FAIL) | 500(以为单位是 kΩ) | 500 MΩ | pass | 不良绝缘按合格入账 |
| 绝缘表头 999 MΩ 溢出读数 | 999 | 999 MΩ | pass | 无碍(本就合格) |
规律一句话:接地只防大(上限 100),绝缘只防小(下限 1.0),而两类单位误写恰好都落在不设防的方向上。这不能归咎于判定函数——单侧阈值在数学上就买不来量级合理性,要拦住“0.15”,得知道这台设备接地回路的典型区间是多少,而这个信息不在设备上、不在台账里、AS/NZS 3760 也没写过。这是端侧工具诚实的能力边界:**判定层可以保证没有非有限数进 pass 分支,但不能保证你敲进去的就是仪表显示的那个数。**从仪表到手机,读数全程靠人手抄写,这条通道上没有任何软件能替你守门。
七、同一个列名,两本账
读数离开设备时的最后一段路,还藏着一个命名事故。两款 CSV 各自有一列,列名都叫 MeasurementState,含义却正好相反:
| 列 | 出处 | 值域 | 取数逻辑 |
|---|---|---|---|
| MeasurementState(登记册 CSV) | CSVExporter.makeCSV | PASS / FAIL / NOT MEASURED | 最近一次 test/retest 的 measurementEvaluation——判定口径 |
| MeasurementState(历史 CSV) | makeHistoryCSV | RECORDED / 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 当前发布源码;解析表与编码行为对产品源文件实测,非文档转述。