customize-sdk-runtime 用于配置 Speakeasy 生成 SDK 的运行时行为,涵盖重试、超时、分页、服务器选择、自定义代码保留和错误处理。
用途
当需要为 SDK 操作配置重试逻辑、设置全局或按操作超时、为列表端点添加分页支持、在多个服务器环境之间选择、在 SDK 重新生成时保留自定义代码,或自定义错误处理与类型化错误响应时,可使用本技能。触发关键词包括“SDK retries”“timeout configuration”“server selection”“pagination config”“custom code”“error handling”。
输入与输出
输入包括:OpenAPI 规范(必需,待配置的规范路径)、gen.yaml(有时需要,用于错误处理自定义的生成配置)、目标语言(有帮助,TypeScript、Python 或 Go,默认值因情况而异)。输出包括:更新后的 OpenAPI 规范(已应用运行时扩展)、SDK 配置(在生成的 SDK 中配置的运行时行为)、自定义代码文件(在重新生成时保留的钩子文件)。
前提条件
需要安装并认证 Speakeasy CLI、已有 OpenAPI 规范、已有 SDK 项目(用于运行时覆盖示例)。
使用方式
运行时配置主要通过 OpenAPI 扩展完成,而非 CLI 命令。修改规范后,运行 speakeasy run --output console 重新生成。
重试配置
全局重试:在 OpenAPI 文档根添加 x-speakeasy-retries,可配置 strategy(必须为 backoff)、backoff.initialInterval(首次重试延迟,毫秒)、backoff.maxInterval(最大延迟,毫秒)、backoff.maxElapsedTime(所有重试总时限,毫秒)、backoff.exponent(退避乘数)、statusCodes(要重试的 HTTP 状态码,支持 5XX 模式)、retryConnectionErrors(连接失败时重试)。按操作重试:在操作级别添加相同结构的 x-speakeasy-retries 覆盖。运行时覆盖:TypeScript、Python、Go 均支持在调用时传入重试配置。
超时配置
全局超时:在文档根设置 x-speakeasy-timeout(毫秒)。按操作超时:在具体操作上覆盖。运行时覆盖:TypeScript 使用 timeoutMs,Python 使用 timeout_ms,Go 使用 WithTimeoutMs。
分页配置
在列表端点添加 x-speakeasy-pagination,支持 offsetLimit(偏移+限制参数)、cursor(游标导航)、url(响应中的下一页 URL)三种类型。对于 cursor 类型,在 inputs 中使用 type: cursor,并在 outputs 中添加 nextCursor: $.meta.next_cursor。SDK 使用(TypeScript)支持自动迭代所有页面或手动分页。
服务器配置
在规范中定义多个服务器,为每个服务器添加 x-speakeasy-server-id。运行时选择:TypeScript 使用 server 或 serverURL,Python 使用 server 或 server_url,Go 使用 WithServer 或 WithServerURL。
自定义代码保留
src/hooks/(TypeScript)或等效钩子目录中的文件在 SDK 重新生成时保留。关键规则:registration.ts 首次运行生成后不再覆盖;添加到 src/hooks/ 的新文件在重新生成时保留;在 registration.ts 中注册自定义钩子以集成到 SDK 生命周期。
错误处理
自定义错误模式(gen.yaml):在 generation.errors.statusCodes 中为状态码指定模式。在 OpenAPI 规范中为特定状态码(如 404、422)添加响应模式,SDK 会为每个生成类型化错误类。SDK 错误处理(TypeScript)可捕获 NotFoundError、ValidationError 等。错误转换钩子:通过钩子添加自定义错误转换。
示例
场景:配置重试、30 秒全局超时和沙箱服务器选择。在 OpenAPI 规范中添加扩展,重新生成,然后使用运行时覆盖。
注意事项
不要设置过长的 maxElapsedTime 导致请求无限挂起;不要对 4XX 状态码重试(408 和 429 除外);不要修改 src/hooks/ 之外的生成文件,因为重新生成时会被覆盖;不要将超时设为 0 期望“无超时”,应省略扩展;不要在应用代码中硬编码服务器 URL,应使用 x-speakeasy-server-id 并在运行时选择。
故障排除
重试不工作:扩展位置错误,确保 x-speakeasy-retries 在文档根或操作级别。超时不生效:值未使用毫秒,x-speakeasy-timeout 期望毫秒而非秒。分页 next() 未定义:缺少扩展,在列表操作添加 x-speakeasy-pagination。自定义钩子重新生成后丢失:文件在钩子目录之外,将自定义代码移至 src/hooks/ 目录。服务器 ID 无法识别:缺少扩展,为每个服务器条目添加 x-speakeasy-server-id。类型化错误未生成:缺少错误模式,在 OpenAPI 规范中为每个状态码定义错误响应模式。钩子未执行:未注册,在 registration.ts 中注册钩子。