mcpField
I
improve-sdk-naming

improve-sdk-naming

github.com/speakeasy-api开发1894 次安装37 周前更新
代码仓库

关于 improve-sdk-naming

用于改进 Speakeasy 生成 SDK 的方法名和错误类型名称，面向基于 OpenAPI 规范工作的开发者。可通过 Speakeasy CLI 获取 AI 建议，并将审核后的建议保存为 overlay。

主要功能

  1. 01通过 CLI 获取 operation ID 建议
  2. 02获取结构化错误类型建议
  3. 03将建议导出为 overlay 文件
  4. 04使用分组和名称覆盖扩展

适用场景

  1. 01替换含义不清的 SDK 自动生成方法名
  2. 02在重新生成前审核方法名称建议
  3. 03向 API 规范添加结构化错误类型建议

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/speakeasy-api/sdk-generation-skills --skill improve-sdk-naming

安装后在 Claude Code 中输入/improve-sdk-naming确认已加载。

详细介绍

改进 SDK 命名

使用 AI 驱动的建议或手动覆盖来改进 SDK 方法命名。涵盖自动 speakeasy suggest 命令，以及使用 x-speakeasy-group 和 x-speakeasy-name-override 扩展手动命名。

适用场景

当你想要获取 Speakeasy 提供的 AI 驱动建议 时，请使用此技能：

  • SDK 方法具有不够理想的自动生成名称，例如 GetApiV1Users
  • 你希望 Speakeasy AI 提供更好的操作 ID 建议
  • 你希望获取 AI 生成的错误类型建议
  • 想要使用 speakeasy suggest 自动提高规范质量
  • 用户表示：“建议改进”“speakeasy suggest”“AI 建议”“建议操作 ID”“建议错误类型”“获取 AI 建议”

不适用于：手动创建覆盖项（请改用 manage-openapi-overlays）

输入

输入必需说明
OpenAPI 规范是规范文件的路径（-s）
身份验证是通过 speakeasy auth login 或 SPEAKEASY_API_KEY 环境变量
输出文件否覆盖文件的输出路径（-o）

输出

输出说明
建议输出到控制台的更佳操作名称或错误类型
覆盖文件可选：将建议保存为覆盖 YAML 文件（-o）

前置条件

对于非交互式环境（CI/CD、AI Agent），请将 API 密钥设为环境变量：

export SPEAKEASY_API_KEY="<your-api-key>"

对于交互式使用，请直接进行身份验证：

speakeasy auth login

命令

AI 驱动的建议
# Suggest better operation IDs (SDK method names)
speakeasy suggest operation-ids -s <spec-path>

# Suggest error type definitions
speakeasy suggest error-types -s <spec-path>

# Output suggestions as an overlay file
speakeasy suggest operation-ids -s <spec-path> -o suggested-overlay.yaml
检查当前操作 ID

运行不带 -o 的 suggest 命令，预览将发生的更改：

speakeasy suggest operation-ids -s openapi.yaml

SDK 方法命名约定

Speakeasy 根据操作 ID 生成分组的 SDK 方法。命名约定使用 x-speakeasy-group 表示命名空间，使用 x-speakeasy-name-override 表示方法名称。

HTTP 方法SDK 用法操作 ID
GET（列表）sdk.users.list()users_list
GET（单项）sdk.users.get()users_get
POSTsdk.users.create()users_create
PUTsdk.users.update()users_update
DELETEsdk.users.delete()users_delete

操作 ID 的格式为 {group}_{method}。Speakeasy 会按下划线拆分，以便在生成的 SDK 中创建命名空间和方法名称。

示例

第 1 步：获取 AI 建议
speakeasy suggest operation-ids -s openapi.yaml -o operation-ids-overlay.yaml

此命令会分析你的规范，并生成覆盖项，将如下名称转换为：

  • get_api_v1_users_list -> listUsers
  • post_api_v1_users_create -> createUser
第 2 步：检查并应用覆盖项

AI 生成的覆盖项（通过 -o 指定）使用 x-speakeasy-group 和 x-speakeasy-name-override 改进命名。

注意：要手动创建覆盖项，请改用 manage-openapi-overlays 技能，而不是此技能。

第 3 步：将覆盖项添加到 workflow.yaml
sources:
  my-api:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: ./operation-ids-overlay.yaml
第 4 步：重新生成 SDK
speakeasy run --output console

错误类型建议

suggest error-types 命令会分析你的 API 并建议结构化错误响应：

speakeasy suggest error-types -s openapi.yaml

此命令会建议：

  • 常见 HTTP 错误代码（400、401、404、500）
  • 适用于你的 API 的自定义错误架构

将结果输出为覆盖项：

speakeasy suggest error-types -s openapi.yaml -o error-types-overlay.yaml

不要这样做

  • 不要在外部管理的源规范中直接修改 operationIds。请改用覆盖项。
  • 不要使用 get 或 post 这类不带分组的通用名称。始终将 x-speakeasy-name-override 与 x-speakeasy-group 配对使用。
  • 不要忘记在创建生成的覆盖项后将其添加到 workflow.yaml。否则，生成的 SDK 中不会更改这些名称。
  • 不要在不同分组中创建重复的操作名称。每个 {group}_{method} 组合都必须唯一。

故障排除

错误原因解决方案
"unauthorized"API 密钥缺失或无效设置 SPEAKEASY_API_KEY 环境变量，或运行 speakeasy auth login
重新生成后名称未改变未将 Overlay 添加到工作流将 Overlay 添加到 workflow.yaml 中的 overlays 列表
未返回建议规范的命名已经很合适无需操作；名称的结构已经很清晰
方法名称重复相似的端点使用了相同名称为每个端点使用唯一的 x-speakeasy-name-override 值
建议过程中超时规范文件过大尝试在较小的子集上运行，或延长超时时间

评论

支持 Markdown