Node.js v18.16.0 文档

公共接口#

概述#

以下是公共 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> 如果有活跃订阅者

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

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

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> 命名通道对象

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

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'。

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) 注册到此通道的消息处理程序。

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)构建通道。

channel.hasSubscribers#

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

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

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

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> 要发送给通道订阅者的消息

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

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'。

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) 注册到此通道的消息处理程序。

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 现在被认为是稳定的，但当前可用的内置通道还不稳定。 每个通道都必须独立声明为稳定的。

HTTP#

http.client.request.start

• request <http.ClientRequest>

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

http.client.response.finish

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

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

http.server.request.start

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

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

http.server.response.finish

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

服务器发送响应时触发。

net.client.socket

• socket <net.Socket>

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

net.server.socket

• socket <net.Socket>

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

udp.socket

• socket <dgram.Socket>

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