API 开发

Node.js 调用 Claude API：多轮、流式与 Express 接口

用官方 JavaScript/TypeScript SDK 接入服务端应用，处理多内容块、流结束、并发和安全边界。

原发表：2026-03-25修订：2026-10-04编辑说明

运行时和配置

安装 @anthropic-ai/sdk，保存 package-lock.json，并选择仍受支持的 Node.js LTS 版本；当前 SDK 文档列出的 Node 范围从 20 LTS 起，但已结束支持的版本不应继续作为新项目默认。示例采用 ESM，可保存为 .mjs。TypeScript 项目应开启严格类型检查并使用 SDK 自带类型，不能把网络结果无条件断言为字符串。

ANTHROPIC_API_KEY 和 CLAUDE_MODEL 只在服务端读取。不要开启浏览器直接持钥模式，也不要把变量放进会被前端打包的公开环境配置。模型 ID 查账号与官方目录，本文不固定某个历史版本。

普通调用与多轮历史

下面将客户端作为依赖注入，便于离线模拟。只有 end_turn 才保存完整轮次；截断、工具调用和拒绝由上层处理。历史属于一个已认证会话，不得设成所有用户共享的全局数组。

javascript · 示例

export async function ask(client, model, history, question) {
  const pending = [...history, { role: "user", content: question }];
  const message = await client.messages.create({
    model, max_tokens: 700, system: "用中文回答，不确定时说明。",
    messages: pending
  });
  if (message.stop_reason === "end_turn") {
    history.push({ role: "user", content: question },
                 { role: "assistant", content: message.content });
  }
  return { text: message.content.filter(b => b.type === "text").map(b => b.text).join(""),
           stop_reason: message.stop_reason, usage: message.usage };
}

可保存为 assistant.mjs；JavaScript 语法与假客户端测试通过。

流式辅助函数

不要在收到第一个 text 事件时就记录“请求成功”。等待 finalMessage 获取 stop_reason 和 usage，异常时保留未完成状态。这个函数把展示交给 onText；HTTP 适配层还必须处理用户断线和背压。

javascript · 示例

export async function streamAnswer(client, model, question, onText) {
  const stream = client.messages.stream({
    model, max_tokens: 700,
    messages: [{ role: "user", content: question }]
  }).on("text", onText);
  return await stream.finalMessage();
}

官方流式辅助方法的调用形状；未进行在线流式测试。

Express：先认证，再读取业务输入

Express 接入时把认证作为必须提供的中间件；它要验证令牌与主体，不是“存在请求头就通过”。下面演示普通响应路由，避免把未完成的流强行包装成成功 JSON。createApp 不自动监听端口。

javascript · 示例

import express from "express";

export function createApp({ client, model, authenticate }) {
  if (typeof authenticate !== "function") throw new Error("authentication_required");
  const app = express();
  app.use(authenticate);
  app.use(express.json({ limit: "16kb" }));
  app.post("/chat", async (req, res) => {
    const text = req.body?.text;
    if (typeof text !== "string" || !text.trim() || text.length > 4000) {
      return res.status(400).json({ error: "invalid_text" });
    }
    try {
      const msg = await client.messages.create({
        model, max_tokens: 700, messages: [{ role: "user", content: text }]
      });
      return res.json({ text: msg.content.filter(b => b.type === "text").map(b => b.text).join(""),
                        stop_reason: msg.stop_reason });
    } catch {
      return res.status(502).json({ error: "upstream_unavailable" });
    }
  });
  return app;
}

Express 适配骨架；认证实现必须由应用提供，未声明已完成生产鉴权。

并发、错误与验收

不要直接 Promise.all 数千个模型请求。为任务队列设置最大在途数、排队容量和总期限；同一会话串行处理，避免历史覆盖。SDK 自动重试与队列重试只选一个明确负责层，不能发生指数叠加。

流式 HTTP 版本应发送 delta、done、error 事件，断线取消上游，慢客户端触发背压或停止。部署前测试无效输入、认证失败、非文本块、max_tokens、上游超时与流中途失败；核对日志不含请求正文和密钥。本文检查了 JS 语法和多轮假数据，未安装或联调真实 SDK/Express 服务；依赖兼容仍须在项目锁定版本下验证。

参考来源

资料核对日期：2026-10-04。涉及产品与账户条件时，请以当前官方说明为准。