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 写 });
纯粹是约定俗成的短写:这两个对象在几乎每个函数签名里都要出现,写全名太长,社区统一缩成 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 是客户端说了什么的完整快照。在 Node 里它的底层类型是 http.IncomingMessage,Express 在上面加了一层糖。
| 属性 | 含义 |
req.method | GET / POST / PUT … |
req.originalUrl | 原始完整路径(含查询串),改写路由后仍然保留 |
req.path | 路径部分,不含查询串 |
req.params | 路径参数,如 /users/:id 里的 id |
req.query | 查询串解析结果,如 ?page=2 |
| 属性 | 含义 |
req.headers | 全部请求头(键名已小写) |
req.get(“user-agent”) | 取单个头的便捷方法(大小写不敏感) |
req.cookies | 需要 cookie 解析中间件 |
req.ip | 客户端 IP,注意反向代理下要配 trust proxy |
req.protocol | http / https,同样受代理影响 |
req.body 是最容易被误解的一项:它不是天生就有的。
req 是可读流,必须自己 req.on(“data”) 拼接 Buffer;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 }); });
req 上挂自定义属性(如 req.auth、req.user)是常见做法,但要选不会与框架字段撞名的名字。req 上有业务状态;它是「这一层的事」的载体。
res 是你要对客户端说的话。底层类型是 http.ServerResponse,它本身是一个可写流,并且有一条硬性约束:
**响应头一旦发出(第一次 ''write'' / ''send'' / ''json'' / ''end''),就不能再改;body 写完就不能再写第二次。**
| 方法 | 作用 |
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”) | 重定向,见 状态码语义 |
res.sendFile(path) / res.render(view) | 发文件 / 渲染模板 |
return:res.json() 之后函数不会自动结束,忘记 return 就会继续执行后面的代码,甚至二次发送。ERRHTTPHEADERS_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 | 二次发送 → ERRHTTPHEADERS_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 |