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

任务 API 从请求到仓储再返回响应的执行链路

先准备完整 package.json,其中 type: module 使下面的 import 语法可直接运行。

json
{
  "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:

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:

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:

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:

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 自身的常规日志,使输出只保留应用启动信息。

bash
npm install --silent
npm start --silent

预期输出:

text
Task API listening on http://127.0.0.1:3000

保持服务器运行,在另一个终端创建任务。<ID> 和 <TIME> 是动态值,实际结果每次都会不同。

bash
curl -s -X POST http://127.0.0.1:3000/tasks   -H "Content-Type: application/json"   -d '{"title":"write API documentation"}'

预期输出:

json
{"data":{"id":"<ID>","title":"write API documentation","completed":false,"createdAt":"<TIME>","updatedAt":"<TIME>"}}

随后访问 GET /tasks 应得到数组形式的 data,其中包含刚创建的任务;如果重启进程后数组变空,这是当前内存仓储方案的预期行为,不是接口故障。

验证失败路径

先用空白标题验证服务层校验。下面命令同时打印响应体和 HTTP 状态码,便于确认不是“返回了错误 JSON,但状态仍是 200”。

bash
curl -s -o - -w "\nHTTP %{http_code}\n"   -X POST http://127.0.0.1:3000/tasks   -H "Content-Type: application/json"   -d '{"title":"   "}'

预期输出:

text
{"error":{"code":"VALIDATION_ERROR","message":"title must contain 1-120 characters"}}
HTTP 400

还应逐项检查三个边界:请求不存在的任务 ID 返回 404 NOT_FOUND;发送破损 JSON 返回 400 INVALID_JSON;成功删除任务返回 204 且响应体为空。若错误响应格式因路由不同而变化,应先统一错误中间件,再继续增加新功能。

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

目录与阅读设置

阅读设置

17

记录一个想法

实现任务管理 API

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

登录哪都通