流消费者的 API

🌐 API for stream consumers

几乎所有的 Node.js 应用，无论多么简单，都会以某种方式使用流。下面是一个在 Node.js 应用中使用流的示例，该应用实现了一个 HTTP 服务器：

🌐 Almost all Node.js applications, no matter how simple, use streams in some manner. The following is an example of using streams in a Node.js application that implements an HTTP server:

const http = require('node:http');

const server = http.createServer((req, res) => {
  // `req` is an http.IncomingMessage, which is a readable stream.
  // `res` is an http.ServerResponse, which is a writable stream.

  let body = '';
  // Get the data as utf8 strings.
  // If an encoding is not set, Buffer objects will be received.
  req.setEncoding('utf8');

  // Readable streams emit 'data' events once a listener is added.
  req.on('data', (chunk) => {
    body += chunk;
  });

  // The 'end' event indicates that the entire body has been received.
  req.on('end', () => {
    try {
      const data = JSON.parse(body);
      // Write back something interesting to the user:
      res.write(typeof data);
      res.end();
    } catch (er) {
      // uh oh! bad json!
      res.statusCode = 400;
      return res.end(`error: ${er.message}`);
    }
  });
});

server.listen(1337);

// $ curl localhost:1337 -d "{}"
// object
// $ curl localhost:1337 -d "\"foo\""
// string
// $ curl localhost:1337 -d "not json"
// error: Unexpected token 'o', "not json" is not valid JSON 拷贝

Writable 流（例如示例中的 res）提供了诸如 write() 和 end() 等方法，用于向流中写入数据。

Readable 流使用 EventEmitter API 来通知应用代码当有数据可以从流中读取时。这些可用的数据可以通过多种方式从流中读取。

Writable 和 Readable 流都以各种方式使用 EventEmitter API 来传达流的当前状态。

🌐 Both Writable and Readable streams use the EventEmitter API in various ways to communicate the current state of the stream.

Duplex 和 Transform 流都是 Writable 和 Readable。

向流写入数据或从流读取数据的应用不需要直接实现流接口，通常也没有理由调用 require('node:stream')。

🌐 Applications that are either writing data to or consuming data from a stream are not required to implement the stream interfaces directly and will generally have no reason to call require('node:stream').

希望实现新类型流的开发者应参考第流实现者的 API节。

🌐 Developers wishing to implement new types of streams should refer to the section API for stream implementers.