NestJS で Gemini API バックエンドを設計する — DI・例外フィルタ・ガードを活かす実装パターン

// src/gemini/gemini.controller.ts
import { Body, Controller, Post, Sse, MessageEvent } from '@nestjs/common';
import { Observable } from 'rxjs';
import { GeminiService } from './gemini.service';
 
@Controller('gemini')
export class GeminiController {
  constructor(private readonly gemini: GeminiService) {}
 
  @Sse('stream')
  stream(@Body() body: { prompt: string }): Observable<MessageEvent> {
    return new Observable((subscriber) => {
      (async () => {
        try {
          for await (const text of this.gemini.stream(body.prompt)) {
            subscriber.next({ data: { text } });
          }
          subscriber.complete();
        } catch (err) {
          subscriber.error(err);
        }
      })();
    });
  }
}

// src/gemini/gemini-exception.filter.ts
import { ArgumentsHost, Catch, ExceptionFilter, HttpStatus } from '@nestjs/common';
import { Response } from 'express';
 
@Catch()
export class GeminiExceptionFilter implements ExceptionFilter {
  catch(exception: any, host: ArgumentsHost) {
    const res = host.switchToHttp().getResponse<Response>();
    const msg = String(exception?.message ?? exception);
 
    if (msg.includes('RESOURCE_EXHAUSTED') || msg.includes('429')) {
      return res.status(HttpStatus.TOO_MANY_REQUESTS).json({
        error: 'rate_limited',
        retryAfter: 30,
      });
    }
    if (msg.includes('SAFETY') || msg.includes('blocked')) {
      return res.status(HttpStatus.BAD_REQUEST).json({
        error: 'content_blocked',
      });
    }
    return res.status(HttpStatus.INTERNAL_SERVER_ERROR).json({
      error: 'gemini_failure',
      detail: process.env.NODE_ENV === 'production' ? undefined : msg,
    });
  }
}

// src/gemini/api-key.guard.ts
import { CanActivate, ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';
 
@Injectable()
export class ApiKeyGuard implements CanActivate {
  canActivate(ctx: ExecutionContext): boolean {
    const req = ctx.switchToHttp().getRequest();
    const key = req.headers['x-api-key'];
    if (!key || key !== process.env.PUBLIC_API_KEY) {
      throw new UnauthorizedException('invalid api key');
    }
    return true;
  }
}

// src/gemini/gemini.service.ts（抜粋）
private readonly fallbackOrder = ['gemini-2.5-flash', 'gemini-2.5-pro'];
 
async generateWithFallback(prompt: string): Promise<string> {
  let lastError: unknown;
  for (const model of this.fallbackOrder) {
    try {
      const m = this.client.getGenerativeModel({ model });
      const res = await m.generateContent(prompt);
      return res.response.text();
    } catch (err) {
      const msg = String((err as Error)?.message ?? err);
      // 過負荷・クォータのみ次モデルへ。安全性ブロックは即座に投げ直す
      if (msg.includes('503') || msg.includes('RESOURCE_EXHAUSTED')) {
        lastError = err;
        continue;
      }
      throw err;
    }
  }
  throw lastError;
}

// src/gemini/retry.interceptor.ts
import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { Observable, throwError } from 'rxjs';
import { retry, timer } from 'rxjs';
 
@Injectable()
export class RetryInterceptor implements NestInterceptor {
  intercept(_ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    return next.handle().pipe(
      retry({
        count: 3,
        delay: (error, retryCount) => {
          const msg = String((error as Error)?.message ?? error);
          const retriable = msg.includes('503') || msg.includes('RESOURCE_EXHAUSTED');
          if (!retriable) return throwError(() => error);
          // 指数バックオフ + ジッタ（250ms, 500ms, 1000ms を基準に揺らす）
          const base = 250 * 2 ** (retryCount - 1);
          const jitter = Math.random() * 100;
          return timer(base + jitter);
        },
      }),
    );
  }
}

// src/gemini/metrics.interceptor.ts
import { CallHandler, ExecutionContext, Injectable, Logger, NestInterceptor } from '@nestjs/common';
import { Observable, tap } from 'rxjs';
 
@Injectable()
export class MetricsInterceptor implements NestInterceptor {
  private readonly logger = new Logger('GeminiMetrics');
 
  intercept(ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    const started = Date.now();
    const route = ctx.switchToHttp().getRequest().url;
    return next.handle().pipe(
      tap((payload: any) => {
        const ms = Date.now() - started;
        const usage = payload?.usageMetadata;
        this.logger.log(
          `route=${route} latency_ms=${ms} ` +
          `in=${usage?.promptTokenCount ?? '-'} out=${usage?.candidatesTokenCount ?? '-'}`,
        );
      }),
    );
  }
}