开发者文档中心

OpenAPI进入控制台

服务端 API 与回调 · 2026-10-31

API 性能与稳定接入

按实际响应类型、限流、分页和回调语义组织调用,避免轮询与重试放大。

调用路径建议

  1. 服务端初始化时先做 capabilities 只读预检,业务请求仍会重新校验授权;预检不代替后续权限检查,也不要每次业务调用前重复拉取完整目录。
  2. 列表按对应接口的分页契约读取,只有用户翻页或后台任务需要时才取下一页;请求日志使用成对 before / beforeId 游标,不通过不断增加偏移量翻页。
  3. 复用宿主 HTTP 连接池,设置有限并发和请求超时;根据429及 Retry-After 降低并发,避免同时重试全部请求。取消已不需要的读取,不把客户端取消当成业务撤销。
  4. SSE / NDJSON 按原响应类型逐块读取,下载按字节处理,不等完整响应后才显示首条结果,也不把所有响应都交给 json()。
  5. 写请求超时保留原 Idempotency-Key,先查询真实业务记录;网关仅对有界已完成响应重放,unknown、running、超限正文均不能靠换标识重做。
  6. 异步任务优先使用已实现回调,配合低频有界状态核对;回调接收只验签并持久入队,避免等待模型、邮件或下游业务完成后才回执。

如何验证性能

指标口径诊断
首字节 / 首事件延迟分别记录HTTP响应头、首条流式事件和最终完成时间连接建立、鉴权、业务处理和下游模型分别排查。
成功请求延迟 p50 / p95区分操作、响应体量、并发和数据规模请求日志 duration 包含流式结束,不等于模型首字延迟;不能只看平均值。
429 / 5xx / 超时率包含失败与被限流请求,不从样本中删去先降并发并核对 Retry-After;不要用提高限额掩盖错误。
回调积压与最老等待时间按 pending / retry / sending / dead 区分确认调度在工作,再查接收端持久存储与回执耗时。

异步与批次调用

SDK 的 batchJson(items, { concurrency: 2, signal }) 接受1–50项,单批并发1–4;同一客户端跨批次最多4项正在执行、100项未完成。返回顺序与输入一致,每项独立成功或失败。JSON正文读完才释放并发额度。

批次中的每项仍是独立HTTP请求,不是服务端批量事务。需要减少请求次数时,优先使用业务原生批量接口,例如 insights.conversations.import 一次提交1–50条 records,整体正文最多150000字节。不能用通用批次绕过逐项权限、计费或幂等。

写入项必须使用各自独立且稳定的 Idempotency-Key。429或503会按 Retry-After 暂缓同一客户端后续批次项,最长60秒;失败项不自动重试。普通 request/json 和流式调用仍需宿主自行控制并发。

批次读取示例

运行前

api-batch-example.mjs · 有界批次示例

  • 与最新版 developer-client.mjs 放在同一目录,传入真实智能体编号。
  • 仅在受控服务端显式调用;示例导入时不发起请求。
完整代码 · 18 行
api-batch-example.mjsJavaScript
import { YunfuDeveloperClient } from './developer-client.mjs';

/** Import is inert. Call only from your authorized server; no secret is embedded. */
export async function readAgentVersionsBatch({ baseUrl, apiKey, agentIds, signal }) {
  if (!Array.isArray(agentIds) || !agentIds.length || agentIds.length > 50 ||
      agentIds.some(id => typeof id !== 'string' || !id.trim())) throw Error('Provide 1–50 real agent IDs');
  const client = new YunfuDeveloperClient({ baseUrl, apiKey });
  const grants = await client.capabilities();
  if (!grants.allowedOperations.includes('agent-versions.read')) throw Error('Operation not authorized');
  const results = await client.batchJson(agentIds.map(agentId => ({
    operation: 'agent-versions.read', query: { agentId },
  })), { concurrency: 2, signal });
  return results.map((result, index) => ({ agentId: agentIds[index], ...result }));
}

// Each item remains a separate HTTP request. Use native records-based imports
// when reducing request count is required. Failed items are not retried here.
// Reuse a client in a long-lived service so concurrent batches share its limits.
使用流程预览 · 示意图

帮助理解此示例的使用顺序,不执行代码或验证连接。

  1. 准备

    与最新版 developer-client.mjs 放在同一目录,传入真实智能体编号。 仅在受控服务端显式调用;示例导入时不发起请求。

  2. 在项目中使用

    api-batch-example.mjs · 有界批次示例

  3. 核对结果

    逐项返回成功或失败,最多50项、默认并发2;不自动重试失败项。

预期结果:逐项返回成功或失败,最多50项、默认并发2;不自动重试失败项。

过载保护

操作网关保留每密钥分钟配额,并增加共享数据库的秒级突发上限:每密钥8次、每企业24次、每环境96次。单个网页服务进程另限制正在执行的操作:每密钥4个、每企业12个、合计64个;流式请求持续占位直到结束或取消。

超出限制在执行业务前返回429或503及 Retry-After,不接受后再丢弃。秒级预算跨进程共享;正在执行数量是单进程保护,不应当作整个集群的总并发承诺。

回调后台分批投递

事件与业务变化仍在同一事务持久保存。网页和构建入口只合并唤醒后台队列;每个环境同一时刻由一个持有有效租约的消费者发送,每次HTTP回调仍保持一个签名事件。

每轮最多50条、最多20秒启动新投递,已经领取的请求仍受8秒超时保护;逐条发送间隔至少100毫秒。到期积压通过持久续调继续处理,丢失唤醒由周期扫描恢复;没有后台执行器时记录会等待,不会伪装成投递成功。

默认不合并或丢弃业务事件,不把整个队列一次放进内存。失败沿用退避和有限重试;接收方应验签、持久去重入队后快速返回2xx,把耗时业务留给自己的后台任务。

本轮优化范围

请求日志深分页按现有复合索引直接定位游标;只读网关响应不再建立文本重放副本,写响应超过256000字节后及时释放缓存;回调列表独立读取并发执行。密钥、企业、当前权限和调用时重新授权仍实时检查,新增过载保护,写入幂等边界保持不变。

性能数据只能对应具体测试条件。离线SQLite或模拟传输结果不等于生产端到端吞吐;正式压测需使用隔离企业、合成数据、明确并发与停止条件,不能把语音/模型调用或真实客户业务作为无约束压力源。

实现依据 · 仓库内路径
  • database/stores/developer-store.ts
  • app/v1/operations/developer-gateway.ts
  • lib/developer-api/developer-replay-capture.ts
  • database/stores/callback-store.ts
  • backend/services/developer-api/callback-settings.ts

文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。