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 不允许被客户端修改。

下面是一个合法资源实例,可直接作为接口文档和测试夹具的基准:

json
{
  "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 状态码

任务管理 API 的分层、依赖方向与数据流

项目配置也要在编码前固定。下面的 package.json 以 ES Modules 和 Express 5 为基线;这是完整配置文件,后续实现中的 import 语法与 npm start 都依赖它。

json
{
  "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 自带模块读取并核对三个关键字段。该命令不依赖第三方包,因此适合在真正安装依赖前做一次静态检查。

bash
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)"

预期输出:

text
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,就应在继续扩展前先修正分层。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

规划综合项目

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通