第 3 章 · 03 其余语言对照(Go/Java/PHP/Ruby/C#/curl)

第 3 章 · 03 其余语言对照(Go/Java/PHP/Ruby/C#/curl)

本节摘要:除 Python 与 TypeScript 两大主力,官方还提供 Go、Java、PHP、Ruby、C# 五种语言 SDK,以及原始 HTTP(curl)形态。它们在概念上与 Python/TS 完全一致——同样的 messages.create、同样的 system/tools/messages、同样的缓存与思考参数——差异只在语言层面:包名、客户端构造方式、异常类命名、异步模型、是否提供 Tool Runner 与托管代理 SDK。本节合并对照这六种形态的配置差异,不逐篇重复翻译,只讲「与 Python/TS 不同的地方」。读完本节,你能用任一语言接入 Claude API,并知道各 SDK 的能力覆盖边界。

内容来源:Anthropic 官方 Claude API 文档各语言 README(Go/Java/PHP/Ruby/C#/curl,随 Claude Code 分发,从泄露素材库提取),汉化并合并对照。

学习目标

阅读完本节,你应当能够:

1. 在 Go/Java/PHP/Ruby/C# 任一语言里初始化客户端并发起最简 messages 请求。
2. 说清各语言 SDK 的能力覆盖边界(哪些有 Tool Runner、哪些有托管代理、哪些有批处理)。
3. 对照各语言的异常类命名(Python BadRequestError vs Ruby Anthropic::Errors::BadRequestError vs Java BadRequestException 等)。
4. 知道 curl 原始 HTTP 何时用、用时要手处理什么(SSE 解析、beta 头、JSON 序列化)。
5. 选型时能按「有官方 SDK 就用 SDK、无 SDK 才用 curl」的原则决策。

一、能力覆盖对照总表

先看一张总表,各 SDK 的能力覆盖一目了然。概念层全一致,差异在生态成熟度:

💡 读表提示:Python/TS 是全能力主力 SDK;Java 紧随其后;Go 的 Tool Runner 与托管代理都是较新加入;Ruby/PHP/C# 各有侧重缺口(如 PHP/C# 无托管代理,Go/Ruby 无批处理)。选型时先确认你要用的特性在该语言是否支持,不支持就考虑 Python/TS 或原始 HTTP。

二、Go:类型常量与单一错误类型

import (
    "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/option"
)

client := anthropic.NewClient()                              // 默认读 ANTHROPIC_API_KEY
client := anthropic.NewClient(option.WithAPIKey("..."))      // 显式 key

response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
    Model:     anthropic.ModelClaudeOpus4_8,                 // 类型常量,非字符串
    MaxTokens: 16000,
    Messages: []anthropic.MessageParam{
        anthropic.NewUserMessage(anthropic.NewTextBlock("Hello")),
    },
})
​

Go 的特色:

• 类型化模型常量:用 anthropic.ModelClaudeOpus4_8 这类常量,而非字符串字面量——编译期防拼错。
• 内容块用类型 switch:block.AsAny().(type) 分支处理 TextBlock 等,与 TS 的判别联合思路一致。
• 单一错误类型 + 分支:Go 对所有非 2xx 返回一个 *anthropic.Error,用 errors.As 解包后按 StatusCode 分支(详见第 2 章 06 节),不像其它语言每个状态码一个异常类。

⚠️ Go 的限制:Tool Runner 是 beta(BetaToolRunner);托管代理已支持;批处理暂不支持——需要批处理就用 Python/TS 或 curl。Agent SDK(Go)尚未提供。

三、Java:异常以 Exception 结尾

import com.anthropic.client.AnthropicClient;
import com.anthropic.models.*;

AnthropicClient client = AnthropicClient.create();          // 默认读环境变量

MessageCreateParams params = MessageCreateParams.builder()
    .model(Model.CLAUDE_OPUS_4_8)
    .maxTokens(16000)
    .messages(MessageParam.builder()
        .role("user").content("Hello").build())
    .build();
Message response = client.messages().create(params);
​

Java 的特色:异常类名以 Exception 结尾(BadRequestException、RateLimitException、UnauthorizedException、NotFoundException、AnthropicServiceException 基类),符合 Java 命名惯例。错误类型查询用 .errorType() 方法。Tool Runner、托管代理、批处理、文件 API 均支持。Kotlin 与 Scala 共用 Java SDK。

四、PHP:命名参数 camelCase + 独立异常命名空间

$client = \Anthropic\Client::create();                       // 默认读环境变量

$response = $client->messages()->create([
    'model' => 'claude-opus-4-8',
    'max_tokens' => 16000,
    'messages' => [['role' => 'user', 'content' => 'Hello']],
]);
echo $response->content[0]->text;
​

PHP 的特色与坑:

• 顶层命名参数是 camelCase:PHP SDK 的顶层命名参数用 camelCase(如 maxTokens),不是 snake_case wire 名。但嵌套数组键随特性变化(如 'taskBudget'、'skillID')——要从文档示例里复制确切键名,别批量转换。这是 PHP SDK 最易踩的 API 漂移点。
• 异常在独立命名空间:Anthropic\Core\Exceptions\RateLimitException 等,要写全命名空间,不是裸 Anthropic\RateLimitException。
• 用量字段访问:$message->usage->cacheReadInputTokens(camelCase 方法)。

⚠️ 支持范围:PHP 有 Tool Runner、批处理、文件 API,但无托管代理 SDK。需要托管代理就用 Python/TS/Java/Go/Ruby。

五、Ruby:块风格与独立错误命名空间

require "anthropic"

client = Anthropic::Client.new                                # 默认读环境变量

response = client.messages.create(
  model: "claude-opus-4-8",
  max_tokens: 16000,
  messages: [{ role: "user", content: "Hello" }],
)
puts response.content.first.text
​

Ruby 的特色:

• 异常在独立命名空间:Anthropic::Errors::RateLimitError、Anthropic::Errors::BadRequestError 等,要写全 Anthropic::Errors:: 前缀。
• Ruby 风格 API:关键字参数、块式调用,符合 Ruby 习惯。
• 支持 Tool Runner、托管代理、流式、工具调用;无批处理、无文件 API——需要这两者用其它语言。

六、C#:4xx 异常共基类

using Anthropic.SDK;

var client = new AnthropicClient();                           // 默认读环境变量

var response = await client.Messages.CreateAsync(new MessageParameters {
    Model = "claude-opus-4-8",
    MaxTokens = 16000,
    Messages = new List<Message> { new() { Role = "user", Content = "Hello" } },
});
​

C# 的特色:

• 异常命名:所有异常带 Anthropic 前缀(AnthropicBadRequestException、AnthropicRateLimitException、AnthropicNotFoundException),所有 4xx 异常还共继承自 Anthropic4xxException,5xx 用 Anthropic5xxException。
• Tool Runner 是 beta;支持流式、工具、批处理、文件 API;无托管代理 SDK。

七、curl:原始 HTTP,手处理一切

curl(或任何语言的 requests/fetch/httpx)是原始 HTTP 形态,只在项目是 shell/cURL 工程、或语言无官方 SDK 时才用。其余情况优先用 SDK——SDK 替你处理认证、重试、超时、分页、错误类型化、beta 头注入。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 16000,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
​

⚠️ curl 要手处理的细节:(1)认证头用 x-api-key(或 OAuth 的 Authorization: Bearer),别用错;(2)anthropic-version 头必填;(3)beta 特性(托管代理、文件 API、缓存)要手动加对应 beta 头(SDK 会自动加);(4)流式要自己解析 SSE(event: / data: 行);(5)错误是 JSON 体,要自己解析 error.type 字段;(6)重试要自己写指数退避。

八、选型决策:一张图

本节要点回顾

1. 概念全一致:六种形态(含 curl)的 system/tools/messages、缓存、思考、流式参数与 Python/TS 完全相同,差异只在语言层(包名、构造、异常命名、异步模型)。
2. 能力覆盖边界:Python/TS 全能力;Java 紧随;Go 缺批处理;Ruby 缺批处理与文件 API;PHP/C# 缺托管代理。选型先确认特性是否支持。
3. Go 特色:类型化模型常量(ModelClaudeOpus4_8)防拼错;单一 *anthropic.Error + errors.As + StatusCode 分支。
4. Java 特色:异常以 Exception 结尾,错误类型用 .errorType();Kotlin/Scala 共用。
5. PHP 坑:顶层命名参数是 camelCase(maxTokens),嵌套键随特性变化要照抄文档;异常在 Anthropic\Core\Exceptions\ 命名空间。
6. Ruby/C# 特色:Ruby 异常在 Anthropic::Errors::;C# 异常带 Anthropic 前缀,4xx 共基类 Anthropic4xxException。
7. curl 何时用:shell/cURL 工程或无 SDK 语言才用;要手处理认证头、version 头、beta 头、SSE 解析、重试——有 SDK 就别用 curl。

第 3 章到此结束——你已能任选语言接入 Claude API。第 4 章进入 Agent 设计与托管代理:如何设计工具表面、管理长程上下文,以及如何用 managed agents 让平台替你跑有状态的 agent 循环。