Node.js ServerHttp2Stream http2stream.respondWithFile(path[, headers[, options]])用法及代码示例

http2stream.respondWithFile(path[, headers[, options]])

参数

• path <string> | <Buffer> | <URL>
• headers <HTTP/2 Headers Object>
• options <Object>
  • statCheck <Function>
  • onError <Function> 发送前发生错误时调用的回调函数。
  • waitForTrailers <boolean> 当 true 时，Http2Stream 将在最后的 DATA 帧发送后发出 'wantTrailers' 事件。
  • offset <number> 开始读取的偏移位置。
  • length <number> 要从 fd 发送的数据量。

发送一个常规文件作为响应。 path 必须指定常规文件，否则将在 Http2Stream 对象上发出 'error' 事件。

使用时，Http2Stream对象的Duplex接口会自动关闭。

可以指定可选的 options.statCheck 函数，以使用户代码有机会根据给定文件的 fs.Stat 详细信息设置其他内容标头：

如果在尝试读取文件数据时发生错误，将使用标准 INTERNAL_ERROR 代码使用 RST_STREAM 帧关闭 Http2Stream。如果定义了onError 回调，那么它将被调用。否则流将被销毁。

使用文件路径的示例：

const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    headers['last-modified'] = stat.mtime.toUTCString();
  }

  function onError(err) {
    // stream.respond() can throw if the stream has been destroyed by
    // the other side.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 });
      } else {
        stream.respond({ ':status': 500 });
      }
    } catch (err) {
      // Perform actual error handling.
      console.log(err);
    }
    stream.end();
  }

  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck, onError });
});

options.statCheck 函数也可用于通过返回 false 来取消发送操作。例如，条件请求可以检查统计结果以确定文件是否已被修改以返回适当的 304 响应：

const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    // Check the stat here...
    stream.respond({ ':status': 304 });
    return false; // Cancel the send operation
  }
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck });
});

content-length 标头字段将被自动设置。

offset 和length 选项可用于将响应限制为特定范围子集。例如，这可以用于支持 HTTP Range 请求。

options.onError 函数还可用于处理在启动文件交付之前可能发生的所有错误。默认行为是销毁流。

当设置options.waitForTrailers 选项时，将在排队要发送的最后一块有效负载数据后立即发出'wantTrailers' 事件。然后可以使用http2stream.sendTrailers() 方法将尾随标头字段发送到对等方。

当设置options.waitForTrailers 时，在传输最后一个DATA 帧时，Http2Stream 不会自动关闭。用户代码必须调用 http2stream.sendTrailers() 或 http2stream.close() 来关闭 Http2Stream 。

const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });
});