volcengine-sdk-generator

Volcengine SDK 代码生成器

根据自然语言描述生成完整、可运行的 Volcengine SDK 代码，并解答 SDK 配置问题。

工作流

当用户描述 Volcengine API 操作时，请按以下步骤执行：

步骤 1：识别目标服务、操作和高级配置需求

解析用户的描述，确定：

• 目标服务：要使用的 Volcengine 服务（例如 ECS、VPC、TOS、billing）

• 目标操作：要执行的操作（例如列出实例、创建 VPC、查询账单）

• 目标语言：要使用的编程语言（Go、Python、PHP、Java、Node.js）。如果未指定，请询问用户。

• 高级配置需求：用户是否提及或场景是否隐含以下任一需求：

  • 重试：用户提及“重试”“容错”，或操作属于写入/创建类型（容易触发限流）
  • 超时：用户提及“超时”，或操作涉及大量数据（批量查询、文件上传）
  • 凭证：用户提及“STS”“AssumeRole”“临时凭证”“OIDC”，或明确要求避免将 AK/SK 硬编码
  • 代理/网络：用户提及“代理”或“内网”
  • 调试模式：用户提及“调试”或“日志记录”
  • 连接池：用户提及“连接池”“高并发”或“池”

  如果用户明确提出这些需求，请在生成的代码中包含相应配置。如果未明确提出，但场景有所暗示（例如创建资源通常需要重试），请以注释形式加入建议配置。

步骤 2：通过 Volcengine API Explorer 查询服务元数据

使用以下 API 查找正确的服务代码、版本和操作名称。此步骤至关重要，因为猜测往往会生成错误代码；API Explorer 是权威来源。

2a. 查找 ServiceCode

获取服务目录：

GET https://api.volcengine.com/api/common/explorer/services

响应结构：

{
  "Result": {
    "Categories": [
      {
        "CategoryName": "...",
        "Services": [
          {
            "ServiceCn": "Cloud Server",
            "ServiceCode": "ecs",
            "Product": "ECS",
            "IsSdkAvailable": true,
            "RegionType": "regional"
          }
        ]
      }
    ]
  }
}

根据 ServiceCn、Product 和类别名称，将用户意图与正确的 ServiceCode 匹配。

2b. 查找 API 版本

GET https://api.volcengine.com/api/common/explorer/versions?ServiceCode={ServiceCode}

响应：

{
  "Result": {
    "Versions": [
      {
        "ServiceCode": "billing",
        "Version": "2022-01-01",
        "IsDefault": 0
      }
    ]
  }
}

使用 IsDefault == 1 的版本。如果没有默认版本，则使用最新版本。

2c. 查找 Action 名称

GET https://api.volcengine.com/api/common/explorer/apis?ServiceCode={ServiceCode}&Version={Version}&APIVersion={Version}

响应：

{
  "Result": {
    "Groups": [
      {
        "Name": "Instance",
        "Apis": [
          {
            "Action": "DescribeInstances",
            "NameCn": "Query instance list",
            "Description": "..."
          }
        ]
      }
    ]
  }
}

根据 Action 名称和 NameCn（中文名称）匹配用户意图。

2c-alt: 搜索 API（直接查询失败时）

如果服务目录或 API 列表无法明确匹配用户的描述，例如用户使用了含糊的术语、无法直接对应到 ServiceCode 的中文名称，或 API 列表中似乎没有用户需要的内容，请将搜索 API 用作备用方案：

GET https://api.volcengine.com/api/common/search/all?Query={URL-encoded search term}&Channel=api&Limit=10

搜索词可以是中文或英文；请选择最符合用户描述的语言。

响应结构：

{
  "Result": {
    "List": [
      {
        "BizInfo": {
          "Action": "ListProjects",
          "ServiceCn": "Access Control",
          "ServiceCode": "iam",
          "Version": "2021-08-01"
        },
        "Highlight": [
          {"Field": "title", "Summary": "Get <em>project</em> <em>list</em>"}
        ]
      }
    ],
    "Total": 200
  }
}

根据 ServiceCn、Action 和高亮文本选择最匹配的结果，然后继续执行步骤 2d。

以下情况尤其适合使用搜索 API：

• 用户用自然语言描述操作，但不知道该由哪个服务提供
• 某个服务的 API 太多，难以手动浏览
• 描述涉及多个服务（搜索会返回所有服务中的结果）

2d. 获取完整的 API 参数详情

GET https://api.volcengine.com/api/common/explorer/api-swagger?ServiceCode={ServiceCode}&Version={Version}&APIVersion={Version}&ActionName={Action}

返回完整的 Swagger/OpenAPI 规范，包括：

• HTTP 方法（GET/POST）
• 所有请求参数的类型、必填标志和说明
• 响应结构
• 约束和验证规则
• x-demo 字段：包含官方示例 requestDemo 和 responseDemo

请仔细阅读此规范，这对于生成准确的代码至关重要。

2e. 提取参数示例值（从 x-demo requestDemo 中）

Swagger 响应中的 info.x-demo 数组包含 requestDemo，即官方请求示例。请从中提取真实的参数值，用于填充生成的代码。 提取流程：

1. 定位 info.x-demo[0].requestDemo，并解析请求体 JSON
2. 将 requestDemo 中的值用作生成代码的示例值——这些值比臆造的值更准确、更贴近实际
3. 对于掩码值（例如 cc5silum********），保留掩码格式，并添加注释提示用户替换为真实值
4. 如果参数值是 JSON 字符串（例如 Config 字段），应清晰地格式化，并为每个子字段添加注释

示例：对于 VKE CreateAddon，requestDemo 包含：

{
    "ClusterId": "cc5silum********",
    "Name": "ingress-nginx",
    "DeployMode": "Unmanaged",
    "DeployNodeType": ["VirtualNode"],
    "Config": "{\"Replica\":1,\"Resource\":{\"Request\":{\"Cpu\":\"0.25\",\"Memory\":\"512Mi\"},\"Limit\":{\"Cpu\":\"0.5\",\"Memory\":\"1024Mi\"}},\"PrivateNetwork\":{\"SubnetId\":\"subnet-2d61qn69iji****\",\"IpVersion\":\"IPV4\"}}"
}

直接使用这些示例值，不要使用空占位符。

2f. 获取复杂参数的详细配置

某些参数的 description 字段中包含文档链接（例如 https://www.volcengine.com/docs/...），指向详细配置指南。对于复杂参数，请获取这些链接以了解更多信息：

查阅文档的时机：

• 参数值是 JSON 字符串，且描述中引用了“查看详细配置”（例如 VKE Config）
• 参数是嵌套结构，其子字段格式在外部文档中有说明
• enum 值的含义不明确，需要通过文档解释

处理流程：

1. 检查参数 description 是否包含 volcengine.com/docs 链接
2. 如果包含，则使用 WebFetch 获取链接页面，并提取与该参数相关的配置信息
3. 将文档中的示例作为注释或结构化参数纳入生成的代码
4. 如果无法访问文档，则回退使用 requestDemo 示例值

2g. 确定必填和建议参数

必填字段的判定依赖多个来源，而不仅仅是 required 数组：

1. 明确必填：列在 Swagger required 数组中
2. 描述暗示必填：描述中包含“必须指定”“必需”等类似措辞
3. 逻辑上必填：语义上不可或缺，即使未正式标记（例如，创建资源时需要实例类型和网络配置）
4. 有条件必填：描述指出“当 X=Y 时必需”——如果符合用户的场景，则应包含

参数值优先级：

1. requestDemo 示例值（最高优先级）：直接使用官方示例
2. example 字段：Swagger 规范中各参数的 example 值
3. enum 值：选择最常见或通用性最强的选项
4. 文档建议：从链接的文档中提取的值
5. 行业惯例：遵循云计算规范的合理默认值（例如，CIDR 使用 172.16.0.0/16，实例采用描述性名称）

步骤 3：查阅 SDK 配置参考（按需）

如果步骤 1 确定需要高级配置，请阅读目标语言对应的参考文件，以获取准确的配置代码：

语言	参考文件
Go	references/sdk-integration-go.md
Python	references/sdk-integration-python.md
Java	references/sdk-integration-java.md
Node.js	references/sdk-integration-nodejs.md
PHP	references/sdk-integration-php.md

这些文件包含经过验证的代码片段，涵盖重试、超时、凭证、代理、连接池和调试配置。请直接使用这些模式，而不要凭记忆编写——SDK 配置因语言而异，而这些参考文件可确保准确性。

步骤 4：生成完整的 SDK 代码

按照以下规则生成完整、可运行的代码示例：

通用规则（所有语言）

1. 身份验证：默认从环境变量 VOLCENGINE_ACCESS_KEY 和 VOLCENGINE_SECRET_KEY 读取 AK/SK。如果用户需要其他身份验证方式（STS、AssumeRole、OIDC），请使用参考文件中的对应模式。具体读取方式因语言而异，详见各语言章节和参考文件。
2. 地域：区域服务默认使用 cn-beijing。添加注释说明用户可以修改此值。
3. 必需参数：包含所有必需参数（来源见步骤 2g），并使用来自 requestDemo 或示例字段的真实示例值。在每个值旁添加注释，说明其含义和来源。
4. 参数值质量：参数值必须符合实际格式和业务语义，不能使用简单占位符：
   • 实例 ID：使用掩码格式，例如 i-abc123******（来自 requestDemo）
   • CIDR：使用合理的范围，例如 172.16.0.0/16
   • 枚举值：使用最常见的选项
   • 嵌套 JSON 配置：展开为易读的多行格式，并为每个字段添加注释
5. 复杂参数处理：对于值为 JSON 字符串的参数（例如 VKE Config），应先构建结构体或字典，再序列化为 JSON，而不是硬编码冗长的字符串。这样能让代码更易读，也更便于修改。
6. 可选参数：以注释行的形式包含常用可选参数（例如分页参数），并附上说明。
7. 错误处理：包含适用于目标语言的标准错误处理。
8. 输出：以易读的格式输出响应（例如格式化后的 JSON）。
9. 注释：添加说明代码用途的头部注释。为不明显的参数添加行内注释。注释语言应与用户提示所用语言一致。
10. 高级配置集成：当用户有高级配置需求时，应将配置自然地融入主代码（而非单独成块），生成单个可运行文件：
    • 重试：在客户端／配置初始化时添加重试设置，并注释说明默认值和可调整的参数
    • 超时：在客户端初始化时设置全局超时；如有需要，展示如何设置单次请求的超时
    • 凭证：将默认的 AK/SK 身份验证代码替换为用户指定的方式（STS、AssumeRole 等）
    • 代理：在客户端配置中添加代理设置
    • 调试：在客户端配置中启用调试模式
    • 连接池：在客户端配置中设置连接池参数

Go

Go SDK 使用 {Action}Input 结构体（而非 Request）。服务通过 {service}.New(sess) 实例化。

package main

import (
    "fmt"
    "os"
    "github.com/volcengine/volcengine-go-sdk/service/{service}"
    "github.com/volcengine/volcengine-go-sdk/volcengine"
    "github.com/volcengine/volcengine-go-sdk/volcengine/credentials"
    "github.com/volcengine/volcengine-go-sdk/volcengine/session"
)

func main() {
    ak := os.Getenv("VOLCENGINE_ACCESS_KEY")
    sk := os.Getenv("VOLCENGINE_SECRET_KEY")
    region := "cn-beijing"

    config := volcengine.NewConfig().
        WithRegion(region).
        WithCredentials(credentials.NewStaticCredentials(ak, sk, ""))

    // [Advanced config — add as needed, see references/sdk-integration-go.md]
    // Retry: config.WithMaxRetries(5)
    // Timeout: config.WithHTTPClient(&http.Client{Timeout: 60 * time.Second})
    // Proxy: config.WithHTTPProxy("http://proxy:8080")
    // Debug: config.WithDebug(true)

    sess, err := session.NewSession(config)
    if err != nil {
        panic(err)
    }
    svc := {service}.New(sess)

    input := &{service}.{Action}Input{
        // Set required parameters here
    }
    resp, err := svc.{Action}(input)
    if err != nil {
        panic(err)
    }
    fmt.Println(resp)
}

要点：

• 包路径：github.com/volcengine/volcengine-go-sdk/service/{service}（小写，例如 billing、ecs、vpc）
• 配置链：volcengine.NewConfig().WithRegion(region).WithCredentials(credentials.NewStaticCredentials(ak, sk, ""))
• 会话：session.NewSession(config)（返回会话和错误）
• 服务客户端：{service}.New(sess)（例如 billing.New(sess)、ecs.New(sess)）
• 请求结构体：{Action}Input（例如 ListAvailableInstancesInput、DescribeInstancesInput）
• 方法：svc.{Action}(input)，操作名称采用 PascalCase

Python

Python SDK 使用 {SERVICE}Api（服务名称大写）和 {Action}Request 模型。

from __future__ import print_function
import os
import volcenginesdkcore
import volcenginesdk{service}
from volcenginesdkcore.rest import ApiException

if __name__ == '__main__':
    configuration = volcenginesdkcore.Configuration()
    configuration.ak = os.environ.get("VOLCENGINE_ACCESS_KEY")
    configuration.sk = os.environ.get("VOLCENGINE_SECRET_KEY")
    configuration.region = "cn-beijing"

    # [Advanced config — add as needed, see references/sdk-integration-python.md]
    # Retry: configuration.max_retry_attempts = 5
    # Timeout: configuration.connection_timeout = 10; configuration.read_timeout = 60
    # Proxy: configuration.proxy = "http://proxy:8080"
    # Debug: configuration.debug = True

    volcenginesdkcore.Configuration.set_default(configuration)

    api_instance = volcenginesdk{service}.{SERVICE}Api()
    request = volcenginesdk{service}.{Action}Request(
        # Set required parameters here
    )

    try:
        resp = api_instance.{action_snake_case}(request)
        print(resp)
    except ApiException as e:
        print("API exception: %s\n" % e)

要点：

• 软件包：volcenginesdkcore + volcenginesdk{service}（全小写，不含分隔符，例如 volcenginesdkbilling、volcenginesdkecs）
• 配置：volcenginesdkcore.Configuration()，设置 .ak、.sk、.region，然后调用 set_default()
• API 类：volcenginesdk{service}.{SERVICE}Api() — 服务名称全大写（例如 BILLINGApi、ECSApi、VPCApi）
• 请求类：volcenginesdk{service}.{Action}Request(...)（PascalCase，例如 ListAvailableInstancesRequest）
• 方法：api_instance.{action_snake_case}(request) — snake_case（例如 list_available_instances、describe_instances）
• 异常：from volcenginesdkcore.rest import ApiException

Java

Java SDK 在 com.volcengine.{service} 下使用 {ServiceName}Api 和 {Action}Request 模型。

package com.volcengine.sample;

import com.volcengine.ApiClient;
import com.volcengine.ApiException;
import com.volcengine.sign.Credentials;
import com.volcengine.{service}.{ServiceName}Api;
import com.volcengine.{service}.model.*;

public class Example {
    public static void main(String[] args) throws Exception {
        String ak = System.getenv("VOLCENGINE_ACCESS_KEY");
        String sk = System.getenv("VOLCENGINE_SECRET_KEY");
        String region = "cn-beijing";

        ApiClient apiClient = new ApiClient()
                .setCredentials(Credentials.getCredentials(ak, sk))
                .setRegion(region);

        // [Advanced config — add as needed, see references/sdk-integration-java.md]
        // Retry: apiClient.setRetrySettings(new RetrySettings().setMaxAttempts(5));
        // Timeout: apiClient.setConnectionTimeout(5000); apiClient.setReadTimeout(30000);
        // Proxy: apiClient.setHttpProxy("http://proxy:8080");
        // Debug: apiClient.setDebugging(true);

        {ServiceName}Api api = new {ServiceName}Api(apiClient);

        {Action}Request request = new {Action}Request();
        // request.setParamName(value);

        try {
            {Action}Response resp = api.{actionCamelCase}(request);
            System.out.println(resp);
        } catch (ApiException e) {
            System.out.println(e.getResponseBody());
        }
    }
}

要点：

• 软件包：com.volcengine.{service}（小写，例如 com.volcengine.billing、com.volcengine.ecs）
• ApiClient：new ApiClient().setCredentials(Credentials.getCredentials(ak, sk)).setRegion(region)
• API 类：{ServiceName}Api（PascalCase，例如 BillingApi、EcsApi）— 构造函数接收 apiClient
• 请求类：{Action}Request（例如 ListAvailableInstancesRequest）— 通过 setter 设置参数
• 方法：api.{actionCamelCase}(request) — camelCase（例如 listAvailableInstances、describeInstances）
• 异常：ApiException，使用 e.getResponseBody() 获取详细信息

Node.js

Node.js SDK 使用命令模式：{SERVICE}Client + {Action}Command。

import { {SERVICE}Client, {Action}Command } from "@volcengine/{service}";

// Automatically reads VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY from env
const client = new {SERVICE}Client({
    region: "cn-beijing",
    // [Advanced config — add as needed, see references/sdk-integration-nodejs.md]
    // maxRetries: 5,                          // retry count
    // autoRetry: false,                       // disable auto-retry
    // httpOptions: { timeout: 30000 },        // timeout (ms)
    // httpOptions: { proxy: { protocol: "http", host: "127.0.0.1", port: 8888 } },  // proxy
});

async function main() {
    try {
        const command = new {Action}Command({
            // Set required parameters here
        });
        const response = await client.send(command);
        console.log(JSON.stringify(response, null, 2));
    } catch (error) {
        console.error("Error:", error);
    }
}

main();

要点：

• 软件包：@volcengine/{service}（小写，例如 @volcengine/ecs、@volcengine/vpc）
• 客户端：{SERVICE}Client（服务名称全大写，例如 ECSClient、VPCClient）
• 命令：{Action}Command（PascalCase，例如 DescribeInstancesCommand、CreateVpcCommand）
• 调用：client.send(command) — 异步，返回一个 Promise
• 身份验证：自动从环境中读取 VOLCENGINE_ACCESS_KEY 和 VOLCENGINE_SECRET_KEY；也可以在客户端构造函数中传入 accessKeyId/secretAccessKey

PHP

PHP SDK 使用 \Volcengine\{Service}\ 命名空间下的类。

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = \Volcengine\Common\Configuration::getDefaultConfiguration()
    ->setAk(getenv("VOLCENGINE_ACCESS_KEY"))
    ->setSk(getenv("VOLCENGINE_SECRET_KEY"))
    ->setRegion("cn-beijing");

// [Advanced config — add as needed, see references/sdk-integration-php.md]
// Proxy and timeout are configured via GuzzleHttp\Client options
$httpClient = new GuzzleHttp\Client([
    // 'proxy' => 'http://proxy:8080',              // proxy
    // 'timeout' => 60,                              // request timeout (seconds)
    // 'connect_timeout' => 10,                      // connection timeout (seconds)
]);

$apiInstance = new \Volcengine\{Service}\Api\{SERVICE}Api(
    $httpClient,
    $config
);

$request = new \Volcengine\{Service}\Model\{Action}Request();
// $request->setParamName("value");

try {
    $resp = $apiInstance->{actionCamelCase}($request);
    print_r($resp);
} catch (Exception $e) {
    echo 'API exception: ', $e->getMessage(), PHP_EOL;
}

要点：

• 配置：\Volcengine\Common\Configuration::getDefaultConfiguration()->setAk()->setSk()->setRegion()
• API 类：\Volcengine\{Service}\Api\{SERVICE}Api — 命名空间中的 Service 使用 PascalCase（例如 Billing），类名使用全大写（例如 BILLINGApi）
• 构造函数：接收 GuzzleHttp\Client() 和 $config
• 请求类：\Volcengine\{Service}\Model\{Action}Request（例如 \Volcengine\Billing\Model\ListAvailableInstancesRequest）
• 通过 setter 设置参数：$request->setProduct("value")
• 方法：$apiInstance->{actionCamelCase}($request)（例如 listAvailableInstances）

步骤 5：展示结果

生成代码后：

1. 在带有正确语言标签的代码块中展示完整代码
2. 列出用户需要安装的依赖项（go get、pip install、npm install、composer require、Maven/Gradle 坐标）
3. 提醒用户设置环境变量：

   export VOLCENGINE_ACCESS_KEY="your-access-key"
   export VOLCENGINE_SECRET_KEY="your-secret-key"
   

4. 说明 API 规范中的重要限制（速率限制、所需权限、数据范围限制等）
5. 如果代码包含高级配置，简要说明各项设置的用途、默认值和调优建议。例如：
   • “重试默认为 3 次，适用于网络错误和限流 — 可通过 WithMaxRetries 调整”
   • “连接超时默认为 30s；对于大型批量查询，可考虑增加超时时间”

回答 SDK 配置问题

当用户询问如何配置或使用 Volcengine SDK（而不是生成 API 调用代码）时，请采用以下方法：

步骤 1：确定用户的需求

常见配置主题：

• 身份验证：AK/SK、STS Token、AssumeRole、OIDC、SAML
• 重试：启用/禁用、最大尝试次数、退避策略、自定义重试条件
• 超时：连接超时、读取超时、单次请求超时
• 代理：HTTP/HTTPS 代理配置
• Endpoint：自定义 Endpoint、基于区域的解析、双栈（IPv6）
• SSL/HTTPS：禁用 SSL 验证、TLS 版本、HTTP 与 HTTPS
• 连接池：池大小、Keep-Alive、空闲连接
• 调试：调试模式、日志记录、中间件
• 错误处理：异常类型、可重试与不可重试错误
• 环境变量：各 SDK 支持的环境变量

步骤 2：查阅参考文档

阅读与用户目标语言对应的参考文件：

语言	参考文件
Go	references/sdk-integration-go.md
Python	references/sdk-integration-python.md
Java	references/sdk-integration-java.md
Node.js	references/sdk-integration-nodejs.md
PHP	references/sdk-integration-php.md

这些文件包含各主要配置主题的简洁代码示例。阅读相关文件，并提供准确、可直接复制粘贴的代码。

如果用户的问题未涵盖在参考文件中，或需要更多细节，请从 GitHub 获取上游完整文档：

语言	上游文档 URL
Go	https://raw.githubusercontent.com/volcengine/volcengine-go-sdk/master/SDK_Integration.md
Python	https://raw.githubusercontent.com/volcengine/volcengine-python-sdk/master/SDK_Integration.md
Java	https://raw.githubusercontent.com/volcengine/volcengine-java-sdk/master/SDK_Integration.md
Node.js	https://raw.githubusercontent.com/volcengine/volcengine-nodejs-sdk/master/SDK_Integration.md
PHP	https://raw.githubusercontent.com/volcengine/volcengine-php-sdk/main/SDK_Integration.md

步骤 3：给出清晰的回答

• 展示完整、可运行的代码片段，演示相关配置
• 说明每项设置的用途和默认值
• 提醒用户注意事项（例如：“禁用 SSL 验证仅适用于测试环境”）
• 如果用户未指定语言，询问他们使用的是哪种语言
• 回答所用语言应与用户提示的语言一致

重要说明

• 始终从 API Explorer 获取数据 — Volcengine API 更新频繁，因此 Explorer 是权威信息来源。不要依赖记忆。
• 如果用户的描述存在歧义（可能对应多个服务或操作），请列出选项并询问用户确认。
• 如果某项服务的 IsSdkAvailable: false，告知用户官方 SDK 可能尚未支持该服务，并提供原始 HTTP 请求示例作为替代方案。
• 对于区域服务，如果用户的资源不在 cn-beijing，提醒其更改区域设置。