请教一个涉及前向兼容的 API 设计问题

[xFrank]

背景：
我们提供一个 SDK ，有很多 API 供上层应用使用。每次 API 变更都要考虑前向兼容，不能影响已有应用（否则代价巨大）

问题： 假设我有一个 API ，设为 DoA ，当 DoA 出现异常的时候，会通过另一个回调函数 OnError(err)返回错误信息给上层应用。 假设前期的错误码回调设计是这样的（ err 是个结构体，包含 code 和字符串）：

{1001, "原因 1"},
{1002, "原因 2"},
{1003, "原因 3"}

最近有部分用户提出来，部分错误码设计不合理：原因 2 太粗，需要细化为原因 2a ，2b ，2c 。需求是合理的。

那这个时候整个 OnError 的错误码回调应该如何设计呢？（即能精细化错误码，又要保证前向兼容） 当前想到的几个方案：

方案 1： 直接新增 code 和错误码字符串，

{1001, "原因 1"},
{1002, "原因 2"},
{1003, "原因 3"},
{10021, "原因 2a"},
{10022, "原因 2b"},
{10023, "原因 2c"},

问题：会导致原来只判断 1002 的应用不兼容

方案 2： 新增 code 和错误码字符串，当出现 2a 导致的错误时，回调两次，把 1002 和 10021 都回调一下 问题：上层应用不一定能接收两次回调，或者可能导致上层应用出现一些时序相关的奇怪问题

方案 3： 不新增 code ，通过不同的字符串来标识精细化的错误信息。类似这样：

{1001, "原因 1"},
{1002, "原因 2a"},
{1002, "原因 2b"},
{1002, "原因 2c"},
{1003, "原因 3"},

问题：对开发者不太友好，因为他还需要去解析字符串。。。

大家看下是否有更好的设计？

[esee]

好麻烦，就算我提供了兼容的 api ，也不知道使用者对返回的结果是怎么使用和判断的，可能又会引发问题。
所以涉及到返回结果数据结构需要变动的话，我都是直接接口 V1 ，接口 V2.。。这样写新的。。

[BiChengfei]

就 subcode 方案，我也是这个意思

[ryanking8215]

为啥不能 {1004: "2b"}

[dddd1919]

设计 APIv2 ，用新设计的 code ，然后给 APIv1 打上 deprecated ，备注迁移说明

[cowcomic]

如果结构体就是发出来这个样子，可以改成下面的形式
```
{1002, "原因 2b", "errorCodes": [1002, 100202], "msg": "原因 2b"}
```
1002, "原因 2b" // 这部分就给原来的系统用

"errorCodes": [1002, 100202], "msg": "原因 2b" // 新系统用这部分，原来系统如果能迭代的话，逐渐改为这种
"errorCodes": [1002, 100202] // 这个结构留着以后细化 code 用

如果新结构想再增加扩展性，不同 codes 不同 msg ，外面再封一层数组

想再再再增加扩展性，参考 Java 的 Exception 对象

[dyllen]

像楼上说的在原来的基础上增加子级错误码和消息，例子有支付宝也是这样干的，有两级，我接过好几个支付相关的接口都是如此。

[xFrank]

@cowcomic 尝试下这个，感谢