====== 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_这些是什么|状态码]] ---- 返回:[[代码术语]]