一、前言做金融、支付、记账、电商类 Flutter 项目小数精度丢失是典型的隐形线上风险。 后端正常返回0.1、9999999999.99经过 Dart JSON 解析后数据直接失真0.1→0.100000001421085489999999999.99→10000000000.0线上对账异常、资产展示错误、结算金额偏差这些都属于 P0 级故障。网上多数文章只给出「DTO 用 String 接收、运算使用 Decimal 库」的结论但很少讲清楚一个核心问题为什么在 Model 层、业务层补救完全无效精度问题究竟发生在哪一步本文结合实际踩坑案例、原理分析、完整可运行代码告诉你精度丢失发生在 JSON 解析瞬间唯一根治手段是在网络层提前处理。二、精度丢失现场可直接复现案例2.1 基础浮点数运算问题dartvoid main() { double a 0.1; double b 0.2; print(a b); // 输出0.30000000000000004 }2.2 普通单层 JSON 解析场景业务高频踩坑dartimport dart:convert; void main() { String responseStr {amount: 9999999999.99, price: 0.1}; MapString, dynamic jsonData jsonDecode(responseStr); double amount jsonData[amount]; double price jsonData[price]; print(原始解析-金额$amount); // 输出10000000000.0 print(原始解析-单价$price); // 输出0.10000000142108548 }2.3 嵌套 JSON 解析案例实际项目主流结构真实接口大多采用嵌套 JSON 结构精度问题同样存在dartimport dart:convert; void main() { // 嵌套结构 JSON String nestedJson { code: 200, data: { orderId: 10086112233445566, totalAmount: 88888888.88, goods: [ { name: 理财产品, unitPrice: 123.45 } ] } } ; MapString, dynamic jsonData jsonDecode(nestedJson); MapString, dynamic data jsonData[data]; print(订单总金额${data[totalAmount]}); // 输出88888888.87999999 print(商品单价${data[goods][0][unitPrice]}); // 输出123.44999999999999 }2.4 误区解析后转 String 无法修复很多开发者误以为解析完成后调用toString()就能还原精度这是典型错误思路dart// 解析后再转字符串数据已经失真 String amountStr jsonData[amount].toString(); print(解析后转字符串$amountStr); // 误以为依旧输出 10000000000.0核心结论一旦被解析为 double精度就彻底损坏后续任何类型转换都无法还原原始数值。三、问题根源Dart JSON 解析机制Dart 内置jsonDecode有固定规则JSON 中的number类型无论整数、小数统一解析为 Dartdoubledouble 遵循IEEE 754 64 位双精度浮点数标准二进制存储特性决定无法精确表示大部分十进制小数。整个数据流拆解后端原始数字(字符串形态)→jsonDecode 转为 double→精度丢失→存入 DTO问题卡在解析环节Model 层、业务层都属于 “事后补救”为时已晚。四、金融行业规范与本方案定位4.1 金融行业标准规范真正的金融级行业规范服务端必须直接返回 String 类型金额、费率、余额、高精度数值后端必须返回100.00而非100.00这是最安全、最标准、最推荐的方案4.2 本方案适用场景本方案是后端无法改造、接口无法调整时App 侧的兜底适配方案适用于历史项目接口无法改动第三方接口无法协调跨团队协作成本高必须前端独立解决五、为什么必须在网络层处理三大核心理由只有网络层能拿到未解析的原始 JSON 字符串Dio 回调、Model 解析阶段数据已经完成 JSON 解码原始字符串被丢弃没有修改机会。解析动作不可逆浮点数精度丢失是永久性数据损坏不存在修复算法只能在解析之前干预。全局统一管控业务零侵入在网络层统一处理高精度字段无需逐个修改接口、逐个适配 DTO团队维护成本最低符合工程化规范。六、关键特性说明重要6.1 后端已返回 String → 不会重复加引号如果后端字段已经是字符串类型例如json{ amount: 99.99 }网络层不会做任何处理不会注入多余引号不会出现 99.99 格式错误。6.2 仅对数字类型自动加引号只有当字段是number 数字类型时才会自动包裹引号保证兼容性与安全性。七、主流解决方案横向对比目前业内针对 Flutter/Dart 浮点精度问题共有 4 类主流方案下表从改造成本、兼容性、侵入性、适用场景多维度对比方便选型表格解决方案实现思路优点缺点适用场景后端改造数字统一返回字符串接口侧将 number 改为 string 类型前端零处理最稳定需协调后端、历史接口改造成本高、跨团队沟通成本大金融规范首选、新项目业务层转 Decimal 计算解析为 double 后借助 decimal 库二次转换运算无需改动网络层解析阶段已丢精度转换无效侵入业务代码临时应急、非核心金额场景正则表达式替换 JSON拿到原始字符串后通过正则匹配数字并添加引号实现简单、代码量少无法兼容嵌套 JSON、转义字符、科学计数法容错率极低简单单层 JSON、内部测试接口本文方案Dio 转换器 状态机网络层拦截原始流状态机解析 指定字段白名单后台 Isolate 处理零后端改动、零业务侵入、兼容嵌套 / 转义字符、异常降级、性能优秀需熟悉 Dio 扩展与字符状态机逻辑后端无法改造时的线上项目推荐总结后端能改 → 优先让后端返回 String后端不能改 → 使用本方案。八、最终方案Dio 自定义转换器 状态机改写 JSON方案思路继承 DioBackgroundTransformer拦截响应原始流通过字符状态机扫描原始 JSON根据配置的字段白名单对指定字段对应的数值自动包裹双引号将数字转为字符串字面量借助Isolate后台解析避免主线程阻塞、卡顿 UIDTO 统一使用String类型接收全程保留原始精度。完整实现代码dartimport dart:convert; import dart:isolate; import package:dio/dio.dart; /// 高精度 JSON 解析转换器 /// 解决 Dart/Flutter JSON 解析浮点数精度丢失问题 class HighPrecisionJsonTransformer extends BackgroundTransformer { HighPrecisionJsonTransformer(); override FutureObject? transformResponse( RequestOptions options, ResponseBody responseBody, ) async { final fields options.extra[highPrecisionFields]; if (fields is List fields.isNotEmpty options.responseType ResponseType.json) { final rawString await utf8.decoder.bind(responseBody.stream).join(); try { final fieldNames fields.castString().toList(); // 后台 Isolate 执行解析不阻塞 UI return Isolate.run(() _parseHighPrecision(rawString, fieldNames)); } catch (e, _) { // 异常降级使用原生解析 return jsonDecode(rawString); } } return super.transformResponse(options, responseBody); } } // 在子 Isolate 中执行 JSON 处理逻辑 Object? _parseHighPrecision(String raw, ListString fields) { final fieldSet fields.toSet(); final safeJson _wrapFieldDecimals(raw, fieldSet); return jsonDecode(safeJson); } /// 状态机逐字符扫描为指定字段的数值添加引号 String _wrapFieldDecimals(String raw, SetString fields) { if (fields.isEmpty) return raw; final buffer StringBuffer(); final len raw.length; int i 0; String? lastKey; bool wrapNextDecimal false; while (i len) { final c raw[i]; // 跳过空白字符 if (c || c \n || c \r || c \t) { buffer.write(c); i; continue; } // 处理 JSON 字符串 if (c ) { final (content, end) _extractString(raw, i); buffer.write(raw.substring(i, end)); int j end; while (j len _isWhitespace(raw[j])) { j; } lastKey (j len raw[j] :) ? content : null; wrapNextDecimal false; i end; continue; } // 冒号标记下一个值是否需要转字符串 if (c :) { buffer.write(c); wrapNextDecimal lastKey ! null fields.contains(lastKey); lastKey null; i; continue; } // 匹配数字并添加引号 if (_isNumberStart(c) wrapNextDecimal) { final (numStr, end) _extractNumber(raw, i); final hasDecimal numStr.contains(.) || numStr.contains(e) || numStr.contains(E); buffer.write(hasDecimal ? jsonEncode(numStr) : numStr); wrapNextDecimal false; i end; continue; } // 其他符号重置标记 wrapNextDecimal false; if (c { || c [) { lastKey null; } buffer.write(c); i; } return buffer.toString(); } /// 提取 JSON 字符串内容 (String, int) _extractString(String raw, int start) { int i start 1; while (i raw.length raw[i] ! ) { if (raw[i] \\) i; i; } return (raw.substring(start 1, i), i 1); } /// 提取 JSON 数字内容支持负数、小数、科学计数法 (String, int) _extractNumber(String raw, int start) { int i start; if (raw[i] -) i; while (i raw.length _isDigit(raw[i])) { i; } if (i raw.length raw[i] .) { i; while (i raw.length _isDigit(raw[i])) { i; } } if (i raw.length (raw[i] e || raw[i] E)) { i; if (i raw.length (raw[i] || raw[i] -)) i; while (i raw.length _isDigit(raw[i])) { i; } } return (raw.substring(start, i), i); } bool _isWhitespace(String c) c || c \n || c \r || c \t; bool _isDigit(String c) c.codeUnitAt(0) 48 c.codeUnitAt(0) 57; bool _isNumberStart(String c) c - || _isDigit(c);九、项目接入使用步骤9.1 全局初始化 Diodartfinal Dio dio Dio(); dio.transformer HighPrecisionJsonTransformer();9.2 接口请求时声明高精度字段支持单层、嵌套结构内的同名字段只需填写字段名即可dartfinal response await dio.get( /api/order/info, options: Options( extra: { highPrecisionFields: [amount, price, rate, totalMoney, unitPrice] }, ), );9.3 DTO 模型使用 String 接收字段dartclass OrderDto { final String amount; final String price; OrderDto.fromJson(MapString, dynamic json) : amount json[amount], price json[price]; }十、方案效果对比❌ 原生解析9999999999.99→10000000000.0精度丢失✅ 网络层预处理9999999999.99→9999999999.99完整保留针对上文嵌套 JSON 案例处理后效果totalAmount: 88888888.88→ 解析为字符串数值完全无失真。十一、方案优势总结遵循金融规范后端能改优先让后端返回 String本方案为兜底适配安全兼容后端已返回 String 不会重复加引号零后端改造无需协调后端改接口前端独立完成适配零业务侵入仅修改网络层配置原有业务代码、逻辑无需改动状态机解析稳定可靠兼容嵌套 JSON、转义字符、科学计数法优于正则方案Isolate 后台处理不卡 UI大数据量响应也不会造成页面卡顿异常自动降级解析异常时切回原生逻辑保障线上可用性十二、已知限制当前实现基于字段名精确匹配暂不支持data.totalAmount这类嵌套路径写法若不同层级存在同名字段会统一做字符串转换该设计可满足绝大多数金融项目需求。十三、适用场景金融理财、支付钱包、电商结算、汇率换算、股票基金、GPS 经纬度等对小数精度要求极高的 Flutter 项目。十四、结尾本文方案是线上项目落地验证过的工业级解法彻底解决 Flutter/Dart JSON 解析精度顽疾。金融规范首选后端下发 String本方案为后端无法改造时的 App 兜底最佳实践。如果你正在开发金融类 Flutter 应用可直接复制代码接入使用。个人开源项目推荐专注 Android / Flutter 金融项目工程化、高精度规范实践https://github.com/brycegao/invest-record-prohttps://github.com/brycegao/android-finance-spec欢迎 Star、交流探讨
Flutter Dart JSON 解析必坑！金额精度丢失为什么必须在网络层处理？附工业级解决方案
一、前言做金融、支付、记账、电商类 Flutter 项目小数精度丢失是典型的隐形线上风险。 后端正常返回0.1、9999999999.99经过 Dart JSON 解析后数据直接失真0.1→0.100000001421085489999999999.99→10000000000.0线上对账异常、资产展示错误、结算金额偏差这些都属于 P0 级故障。网上多数文章只给出「DTO 用 String 接收、运算使用 Decimal 库」的结论但很少讲清楚一个核心问题为什么在 Model 层、业务层补救完全无效精度问题究竟发生在哪一步本文结合实际踩坑案例、原理分析、完整可运行代码告诉你精度丢失发生在 JSON 解析瞬间唯一根治手段是在网络层提前处理。二、精度丢失现场可直接复现案例2.1 基础浮点数运算问题dartvoid main() { double a 0.1; double b 0.2; print(a b); // 输出0.30000000000000004 }2.2 普通单层 JSON 解析场景业务高频踩坑dartimport dart:convert; void main() { String responseStr {amount: 9999999999.99, price: 0.1}; MapString, dynamic jsonData jsonDecode(responseStr); double amount jsonData[amount]; double price jsonData[price]; print(原始解析-金额$amount); // 输出10000000000.0 print(原始解析-单价$price); // 输出0.10000000142108548 }2.3 嵌套 JSON 解析案例实际项目主流结构真实接口大多采用嵌套 JSON 结构精度问题同样存在dartimport dart:convert; void main() { // 嵌套结构 JSON String nestedJson { code: 200, data: { orderId: 10086112233445566, totalAmount: 88888888.88, goods: [ { name: 理财产品, unitPrice: 123.45 } ] } } ; MapString, dynamic jsonData jsonDecode(nestedJson); MapString, dynamic data jsonData[data]; print(订单总金额${data[totalAmount]}); // 输出88888888.87999999 print(商品单价${data[goods][0][unitPrice]}); // 输出123.44999999999999 }2.4 误区解析后转 String 无法修复很多开发者误以为解析完成后调用toString()就能还原精度这是典型错误思路dart// 解析后再转字符串数据已经失真 String amountStr jsonData[amount].toString(); print(解析后转字符串$amountStr); // 误以为依旧输出 10000000000.0核心结论一旦被解析为 double精度就彻底损坏后续任何类型转换都无法还原原始数值。三、问题根源Dart JSON 解析机制Dart 内置jsonDecode有固定规则JSON 中的number类型无论整数、小数统一解析为 Dartdoubledouble 遵循IEEE 754 64 位双精度浮点数标准二进制存储特性决定无法精确表示大部分十进制小数。整个数据流拆解后端原始数字(字符串形态)→jsonDecode 转为 double→精度丢失→存入 DTO问题卡在解析环节Model 层、业务层都属于 “事后补救”为时已晚。四、金融行业规范与本方案定位4.1 金融行业标准规范真正的金融级行业规范服务端必须直接返回 String 类型金额、费率、余额、高精度数值后端必须返回100.00而非100.00这是最安全、最标准、最推荐的方案4.2 本方案适用场景本方案是后端无法改造、接口无法调整时App 侧的兜底适配方案适用于历史项目接口无法改动第三方接口无法协调跨团队协作成本高必须前端独立解决五、为什么必须在网络层处理三大核心理由只有网络层能拿到未解析的原始 JSON 字符串Dio 回调、Model 解析阶段数据已经完成 JSON 解码原始字符串被丢弃没有修改机会。解析动作不可逆浮点数精度丢失是永久性数据损坏不存在修复算法只能在解析之前干预。全局统一管控业务零侵入在网络层统一处理高精度字段无需逐个修改接口、逐个适配 DTO团队维护成本最低符合工程化规范。六、关键特性说明重要6.1 后端已返回 String → 不会重复加引号如果后端字段已经是字符串类型例如json{ amount: 99.99 }网络层不会做任何处理不会注入多余引号不会出现 99.99 格式错误。6.2 仅对数字类型自动加引号只有当字段是number 数字类型时才会自动包裹引号保证兼容性与安全性。七、主流解决方案横向对比目前业内针对 Flutter/Dart 浮点精度问题共有 4 类主流方案下表从改造成本、兼容性、侵入性、适用场景多维度对比方便选型表格解决方案实现思路优点缺点适用场景后端改造数字统一返回字符串接口侧将 number 改为 string 类型前端零处理最稳定需协调后端、历史接口改造成本高、跨团队沟通成本大金融规范首选、新项目业务层转 Decimal 计算解析为 double 后借助 decimal 库二次转换运算无需改动网络层解析阶段已丢精度转换无效侵入业务代码临时应急、非核心金额场景正则表达式替换 JSON拿到原始字符串后通过正则匹配数字并添加引号实现简单、代码量少无法兼容嵌套 JSON、转义字符、科学计数法容错率极低简单单层 JSON、内部测试接口本文方案Dio 转换器 状态机网络层拦截原始流状态机解析 指定字段白名单后台 Isolate 处理零后端改动、零业务侵入、兼容嵌套 / 转义字符、异常降级、性能优秀需熟悉 Dio 扩展与字符状态机逻辑后端无法改造时的线上项目推荐总结后端能改 → 优先让后端返回 String后端不能改 → 使用本方案。八、最终方案Dio 自定义转换器 状态机改写 JSON方案思路继承 DioBackgroundTransformer拦截响应原始流通过字符状态机扫描原始 JSON根据配置的字段白名单对指定字段对应的数值自动包裹双引号将数字转为字符串字面量借助Isolate后台解析避免主线程阻塞、卡顿 UIDTO 统一使用String类型接收全程保留原始精度。完整实现代码dartimport dart:convert; import dart:isolate; import package:dio/dio.dart; /// 高精度 JSON 解析转换器 /// 解决 Dart/Flutter JSON 解析浮点数精度丢失问题 class HighPrecisionJsonTransformer extends BackgroundTransformer { HighPrecisionJsonTransformer(); override FutureObject? transformResponse( RequestOptions options, ResponseBody responseBody, ) async { final fields options.extra[highPrecisionFields]; if (fields is List fields.isNotEmpty options.responseType ResponseType.json) { final rawString await utf8.decoder.bind(responseBody.stream).join(); try { final fieldNames fields.castString().toList(); // 后台 Isolate 执行解析不阻塞 UI return Isolate.run(() _parseHighPrecision(rawString, fieldNames)); } catch (e, _) { // 异常降级使用原生解析 return jsonDecode(rawString); } } return super.transformResponse(options, responseBody); } } // 在子 Isolate 中执行 JSON 处理逻辑 Object? _parseHighPrecision(String raw, ListString fields) { final fieldSet fields.toSet(); final safeJson _wrapFieldDecimals(raw, fieldSet); return jsonDecode(safeJson); } /// 状态机逐字符扫描为指定字段的数值添加引号 String _wrapFieldDecimals(String raw, SetString fields) { if (fields.isEmpty) return raw; final buffer StringBuffer(); final len raw.length; int i 0; String? lastKey; bool wrapNextDecimal false; while (i len) { final c raw[i]; // 跳过空白字符 if (c || c \n || c \r || c \t) { buffer.write(c); i; continue; } // 处理 JSON 字符串 if (c ) { final (content, end) _extractString(raw, i); buffer.write(raw.substring(i, end)); int j end; while (j len _isWhitespace(raw[j])) { j; } lastKey (j len raw[j] :) ? content : null; wrapNextDecimal false; i end; continue; } // 冒号标记下一个值是否需要转字符串 if (c :) { buffer.write(c); wrapNextDecimal lastKey ! null fields.contains(lastKey); lastKey null; i; continue; } // 匹配数字并添加引号 if (_isNumberStart(c) wrapNextDecimal) { final (numStr, end) _extractNumber(raw, i); final hasDecimal numStr.contains(.) || numStr.contains(e) || numStr.contains(E); buffer.write(hasDecimal ? jsonEncode(numStr) : numStr); wrapNextDecimal false; i end; continue; } // 其他符号重置标记 wrapNextDecimal false; if (c { || c [) { lastKey null; } buffer.write(c); i; } return buffer.toString(); } /// 提取 JSON 字符串内容 (String, int) _extractString(String raw, int start) { int i start 1; while (i raw.length raw[i] ! ) { if (raw[i] \\) i; i; } return (raw.substring(start 1, i), i 1); } /// 提取 JSON 数字内容支持负数、小数、科学计数法 (String, int) _extractNumber(String raw, int start) { int i start; if (raw[i] -) i; while (i raw.length _isDigit(raw[i])) { i; } if (i raw.length raw[i] .) { i; while (i raw.length _isDigit(raw[i])) { i; } } if (i raw.length (raw[i] e || raw[i] E)) { i; if (i raw.length (raw[i] || raw[i] -)) i; while (i raw.length _isDigit(raw[i])) { i; } } return (raw.substring(start, i), i); } bool _isWhitespace(String c) c || c \n || c \r || c \t; bool _isDigit(String c) c.codeUnitAt(0) 48 c.codeUnitAt(0) 57; bool _isNumberStart(String c) c - || _isDigit(c);九、项目接入使用步骤9.1 全局初始化 Diodartfinal Dio dio Dio(); dio.transformer HighPrecisionJsonTransformer();9.2 接口请求时声明高精度字段支持单层、嵌套结构内的同名字段只需填写字段名即可dartfinal response await dio.get( /api/order/info, options: Options( extra: { highPrecisionFields: [amount, price, rate, totalMoney, unitPrice] }, ), );9.3 DTO 模型使用 String 接收字段dartclass OrderDto { final String amount; final String price; OrderDto.fromJson(MapString, dynamic json) : amount json[amount], price json[price]; }十、方案效果对比❌ 原生解析9999999999.99→10000000000.0精度丢失✅ 网络层预处理9999999999.99→9999999999.99完整保留针对上文嵌套 JSON 案例处理后效果totalAmount: 88888888.88→ 解析为字符串数值完全无失真。十一、方案优势总结遵循金融规范后端能改优先让后端返回 String本方案为兜底适配安全兼容后端已返回 String 不会重复加引号零后端改造无需协调后端改接口前端独立完成适配零业务侵入仅修改网络层配置原有业务代码、逻辑无需改动状态机解析稳定可靠兼容嵌套 JSON、转义字符、科学计数法优于正则方案Isolate 后台处理不卡 UI大数据量响应也不会造成页面卡顿异常自动降级解析异常时切回原生逻辑保障线上可用性十二、已知限制当前实现基于字段名精确匹配暂不支持data.totalAmount这类嵌套路径写法若不同层级存在同名字段会统一做字符串转换该设计可满足绝大多数金融项目需求。十三、适用场景金融理财、支付钱包、电商结算、汇率换算、股票基金、GPS 经纬度等对小数精度要求极高的 Flutter 项目。十四、结尾本文方案是线上项目落地验证过的工业级解法彻底解决 Flutter/Dart JSON 解析精度顽疾。金融规范首选后端下发 String本方案为后端无法改造时的 App 兜底最佳实践。如果你正在开发金融类 Flutter 应用可直接复制代码接入使用。个人开源项目推荐专注 Android / Flutter 金融项目工程化、高精度规范实践https://github.com/brycegao/invest-record-prohttps://github.com/brycegao/android-finance-spec欢迎 Star、交流探讨
