Kodokon kodokon.com

构建一个 REST API

用正确的 HTTP 方法、正确的状态码以及对请求体的校验，设计一个整洁的 REST API。

9 分钟 · 3 题

在 Kodokon 中打开本课

一个 REST API 暴露出一批资源（用户、任务、订单），并用 HTTP 方法来操作它们：GET 读取、POST 创建、PUT 或 PATCH 更新、DELETE 删除。专业的约定是：URL 里用复数名词，绝不用动词。你写 POST /tasks，而不是 /createTask。我们来搭建一个小小的任务 API，目前先放在内存里。

JAVASCRIPT
import express from "express";

const app = express();
app.use(express.json());

const tasks = [
  { id: 1, title: "Review the module", done: false }
];

app.get("/tasks", (req, res) => {
  res.json(tasks);
});

app.listen(3000);

app.use(express.json()) 这一行至关重要：没有它，对任何 JSON 请求来说 req.body 都是 undefined。创建资源时，务必校验输入、以 201 作出响应，并返回创建好的资源：这样客户端就能取回服务器生成的 id。

JAVASCRIPT
app.post("/tasks", (req, res) => {
  const { title } = req.body;
  if (!title) {
    return res.status(400).json({
      error: "The title field is required"
    });
  }
  const task = {
    id: tasks.length + 1,
    title,
    done: false
  };
  tasks.push(task);
  res.status(201).json(task);
});

记住这些你每天都会用到的状态码：200 读取或更新成功、201 资源已创建、204 成功但无内容（删除）、400 请求无效、404 资源未找到、500 服务器错误。规律是：4xx 表示客户端犯了错，5xx 表示出问题的是你的代码。

JAVASCRIPT
app.delete("/tasks/:id", (req, res) => {
  const id = Number(req.params.id);
  const index = tasks.findIndex((t) => t.id === id);
  if (index === -1) {
    return res.status(404).json({
      error: "Task not found"
    });
  }
  tasks.splice(index, 1);
  res.status(204).end();
});

知识检测

确认你已牢记本课的重点内容。

  1. 成功创建一个资源之后，你应该返回哪个状态码？
    • 200
    • 201
    • 204
    • 301
  2. 缺了哪一行，JSON 请求的 req.body 会一直是 undefined？
    • app.use(express.json())
    • app.use(express.static(...))
    • app.listen(3000)
  3. 客户端发来一个 POST，却缺少必填的 title 字段。这个 API 正确的反应是什么？
    • 用空标题创建这个资源
    • 返回一个带错误信息的 400 状态码
    • 返回一个 500 状态码
    • 忽略这个请求，不作任何响应