configure-sdk-options

配置 SDK 选项

为现有 Speakeasy SDK 配置 gen.yaml 选项。支持 TypeScript、Python、Go、Java、C#、PHP 和 Ruby。

对于新的 SDK 项目：请改用 start-new-sdk-project 技能。此技能用于配置现有 SDK。

语言专属指南

如需全面了解配置详情，请参阅语言专属指南：

语言	指南	主要功能
TypeScript	content/languages/typescript.md	Zod 验证、React Query、独立函数、双模块格式
Python	content/languages/python.md	Pydantic 模型、异步模式（both/split）、uv/poetry 支持
Go	content/languages/go.md	响应格式、接口生成、K8s 集成
Java	content/languages/java.md	Builder 模式、Gradle 自定义、Maven Central 发布
C#	content/languages/csharp.md	异步/等待、取消令牌、DI 集成、NuGet
PHP	content/languages/php.md	Laravel 集成、Guzzle 配置、Packagist 发布
Ruby	content/languages/ruby.md	Sorbet 类型标注、Rails 集成、RubyGems 发布

这些指南包含详细的配置选项、代码示例、框架集成和发布说明。

适用场景

• 为现有 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	是	已创建 .speakeasy/workflow.yaml 的 SDK
目标语言	是	TypeScript、Python、Go、Java、C#、PHP 或 Ruby

输出

输出	描述
更新后的 gen.yaml	特定语言的配置
钩子文件	启用时生成的自定义钩子

前置条件

你必须已有一个包含 .speakeasy/workflow.yaml 的 SDK。如果没有，请运行：

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

通用配置（所有语言）

这些选项适用于 gen.yaml 中的所有 SDK 目标：

<language>:
  version: 1.0.0
  packageName: "my-sdk"

  # Method signatures
  maxMethodParams: 4              # Params before request object
  flatteningOrder: parameters-first

  # Error handling
  responseFormat: flat            # or "envelope" (Go)
  clientServerStatusCodesAsErrors: true

TypeScript 配置

typescript:
  version: 1.0.0
  packageName: "@myorg/my-sdk"
  moduleFormat: dual              # esm, commonjs, or dual
  zodVersion: v4-mini             # v3, v4, or v4-mini
  enableCustomCodeRegions: true   # For custom code
  enableReactQuery: true          # React Query hooks

功能	说明
Zod 验证	自动应用于所有模型
Tree-shaking	使用 moduleFormat: dual 和独立函数
JSR 发布	创建 jsr.json，运行 deno publish
npm 发布	标准的 npm publish

用于 tree-shaking 的独立函数：

import { TodoCore } from "my-sdk/core.js";
import { todosCreate } from "my-sdk/funcs/todosCreate.js";
const sdk = new TodoCore({ apiKey: "..." });

Python 配置

python:
  version: 1.0.0
  packageName: "my-sdk"
  asyncMode: both                 # both or split
  packageManager: uv              # uv or poetry
  envVarPrefix: ""                # Prefix for env config

功能	说明
Pydantic 模型	自动应用于所有模型
异步模式 both	sdk.method() 和 sdk.method_async()
异步模式 split	SDK() 和 AsyncSDK() 构造函数
PyPI 发布	uv publish 或 poetry publish

异步模式：

# asyncMode: both (default)
result = sdk.users.list()           # sync
result = await sdk.users.list_async() # async

# asyncMode: split
sdk = MySDK()                       # sync only
async_sdk = AsyncMySDK()            # async only

Go 配置

go:
  version: 0.1.0
  packageName: github.com/myorg/my-sdk
  maxMethodParams: 2
  methodArguments: require-security-and-request
  responseFormat: envelope
  flattenGlobalSecurity: true

功能	说明
接口	使用 ifacemaker 生成
Mock	使用 mockery 生成
K8s 集成	添加 kubebuilder 标记，运行 controller-gen

用于测试的接口生成：

go install github.com/vburenin/ifacemaker@latest
go install github.com/vektra/mockery/v2@latest
ifacemaker --file consumers.go --struct Consumers --iface ConsumersSDK --output consumers_i.go
mockery

Java 配置

java:
  version: 1.0.0
  groupID: com.myorg
  artifactID: my-sdk
  packageName: com.myorg.mysdk
  methodArguments: require-security-and-request

功能	说明
Builder 模式	自动应用于所有类
构建自定义	使用 build-extras.gradle（会保留）
Maven Central	./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository

客户端用法：

MySdk sdk = MySdk.builder()
    .security(Security.builder().apiKey("key").build())
    .build();

C# 配置

csharp:
  version: 1.0.0
  packageName: MyOrg.MySDK
  dotnetVersion: "6.0"
  baseErrorName: MySDKException

功能	说明
Async/await	默认所有操作均为异步
SSE 流式传输	支持 EventStream<T>
NuGet 发布	dotnet pack -c Release && dotnet nuget push

支持取消的异步操作：

var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var result = await sdk.Users.ListAsync(cancellationToken: cts.Token);

PHP 配置

php:
  version: 1.0.0
  packageName: myorg/my-sdk
  namespace: MyOrg\MySDK

功能	说明
PHP 8.2+	最低要求版本
Guzzle	HTTP 客户端（可配置超时）
Packagist	标记发布版本，并在 Packagist.org 上注册

用于刷新令牌的安全回调：

$sdk = MySDK\MySDK::builder()
    ->setSecuritySource(fn() => getTokenFromCache() ?? refreshToken())
    ->build();

Ruby 配置

ruby:
  version: 1.0.0
  packageName: my-sdk
  module: MySdk
  typingStrategy: sorbet          # sorbet or none

功能	说明
Sorbet 类型检查	可选，可通过 typingStrategy: sorbet 启用
Faraday	HTTP 客户端
RubyGems	gem build && gem push

SDK 钩子（所有语言）

通过 enableCustomCodeRegions: true 启用自定义钩子。重新生成时会保留钩子文件。

语言	钩子位置
TypeScript	src/hooks/
Python	src/<pkg>/_hooks/
Go	internal/hooks/
Java	src/main/java/.../hooks/
C#	src/.../Hooks/
PHP	src/Hooks/
Ruby	lib/.../sdk_hooks/

有关钩子实现的详细信息，请参阅 customize-sdk-hooks 技能。

运行时覆盖

可在实例化 SDK 时或针对单次调用配置运行时行为。这些设置会覆盖 gen.yaml 默认值。

服务器选择

在 OpenAPI 规范中定义服务器 ID，然后在运行时选择：

# OpenAPI spec
servers:
  - url: https://api.example.com
    x-speakeasy-server-id: production
  - url: https://sandbox.example.com
    x-speakeasy-server-id: sandbox

语言	SDK 构造函数	自定义 URL
TypeScript	new SDK({ server: "sandbox" })	new SDK({ serverURL: "..." })
Python	SDK(server="sandbox")	SDK(server_url="...")
Go	SDK.New(SDK.WithServer("sandbox"))	SDK.WithServerURL("...")

重试覆盖

针对单次调用覆盖重试行为（规范默认值通过 x-speakeasy-retries 设置）：

TypeScript：

const res = await sdk.payments.create({ amount: 1000 }, {
  retries: {
    strategy: "backoff",
    backoff: { initialInterval: 1000, maxInterval: 30000, maxElapsedTime: 120000, exponent: 2.0 },
    retryConnectionErrors: true,
  },
});

Python：

from sdk.utils import BackoffStrategy, RetryConfig
res = sdk.payments.create(amount=1000, retries=RetryConfig("backoff",
    backoff=BackoffStrategy(1000, 30000, 120000, 2.0), retry_connection_errors=True))

Go：

res, err := sdk.Payments.Create(ctx, req, operations.WithRetries(retry.Config{
    Strategy: "backoff", Backoff: &retry.BackoffStrategy{
        InitialInterval: 1000, MaxInterval: 30000, MaxElapsedTime: 120000, Exponent: 2.0},
    RetryConnectionErrors: true}))

超时覆盖

在 SDK 构造函数中设置全局超时，或针对单次调用设置：

语言	全局	单次调用
TypeScript	new SDK({ timeoutMs: 30000 })	sdk.op({}, { timeoutMs: 60000 })
Python	SDK(timeout_ms=30000)	sdk.op(timeout_ms=60000)
Go	SDK.WithTimeoutMs(30000)	operations.WithTimeoutMs(60000)

分页用法

当规范中设置了 x-speakeasy-pagination 时，SDK 会自动生成分页辅助工具：

// Auto-iterate all pages
for await (const user of await sdk.users.list({ limit: 50 })) {
  console.log(user.name);
}

// Manual pagination
let page = await sdk.users.list({ limit: 50 });
while (page) {
  for (const user of page.data) { console.log(user.name); }
  page = await page.next();
}

决策框架

情况	操作
需要摇树优化（TS）	设置 moduleFormat: dual，使用独立函数
需要异步/同步（Python）	设置 asyncMode: both（默认值）
需要独立的异步客户端	设置 asyncMode: split（Python）
需要用于测试的接口（Go）	使用 ifacemaker + mockery
需要自定义构建配置（Java）	编辑 build-extras.gradle
需要在运行时覆盖重试设置	在单次调用选项中传入 retries 配置
需要在运行时覆盖超时设置	在构造函数或单次调用中设置 timeoutMs
需要切换服务器	在规范中使用 x-speakeasy-server-id，并在运行时选择

不要做的事

• 不要将此技能用于初始 SDK 生成——请使用 start-new-sdk-project
• 不要编辑自定义代码区域之外的生成文件
• 不要修改 src/ 中不在保留目录（hooks、extra）内的文件

故障排查

语言	问题	解决方案
TypeScript	包体积过大	使用独立函数
Python	异步分页阻塞	启用 fixFlags.asyncPaginationSep2025: true
Go	未生成接口	确保结构体已导出（首字母大写）
Java	Gradle 同步失败	运行 ./gradlew --refresh-dependencies
C#	异步死锁	使用 await，而不是 .Result
PHP	PHP 版本错误	需要 PHP 8.2+
Ruby	Sorbet 错误	运行 bundle exec tapioca gems
全部	重试不起作用	确保 x-speakeasy-retries 位于文档根级别或操作级别
全部	无法识别服务器 ID	为每个服务器条目添加 x-speakeasy-server-id
全部	分页 next() 未定义	为列表操作添加 x-speakeasy-pagination

完成更改后

修改 gen.yaml 配置后，提示用户重新生成 SDK：

配置完成。 是否现在使用 speakeasy run 重新生成 SDK？

如果用户确认，请运行：

speakeasy run --output console

更改 gen.yaml 只有在重新生成后才会生效。

相关技能

• start-new-sdk-project - 初始 SDK 生成
• customize-sdk-hooks - 钩子实现详解
• manage-openapi-overlays - 规范自定义