代码术语:req和res

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

代码术语:req和res [2026/11/11 14:50] – 创建 张叶安代码术语:req和res [2026/11/11 14:51] (当前版本) – 补全 req 和 res(请求与响应)词条:含义、职责、对照表、各框架写法、常见坑 张叶安
行 1: 行 1:
-1+====== req 和 res(请求与响应) ====== 
 + 
 +**''req''** 是 **request**(请求)的缩写,**''res''** 是 **response**(响应)的缩写。它们成对出现,代表一次 HTTP 交互的两端: 
 + 
 +  * **''req''** = 客户端递进来的那张单子 —— **只读的输入**; 
 +  * **''res''** = 服务端要写回去的回执 —— **只能写一次的输出**。 
 + 
 +> **一句话**:''req'' 负责「读进来」,''res'' 负责「写回去」;它们的名字不是随便起的,而是**方向**的标记。 
 + 
 +这个命名在 Node.js / Express 生态里几乎人尽皆知,因为每个处理器都长这样: 
 + 
 +<code javascript> 
 +app.get("/users/:id", (req, res) => { 
 +  const id = req.params.id;          // 从 req 读 
 +  res.json({ id });                  // 往 res 写 
 +}); 
 +</code> 
 + 
 +===== 一、为什么不叫 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')''」的第一大来源。 
 + 
 +<code javascript> 
 +app.use(express.json());              // 少了这一行,req.body 就是 undefined 
 + 
 +app.post("/orders", (req, res) => { 
 +  const { amount } = req.body ?? {};   // 保守写法 
 +  res.status(201).json({ amount }); 
 +}); 
 +</code> 
 + 
 +==== 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 一次」。 
 + 
 +<code javascript> 
 +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" }); 
 +  } 
 +}); 
 +</code> 
 + 
 +===== 四、一张对照表 ===== 
 + 
 +| 维度 | ''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_这些是什么|状态码]] 
 + 
 +---- 
 + 
 +返回:[[代码术语]] 

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • 代码术语/req和res.txt
  • 最后更改: 2026/11/11 14:51
  • 由 张叶安