用Node.js+Express从零搭建AI API服务：小项目实战入门

1. 为什么我劝你用一个小项目来学 AI 后端1.1 从“只会调 API”到“能自己搭服务”的分水岭很多人接触 AI 开发的第一步是在某个聊天窗口里粘贴一段提示词或者用 Python 脚本调一次大模型接口看到返回结果就觉得自己“会 AI 了”。但真到了要做一个能给别人用的东西时问题立刻暴露接口密钥放哪里前端怎么调并发上来怎么办返回格式怎么统一这些问题的答案都指向同一个东西——你得有一个自己的 API 服务。我见过太多人卡在这一步。他们能写几十行 Python 调模型却不知道怎么把这段逻辑包装成一个 HTTP 接口让浏览器、App、甚至另一个服务来调用。这不是能力问题是缺少一个“从脚本到服务”的完整实践。而“用 AI 从零搭一个 API 服务”这个小项目恰好补的就是这一环。这个项目的核心目标很明确用 Node.js 和 Express 搭一个后端服务对外暴露一个接口接口内部去调用 AI 能力把结果返回给调用方。听起来简单但里面涉及的东西一点不少——项目初始化、路由设计、请求参数校验、密钥管理、错误处理、跨域配置、日志记录每一项都是真实后端开发里绕不开的环节。适合谁来参考如果你已经会一点 JavaScript 基础知道函数、对象、数组怎么用但没怎么写过服务端代码这个项目就是为你准备的。如果你是从 Python 转过来的想看看 Node.js 生态里怎么快速起一个服务同样适用。甚至你是个前端想自己做个带 AI 功能的小工具但不想依赖别人的后端那这套东西你直接抄作业就行。1.2 为什么选 Node.js Express 而不是别的技术选型这件事很多人一上来就纠结。我试过用 Python 的 FastAPI、用 Go 的 Gin、用 Java 的 Spring Boot 来搭类似的 AI 代理服务最后发现对于“小项目快速验证”这个场景Node.js Express 的组合有几个很实际的优势。第一是启动成本极低。装完 Node.js 之后两行命令就能初始化项目装一个 express 依赖十几行代码就能跑起一个能接收请求的服务。对比 Java 那套要配 Maven、写一堆注解、等编译Node.js 的反馈循环快得多。你做小项目最怕的就是“还没看到效果就先被环境搞烦了”Express 在这方面几乎零阻力。第二是 JavaScript 本身的异步特性天然适合 AI 接口代理。调用大模型接口本质上是发一个 HTTP 请求然后等响应这是典型的 I/O 密集型任务。Node.js 的事件循环模型处理这类任务很顺手你不需要开一堆线程一个进程就能扛住不少并发。虽然它不适合做 CPU 密集计算但 AI 代理服务恰恰不是干这个的。第三是生态和调试体验。npm 上现成的中间件太多了处理跨域、解析请求体、加日志、做限流都有成熟方案你不用自己造轮子。而且 Node.js 的报错信息相对直观配合 console.log 和 nodemon 热重载调试起来很舒服。当然这不是说 Express 是唯一选择。Fastify 性能更好NestJS 结构更规范但对于“从零搭一个小项目”这个目标Express 的简单直接是最匹配的。等你把这个小项目跑通了再去了解其他框架会更有判断力。提示不要在这个阶段纠结“哪个框架最好”。小项目的价值在于跑通全流程而不是选出一个能用十年的技术栈。先用 Express 把东西做出来比什么都重要。2. 动手之前先把这几个核心概念理清楚2.1 API 服务到底在做什么很多人对“API 服务”这个词有距离感觉得是个很庞大的东西。其实拆开看一个最基础的 API 服务就干三件事接收请求、处理逻辑、返回响应。接收请求就是服务在某个端口上监听等着别人来访问。比如你的服务跑在 3000 端口别人访问http://localhost:3000/chat这个请求就进来了。处理逻辑就是根据请求里带的内容去做对应的事情。在 AI 场景里通常是把用户发来的消息转发给大模型接口拿到模型的回复。返回响应就是把处理结果按照约定的格式发回去通常是 JSON。这三件事对应到 Express 里就是路由、处理函数、响应方法。你写一个app.post(/chat, handler)就是在告诉 Express当有人用 POST 方法访问/chat这个路径时执行 handler 这个函数。handler 里面你去调 AI 接口拿到结果后用res.json()返回。就这么简单。理解了这个模型你就知道为什么需要 Express 了。它帮你把 HTTP 协议那套底层的东西封装好了你只需要关心“什么路径、什么方法、做什么事、返回什么”。不用自己去解析 TCP 包、拼 HTTP 头这些脏活累活框架都替你干了。2.2 密钥管理为什么绝对不能写死在代码里这是新手最容易犯的错也是我要重点强调的地方。很多人在本地测试的时候图省事直接把 API Key 写在代码里比如const apiKey sk-xxxxxx。本地跑没问题但一旦你要把代码传到代码托管平台或者分享给别人这个密钥就泄露了。密钥泄露的后果很直接别人可以用你的额度产生费用如果密钥绑定了敏感权限还可能造成更严重的问题。我见过有人把带密钥的代码传到公开仓库几个小时后收到账单提醒额度被刷光了。正确的做法是用环境变量。具体来说在项目根目录建一个.env文件把密钥写进去然后在代码里通过process.env.XXX来读取。同时.env文件必须加到.gitignore里确保它不会被提交。另外再建一个.env.example文件里面只写变量名不写真实值作为模板提交上去告诉别人需要配置哪些变量。# .env 文件内容示例 AI_API_KEY你的真实密钥 AI_API_BASEhttps://api.example.com/v1 PORT3000// 代码里这样读取 const apiKey process.env.AI_API_KEY;这样做的另一个好处是本地开发、测试环境、生产环境可以用不同的密钥只需要改环境变量代码一行都不用动。部署到服务器上的时候在服务器的环境变量里配置即可密钥永远不会出现在代码仓库里。注意.env文件不要用任何形式提交到公开仓库。哪怕你后来删掉了Git 历史里依然能查到。如果不小心提交了第一件事是去服务商后台把那个密钥作废重新生成一个。2.3 请求参数校验别信任任何外部输入服务一旦对外暴露就会收到各种各样的请求。有人传空字符串有人传超长文本有人传个数组过来甚至有人传个对象套对象。如果你不校验直接把req.body.message拿去调 AI 接口轻则报错重则可能触发一些意料之外的行为。参数校验的核心思路是在进入业务逻辑之前先确认请求里该有的字段都有类型对范围合理。比如聊天接口通常需要一个message字段那就要检查它是否存在、是否是字符串、长度是否在合理范围内。如果不符合直接返回 400 错误并说明原因不要让它继续往下走。// 一个简单的校验逻辑 app.post(/chat, (req, res) { const { message } req.body; if (!message || typeof message ! string) { return res.status(400).json({ error: message 字段必须是非空字符串 }); } if (message.length 2000) { return res.status(400).json({ error: message 长度不能超过 2000 字符 }); } // 校验通过继续处理 });这段代码看起来简单但能挡掉大部分无效请求。实际项目中你可以用express-validator或者joi这类库来做更系统的校验但对于小项目手写几个 if 判断完全够用。关键是要有这个意识外部输入永远不可信先校验再使用。3. 从零开始的完整实操流程3.1 环境准备与项目初始化第一步是装 Node.js。去官网下载 LTS 版本就行不要追求最新版LTS 更稳定。安装完成后打开终端输入node -v和npm -v能看到版本号就说明装好了。这里有个小坑有些人电脑上之前装过旧版本或者用某些工具装过导致node -v报错或者版本混乱。遇到这种情况先把旧的卸载干净再重新装官方版本。接下来创建项目目录初始化 npm。mkdir ai-api-demo cd ai-api-demo npm init -ynpm init -y会生成一个默认的package.json文件里面记录了项目的基本信息和依赖。然后安装 Express 和几个必要的依赖。npm install express dotenv cors npm install nodemon --save-dev这里解释一下每个依赖的作用。express是 Web 框架本体。dotenv用来读取.env文件里的环境变量。cors处理跨域请求因为你的前端页面和服务很可能不在同一个端口上不加这个浏览器会拦截请求。nodemon是开发工具它会在你修改代码后自动重启服务省得你每次手动停掉再启动。在package.json里加一个启动脚本方便后面运行。{ scripts: { start: node index.js, dev: nodemon index.js } }这样开发的时候用npm run dev生产环境用npm start。3.2 搭建服务骨架与第一个接口新建一个index.js文件写入最基础的服务代码。require(dotenv).config(); const express require(express); const cors require(cors); const app express(); const PORT process.env.PORT || 3000; app.use(cors()); app.use(express.json()); app.get(/, (req, res) { res.json({ status: ok, message: AI API 服务已启动 }); }); app.listen(PORT, () { console.log(服务运行在 http://localhost:${PORT}); });这几行代码做了几件事。require(dotenv).config()加载环境变量必须放在最前面不然后面读不到。app.use(cors())开启跨域支持。app.use(express.json())让 Express 能解析请求体里的 JSON 数据没有这行的话req.body会是 undefined。然后定义了一个根路径的 GET 接口用来做健康检查。最后监听端口启动服务。跑起来之后浏览器访问http://localhost:3000看到{status:ok,message:AI API 服务已启动}就说明服务正常。这一步看起来简单但它是后面所有功能的基础。我建议你在这里多停一下确认服务能正常启动、能正常响应再往下走。3.3 接入 AI 能力调用大模型接口现在到了核心部分。我们要加一个/chat接口接收用户消息转发给 AI 接口把结果返回。app.post(/chat, async (req, res) { const { message } req.body; if (!message || typeof message ! string) { return res.status(400).json({ error: message 字段必须是非空字符串 }); } try { const response await fetch(${process.env.AI_API_BASE}/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${process.env.AI_API_KEY} }, body: JSON.stringify({ model: your-model-name, messages: [ { role: user, content: message } ] }) }); if (!response.ok) { const errorText await response.text(); console.error(AI 接口返回错误:, response.status, errorText); return res.status(response.status).json({ error: AI 接口调用失败 }); } const data await response.json(); const reply data.choices?.[0]?.message?.content || ; res.json({ reply }); } catch (err) { console.error(请求异常:, err.message); res.status(500).json({ error: 服务内部错误 }); } });这段代码有几个关键点值得展开说。第一用async/await处理异步请求。调用 AI 接口是网络请求必须异步处理不然会阻塞整个服务。try/catch包裹是为了捕获网络异常比如超时、连接失败这些情况。第二错误处理分了两层。一层是 AI 接口返回了非 200 状态码这时候要把状态码透传回去同时记录日志。另一层是请求本身抛异常比如网络不通这时候返回 500。两层分开处理排查问题的时候能快速定位是对方的问题还是自己的问题。第三返回结果做了防御性取值。data.choices?.[0]?.message?.content用了可选链防止某一层结构不存在导致报错。AI 接口的返回结构有时候会因为各种原因不完整加个保护更稳妥。第四密钥通过Authorization头传递值从环境变量读取。这样代码里看不到任何真实密钥安全。3.4 参数计算与模型选择在调用 AI 接口时有几个参数需要你根据实际情况决定。model字段指定用哪个模型。不同模型的能力、速度、价格都不一样。小项目验证阶段选一个性价比高的就行不用一上来就上最贵的。等你确认流程跑通了再根据实际需求调整。max_tokens控制返回内容的最大长度。如果不设有些接口会用一个默认值可能不够用设太大又浪费。一般聊天场景设 1000 到 2000 就够。这个值的计算逻辑是你预期的回复长度加上一定余量。比如你希望回复不超过 500 字中文大概对应 700 到 1000 token那就设 1200 左右留点空间。temperature控制输出的随机性。值越低越确定越高越有创造性。做问答类应用设 0.3 到 0.7 比较合适做创意类可以设 0.8 到 1.0。小项目里可以先不设用默认值等有具体需求再调。这些参数不是必须的但了解它们的作用能让你在遇到“回复太短”“回复太随机”这类问题时知道去哪里调。4. 踩过的坑和排查经验4.1 常见报错与解决思路做这个项目的过程中我遇到过几类典型问题整理成表格方便你对照排查。报错信息可能原因解决方向Cannot find module express依赖没装或装到了别的目录确认在项目根目录执行npm installreq.body是 undefined没加express.json()中间件在路由之前加app.use(express.json())401 Unauthorized密钥错误或没读到环境变量检查.env文件位置和变量名确认dotenv在最前面加载400 Bad Request请求参数格式不对检查发送的 JSON 结构确认字段名和类型跨域错误没配 CORS加app.use(cors())请求超时AI 接口响应慢或网络问题加超时设置或换一个响应更快的模型这里重点说 401 这个错误。它出现的原因通常是密钥问题但具体又分几种情况。一种是密钥本身写错了比如复制的时候多了空格或者少了字符。一种是.env文件没被正确加载比如文件不在项目根目录或者dotenv的config()调用放在了读取环境变量的代码之后。还有一种是密钥对应的服务没开通或者额度用完了。排查的时候按这个顺序检查先确认密钥字符串本身没问题再确认环境变量读到了可以临时console.log一下最后确认服务商后台的额度和权限。4.2 几个让我印象深刻的实操教训第一个教训是关于异步错误的。我一开始写代码的时候在async函数里忘了加try/catch结果 AI 接口一报错整个服务就崩了进程直接退出。后来才明白Node.js 里未捕获的 Promise 异常会导致进程终止。所以凡是await的地方都要考虑异常处理。这不是可选项是必须项。第二个教训是关于日志的。我最初只在成功的时候打印结果出错的时候什么都不打结果线上出问题完全不知道发生了什么。后来改成每个关键节点都打日志收到请求打一条调用 AI 接口前打一条拿到响应打一条出错打详细错误。这样排查问题的时候一眼就能看出卡在哪一步。日志不用很复杂console.log加时间戳和关键信息就够用。第三个教训是关于超时的。AI 接口有时候会响应很慢如果不设超时请求会一直挂着占用连接资源。我后来加了超时控制超过一定时间就主动断开并返回错误。Node.js 里可以用AbortController来实现。const controller new AbortController(); const timeout setTimeout(() controller.abort(), 30000); try { const response await fetch(url, { signal: controller.signal, // 其他配置 }); clearTimeout(timeout); // 处理响应 } catch (err) { if (err.name AbortError) { return res.status(504).json({ error: AI 接口响应超时 }); } // 其他错误处理 }这段代码设置了 30 秒超时超过就中断请求。实际项目中这个值可以根据你用的模型调整一般 20 到 60 秒之间。4.3 上线前必须检查的几件事小项目跑通之后如果你想把它部署到服务器上给别人用有几件事必须确认。密钥是否已经换成生产环境的。不要把开发用的密钥直接用到线上最好分开管理。环境变量是否在服务器上正确配置了。不同平台的配置方式不一样有的在控制面板里设有的要改配置文件部署前确认一遍。端口是否对外开放了防火墙规则是否允许访问。日志是否输出到了可查看的地方出问题的时候能查到记录。有没有基本的限流措施防止被人恶意刷接口。限流这块小项目可以用express-rate-limit这个中间件几行代码就能加上。const rateLimit require(express-rate-limit); const limiter rateLimit({ windowMs: 60 * 1000, max: 20, message: { error: 请求过于频繁请稍后再试 } }); app.use(/chat, limiter);这段配置的意思是每个 IP 每分钟最多请求 20 次超过就返回提示。对于个人小项目这个量级基本够用既能防止滥用又不会误伤正常用户。5. 这个项目还能怎么扩展5.1 加上对话历史让体验更连贯现在的/chat接口是无状态的每次请求都是独立的模型不记得上一轮说了什么。如果你想让对话更连贯需要把历史消息一起传过去。思路是在请求里加一个history数组里面按顺序存放之前的对话。调用 AI 接口的时候把历史消息和当前消息拼在一起传给模型。const { message, history [] } req.body; const messages [ ...history, { role: user, content: message } ]; // 调用 AI 接口时传 messages前端那边负责维护历史记录每次请求带上。后端只负责转发不存状态。这样做的好处是服务端简单坏处是请求体越来越大。如果历史很长需要考虑截断策略只保留最近几轮。这个扩展不难但能让你的小工具从“一问一答”变成“能聊天”体验提升很明显。5.2 加一个简单的网页界面服务搭好了但每次测试都要用 curl 或者 Postman 发请求不太方便。你可以加一个静态页面放一个输入框和显示区域用 fetch 调自己的接口。!DOCTYPE html html head meta charsetutf-8 titleAI 对话/title /head body div idmessages/div input idinput typetext placeholder输入消息... button onclicksend()发送/button script async function send() { const input document.getElementById(input); const message input.value.trim(); if (!message) return; const res await fetch(/chat, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ message }) }); const data await res.json(); // 把 data.reply 显示到页面上 input.value ; } /script /body /html把这个文件放到public目录下然后在 Express 里加app.use(express.static(public))访问根路径就能看到页面。这样你就有了一个能直接用的 AI 对话工具虽然简陋但完整跑通了“前端发请求、后端调 AI、结果返回展示”的全链路。5.3 从单文件到模块化拆分现在所有代码都在index.js里项目小的时候没问题但功能一多就会乱。可以按职责拆成几个文件routes/chat.js放路由定义services/ai.js放调用 AI 接口的逻辑middlewares/放校验和限流中间件index.js只负责组装和启动。拆分的逻辑是路由层只关心“什么路径、什么方法”不关心具体怎么调 AI服务层只关心“怎么调 AI、怎么处理返回”不关心 HTTP 细节。这样改 AI 接口的时候不用动路由改路由的时候不用动 AI 逻辑各管各的。对于小项目这个拆分不是必须的但养成这个习惯后面做更大的东西会轻松很多。5.4 部署上线的几种选择本地跑通之后你可能想把它放到网上让朋友也能用。部署方式有几种。一种是找支持 Node.js 的云平台把代码传上去配置好环境变量平台会自动帮你跑起来。一种是自己租一台服务器装好 Node.js 环境用pm2这类进程管理工具让服务常驻。还有一种是打包成容器镜像用容器服务跑。对于小项目第一种最省事不用管服务器运维专注写代码就行。第二种更灵活但需要你懂一些 Linux 操作。第三种适合以后要扩展成更大规模的情况。不管选哪种核心都是把代码和环境变量配置好确保服务能稳定运行。提示部署之后记得把NODE_ENV设成production有些库会根据这个变量做优化比如 Express 在生产模式下会缓存视图、减少日志输出性能会好一些。6. 我个人的一些体会这个项目我从头到尾做了大概三遍每次都有新的收获。第一遍是照着教程走能跑起来但很多地方不理解。第二遍是自己从头写遇到问题去查文档才真正搞懂了中间件、异步、错误处理这些概念。第三遍是把它改造成能实际用的工具加了历史记录、限流、日志才体会到“能跑”和“能用”之间的差距。最大的感受是小项目虽然小但五脏俱全。它逼着你去面对真实开发里的每一个环节而不是停留在“调通接口”这个层面。密钥管理、参数校验、错误处理、日志、限流这些东西在教程里可能一笔带过但真正做的时候每一个都值得花时间搞明白。另一个体会是不要怕代码写得丑。我第一版的代码现在回头看简直没法看但正是那个丑陋的版本让我跑通了流程才有了后面优化的基础。先让它跑起来再让它变好这个顺序不能反。很多人卡在“想写出完美代码”这一步结果什么都没做出来。最后分享一个小技巧每次遇到报错先把错误信息完整读一遍不要急着去搜。很多时候错误信息本身就说明了问题比如“Cannot find module”就是缺依赖“undefined”就是某个变量没取到。读懂了再动手比盲目搜索效率高得多。