批量操作接口的相关说明

批量操作接口的相关说明

批量操作指一个请求中携带多条记录或多个 List 元素。批量接口不保证原子性，一次请求可能部分成功、部分失败，业务必须逐条检查子错误码。

1. 接口分类

1.1 Generic 表批量接口

Generic 表批量请求主要由接入层拆分、转发到存储层，再聚合多个单记录响应返回客户端。

1.2 List 表批量接口

List 表批量请求都针对同一个大 key 下的多个元素，接入层透传给存储层，由存储层在一次请求中循环处理。

2. 通用限制

3. 返回码与结果读取

批量响应包含两层错误码，业务判断每个 key 是否成功时，应以分错误码为准：

总错误码和分错误码的关系：

proxy 对普通 Batch* 写类请求的回包规则：

因此，批量写接口的正确处理方式是：先遍历响应中每条 key 的分错误码，再决定该 key 成功还是失败。总错误码只用于判断整体流程状态，不能替代分错误码。需要控制 value 回带时，使用 SetResultFlagForSuccess / SetResultFlagForFail，详见 ResultFlag响应数据返回控制。

3.1 C++ TDR SDK 示例

C++ TDR SDK 完整示例（含 RecvResponse 主循环、FetchRecord 读分错误码、HaveMoreResPkgs 续包、ScanTimeout 超时兜底）以及对应的分包丢包处理思路，参见 响应分包和丢包处理说明 §3.2.1 Generic Batch 类。

3.2 C++ PB SDK 示例

C++ PB async 的批量写接口通过 TcaplusPbCallback 回调返回结果，三个回调的含义如下：

C++ PB SDK 完整示例（含 OnRecv 累积分错误码、OnError 处理 API_ERR_NO_MORE_RECORD 结束哨兵、OnTimeout 兜底、OnFinish 统一收口）以及 m_result 哨兵覆写思路，参见 响应分包和丢包处理说明 §3.2.1 Generic Batch 类。

3.3 Go SDK 示例

Go SDK 提供两套接口：

高级用法内部就是封装了底层 NewRequest + DoMore，并自动把每条记录的分错误码、version 按下标回填到 opt.BatchResult / opt.BatchVersion，再把任一子失败聚合成接口级 err。两套接口最终走同一条协议链路，分错误码语义一致；但接口返回值的含义不同：高级用法是”全成功才返回 nil”，底层用法是”SDK 层无错就返回 nil”。

Go SDK 完整示例（高级用法 DoBatchGet + 底层用法 NewRequest / DoMore）以及分错误码、丢包识别、超时兜底的处理思路，参见 响应分包和丢包处理说明 §3.2.1 Generic Batch 类。

4. 分包行为

4.1 分包规则

4.2 强烈建议：所有批量接口都手动开启分包

⚠️ “不允许分包” 是历史遗留的畸形设计：响应数据超过 256 KB 时，会出现只返回部分记录、ListGetBatch 提前截断等”静默丢数据”现象，但接口仍可能返回成功，业务很难感知。

为了好记，请把下面这条作为统一规则：

• 任何批量接口、任何 SDK、任何表类型，调用前都手动设置 SetMultiResponseFlag(1)，由 SDK 负责收齐所有分包；
• 不要去记忆”哪个 SDK / 哪个命令字默认是否允许分包”，记一条规则比记一张表更可靠。

各 SDK 中开启分包的入口：

4.3 不开启分包时各接口的具体影响

不开启分包并不会让 SDK 报错，但响应数据过大时会发生静默截断，下表列出典型场景：

综上，所有批量接口都建议默认打开 SetMultiResponseFlag(1)，不需要再按接口/SDK 区分。

5. 返回顺序

6. 超时处理

接入层等待存储层单记录响应有超时时间，默认约 2 秒。超时后处理如下：

SDK 侧超时判断：

如需调整接入层等待存储层的超时时间，请联系 DBA。

7. 性能与使用建议

建议：

8. 接口文档与示例

各 SDK 和 API 的具体接口说明，请参考 TcaplusDB SDK & API。

常用 C++ TDR SDK 接口文档：