@bernierllc/ 绝不是适应器
标准化适配器,用于将BernierLLC包与NeverHub服务发现和事件总线系统相融合.
安装
npm install @bernierllc/neverhub-adapter
特征
- 自动检测: 如果环境中有NeverHub,则自动检测
- 服务登记: 登记服务发现的软件包能力和依赖性
- 事件系统: 出版/订阅生态系统各套件的事件
- 服务发现: 动态查找和使用其他软件包
- 卫生监测: 整套报告健康状况和衡量标准
- 配置: 从 NeverHub 装入配置和连接字符串
- 重大退化: NeverHub 不可用时的完整功能
快速启动
基本融合
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();
}
}
事件出版
// Safe event publishing - works even when NeverHub is unavailable
await this.neverhub?.publishEvent({
type: 'data.processed',
data: { recordId: '123', status: 'success' },
source: 'my-package'
});
事件订阅
// 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?.();
服务发现
// 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
}
配置管理
// 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');
健康检查和计量
// 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 URLNEVERHUB_ENDPOINT- 备选终点规格NEVERHUB_HOST- 仅限主机规格(将添加议定书)
或在方案方面:
const adapter = new NeverHubAdapter({
apiUrl: 'http://custom.neverhub.com:3001',
timeout: 5000,
maxRetries: 5,
debug: true
});
类型
软件包注册
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
}
活动
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
}
能力
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
}
环境检测
适配器通过:
- 环境变量: 检查
NEVERHUB_API_URL, (中文(简体) ),NEVERHUB_ENDPOINT,或NEVERHUB_HOST - 默认终点: 测试
http://localhost:3001财务报告和审定财务报表http://neverhub:3001 - 健康检查: 验证 API 可用性
/api/health
重大退化
当 NeverHub 不可用时,适配器 :
- 返回配置请求的默认值
- 默默忽略事件发布尝试
- 返回服务发现的空结果
- 调试日志警告, 但绝不丢出错误
- 维护完整软件包功能
处理错误
适配器的设计以优雅的退化为核心原则:
- 从不扔出错误 由于NeverHub不可用
- 日志警告 当操作失败时调试
- 返回合理默认值 当 NeverHub 数据不存在时
- 维护软件包功能 无论NeverHub状态
高级使用
自定义配置
const adapter = new NeverHubAdapter({
apiUrl: 'http://my-neverhub.internal:3001',
timeout: 10000,
maxRetries: 5,
debug: process.env.NODE_ENV === 'development'
});
环境配置
const config = await adapter.getEnvironmentConfiguration(
'my-package',
process.env.NODE_ENV || 'development',
{ logging: { level: 'info' } }
);
事件模式匹配
事件系统支持灵活模式匹配 :
*- 匹配任何事件类型user.*- 匹配所有与用户相关的事件service.*.created- 匹配任何服务的创建事件exact.match- 只匹配确切的事件类型
工具函数
对于高级用途案例,输出工具功能:
import {
detectNeverHub,
publishEvent,
discoverServices,
validatePackageRegistration
} from '@bernierllc/neverhub-adapter';
另见
这个软件包与其他 BernerLLC 软件包集成:
- @bernierllc/retry-policy (英语) - 内部用于重试逻辑
- @bernierllc/ logb- core - 可以通过服务发现发现
许可证
版权(c)2025 Bernier有限责任公司。 版权所有.