# @bernierllc/neverhub-adapter 中文文档

规范地址：https://npmcn.com/package/%40bernierllc/neverhub-adapter/

版本：0\.4\.1
npm 元数据更新时间：2026-07-14T07:54:25.347Z
中文译文更新时间：2026-11-07T23:11:38.486Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bernierllc/neverhub-adapter
原文对照：https://npmcn.com/package/%40bernierllc/neverhub-adapter/?lang=original
项目主页：https://github.com/bernier-llc/tools#readme
源码仓库：https://github.com/bernier-llc/tools

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：138 kB，43 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-08-29T22:48:48.000Z
- 最新版本发布：2026-07-14T07:54:25.215Z
- 近 30 天下载量：4397（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 8 个）

## 中文简介

将伯尼尔LLC软件包与NeverHub服务发现和事件总线系统整合的标准化适配器

## 安装

```sh
npm install @bernierllc/neverhub-adapter
```

也可以使用：`pnpm add @bernierllc/neverhub-adapter`、`yarn add @bernierllc/neverhub-adapter`、`bun add @bernierllc/neverhub-adapter`

## README

# @bernierllc/ 绝不是适应器

标准化适配器,用于将BernierLLC包与NeverHub服务发现和事件总线系统相融合.

## 安装

```bash
npm install @bernierllc/neverhub-adapter
```

## 特征

-   **自动检测**: 如果环境中有NeverHub,则自动检测
-   **服务登记**: 登记服务发现的软件包能力和依赖性
-   **事件系统**: 出版/订阅生态系统各套件的事件
-   **服务发现**: 动态查找和使用其他软件包
-   **卫生监测**: 整套报告健康状况和衡量标准
-   **配置**: 从 NeverHub 装入配置和连接字符串
-   **重大退化**: NeverHub 不可用时的完整功能

## 快速启动

### 基本融合

```typescript
import { NeverHubAdapter } from '@bernierllc/neverhub-adapter';

export class MyPackage {
  private neverhub?: NeverHubAdapter;

  async initialize(): Promise<void> {
    // Auto-detect NeverHub
    if (await NeverHubAdapter.detect()) {
      this.neverhub = new NeverHubAdapter();
      
      // Register with NeverHub
      await this.neverhub.register({
        type: 'my-package',
        name: '@bernierllc/my-package',
        version: '1.0.0',
        capabilities: [
          { type: 'data', name: 'processing', version: '1.0.0' }
        ],
        dependencies: ['logging']
      });
    }

    await this.initializeCore();
  }
}
```

### 事件出版

```typescript
// Safe event publishing - works even when NeverHub is unavailable
await this.neverhub?.publishEvent({
  type: 'data.processed',
  data: { recordId: '123', status: 'success' },
  source: 'my-package'
});
```

### 事件订阅

```typescript
// Subscribe to events with pattern matching
const unsubscribe = await this.neverhub?.subscribe('user.*', async (event) => {
  console.log('User event received:', event);
});

// Clean up subscription when done
// unsubscribe?.();
```

### 服务发现

```typescript
// Find services by capability
const services = await this.neverhub?.discover({
  capabilityTypes: ['logging']
});

if (services?.available.includes('structured-logging')) {
  const logger = await this.neverhub.getService('structured-logging');
  // Use the logger service
}
```

### 配置管理

```typescript
// Load configuration with defaults
const config = await this.neverhub?.getConfiguration('my-package', {
  logging: { level: 'info' },
  retries: 3
});

// Get connection strings
const dbConnection = await this.neverhub?.getConnectionString('my-package', 'database');
```

### 健康检查和计量

```typescript
// Register health check
await this.neverhub?.registerHealthCheck('my-package', async () => {
  return {
    healthy: this.isOperational(),
    message: 'Service is running normally',
    metadata: { uptime: process.uptime() }
  };
});

// Report metrics
await this.neverhub?.reportMetric('my-package', {
  name: 'requests_total',
  value: 100,
  type: MetricType.COUNTER,
  labels: { status: 'success' }
});
```

## API 参考

### Never HubAdapter 类

#### 静态方法

-   `static detect(): Promise<boolean>` - 检测是否有NeverHub可用

#### 实例方法

##### 核心方法

-   `initialize(): Promise<boolean>` - 初始化适配器
-   `register(registration: PackageRegistration): Promise<void>` - 登记包
-   `getState(): AdapterState` - 获得当前适配器状态
-   `isAvailable(): boolean` - 检查NeverHub是否可用
-   `isInitialized(): boolean` - 检查适配器是否已初始化
-   `isRegistered(): boolean` - 检查包是否注册

##### 活动方法

-   `publishEvent(event: Event): Promise<void>` - 出版活动
-   `subscribe(pattern: string, handler: EventHandler): Promise<() => void>` - 订阅活动

##### 发现方法

-   `discover(criteria: DiscoveryCriteria): Promise<ServiceDiscoveryResult>` - 发现服务
-   `getService(serviceName: string): Promise<any>` - 获得具体服务

##### 配置方法

-   `getConfiguration(packageName: string, defaults?: any): Promise<any>` - 获得配置
-   `getConnectionString(packageName: string, connectionName: string): Promise<string | null>` - 获取连接字符串
-   `getEnvironmentConfiguration(packageName: string, environment: string, defaults?: any): Promise<any>` - 获得环境特定配置

##### 卫生方法

-   `registerHealthCheck(packageName: string, checkFn: HealthCheckFunction): Promise<void>` - 登记健康检查
-   `reportMetric(packageName: string, metric: Metric): Promise<void>` - 报告标准

### 配置

适配器可以配置环境变量 :

-   `NEVERHUB_API_URL` - 自定义 NeverHub API URL
-   `NEVERHUB_ENDPOINT` - 备选终点规格
-   `NEVERHUB_HOST` - 仅限主机规格(将添加议定书)

或在方案方面:

```typescript
const adapter = new NeverHubAdapter({
  apiUrl: 'http://custom.neverhub.com:3001',
  timeout: 5000,
  maxRetries: 5,
  debug: true
});
```

### 类型

#### 软件包注册

```typescript
interface PackageRegistration {
  type: string;                    // Package type identifier
  name: string;                    // Full package name including scope
  version: string;                 // Semantic version
  dependencies: string[];          // List of dependency package names
  capabilities: Capability[];      // List of capabilities provided
  discoveryEnabled?: boolean;      // Whether discoverable by others
  discoverySubscriptions?: DiscoverySubscription[];
  webhookUrl?: string;            // Optional webhook URL
}
```

#### 活动

```typescript
interface Event {
  type: string;                   // Event type identifier
  data: any;                      // Event payload
  source?: string;                // Source package identifier
  timestamp?: string;             // Event timestamp (ISO string)
  metadata?: Record<string, any>; // Additional metadata
}
```

#### 能力

```typescript
interface Capability {
  type: string;                   // Capability type (e.g., 'data', 'logging')
  name: string;                   // Specific capability name
  version: string;                // Version of the capability interface
  metadata?: Record<string, any>; // Additional metadata
}
```

## 环境检测

适配器通过:

1.  **环境变量**: 检查 `NEVERHUB_API_URL`, (中文(简体) ), `NEVERHUB_ENDPOINT`,或 `NEVERHUB_HOST`
2.  **默认终点**: 测试 `http://localhost:3001` 财务报告和审定财务报表 `http://neverhub:3001`
3.  **健康检查**: 验证 API 可用性 `/api/health`

## 重大退化

当 NeverHub 不可用时,适配器 :

-   返回配置请求的默认值
-   默默忽略事件发布尝试
-   返回服务发现的空结果
-   调试日志警告, 但绝不丢出错误
-   维护完整软件包功能

## 处理错误

适配器的设计以优雅的退化为核心原则:

-   **从不扔出错误** 由于NeverHub不可用
-   **日志警告** 当操作失败时调试
-   **返回合理默认值** 当 NeverHub 数据不存在时
-   **维护软件包功能** 无论NeverHub状态

## 高级使用

### 自定义配置

```typescript
const adapter = new NeverHubAdapter({
  apiUrl: 'http://my-neverhub.internal:3001',
  timeout: 10000,
  maxRetries: 5,
  debug: process.env.NODE_ENV === 'development'
});
```

### 环境配置

```typescript
const config = await adapter.getEnvironmentConfiguration(
  'my-package',
  process.env.NODE_ENV || 'development',
  { logging: { level: 'info' } }
);
```

### 事件模式匹配

事件系统支持灵活模式匹配 :

-   `*` - 匹配任何事件类型
-   `user.*` - 匹配所有与用户相关的事件
-   `service.*.created` - 匹配任何服务的创建事件
-   `exact.match` - 只匹配确切的事件类型

### 工具函数

对于高级用途案例,输出工具功能:

```typescript
import {
  detectNeverHub,
  publishEvent,
  discoverServices,
  validatePackageRegistration
} from '@bernierllc/neverhub-adapter';
```

## 另见

这个软件包与其他 BernerLLC 软件包集成:

-   [@bernierllc/retry-policy (英语)](https://npmcn.com/package/%40bernierllc/retry-policy) - 内部用于重试逻辑
-   [@bernierllc/ logb- core](https://npmcn.com/package/%40bernierllc/logging-core) - 可以通过服务发现发现

## 许可证

版权(c)2025 Bernier有限责任公司。 版权所有.

## 常见问题

### @bernierllc/neverhub-adapter 是什么？

将伯尼尔LLC软件包与NeverHub服务发现和事件总线系统整合的标准化适配器

### 如何安装 @bernierllc/neverhub-adapter？

在项目目录运行 npm install @bernierllc/neverhub-adapter，或使用 pnpm add / yarn add / bun add。

### @bernierllc/neverhub-adapter 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bernierllc/neverhub-adapter 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bernierllc/neverhub-adapter 可以商用吗？

@bernierllc/neverhub-adapter 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bernierllc/neverhub-adapter 的下载量有多少？

根据 npm 官方下载统计，@bernierllc/neverhub-adapter 在 2026/10/08 – 2026/11/06 这 30 天内被下载 4,397 次，日均约 147 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bernierllc/neverhub-adapter 还在维护吗？

最新版本 0\.4\.1 发布于 2026/07/14（3 个月前）；至今共发布 9 个版本，其中过去 12 个月发布了 8 个；首次发布于 2025/08/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。