3. 接口兼容性基础

在核心银行系统的接口适配层设计中，兼容性不是一个“有或没有”的开关，而是一组需要被精确定义、度量和治理的工程属性。很多接口事故并非源于技术能力不足，而是团队对“兼容”二字的理解不一致：一方认为只是字段没删，另一方却认为业务语义已经改变。本节将兼容性拆解为四个可讨论的维度：定义、方向、层次与等级。

一、兼容性的本质定义

接口兼容性，指的是当接口的提供方或消费方发生变更时，双方仍能按照原有约定完成交互、且不产生非预期结果的能力。它包含三个隐含条件：契约可识别（双方对报文结构、字段含义、协议行为有共同认知）、行为可预测（调用结果符合既有业务预期）、失败可界定（不兼容时能明确报错，而非静默产生错误数据）。

在核心银行场景中，兼容性尤其敏感。账户、余额、交易流水等接口往往被柜面、手机银行、信贷、风控、监管报送等多方消费，任何一次“看似无害”的字段调整，都可能在下游引发对账差异或监管口径偏差。因此，兼容性必须被显式声明，而不是默认假设。

二、向前兼容与向后兼容：方向决定责任

兼容性具有方向性，这是最容易被混淆的一点。我们以“新版本”为参照来定义：

• 向后兼容（Backward Compatible）：新版本接口能够正确处理旧版本消费方的请求。即“新服务端兼容老客户端”。这是核心银行系统升级时最常追求的目标，因为客户端（如柜面终端、老旧渠道）往往无法同步升级。
• 向前兼容（Forward Compatible）：旧版本接口能够容忍新版本消费方发来的、包含新增字段或扩展语义的请求。即“老服务端兼容新客户端”。在灰度发布、双跑并行阶段尤为关键。

两者并非对称。向后兼容通常通过“保留旧字段、新增字段可选、默认值兜底”实现；向前兼容则要求旧服务端具备“忽略未知字段、不因多余参数报错”的宽容策略。核心银行接口适配层往往需要同时满足两个方向，才能支撑平滑演进。

三、语义兼容与协议兼容：层次决定风险

兼容性还分为两个层次，二者常被混为一谈，但风险等级完全不同。

维度	关注点	典型变更	风险特征
协议兼容	报文结构、字段类型、传输格式、编码、超时与重试约定	新增可选字段、字段长度扩展、HTTP 状态码调整	易检测，通常可通过 Schema 校验和联调发现
语义兼容	字段业务含义、单位、精度、枚举取值、计算口径、时序约束	金额单位由“分”改为“元”、状态码含义扩展、余额口径调整	难检测，可能静默产生错误数据，引发对账与监管问题

协议兼容是“形”，语义兼容是“神”。核心银行接口中，最危险的不是字段缺失导致的报错，而是字段存在但含义漂移。例如，某接口的 balance 字段原本表示“可用余额”，升级后改为“账面余额”，协议上完全兼容，语义上却已不兼容，下游若直接用于风控决策，后果严重。

四、兼容性等级划分：从 L0 到 L4

为了让兼容性可度量、可治理，建议在适配层设计中引入分级模型。等级越高，变更自由度越大，但对消费方的约束也越强。

1. L0 不兼容：删除必填字段、修改字段类型、改变协议方法。消费方必须同步改造，否则调用失败。
2. L1 协议兼容：仅新增可选字段或扩展枚举，旧消费方可忽略新字段继续工作，但语义未经验证。
3. L2 语义兼容：在 L1 基础上，确认所有既有字段含义、单位、精度、时序均未改变，旧消费方行为完全可预测。
4. L3 双向兼容：同时满足向后与向前兼容，新旧消费方与新旧服务端可任意组合，支持灰度与双跑。
5. L4 自适应兼容：适配层具备版本协商、字段映射与语义转换能力，可在运行时根据消费方版本动态适配，是核心银行接口治理的理想目标。

# 适配层版本协商配置示例（YAML 片段）
compatibility:
  level: L3
  version_routing:
    - consumer: "teller-v1"
      target: "core-account-v2"
      mapping: "legacy_balance_to_available"
    - consumer: "mobile-v3"
      target: "core-account-v2"
      mapping: "native"
  unknown_field_policy: "ignore"   # 向前兼容策略
  missing_field_policy: "default"  # 向后兼容策略
  semantic_guard:
    - field: "balance"
      unit: "CNY_CENT"
      forbid_silent_change: true

五、案例与复盘：一次“兼容”引发的对账差异

某银行在升级账户查询接口时，将返回报文中的 status 字段由“0/1”扩展为“0/1/2/3”，并新增了 statusDesc。协议层面完全向后兼容，旧消费方仍能解析。但下游对账系统此前用 status == 1 判断“正常账户”，而新版本中“1”被重新定义为“冻结”，导致大量正常账户被误判为异常，日终对账出现巨额差异。

复盘结论有三点：其一，枚举扩展属于语义变更，必须走语义兼容评审；其二，适配层应提供字段映射与语义转换，而非让消费方直接面对原始枚举；其三，兼容性等级应作为发布门禁，L1 变更不得直接进入生产。这正是将兼容性从“口头共识”升级为“工程约束”的价值所在。

理解兼容性的定义、方向、层次与等级，是设计适配层的前提。只有先明确“兼容什么、对谁兼容、兼容到什么程度”，后续的版本路由、字段映射与灰度策略才有可靠的判断依据。