跳到主要内容

业务接口稳定性

应用“能运行”不等于业务数据能稳定显示。读取开放平台数据前，就应把排队、重复请求和失败展示一起实现，而不是等客户遇到空数据后再补。这是开发者和 AI 的工作，不要求商家理解或配置限流。

本地、云端和正式环境都要处理​

开放平台通用限制是同一商家的业务接口共享额度，当前默认每秒最多 4 次；部分商家有更低额度或更长窗口。不能按接口、员工、应用或 AppID 各分一份。本地 WorkBuddy、其他 AI 工具、云开发、测试版和正式版调用的仍是开放平台，不会因使用 SDK、xdbapp dev 或短期 Token 而免除限制。

SDK 自动处理签名和 Token 缓存，目前不自动给业务请求限速、合并或缓存业务结果，也不自动重试业务请求。不要把“已接入 SDK”写成“已经不会触发限流”。

AI 编码前必须落实​

  1. 后端统一安排请求。 按上游商家主体共享队列，跨接口共用预算，页面、分页、轮询、后台同步和重试都经过该队列。同一主体共用凭据时，不能给每个前端员工、页面、组件或 SDK 实例分别算一份额度。普通单进程实现可让同一商家全部业务请求的开始时间至少相隔 300ms，控制默认窗口内最多 4 次；这是建议默认值，不是平台新增限制，也不能覆盖更严格的接口规则。
  2. 并发少不等于频率低。 即使每次都 await，上游响应快时，一秒仍可能调用十几次。必须控制请求开始时间；不能用没有间隔的串行循环，或只设置 concurrency=1 代替限速。队列还要有等待超时和容量上限，取消/失败后能继续处理后续请求，不无限积压。
  3. 重复读取合并，适合的数据缓存。 同一商家、有效权限范围、接口和规范化参数内，相同只读请求正在执行时复用同一结果。已有成功结果按业务时效设置短 TTL；缓存必须在鉴权之后读取，不能跨商家或权限复用数据，失败不缓存。写入成功后使相关查询缓存失效，不让用户改完仍看到旧值。Token 获取按 AppID 计数，应缓存并合并并发刷新；切换 Token 不会重置商家业务请求额度。
  4. 页面不负责全量同步。 优先使用已存在的分页、批量查询和按需详情；不要逐行无限并发拉详情或每个组件各自轮询。确实需要大量数据时，在后台分批同步到应用数据库，页面读取已有结果，显示真实进度和更新时间；同步可以中断后继续。无需新建另一套任务平台，优先复用项目已有机制。
  5. 多个进程不能各拿一份额度。 单进程队列只保护这个进程。Python 多 worker、Node 多进程、多个容器，以及其他程序使用同一上游主体时，要复用共享协调机制或统一的同步执行入口；不能为每个进程各配 4 次，然后声称整个应用不超限。不改平台限流，不使用绕过限流的参数或密钥。

这些要求适用于本轮新增、修改的相关调用路径，先复用现有能力；不要求为了接入重写全部历史业务。

失败不能伪装成“没有数据”​

  • 按 HTTP 状态和实际业务响应判断结果。HTTP 200 也可能是业务失败，不要假设限流一定表现为 HTTP 429，更不能把异常 catch 后返回 [] 当成查询成功。
  • 只对确认可以安全重复的只读调用做有限退避，建议最多重试 2 次（总共至多 3 次尝试），默认等待逐次增加并带少量随机间隔；响应提供有效 Retry-After 时遵守等待时间，超过总等待预算就停止并提示。每次重试仍需经过同一队列。授权不足、参数错误不按限流反复重试。
  • 写操作不自动重试。 下单、新增营员、核销、退款、发通知等，超时不代表操作没有发生。只按该接口已有的幂等和结果查询规则处理，不能照搬只读重试。
  • 有已成功加载且仍在权限范围内的数据时保留展示，注明更新时间和更新失败；首次加载失败则显示“数据暂时加载失败，请稍后重试”，提供一次明确的重试操作。只有上游真正成功返回空集合时才显示“暂无数据”。自动恢复要有次数与等待上限，不无限刷新。

交付前由 AI 自测​

使用模拟上游与模拟时钟，验证本轮相关实现，不用真实客户数据高频试探限额：

  • 同一商家跨多个接口同时提交 20 个不同查询，任意连续一秒内发送数量都不超过文档额度；同时验证更低额度的配置；不能只验证总耗时。
  • 多人打开页面、多个组件和后台同步同时执行，合计仍使用同一预算；多 worker 场景验证共享协调，而不是只测试一个进程。
  • 同权限、同参数的重复只读请求会合并；不同商家或权限的查询不会误用缓存。写入后能读到更新结果。
  • 上游限流、HTTP 200 业务错误、网络超时不会变成“暂无数据”；失败后后续请求还能继续，自动重试有上限。
  • 写操作遇到失败不会被通用重试逻辑重复执行；数据导入或同步中断后不会重复处理已完成部分。

在应用的现有测试入口保存用例并记录实际执行结果。没有执行不能声称通过；这不是平台新增的一项发布拦截，也不让商家手工验算频率。

已有项目如何生效​

云开发更新后会在后续开发轮次提供这套要求；本地 WorkBuddy 等工具需要读取最新的 AI 接入说明 和 https://paas.xinduobang.cn/XDB_PAAS.md。旧对话、项目内旧说明和已发布的应用不会自动补上流控，不能声称更新文档就已修复历史应用。AI 修改相关代码后仍需测试并按原流程发布。