====== req 和 res(请求与响应) ======
**''req''** 是 **request**(请求)的缩写,**''res''** 是 **response**(响应)的缩写。它们成对出现,代表一次 HTTP 交互的两端:
* **''req''** = 客户端递进来的那张单子 —— **只读的输入**;
* **''res''** = 服务端要写回去的回执 —— **只能写一次的输出**。
> **一句话**:''req'' 负责「读进来」,''res'' 负责「写回去」;它们的名字不是随便起的,而是**方向**的标记。
这个命名在 Node.js / Express 生态里几乎人尽皆知,因为每个处理器都长这样:
app.get("/users/:id", (req, res) => {
const id = req.params.id; // 从 req 读
res.json({ id }); // 往 res 写
});
===== 一、为什么不叫 request / response =====
纯粹是**约定俗成的短写**:这两个对象在几乎每个函数签名里都要出现,写全名太长,社区统一缩成 ''req'' / ''res''(Java 里则习惯写 ''request'' / ''response'',Go 里干脆叫 ''w'' 和 ''r'')。
| 写法 | 出处 | 说明 |
| ''req'' / ''res'' | Express、Next.js、大部分 Node 框架 | 最主流的写法 |
| ''request'' / ''response'' | Java Servlet、ASP.NET | 写全名,because 类型名就这么长 |
| ''ctx'' | Koa、Gin | 把两者合成一个上下文对象 |
| ''w'' / ''r'' | Go 标准库 | ''w http.ResponseWriter, r *http.Request'' |
**名字不同,角色是同一个**:一个是「进来的请求」,一个是「出去的回答」。
===== 二、req:只读的输入 =====
''req'' 是**客户端说了什么**的完整快照。在 Node 里它的底层类型是 ''http.IncomingMessage'',Express 在上面加了一层糖。
==== 2.1 请求行 ====
| 属性 | 含义 |
| ''req.method'' | ''GET'' / ''POST'' / ''PUT'' … |
| ''req.originalUrl'' | 原始完整路径(含查询串),**改写路由后仍然保留** |
| ''req.path'' | 路径部分,不含查询串 |
| ''req.params'' | **路径参数**,如 ''/users/:id'' 里的 ''id'' |
| ''req.query'' | **查询串**解析结果,如 ''?page=2'' |
==== 2.2 头部与来源 ====
| 属性 | 含义 |
| ''req.headers'' | 全部请求头(键名已小写) |
| ''req.get("user-agent")'' | 取单个头的便捷方法(大小写不敏感) |
| ''req.cookies'' | 需要 cookie 解析中间件 |
| ''req.ip'' | 客户端 IP,**注意反向代理下要配 ''trust proxy''** |
| ''req.protocol'' | ''http'' / ''https'',同样受代理影响 |
==== 2.3 请求体 ====
''req.body'' 是**最容易被误解**的一项:**它不是天生就有的**。
* 原生 Node 里 ''req'' 是**可读流**,必须自己 ''req.on("data")'' 拼接 Buffer;
* Express 4/5 中要显式挂上解析中间件(''express.json()'' / ''express.urlencoded()''),否则 ''req.body'' 是 ''undefined'';
* 这也是新手报「''Cannot read properties of undefined (reading 'xxx')''」的第一大来源。
app.use(express.json()); // 少了这一行,req.body 就是 undefined
app.post("/orders", (req, res) => {
const { amount } = req.body ?? {}; // 保守写法
res.status(201).json({ amount });
});
==== 2.4 使用纪律 ====
* **默认当作只读**。往 ''req'' 上挂自定义属性(如 ''req.auth''、''req.user'')是常见做法,但要**选不会与框架字段撞名的名字**。
* 不要指望 ''req'' 上有业务状态;它是「这一层的事」的载体。
===== 三、res:只能写一次的输出 =====
''res'' 是**你要对客户端说的话**。底层类型是 ''http.ServerResponse'',它本身是一个**可写流**,并且有一条硬性约束:
> **响应头一旦发出(第一次 ''write'' / ''send'' / ''json'' / ''end''),就不能再改;body 写完就不能再写第二次。**
==== 3.1 常用方法 ====
| 方法 | 作用 |
| ''res.status(201)'' | 设置状态码(可链式调用) |
| ''res.set("X-Foo", "bar")'' / ''res.header()'' | 设置响应头 |
| ''res.cookie(name, value, opts)'' | 写 Cookie |
| ''res.json(obj)'' | 序列化并发送 JSON,自动设 ''Content-Type'' |
| ''res.send(body)'' | 发送字符串 / Buffer / 对象(会推断类型) |
| ''res.end()'' | 结束响应,不带 body |
| ''res.redirect(302, "/login")'' | 重定向,见 [[代码术语:404_303_这些是什么|状态码语义]] |
| ''res.sendFile(path)'' / ''res.render(view)'' | 发文件 / 渲染模板 |
==== 3.2 两条最容易踩的规则 ====
* **必须 ''return''**:''res.json()'' 之后函数不会自动结束,忘记 ''return'' 就会继续执行后面的代码,甚至二次发送。
* **不能发两次**:第二次发送会抛 ''ERR_HTTP_HEADERS_SENT'',或者客户端直接卡住/报错。典型场景是「''try'' 里 send 了,''catch'' 里又 send 一次」。
app.get("/u/:id", async (req, res) => {
try {
const u = await repo.find(req.params.id);
if (!u) return res.status(404).json({ error: "not_found" }); // ① 一定 return
return res.json(u);
} catch (e) {
if (res.headersSent) return next(e); // ② 已经发过了,交给错误中间件
return res.status(500).json({ error: "internal" });
}
});
===== 四、一张对照表 =====
| 维度 | ''req''(请求) | ''res''(响应) |
| 数据方向 | 浏览器 → 服务器 | 服务器 → 浏览器 |
| 角色 | **输入**,主要在读 | **输出**,主要在写 |
| 底层类型(Node) | ''http.IncomingMessage'' | ''http.ServerResponse'' |
| 能不能重复操作 | 可以反复读属性 | **只能写一次**,写完即结束 |
| 关键内容 | method / 路径 / 头 / body | status / 头 / body |
| 谁构造 | 由框架根据 HTTP 报文创建 | 由框架创建,你往里填 |
| 常见错误 | 读 ''req.body'' 得到 ''undefined'' | 二次发送 → ''ERR_HTTP_HEADERS_SENT'' |
===== 五、三处输入别搞混 =====
面试和实际开发里最高频的混淆点:
| 来源 | 位置 | 取值 | 例 |
| ''req.params'' | **路径**里 | 路由占位符 | ''GET /users/42'' → ''{ id: "42" }'' |
| ''req.query'' | **''?'' 后面** | 查询串,值恒为字符串或数组 | ''?page=2&tag=a'' → ''{ page: "2", tag: "a" }'' |
| ''req.body'' | **报文主体** | 要解析,可能是 JSON / 表单 / 文件 | ''POST'' 体 ''{"name":"张三"}'' |
推论:''req.query'' 里拿到的 ''"2"'' 是**字符串**,直接做算术要显式 ''Number()'';''req.params.id'' 也是字符串,别拿它去和数字做 ''==='' 比较。
===== 六、其他语言 / 框架里的同一对角色 =====
| 框架 | 写法 | 备注 |
| Express | ''(req, res)'' | 本文主要依据 |
| Next.js API 路由 | ''(req: NextApiRequest, res: NextApiResponse)'' | App Router 起改为 ''Request'' / ''Response'' 标准对象 |
| NestJS | ''@Req() req'' / ''@Res() res'' | **用了 ''@Res()'' 就退出框架托管,必须自己 ''res.send()''** |
| Koa | ''ctx'' | ''ctx.req''/''ctx.res'' 是原生对象,日常用 ''ctx.request''/''ctx.response'' 与 ''ctx.body'' |
| Go | ''(w http.ResponseWriter, r *http.Request)'' | 头要在 ''WriteHeader'' 之前设 |
| Java Servlet | ''HttpServletRequest'' / ''HttpServletResponse'' | 语义完全一致 |
| Python Flask | 全局 ''request'' + **函数返回值** | 没有显式 ''res'',返回即响应 |
可以看到一个共同规律:**请求对象由框架交给你读,响应对象由你填完交回框架发出去**。这是几乎所有 Web 框架的同构设计。
===== 七、常见坑 =====
| 坑 | 说明 |
| ''res.json()'' 后忘记 ''return'' | 后续代码继续执行,可能二次发送 |
| ''try'' 和 ''catch'' 各发一次响应 | 抛 ''ERR_HTTP_HEADERS_SENT'';先判断 ''res.headersSent'' |
| 没装解析中间件就读 ''req.body'' | 得到 ''undefined'',再解构就崩 |
| 用 ''req.query.id'' 当路径参数 | 语义不对,还会被 ''?id='' 伪造 |
| 相信 ''req.ip'' 就是真实客户端 IP | 有反向代理时必须配置 ''trust proxy'',否则拿到的是代理 IP |
| 把 ''res'' 当 Promise | ''res'' 没有 ''then'',''await res.json()'' 不会等到响应发完 |
| ''async'' 处理器异常没捕获 | Express 4 不会自动 ''catch'',请求会一直挂到超时 |
| 在 ''req'' 上挂与框架字段同名的属性 | 例如覆盖 ''req.body'',后续中间件行为异常 |
| 手动改 ''req.headers'' 当权限判断 | 头部由客户端控制,**绝不可信**,见 [[代码术语:authorization|Authorization]] |
===== 八、30 秒自测 =====
* ''req'' 和 ''res'' 分别是哪个词的缩写?→ **request / response**
* 哪个是只读输入,哪个是只能写一次的输出?→ **''req'' 读,''res'' 写一次**
* ''req.body'' 一定存在吗?→ **不一定,要装 body 解析中间件**
* ''/users/:id?tab=post'' 里的 ''id'' 和 ''tab'' 分别在哪?→ **''req.params.id'' / ''req.query.tab''**
* 响应已经发出去了,还能改状态码吗?→ **不能**
* 为什么 ''res.json()'' 前面通常要写 ''return''?→ **防止继续执行导致二次发送**
===== 九、一句话记住 =====
> **''req'' = request,''res'' = response:前者是客户端送进来的只读请求对象,后者是你要写回客户端的响应对象;读 ''req''、写 ''res'',一个进一个出,方向相反且 ''res'' 只能写一次。**
```mdk height=560 color=#4f46e5
# req 和 res
## 是什么
- req = request 请求
- res = response 响应
- 一次 HTTP 交互的两端
- req:只读的输入
- res:只能写一次的输出
## 底层类型
- req → http.IncomingMessage
- res → http.ServerResponse
- Express 在其上加了语法糖
## req 里有什么
### 请求行与路径
- req.method
- req.path / req.originalUrl
- req.params:路径参数
- req.query:查询串
### 头部
- req.headers / req.get()
- req.cookies
- req.ip / req.protocol
- 反向代理下要配 trust proxy
### 主体
- req.body 依赖解析中间件
- 原生是流:req.on('data')
- 没中间件就是 undefined
### 纪律
- 默认只读
- 自定义挂载避开框架字段
## res 里有什么
### 状态与头
- res.status()
- res.set() / res.header()
- res.cookie()
- 头发出后不可再改
### 输出
- res.send() / res.json()
- res.end()
- res.redirect()
- res.sendFile() / res.render()
### 硬约束
- 是流,写完即结束
- 只能发送一次
- 二次发送抛 ERR_HTTP_HEADERS_SENT
- 记得 return
## 三处输入别混
- req.params:路径占位符
- req.query:始终是字符串
- req.body:需解析
## 各框架的同一对
- Express:(req, res)
- Next.js:NextApiRequest / NextApiResponse
- NestJS:@Req() / @Res(),自己响应
- Koa:ctx.request / ctx.response / ctx.body
- Go:w ResponseWriter, r *Request
- Java:ServletRequest / ServletResponse
- Flask:全局 request + 返回值
## 常见坑
- res.json 后忘 return
- try 和 catch 各发一次响应
- 没中间件就读 req.body
- 拿 query 当路径参数
- 把 res 当 Promise await
- async 异常没捕获,请求挂起
- 相信客户端传来的头部
## 一句话
- req 读进来、res 写回去
- 方向相反,res 只能写一次
```
===== 参考 =====
* Express 文档 —— [[https://expressjs.com/en/4x/api.html#req|Request(''req'')]] / [[https://expressjs.com/en/4x/api.html#res|Response(''res'')]]
* Node.js 文档 —— [[https://nodejs.org/api/http.html#class-httpincomingmessage|http.IncomingMessage]] / [[https://nodejs.org/api/http.html#class-httpserverresponse|http.ServerResponse]]
* MDN —— [[https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Messages|HTTP 消息(请求与响应的结构)]]
* Koa 文档 —— [[https://koajs.com/|Context(ctx)]]
* RFC 9110 —— [[https://www.rfc-editor.org/rfc/rfc9110.html|HTTP Semantics(方法、状态码与报文语义)]]
相关:[[express]] · [[nodejs]] · [[代码术语:authorization|Authorization]] · [[代码术语:bearer|Bearer]] · [[代码术语:幂等|幂等]] · [[代码术语:404_303_这些是什么|状态码]]
----
返回:[[代码术语]]