Claude API 开发者实战指南：从基础调用到 Tool Use 高级模式

Anthropic 的 Claude 模型在 2025-2026 年完成了从"学术派选手"到"生产级主力"的蜕变——Claude 4 Sonnet 在 SWE-bench 上以 72.7% 的成绩刷新了编码能力纪录，Claude 4 Opus 在复杂推理任务上的表现让 GPT-4o 望尘莫及。更关键的是，Claude API 的 Tool Use（工具调用）模式和超长上下文窗口（200K tokens）让它成为构建 AI Agent 的首选底层模型。如果你还在用 OpenAI 的接口"一招鲜"，是时候看看 Claude API 到底能做什么不一样的事情了。

🔑 一、Claude API 基础：快速上手与核心概念

1.1 认证与 SDK 安装

Claude API 使用 API Key 认证，支持 Node.js 和 Python 两种官方 SDK。与 OpenAI API 的最大区别是：Claude 的 Messages API 强制要求 system 参数与 messages 分离，且每条消息必须明确指定 role（user/assistant）。

# Node.js SDK 安装
npm install @anthropic-ai/sdk

# Python SDK 安装
pip install anthropic

// Node.js 基础调用示例
import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY, // 推荐使用环境变量
})

const message = await client.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  system: '你是一个专业的 TypeScript 开发助手，回答要简洁准确。',
  messages: [
    { role: 'user', content: '解释 TypeScript 中 const enum 和普通 enum 的区别' }
  ],
})

console.log(message.content[0].text)
// usage 信息：input_tokens, output_tokens
console.log('Token 用量:', message.usage)

# Python 基础调用示例
import anthropic

client = anthropic.Anthropic()  # 自动读取 ANTHROPIC_API_KEY 环境变量

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="你是一个专业的 Python 开发助手。",
    messages=[
        {"role": "user", "content": "用 Python 实现一个 LRU Cache"}
    ]
)

print(message.content[0].text)

📌 记住：Claude API 的 max_tokens 是必填参数，不像 OpenAI 那样有默认值。忘记设置会直接报错。

1.2 模型选型：Sonnet vs Opus vs Haiku

Claude 提供三个系列的模型，定位差异明显：

⚡ **关键结论：**90% 的应用场景选 Claude 4 Sonnet 就够了。它在编码能力上与 Opus 差距不到 5%，但成本只有 1/5。只有在需要深度推理（如数学证明、多步逻辑分析）时才考虑 Opus。

1.3 多轮对话的消息结构

Claude 的多轮对话通过 messages 数组实现，必须严格交替 user/assistant 角色：

// 多轮对话示例
const messages = [
  { role: 'user', content: '什么是 React Server Components？' },
  { role: 'assistant', content: 'React Server Components 是...' },  // 上一轮的回复
  { role: 'user', content: '它和 SSR 有什么区别？' },              // 新问题
]

const response = await client.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages,
})

⚠️ **警告：**如果 messages 数组中出现连续两个相同 role 的消息，API 会返回 400 错误。这与 OpenAI API 的行为不同——OpenAI 会自动合并相邻的同角色消息。

🛠️ 二、Tool Use 实战：让 Claude 调用你的函数

Tool Use 是 Claude API 最强大的功能之一，也是构建 AI Agent 的核心能力。与 OpenAI 的 Function Calling 相比，Claude 的 Tool Use 有两个显著优势：支持并行工具调用和更准确的参数推理。

2.1 基础 Tool Use 流程

Tool Use 的核心流程是：定义工具 → 发送请求 → Claude 决定调用 → 执行工具 → 返回结果 → Claude 生成最终回复。

// 完整的 Tool Use 实战示例
import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic()

// 第一步：定义工具
const tools = [
  {
    name: 'get_weather',
    description: '获取指定城市的当前天气信息。当用户询问天气时使用此工具。',
    input_schema: {
      type: 'object',
      properties: {
        city: {
          type: 'string',
          description: '城市名称，如"北京"、"上海"',
        },
        unit: {
          type: 'string',
          enum: ['celsius', 'fahrenheit'],
          description: '温度单位，默认摄氏度',
        },
      },
      required: ['city'],
    },
  },
  {
    name: 'search_products',
    description: '搜索商品库中的产品。当用户询问商品信息或想购买商品时使用。',
    input_schema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: '搜索关键词' },
        category: { type: 'string', description: '商品分类' },
        max_price: { type: 'number', description: '最高价格（元）' },
      },
      required: ['query'],
    },
  },
]

// 第二步：发送请求，带上工具定义
let response = await client.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  tools,
  messages: [
    { role: 'user', content: '北京今天天气怎么样？' }
  ],
})

// 第三步：检查 Claude 是否要调用工具
console.log('Stop reason:', response.stop_reason)  // "tool_use"
console.log('Content:', response.content)
// [
//   { type: "text", text: "我来帮你查询北京的天气。" },
//   { type: "tool_use", id: "toolu_xxx", name: "get_weather", input: { city: "北京" } }
// ]

// 第四步：执行工具并返回结果
if (response.stop_reason === 'tool_use') {
  const toolUseBlock = response.content.find(b => b.type === 'tool_use')

  // 模拟工具执行
  const weatherResult = { temp: 28, condition: '晴', humidity: 45 }

  // 第五步：将工具结果发回给 Claude
  const finalResponse = await client.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    tools,
    messages: [
      { role: 'user', content: '北京今天天气怎么样？' },
      { role: 'assistant', content: response.content },
      {
        role: 'user',
        content: [{
          type: 'tool_result',
          tool_use_id: toolUseBlock.id,
          content: JSON.stringify(weatherResult),
        }],
      },
    ],
  })

  console.log(finalResponse.content[0].text)
  // "北京今天天气晴朗，气温 28°C，湿度 45%，非常适合户外活动！"
}

2.2 Tool Use 高级技巧

在生产环境中，Tool Use 需要处理更多边界情况。以下是三个关键技巧：

技巧一：工具错误处理

当工具执行失败时，需要将错误信息返回给 Claude，让它生成用户友好的错误提示：

// 工具执行失败时的处理
const toolResult = {
  type: 'tool_result',
  tool_use_id: toolUseBlock.id,
  content: 'Error: API 请求超时，无法获取天气数据',
  is_error: true,  // 关键字段：告诉 Claude 这是一个错误结果
}

技巧二：强制使用特定工具

通过 tool_choice 参数强制 Claude 调用某个工具，或禁止 Claude 自主决定：

// 强制使用 get_weather 工具
const response = await client.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  tools,
  tool_choice: { type: 'tool', name: 'get_weather' },  // 强制调用
  messages: [{ role: 'user', content: '帮我查一下天气' }],
})

// 禁止使用工具（让 Claude 自己回答）
tool_choice: { type: 'none' }

// 让 Claude 自动决定（默认）
tool_choice: { type: 'auto' }

技巧三：并行工具调用

Claude 可以在一次回复中请求调用多个工具，你需要并行执行它们：

// Claude 可能同时请求多个工具调用
// content: [
//   { type: "tool_use", id: "toolu_1", name: "get_weather", input: { city: "北京" } },
//   { type: "tool_use", id: "toolu_2", name: "get_weather", input: { city: "上海" } },
// ]

// 并行执行所有工具调用
const toolUseBlocks = response.content.filter(b => b.type === 'tool_use')
const results = await Promise.all(
  toolUseBlocks.map(async (block) => {
    const result = await executeTool(block.name, block.input)
    return {
      type: 'tool_result',
      tool_use_id: block.id,
      content: JSON.stringify(result),
    }
  })
)

💡 **提示：**Claude 的并行工具调用能力在处理"同时查多个城市天气"、"批量获取数据"等场景下非常实用。OpenAI 的 Function Calling 也支持并行调用，但 Claude 的触发更准确。

🖼️ 三、Vision 多模态与 Streaming 流式输出

3.1 图片理解（Vision）

Claude 支持在 messages 中直接传入图片（base64 或 URL），用于图片分析、OCR、图表解读等场景：

// 图片分析示例：识别图片中的代码
const response = await client.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{
    role: 'user',
    content: [
      {
        type: 'image',
        source: {
          type: 'base64',
          media_type: 'image/png',
          image_base64: 'iVBORw0KGgo...'  // 图片的 base64 编码
        }
      },
      {
        type: 'text',
        text: '请分析这张截图中的代码，指出潜在的 bug 并给出修复建议。'
      }
    ]
  }]
})

也可以通过 URL 传入图片（仅支持可公开访问的 URL）：

content: [
  {
    type: 'image',
    source: {
      type: 'url',
      url: 'https://example.com/screenshot.png'
    }
  },
  { type: 'text', text: '描述这张图片的内容' }
]

⚠️ **警告：**Claude Vision 对图片大小有限制——单张图片不超过 10MB，且会消耗额外的 input tokens。一张 1024x1024 的图片大约消耗 1600 tokens。

3.2 Streaming 流式输出

对于聊天类应用，流式输出是必须的——用户不想等 5 秒才看到第一个字。Claude API 支持 Server-Sent Events (SSE) 流式输出：

// Node.js 流式输出
const stream = client.messages.stream({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 2048,
  messages: [{ role: 'user', content: '用 TypeScript 写一个简单的 ORM' }],
})

// 逐块接收文本
stream.on('text', (text) => {
  process.stdout.write(text)  // 实时输出到控制台
})

// 完成后获取完整消息
const finalMessage = await stream.finalMessage()
console.log('\n\n总 Token 用量:', finalMessage.usage)

# Python 流式输出
with client.messages.stream(
    model="claude-sonnet-4-20250514",
    max_tokens=2048,
    messages=[{"role": "user", "content": "用 Python 实现快速排序"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

在 Web 应用中，你可以将流式输出转发给前端：

// Express + Streaming 转发示例
import express from 'express'
import Anthropic from '@anthropic-ai/sdk'

const app = express()
const client = new Anthropic()

app.get('/api/chat', async (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream')
  res.setHeader('Cache-Control', 'no-cache')
  res.setHeader('Connection', 'keep-alive')

  const stream = client.messages.stream({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 2048,
    messages: [{ role: 'user', content: req.query.q }],
  })

  stream.on('text', (text) => {
    res.write(`data: ${JSON.stringify({ text })}\n\n`)
  })

  stream.on('finalMessage', () => {
    res.write('data: [DONE]\n\n')
    res.end()
  })
})

💰 四、成本优化与生产最佳实践

4.1 Prompt Caching（提示缓存）

Claude API 支持 Prompt Caching，可以将频繁使用的 system prompt 和工具定义缓存起来，避免重复计算。缓存命中后，cached tokens 的成本仅为正常价格的 10%。

// 启用 Prompt Caching
const response = await client.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  system: [{
    type: 'text',
    text: '你是一个专业的代码审查助手...' + veryLongSystemPrompt,  // 长 system prompt
    cache_control: { type: 'ephemeral' },  // 关键：标记为可缓存
  }],
  tools: [{
    name: 'search_code',
    description: '搜索代码库...',
    input_schema: { /* ... */ },
    cache_control: { type: 'ephemeral' },  // 工具定义也可以缓存
  }],
  messages: [{ role: 'user', content: '帮我审查这段代码' }],
})

// 查看缓存命中情况
console.log('Cache creation tokens:', message.usage.cache_creation_input_tokens)
console.log('Cache read tokens:', message.usage.cache_read_input_tokens)

📌 **记住：**Prompt Caching 的最小缓存长度是 1024 tokens（Haiku）或 2048 tokens（Sonnet/Opus）。短于此长度的 prompt 不会被缓存。

4.2 成本对比：Claude vs OpenAI vs DeepSeek

⚡ 关键结论：纯成本考虑选 DeepSeek；需要最强 Tool Use 和 Vision 能力选 Claude；通用场景 GPT-4o 仍然可靠。在实际项目中，建议多模型路由——简单任务用 Haiku/DeepSeek，复杂任务用 Sonnet，关键推理用 Opus。

4.3 生产环境注意事项

✅ 推荐做法：

• 使用 max_tokens 限制输出长度，避免意外的高额账单
• 实现重试机制（指数退避），处理 429 Rate Limit 和 529 Overloaded 错误
• 使用 Prompt Caching 降低 system prompt 的重复计算成本
• 记录每次 API 调用的 usage 信息，建立成本监控

❌ 避免做法：

• 不要在前端直接调用 Claude API（会暴露 API Key）
• 不要忽略 stop_reason 的检查——可能是 max_tokens 截断而非正常完成
• 不要在 messages 中传递过多的历史对话（每轮都算 input tokens）
• 不要对所有任务都用 Opus（成本是 Sonnet 的 5 倍）

// 生产级错误处理与重试
async function callWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn()
    } catch (error) {
      if (error.status === 429 || error.status === 529) {
        const delay = Math.pow(2, i) * 1000 + Math.random() * 1000
        console.log(`Rate limited, retrying in ${delay}ms...`)
        await new Promise(r => setTimeout(r, delay))
        continue
      }
      throw error  // 非限流错误直接抛出
    }
  }
  throw new Error('Max retries exceeded')
}

// 使用示例
const response = await callWithRetry(() =>
  client.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    messages: [{ role: 'user', content: '你好' }],
  })
)

🎯 总结与工具推荐

Claude API 在 2026 年已经成为 LLM 应用开发的核心选择之一，尤其是在 Tool Use、长上下文和 Vision 能力上具有明显优势。以下是实践建议：

1. 首选 Claude 4 Sonnet：性价比最优，覆盖 90% 的应用场景
2. Tool Use 是杀手锏：在需要调用外部工具的 Agent 场景中，Claude 的准确率显著高于竞品
3. Prompt Caching 必须用：对于有固定 system prompt 的应用，缓存可以节省 90% 的 input 成本
4. 多模型路由是趋势：用 Haiku 处理简单分类，Sonnet 处理通用任务，Opus 处理关键推理

相关工具推荐：

• 🔧 jsjson.com JSON 格式化工具 — 处理 Claude API 返回的 JSON 数据
• 🔧 jsjson.com Base64 编码工具 — 处理 Vision API 的图片编码
• 🔧 jsjson.com JWT 解析工具 — 调试 API 认证 Token

本文基于 Anthropic API 2026 年 6 月最新文档编写，API 细节可能随版本更新而变化。建议参考 Anthropic 官方文档 获取最新信息。