《小项目实战 1：用 AI 从零搭一个 API 服务》

开篇

从今天开始，我们用 4 篇文章完成一个小项目：任务清单 API 服务。

这不是为了让 AI 一次性生成一个“看起来很完整”的项目，而是观察一项真实开发任务应该怎样分阶段完成。

本篇只完成第一步：

确定项目范围
  ↓
生成基础结构
  ↓
启动 API 服务
  ↓
验证第一条请求

技术栈选择 Node.js + Express，数据暂时保存在内存中。这样可以把注意力放在 AI 协作流程上，不提前引入数据库和登录认证的复杂度。

一、先定义项目的最小范围

项目名称：task-api

第一版只支持下面 4 个接口：

任务对象只保留 4 个字段：

<span>{</span>
  <span>"id"</span><span>:</span> <span>1</span><span>,</span>
  <span>"title"</span><span>:</span> <span>"完成 API 设计"</span><span>,</span>
  <span>"completed"</span><span>:</span> <span><span>false</span></span><span>,</span>
  <span>"createdAt"</span><span>:</span> <span>"2026-08-28T08:00:00.000Z"</span>
<span>}</span>

暂时不做：

• 用户登录和权限。
• 数据库持久化。
• 分页、搜索和标签。
• Docker、监控和自动部署。

边界越清楚，AI 越不容易擅自扩展项目范围。

二、先让 AI 给出实现计划

我不会一开始就让 AI 生成所有代码，而是先让它确认实现方案：

你是一名有经验的 Node.js 开发者，请为我设计一个最小可运行的任务清单 API 服务。

项目约束：
- 使用 Node.js 20 和 Express。
- 使用 JavaScript，不使用 TypeScript。
- 数据暂时保存在内存中，不接数据库。
- 只实现 GET、POST、PATCH、DELETE 四个接口。
- 不新增登录、权限和分页功能。

请先不要写代码，只输出：
1. 推荐的目录结构。
2. 每个文件的职责。
3. 四个接口的请求和响应约定。
4. 可能出现的边界问题。
5. 启动和验证步骤。

不确定的内容标记为“待确认”，不要擅自扩展需求。

这一步的目的，是先看 AI 是否理解了项目，而不是马上接收一大堆代码。

三、再让 AI 按文件生成代码

确认计划没有偏离后，再继续提问：

请根据已经确认的方案，按文件逐个生成代码。

要求：
1. 先输出 package.json，再输出 src 目录中的文件。
2. 每个代码块前标注完整文件路径。
3. app.js 需要导出 Express 实例，便于后续编写测试。
4. 路由、数据存储和错误处理中间件分开。
5. title 不能为空，找不到任务时返回 404。
6. 不要增加没有确认的依赖和功能。
7. 最后给出安装、启动和 curl 验证命令。

这里有一个很实用的要求：

让 AI 按文件输出，而不是把整个项目混在一个代码块里。

按文件生成更容易检查路径、依赖关系和修改范围，也方便发现 AI 是否漏掉了启动文件。

四、我会保留的基础目录

第一版目录不需要复杂：

task-api/
├── package.json
├── src/
│   ├── app.js
│   ├── server.js
│   ├── routes/
│   │   └── tasks.js
│   ├── store/
│   │   └── task-store.js
│   └── middleware/
│       └── error-handler.js
└── README.md

目录职责保持简单：

• app.js：创建 Express 应用和注册中间件。
• server.js：读取端口并启动服务。
• tasks.js：处理任务接口的路由。
• task-store.js：暂时保存和操作任务数据。
• error-handler.js：统一处理未捕获异常。

如果 AI 为这个小项目额外生成十几个目录和抽象层，我会先要求它说明必要性，而不是默认接受。

五、启动并验证第一条请求

安装依赖并启动服务：

npm install
npm start

创建一个任务：

curl -X POST http://localhost:3000/api/tasks \
  -H <span>"Content-Type: application/json"</span> \
  -d <span>'{"title":"完成 API 设计"}'</span>

查询任务：

curl http://localhost:3000/api/tasks

第一轮只验证三件事：

[ ] 服务能够正常启动。
[ ] POST 能够创建任务。
[ ] GET 能够返回刚创建的任务。

不要因为 AI 给出了完整目录，就跳过实际启动。能否运行，才是第一道验收门槛。

六、第一版代码重点检查什么

代码生成后，我不会马上继续增加功能，而是先检查以下风险：

• 请求体是否正确解析为 JSON。
• title 为空时是否拒绝请求。
• 不存在的任务是否返回 404。
• PATCH 是否只修改允许的字段。
• 删除任务后，列表是否真的不再包含它。
• 服务重启后数据丢失是否符合当前约定。

其中最后一点很容易被忽略。内存存储意味着服务重启后数据会消失，这不是代码错误，而是本篇明确选择的项目限制。

七、不要把“能启动”当成“完成了”

AI 从零搭项目时，最容易出现三个错觉：

1. 文件很多，所以项目很完整。
2. 服务能启动，所以功能没有问题。
3. 请求能返回，所以代码可以直接上线。

实际上，当前只完成了一个可运行的骨架。

后续还需要补齐：

接口约定
  ↓
异常处理
  ↓
单元测试和接口测试
  ↓
代码审查与交付检查

这也是本次小项目实战的安排：每一篇只解决一层问题，避免让 AI 一次性生成难以验证的大项目。

总结

今天完成了任务清单 API 的第一版骨架，最重要的不是生成了多少代码，而是建立了正确的协作顺序：

先定范围
  ↓
先看方案
  ↓
按文件生成
  ↓
启动验证
  ↓
记录待改问题

• 小项目也要先定义边界。
• 让 AI 先给方案，再生成代码。
• 代码按文件输出，更容易审查和维护。
• 服务能启动只是开始，不能代替功能验证。

下一篇文章，我们将继续完善这个项目：

《小项目实战 2：让 AI 帮你补齐接口设计和异常处理》

✍坚持原创，求关注，点赞，收藏