1. 为什么我选 Node.js Express 来搭这个 API 服务1.1 从零搭 API 服务第一步不是写代码而是选型很多人一听到“用 AI 搭 API 服务”第一反应是打开编辑器让 AI 生成一堆代码然后复制粘贴跑起来。我一开始也这么干过结果就是代码能跑但完全看不懂改一个参数就崩排查问题无从下手。后来我换了个思路先想清楚这个 API 服务要解决什么问题再决定用什么技术栈最后才让 AI 帮我写具体实现。这个项目的目标很明确搭一个能对外提供数据接口的 HTTP 服务支持基本的增删改查能返回 JSON 格式的数据最好还能接入 AI 能力做一点智能处理。基于这个目标我选了Node.js Express这套组合。原因有三点第一JavaScript 是我最熟悉的语言前后端可以共用一套语法调试成本低第二Express 是目前 Node.js 生态里最成熟的 Web 框架文档全、社区大、遇到问题容易搜到答案第三Node.js 天生适合 I/O 密集型的 API 服务处理大量并发请求时性能表现不错而且 npm 生态里有大量现成的中间件可以直接用。提示如果你之前只写过前端 JavaScript完全不用担心。Node.js 只是把 JavaScript 的运行环境从浏览器搬到了服务器语法一模一样只是多了文件操作、网络通信这些能力。1.2 环境准备Node.js 安装与版本选择搭 API 服务的第一步是把环境装好。Node.js 的安装本身不复杂但版本选择有讲究。我建议直接上Node.js 20 LTS或更高版本的 LTS 版本。LTS 是长期支持版稳定性有保障不会像最新版那样时不时冒出兼容性问题。在 Ubuntu 上安装 Node.js 20 的方式有好几种我试过最省事的是用 NodeSource 的安装脚本curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完之后验证一下版本node -v npm -v如果输出类似v20.x.x和10.x.x说明安装成功。Windows 和 macOS 用户直接去 Node.js 官网下载 LTS 版本的安装包双击下一步就行没什么坑。注意不要用sudo apt install nodejs这种方式装 Ubuntu 自带的版本那个版本通常很老可能还是 12.x 甚至更低跑现代 npm 包会各种报错。1.3 项目初始化让 AI 帮你生成第一版骨架环境好了之后新建一个项目目录初始化 npmmkdir ai-api-service cd ai-api-service npm init -y这时候你有了一个package.json文件。接下来安装 Expressnpm install express到这里基础骨架就有了。接下来我会让 AI 帮我生成一个最简的 Express 服务入口文件。我给 AI 的提示词是这样的帮我写一个 Node.js Express 的 API 服务入口文件要求监听 3000 端口有一个 GET /health 接口返回{status:ok}有一个 GET /api/items 接口返回一个数组有一个 POST /api/items 接口接收 JSON 请求体并返回创建结果。代码要加注释用 ES Module 语法。AI 生成的代码大概长这样import express from express; const app express(); const PORT process.env.PORT || 3000; // 解析 JSON 请求体 app.use(express.json()); // 健康检查接口 app.get(/health, (req, res) { res.json({ status: ok }); }); // 获取列表 app.get(/api/items, (req, res) { res.json({ items: [], total: 0 }); }); // 创建条目 app.post(/api/items, (req, res) { const { name } req.body; if (!name) { return res.status(400).json({ error: name is required }); } res.status(201).json({ id: Date.now(), name }); }); app.listen(PORT, () { console.log(Server running on port ${PORT}); });这段代码虽然简单但已经包含了 API 服务的核心要素路由、请求体解析、状态码返回、错误处理。你可以直接node index.js跑起来用浏览器访问http://localhost:3000/health就能看到返回结果。2. 核心细节解析API 服务的关键环节与避坑要点2.1 路由设计RESTful 风格不是唯一选择但确实好用路由是 API 服务的骨架。我见过很多新手写路由就是想到哪写到哪/getUser、/createUser、/deleteUser这样一路排下去。能跑但后期维护很痛苦。我建议从一开始就按 RESTful 风格来组织操作HTTP 方法路径说明获取列表GET/api/items返回资源集合获取单个GET/api/items/:id返回指定资源创建POST/api/items创建新资源更新PUT/api/items/:id全量更新部分更新PATCH/api/items/:id局部更新删除DELETE/api/items/:id删除资源这样设计的好处是路径语义清晰前端一看就知道该调哪个接口。而且 Express 的路由参数:id可以直接从req.params.id取到非常方便。实操心得路由路径尽量用复数名词比如/api/items而不是/api/item。因为列表接口返回的是多个资源用复数更符合语义。2.2 中间件机制Express 的灵魂所在Express 的中间件机制是它最强大的地方。一个请求从进入服务器到返回响应中间会经过一系列中间件函数每个中间件可以对请求做处理然后决定是继续往下传递还是直接返回响应。我常用的中间件有这么几类请求体解析express.json()用于解析 JSON 格式的请求体express.urlencoded()用于解析表单格式。没有这两个中间件req.body就是 undefined。日志记录自己写一个简单的日志中间件记录每个请求的方法、路径、耗时app.use((req, res, next) { const start Date.now(); res.on(finish, () { const duration Date.now() - start; console.log(${req.method} ${req.path} ${res.statusCode} ${duration}ms); }); next(); });错误处理Express 的错误处理中间件有四个参数(err, req, res, next)必须放在所有路由之后app.use((err, req, res, next) { console.error(err.stack); res.status(500).json({ error: Internal Server Error }); });跨域处理如果前端和后端不在同一个域名下需要处理 CORS。可以用cors这个 npm 包一行代码搞定npm install corsimport cors from cors; app.use(cors());注意中间件的注册顺序非常重要。express.json()必须放在路由之前错误处理中间件必须放在所有路由之后。顺序错了就会出现req.body为空或者错误没被捕获的情况。2.3 数据校验别让脏数据进到你的服务里API 服务对外暴露什么请求都可能收到。如果不做数据校验轻则返回错误结果重则导致服务崩溃。我一般会在路由处理函数里做基础校验复杂场景用joi或zod这样的校验库。基础校验就是检查必填字段是否存在、类型是否正确app.post(/api/items, (req, res) { const { name, price } req.body; if (!name || typeof name ! string) { return res.status(400).json({ error: name must be a non-empty string }); } if (price ! undefined (typeof price ! number || price 0)) { return res.status(400).json({ error: price must be a non-negative number }); } // 通过校验继续处理 res.status(201).json({ id: Date.now(), name, price }); });用zod的话可以更优雅import { z } from zod; const ItemSchema z.object({ name: z.string().min(1), price: z.number().nonnegative().optional(), }); app.post(/api/items, (req, res) { const result ItemSchema.safeParse(req.body); if (!result.success) { return res.status(400).json({ error: result.error.issues }); } res.status(201).json({ id: Date.now(), ...result.data }); });实操心得校验失败时返回 400 状态码并在响应体里说明具体哪个字段有问题。不要只返回一个笼统的 Bad Request那样前端排查起来很痛苦。3. 实操过程从零到一完整搭建并接入 AI 能力3.1 项目结构规划别把所有代码塞进一个文件第一版代码跑通之后下一步就是拆结构。所有代码堆在index.js里超过两百行就难以维护了。我一般会拆成这样的目录结构ai-api-service/ ├── src/ │ ├── routes/ │ │ ├── items.js │ │ └── ai.js │ ├── middleware/ │ │ ├── logger.js │ │ └── errorHandler.js │ ├── services/ │ │ └── aiService.js │ └── app.js ├── package.json └── .envapp.js负责创建 Express 实例、注册中间件和路由routes/目录下按业务模块拆分路由文件middleware/放自定义中间件services/放业务逻辑比如调用 AI 接口的代码。这样拆的好处是加新功能只需要新建一个路由文件改某个中间件不会影响到其他部分测试的时候也可以单独测某个模块。3.2 接入 AI 能力调用大模型 API 的完整流程这个项目叫“用 AI 搭 API 服务”那 AI 能力本身也得接进去。我选了一个国内可用的 AI 大模型 API 来做演示整体流程是前端发请求到我的 API 服务我的服务再调用 AI 接口拿到结果后返回给前端。首先安装 HTTP 请求库npm install axios然后写一个 AI 服务模块// src/services/aiService.js import axios from axios; const AI_API_URL process.env.AI_API_URL; const AI_API_KEY process.env.AI_API_KEY; export async function askAI(prompt) { try { const response await axios.post( AI_API_URL, { model: glm-4, messages: [{ role: user, content: prompt }], temperature: 0.7, }, { headers: { Authorization: Bearer ${AI_API_KEY}, Content-Type: application/json, }, timeout: 30000, } ); return response.data.choices[0].message.content; } catch (error) { console.error(AI API error:, error.message); throw new Error(AI service unavailable); } }然后在路由里调用// src/routes/ai.js import { Router } from express; import { askAI } from ../services/aiService.js; const router Router(); router.post(/ask, async (req, res, next) { try { const { prompt } req.body; if (!prompt) { return res.status(400).json({ error: prompt is required }); } const answer await askAI(prompt); res.json({ answer }); } catch (error) { next(error); } }); export default router;API Key 这类敏感信息不要硬编码在代码里放到.env文件中AI_API_URLhttps://your-ai-api-endpoint/v1/chat/completions AI_API_KEYyour-api-key-here PORT3000然后用dotenv加载npm install dotenvimport dotenv/config;注意.env文件一定要加到.gitignore里千万别提交到代码仓库。我见过有人把 API Key 推到公开仓库结果被人扫到之后一夜之间跑掉几百块的调用量。3.3 参数计算与超时设置AI 接口调用的关键细节调用 AI 接口有几个参数需要特别注意超时时间AI 大模型生成回复通常需要几秒到几十秒timeout设太短会导致请求还没完成就断了。我一般设 30 秒如果模型响应慢可以调到 60 秒。temperature控制输出的随机性。0 表示最确定性的输出1 表示最随机。做事实性问答时设 0.1~0.3做创意生成时设 0.7~0.9。max_tokens限制返回内容的最大长度。设太小会导致回答被截断设太大会增加费用和响应时间。一般设 1024 或 2048 够用。重试机制AI 接口偶尔会超时或返回 5xx 错误加一个简单的重试逻辑能提升稳定性async function askAIWithRetry(prompt, retries 2) { for (let i 0; i retries; i) { try { return await askAI(prompt); } catch (error) { if (i retries) throw error; console.log(Retry ${i 1}/${retries}...); await new Promise(r setTimeout(r, 1000 * (i 1))); } } }3.4 用 AI 辅助开发提示词怎么写才高效这个项目本身也是“用 AI 搭”的所以我想分享一下用 AI 辅助写代码的提示词技巧。我踩过的坑是提示词太笼统AI 生成的代码虽然能跑但不符合我的项目结构提示词太细又不如自己写。我总结了一个好用的提示词模板项目背景[一句话说明项目是做什么的] 技术栈[Node.js 20 Express 4 ES Module] 当前文件[src/routes/items.js] 需求[实现一个 GET /api/items/:id 接口从内存数组中查找并返回找不到返回 404] 约束[不要引入新的依赖错误处理用 next(error) 传递给全局错误中间件]这样 AI 生成的代码基本可以直接用不需要大改。关键是给上下文和给约束不要让 AI 自由发挥。4. 常见问题与排查技巧实录4.1 启动报错排查速查表报错信息原因解决方法Cannot find module express依赖没装执行npm installSyntaxError: Cannot use import statement outside a module没配 ES Module在 package.json 加type: moduleEADDRINUSE: address already in use :::3000端口被占用换端口或 kill 掉占用进程req.body为 undefined没加express.json()在路由之前注册该中间件ERR_REQUIRE_ESMCommonJS 和 ESM 混用统一用 import/export 语法端口被占用这个问题特别常见。查占用进程lsof -i :3000然后 kill 掉kill -9 PID或者直接在代码里换个端口用环境变量控制const PORT process.env.PORT || 3001;4.2 AI 接口调用失败的典型场景场景一API Key 无效或过期。报错通常是 401 Unauthorized。检查.env文件里的 Key 是否正确有没有多余的空格或换行。场景二请求超时。报错是timeout of 30000ms exceeded。可能是网络问题也可能是模型负载高。加长超时时间或者加重试逻辑。场景三返回内容被截断。finish_reason是length而不是stop说明max_tokens设小了。调大这个值。场景四并发请求被限流。报错 429 Too Many Requests。需要加请求队列或者降低并发数。我一般用一个简单的信号量控制同时进行的 AI 请求数量不超过 3 个。4.3 我踩过的三个坑和对应的解决方案第一个坑忘记处理异步错误。Express 4 不会自动捕获 async 函数里抛出的错误如果不在 try/catch 里调用next(error)请求会一直挂起直到超时。解决方案是每个 async 路由都包 try/catch或者用一个包装函数const asyncHandler (fn) (req, res, next) { Promise.resolve(fn(req, res, next)).catch(next); }; router.get(/api/items, asyncHandler(async (req, res) { const items await getItems(); res.json({ items }); }));第二个坑CORS 配置不当。开发阶段直接app.use(cors())没问题但上线后最好限制允许的来源app.use(cors({ origin: [https://your-frontend.com], methods: [GET, POST, PUT, DELETE], }));第三个坑没有做请求频率限制。API 服务公开之后可能会被恶意刷接口。加一个简单的限流中间件npm install express-rate-limitimport rateLimit from express-rate-limit; const limiter rateLimit({ windowMs: 60 * 1000, max: 60, message: { error: Too many requests, please try again later }, }); app.use(/api/, limiter);这样每个 IP 每分钟最多请求 60 次超过就返回 429。4.4 部署上线的注意事项本地跑通之后部署到服务器上还有几个点要注意。第一用pm2或systemd守护进程保证服务崩溃后能自动重启。第二用 Nginx 做反向代理处理 HTTPS 证书和静态文件。第三日志要输出到文件方便排查问题。用 pm2 部署很简单npm install -g pm2 pm2 start src/app.js --name ai-api pm2 save pm2 startuppm2 startup会生成一条命令复制执行之后服务器重启时 pm2 会自动拉起你的服务。实操心得部署之前先在本地用NODE_ENVproduction node src/app.js跑一遍确保生产环境下没有报错。有些问题只在生产模式下才会暴露比如某些库的调试输出被关闭后导致的路径问题。5. 这个项目还能怎么扩展5.1 加数据库从内存存储到持久化目前数据存在内存里服务一重启就没了。下一步可以接一个数据库。轻量级场景用 SQLite不需要额外安装服务一个文件就是一个数据库npm install better-sqlite3import Database from better-sqlite3; const db new Database(data.db); db.exec( CREATE TABLE IF NOT EXISTS items ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, price REAL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ) );数据量大或者需要多实例部署时换成 PostgreSQL 或 MySQL。切换数据库只需要改services/里的实现路由层不用动这就是分层架构的好处。5.2 加认证API Key 或 JWT对外提供的 API 服务通常需要认证。最简单的方案是 API Key每个调用方分配一个 Key请求时放在 Header 里服务端校验。function authMiddleware(req, res, next) { const apiKey req.headers[x-api-key]; if (!apiKey || !validKeys.includes(apiKey)) { return res.status(401).json({ error: Invalid API key }); } next(); } app.use(/api/, authMiddleware);更复杂的场景用 JWT支持用户登录、Token 过期刷新等功能。不过对于小项目来说API Key 已经够用了。5.3 加文档让调用方知道怎么用API 写好了别人不知道怎么调也是白搭。可以用 Swagger 自动生成接口文档npm install swagger-ui-express swagger-jsdoc在路由上加注释Swagger 会自动生成可交互的文档页面。调用方打开浏览器就能看到所有接口的说明、参数、返回值还能直接在页面上测试。这个项目从零到跑通大概花了我一个下午的时间其中大部分时间不是在写代码而是在调 AI 生成的代码和排查环境问题。我的体会是AI 能帮你省掉大量敲键盘的时间但省不掉理解代码和排查问题的时间。你越清楚自己想要什么AI 生成的代码就越接近可用状态。反过来如果你自己都不知道要做什么AI 只会给你一堆看起来正确但跑不起来的东西。
1. 为什么我选 Node.js Express 来搭这个 API 服务1.1 从零搭 API 服务第一步不是写代码而是选型很多人一听到“用 AI 搭 API 服务”第一反应是打开编辑器让 AI 生成一堆代码然后复制粘贴跑起来。我一开始也这么干过结果就是代码能跑但完全看不懂改一个参数就崩排查问题无从下手。后来我换了个思路先想清楚这个 API 服务要解决什么问题再决定用什么技术栈最后才让 AI 帮我写具体实现。这个项目的目标很明确搭一个能对外提供数据接口的 HTTP 服务支持基本的增删改查能返回 JSON 格式的数据最好还能接入 AI 能力做一点智能处理。基于这个目标我选了Node.js Express这套组合。原因有三点第一JavaScript 是我最熟悉的语言前后端可以共用一套语法调试成本低第二Express 是目前 Node.js 生态里最成熟的 Web 框架文档全、社区大、遇到问题容易搜到答案第三Node.js 天生适合 I/O 密集型的 API 服务处理大量并发请求时性能表现不错而且 npm 生态里有大量现成的中间件可以直接用。提示如果你之前只写过前端 JavaScript完全不用担心。Node.js 只是把 JavaScript 的运行环境从浏览器搬到了服务器语法一模一样只是多了文件操作、网络通信这些能力。1.2 环境准备Node.js 安装与版本选择搭 API 服务的第一步是把环境装好。Node.js 的安装本身不复杂但版本选择有讲究。我建议直接上Node.js 20 LTS或更高版本的 LTS 版本。LTS 是长期支持版稳定性有保障不会像最新版那样时不时冒出兼容性问题。在 Ubuntu 上安装 Node.js 20 的方式有好几种我试过最省事的是用 NodeSource 的安装脚本curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完之后验证一下版本node -v npm -v如果输出类似v20.x.x和10.x.x说明安装成功。Windows 和 macOS 用户直接去 Node.js 官网下载 LTS 版本的安装包双击下一步就行没什么坑。注意不要用sudo apt install nodejs这种方式装 Ubuntu 自带的版本那个版本通常很老可能还是 12.x 甚至更低跑现代 npm 包会各种报错。1.3 项目初始化让 AI 帮你生成第一版骨架环境好了之后新建一个项目目录初始化 npmmkdir ai-api-service cd ai-api-service npm init -y这时候你有了一个package.json文件。接下来安装 Expressnpm install express到这里基础骨架就有了。接下来我会让 AI 帮我生成一个最简的 Express 服务入口文件。我给 AI 的提示词是这样的帮我写一个 Node.js Express 的 API 服务入口文件要求监听 3000 端口有一个 GET /health 接口返回{status:ok}有一个 GET /api/items 接口返回一个数组有一个 POST /api/items 接口接收 JSON 请求体并返回创建结果。代码要加注释用 ES Module 语法。AI 生成的代码大概长这样import express from express; const app express(); const PORT process.env.PORT || 3000; // 解析 JSON 请求体 app.use(express.json()); // 健康检查接口 app.get(/health, (req, res) { res.json({ status: ok }); }); // 获取列表 app.get(/api/items, (req, res) { res.json({ items: [], total: 0 }); }); // 创建条目 app.post(/api/items, (req, res) { const { name } req.body; if (!name) { return res.status(400).json({ error: name is required }); } res.status(201).json({ id: Date.now(), name }); }); app.listen(PORT, () { console.log(Server running on port ${PORT}); });这段代码虽然简单但已经包含了 API 服务的核心要素路由、请求体解析、状态码返回、错误处理。你可以直接node index.js跑起来用浏览器访问http://localhost:3000/health就能看到返回结果。2. 核心细节解析API 服务的关键环节与避坑要点2.1 路由设计RESTful 风格不是唯一选择但确实好用路由是 API 服务的骨架。我见过很多新手写路由就是想到哪写到哪/getUser、/createUser、/deleteUser这样一路排下去。能跑但后期维护很痛苦。我建议从一开始就按 RESTful 风格来组织操作HTTP 方法路径说明获取列表GET/api/items返回资源集合获取单个GET/api/items/:id返回指定资源创建POST/api/items创建新资源更新PUT/api/items/:id全量更新部分更新PATCH/api/items/:id局部更新删除DELETE/api/items/:id删除资源这样设计的好处是路径语义清晰前端一看就知道该调哪个接口。而且 Express 的路由参数:id可以直接从req.params.id取到非常方便。实操心得路由路径尽量用复数名词比如/api/items而不是/api/item。因为列表接口返回的是多个资源用复数更符合语义。2.2 中间件机制Express 的灵魂所在Express 的中间件机制是它最强大的地方。一个请求从进入服务器到返回响应中间会经过一系列中间件函数每个中间件可以对请求做处理然后决定是继续往下传递还是直接返回响应。我常用的中间件有这么几类请求体解析express.json()用于解析 JSON 格式的请求体express.urlencoded()用于解析表单格式。没有这两个中间件req.body就是 undefined。日志记录自己写一个简单的日志中间件记录每个请求的方法、路径、耗时app.use((req, res, next) { const start Date.now(); res.on(finish, () { const duration Date.now() - start; console.log(${req.method} ${req.path} ${res.statusCode} ${duration}ms); }); next(); });错误处理Express 的错误处理中间件有四个参数(err, req, res, next)必须放在所有路由之后app.use((err, req, res, next) { console.error(err.stack); res.status(500).json({ error: Internal Server Error }); });跨域处理如果前端和后端不在同一个域名下需要处理 CORS。可以用cors这个 npm 包一行代码搞定npm install corsimport cors from cors; app.use(cors());注意中间件的注册顺序非常重要。express.json()必须放在路由之前错误处理中间件必须放在所有路由之后。顺序错了就会出现req.body为空或者错误没被捕获的情况。2.3 数据校验别让脏数据进到你的服务里API 服务对外暴露什么请求都可能收到。如果不做数据校验轻则返回错误结果重则导致服务崩溃。我一般会在路由处理函数里做基础校验复杂场景用joi或zod这样的校验库。基础校验就是检查必填字段是否存在、类型是否正确app.post(/api/items, (req, res) { const { name, price } req.body; if (!name || typeof name ! string) { return res.status(400).json({ error: name must be a non-empty string }); } if (price ! undefined (typeof price ! number || price 0)) { return res.status(400).json({ error: price must be a non-negative number }); } // 通过校验继续处理 res.status(201).json({ id: Date.now(), name, price }); });用zod的话可以更优雅import { z } from zod; const ItemSchema z.object({ name: z.string().min(1), price: z.number().nonnegative().optional(), }); app.post(/api/items, (req, res) { const result ItemSchema.safeParse(req.body); if (!result.success) { return res.status(400).json({ error: result.error.issues }); } res.status(201).json({ id: Date.now(), ...result.data }); });实操心得校验失败时返回 400 状态码并在响应体里说明具体哪个字段有问题。不要只返回一个笼统的 Bad Request那样前端排查起来很痛苦。3. 实操过程从零到一完整搭建并接入 AI 能力3.1 项目结构规划别把所有代码塞进一个文件第一版代码跑通之后下一步就是拆结构。所有代码堆在index.js里超过两百行就难以维护了。我一般会拆成这样的目录结构ai-api-service/ ├── src/ │ ├── routes/ │ │ ├── items.js │ │ └── ai.js │ ├── middleware/ │ │ ├── logger.js │ │ └── errorHandler.js │ ├── services/ │ │ └── aiService.js │ └── app.js ├── package.json └── .envapp.js负责创建 Express 实例、注册中间件和路由routes/目录下按业务模块拆分路由文件middleware/放自定义中间件services/放业务逻辑比如调用 AI 接口的代码。这样拆的好处是加新功能只需要新建一个路由文件改某个中间件不会影响到其他部分测试的时候也可以单独测某个模块。3.2 接入 AI 能力调用大模型 API 的完整流程这个项目叫“用 AI 搭 API 服务”那 AI 能力本身也得接进去。我选了一个国内可用的 AI 大模型 API 来做演示整体流程是前端发请求到我的 API 服务我的服务再调用 AI 接口拿到结果后返回给前端。首先安装 HTTP 请求库npm install axios然后写一个 AI 服务模块// src/services/aiService.js import axios from axios; const AI_API_URL process.env.AI_API_URL; const AI_API_KEY process.env.AI_API_KEY; export async function askAI(prompt) { try { const response await axios.post( AI_API_URL, { model: glm-4, messages: [{ role: user, content: prompt }], temperature: 0.7, }, { headers: { Authorization: Bearer ${AI_API_KEY}, Content-Type: application/json, }, timeout: 30000, } ); return response.data.choices[0].message.content; } catch (error) { console.error(AI API error:, error.message); throw new Error(AI service unavailable); } }然后在路由里调用// src/routes/ai.js import { Router } from express; import { askAI } from ../services/aiService.js; const router Router(); router.post(/ask, async (req, res, next) { try { const { prompt } req.body; if (!prompt) { return res.status(400).json({ error: prompt is required }); } const answer await askAI(prompt); res.json({ answer }); } catch (error) { next(error); } }); export default router;API Key 这类敏感信息不要硬编码在代码里放到.env文件中AI_API_URLhttps://your-ai-api-endpoint/v1/chat/completions AI_API_KEYyour-api-key-here PORT3000然后用dotenv加载npm install dotenvimport dotenv/config;注意.env文件一定要加到.gitignore里千万别提交到代码仓库。我见过有人把 API Key 推到公开仓库结果被人扫到之后一夜之间跑掉几百块的调用量。3.3 参数计算与超时设置AI 接口调用的关键细节调用 AI 接口有几个参数需要特别注意超时时间AI 大模型生成回复通常需要几秒到几十秒timeout设太短会导致请求还没完成就断了。我一般设 30 秒如果模型响应慢可以调到 60 秒。temperature控制输出的随机性。0 表示最确定性的输出1 表示最随机。做事实性问答时设 0.1~0.3做创意生成时设 0.7~0.9。max_tokens限制返回内容的最大长度。设太小会导致回答被截断设太大会增加费用和响应时间。一般设 1024 或 2048 够用。重试机制AI 接口偶尔会超时或返回 5xx 错误加一个简单的重试逻辑能提升稳定性async function askAIWithRetry(prompt, retries 2) { for (let i 0; i retries; i) { try { return await askAI(prompt); } catch (error) { if (i retries) throw error; console.log(Retry ${i 1}/${retries}...); await new Promise(r setTimeout(r, 1000 * (i 1))); } } }3.4 用 AI 辅助开发提示词怎么写才高效这个项目本身也是“用 AI 搭”的所以我想分享一下用 AI 辅助写代码的提示词技巧。我踩过的坑是提示词太笼统AI 生成的代码虽然能跑但不符合我的项目结构提示词太细又不如自己写。我总结了一个好用的提示词模板项目背景[一句话说明项目是做什么的] 技术栈[Node.js 20 Express 4 ES Module] 当前文件[src/routes/items.js] 需求[实现一个 GET /api/items/:id 接口从内存数组中查找并返回找不到返回 404] 约束[不要引入新的依赖错误处理用 next(error) 传递给全局错误中间件]这样 AI 生成的代码基本可以直接用不需要大改。关键是给上下文和给约束不要让 AI 自由发挥。4. 常见问题与排查技巧实录4.1 启动报错排查速查表报错信息原因解决方法Cannot find module express依赖没装执行npm installSyntaxError: Cannot use import statement outside a module没配 ES Module在 package.json 加type: moduleEADDRINUSE: address already in use :::3000端口被占用换端口或 kill 掉占用进程req.body为 undefined没加express.json()在路由之前注册该中间件ERR_REQUIRE_ESMCommonJS 和 ESM 混用统一用 import/export 语法端口被占用这个问题特别常见。查占用进程lsof -i :3000然后 kill 掉kill -9 PID或者直接在代码里换个端口用环境变量控制const PORT process.env.PORT || 3001;4.2 AI 接口调用失败的典型场景场景一API Key 无效或过期。报错通常是 401 Unauthorized。检查.env文件里的 Key 是否正确有没有多余的空格或换行。场景二请求超时。报错是timeout of 30000ms exceeded。可能是网络问题也可能是模型负载高。加长超时时间或者加重试逻辑。场景三返回内容被截断。finish_reason是length而不是stop说明max_tokens设小了。调大这个值。场景四并发请求被限流。报错 429 Too Many Requests。需要加请求队列或者降低并发数。我一般用一个简单的信号量控制同时进行的 AI 请求数量不超过 3 个。4.3 我踩过的三个坑和对应的解决方案第一个坑忘记处理异步错误。Express 4 不会自动捕获 async 函数里抛出的错误如果不在 try/catch 里调用next(error)请求会一直挂起直到超时。解决方案是每个 async 路由都包 try/catch或者用一个包装函数const asyncHandler (fn) (req, res, next) { Promise.resolve(fn(req, res, next)).catch(next); }; router.get(/api/items, asyncHandler(async (req, res) { const items await getItems(); res.json({ items }); }));第二个坑CORS 配置不当。开发阶段直接app.use(cors())没问题但上线后最好限制允许的来源app.use(cors({ origin: [https://your-frontend.com], methods: [GET, POST, PUT, DELETE], }));第三个坑没有做请求频率限制。API 服务公开之后可能会被恶意刷接口。加一个简单的限流中间件npm install express-rate-limitimport rateLimit from express-rate-limit; const limiter rateLimit({ windowMs: 60 * 1000, max: 60, message: { error: Too many requests, please try again later }, }); app.use(/api/, limiter);这样每个 IP 每分钟最多请求 60 次超过就返回 429。4.4 部署上线的注意事项本地跑通之后部署到服务器上还有几个点要注意。第一用pm2或systemd守护进程保证服务崩溃后能自动重启。第二用 Nginx 做反向代理处理 HTTPS 证书和静态文件。第三日志要输出到文件方便排查问题。用 pm2 部署很简单npm install -g pm2 pm2 start src/app.js --name ai-api pm2 save pm2 startuppm2 startup会生成一条命令复制执行之后服务器重启时 pm2 会自动拉起你的服务。实操心得部署之前先在本地用NODE_ENVproduction node src/app.js跑一遍确保生产环境下没有报错。有些问题只在生产模式下才会暴露比如某些库的调试输出被关闭后导致的路径问题。5. 这个项目还能怎么扩展5.1 加数据库从内存存储到持久化目前数据存在内存里服务一重启就没了。下一步可以接一个数据库。轻量级场景用 SQLite不需要额外安装服务一个文件就是一个数据库npm install better-sqlite3import Database from better-sqlite3; const db new Database(data.db); db.exec( CREATE TABLE IF NOT EXISTS items ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, price REAL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ) );数据量大或者需要多实例部署时换成 PostgreSQL 或 MySQL。切换数据库只需要改services/里的实现路由层不用动这就是分层架构的好处。5.2 加认证API Key 或 JWT对外提供的 API 服务通常需要认证。最简单的方案是 API Key每个调用方分配一个 Key请求时放在 Header 里服务端校验。function authMiddleware(req, res, next) { const apiKey req.headers[x-api-key]; if (!apiKey || !validKeys.includes(apiKey)) { return res.status(401).json({ error: Invalid API key }); } next(); } app.use(/api/, authMiddleware);更复杂的场景用 JWT支持用户登录、Token 过期刷新等功能。不过对于小项目来说API Key 已经够用了。5.3 加文档让调用方知道怎么用API 写好了别人不知道怎么调也是白搭。可以用 Swagger 自动生成接口文档npm install swagger-ui-express swagger-jsdoc在路由上加注释Swagger 会自动生成可交互的文档页面。调用方打开浏览器就能看到所有接口的说明、参数、返回值还能直接在页面上测试。这个项目从零到跑通大概花了我一个下午的时间其中大部分时间不是在写代码而是在调 AI 生成的代码和排查环境问题。我的体会是AI 能帮你省掉大量敲键盘的时间但省不掉理解代码和排查问题的时间。你越清楚自己想要什么AI 生成的代码就越接近可用状态。反过来如果你自己都不知道要做什么AI 只会给你一堆看起来正确但跑不起来的东西。
