大家好，我是隐墨星辰，今天和大家简单聊下返回码映射存在哪些坑，以及如何避坑。
我在支付行业呆了十来年，和返回码映射导致的线上生产问题交手无数次，有很多是因为影响用户体验，也有一些直接导致了线上资损，所以有必要开一篇小文聊一下。
1. 返回码还是错误码
有些人喜欢用"返回码"，有些人喜欢用"错误码"。两者本质相同，都是用于标识通信或交易的状态。但我更倾向于使用"返回码"，因为它不仅涵盖错误状态，还包括成功状态，而成功并非错误，所以使用"返回码"更为合适。
2. 返回码的本质
我很喜欢探寻事务的本质，那么返回码的本质是什么？我觉得是解决2个问题：
- 标识单一系统内的业务处理结果： 在一个单一系统内，如何表达业务处理的结果，比如参数不对，余额不足，还是成功等。
- 完成异构系统或应用之间的处理结果同步： 在多个系统之间如何同步业务处理的结果，比如渠道的结果同步给支付平台的网关系统，网关系统同步给支付引擎等。
3. 返回码最核心的关注点
返回码最核心的关注点也只有2个：
- 同一系统 内定义是否足够清晰明确。减少歧义，减少误解。
- 异构 系统或应用之间的映射是否足够准确。映射不好，轻则影响用户体验，重则有资损。
4. 曾经碰到过的坑
踩过的坑很多，大致可以归为以下几类：
- 对客映射不准确，导致用户持续重试失败，影响用户体验。比如"余额不足"或"风控不过"，返回给用户"系统异常，请重试"，有些用户就疯狂地重试。
- 外部渠道没有明确成功或失败，内部映射成明确成功或失败 ，造成资损。比如：
-
- 支付同步请求渠道响应还没有回来，发起了查询，查询返回"订单不存在"，直接推进失败，但最后银行扣款成功。
- 退款同步请求渠道响应返回"系统异常"，直接推进到失败，但最后银行退款成功。
- 外部渠道有双层返回码，没有做完整判断。比如第1层只表示接口是否成功（通信层面），第2层才是表示业务是否成功，但是只判断了接口层面，就推进了内部订单的业务状态。
- 返回码制定过于笼统或太细。
5. 最佳实践
5.1. 基本原则
- 制定统一返回码规范：在团队或公司层面制定统一的返回码规范，明确各个返回码的含义，确保各模块一致性。
- 严格遵守返回码定义 ：研发人员在编码时，应严格按照规范返回对应的返回码，确保返回码与实际状态匹配。明确成功才推进成功，明确失败才推进失败，其它全部按"未知"处理。
- 流入到平台的（支付、充值等），谨慎映射到成功。从平台流出的（提现，代发等），谨慎映射到失败。
5.2. 三级返回码体系
外部商户对接支付平台，支付平台内部有自己的业务处理，同时还对接了外部的很多渠道，所以需要管理三套返回码：
- 提供给商户OpenAPI使用的返回码：这块可以直接参考微信支付、支付宝等机构的门户网站。
- 内部各应用使用的标准返回码：用于内部业务的处理。
- 渠道返回码：外部渠道提供的返回码，每个渠道都不一样，需要映射到内部标准返回码。
为什么需要三层？主要有3个原因：
- 内部应用使用的标准返回码需要精确，便于内部系统运行的监控。
- 给商户OpenAPI的返回码需要业务语义明确，但不能过于精确。比如内部出现"卡的有效期不正确"，对外则是"卡号或持卡人或有效期不正确"，避免轮询攻击。
- 外部渠道返回码不能全部一对一映射到内部，因为外部渠道太多，容易膨胀。
5.3. 商户OpenAPI返回码设计
这部分建议直接参考微信支付、支付宝或者ISO20022标准，这几家代表了行业的最高水准。
5.4. 内部标准返回码设计
支付平台内部也分了不同域，建议使用一个共同的规范，比如：RS+子系统编号+错误级别+具体返回码。具体如下图所示：
说明：
1-2位：固定值RS，Result缩写。
3-5位：子系统编号。比如001：收银支付，002：会员等。可方便定位哪个系统出的问题。
6位：错误类或等级。比如：0：正常，1：业务级异常，2：系统级异常。
7-9位：各业务线自己定。比如：1xx：参数相关，2xx：数据库相关，3xx：账户状态/Token状态相关等。
这样的好处在于，每个子域或子系统既有全局的规范，又有自己的灵活性，减少沟通成本。
5.5. 渠道返回码映射
每个渠道的返回码都是不一样的，所以需要设计外部渠道返回码映射到内部标准返回码。需要遵守几个原则：
- 只有明确成功，才能映射到成功。
- 只有明确失败，才能映射到失败。比如渠道返回：订单不存在，或者系统异常，不能直接映射到失败，因为有可能会成功。
- 涉及个人敏感信息或内部系统敏感信息的，需要转成模糊返回码和描述出去，不能给最终用户展示精确信息。比如内部一个系统宕机，不能直接把异常抛出去。有效期错误也需要映射成"卡号或姓名或有效期不正确"。
- 与敏感信息无关的，越准确越好，避免用户无谓的重试。比如余额不足，就不要映射成"系统异常，请重试"。
具体的技术实现，通过使用映射表就足够，加到缓存中，增加运算速度。如果找不到映射关系，就全部转到一个默认的返回码上面，同时对这个默认返回码做监控，定期把这些没有做映射的返回码映射到正确的返回码上面去。避免应该把类似"余额不足"映射成了"系统异常请重试"的场景。
5.6. 返回码监控与告警
大部分团队都会监控成功率，只有少数团队会监控返回码或定期分析返回码。然而当交易量足够大时，成功率的波动可能只有0.5%，很难看出异常，而如果去分析返回码，则可以快速看出并定位问题。
一般来说，有几个建议：
- 实时监控返回码的突变异常。比如：最近10分钟，某个返回码突然增加50%，或者比明天突然增加50%等。都需要介入看看。
- 定期观察返回码曲线表。如果某个返回码连续多天持续在上升，一般都是有问题的。
- 建立返回码全链路映射大盘。比如渠道返回"余额不足"或"风控不通过"，映射到用户展示"系统异常，请重试"，那就有问题。而且类似这种情况还非常常见。
- 定期分析用户支付行为。以前在分析用户行为时，发现同一用户重试了20多次，最后排查发现，就是返回码映射不准确，导致用户无谓的重试。
7. 结束语
卷用户体验和成功率时，往往需要于细微处见真章，而返回码的设计和映射就是如此。做得不好，轻则影响用户体验，重则资损。
希望对大家在设计返回码映射时有所启发，也欢迎点赞转发。
这是《图解支付系统设计与实现》专栏系列文章中的第（48）篇。 欢迎和我一起深入解码支付系统的方方面面。