@lark-apaas/nestjs-observable

面向 NestJS 的 Observable SDK 集成，提供可注入的 Observable 服务、自动链路追踪拦截器，以及请求级 Root Span 中间件，便于在应用内统一记录日志与链路数据并自动透传请求上下文。

1. Project Context (项目背景与定位)

Architectural Role: Core (核心底层)

NestJS Observable 是一个核心底层库，为整个 Lark Apaas 服务端生态提供统一的可观测性能力，包括日志记录和链路追踪。

Key Consumers (谁在用我)

• 📱 @lark-apaas/fullstack-nestjs-core：平台核心模块，集成了该库作为底层可观测性基础
• 📝 @lark-apaas/nestjs-logger：日志模块，基于该库实现可观测性日志功能

Core Dependencies (我依赖谁)

• 🔧 @lark-apaas/nestjs-common：提供请求上下文服务和基础接口定义
• 📊 @lark-apaas/observable：底层可观测性 SDK，提供实际的日志和链路功能

2. Real-world Scenarios (基于真实挖掘)

Scenario A: The Standard Usage

说明： 在应用中集成和使用 Observable 服务的标准方式（参考自 @lark-apaas/nestjs-logger）

import { Module } from '@nestjs/common';
import { NestjsObservableModule, Observable } from '@lark-apaas/nestjs-observable';
import { RequestContextService, OBSERVABLE_SERVICE, CommonModule, ObservableService } from '@lark-apaas/nestjs-common';

@Module({
  imports: [CommonModule, NestjsObservableModule],
  providers: [
    {
      provide: OBSERVABLE_SERVICE,
      useFactory: (observable: ObservableService | null, rtx: RequestContextService) => {
        return observable ?? new Observable(rtx);
      },
      inject: [{
        token: OBSERVABLE_SERVICE,
        optional: true,
      }, RequestContextService],
    },
  ],
})
export class AppModule {}

Scenario B: Integration Example

说明： 在完整的 NestJS 应用中集成所有可观测性功能（参考自 @lark-apaas/fullstack-nestjs-core）

import { DynamicModule, Global, Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { CommonModule, OBSERVABLE_SERVICE } from '@lark-apaas/nestjs-common';
import { NestjsObservableModule, Observable, ObservableTraceMiddleware, TraceInterceptor } from '@lark-apaas/nestjs-observable';

@Global()
@Module({})
export class PlatformModule implements NestModule {
  static forRoot(options = {}): DynamicModule {
    return {
      module: PlatformModule,
      imports: [
        CommonModule,
        ObservableModule, // 引入 Observable 模块
      ],
      providers: [
        {
          provide: OBSERVABLE_SERVICE,
          useClass: Observable, // 提供可注入的 Observable 服务
        },
        {
          provide: APP_INTERCEPTOR,
          useClass: TraceInterceptor, // 全局应用自动链路追踪拦截器
        }
      ],
      exports: [OBSERVABLE_SERVICE]
    };
  }

  // 配置中间件
  configure(consumer: MiddlewareConsumer) {
    // 应用请求级 Root Span 中间件
    consumer
      .apply(
        ObservableTraceMiddleware // 应用 Observable 跟踪中间件
      )
      .forRoutes('/*');
  }
}

业务服务中使用示例：

import { Injectable } from '@nestjs/common';
import { Observable } from '@lark-apaas/nestjs-observable';

@Injectable()
export class DemoService {
  constructor(private readonly observable: Observable) {}

  async doWork(): Promise<boolean> {
    // 记录日志，自动包含上下文信息
    this.observable.log('info', '任务开始', { module: 'demo' });
    
    // 在链路中执行业务逻辑
    return this.observable.trace('doWork', async (span) => {
      // 业务逻辑
      this.observable.log('info', '任务进行中', { step: 'processing' });
      
      // 记录链路属性
      span.setAttributes({ processing_step: 'completed' });
      
      return true;
    });
  }
}

3. API Reference

Core Exports

| 导出项 | 类型 | 说明 | |--------|------|------| | NestjsObservableModule | NestJS Module | 全局模块，自动启动底层 SDK | | Observable | Injectable Class | 可注入的 Observable 服务，提供日志和链路功能 | | ObservableTraceMiddleware | NestJS Middleware | 请求级 Root Span 中间件，自动创建和管理链路上下文 | | TraceInterceptor | NestJS Interceptor | 自动链路追踪拦截器，基于元数据自动为方法创建子链路 |

Observable Service API

log(level: string, message: string, attributes?: Record<string, unknown>): void

• 记录日志，自动合并平台默认属性和请求上下文属性（user_id, tenant_id, app_id）
• 参数：
  • level: 日志级别（如 'info', 'error'）
  • message: 日志消息内容
  • attributes: 自定义属性（可选）

trace<T>(name: string, fn: (span: Span) => T | Promise<T> | Observable<T>): T | Promise<T> | Observable<T>

• 在指定名称的链路中执行函数，自动设置默认和上下文属性
• 参数：
  • name: 链路名称
  • fn: 要执行的函数，接收 span 对象作为参数
• 返回值：函数执行结果，支持同步、Promise 和 RxJS Observable

flush(): Promise<void>

• 主动刷新缓冲，在 FaaS 或短生命周期场景下使用更安全

Configuration

该库无需额外配置，会自动使用底层 @lark-apaas/observable SDK 的配置。主要依赖请求上下文服务 RequestContextService 来获取用户、租户和应用信息。

4. Middleware & Interceptor Behavior

ObservableTraceMiddleware

• 根据请求 method 和 path 自动命名 Root Span
• 从请求上下文获取用户信息并添加到链路属性
• 响应完成时自动设置 HTTP 状态码和 Span 状态（5xx 为 ERROR，4xx 为 UNSET，其他为 OK）
• 自动结束 Span 并刷新缓冲

TraceInterceptor

• 读取处理器元数据键 AUTO_TRACE（来自 @lark-apaas/nestjs-common）
• 存在时使用其值作为追踪名，否则采用处理器方法名
• 通过 Observable.trace() 包裹后续执行，实现自动链路追踪

5. Installation

npm install @lark-apaas/nestjs-observable

需要 @nestjs/common 与 @nestjs/core 作为 peer 依赖。

License

MIT