★ FEATURED ARTICLE 1. 项目缘起与整体设计思路1.1 为什么选这个题目练手做了几年后端开发我越来越觉得很多新手包括当年我自己学 Node.js 和 Express 的方式有问题——看了一堆文档知道app.get()怎么写知道中间件大概是个什么概念但真要从零搭一个能跑、能看、能扩展的 API 服务脑子里还是一团浆糊。所以我一直想找一个足够小、但又能把核心链路串起来的实战项目作为团队新人练手或者自己温故知新的素材。“用 AI 从零搭一个 API 服务”这个题目恰好满足几个条件第一API 服务是后端最基础的形态几乎所有业务系统都绕不开第二Node.js Express 是目前上手成本最低、生态最成熟的组合之一新手不用在环境配置上耗太久第三把 AI 引入进来不是赶时髦而是让 AI 承担“代码生成 方案建议 排错辅助”的角色把原本需要查文档、搜社区、反复试错的过程压缩掉让注意力集中在服务本身的设计和实现上。这个项目适合谁如果你刚学完 JavaScript 基础语法想找一个能落地的练手项目或者你之前用其他语言写过服务端想快速了解 Node.js 生态下 API 服务长什么样再或者你已经在做业务开发但想看看 AI 辅助编码到底能在多大程度上提升效率——这个项目都值得跟着走一遍。1.2 整体架构与选型考量在动手之前先把整体结构想清楚。一个最小可用的 API 服务至少需要这几层HTTP 服务层负责接收请求和返回响应路由层负责把不同 URL 映射到不同处理逻辑业务逻辑层负责具体的数据处理数据层负责持久化哪怕先用内存或 JSON 文件顶着。Express 在这套结构里扮演的是 HTTP 服务层 路由层的角色它足够轻不会强迫你接受一套复杂的框架约定同时又提供了中间件机制让你可以按需插入日志、鉴权、错误处理等逻辑。为什么不用 FastifyFastify 性能确实更好Schema 校验也更规范但对于一个练手项目来说Express 的文档丰富度和社区示例数量是压倒性的优势。你遇到任何问题搜索“Express 某个需求”几乎都能找到现成的答案。Fastify 的生态虽然也在成长但新手在排错时容易卡在一些冷门问题上。所以这个项目选 Express不是因为它最好而是因为它最适合“从零搭一个能跑的服务”这个目标。Node.js 版本方面我建议直接用当前 LTS 版本。写这篇文章时Node.js 20.x 是主流 LTS安装方式后面会详细说。JavaScript 方面这个项目用原生 JS 就够了不需要 TypeScript——不是 TypeScript 不好而是练手阶段先把运行时逻辑跑通比纠结类型定义更重要。等你把服务搭起来、跑通了再考虑用 TypeScript 重构那时候你对整体结构的理解会深得多。AI 在这个项目里的角色我把它定位为“结对编程的伙伴”你告诉它你要什么它给你代码草稿你运行报错了把错误贴给它它帮你分析原因你想加一个功能不知道从哪下手它给你几种方案让你选。但最终的决定权和调试责任还是在你手里。这一点很重要——AI 生成的代码不是拿来就能用的你需要理解每一行在干什么否则出了问题你根本不知道怎么修。1.3 项目最终形态预览在正式开始之前先让你看看这个项目做完之后大概长什么样这样你心里有个目标。最终我们会得到一个运行在本地 3000 端口的 API 服务提供以下几组接口健康检查接口GET /health用来确认服务是否正常用户资源的增删改查接口GET/POST/PUT/DELETE /api/users用来演示标准的 RESTful 风格以及一个简单的搜索接口GET /api/users?keywordxxx用来演示查询参数的解析和过滤逻辑。数据先存在内存里服务重启后数据会丢失但这不影响我们理解 API 服务的核心流程。后续如果你想扩展可以把内存存储换成 SQLite 或 PostgreSQL那是下一步的事。整个项目的代码量大概在 200 行左右分文件组织结构清晰。你跟着走一遍大概需要 1 到 2 小时取决于你对 JavaScript 和命令行的熟悉程度。如果你完全没接触过 Node.js可能需要 3 小时左右因为环境安装和调试会花一些时间。但相信我这个时间投入是值得的——走完一遍之后你对 API 服务的理解会从“知道概念”变成“亲手做过”。2. 环境准备与 AI 辅助编码的定位2.1 Node.js 安装别在这步卡太久Node.js 的安装本身不复杂但新手容易在版本选择和环境变量上出问题。我的建议是直接去 Node.js 官网下载 LTS 版本的安装包Windows 选.msimacOS 选.pkg一路下一步就行。安装完成后打开终端Windows 用 PowerShell 或 CMDmacOS 用 Terminal输入node -v和npm -v如果都能输出版本号说明安装成功。如果你在 Ubuntu 上用包管理器安装可能会遇到版本过旧的问题。Ubuntu 自带的 apt 源里的 Node.js 版本往往落后好几个大版本所以更推荐用 NodeSource 的源来安装。具体命令是先curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -然后sudo apt-get install -y nodejs。这两条命令执行完之后再用node -v确认版本。注意这里涉及的是正常的软件源配置属于标准的开发环境搭建流程。有一个坑我踩过如果你之前用其他方式装过 Node.js可能会有多个版本共存导致node -v显示的版本和你预期的不一样。这时候可以用which nodemacOS/Linux或where nodeWindows看看当前用的是哪个路径下的 Node.js。如果路径不对要么调整环境变量要么把旧的卸载掉。这个问题不解决后面装依赖时会出现各种莫名其妙的错误。2.2 初始化项目与依赖安装环境好了之后找一个空目录执行npm init -y这会生成一个默认的package.json。然后安装 Expressnpm install express。如果你想让开发过程更顺畅可以再装一个nodemon作为开发依赖npm install --save-dev nodemon。nodemon 的作用是监听文件变化自动重启服务这样你改完代码不用手动CtrlC再重新node index.js效率会高很多。在package.json里把scripts部分改成这样scripts: { start: node index.js, dev: nodemon index.js }这样开发时用npm run dev生产环境用npm start。虽然这个练手项目谈不上生产环境但养成区分开发和生产脚本的习惯是好的。2.3 AI 在编码过程中的正确打开方式很多人用 AI 辅助编码方式不对——直接把需求丢给 AI让它生成一大段代码然后复制粘贴跑不起来就再问一遍。这种方式效率其实很低因为你没有理解代码出了问题只能反复问 AI而 AI 每次给的答案可能都不一样你会越来越糊涂。我的做法是把 AI 当成一个“随时可以问的资深同事”。具体来说在写每一部分代码之前先自己想清楚这部分要做什么然后问 AI“用 Express 实现 XXX 功能代码大概怎么写”拿到代码后逐行看一遍不理解的地方追问。运行报错时把完整的错误信息贴给 AI同时说明你正在做什么让它帮你定位问题。这样一轮下来你不仅得到了能跑的代码还理解了背后的逻辑。举个例子当你需要实现“根据 ID 获取单个用户”的接口时你可以先自己想需要从请求参数里拿到 ID然后在用户数组里查找找到就返回找不到就返回 404。然后问 AI“Express 里怎么获取 URL 参数”它会告诉你用req.params.id。你再问“怎么返回 404 状态码”它会告诉你用res.status(404).json(...)。这样一步步拼起来比直接要一整段代码收获大得多。3. 核心功能实现与关键细节3.1 服务入口与基础中间件配置先创建index.js这是服务的入口文件。基础结构大概是这样的引入 Express创建 app 实例配置中间件定义路由启动监听。中间件方面至少需要express.json()来解析 JSON 请求体否则 POST 和 PUT 请求里的req.body会是 undefined。这个坑很常见——新手写了 POST 接口测试时发现req.body是空的查半天以为是前端没传对其实是忘了加express.json()。const express require(express); const app express(); const PORT process.env.PORT || 3000; app.use(express.json()); // 路由定义放在这里 app.listen(PORT, () { console.log(Server running on port ${PORT}); });process.env.PORT || 3000这个写法是为了兼容部署环境——很多云平台会通过环境变量指定端口本地开发时没有这个变量就默认用 3000。这是一个很小的细节但养成这个习惯没坏处。3.2 数据层先用内存数组顶着练手项目不需要一上来就上数据库。用内存数组存数据简单直接能把注意力集中在 API 逻辑上。定义一个users数组每个元素是一个对象包含id、name、email三个字段。id 用自增的方式生成可以定义一个nextId变量每次新增用户时nextId。let users [ { id: 1, name: 张三, email: zhangsanexample.com }, { id: 2, name: 李四, email: lisiexample.com } ]; let nextId 3;这里预置两条数据方便测试查询接口。实际开发中你可能需要更复杂的数据结构但练手阶段这样足够了。注意内存存储的缺点是服务重启后数据丢失所以不要用它存重要数据。如果你想让数据持久化可以把数组读写到 JSON 文件里用fs模块操作但那是另一个话题了。3.3 路由设计RESTful 风格的增删改查RESTful 是一种 API 设计风格核心思想是用 HTTP 方法表示操作类型GET 查、POST 增、PUT 改、DELETE 删。URL 表示资源比如/api/users表示用户集合/api/users/1表示 ID 为 1 的用户。这种风格的好处是直观、统一前端开发者看到 URL 和方法就能猜到接口的作用。先写健康检查接口app.get(/health, (req, res) { res.json({ status: ok, timestamp: new Date().toISOString() }); });这个接口看起来没什么用但在实际项目中很重要——部署之后你需要一个方式来确认服务是否正常启动。很多云平台也要求你提供一个健康检查端点用来判断服务是否存活。然后是获取用户列表app.get(/api/users, (req, res) { const { keyword } req.query; let result users; if (keyword) { result users.filter(u u.name.includes(keyword) || u.email.includes(keyword) ); } res.json({ data: result, total: result.length }); });这里顺便实现了搜索功能——如果 URL 里带了keyword查询参数就按名称或邮箱过滤。req.query是 Express 自动解析的查询参数对象不需要额外配置。返回结构用{ data, total }包裹而不是直接返回数组这样后续加分页信息时不用改返回结构前端也不用改解析逻辑。获取单个用户app.get(/api/users/:id, (req, res) { const id parseInt(req.params.id, 10); const user users.find(u u.id id); if (!user) { return res.status(404).json({ error: User not found }); } res.json({ data: user }); });注意parseInt(req.params.id, 10)这一步——URL 参数默认是字符串如果不转成数字u.id id永远为 false因为1 1是 false。这个坑我见过很多人踩表现就是“明明数据存在但就是查不到”。加个parseInt就解决了。新增用户app.post(/api/users, (req, res) { const { name, email } req.body; if (!name || !email) { return res.status(400).json({ error: Name and email are required }); } const newUser { id: nextId, name, email }; users.push(newUser); res.status(201).json({ data: newUser }); });这里做了基本的参数校验——name 和 email 必填缺了就返回 400。返回状态码用 201 表示“已创建”这是 RESTful 的惯例。虽然用 200 也不会报错但遵循惯例能让你的 API 更规范。更新用户app.put(/api/users/:id, (req, res) { const id parseInt(req.params.id, 10); const user users.find(u u.id id); if (!user) { return res.status(404).json({ error: User not found }); } const { name, email } req.body; if (name) user.name name; if (email) user.email email; res.json({ data: user }); });这里用的是“部分更新”逻辑——只更新传了的字段。严格来说 PUT 应该全量替换PATCH 才是部分更新但实际项目中很多人用 PUT 做部分更新前端也习惯了。如果你想更规范可以把 PUT 改成 PATCH或者两个都提供。删除用户app.delete(/api/users/:id, (req, res) { const id parseInt(req.params.id, 10); const index users.findIndex(u u.id id); if (index -1) { return res.status(404).json({ error: User not found }); } users.splice(index, 1); res.status(204).send(); });删除成功返回 204表示“成功但没有内容返回”。这也是 RESTful 的惯例。如果你返回 200 加一个{ message: deleted }也不会错但 204 更简洁。3.4 错误处理与 404 兜底上面的路由都是正常流程但实际运行中会有各种意外——请求了不存在的路径、服务器内部出错等。Express 提供了错误处理中间件机制可以统一捕获和处理错误。在所有的路由定义之后加一个 404 处理和一个错误处理app.use((req, res) { res.status(404).json({ error: Not found }); }); app.use((err, req, res, next) { console.error(err.stack); res.status(500).json({ error: Internal server error }); });404 处理放在所有路由之后意思是“如果前面的路由都没匹配上就走到这里”。错误处理中间件有四个参数(err, req, res, next)Express 通过参数个数来识别它是错误处理中间件。这个机制很巧妙但新手容易写错——少写一个参数Express 就把它当普通中间件了错误不会被捕获。4. 常见问题与排查技巧实录4.1 启动报错端口被占用怎么办这是最常见的问题之一。你运行npm run dev终端报Error: listen EADDRINUSE: address already in use :::3000意思是 3000 端口已经被别的程序占用了。可能是你之前启动的服务没关干净也可能是其他软件占用了这个端口。解决办法有两个一是找到占用端口的进程并杀掉。在 macOS/Linux 上用lsof -i :3000找到进程 ID然后kill -9 PID。在 Windows 上用netstat -ano | findstr :3000找到 PID然后taskkill /PID PID /F。二是换个端口把PORT改成 3001 或别的。我一般先用第一种方法实在找不到占用进程再换端口。4.2 请求体为空req.body是 undefined前面提过忘了加express.json()是最常见的原因。但还有一种情况你加了express.json()但前端发送请求时Content-Type没设成application/json。Express 的express.json()只解析Content-Type: application/json的请求体如果前端用的是application/x-www-form-urlencoded或没设 Content-Typereq.body就会是空的。排查方法在路由处理函数里加一行console.log(req.headers[content-type])看看实际收到的 Content-Type 是什么。如果是前端问题让前端改如果是你自己用 Postman 或 curl 测试检查一下请求头设置。4.3 ID 比较失败字符串和数字的坑前面提到过req.params.id是字符串直接和数字比较会失败。除了用parseInt还有一种情况是数据库返回的 ID 是字符串比如 MongoDB 的 ObjectId而你在代码里用数字比较。这种问题的表现是“数据明明存在但查询返回空”。排查时在比较之前把两个值都打印出来看看类型是否一致。JavaScript 的会做类型转换不会所以用比较时类型不一致就会返回 false。我的习惯是所有从外部来的 ID先转成数字如果是数字型 ID再参与比较。4.4 nodemon 不生效文件监听失效有时候你改了代码nodemon 没有自动重启。可能的原因有几个一是 nodemon 没装成功检查package.json的devDependencies里有没有它二是你改的文件不在 nodemon 的监听范围内默认它监听当前目录下的.js、.json等文件如果你把代码写在了别的目录需要配置nodemon.json指定监听路径三是文件系统监听数量限制在 Linux 上可能会遇到ENOSPC错误需要调整fs.inotify.max_user_watches参数。不过对于这个练手项目一般不会遇到第三种情况。4.5 常见问题速查表问题现象可能原因排查方法解决方案启动报 EADDRINUSE端口被占用lsof -i :3000或netstat -ano杀掉进程或换端口req.body为 undefined缺express.json()或 Content-Type 不对打印req.headers[content-type]加中间件或修正请求头按 ID 查询返回空字符串和数字比较失败打印typeof req.params.id用parseInt转换nodemon 不重启监听配置问题检查 nodemon 是否运行配置监听路径或重装404 处理不生效放在了路由之前检查代码顺序移到所有路由之后错误处理不捕获中间件参数个数不对检查是否四个参数补全(err, req, res, next)4.6 用 AI 排错的正确姿势当你遇到报错时不要只把错误信息贴给 AI还要附上相关代码和你的操作步骤。比如“我运行npm run dev终端报了这个错Error: listen EADDRINUSE: address already in use :::3000我之前启动过一个服务但已经 CtrlC 了现在应该怎么处理”这样 AI 能更准确地判断问题。如果你只贴一句错误信息AI 可能会给出多种可能的原因你还得自己一个个试效率反而低。另外AI 给出的解决方案你要理解之后再执行。比如它让你kill -9 PID你要知道这是在强制杀掉进程确认那个进程确实是你想杀的那个再执行。不要盲目复制粘贴命令尤其是涉及系统操作的命令。5. 项目扩展与个人经验分享5.1 从内存到数据库下一步怎么走这个项目的数据存在内存里服务重启就没了。如果你想让它更实用下一步可以把存储换成 SQLite。SQLite 是一个文件型数据库不需要单独安装服务Node.js 里有better-sqlite3这个库用起来很简单。再往后可以换成 PostgreSQL 或 MySQL那就更接近真实项目了。但我的建议是先把内存版本跑通、理解透再考虑换数据库。否则你会在数据库配置、连接池、SQL 语句上花很多时间反而忽略了 API 服务本身的设计。5.2 加一层日志中间件实际项目中日志是必不可少的。你可以在 Express 里加一个简单的日志中间件记录每个请求的方法、路径、状态码和耗时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(); });这个中间件放在所有路由之前这样每个请求都会经过它。res.on(finish)是在响应发送完成后触发这时候能拿到最终的状态码。这个日志格式虽然简单但足够你排查大部分问题——哪个接口慢了、哪个接口报错了一目了然。5.3 参数校验别等到出问题才补上面的代码里我只做了最基本的必填校验。实际项目中参数校验要严格得多——email 格式对不对、name 长度有没有超、有没有非法字符等。你可以手写校验逻辑也可以用joi或express-validator这类库。我的建议是练手阶段先手写理解校验的逻辑等项目复杂了再引入校验库减少重复代码。手写校验的时候注意把校验逻辑抽成单独的函数不要全堆在路由处理函数里否则代码会很难维护。5.4 我踩过的几个坑第一个坑是忘了加express.json()导致 POST 请求的req.body一直是空的查了半小时才发现。第二个坑是req.params.id没转数字查询一直返回 404打印出来才发现是字符串。第三个坑是 404 处理写在了路由前面导致所有请求都被 404 拦截了。这三个坑都很典型你在写的时候注意一下能省不少时间。还有一个经验用 Postman 或 curl 测试接口时先把每个接口的正常流程跑通再测试异常情况比如传空值、传不存在的 ID。这样出问题时你能快速判断是正常流程的问题还是异常处理的问题。我见过有人一上来就测各种边界情况结果正常流程都没跑通排查起来很混乱。5.5 这个项目还能怎么玩如果你已经把基础版本跑通了可以试试这几个扩展方向加一个PATCH /api/users/:id接口实现部分更新加一个分页功能GET /api/users?page1size10加一个简单的 API Key 鉴权请求头里带x-api-key才能访问把数据存到 JSON 文件里实现简单的持久化。每一个扩展都不难但能让你对 API 服务的理解更深一层。我个人在实际操作中的体会是搭 API 服务这件事看十遍不如亲手写一遍。你可能会在环境配置上卡住可能会在某个报错上耗时间但正是这些卡住和耗时间的时刻让你真正理解了服务是怎么跑起来的。AI 能帮你省掉一些查文档的时间但不能替你理解代码。所以动手写遇到问题解决问题这才是最快的成长路径。
阅读完成 · 觉得有帮助？
