configure-sdk-options

用途

本技能用于配置已有的 Speakeasy SDK，不适用于初次生成 SDK。它聚焦于 gen.yaml 文件的配置，支持 TypeScript、Python、Go、Java、C#、PHP、Ruby 七种语言。若需新建 SDK 项目，应改用 start-new-sdk-project 技能。

在 gen.yaml 中可设置版本、包名、方法签名（maxMethodParams、flatteningOrder）、错误处理（responseFormat、clientServerStatusCodesAsErrors）等。

TypeScript：moduleFormat（esm/commonjs/dual）、zodVersion、enableCustomCodeRegions、enableReactQuery；支持 Zod 校验、tree-shaking、JSR 与 npm 发布。
Python：asyncMode（both/split）、packageManager（uv/poetry）、envVarPrefix；支持 Pydantic 模型、PyPI 发布。
Go：maxMethodParams、methodArguments、responseFormat（envelope）、flattenGlobalSecurity；支持接口生成（ifacemaker）、Mock（mockery）、K8s 集成。
Java：groupID、artifactID、packageName、methodArguments；支持 Builder 模式、build-extras.gradle 定制、Maven Central 发布。
C#：dotnetVersion、baseErrorName；支持 async/await、SSE 流式、NuGet 发布。
PHP：namespace；要求 PHP 8.2+，使用 Guzzle，支持 Packagist 发布与安全回调刷新令牌。
Ruby：module、typingStrategy（sorbet/none）；使用 Faraday，支持 RubyGems 发布。

通过 enableCustomCodeRegions: true 启用自定义钩子，钩子文件在重新生成时会被保留，各语言有对应的钩子目录。

可在 SDK 实例化或每次调用时覆盖 gen.yaml 默认值，包括服务器选择（基于 x-speakeasy-server-id）、重试（retries 配置）、超时（timeoutMs）。

当规范中设置 x-speakeasy-pagination 时，SDK 自动生成分页辅助方法，支持自动遍历所有页或手动分页。

前提：已存在带 .speakeasy/workflow.yaml 的 SDK。若没有，可运行：

speakeasy quickstart --skip-interactive --output console
-s openapi.yaml -t <language> -n "MySDK" -p "<package-name>"

修改 gen.yaml 后，需提示用户重新生成 SDK，确认后运行：

speakeasy run --output console

配置更改仅在重新生成后生效。

为已有 SDK 配置语言特定的 gen.yaml 选项
设置 SDK 钩子、异步模式或发布流程
在应用代码中配置运行时行为（重试、超时、服务器选择）
用户提及 configure SDK、gen.yaml options、SDK config、runtime override、per-call config，或询问 Zod、Pydantic、NuGet、PyPI、npm、Maven Central、Packagist、RubyGems 等

不用于初次生成 SDK，应使用 start-new-sdk-project
不要编辑自定义代码区域之外的生成文件
不要修改 src/ 中非保留目录（hooks、extra）下的文件
各语言存在特定问题与解决方式，如 TypeScript 包过大可用独立函数、Python 异步分页阻塞可启用 fixFlags.asyncPaginationSep2025、Go 接口未生成需确保结构体导出、Java Gradle 同步失败可刷新依赖、C# 异步死锁应使用 await、PHP 需 8.2+、Ruby Sorbet 错误可运行 bundle exec tapioca gems 等
重试不生效需确保 x-speakeasy-retries 位于文档根或操作级别；服务器 ID 未识别需为每个 server 条目添加 x-speakeasy-server-id；分页 next() 未定义需为列表操作添加 x-speakeasy-pagination