1. 项目概述从“豆包”到“菜包”的AI全栈之旅最近在AI圈子里“豆包”这个名字挺火的不少朋友都在讨论。但说实话作为一个喜欢自己动手鼓捣的开发者我更享受那种从零开始把一个想法变成可运行、可交互的产品的过程。与其用现成的“豆包”不如自己亲手做一个哪怕它现在还只是个“菜包”。这个项目就是一次完整的新手向AI全栈实战使用Cursor这个新兴的AI编程工具从零开始复刻一个具备基础对话能力的AI聊天助手。这不仅仅是调用一个API那么简单它涉及到前端界面、后端逻辑、AI模型集成、状态管理、乃至简单的部署上线是一个麻雀虽小五脏俱全的练手项目。无论你是想入门前端、后端还是对AI应用开发感兴趣这个“菜包”项目都能让你对现代Web应用和AI集成有一个清晰、落地的认识。2. 核心思路与技术选型解析2.1 为什么选择“复刻聊天助手”作为练手项目聊天助手看似简单一个输入框一个发送按钮加上对话历史展示。但正是这种简单的表象下隐藏了全栈开发的几乎所有核心环节。前端需要处理用户输入、实时渲染消息流、管理复杂的UI状态如加载中、错误提示。后端需要设计清晰的API接口、处理并发请求、与AI服务进行安全可靠的通信。AI集成部分你需要理解如何调用大语言模型的API如何处理上下文Context如何对返回的流式数据进行解析。此外还有项目工程化的考量如何组织代码结构、管理环境变量、进行基本的错误处理和日志记录。通过完成这样一个项目你能系统地串起这些知识点而不是孤立地学习某个框架或API。更重要的是你能获得一个“看得见、摸得着”的成果这种正向反馈对于学习动力至关重要。2.2 核心工具栈Cursor Vite React Node.js OpenAI API这个技术栈的选择平衡了现代性、效率和学习曲线。Cursor这不是一个传统的框架或语言而是一个深度融合了AI能力的代码编辑器。它将是我们的“副驾驶”。在本项目中Cursor的核心价值在于1)快速生成样板代码我们可以用自然语言描述需求让它生成React组件、Express路由的骨架。2)解释代码与调试遇到不理解的库或报错可以直接询问Cursor。3)代码重构与优化建议它可以帮我们审查代码提出改进意见。这能极大降低新手在初期查阅文档和调试上的时间成本让我们更专注于逻辑和理解。Vite React前端部分选择Vite和React。Vite的启动速度和热更新体验极佳能提供流畅的开发体验。React的组件化思想清晰生态成熟是构建交互式UI的不二之选。我们将使用函数组件和Hooks如useState,useEffect来管理状态和副作用。Node.js Express后端选择Node.js和轻量级的Express框架。Node.js的非阻塞I/O模型适合处理像AI API调用这类可能耗时的I/O操作。Express则提供了最小化、灵活的路由和中间件支持让我们能快速搭建起API服务器。OpenAI API (或兼容API)这是我们“菜包”的“大脑”。我们将使用其chat.completions接口。选择OpenAI API是因为其文档清晰、稳定且Cursor对其有很好的理解能辅助生成相关的调用代码。当然你也可以替换为其他兼容OpenAI API格式的服务如DeepSeek、Ollama本地模型等这只需要修改API Base URL和密钥即可后端接口可以保持不变这体现了我们设计的灵活性。注意使用任何第三方AI API都需要注意成本。OpenAI API按Token收费在开发测试阶段务必设置使用量限制并避免在代码中提交真实的API密钥到公开仓库。2.3 项目架构设计前后端分离我们将采用经典的前后端分离架构。前端是一个独立的React应用运行在http://localhost:5173Vite默认端口。后端是一个Express服务器运行在http://localhost:3000。前端通过HTTP请求使用fetch或axios与后端通信。这种分离的好处是职责清晰前端专注于展示和用户交互后端专注于业务逻辑和数据处理并且未来可以独立部署和扩展。数据流大致如下用户在网页输入框输入问题点击发送。前端将问题文本、以及可选的对话历史通过POST请求发送到后端接口如/api/chat。后端接收到请求验证后构造符合OpenAI API要求的消息格式包含role和content的数组并调用OpenAI API。后端将OpenAI API返回的流式数据Stream或完整响应转发给前端。前端接收到数据后实时或一次性更新对话界面展示AI的回答。3. 开发环境搭建与项目初始化3.1 使用Cursor初始化前端项目首先我们创建前端项目。打开Cursor在终端中导航到你的工作目录执行以下命令npm create vitelatest my-ai-chat-frontend -- --template react cd my-ai-chat-frontend npm install这行命令会使用Vite官方工具创建一个基于React模板的新项目。进入项目目录并安装依赖后你可以用npm run dev启动开发服务器。此时一个基础的React应用就跑起来了。接下来我们需要安装一些额外的UI库和工具来加速开发。这里我选择Tailwind CSS进行快速样式构建以及axios用于更优雅地处理HTTP请求。npm install -D tailwindcss postcss autoprefixer npx tailwindcss init -p npm install axios安装完成后需要配置Tailwind。根据其官方文档修改tailwind.config.js和src/index.css。这个过程Cursor可以很好地协助你完成你可以直接问它“如何在Vite React项目中配置Tailwind CSS”它会给出准确的步骤和代码片段。3.2 使用Cursor初始化后端项目在前端项目同级目录下我们新建一个后端项目。mkdir my-ai-chat-backend cd my-ai-chat-backend npm init -y npm install express dotenv cors openai这里我们安装了核心依赖express是Web框架dotenv用于管理环境变量特别是API密钥cors用于处理前端跨域请求openai是OpenAI的官方Node.js SDK它封装了API调用比手动写fetch更便捷。初始化后在项目根目录创建两个关键文件.env和index.js。 在.env文件中存放你的敏感配置OPENAI_API_KEYsk-your-actual-api-key-here PORT3000在index.js中我们可以让Cursor帮忙生成一个基础的Express服务器骨架。你可以输入提示“创建一个Express服务器读取.env的端口设置CORS并创建一个/api/chat的POST接口暂时返回一个测试JSON。” Cursor会生成类似下面的代码const express require(express); const cors require(cors); require(dotenv).config(); const OpenAI require(openai); const app express(); const port process.env.PORT || 3000; // 初始化OpenAI客户端从环境变量读取密钥 const openai new OpenAI({ apiKey: process.env.OPENAI_API_KEY, }); // 中间件 app.use(cors()); // 允许前端跨域 app.use(express.json()); // 解析JSON请求体 // 测试路由 app.get(/, (req, res) { res.json({ message: AI Chat Backend is running! }); }); // 聊天接口 app.post(/api/chat, async (req, res) { // 暂时返回测试数据 res.json({ reply: This is a test reply from the backend. }); }); app.listen(port, () { console.log(Backend server listening on port ${port}); });用node index.js启动后端服务器。至此前后端的基础架子就搭好了。4. 前端核心组件与状态管理实现4.1 构建聊天界面组件前端的主要任务是提供一个美观易用的聊天界面。我们可以在src/App.jsx中重构。这个界面通常包含以下几个部分消息列表区域用于展示用户和AI的对话历史。输入区域包含一个文本输入框和一个发送按钮。状态指示器如“AI正在思考...”的加载状态。我们可以让Cursor协助我们构建组件。提示词可以是“创建一个React聊天组件包含一个消息列表区分用户和AI一个底部的输入框和发送按钮使用Tailwind CSS美化并管理消息列表的状态。”Cursor生成的代码可能需要调整但会提供一个很好的起点。核心状态通常是一个消息数组每条消息包含id,role‘user’ 或 ‘assistant’,content。import { useState, useRef, useEffect } from react; import axios from axios; import SendIcon from ./assets/send.svg; // 假设有个发送图标 function App() { const [messages, setMessages] useState([]); const [inputText, setInputText] useState(); const [isLoading, setIsLoading] useState(false); const messagesEndRef useRef(null); // 自动滚动到最新消息 useEffect(() { messagesEndRef.current?.scrollIntoView({ behavior: smooth }); }, [messages]); const handleSend async () { if (!inputText.trim() || isLoading) return; const userMessage { id: Date.now(), role: user, content: inputText }; setMessages(prev [...prev, userMessage]); setInputText(); setIsLoading(true); try { // 调用后端接口 const response await axios.post(http://localhost:3000/api/chat, { message: inputText, history: messages, // 可选发送历史上下文 }); const aiMessage { id: Date.now() 1, role: assistant, content: response.data.reply }; setMessages(prev [...prev, aiMessage]); } catch (error) { console.error(Error calling chat API:, error); const errorMessage { id: Date.now() 1, role: assistant, content: 抱歉我暂时无法回答。请检查网络或后端服务。 }; setMessages(prev [...prev, errorMessage]); } finally { setIsLoading(false); } }; const handleKeyPress (e) { if (e.key Enter !e.shiftKey) { e.preventDefault(); handleSend(); } }; return ( div classNameflex flex-col h-screen bg-gray-50 {/* 标题栏 */} header classNamebg-white shadow p-4 h1 classNametext-2xl font-bold text-center text-gray-800我的菜包AI助手/h1 /header {/* 消息列表 */} div classNameflex-1 overflow-y-auto p-4 space-y-4 {messages.map(msg ( div key{msg.id} className{flex ${msg.role user ? justify-end : justify-start}} div className{max-w-xs md:max-w-md lg:max-w-lg rounded-2xl px-4 py-2 ${msg.role user ? bg-blue-500 text-white rounded-br-none : bg-gray-200 text-gray-800 rounded-bl-none }} {msg.content} /div /div ))} {isLoading ( div classNameflex justify-start div classNamebg-gray-200 text-gray-800 rounded-2xl rounded-bl-none px-4 py-2 div classNameflex space-x-1 div classNamew-2 h-2 bg-gray-500 rounded-full animate-bounce/div div classNamew-2 h-2 bg-gray-500 rounded-full animate-bounce style{{ animationDelay: 0.1s }}/div div classNamew-2 h-2 bg-gray-500 rounded-full animate-bounce style{{ animationDelay: 0.2s }}/div /div /div /div )} div ref{messagesEndRef} / /div {/* 输入区域 */} div classNameborder-t bg-white p-4 div classNameflex items-center space-x-2 textarea classNameflex-1 border rounded-2xl p-3 resize-none focus:outline-none focus:ring-2 focus:ring-blue-300 placeholder和菜包聊点什么... rows2 value{inputText} onChange{(e) setInputText(e.target.value)} onKeyDown{handleKeyPress} disabled{isLoading} / button onClick{handleSend} disabled{isLoading || !inputText.trim()} classNamebg-blue-500 hover:bg-blue-600 disabled:bg-blue-300 text-white rounded-2xl p-3 px-6 transition-colors img src{SendIcon} alt发送 classNamew-6 h-6 / /button /div p classNametext-xs text-gray-500 text-center mt-2菜包努力成长中回答可能不完美请多包涵~/p /div /div ); } export default App;这段代码构建了一个完整的聊天界面。useState管理消息、输入和加载状态。useEffect和useRef实现了发送消息后自动滚动到底部。handleSend函数是核心它先更新本地UI然后异步调用后端接口并根据结果更新消息列表。错误处理也包含在内。4.2 实现流式响应以提升体验上面的代码是一次性获取AI的完整回复。为了获得更像真人的、逐字打印的体验我们可以使用流式响应。这需要后端和前端配合修改。后端修改调用OpenAI API时设置stream: true并将接收到的数据流Stream通过Server-Sent Events (SSE) 或直接以流的形式pipe到响应中。前端修改不再使用axios等待完整响应而是使用fetchAPI处理流式数据。我们需要逐块chunk读取响应体并实时更新最后一条AI消息的内容。这是一个更高级但体验更好的特性。你可以向Cursor提问“如何在React中从fetch流式响应中实时更新UI” 它会引导你使用response.body.getReader()和TextDecoder来逐步读取和处理数据。实现流式响应后AI的回答会像打字一样逐个字符出现体验大幅提升。5. 后端API与AI模型集成实战5.1 完善/api/chat接口逻辑现在我们来充实后端的核心接口。目标是从前端接收用户消息和可选的历史记录调用OpenAI API并返回结果。我们需要处理上下文让AI能记住之前的对话。app.post(/api/chat, async (req, res) { const userMessage req.body.message; const history req.body.history || []; // 前端传来的历史消息 if (!userMessage || typeof userMessage ! string) { return res.status(400).json({ error: Invalid message }); } // 1. 构造对话历史格式 const messagesForAI []; // 将前端的历史记录格式转换为OpenAI需要的格式 history.forEach(msg { messagesForAI.push({ role: msg.role, content: msg.content }); }); // 加入最新的用户消息 messagesForAI.push({ role: user, content: userMessage }); // 2. 设置请求参数 const requestPayload { model: gpt-3.5-turbo, // 可根据需要更换模型如 gpt-4 messages: messagesForAI, max_tokens: 1000, // 限制回复长度控制成本 temperature: 0.7, // 控制创造性0-2之间越高越随机 stream: false, // 先实现非流式稳定后再改流式 }; try { // 3. 调用OpenAI API const completion await openai.chat.completions.create(requestPayload); // 4. 提取AI回复 const aiReply completion.choices[0]?.message?.content || 未收到回复; // 5. 返回给前端 res.json({ reply: aiReply }); } catch (error) { console.error(OpenAI API Error:, error); // 更友好的错误处理 let errorMessage AI服务暂时不可用; if (error.response) { errorMessage API错误: ${error.response.status} - ${error.response.data.error?.message || 未知错误}; } else if (error.request) { errorMessage 网络错误无法连接到AI服务; } res.status(500).json({ error: errorMessage }); } });这段代码完成了核心的集成工作。它构造了符合OpenAI API要求的消息数组包含了对话历史使得AI能进行多轮有上下文的对话。max_tokens和temperature是两个关键参数需要根据实际场景调整。同时我们也添加了基本的错误处理将API错误信息清晰地返回给前端。5.2 实现流式响应接口要将上面的接口改为流式改动主要在于API调用和响应处理。app.post(/api/chat-stream, async (req, res) { // ... 参数验证和消息构造同上 ... // 设置响应头表明是流式传输 res.setHeader(Content-Type, text/event-stream); res.setHeader(Cache-Control, no-cache); res.setHeader(Connection, keep-alive); try { const stream await openai.chat.completions.create({ ...requestPayload, stream: true, // 关键开启流式 }); // 逐块读取流并发送给前端 for await (const chunk of stream) { const content chunk.choices[0]?.delta?.content || ; if (content) { // 以SSE格式发送数据 res.write(data: ${JSON.stringify({ content })}\n\n); } } // 发送结束标志 res.write(data: [DONE]\n\n); res.end(); } catch (error) { console.error(Streaming Error:, error); res.write(data: ${JSON.stringify({ error: 流式请求失败 })}\n\n); res.end(); } });前端则需要对应地修改handleSend函数使用fetch来读取这个流并逐步更新UI。这个过程稍复杂但Cursor可以一步步引导你完成代码的修改。6. 项目优化、部署与常见问题6.1 性能与体验优化点上下文长度管理Token限制大模型有上下文窗口限制如GPT-3.5-turbo是16K tokens。如果对话历史太长API调用会失败或截断。需要在后端实现一个逻辑当历史消息的估算Token数超过某个阈值如12K时丢弃最早的一些消息或者进行智能摘要。可以借助tiktoken这个库来估算Token数量。前端防抖与加载状态在输入框输入时如果要做实时搜索之类的功能需要防抖。发送请求时按钮要禁用并显示加载状态防止重复提交。错误重试与降级网络请求可能失败。可以为AI API调用添加简单的重试逻辑例如最多重试2次。如果AI服务完全不可用可以考虑返回一个预设的静态回复作为降级方案。环境变量与安全永远不要将API密钥硬编码在代码中或提交到Git。使用.env文件并将其添加到.gitignore中。在部署时使用服务器环境变量或托管平台提供的密钥管理服务。6.2 简单的部署方案开发完成后你可能想把它分享给别人。一个简单的方案是使用Vercel前端和Railway/Render后端这类现代云平台。前端部署 (Vercel)将前端代码推送到GitHub仓库。在Vercel官网导入该仓库构建命令为npm run build输出目录为dist。在Vercel的环境变量设置中配置生产环境的API地址如VITE_API_BASE_URLhttps://your-backend.railway.app。前端代码中通过import.meta.env.VITE_API_BASE_URL来获取。后端部署 (Railway)同样将后端代码推送到GitHub。在Railway上通过GitHub导入项目。Railway会自动检测为Node.js项目并安装依赖。最关键的一步在Railway项目的Variables选项卡中添加你在.env里定义的变量特别是OPENAI_API_KEY和PORTRailway会自动分配端口可用process.env.PORT。部署后Railway会给你一个.up.railway.app的域名这就是你的后端API地址将其填入前端的生产环境变量中。6.3 常见问题与排查实录在开发这个“菜包”的过程中我踩过不少坑这里记录几个典型的CORS跨域错误前端调用后端接口时浏览器报错“Access-Control-Allow-Origin”。这是因为前端(localhost:5173)和后端(localhost:3000)端口不同触发了浏览器的同源策略限制。解决确保后端使用了cors中间件并且正确配置。最简单的就是app.use(cors())这会允许所有来源。在生产环境中可以配置具体的来源以增强安全app.use(cors({ origin: https://your-frontend.vercel.app }))。OpenAI API 返回 401 或 429 错误401API密钥错误或未设置。检查.env文件中的OPENAI_API_KEY是否正确是否在代码中通过process.env正确读取。确保.env文件不在Git中提交。429请求速率超限或余额不足。免费额度用完或新账号的速率限制较低。需要去OpenAI平台检查用量和余额并考虑在代码中增加请求间隔或处理降级。前端收不到流式数据或显示异常检查后端流式接口的响应头Content-Type是否正确设置为text/event-stream。检查前端读取流的代码是否正确处理了SSE格式data:前缀和\n\n分隔符。在浏览器开发者工具的“网络”选项卡中查看该请求的响应类型是否为“EventStream”并观察是否有数据流进来。对话上下文混乱AI“失忆”检查后端构造messagesForAI数组的逻辑是否正确。每次请求都需要携带完整的历史对话或最近的有效历史。注意每条消息的role必须是system,user,assistant中的一个且顺序要符合对话时序。如果历史太长参考上文“Token限制”部分进行管理。部署后前端找不到后端API前端构建后API请求地址仍然是localhost:3000。你需要使用环境变量来区分开发和生产环境。Vite使用import.meta.env.MODE来获取模式你可以配置不同的.env.development和.env.production文件或者直接在构建时注入变量。这个“菜包”项目虽然基础但完整走一遍后你会对AI应用的全栈开发链路有一个扎实的感性认识。从界面到逻辑从本地开发到线上部署每一个环节都有值得深挖的细节。最重要的是你拥有了一个完全由自己掌控、可以随意扩展和修改的AI聊天应用原型。接下来你可以为它增加语音输入输出、文件上传分析、自定义知识库RAG、甚至用开源模型替换OpenAI API让它真正变成属于你的、独一无二的智能助手。
