1. 为什么我建议每个开发者都动手搭一个 API 服务说实话写了这么多年代码我越来越觉得“能跑起来”和“能对外提供服务”之间隔着一道很深的沟。很多新手朋友学 Node.js跟着教程写了个console.log(hello world)或者用 Express 起了个本地服务浏览器打开localhost:3000看到一行字就觉得自己会后端了。但真让他从零搭一个能给别人调用的 API 服务立刻就卡住了——端口怎么选、路由怎么分、参数怎么校验、错误怎么处理、跨域怎么办、怎么部署到服务器上让别人访问这一连串问题全冒出来了。这篇内容就是来解决这个问题的。我打算用一个周末就能搞定的小项目实战带你从零开始用AI 辅助 Node.js Express JavaScript这套组合搭一个结构完整、能真正对外提供服务的API 服务。这个服务不复杂就是一个“待办事项管理”的接口包含增删改查四个基本操作但麻雀虽小五脏俱全路由设计、中间件、参数校验、错误处理、日志、跨域、环境变量、部署上线该有的全都有。你可能会问现在都 2025 年了AI 都能一键生成代码了为什么还要自己动手搭我的答案是AI 能帮你写代码但不能替你理解系统。你让 AI 生成一个 Express 服务它三秒钟就能吐出来但如果你不知道app.use(express.json())这行代码为什么必须放在路由注册之前不知道req.body什么时候是undefined不知道错误中间件为什么必须写四个参数那你拿到代码也只是个“代码搬运工”出了问题完全无从下手。这个项目的核心价值就是让你在动手的过程中把这些“为什么”一个个搞清楚。适合谁来参考这份实战记录我总结了三类人。第一类是刚学完 JavaScript 基础、想往全栈方向走的新手你懂变量、函数、数组、对象但没写过真正的服务端代码这个项目就是你的第一块敲门砖。第二类是前端开发者想补后端短板你天天调别人的 API但不知道 API 是怎么被造出来的自己搭一个以后跟后端沟通会顺畅很多。第三类是想用 AI 提效但不知道怎么下手的开发者我会在过程中展示怎么把 AI 当成结对编程的伙伴而不是无脑复制粘贴的工具。整个项目我会按照真实的开发流程来写先做技术选型和环境准备再设计接口和目录结构然后逐个模块实现接着处理那些新手最容易踩的坑最后部署上线并做一轮完整的测试。每一步我都会解释“为什么这么做”而不是只告诉你“这么做”。代码我会给全但更重要的是背后的思路。你跟着走一遍以后遇到任何类似的小项目都能自己独立搭起来。2. 技术选型与环境准备为什么是 Node.js Express2.1 选型背后的真实考量先说说为什么选Node.js和Express这套组合。市面上的后端技术栈多得是Python 有 Django 和 FastAPIJava 有 Spring BootGo 有 Gin为什么偏偏选 Node.js原因很实际对前端开发者最友好学习成本最低而且生态足够成熟。你写 JavaScript 的那套语法、那些思维习惯在 Node.js 里几乎可以无缝迁移不用重新学一门语言的语法糖。而且 Node.js 的非阻塞 I/O 模型特别适合 API 服务这种“请求-响应”密集型的场景处理大量并发请求时资源占用很低。那为什么是 Express 而不是 Fastify 或者 KoaExpress 确实是“老古董”了2010 年就发布了但它的优势恰恰在于老——文档最全、社区最大、遇到问题一搜就有答案、中间件生态最丰富。对于新手来说这一点太重要了。Fastify 性能确实更好但它的插件机制和生命周期钩子对新手不够友好Koa 的洋葱模型很优雅但需要自己组装的东西太多。Express 就像一把用了十几年的老菜刀不花哨但切菜就是顺手。等你把这个项目跑通了再去了解 Fastify 和 Koa会更容易理解它们各自的设计取舍。至于AI 辅助我的定位很明确AI 是我的结对编程伙伴不是我的代笔。我会用它来生成样板代码、解释报错信息、提供多种实现思路但每一行代码我都会自己过一遍搞清楚它在干什么。这样既提高了效率又保证了理解深度。后面我会具体展示怎么跟 AI 配合。2.2 环境搭建的完整步骤环境准备这块我踩过的坑比想象中多。很多人卡在第一步——Node.js 装不上或者版本不对。我建议直接用nvmNode Version Manager来管理 Node.js 版本这样以后切换版本不用卸载重装。Windows 用户可以用 nvm-windowsMac 和 Linux 用户用官方的 nvm 脚本。安装 Node.js 的时候选LTS 版本长期支持版不要选 Current 版。LTS 版本更稳定社区支持周期更长生产环境基本都用 LTS。截至我写这篇内容的时候Node.js 20.x 和 22.x 都是 LTS选哪个都行我用的 20.x。安装完成后打开终端验证一下node -v npm -v两条命令都能输出版本号说明装好了。如果提示“command not found”大概率是环境变量没配好重启终端或者检查 PATH。接下来创建项目目录初始化 npmmkdir todo-api cd todo-api npm init -ynpm init -y会生成一个默认的package.json里面的字段都是默认值。我习惯手动改一下name、version、description和main让它更符合项目实际。然后安装核心依赖npm install express cors dotenv npm install -D nodemon这里解释一下每个包的作用。express是 Web 框架本体cors处理跨域请求前端调接口必备dotenv用来读取.env文件里的环境变量避免把敏感配置硬编码在代码里nodemon是开发工具监听文件变化自动重启服务省得每次改代码都手动 CtrlC 再重启。注意nodemon装在devDependencies里因为它只在开发环境用生产环境不需要。提示npm install和npm install -D的区别一定要搞清楚。前者装的包会出现在dependencies里是项目运行必需的后者装的包在devDependencies里只在开发阶段用。部署到生产环境时用npm install --production就只会装dependencies能减小体积、加快部署。装完之后在package.json的scripts里加两行scripts: { start: node src/app.js, dev: nodemon src/app.js }这样开发时跑npm run dev生产环境跑npm start。约定俗成的做法团队协作时别人一看就懂。2.3 目录结构的设计逻辑新手最容易犯的错就是把所有代码堆在一个app.js里。项目小的时候没问题一旦接口多了、逻辑复杂了那个文件会变成几千行的“屎山”改一处崩三处。所以从第一天起就要养成分层的习惯。我的目录结构是这样的todo-api/ ├── src/ │ ├── app.js # 应用入口组装中间件和路由 │ ├── routes/ │ │ └── todos.js # 待办事项相关路由 │ ├── controllers/ │ │ └── todoController.js # 业务逻辑处理 │ ├── middlewares/ │ │ ├── errorHandler.js # 统一错误处理 │ │ └── logger.js # 请求日志 │ └── utils/ │ └── response.js # 统一响应格式 ├── .env # 环境变量不提交到 git ├── .env.example # 环境变量示例提交到 git ├── .gitignore └── package.json这个结构对应的是经典的MVC 变体路由层负责“哪个 URL 对应哪个处理函数”控制器层负责“具体怎么处理业务”中间件层负责“请求前后的通用逻辑”。这样分层的好处是当你需要改某个接口的逻辑时只需要动对应的控制器文件不会影响到其他部分。而且这种结构是业界通用的以后你去看别人的 Express 项目基本都能对上号。.env文件里放什么至少放两个PORT和NODE_ENV。PORT是服务监听的端口NODE_ENV区分开发和生产环境。.env绝对不能提交到 git因为里面可能有数据库密码、API 密钥之类的敏感信息。所以要建一个.env.example里面只写变量名不写真实值作为团队成员的配置参考。.gitignore里加上node_modules/、.env、*.log这几项。3. 接口设计与核心代码实现3.1 先把接口设计想清楚再动手很多人一上来就写代码写着写着发现接口设计不合理又回头改浪费时间。我的习惯是先用文字把接口定义写清楚相当于给自己画一张地图。这个待办事项服务我设计了五个接口方法路径功能请求体响应GET/api/todos获取所有待办无待办数组GET/api/todos/:id获取单个待办无单个待办对象POST/api/todos创建待办{title, completed?}新建的待办对象PUT/api/todos/:id更新待办{title?, completed?}更新后的对象DELETE/api/todos/:id删除待办无空响应设计接口时有几个原则要遵守。第一用名词复数表示资源所以是/todos而不是/todo或/getTodo。第二用 HTTP 方法表示操作GET 查、POST 增、PUT 改、DELETE 删不要用/deleteTodo这种动词路径。第三版本化路径里加/api前缀以后要升级接口可以改成/api/v2不影响老用户。第四统一响应格式成功和失败都返回固定结构前端处理起来方便。统一响应格式我设计成这样// 成功 { success: true, data: { ... }, message: 操作成功 } // 失败 { success: false, error: { code: VALIDATION_ERROR, message: 标题不能为空 } }为什么要统一因为前端拿到响应后只需要判断success字段就知道成功还是失败不用去猜每个接口的返回结构。这是 API 设计的基本素养也是面试常考点。3.2 用 AI 辅助生成基础代码接口设计清楚了接下来写代码。这时候 AI 就派上用场了。我的做法是给 AI 一个清晰的提示词让它生成基础骨架然后我自己填充细节。比如我会这样问“用 Express 写一个待办事项 API 的路由文件包含 GET /todos、GET /todos/:id、POST /todos、PUT /todos/:id、DELETE /todos/:id 五个接口路由处理函数先留空只写路由注册部分。”AI 会很快给我一个routes/todos.js的骨架。但注意AI 生成的代码不能直接用它可能用了过时的写法或者漏掉了错误处理。我要做的是把它当成一个“打字员”帮我省去敲样板代码的时间然后我逐行审查、修改、补充。比如 AI 生成的代码里路由处理函数可能是直接写在路由文件里的。但按照我们前面的分层设计业务逻辑应该放在控制器里。所以我会把 AI 生成的代码改造成路由只负责映射控制器负责逻辑。这个改造过程就是理解分层思想的过程。3.3 控制器层的实现细节控制器是业务逻辑的核心。我以创建待办POST为例讲讲实现细节。首先数据存哪里这个项目为了简单用内存数组模拟数据库。真实项目当然要用数据库但内存数组足够我们理解 API 服务的完整流程而且不用额外装数据库降低了上手门槛。// src/controllers/todoController.js let todos []; let nextId 1; const createTodo (req, res, next) { try { const { title, completed false } req.body; // 参数校验 if (!title || typeof title ! string || title.trim() ) { return res.status(400).json({ success: false, error: { code: VALIDATION_ERROR, message: 标题不能为空且必须是字符串 } }); } const todo { id: nextId, title: title.trim(), completed: Boolean(completed), createdAt: new Date().toISOString() }; todos.push(todo); res.status(201).json({ success: true, data: todo, message: 创建成功 }); } catch (err) { next(err); // 交给错误中间件处理 } };这段代码里有几个关键点值得展开。第一参数校验必须做。你永远不能相信客户端传来的数据req.body可能是空的title可能是数字、对象、甚至undefined。不校验的话脏数据进了数据库后面排查起来要命。第二title.trim()去掉首尾空格防止用户输入一堆空格绕过校验。第三返回 201 状态码表示资源创建成功这是 HTTP 语义的规范。第四用next(err)把异常交给统一错误处理中间件而不是在每个控制器里写res.status(500).json(...)这样代码更干净。其他几个接口的实现思路类似我就不逐个贴了。核心是查询类接口处理“找不到”的情况返回 404更新和删除类接口先查再改参数校验统一处理。这些细节看起来琐碎但正是它们决定了一个 API 服务是“能用”还是“好用”。3.4 中间件的正确使用姿势中间件是 Express 的灵魂也是新手最容易懵的地方。我重点讲三个必用的中间件。第一个是express.json()。它的作用是解析请求体里的 JSON 数据把结果挂到req.body上。如果不加这行req.body就是undefined你的 POST 接口永远拿不到数据。它必须放在路由注册之前因为 Express 的中间件是按注册顺序执行的请求进来先过express.json()解析再到路由处理函数。第二个是 CORS 中间件。前端在localhost:5173后端在localhost:3000浏览器会因为同源策略拦截请求。cors中间件就是给响应加上Access-Control-Allow-Origin等头部告诉浏览器“这个跨域请求我允许”。开发环境可以简单用app.use(cors())允许所有来源但生产环境一定要配置白名单只允许你自己的域名否则会有安全风险。第三个是自定义的请求日志中间件。每次请求进来打印方法、路径、耗时方便调试和监控// src/middlewares/logger.js const logger (req, res, next) { const start Date.now(); res.on(finish, () { const duration Date.now() - start; console.log(${req.method} ${req.originalUrl} ${res.statusCode} - ${duration}ms); }); next(); };这里用res.on(finish)而不是直接在next()前后打印是因为响应还没结束时状态码是拿不到的。finish事件在响应完全发送后触发这时候res.statusCode才是最终值。这个小技巧很多人不知道值得记一下。3.5 统一错误处理的四个参数错误处理中间件是 Express 里最特殊的一个它必须写四个参数(err, req, res, next)。少一个 Express 就不认会把它当成普通中间件。这个设计经常被吐槽但记住就行。// src/middlewares/errorHandler.js const errorHandler (err, req, res, next) { console.error(Error:, err.message); const statusCode err.statusCode || 500; const message err.message || 服务器内部错误; res.status(statusCode).json({ success: false, error: { code: err.code || INTERNAL_ERROR, message: process.env.NODE_ENV production ? 服务器内部错误 : message } }); };注意最后那个三元表达式生产环境不暴露具体错误信息只返回笼统的“服务器内部错误”。为什么因为具体的错误信息可能包含数据库结构、文件路径等敏感信息暴露给攻击者等于送情报。开发环境则保留详细信息方便调试。这个细节体现的是安全意识面试时能说出来会加分。错误中间件必须注册在所有路由之后因为它是“兜底”的只有前面的路由都没处理才会走到它这里。4. 那些新手必踩的坑与排查技巧4.1 端口被占用怎么办这是最高频的问题没有之一。你跑npm run dev终端报错EADDRINUSE: address already in use :::3000意思是 3000 端口被别的程序占了。原因可能是你上次的服务没关干净或者别的软件占用了这个端口。排查方法Mac 和 Linux 用lsof -i :3000查看谁占用了端口Windows 用netstat -ano | findstr :3000。找到进程 ID 后用kill -9 PIDMac/Linux或taskkill /PID PID /FWindows干掉它。或者更简单改.env里的PORT换个端口比如 3001。提示我习惯在代码里加一个端口占用的友好提示而不是让程序直接崩掉。用server.on(error, ...)监听错误如果是EADDRINUSE就打印“端口 X 已被占用请更换端口”体验好很多。4.2 req.body 为 undefined 的三种原因调 POST 接口时req.body是undefined这是新手最常见的困惑。原因通常有三个。第一忘了加express.json()中间件这是最常见的。第二中间件加在了路由注册之后顺序错了。第三请求头没带Content-Type: application/jsonExpress 不知道该怎么解析。用 Postman 或 curl 测试时记得在 Headers 里加上这个头。排查顺序先看中间件加没加再看顺序对不对最后看请求头。三步走基本能定位。4.3 跨域报错的完整解决浏览器控制台报Access to fetch at http://localhost:3000/api/todos from origin http://localhost:5173 has been blocked by CORS policy这就是跨域问题。解决方法是后端加cors中间件。但要注意CORS 是浏览器行为不是服务器行为。你用 Postman 或 curl 测试接口时不会遇到跨域因为它们是直接发请求没有浏览器的同源策略限制。所以如果你用 Postman 测通了但前端调不通八成就是跨域。生产环境配置 CORS 白名单app.use(cors({ origin: [https://yourdomain.com], methods: [GET, POST, PUT, DELETE], credentials: true }));credentials: true允许携带 Cookie如果你的接口需要登录态就加上不需要就去掉。4.4 常见问题速查表我把这个项目开发过程中遇到的高频问题整理成一张表方便你遇到时快速定位现象可能原因解决方法服务启动报 EADDRINUSE端口被占用换端口或杀掉占用进程req.body 为 undefined缺 json 中间件/顺序错/缺请求头检查三者跨域报错未配置 CORS加 cors 中间件404 找不到路由路径拼写错/方法不匹配核对路径和方法500 错误无信息错误中间件没注册注册在路由之后nodemon 不重启监听路径不对检查 nodemon 配置环境变量读不到.env 位置不对/没装 dotenv检查文件位置和依赖4.5 我的独家避坑心得分享几个文档里不会写、但实际开发中很有用的经验。第一用async/await时一定要包try/catch。Express 4.x 不会自动捕获异步函数里抛出的异常如果你在async控制器里throw一个错误不包try/catch的话请求会一直挂起直到超时而不是返回 500。这是个巨坑很多人排查半天才发现。Express 5.x 修复了这个问题但如果你用 4.x务必手动处理。第二ID 用自增数字还是 UUID这个项目我用自增数字简单直观。但真实项目建议用 UUID因为自增 ID 会暴露业务量别人看到 ID 是 10000就知道你有大约一万条数据而且分布式环境下自增 ID 会冲突。UUID 虽然长一点但更安全、更适合分布式。第三接口测试要覆盖边界情况。不要只测“正常输入”要测空字符串、超长字符串、特殊字符、不存在的 ID、错误的类型。我习惯用 Postman 建一个集合把这些边界用例都存进去每次改代码后跑一遍能提前发现很多问题。第四日志不要用console.log一把梭。开发时console.log够用但生产环境建议用winston或pino这类日志库支持分级info/warn/error、格式化、输出到文件。日志是排查线上问题的唯一线索值得投入。5. 部署上线与完整测试5.1 部署前的最后检查代码写完了本地跑通了接下来要部署到服务器上让别人能访问。部署前有几件事必须做。第一把NODE_ENV设成production这样错误信息不会暴露细节某些库也会切换到性能优化模式。第二检查.gitignore确保node_modules和.env没被提交。第三在package.json里加engines字段声明 Node.js 版本要求避免服务器上版本不兼容engines: { node: 20.0.0 }第四跑一遍完整的接口测试确保所有功能正常。第五准备好.env.example部署时照着它配置服务器的环境变量。5.2 用 PM2 守护进程Node.js 服务直接node app.js跑有个问题一旦终端关闭或者程序崩溃服务就停了。生产环境要用进程管理工具我推荐PM2。它能在程序崩溃时自动重启支持多进程负载均衡还能查看日志和监控状态。安装和启动npm install -g pm2 pm2 start src/app.js --name todo-api pm2 save pm2 startuppm2 save保存当前进程列表pm2 startup配置开机自启。这样服务器重启后服务会自动拉起来。查看状态用pm2 status看日志用pm2 logs todo-api重启用pm2 restart todo-api。这几个命令记住就够日常用了。5.3 完整的接口测试流程部署完成后做一轮完整的测试。我用 curl 演示几个关键用例。测试获取所有待办curl http://your-server-ip:3000/api/todos测试创建待办curl -X POST http://your-server-ip:3000/api/todos \ -H Content-Type: application/json \ -d {title: 学习 Express}测试参数校验传空标题应该返回 400curl -X POST http://your-server-ip:3000/api/todos \ -H Content-Type: application/json \ -d {title: }测试不存在的 ID应该返回 404curl http://your-server-ip:3000/api/todos/99999每个用例都要验证状态码和响应体结构是否符合预期。测试通过后这个 API 服务就算真正上线了。5.4 后续可以怎么扩展这个项目虽然小但扩展空间很大。想继续深入的话我建议按这个顺序加功能。第一步接入真实数据库把内存数组换成 MongoDB 或 PostgreSQL学习数据持久化。第二步加用户认证用 JWT 实现注册登录接口加上鉴权中间件。第三步加接口文档用 Swagger 自动生成 API 文档方便前端对接。第四步加单元测试用 Jest 或 Mocha 给控制器写测试用例保证代码质量。第五步容器化写 Dockerfile 把服务打包成镜像部署更标准化。每加一个功能你都会遇到新的“为什么”而搞清楚这些“为什么”的过程就是从“会写代码”到“懂系统”的进阶之路。我在实际带新人的过程中发现很多人卡在“教程看懂了但自己写不出来”这个阶段根本原因就是缺少一个从零到一的完整项目经验。这个待办 API 服务虽然简单但它覆盖了后端开发的完整链路环境搭建、依赖管理、分层设计、路由、中间件、参数校验、错误处理、日志、跨域、部署、测试。你亲手走一遍把这些环节串起来以后再遇到更复杂的项目心里就有底了。最后分享一个小技巧把这个项目的代码托管到代码仓库写一份清晰的 README说明接口定义和启动方式。这不仅是好习惯也是你以后面试时可以拿出手的作品。