Node.js / 系统课时
规划综合项目
规划综合项目
这一课把“做一个任务管理 API”收敛成可交付范围:先固定资源字段与 HTTP 契约,再确定目录职责、依赖方向和开发顺序。完成后,你会得到一份可以直接照着实现和验收的项目蓝图,而不是边写代码边临时决定接口。
学习目标
- 划定任务管理 API 的最小功能范围,并为每个端点确定状态码
- 设计可验证的数据模型、目录职责和层间依赖
- 按风险由低到高安排开发顺序,并为每一步写出验收条件
固定功能边界
第一版只处理 Task 一种资源,不加入用户、鉴权、分页和数据库。数据先保存在进程内 Map 中,这样可以把注意力放在 HTTP、校验和分层;进程重启后数据丢失属于已知限制,不应伪装成持久化能力。
| 方法与路径 | 行为 | 成功状态码 | 关键输入 |
|---|---|---|---|
POST /tasks |
创建任务 | 201 | title |
GET /tasks |
列出全部任务 | 200 | 无 |
GET /tasks/:id |
查询单个任务 | 200 | 路径参数 id |
PATCH /tasks/:id |
修改标题或完成状态 | 200 | title、completed 至少一项 |
DELETE /tasks/:id |
删除任务 | 204 | 路径参数 id |
失败规则也要提前写死:请求体不合法返回 400,任务不存在返回 404,JSON 语法错误返回 400。这样实现路由时不需要临时争论“该返回什么”,测试也能直接按契约断言。
定义数据模型与接口契约
任务对象固定为 5 个字段:id 使用 UUID 字符串;title 去掉首尾空白后长度为 1~120;completed 只接受布尔值;createdAt 与 updatedAt 使用 ISO 8601 字符串。更新任务时,updatedAt 必须刷新,createdAt 不允许被客户端修改。
下面是一个合法资源实例,可直接作为接口文档和测试夹具的基准:
{
"id": "7a34b3bc-6538-4d3b-8bb2-03772cc93b9f",
"title": "write API documentation",
"completed": false,
"createdAt": "2026-10-03T02:00:00.000Z",
"updatedAt": "2026-10-03T02:00:00.000Z"
}成功响应统一包在 data 字段中,例如创建任务返回 {"data":{...}};错误统一使用 {"error":{"code":"...","message":"..."}}。DELETE 成功时按 HTTP 语义返回 204,不再附带 JSON 响应体。
划分目录职责
目录按“HTTP 适配、业务规则、数据访问”三层拆开。路由只处理 HTTP 输入输出;服务层负责标题长度、更新字段等业务规则;仓储层只负责读写任务。这样以后把 Map 换成 SQLite 时,不需要改路由契约。
| 路径 | 职责 | 不应该做的事 |
|---|---|---|
src/app.js |
创建 Express 应用、挂载中间件与统一错误处理 | 编写任务业务规则 |
src/routes/tasks.js |
声明 /tasks 路由并转换 HTTP 响应 |
直接操作 Map |
src/services/taskService.js |
校验输入、组织任务用例 | 读取 req、写 res |
src/repositories/taskRepository.js |
创建、查询、更新、删除任务 | 决定 HTTP 状态码 |

项目配置也要在编码前固定。下面的 package.json 以 ES Modules 和 Express 5 为基线;这是完整配置文件,后续实现中的 import 语法与 npm start 都依赖它。
{
"name": "task-api",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"start": "node src/app.js"
},
"dependencies": {
"express": "^5.1.0"
}
}把配置保存为项目根目录的 package.json 后,可用 Node.js 自带模块读取并核对三个关键字段。该命令不依赖第三方包,因此适合在真正安装依赖前做一次静态检查。
node --input-type=commonjs -e "const p=JSON.parse(require('node:fs').readFileSync('package.json','utf8')); console.log(p.type, p.scripts.start, p.dependencies.express)"预期输出:
module node src/app.js ^5.1.0如果输出中的模块类型、启动入口或 Express 主版本不一致,应先修正配置;同时检查项目中不要让 routes 直接导入仓储层。
安排开发顺序与验收点
实现顺序按“先打通最短链路,再逐层增加规则”执行。第一步让 app.js 能启动并监听端口;第二步完成仓储层的增删改查;第三步在服务层加入校验;第四步接上 5 个路由;第五步补 404、非法 JSON 和统一错误响应;最后再用 HTTP 请求逐项验收。
每一步都设置可判定的完成条件:仓储层创建后能立即按 id 查到同一任务;服务层拒绝空标题和长度超过 120 的标题;POST /tasks 返回 201 且包含 Location;不存在的 id 返回 404;删除成功返回 204 且响应体为空。
开发时如果发现“必须先改三层才能加一个字段”,说明职责边界出了问题。以新增 priority 为检查例:仓储层只存值,服务层校验允许值,路由层只透传结果;如果仓储层开始返回 400 或服务层开始读取 req.params,就应在继续扩展前先修正分层。