扫码点餐这个赛道国内早就卷成了红海Java后端做一套本地版本并不难难的是把它改造成一个真正意义上的国际版。我这次接手的系统就是把一套原本只面向国内单一市场的扫码点餐系统重构成支持多语言、多币种、多支付渠道的跨境版本整个过程踩坑不少但做完以后对整个支付体系的认知也彻底不一样了。这篇文章就把整个项目拆开讲清楚从架构设计、多语言方案、支付抽象到回调幂等、对账补偿、沙箱验证全部梳理成可以直接参考的实操记录。适合正在做出海餐饮SaaS、跨国门店点餐系统、或者想了解支付集成细节的Java后端开发者阅读。不管你只是写Demo还是真的要上线这套设计思路都能用得上。1. 项目整体设计与思路拆解1.1 为什么国际版不是简单加几个翻译文件一开始产品提需求时说国际版嘛就是把页面上中文改成英文再加一个PayPal不就行了。真做起来才发现这句话里藏着至少三个层次的改动语言只是表象币种和支付渠道才是核心再往下是订单生命周期和结算逻辑的连锁反应。单说点餐这个动作国内用户扫码之后看到的是菜品列表、价格、购物车、结算。但国际版场景里同一个门店可能有本地顾客、游客、外籍常客他们看到的语言不一样显示的价格币种不一样最后付款时能用的支付方式也不一样。有人想用本地银行转账有人习惯刷信用卡还有人只有某个电子钱包。更复杂的是订单价格是按A币种菜单位价计算的但用户可能想用B币种的钱包支付这中间就涉及到汇率换算、四舍五入、以及支付渠道是否支持跨境结算等一系列问题。所以国际版的本质是把点餐-支付这条主链路里的每一个环节从单一国家假设里拆出来变成可配置、可插拔的模块。这也是我在项目里做的第一个决定先不写业务功能先把国家/区域作为顶层维度设计进来。1.2 整体架构配置驱动而非代码直写我的方案是把系统按区域、语言、币种、支付渠道四个维度做配置化。每个维度都是独立的区域决定可用币种和合规要求语言决定文案和数字格式币种决定计价和结算方式支付渠道决定用户最终付款的通道。架构上分了四层接入层扫码入口桌码/台码里携带门店ID、桌号、会话token。这一层跟国际版关系不大但token设计上要注意支持跨语言环境下的重新拉取。业务层菜单浏览、购物车、下单、订单状态机。所有业务数据在主语言比如英语下存储同时保留多语言副本而不是直接把中文硬编码到业务表里。支付层统一支付抽象接口对抗不同支付渠道的差异。这是整个项目改动最大的地方。数据层订单表、支付流水表、汇率表、语言资源表、幂等记录表。这些表都要加上区域和语言维度。为什么用配置驱动因为不同市场的上线节奏不一样。某区域上线时只需要新增一个区域配置、两个语言资源文件、一个支付渠道适配器不需要改核心代码。这套思路在项目中期被验证得非常香——后来新增一个本地钱包渠道时我一个人一天就完成了从适配器到联调的全流程。1.3 核心链路下单、支付、回调、对账扫码点餐的核心链路是这样的顾客扫桌上的二维码拿到店铺ID、桌号、会话token。前端拿着token去拉取菜单和店铺配置按当前语言展示。顾客加购下单点击结算后端生成待支付订单。订单状态由用户选择的支付渠道决定跳转方式有的拉起收银台App有的跳转到H5支付页有的展示付款码。支付渠道异步回调后端验签、修改订单状态、通知前端刷新页面。定时任务扫描超时未支付的订单做关闭处理扫描支付成功但回调未到的订单做主动查单补偿。这条链路本身不复杂复杂的是第4步和第5步在多语言、多币种环境下所有细节都会被放大。比如回调里返回的金额、币种、支付时间都要经过一套统一的转换逻辑才能落到订单上不能想当然地直接用渠道返回的原始字段去更新订单不然汇率波动、小数位数差异就能把对账搞崩。2. 多语言与多币种方案设计2.1 国际化不只是语言资源文件语言回退与动态切换很多人以为i18n就是放几个messages.properties对不起那只是最基本的。扫码点餐场景中语言问题发生在三个层面后端文案错误信息、状态提示、邮件通知。这些用标准的ResourceBundle机制就能解决。菜品和规格数据菜品名称、描述、规格选项比如大份/中份/小份这些存在数据库里不是静态资源文件。处理方案是给菜品表加一个多语言文案子表每个菜品在每种语言下都有一条文案记录没有记录时回退到主语言。数字和日期格式1,234.56和1.234,56在不同语言环境代表完全不同的金额。这个问题坑了我很久后面单独说。语言回退是三件事用户首选语言 - 浏览器/App语言 - 默认英语。回退不能满足时用主语言兜底并加一个标志位让前端知道当前显示的是回退文案可以提示用户该内容暂时只支持英语。动态切换方面我用的方案是前端把当前语言编码放到请求头里后端用拦截器解析后放入ThreadLocal然后业务代码里所有文案取值都走一个LocalizationUtil。这个工具类读数据库多语言表优先取请求语言没有就取回退语言。实测下来性能影响可以忽略但要注意缓存问题——语言表有更新时必须主动刷新缓存。2.2 金额与精度钱永远不要用double这是老生常谈但国际版场景下犯错的代价更大了。国内版本可能所有价格都在同一个币种下用分还是用元反正一致就行。国际版一旦出现汇率转换任何浮点数误差都会被放大而且支付渠道只认原始币种的小数位。我定的规则数据库所有金额字段用DECIMAL(18,2)统一存储存储的是订单计价币种的主单位金额。Java代码里所有金额计算一律使用BigDecimal禁止double和float。与支付渠道交互时按渠道要求的单位传递有的渠道要分有的渠道要厘有的要元。适配器内部负责转换业务层不感知。每个币种定义一个货币元数据小数位数、默认舍入模式、最小支付单位。例如日元没有小数港币两位小数有些中东货币三位小数。BigDecimal的构造陷阱也踩过new BigDecimal(0.1)会得到一堆精度垃圾一定要用new BigDecimal(0.1)或BigDecimal.valueOf(0.1)。这两种我都遇到过后来索性在工具类里统一封装金额创建入口禁止业务代码直接new BigDecimal。2.3 时区与日期格式在谁的时间里结账多语言系统里时间问题比金额问题更隐蔽。一个订单可能有多个时间概念门店当地时间、顾客所在时区时间、支付渠道回调时间、系统服务器时间。我不建议把时间都转成UTC然后存字符串那样查询报表时很难受。我的方案数据库一律存储UTC时间用TIMESTAMP WITH TIME ZONE或统一约定存UTC时间运算在服务端完成。订单表额外存一个门店时区字段注意这不是一次性的因为顾客可能跨时区下单。展示给顾客的时间由前端使用其本地时区渲染但订单的结账时间出餐时间等业务时间统一用门店时区定义。支付渠道回调返回的时间先解析成UTC再转成订单所属时区的本地时间避免直接用字符串拼接。这个方案在测试时看起来繁琐真正上线后才发现它的价值因为跨境顾客完全不会困惑门店看报表时也是回到自己熟悉的时间语义。2.4 汇率处理计价、结算与展示的三角关系国际版扫码点餐里汇率是最容易出逻辑混乱的地方。一个订单流程中汇率可能出现在三个位置菜单展示汇率用户看到的菜单位价可能是本店币种标价也可能是用户自己选定的币种折算价。这个汇率仅用于展示不影响订单计价。订单计价汇率顾客下单时订单金额锁定为某个币种。比如菜单位价是美元顾客选择用欧元支付订单金额就是按当时汇率换算的欧元金额。这个汇率要固化在订单表里不能实时浮动。对账结算汇率餐企最终跟门店结算时使用的汇率跟顾客看到的无关走财务模块。我封装了一个ExchangeRateService职责是提供实时汇率查询、在订单生成时固化汇率快照、在展示时只读换算。注意汇率快照本身要存储换算时间、来源、买入价卖出价方便后续审计。我踩的一个坑是以为可以从支付渠道返回的结算金额倒推汇率结果发现渠道的汇率包含手续费跟订单固化汇率差了一截导致对账时产生了金额差异。最后解决方案是订单表永久保存订单币种金额、支付币种金额、汇率、手续费明细对账时逐一比对而不是用总额除以汇率去猜测。3. 支付网关的适配与集成3.1 支付渠道差异分析四种支付形态国际版支付渠道的形态差异比国内大得多。粗略可分成四类扫码支付形态顾客扫描商家提供的二维码或者商家扫描顾客的付款码。这是国内主流在海外某些区域也存在但覆盖率没那么高。银行卡收单形态顾客在支付页填写卡号、有效期、CVV或者跳转到银行3D验证页面确认。这是海外最通用的形态涉及卡组织网络。钱包/转账形态顾客跳转到某个本地钱包App完成支付或通过银行转账、先买后付等方式。这类渠道区域性极强。统一收银台形态顾客在一个聚合网页上选择支付方式聚合服务商帮你完成后续逻辑。这种对商家开发量最小但定制能力受限。这些渠道的差异不仅体现在交互还体现在技术对接上签名方式、回调方式、退款方式、订阅机制各不相同。我花了很大篇幅做了一张对比表驱动力只有一个——统一抽象接口时要覆盖这些差异不能让某个渠道的特殊逻辑污染业务层。3.2 支付适配层把差异锁在接口背后我的核心抽象就三层public interface PaymentAdapter { PayResult createPayment(PayRequest request); PayResult queryPayment(String outTradeNo); void handleCallback(CallbackRequest request); RefundResult refund(RefundRequest request); String getChannelCode(); boolean supportsCurrency(String currency); }PayRequest里包含订单号、金额、币种、顾客语言、区域、同步跳转地址和异步回调地址。PayResult统一返回支付跳转参数、支付状态、渠道流水号。实现类根据渠道差异化填充细节比如某国内扫码渠道的签名方式A需要证书加密回调报文格式是XML。某海外卡组织的收单服务签名方式B需要消息签名回调报文是JSON。某个本地钱包渠道签名方式C回调里会有多层嵌套和自定义加密字段。这些差异全部封装在各自的适配器里业务层只面对接口。业务层不用关心当前用户在用什么渠道它只需要根据渠道code从注册表里取适配器然后调用统一方法。还需要一个工厂或者注册管理器把所有适配器按渠道code注册进一个Map启动时校验是否有渠道缺失。我还做了一件事createPayment返回值里同时携带前端需要展示的支付方式名称这个名称本身走多语言资源确保顾客看到的支付方式文案也是本地化的。3.3 核心实现下单、回调验签、状态流转以一个典型流程为例顾客在澳大利亚门店扫码菜单以英语展示选择用银行卡支付。下单时后端创建订单初始化状态为PENDING_PAYMENT然后调用对应的银行卡收单适配器。适配器内部第一步调用支付网关的创建订单接口拿到一串跳转URL第二步把URL封装成PayResult返回第三步前端拿到URL后跳转到网关页面顾客完成付款。这里有一个细节跳转URL上经常会带着语言参数比如?langen-AU或?localede。支付网关能根据这个参数决定用户看到的支付页语言。所以适配器设计时这个参数必须从请求里透传过去。我给适配器加了一个LocalizedParameter字段由业务层填充适配器拼接到请求里。回调处理是整个支付集成最核心的部分。各渠道回调报文差异巨大但流程一致验签。用渠道公钥验签失败直接拒绝并记录日志。解析出订单号、渠道流水号、支付金额、支付币种。查询本地订单校验状态。如果订单已是PAID直接返回成功避免重复处理。幂等锁。用订单号加锁防止并发回调导致重复修改。更新订单状态为PAID写入支付流水记录渠道回调原始报文。触发后续业务动作比如通知门店、更新桌台状态。向渠道返回确认成功。每个步骤都可能出错。验签失败时我会先检查公钥是否正确、回调时间戳偏差、字符集问题而不是直接报警。幂等锁我用的方案是Redis分布式锁加数据库唯一索引双重保障因为极端情况下回调并发导致连接数打满时Redis锁虽然能挡住大部分重复请求但万一锁超时释放了数据库的唯一索引还能兜底。3.4 幂等、对账与掉单补偿支付集成的噩梦不是支付失败而是支付成功但系统没感知。我遇到最多的是这两种情况回调没有到达网络抖动、渠道侧bug、防火墙拦了。回调到达了但验签时由于时间偏差失败。所以必须有主动查单机制作为兜底。我的方案是定时任务每2分钟扫描状态仍是PENDING_PAYMENT且创建时间超过10分钟的订单对每个渠道调用queryPayment方法查询订单真实状态。查到已支付就补单查到已关闭就关单查询本身也有超时重试和重试上限防止把任务线程打爆。幂等设计里有一个关键点查询补单的写操作和回调的写操作要复用同一个paymentSuccess方法这个方法的内部逻辑必须是无论谁先执行结果一致。我通过唯一索引order_id channel_txn_no保证支付流水只有一条记录配合Redis锁确保只修一次订单状态。对账则是一条更长的链路每日跑批本地订单表金额 渠道侧当日账单金额。误差来源通常有手续费、退款、折扣、汇率差。这个项目里我把对账差异拆成四类已支付未入账、入账未支付、金额不一致、退款记录缺失。每一类都会生成对账异常单由财务或研发介入处理。4. 多语言支付无缝集成的实操细节4.1 点餐场景中的多语言边界菜品、规格、备注支付集成之前多语言的坑先出现在菜单数据上。菜品名称、描述、过敏原信息、规格标签、忌口备注全都要多语言。我建了一张dish_localization子表用dish_id locale做主键文案列存文本主语言永远是产品的核心语言比如英语。国际化子表的增删改走统一接口不允许开发直接改数据库。这里有个体验细节顾客提交的备注比如不要香菜是自由文本不会也不需要做多语言翻译但门店看到时必须能看懂。我的做法是提供一套常用备注标签体系顾客点选标签标签本身按多语言展示门店端则显示该标签对应的门店语言文案。自由文本备注走OCR翻译服务但这属于后期迭代超出本次支付集成的范围。支付环节里也到处是多语言比如支付方式列表的文案要展示Credit Card还是Kreditkarte取决于用户语言。我用一个PaymentMethodLocalization映射表key是渠道codevalue是各个语言下的展示名称。适配器返回渠道code前端根据用户语言取文案这样业务层跟语言彻底解耦。4.2 扫码链路与支付参数的完整传递二维码的内容设计也会影响多语言体验。一个桌码内容里至少要包含店铺ID、桌号、渠道来源、会话token、语言偏好。语言偏好从二维码里读出来还是从请求头里读出来我最终选择的是两种结合——二维码里写一个默认语言前端检测到浏览器语言时再覆盖。在支付环节PayRequest里需要传递一个cancelUrl参数顾客取消支付后跳转回来的页面。这个页面本身要做多语言化处理不然用户从英文支付页取消后跳回一个中文页面的菜单体验很割裂。我踩过这个坑所以后来设计支付结果页时特意要求前端在URL的query里带上语言参数。支付参数传递上另一个坑是callback地址不能经过任何重定向或者前置网关处理因为支付渠道要求回调地址是公网可直达的HTTPS地址任何中间层都可能改变报文体里面的某个参数导致验签失败。我们在生产环境还被CDN缓存坑过一次后来直接把核心回调接口排除在CDN缓存规则之外。4.3 货币符号与数字格式的三种坑国际版UI上最容易被忽略的是货币展示格式。同一个美元金额不同语言环境下习惯不一样英语$1,234.56德语区1.234,56 $日语¥1,235没有小数位如果只是简单地在金额前面硬拼货币符号一定有一批用户的看到的是错误格式。我的做法是把金额格式化交给前端后端只返回金额数字字符串币种代码由前端的国际化库根据当前语言环境生成格式化字符串。后端务必不要拼好符号再返回否则汇率转换和格式化逻辑会纠缠在一起。但有一种情况例外PDF小票、邮件通知、或者发给门店的系统推送。这种没有前端国际化的场景后端必须自己格式化。我封装了一个MoneyFormatter输入金额数字字符串和币种代码输出标准格式。测试用例覆盖了几十个币种包括阿联酋迪拉姆的三位小数、智利比索的整数币、以及某些主要货币符号和代码在不同语言下的展示差异。另外还有一个隐形坑某些币种代码跟货币符号有歧义。比如CAD加元和AUD澳元符号都是$前端如果只按符号展示顾客根本分不清到底扣的是哪国钱。所以支付页里我要求一律展示ISO货币代码符号只是辅助。4.4 多语言多币种的沙箱验证方案沙箱环境是整个项目里的隐形功臣。没有沙箱我不敢想象怎么验证多语言、多币种、多渠道的排列组合。我的沙箱验证步骤通过管理后台配置三个区域澳大利亚门店、新加坡门店、日本门店。每个区域配置不同币种和默认语言分别对应英语、英语/中文双语、日语。每个支付渠道在沙箱模式下配置一组测试密钥注意沙箱密钥和正式密钥严禁混用且环境隔离我见过有人把沙箱密钥带到生产环境引发大面积验签失败的事故。写一套e2e冒烟用例覆盖用日语下的订单能不能用新加坡钱包支付用美元计价的门店能不能收欧元这类交叉场景。用一个模拟回调工具手动修改回调报文中的金额字段验证验签失败时订单状态不变化。沙箱环境里最值钱的一点是它能验证出回调报文在真实的网络链路上是否丢字段、是否乱码、是否有签名时间偏差。比如某海外渠道沙箱的服务器时间是UTC本地时间跟它差了8小时我一开始没做时间窗口容忍导致所有回调验签都失败。这个教训帮我写出了一套统一的回调验签工具内部自动处理了时间窗口和时钟偏移。5. 常见问题与排查技巧实录5.1 金额对不上浮点精度、舍入模式和币种小数位先说结论所有的金额计算一律用BigDecimal起步就要规划好舍入模式。我遇到的实际案例是订单总额为12.345欧元这是三位小数的币种渠道要求以分为单位存储也就是1234.5分但整数分是1235还是1234取决于舍入模式。我们用的模式是RoundingMode.HALF_UP但某渠道默认用HALF_EVEN两边算出来不一样对账差了一分钱。解决方式是在订单表里增加一列amount_in_minor_unit直接存渠道要求的最小单位金额这样业务层不管舍入只是传递。但每次生成订单时都要明确使用统一配置的舍入模式这个配置存在币种元数据表里。另一个容易踩的坑是BigDecimal除以BigDecimal时如果不指定精度会抛ArithmeticException。所以我统一用divide(BigDecimal divisor, int scale, RoundingMode roundingMode)禁止使用无参除法。5.2 回调验签失败的三个源头回调验签失败最常见的原因按频率排序是字符集不一致。渠道用ISO-8859-1签名我们用UTF-8验签只要报文里含非英文字符签名必挂。时间戳偏差。渠道要求签名里的时间戳跟当前时间差不能超过5分钟但服务端时钟没有做NTP同步导致超时。拼接顺序错。有些渠道签名串是金额订单号渠道流水有些是订单号金额渠道流水顺序反了验签就失败。排查这三个问题的办法是把回调原始报文完整落库存档单独做一个验签调试页面可以粘贴报文、换字符集、换拼接顺序反复测试。这个调试页面在联调阶段救我无数次后来直接做成了生产环境的只读排查工具。5.3 超时未支付、取消、重复支付的状态处理状态机要严谨。我用的订单状态是PENDING_PAYMENT: 已下单未支付PAID: 支付成功CLOSED: 超时关闭或用户取消REFUNDING: 退款中REFUNDED: 已退款关键规则PENDING_PAYMENT在超时后不能直接变成CLOSED因为可能存在渠道已扣款但回调延迟的极端情况。我做的处理是超时任务里先调渠道查单查不到支付成功才关单。用户扫码重复支付同一订单时第二次支付请求直接返回订单已支付不允许重复扣款。这个校验必须在创建支付请求前执行而不是在回调阶段才判断。订单关闭后又收到回调这种场景要特殊标记。我建了一张late_callback_log表记录迟到的回调人工介入处理后续退款。5.4 多语言订单备注与支付小票的乱码与空白如果订单备注是自由文本多语言环境下API传输很容易出现乱码。原因通常是编码不一致——某个渠道回传备注字段时用了ISO-8859-1而我们数据库用的是UTF-8。解决方式是在系统入口统一加一个过滤器强制所有请求响应字符集为UTF-8。注意还要检查数据库连接串里的characterEncoding参数Java侧连接MySQL时如果漏了一样会乱码。另外支付成功后的电子小票上门店名称、菜品名称需要按门店语言展示但支付渠道的收据上是顾客语言。这个小细节在设计支付页时就要确认不能让渠道的默认文案直接展示因为它是基于渠道后台配置的通常没有做多语言。6. 从国际版支付集成中收获的经验这个项目的后半段几乎每一天都在验证一句话支付集成的复杂度不在代码量而在边界情况。多语言、多币种放进来后边界情况成倍增加而处理边界情况的核心不是更多if-else而是配置驱动统一抽象。我个人最受用的一个设计决定是不要让业务代码知道任何支付渠道的具体规则。所有渠道差异被锁死在适配器内部业务层只面对订单和统一接口。这样做的回报是巨大的——后来新增一个先买后付渠道时我只花了一个下午就完成了适配器、沙箱联调、回归测试三件事。还有一点想分享多语言支付集成的测试一定要用真实的多币种沙箱账号去测试模拟回调时故意改变金额字段验证验签和幂等是否可靠。这些测试用例要沉淀下来放在CI/CD里每次发布回归都跑一遍不然后面改任何一行支付代码都可能悄悄引入金额错位的问题。最后一个小技巧无论渠道文档声称支持多少种语言支付页上一定要有一个手动切换语言的入口不能只依赖浏览器检测。我遇到过不少用户浏览器默认语言是英语但实际习惯用德语看支付页。进去点别的入口之前用户就要能手动调整语言这一点做得好不好直接影响支付转化率。