4.4 RESTful API 开发

4.4 RESTful API 开发

本节摘要：用 Express 的 HTTP 方法快捷方式写 RESTful 接口。本节以"用户管理"为例实现 CRUD、处理参数与请求体、返回 JSON，并给出一套完整接口示例。

学习目标

阅读完本节，你应当能够：

1. 用方法快捷方式写接口
2. 处理路径与查询参数
3. 解析 JSON 请求体
4. 返回 JSON 响应
5. 完成完整 CRUD

一、问题与直觉

"Express 接口怎么写？"——app.get/app.post 等方法名直接对应 HTTP 方法，一个方法一个接口。相比注解与文件配置，Express 的接口是最"直给"的：方法名 + 路径 + 处理函数。

二、核心原理

Express 接口的骨架：

2.1 CRUD 接口

const express = require('express')
const app = express()
app.use(express.json())   // 解析 JSON 请求体

app.get('/users', (req, res) => {
  res.json([{ id: 1, name: '张三' }])
})

app.get('/users/:id', (req, res) => {
  res.json({ id: req.params.id, name: '张三' })
})

app.post('/users', (req, res) => {
  res.status(201).json(req.body)   // 返回创建的数据
})

app.delete('/users/:id', (req, res) => {
  res.json({ deleted: req.params.id })
})

app.listen(3000)
​

三、工程实践要点

3.1 参数速查

💡 关键直觉：方法名就是 HTTP 动词——get/post/put/delete 直接对应 RESTful 方法。看懂一个接口，就懂了 Express 的接口体系。

3.2 状态码设置

创建成功 → 201
删除成功 → 200/204
校验失败 → 400
未找到 → 404
​

⚠️ 常见坑：忘记 express.json()。不解析 JSON，req.body 就是 undefined——接口拿不到数据。启用解析中间件是 POST/PUT 的前提。

要点串联

• 要点一：方法名对应 HTTP 动词
• 要点二：params/query/body 三类参数
• 要点三：res.json 返回 JSON
• 要点四：状态码按语义设置
• 要点五：express.json 必装
• 要点六：接口最"直给"的框架

接口会写了，下一节接数据——数据访问。

常见疑问

Q1：Express 的接口为什么说"最直给"？

因为接口定义就是"方法名 + 路径 + 处理函数"三件套，没有任何注解或额外配置。app.get('/users', 处理函数) 就是一个 GET 接口，app.post('/users', 处理函数) 就是一个新增接口。你看到代码的一瞬间就知道它在定义什么接口。这种直给风格的好处是上手快、心智负担小，也是 Express 轻量哲学的体现。

Q2：路径参数和查询参数在 Express 里怎么读？

路径参数写在路径里用冒号声明（如 /users/:id），在处理函数里用 req.params.id 读取；查询参数在问号后面，用 req.query.page 读取；请求体（JSON 数据）需要先挂 express.json() 中间件，然后用 req.body 读取。三类参数的读法各不相同，写接口时按需选用，这一点和第 2 章的注解参数、第 3 章的 request 参数是同一个道理，只是语法不同。

Q3：为什么 POST 接口拿不到 req.body？

最常见的原因就是没挂 express.json() 中间件。请求体解析是需要显式开启的：app.use(express.json()) 要写在读取 body 的路由之前。没有它，req.body 就是 undefined。排查"接口拿不到数据"时，第一件事就是检查这个中间件挂了没有、挂的位置对不对。

Q4：接口返回的 JSON 怎么设置状态码？

res.json(数据) 默认返回 200；要指定状态码用 res.status(码).json(数据)，比如创建成功返回 201、未登录返回 401、没找到返回 404、参数错误返回 400。状态码和响应体配合，前端才能正确判断结果。原则和第 2、3 章一致：成功返 2xx，客户端错返 4xx，服务端错返 5xx。

工程实践要点

动手建议：把本节用户 CRUD 完整实现一遍，重点练习三类参数：路径参数（查询单个用户）、查询参数（分页筛选）、请求体（新增用户）。用接口测试工具逐个测试每个接口，观察请求方法、路径、状态码、响应体是否都符合 RESTful 约定。特别测试：POST 请求不带 express.json 时会发生什么、带了之后又能拿到什么。接口全部跑通后，这个"用 Express 写接口"的套路你就熟透了。

实战演练：写完并测透一套 CRUD

本节练习的目标，是把用户管理接口五件套完整实现并逐一测试。步骤如下：

第一步，写查列表接口。用 GET 方法返回一个用户数组（先用假数据）。访问测试，确认返回 JSON 数组。验收标准：状态码 200，响应是数组。

第二步，写查单个接口。用 GET 加路径参数，路径形如 /users/1，返回该用户。访问不同 id 观察结果。验收标准：路径参数正确读取，响应是单个用户对象。

第三步，写新增接口。先确保 JSON 解析中间件已挂载，再用 POST 接口接收请求体并返回 201 状态码。验收标准：发送 JSON 后能回显数据，状态码是 201。

第四步，写删除接口。用 DELETE 加路径参数删除用户，返回删除结果。验收标准：调用后返回正确响应。

第五步，写修改接口。用 PUT 加路径参数接收请求体更新用户。验收标准：修改后能读到新数据。

第六步，做链路测试。按"新增→查列表→查单个→修改→删除→再查"的顺序走一遍，每一步都确认状态码和数据正确。验收标准：整条链路无一处返回意外结果。

做完这套练习，你会发现 Express 接口虽然写法"直给"，但状态码、参数、数据格式的规范性和前面两个框架完全一致。这正是 RESTful 约定的价值——框架可以不同，接口规范相通。

一句话记忆

Express 写接口就是"方法名加路径加处理函数"。把五件套写完、把链路测通、把状态码校准，你就掌握了 Express 接口开发的全部日常。写法简单，规范不能省。