指南教程

构建由服务器保管 API 密钥的 Flutter 货币转换器

通过自有代理加载带来源信息的汇率,构建有类型校验的 Flutter 转换器,显示加载、错误及缓存年龄,并仅在显示时舍入。

2026年9月29日 · 阅读约 8 分钟

移动 Flutter 应用属于公开客户端,不能包含 exchangerate.dev bearer 密钥。把密钥放在服务器 /api/fx 代理中,让 Flutter 请求 {from,to},并在有类型的模型中一起保存汇率、来源、市场时段和观测时间。

  • 下载的 Dart 文件调用你自己的代理,应用不携带 exchangerate.dev API 密钥。
  • 响应模型在显示前验证汇率和 data_updated_at。
  • 用户可查看加载状态、HTTP/格式错误、来源、市场时段和缓存年龄。
  • 显示时使用指定小数位,代码仍保留未舍入的 API 数值。
  • 参考汇率适合估算和显示;结算由负责的支付服务商处理。

让服务器保管凭据

服务器路由接收 from 和 to,添加 Authorization: Bearer $EXCHANGERATE_API_KEY,调用 /v1/latest/{from}?symbols={to},并只返回应用所需字段。将密钥保存在服务器环境中。应用通过 --dart-define=FX_PROXY_BASE_URL=… 接收代理 URL,始终不会收到上游密钥。

proxy contract · response
GET /api/fx?from=USD&to=EUR{"from":"USD","to":"EUR","rate":0.9245,"source":"live","market_session":"open","data_updated_at":"2026-09-29T10:00:00Z"}

添加 HTTP 依赖

创建 Flutter 应用,将当前 http 包加入 pubspec.yaml,把完整的 Flutter 转换器保存为 lib/main.dart。运行 flutter run --dart-define=FX_PROXY_BASE_URL=https://your-app.example/api/fx。下载最小 Node 代理,在服务器环境设置 EXCHANGERATE_API_KEY,使用 Node 20 或更新版本运行 node flutter-currency-converter-proxy.mjs。它监听回环地址端口 8787,供本地测试。连接设备前,应通过你自己的、带身份验证和请求限制的 HTTPS 后端提供访问。代理验证币种和金额、转发密钥,并只返回所需的有类型报价字段。客户端使用标准 Material 组件及 FxQuote 模型。Flutter 官方网络请求教程介绍了依赖设置和请求方式。

显示前验证汇率

模型拒绝缺失、非正数、非有限值或非数字的 rate,以及缺失的 data_updated_at,避免 HTML 错误页、代理缺陷或空 JSON 进入换算结果。客户端还设置十秒请求超时,并显示非 2xx 状态。

Dart · typed response shape
class FxQuote {  final String from;  final String to;  final double rate;  final String source;  final String marketSession;  final DateTime dataUpdatedAt;}

显示加载、错误和数据时间

请求期间,页面禁用按钮并显示进度指示;代理失败时显示可读错误。成功后显示金额、汇率、来源、市场时段、观测时间、应用缓存年龄(自设备获取响应以来的时间)和观测年龄(自 data_updated_at 以来的时间)。用户可以判断数据是交易日内的实时观测,还是每日参考值。

只对显示值舍入

示例支持的币种中,JPY 显示 0 位小数,USD、EUR、GBP、IDR 显示 2 位;汇率显示 6 位以便阅读。这只是显示层舍入。保留解析后的原始数值,在生产会计边界使用十进制或定点计算;不要把二进制浮点显示值当作结算记录。

移动应用中的凭据可被读取

代码混淆、编译期常量和私有 Flutter 仓库都无法保证已发布应用中的 API 密钥保密。代理是设计的一部分,不是可有可无的加固措施。

测试用户使用流程

使用测试代理响应运行应用,再验证超时、HTTP 401/429、无效 JSON、缺失汇率和过期 data_updated_at。Flutter 各平台网络设置、TLS 和代理部署仍需通过真机或模拟器检查;下载文件是可运行的客户端示例,不是已托管的代理服务。

仅供参考的汇率

将结果用于换算估算、显示和分析。支付服务商或受监管系统必须获取并保存自己的可执行报价和结算记录。

常见问题

Flutter 可以直接调用 exchangerate.dev API 吗?

公开应用可以访问匿名评估端点,但不能内置生产 API 密钥。使用账户密钥时,应通过服务器代理访问。

示例中的缓存年龄是什么意思?

应用缓存年龄是设备加载响应后经过的时间;观测年龄从 data_updated_at 开始计算。刚获取的响应也可能包含较早的每日或休市观测,应同时显示两者。

toStringAsFixed 会修改 API 汇率吗?

不会,它只格式化显示文本。保留数值用于应用逻辑;需要准确金额运算时,采用合适的十进制策略。

可以用此转换器结算付款吗?

不可。它提供的是用于估算和显示的参考数据,而非可执行的结算报价。

继续阅读

从免费API密钥开始

免费套餐每月提供5,000次请求。无需信用卡。

获取免费密钥