如何理解SDK 的公开 API 需要明确哪些契约？

标准回答

明确参数约束、调用线程、回调线程、操作前置状态、并发规则、取消含义、超时范围和资源归属。调用方应知道方法返回代表“受理”“传输完成”还是“业务成功”，以及是否可能同步回调。

如果允许用户注入 Executor，说明回调在该执行器上的顺序保障和拒绝策略；如果固定主线程回调，说明重型数据处理应在哪里完成。终态回调通常应保证至多一次，取消和结果竞争时也要遵守同一规则。

SDK 可以回调前自己吞掉所有异常吗？内部要避免异常破坏状态，但不能把真实失败都伪装为成功。对调用方回调抛异常的处理也要明确，避免一条错误回调破坏整个队列。