Node.js v18.18.0 文档

公共接口#

概述#

以下是公共 API 的简单概述。

英Following is a simple overview of the public API.

import diagnostics_channel from 'node:diagnostics_channel';

// Get a reusable channel object
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Received data
}

// Subscribe to the channel
diagnostics_channel.subscribe('my-channel', onMessage);

// Check if the channel has an active subscriber
if (channel.hasSubscribers) {
  // Publish data to the channel
  channel.publish({
    some: 'data',
  });
}

// Unsubscribe from the channel
diagnostics_channel.unsubscribe('my-channel', onMessage);const diagnostics_channel = require('node:diagnostics_channel');

// Get a reusable channel object
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Received data
}

// Subscribe to the channel
diagnostics_channel.subscribe('my-channel', onMessage);

// Check if the channel has an active subscriber
if (channel.hasSubscribers) {
  // Publish data to the channel
  channel.publish({
    some: 'data',
  });
}

// Unsubscribe from the channel
diagnostics_channel.unsubscribe('my-channel', onMessage);拷贝

diagnostics_channel.hasSubscribers(name)#

• name <string> | <symbol> 通道名称
• 返回： <boolean> 如果有活跃订阅者

检查指定通道是否有活跃订阅者。 如果你要发送的消息的准备成本可能很高，这将很有帮助。

英Check if there are active subscribers to the named channel. This is helpful if the message you want to send might be expensive to prepare.

此 API 是可选的，但在尝试从对性能非常敏感的代码发布消息时很有用。

英This API is optional but helpful when trying to publish messages from very performance-sensitive code.

import diagnostics_channel from 'node:diagnostics_channel';

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // There are subscribers, prepare and publish message
}const diagnostics_channel = require('node:diagnostics_channel');

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // There are subscribers, prepare and publish message
}拷贝

diagnostics_channel.channel(name)#

• name <string> | <symbol> 通道名称
• 返回： <Channel> 命名通道对象

这是任何想要发布到命名通道的人的主要入口点。 它生成一个通道对象，该对象经过优化以尽可能减少发布时的开销。

英This is the primary entry-point for anyone wanting to publish to a named channel. It produces a channel object which is optimized to reduce overhead at publish time as much as possible.

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');拷贝

diagnostics_channel.subscribe(name, onMessage)#

• name <string> | <symbol> 通道名称
• onMessage <Function> 接收通道消息的处理程序
  • message <any> 消息数据
  • name <string> | <symbol> 通道名称

注册消息处理程序以订阅此通道。 每当消息发布到通道时，此消息处理程序将同步运行。 消息处理程序中抛出的任何错误都将触发 'uncaughtException'。

英Register a message handler to subscribe to this channel. This message handler will be run synchronously whenever a message is published to the channel. Any errors thrown in the message handler will trigger an 'uncaughtException'.

import diagnostics_channel from 'node:diagnostics_channel';

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Received data
});const diagnostics_channel = require('node:diagnostics_channel');

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Received data
});拷贝

diagnostics_channel.unsubscribe(name, onMessage)#

• name <string> | <symbol> 通道名称
• onMessage <Function> 要删除的先前订阅的处理程序
• 返回： <boolean> 如果找到处理程序则为 true，否则为 false。

删除以前使用 diagnostics_channel.subscribe(name, onMessage) 注册到此通道的消息处理程序。

英Remove a message handler previously registered to this channel with diagnostics_channel.subscribe(name, onMessage).

import diagnostics_channel from 'node:diagnostics_channel';

function onMessage(message, name) {
  // Received data
}

diagnostics_channel.subscribe('my-channel', onMessage);

diagnostics_channel.unsubscribe('my-channel', onMessage);const diagnostics_channel = require('node:diagnostics_channel');

function onMessage(message, name) {
  // Received data
}

diagnostics_channel.subscribe('my-channel', onMessage);

diagnostics_channel.unsubscribe('my-channel', onMessage);拷贝

类：Channel#

Channel 类代表数据管道中的一个单独的命名通道。 它用于跟踪订阅者并在有订阅者时发布消息。 它作为一个单独的对象存在，以避免在发布时进行通道查找，从而实现非常快的发布速度并允许大量使用，同时产生非常低的成本。 通道是用 diagnostics_channel.channel(name) 创建的，不支持直接用 new Channel(name) 构建通道。

英The class Channel represents an individual named channel within the data pipeline. It is used to track subscribers and to publish messages when there are subscribers present. It exists as a separate object to avoid channel lookups at publish time, enabling very fast publish speeds and allowing for heavy use while incurring very minimal cost. Channels are created with diagnostics_channel.channel(name), constructing a channel directly with new Channel(name) is not supported.

channel.hasSubscribers#

• 返回： <boolean> 如果有活跃订阅者

检查此通道是否有活跃订阅者。 如果你要发送的消息的准备成本可能很高，这将很有帮助。

英Check if there are active subscribers to this channel. This is helpful if the message you want to send might be expensive to prepare.

此 API 是可选的，但在尝试从对性能非常敏感的代码发布消息时很有用。

英This API is optional but helpful when trying to publish messages from very performance-sensitive code.

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

if (channel.hasSubscribers) {
  // There are subscribers, prepare and publish message
}const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');

if (channel.hasSubscribers) {
  // There are subscribers, prepare and publish message
}拷贝

channel.publish(message)#

• message <any> 要发送给通道订阅者的消息

向通道的任何订阅者发布消息。 这将同步触发消息处理程序，因此它们将在同一上下文中执行。

英Publish a message to any subscribers to the channel. This will trigger message handlers synchronously so they will execute within the same context.

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

channel.publish({
  some: 'message',
});const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');

channel.publish({
  some: 'message',
});拷贝

channel.subscribe(onMessage)#

• onMessage <Function> 接收通道消息的处理程序
  • message <any> 消息数据
  • name <string> | <symbol> 通道名称

注册消息处理程序以订阅此通道。 每当消息发布到通道时，此消息处理程序将同步运行。 消息处理程序中抛出的任何错误都将触发 'uncaughtException'。

英Register a message handler to subscribe to this channel. This message handler will be run synchronously whenever a message is published to the channel. Any errors thrown in the message handler will trigger an 'uncaughtException'.

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

channel.subscribe((message, name) => {
  // Received data
});const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');

channel.subscribe((message, name) => {
  // Received data
});拷贝

channel.unsubscribe(onMessage)#

• onMessage <Function> 要删除的先前订阅的处理程序
• 返回： <boolean> 如果找到处理程序则为 true，否则为 false。

删除以前使用 channel.subscribe(onMessage) 注册到此通道的消息处理程序。

英Remove a message handler previously registered to this channel with channel.subscribe(onMessage).

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Received data
}

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Received data
}

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);拷贝

内置通道#

虽然 diagnostics_channel API 现在被认为是稳定的，但当前可用的内置通道还不稳定。 每个通道都必须独立声明为稳定的。

英While the diagnostics_channel API is now considered stable, the built-in channels currently available are not. Each channel must be declared stable independently.

HTTP#

http.client.request.start

英http.client.request.start

• request <http.ClientRequest>

当客户端开始请求时触发。

英Emitted when client starts a request.

http.client.response.finish

英http.client.response.finish

• request <http.ClientRequest>
• response <http.IncomingMessage>

当客户端收到响应时触发。

英Emitted when client receives a response.

http.server.request.start

英http.server.request.start

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

当服务器收到请求时触发。

英Emitted when server receives a request.

http.server.response.finish

英http.server.response.finish

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

服务器发送响应时触发。

英Emitted when server sends a response.

net.client.socket

英net.client.socket

• socket <net.Socket>

创建新的 TCP 或管道客户端套接字时触发。

英Emitted when a new TCP or pipe client socket is created.

net.server.socket

英net.server.socket

• socket <net.Socket>

当接收到新的 TCP 或管道连接时触发。

英Emitted when a new TCP or pipe connection is received.

udp.socket

英udp.socket

• socket <dgram.Socket>

创建新的 UDP 套接字时触发。

英Emitted when a new UDP socket is created.