用途:为 Speakeasy 生成的 SDK 配置运行时行为,涵盖重试、超时、分页、服务器选择、自定义代码保留和错误处理。
主要能力:通过 OpenAPI 扩展配置。重试使用 x-speakeasy-retries(根或操作级),支持 backoff 策略及 initialInterval、maxInterval、maxElapsedTime、exponent、statusCodes、retryConnectionErrors。超时使用 x-speakeasy-timeout(毫秒)。分页使用 x-speakeasy-pagination,支持 offsetLimit、cursor、url。服务器用 x-speakeasy-server-id 标记,运行时按 id 选择。自定义代码放入 hooks 目录,registration.ts 首次生成后不覆盖。错误处理可在 gen.yaml 按状态码映射错误 schema,并可通过 hooks 转换错误。
使用方式:修改 OpenAPI 规范后运行 speakeasy run --output console 重新生成。运行时可在 TypeScript、Python、Go 中覆盖重试、超时与服务器。
适用场景:为生成 SDK 统一运行时行为、保留自定义逻辑、定制错误类型。
限制:不要设置过长 maxElapsedTime;不要重试 4XX(408、429 除外);不要修改 hooks 目录外的生成文件;不要将超时设为 0,应省略扩展;不要在应用代码硬编码服务器 URL。缺失信息暂未提供。