Node.js / 系统课时
实现任务管理 API
实现任务管理 API
这一课把任务资源真正跑起来:使用 Express 5 完成路由、业务校验、内存仓储和统一错误响应,并用 curl 验证创建与失败路径。示例采用 ES Modules,默认监听 127.0.0.1:3000,完整代码复制到对应文件后即可启动。
学习目标
- 实现任务资源的创建、查询、更新和删除接口
- 把 HTTP、业务规则和数据访问分到不同模块
- 用真实请求验证 201、204、400 与 404 等关键结果
确认最小实现结构
示例使用 Node.js 20 或更高版本与 Express 5。项目只依赖 express,数据保存在进程内 Map 中;四个源文件的依赖方向固定为 app -> routes -> service -> repository,避免下层反向引用 HTTP 对象。
| 文件 | 对外职责 | 直接依赖 |
|---|---|---|
src/app.js |
中间件、路由挂载、404、错误处理、监听端口 | tasks.js |
src/routes/tasks.js |
把 HTTP 方法映射为任务用例 | taskService.js |
src/services/taskService.js |
输入校验、404 判断、业务操作 | taskRepository.js |
src/repositories/taskRepository.js |
内存数据读写 | Node.js crypto |

先准备完整 package.json,其中 type: module 使下面的 import 语法可直接运行。
{
"name": "task-api",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"start": "node src/app.js"
},
"dependencies": {
"express": "^5.1.0"
}
}实现核心链路
片段示例:下面四个模块共同组成完整项目,单个模块不应脱离其余文件单独运行。仓储层用 randomUUID() 生成 ID,并始终返回对象副本,避免服务层意外修改 Map 中的原对象。
src/repositories/taskRepository.js:
import { randomUUID } from 'node:crypto';
const tasks = new Map();
const copy = (task) => ({ ...task });
export function list() {
return [...tasks.values()].map(copy);
}
export function findById(id) {
const task = tasks.get(id);
return task ? copy(task) : null;
}
export function create({ title }) {
const now = new Date().toISOString();
const task = {
id: randomUUID(),
title,
completed: false,
createdAt: now,
updatedAt: now
};
tasks.set(task.id, task);
return copy(task);
}
export function update(id, patch) {
const current = tasks.get(id);
if (!current) return null;
const next = {
...current,
...patch,
updatedAt: new Date().toISOString()
};
tasks.set(id, next);
return copy(next);
}
export function remove(id) {
return tasks.delete(id);
}服务层只接受普通对象作为请求体;title 会先 trim(),空字符串和超过 120 个字符都返回 400。PATCH 至少要提供 title 或 completed 之一。
src/services/taskService.js:
import * as repo from '../repositories/taskRepository.js';
export class ApiError extends Error {
constructor(status, code, message) {
super(message);
this.status = status;
this.code = code;
}
}
function asObject(input) {
return input && typeof input === 'object' && !Array.isArray(input)
? input
: {};
}
function readTitle(value) {
if (typeof value !== 'string') {
throw new ApiError(400, 'VALIDATION_ERROR', 'title must be a string');
}
const title = value.trim();
if (title.length < 1 || title.length > 120) {
throw new ApiError(
400,
'VALIDATION_ERROR',
'title must contain 1-120 characters'
);
}
return title;
}
export function listTasks() {
return repo.list();
}
export function getTask(id) {
const task = repo.findById(id);
if (!task) throw new ApiError(404, 'NOT_FOUND', 'task not found');
return task;
}
export function createTask(input) {
const body = asObject(input);
return repo.create({ title: readTitle(body.title) });
}
export function updateTask(id, input) {
const body = asObject(input);
const patch = {};
if (Object.hasOwn(body, 'title')) {
patch.title = readTitle(body.title);
}
if (Object.hasOwn(body, 'completed')) {
if (typeof body.completed !== 'boolean') {
throw new ApiError(
400,
'VALIDATION_ERROR',
'completed must be a boolean'
);
}
patch.completed = body.completed;
}
if (Object.keys(patch).length === 0) {
throw new ApiError(
400,
'VALIDATION_ERROR',
'provide title or completed'
);
}
const task = repo.update(id, patch);
if (!task) throw new ApiError(404, 'NOT_FOUND', 'task not found');
return task;
}
export function deleteTask(id) {
if (!repo.remove(id)) {
throw new ApiError(404, 'NOT_FOUND', 'task not found');
}
}路由层不重复业务校验,只负责把 URL、请求体和状态码接起来。创建成功时同时设置 Location,删除成功时用 204 并结束响应。
src/routes/tasks.js:
import { Router } from 'express';
import {
createTask,
deleteTask,
getTask,
listTasks,
updateTask
} from '../services/taskService.js';
const router = Router();
router.get('/', (req, res) => {
res.json({ data: listTasks() });
});
router.get('/:id', (req, res) => {
res.json({ data: getTask(req.params.id) });
});
router.post('/', (req, res) => {
const task = createTask(req.body);
res
.status(201)
.location(`/tasks/${task.id}`)
.json({ data: task });
});
router.patch('/:id', (req, res) => {
res.json({ data: updateTask(req.params.id, req.body) });
});
router.delete('/:id', (req, res) => {
deleteTask(req.params.id);
res.status(204).end();
});
export { router as taskRouter };入口文件把 JSON 解析、业务路由、404 和错误中间件按顺序挂载。Express 的错误中间件必须保留 4 个参数;非法 JSON 单独转成稳定的 INVALID_JSON,500 错误则不向客户端暴露内部异常信息。
src/app.js:
import express from 'express';
import { taskRouter } from './routes/tasks.js';
const app = express();
app.disable('x-powered-by');
app.use(express.json({ limit: '16kb' }));
app.use('/tasks', taskRouter);
app.use((req, res) => {
res.status(404).json({
error: {
code: 'ROUTE_NOT_FOUND',
message: 'route not found'
}
});
});
app.use((err, req, res, next) => {
if (err?.type === 'entity.parse.failed') {
return res.status(400).json({
error: {
code: 'INVALID_JSON',
message: 'request body is not valid JSON'
}
});
}
const status = Number.isInteger(err?.status) ? err.status : 500;
const code = typeof err?.code === 'string' ? err.code : 'INTERNAL_ERROR';
const message =
status >= 500 ? 'internal server error' : err.message;
return res.status(status).json({
error: { code, message }
});
});
const port = Number(process.env.PORT ?? 3000);
app.listen(port, '127.0.0.1', () => {
console.log(`Task API listening on http://127.0.0.1:${port}`);
});运行并验证成功路径
在项目根目录执行下面命令。--silent 用来抑制 npm 自身的常规日志,使输出只保留应用启动信息。
npm install --silent
npm start --silent预期输出:
Task API listening on http://127.0.0.1:3000保持服务器运行,在另一个终端创建任务。<ID> 和 <TIME> 是动态值,实际结果每次都会不同。
curl -s -X POST http://127.0.0.1:3000/tasks -H "Content-Type: application/json" -d '{"title":"write API documentation"}'预期输出:
{"data":{"id":"<ID>","title":"write API documentation","completed":false,"createdAt":"<TIME>","updatedAt":"<TIME>"}}随后访问 GET /tasks 应得到数组形式的 data,其中包含刚创建的任务;如果重启进程后数组变空,这是当前内存仓储方案的预期行为,不是接口故障。
验证失败路径
先用空白标题验证服务层校验。下面命令同时打印响应体和 HTTP 状态码,便于确认不是“返回了错误 JSON,但状态仍是 200”。
curl -s -o - -w "\nHTTP %{http_code}\n" -X POST http://127.0.0.1:3000/tasks -H "Content-Type: application/json" -d '{"title":" "}'预期输出:
{"error":{"code":"VALIDATION_ERROR","message":"title must contain 1-120 characters"}}
HTTP 400还应逐项检查三个边界:请求不存在的任务 ID 返回 404 NOT_FOUND;发送破损 JSON 返回 400 INVALID_JSON;成功删除任务返回 204 且响应体为空。若错误响应格式因路由不同而变化,应先统一错误中间件,再继续增加新功能。