TypeScript SDK 实战项目

上一篇用 Python 做了文档问答，这篇用 TypeScript + Next.js 构建一个完整的 Web 聊天应用——包含流式响应、会话管理和前端渲染。这是最接近生产级 AI 应用的入门项目。

你将学到什么

• Next.js API Route 集成 Claude SDK
• 流式响应（SSE）的实现
• 前端实时渲染流式文本
• 会话管理和错误处理

项目结构

chat-app/
  app/
    api/chat/route.ts     # API 端点
    page.tsx              # 前端页面
  lib/
    claude.ts             # Claude 客户端封装
  package.json

安装依赖

npx create-next-app@latest chat-app --typescript --tailwind
cd chat-app
npm install @anthropic-ai/sdk

lib/claude.ts — SDK 封装

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

export async function* streamChat(
  messages: Anthropic.MessageParam[],
  system?: string
) {
  const stream = client.messages.stream({
    model: "claude-sonnet-4-6",
    max_tokens: 4096,
    system: system || "你是一位友好的中文助手。",
    messages,
  });

  for await (const event of stream) {
    if (
      event.type === "content_block_delta" &&
      event.delta.type === "text_delta"
    ) {
      yield event.delta.text;
    }
  }
}

app/api/chat/route.ts — API 端点

import { streamChat } from "@/lib/claude";

export async function POST(req: Request) {
  const { messages, system } = await req.json();

  const encoder = new TextEncoder();
  const readable = new ReadableStream({
    async start(controller) {
      try {
        for await (const chunk of streamChat(messages, system)) {
          controller.enqueue(encoder.encode(chunk));
        }
      } catch (error) {
        controller.enqueue(
          encoder.encode("[ERROR] 请求失败，请重试")
        );
      } finally {
        controller.close();
      }
    },
  });

  return new Response(readable, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}

前端核心逻辑

// 发送消息并流式接收
async function sendMessage(input: string) {
  const newMessages = [
    ...messages,
    { role: "user" as const, content: input },
  ];

  const response = await fetch("/api/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ messages: newMessages }),
  });

  const reader = response.body?.getReader();
  const decoder = new TextDecoder();
  let assistantText = "";

  while (reader) {
    const { done, value } = await reader.read();
    if (done) break;
    assistantText += decoder.decode(value);
    // 实时更新 UI
    setCurrentResponse(assistantText);
  }

  // 完成后保存到消息历史
  setMessages([
    ...newMessages,
    { role: "assistant", content: assistantText },
  ]);
}

流式响应的优势

• 即时反馈：用户不用等 Claude 生成完整回答
• 更好的体验：逐字出现，像真人在打字
• 节省等待：长回答可能需要 10-20 秒，流式让用户立刻看到内容

错误处理

// 在 API 端点中添加错误处理
try {
  for await (const chunk of streamChat(messages)) {
    controller.enqueue(encoder.encode(chunk));
  }
} catch (error) {
  if (error instanceof Anthropic.RateLimitError) {
    controller.enqueue(encoder.encode("请求太频繁，请稍后重试"));
  } else if (error instanceof Anthropic.AuthenticationError) {
    controller.enqueue(encoder.encode("API Key 配置错误"));
  }
}

扩展方向

• 添加对话历史持久化：保存到数据库
• 支持多模型切换：前端选择 Opus/Sonnet/Haiku
• 添加工具调用：集成搜索、计算等工具
• 部署到 Vercel：一键部署上线

实战练习

Tip: 搭建你的第一个 AI Web 应用。

1. 用上面的代码创建项目并运行
2. 添加一个「清空对话」按钮
3. 在前端显示每次请求的 token 用量

关键要点

Note: 本文核心总结

• Next.js API Route + Claude SDK 是构建 AI Web 应用的黄金组合
• 流式响应通过 ReadableStream + SSE 实现
• 前端用 reader.read() 循环实时渲染
• 错误处理和会话管理是生产级应用的必要组件

延伸阅读

• 下一篇：错误处理与速率限制