Node.js / 系统课时
构造 HTTP 响应
构造 HTTP 响应
Node.js 原生 http 模块把响应交给 ServerResponse 对象控制。一次完整响应至少要处理状态码、响应头、响应体和结束时机;下面会直接搭一个可访问的 HTTP 服务,并检查客户端最终收到的内容。
学习目标
- 使用
statusCode和setHeader()设置 HTTP 状态与响应头 - 使用
write()、end()正确发送响应体并结束响应 - 根据
headersSent和响应语义定位常见错误
设置状态码和响应头
http.createServer() 的回调会收到 req 和 res。res.statusCode 在没有显式修改时默认为 200;响应头可在发送正文前通过 res.setHeader(name, value) 设置。返回 JSON 时,建议明确声明 UTF-8 编码,并按接口需要配置缓存策略。
下面的服务对 /users 返回 201 Created,其他路径返回 404 Not Found。示例适用于当前仍受支持的 Node.js 版本,并只使用稳定的 node:http API。
const http = require('node:http');
const server = http.createServer((req, res) => {
if (req.url === '/users') {
res.statusCode = 201;
res.setHeader('Content-Type', 'application/json; charset=utf-8');
res.setHeader('Cache-Control', 'no-store');
res.end(JSON.stringify({ id: 101, name: 'Ada' }));
return;
}
res.statusCode = 404;
res.setHeader('Content-Type', 'text/plain; charset=utf-8');
res.end('Not Found');
});
server.listen(3000, () => {
console.log('Server listening on http://localhost:3000');
});预期输出
Server listening on http://localhost:3000服务启动后执行:
curl -i http://localhost:3000/users预期结果中应看到 201 Created、Content-Type: application/json; charset=utf-8,响应体为:
{"id":101,"name":"Ada"}不同 Node.js 版本可能额外输出 Date、Connection、Keep-Alive 或传输编码相关响应头,这些自动生成的字段不影响本例验证。
写入并结束响应体
只有一小段正文时,直接把数据交给 res.end(data) 最简单。需要分多次产生内容时,可以先调用 res.write(),最后必须调用一次 res.end();否则客户端可能一直等待响应结束。
例如把两段文本依次写入响应体时,可以改成:
res.setHeader('Content-Type', 'text/plain; charset=utf-8');
res.write('hello ');
res.write('node');
res.end();预期结果
hello nodewrite() 可以调用多次,但不要把它理解成客户端一定会收到对应数量的数据包。TCP 和 HTTP 传输层可能重新组合这些数据,业务代码只应关心最终字节顺序是否正确。
不要在响应开始后再修改头部
第一次 res.write()、res.end(data) 或显式发送头部后,响应头就可能已经发给客户端。此时再执行 setHeader() 会失败。排查这类问题时,可以读取只读属性 res.headersSent 判断头部是否已经发送。
错误顺序是先写正文,再修改 Content-Type;正确顺序应当是先确定状态码和所有响应头,再发送正文。需要集中设置状态和头部时也可以使用 res.writeHead(statusCode, headers),但初学阶段建议统一使用 statusCode 加 setHeader(),更容易逐项修改和检查。
按响应语义选择正文
状态码不仅影响数字,还决定客户端应怎样解释响应。普通成功结果通常使用 200;成功创建资源常用 201;找不到资源使用 404;请求参数不合法常用 400。如果使用 204 No Content,就不应再设计业务响应体。
实际接口可以用固定顺序检查:先确定状态码,再设置 Content-Type 等响应头,然后序列化正文,最后调用 end()。当 curl -i 能同时看到预期状态行、响应头和响应体,并且请求能正常结束时,这次 HTTP 响应才算构造完整。