Node.js + Express 从零搭建 API 服务并接入 AI 能力实战

1. 为什么我选 Node.js + Express 来搭这个 API 服务

1.1 从"能跑就行"到"能扛住"的选型逻辑

很多人第一次搭 API 服务，脑子里第一反应是"我用什么语言写不是写"。但真到了要交付、要维护、要给别人接手的时候，选型这件事的权重就上来了。我这次的小项目目标很明确：给一个前端页面提供几个数据接口，包括用户信息查询、列表分页、简单的表单提交，未来可能还要接大模型的能力做点智能问答。需求不复杂，但要求响应快、部署简单、后期好扩展。

Node.js 在这个场景下几乎是天然的选择。原因不复杂：JavaScript 一门语言从前端写到后端，心智负担小；npm 生态里现成的轮子多，不用什么都自己造；非阻塞 I/O 模型处理大量轻量请求时表现稳定，特别适合 API 这种"请求进来、查一下、返回出去"的模式。Express 则是 Node.js 里最成熟的 Web 框架之一，中间件机制清晰，路由写法直观，社区资料多到几乎任何问题都能搜到答案。

我对比过 Fastify。Fastify 性能确实更好，schema 校验也更严格，但它的学习曲线对新手稍微陡一点，插件生态虽然够用但不如 Express 铺得广。这个项目不是追求极致 QPS 的场景，Express 的"够用且好懂"反而成了优势。选型这件事，从来不是选最强的，而是选最匹配当前阶段和团队能力的。

1.2 环境准备：Node.js 版本与安装的坑

环境这块我踩过坑，值得单独说。Node.js 的版本迭代很快，LTS（长期支持版）和 Current（最新特性版）要分清楚。生产环境我一律建议用 LTS，稳定、bug 少、社区支持周期长。写这篇文章时，Node.js 20.x 是主流 LTS，安装方式根据系统不同有差异。

Windows 用户直接去官网下载安装包，一路下一步就行，安装完在命令行敲node -v和npm -v验证。macOS 用户我更推荐用 nvm 来管理版本，因为不同项目可能依赖不同 Node 版本，nvm 可以一键切换。Linux 服务器上也是同理，用 nvm 装比用系统包管理器装更灵活，系统自带的 Node 版本往往偏旧。

# 用 nvm 安装并切换到 Node.js 20 LTS nvm install 20 nvm use 20 node -v

这里有个常见的报错：error installing 24.21.0: node.js v24.21.0 is not yet released。这通常是因为你指定的版本号根本不存在，或者 nvm 的远程版本列表没更新。解决办法是先nvm ls-remote看看有哪些可用版本，别凭记忆瞎写版本号。另一个坑是权限问题，Linux 下如果用 sudo 装全局包，后面可能遇到各种权限拒绝，用 nvm 就能绕开这个雷。

1.3 项目初始化：package.json 里藏着的信息

初始化项目就一条命令npm init -y，它会生成一个默认的package.json。别小看这个文件，它是整个项目的身份证。我习惯手动改几个字段：name改成项目名，version从 0.1.0 起步，scripts里加上start和dev两个脚本，type字段设成module就能用 ES Module 语法，写起来更现代。

{ "name": "mini-api-service", "version": "0.1.0", "type": "module", "scripts": { "start": "node src/index.js", "dev": "node --watch src/index.js" } }

node --watch是 Node.js 18 之后内置的热重载能力，改完代码自动重启，省得装 nodemon。虽然功能没 nodemon 全，但对小项目来说够用了，少一个依赖就少一份维护成本。装 Express 就一句npm install express，装完你会看到node_modules目录和package-lock.json，后者一定要提交到版本控制里，它锁定了依赖的精确版本，保证别人拉下来装的是同一套东西。

2. 从零写出第一个能返回 JSON 的接口

2.1 最小可运行服务的骨架长什么样

先别急着上复杂功能，把"能返回一个 JSON"这件事跑通，是建立信心的第一步。我建了一个src/index.js，内容大概是这样：

import express from 'express'; const app = express(); const PORT = process.env.PORT || 3000; app.use(express.json()); app.get('/api/health', (req, res) => { res.json({ status: 'ok', timestamp: Date.now() }); }); app.listen(PORT, () => { console.log(`API service running on http://localhost:${PORT}`); });

跑起来之后访问http://localhost:3000/api/health，能看到{"status":"ok","timestamp":...}就说明通了。这几行代码里有几个关键点值得展开。express.json()这个中间件负责解析请求体里的 JSON，没有它，POST 请求过来的req.body就是 undefined，这是新手最容易懵的地方。process.env.PORT是为了部署时能通过环境变量指定端口，本地默认 3000，云平台通常会注入自己的端口号。

2.2 路由设计：为什么我坚持用 /api 前缀

路由路径的设计看着随意，其实影响后期维护。我所有接口都挂在/api下面，好处是前端做代理转发时规则简单，Nginx 配置里一个location /api就能把请求转给后端，静态资源和接口泾渭分明。如果以后要加版本管理，可以进一步变成/api/v1/xxx，老接口不动，新接口走 v2，平滑过渡。

RESTful 风格我尽量遵守，但不过度教条。查询用 GET，创建用 POST，更新用 PUT 或 PATCH，删除用 DELETE。资源名用复数，比如/api/users而不是/api/user。这些约定不是法律，但团队协作时大家都按这个来，沟通成本会低很多。我见过有人把所有操作都塞进一个 POST 接口，靠 body 里的 action 字段区分，短期省事，长期就是灾难。

2.3 中间件：请求进出的"关卡"

Express 的中间件本质是一个函数，签名是(req, res, next)，它能在请求到达路由之前或响应发出之后做点事情。这个机制是 Express 的灵魂。我通常会加这么几类中间件：日志记录、跨域处理、错误捕获、请求体解析。

日志中间件我写得简单，打印方法、路径、耗时：

app.use((req, res, next) => { const start = Date.now(); res.on('finish', () => { console.log(`${req.method} ${req.path} ${res.statusCode} ${Date.now() - start}ms`); }); next(); });

跨域处理小项目直接手写就行，不用装 cors 包：

app.use((req, res, next) => { res.setHeader('Access-Control-Allow-Origin', '*'); res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE'); res.setHeader('Access-Control-Allow-Headers', 'Content-Type,Authorization'); if (req.method === 'OPTIONS') return res.sendStatus(204); next(); });

注意：Access-Control-Allow-Origin设成*只适合开发阶段，生产环境要指定具体域名，否则任何网站都能调你的接口，存在安全风险。

中间件的顺序很重要，express.json()要放在路由之前，错误处理中间件要放在所有路由之后。顺序错了，功能就不生效，而且不报错，排查起来很折磨人。

3. 数据层怎么处理：先内存后数据库的渐进路线

3.1 用内存数组先把业务逻辑跑通

小项目最容易犯的错是一上来就设计数据库表结构，结果业务还没想清楚，表改来改去。我的做法是先用内存数组模拟数据，把接口的输入输出、业务规则全部跑通，确认没问题了再换真正的数据库。这样前期迭代速度极快，改数据结构就是改几行代码的事。

let users = [ { id: 1, name: '张三', email: 'zhangsan@example.com' }, { id: 2, name: '李四', email: 'lisi@example.com' } ]; app.get('/api/users', (req, res) => { res.json({ code: 0, data: users, total: users.length }); }); app.get('/api/users/:id', (req, res) => { const user = users.find(u => u.id === Number(req.params.id)); if (!user) return res.status(404).json({ code: 404, message: '用户不存在' }); res.json({ code: 0, data: user }); });

注意req.params.id拿到的是字符串，比较前要转成数字，这是 JavaScript 弱类型带来的经典坑。Number()转换比parseInt()更严格，parseInt('12abc')会返回 12，而Number('12abc')返回 NaN，后者更符合"要么全对要么全错"的预期。

3.2 统一响应格式：让前端少写判断

接口返回格式不统一，前端就得为每个接口写不同的解析逻辑，这是协作中的大忌。我定了一套约定：成功返回{ code: 0, data: ..., message: 'ok' }，失败返回{ code: 非0, message: '错误描述' }。HTTP 状态码也配合使用，404 表示资源不存在，400 表示参数错误，500 表示服务端异常。

function success(res, data, message = 'ok') { res.json({ code: 0, data, message }); } function fail(res, status, message) { res.status(status).json({ code: status, message }); }

封装这两个小函数之后，路由里的代码干净很多。前端拿到响应先看code，是 0 就取data，不是 0 就弹message，一套逻辑走天下。这种约定要写进接口文档里，让所有参与者都遵守。

3.3 分页、筛选、排序的参数设计

列表接口迟早要面对分页。我的参数设计是page（页码，从 1 开始）和pageSize（每页条数，默认 10，上限 100）。为什么要有上限？防止有人传pageSize=999999把服务拖垮。筛选参数用查询字符串，比如?keyword=张&status=active，排序用?sort=createdAt&order=desc。

app.get('/api/users', (req, res) => { const page = Math.max(1, Number(req.query.page) || 1); const pageSize = Math.min(100, Math.max(1, Number(req.query.pageSize) || 10)); const keyword = req.query.keyword || ''; let filtered = users; if (keyword) { filtered = users.filter(u => u.name.includes(keyword)); } const start = (page - 1) * pageSize; const list = filtered.slice(start, start + pageSize); res.json({ code: 0, data: { list, page, pageSize, total: filtered.length } }); });

Math.max和Math.min的组合是防御性编程的典型手法，保证参数落在合理区间。Number(x) || 默认值这个写法能同时处理 undefined、空字符串和 NaN 三种情况，比一堆 if 判断简洁。

4. 接入 AI 能力：让接口"聪明"起来

4.1 为什么要在 API 服务里接大模型

这个项目最初只是个普通 CRUD 服务，但我想让它有点"智能"的味道。比如用户提交一段文字，接口能自动分类、提取关键词，或者做一个简单的问答。大模型的 API 调用本质上就是一次 HTTP 请求，和调用任何第三方服务没区别，把它封装成一个接口，前端就能用。

调用大模型 API 的通用模式是：准备 API Key、构造请求体、发 POST 请求、解析响应。以常见的对话补全接口为例，请求体里通常包含model（模型名）、messages（对话历史数组）、temperature（随机性，0 到 1 之间）等字段。messages里每条消息有role（system/user/assistant）和content。

async function callLLM(prompt) { const response = await fetch('https://api.example.com/v1/chat/completions', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.LLM_API_KEY}` }, body: JSON.stringify({ model: 'your-model-name', messages: [ { role: 'system', content: '你是一个简洁的助手，回答不超过50字。' }, { role: 'user', content: prompt } ], temperature: 0.7 }) }); const data = await response.json(); return data.choices[0].message.content; }

4.2 API Key 管理：绝对不能硬编码

API Key 泄露是新手最常犯的严重错误。把 Key 直接写在代码里，一旦代码上传到公开仓库，别人就能拿你的 Key 刷额度，账单能吓死人。正确做法是用环境变量。本地开发建一个.env文件，里面写LLM_API_KEY=xxx，然后把这个文件加进.gitignore，确保它不会被提交。

Node.js 20 之后内置了--env-file参数，可以不用 dotenv 包：

node --env-file=.env src/index.js

部署到服务器时，在平台的环境变量配置里填 Key，代码里统一用process.env.LLM_API_KEY读取。这样代码和密钥彻底分离，换 Key 不用改代码，代码开源也不怕泄露。

4.3 超时、重试与降级：AI 接口的稳定性设计

大模型接口的响应时间不稳定，快的时候一两秒，慢的时候十几秒甚至超时。如果不做处理，用户会一直卡在那里等。我的做法是给 fetch 加超时控制，用AbortController：

async function callLLMWithTimeout(prompt, timeoutMs = 15000) { const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), timeoutMs); try { const response = await fetch(url, { signal: controller.signal, ... }); return await response.json(); } catch (err) { if (err.name === 'AbortError') { throw new Error('AI 服务响应超时'); } throw err; } finally { clearTimeout(timer); } }

超时之后要有降级方案。比如问答接口超时了，就返回一个"当前繁忙，请稍后再试"的友好提示，而不是让请求挂死。重试要谨慎，因为大模型调用通常按 token 计费，无脑重试会烧钱。我的策略是只对网络层面的错误重试一次，业务层面的错误（比如参数不合法）不重试。

提示：调用大模型接口时，temperature参数控制输出的随机性。做分类、提取这类需要稳定结果的任务，设成 0 到 0.3；做创意写作，可以设到 0.7 到 1.0。这个参数调对了，输出质量差别很大。

5. 错误处理与日志：让问题可追溯

5.1 全局错误中间件：兜住所有漏网之鱼

Express 的错误处理中间件有四个参数(err, req, res, next)，必须四个都写，少一个 Express 就不认。它要放在所有路由和普通中间件之后。任何路由里抛出的异常，或者next(err)传出来的错误，都会汇聚到这里。

app.use((err, req, res, next) => { console.error(`[ERROR] ${req.method} ${req.path}`, err.message); const status = err.status || 500; res.status(status).json({ code: status, message: status === 500 ? '服务器内部错误' : err.message }); });

这里有个细节：500 错误不要把原始错误信息返回给前端，因为可能包含堆栈、数据库结构等敏感信息。日志里记详细的，返回给用户的只给一句笼统的提示。自定义错误可以带status字段，比如参数校验失败抛一个status: 400的错误，中间件就能返回正确的状态码。

5.2 异步路由的错误捕获：Express 4 的老问题

Express 4 有个历史遗留问题：异步路由里抛出的错误不会被自动捕获。比如async (req, res) => { throw new Error('x') }，这个错误不会进错误中间件，而是变成未处理的 Promise rejection。解决办法是包一层：

const asyncHandler = (fn) => (req, res, next) => { Promise.resolve(fn(req, res, next)).catch(next); }; app.get('/api/async-route', asyncHandler(async (req, res) => { const data = await someAsyncOperation(); res.json({ code: 0, data }); }));

Express 5 已经原生支持异步错误捕获，但如果你还在用 4.x，这个asyncHandler包装函数几乎是必备的。我见过太多项目因为漏了这个，异步错误直接让进程崩溃。

5.3 日志分级与输出：别只会 console.log

小项目用console.log没问题，但要养成分级意识。info 记录正常流程，warn 记录可恢复的异常，error 记录需要关注的故障。生产环境建议用 pino 或 winston 这类日志库，它们支持结构化输出（JSON 格式），方便日志系统采集和分析。

const log = { info: (msg, meta) => console.log(JSON.stringify({ level: 'info', msg, ...meta, time: new Date().toISOString() })), error: (msg, meta) => console.error(JSON.stringify({ level: 'error', msg, ...meta, time: new Date().toISOString() })) };

结构化日志的好处是可以用工具按字段检索，比如"找出所有 status 为 500 的请求"或者"统计某个接口的平均耗时"。纯文本日志只能靠 grep，效率低很多。日志里记得带上请求 ID，这样一次请求涉及的多条日志能串起来。

6. 部署上线：从本地到公网的最后一步

6.1 环境变量与配置分离

本地能跑不代表线上能跑，最大的差异往往在配置。端口、数据库连接串、API Key、日志级别，这些都应该通过环境变量注入。我习惯建一个config.js统一读取和校验：

export const config = { port: Number(process.env.PORT) || 3000, nodeEnv: process.env.NODE_ENV || 'development', llmApiKey: process.env.LLM_API_KEY, }; if (!config.llmApiKey && config.nodeEnv === 'production') { throw new Error('生产环境必须配置 LLM_API_KEY'); }

启动时校验关键配置，缺了就立刻报错退出，而不是等到第一次调用接口才发现。这种"快速失败"的策略能省下大量排查时间。

6.2 进程守护与自动重启

Node.js 进程挂了不会自己起来，所以线上要用进程管理工具。pm2 是最常用的选择，pm2 start src/index.js --name api-service就能把服务托管起来，崩溃自动重启，还能看日志、看资源占用。另一种思路是用容器化部署，把服务打包成镜像，由平台负责调度和重启。

pm2 start src/index.js --name api-service pm2 save pm2 startup

pm2 save保存当前进程列表，pm2 startup生成开机自启配置，这两步做完，服务器重启后服务也能自动拉起来。别忘了设置NODE_ENV=production，很多库会根据这个变量切换行为，比如关闭详细错误输出、启用缓存等。

6.3 上线前的自检清单

部署前我会过一遍这个清单，每一条都是踩过坑总结出来的：

npm ci和npm install的区别值得说一句：ci严格按 lock 文件安装，不会更新任何版本，适合 CI/CD 环境；install可能会更新 lock 文件，适合本地开发。生产部署一律用ci，保证每次构建结果一致。

7. 我在这个项目里踩过的几个真实坑

7.1 端口占用：EADDRINUSE 的排查

服务启动报EADDRINUSE: address already in use :::3000，意思是 3000 端口被占了。原因通常是上一次的服务没关干净，或者有别的程序在用这个端口。排查方法：Linux/macOS 用lsof -i :3000找到进程号，然后kill -9 进程号；Windows 用netstat -ano | findstr :3000找 PID，再taskkill /PID 进程号 /F。更省事的办法是启动前先杀掉占用端口的进程，或者干脆换个端口。

7.2 JSON 解析失败：请求体格式的隐形陷阱

前端发 POST 请求，后端req.body是空对象，十有八九是 Content-Type 没设对。express.json()只解析Content-Type: application/json的请求，如果前端发的是text/plain或者没设这个头，body 就不会被解析。用 Postman 测试时记得选 Body 里的 raw + JSON，用 fetch 时要显式设置 headers。

7.3 数字与字符串：JavaScript 类型转换的经典坑

前面提过req.params.id是字符串，但还有更隐蔽的。比如从查询字符串拿到的page也是字符串，'2' + 1得到'21'而不是3。所有来自 URL、请求体的数据，类型都不可信，该转数字就转数字，该校验就校验。我现在的习惯是入口处统一做一次类型转换和校验，后面就按确定的类型用。

7.4 循环里发异步请求：别用 forEach

需要批量调用接口时，array.forEach(async item => { await ... })是个陷阱，forEach 不会等待异步回调完成，循环结束就往下走了。正确做法是用for...of配合 await，或者Promise.all并发处理：

// 错误示范 items.forEach(async (item) => { await processItem(item); }); console.log('这行会在所有处理完成前执行'); // 正确示范 for (const item of items) { await processItem(item); } console.log('这行会在所有处理完成后执行');

如果各条处理之间没有依赖，用Promise.all(items.map(processItem))并发跑更快，但要注意控制并发数量，别一次发几百个请求把对方接口打挂。

8. 后续可以怎么扩展这个服务

这套骨架跑通之后，往上加东西就很顺了。数据层可以从内存换成 SQLite 或 PostgreSQL，接口不用改，只改数据访问那几行。认证可以加 JWT，登录接口发 token，其他接口用中间件校验。限流可以用 express-rate-limit，防止有人恶意刷接口。接口文档可以用 swagger 自动生成，前端对接时省去大量沟通。

AI 能力这块，除了简单的问答，还能做流式输出。大模型支持 SSE（Server-Sent Events）逐字返回，前端体验会好很多，用户不用等整段生成完才看到内容。实现上就是把上游的流透传给前端，设置Content-Type: text/event-stream，边收边发。这个稍微复杂点，但原理不神秘，就是管道转发。

我个人在实际操作中的体会是，小项目最大的价值不在于功能多全，而在于把"从零到上线"的完整链路走一遍。走通了这一遍，下次遇到再复杂的项目，心里也有底，知道每一步该干什么、坑在哪里。这套代码我后来直接当模板用，换个业务逻辑就能开新项目，省下的时间相当可观。