Kurs NestJS · Moduł 8: Cache i wydajność

Compression i Response Optimization - przyspieszenie posłańców Imperium

7 min czytania ·
W tej lekcji6

Dowódco legionów! Endpoint z listą legionów wysyła dwa megabajty JSON-a, w tym pola, których żaden klient nie powinien zobaczyć. Wyobraź sobie posłańców Imperium, którzy wożą ogromne zwoje pergaminu między prowincjami. Mądry pretorianin kompresuje wiadomości: zamiast pełnych kronik wysyła zwięzłe raporty. W NestJS compression i response optimization to ta sama sztuka - zmniejszamy odpowiedzi, aby szybciej dotarły do klienta.

Compression Middleware - kompresja gzip/deflate

Kompresja to najprostszy sposób na przyspieszenie odpowiedzi HTTP. Middleware compression sam kompresuje odpowiedzi według nagłówka Accept-Encoding klienta:

// main.ts - dodanie kompresji
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import compression from 'compression';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Włącz kompresję (gzip, deflate, a od wersji 1.8 także brotli)
  app.use(compression({
    filter: (req, res) => {
      // Nie kompresuj odpowiedzi z nagłówkiem x-no-compression
      if (req.headers['x-no-compression']) {
        return false;
      }
      // Domyślny filtr - kompresuj text/html, application/json, etc.
      return compression.filter(req, res);
    },
    threshold: 1024,  // Kompresuj odpowiedzi > 1KB
    level: 6,         // Poziom kompresji zlib (0-9, domyślnie -1, czyli 6)
  }));

  await app.listen(3000);
}

bootstrap();

Pakiet obsługuje deflate, gzip, a od wersji 1.8 także brotli: w teście klient akceptujący gzip, deflate, br dostał brotli. Middleware dokłada też nagłówek Vary: Accept-Encoding. Poziom zlib to liczba od 0 do 9, a domyślne -1 oznacza obecnie 6. Dokumentacja NestJS radzi przy dużym ruchu przenieść kompresję do reverse proxy, np. Nginx.

Response Serialization z class-transformer

class-transformer pozwala kontrolować, które pola obiektu wyjdą w odpowiedzi. To jak cenzor w Imperium, który decyduje, jakie informacje mogą opuścić mury Senatu:

// legion.entity.ts
import { Exclude, Expose, Transform } from 'class-transformer';

export class LegionResponseDto {
  @Expose()
  id: number;

  @Expose()
  name: string;

  @Expose()
  province: string;

  // Ukryj wewnętrzne dane - nie wysyłaj za mury Imperium!
  @Exclude()
  internalCode: string;

  @Exclude()
  secretOrders: string;

  // Transformacja - przelicz na format czytelny dla obywateli
  @Transform(({ value }) => Math.round(value), { toPlainOnly: true })
  @Expose()
  soldiers: number;

  @Transform(({ value }) => new Date(value).toLocaleDateString('pl-PL'), { toPlainOnly: true })
  @Expose()
  foundedAt: string;

  // Warunkowe ukrywanie - pokaż tylko jeśli użytkownik ma rangę
  @Expose({ groups: ['admin', 'senator'] })
  budget: number;
}

@Exclude() ukrywa pole, @Expose() je pokazuje, a @Expose({ groups }) - tylko gdy żądanie ma jedną z grup. @Transform() zmienia wartość, a { toPlainOnly: true } ogranicza zmianę do wysyłki. Bez tej opcji transformacja przy obiektach z bazy uruchamia się dwa razy i w teście data zamieniła się w „Invalid Date”.

ClassSerializerInterceptor

Serializację wykonuje ClassSerializerInterceptor. Rejestrujemy go globalnie:

// app.module.ts - globalny interceptor serializacji
import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { ClassSerializerInterceptor } from '@nestjs/common';

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: ClassSerializerInterceptor,
    },
  ],
})
export class AppModule {}

Zamiast rejestracji globalnej możesz dać @UseInterceptors(ClassSerializerInterceptor) na kontrolerze - jedno albo drugie, bo razem serializują dwa razy. Uwaga na haczyk: interceptor działa tylko na instancjach klasy. Zwykły obiekt, np. z lean(), przechodzi nietknięty - w teście wyciekły internalCode i secretOrders. Pomaga opcja type:

// legion.controller.ts - użycie w kontrolerze
import { Controller, Get, SerializeOptions } from '@nestjs/common';
import { LegionResponseDto } from './legion.entity';
import { LegionService } from './legion.service';

@Controller('legions')
@SerializeOptions({ type: LegionResponseDto }) // zwykłe obiekty staną się instancjami DTO
export class LegionController {
  constructor(private readonly legionService: LegionService) {}

  @Get()
  findAll(): Promise<LegionResponseDto[]> {
    // Pola z @Exclude() zostaną automatycznie usunięte z odpowiedzi
    return this.legionService.findAll();
  }

  @Get('admin')
  @SerializeOptions({ type: LegionResponseDto, groups: ['admin'] })
  findAllAdmin(): Promise<LegionResponseDto[]> {
    // Pola z @Expose({ groups: ['admin'] }) będą widoczne
    return this.legionService.findAll();
  }
}

@SerializeOptions({ type }) zamienia zwykłe obiekty w instancje DTO przed serializacją. Opcje metody zastępują opcje klasy, dlatego przy groups powtarzamy type.

Pagination - stronicowanie odpowiedzi

Zamiast wysyłać wszystkie rekordy naraz, jak całą armię jedną drogą, dzielimy odpowiedź na strony. Parametry przychodzą w query jako tekst, więc DTO je waliduje:

// pagination.dto.ts
import { Type } from 'class-transformer';
import { IsIn, IsInt, IsOptional, Max, Min } from 'class-validator';

export class PaginationDto {
  @IsOptional()
  @Type(() => Number)
  @IsInt()
  @Min(1)
  page?: number = 1;

  @IsOptional()
  @Type(() => Number)
  @IsInt()
  @Min(1)
  @Max(100)
  limit?: number = 20;

  @IsOptional()
  @IsIn(['id', 'name', 'province'])
  sortBy?: string = 'id';

  @IsOptional()
  @IsIn(['ASC', 'DESC'])
  sortOrder?: 'ASC' | 'DESC' = 'ASC';
}

export class PaginatedResponse<T> {
  data: T[];
  meta: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  };
}

@Type(() => Number) zamienia tekst na liczbę, gdy globalny ValidationPipe ma transform: true. @Max(100) blokuje limit=1000000, a @IsIn przepuszcza tylko znane pola sortowania - sortowanie po ukrytym polu, np. hash hasła, zdradzałoby jego kolejność.

Serwis pobiera stronę i liczbę wszystkich rekordów równolegle:

// legion.service.ts
import { Injectable } from '@nestjs/common';
import { InjectModel } from '@nestjs/mongoose';
import { Model } from 'mongoose';

@Injectable()
export class LegionService {
  constructor(@InjectModel(Legion.name) private legionModel: Model<Legion>) {}

  async findPaginated(pagination: PaginationDto): Promise<PaginatedResponse<any>> {
    const { page, limit, sortBy, sortOrder } = pagination;
    const skip = (page - 1) * limit;

    // MongoDB z Mongoose
    const [data, total] = await Promise.all([
      this.legionModel
        .find()
        .sort({ [sortBy]: sortOrder === 'ASC' ? 1 : -1 })
        .skip(skip)
        .limit(limit)
        .lean()      // lean() zwraca POJO zamiast Mongoose Document - szybsze!
        .exec(),
      this.legionModel.countDocuments(),
    ]);

    const totalPages = Math.ceil(total / limit);

    return {
      data,
      meta: {
        page,
        limit,
        total,
        totalPages,
        hasNextPage: page < totalPages,
        hasPreviousPage: page > 1,
      },
    };
  }
}

lean() zwraca zwykłe obiekty, więc przy serializacji przydaje się type z poprzedniej sekcji. Na dużych kolekcjach countDocuments() bywa wolne, a skip zwalnia na dalekich stronach - wtedy pomaga kursor z lekcji o optymalizacji.

Response Caching Headers

Nagłówki cache pozwalają przeglądarkom i CDN-om trzymać odpowiedzi lokalnie. Interceptor ustawia je na drodze powrotnej:

// cache-headers.interceptor.ts
import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  CallHandler,
} from '@nestjs/common';
import { createHash } from 'node:crypto';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';
import { Response } from 'express';

@Injectable()
export class CacheHeadersInterceptor implements NestInterceptor {
  constructor(
    private readonly maxAge: number = 300, // 5 minut domyślnie
  ) {}

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const response = context.switchToHttp().getResponse<Response>();

    return next.handle().pipe(
      tap((body) => {
        // Cache-Control - jak długo posłaniec może trzymać kopię
        response.setHeader(
          'Cache-Control',
          `public, max-age=${this.maxAge}, s-maxage=${this.maxAge * 2}`
        );

        // ETag - identyfikator wersji zasobu, liczony z treści
        // Przeglądarka odeśle go w If-None-Match i dostanie 304 Not Modified
        response.setHeader('ETag', this.generateETag(body));
      }),
    );
  }

  private generateETag(body: unknown): string {
    // Ta sama treść = ten sam ETag; W/ oznacza słaby ETag
    const hash = createHash('sha1').update(JSON.stringify(body)).digest('base64url');
    return `W/"${hash}"`;
  }
}

max-age obowiązuje przeglądarkę, s-maxage - współdzielone cache, jak CDN. public stosuj tylko do danych wspólnych dla wszystkich; dane użytkownika dostają private. Pierwsza wersja liczyła ETag z Date.now(), więc zmieniał się przy każdym żądaniu i 304 nigdy nie padało. Express sam nadaje słaby ETag i odpowiada 304, więc własny ma sens, gdy wyliczysz go taniej, np. z updatedAt.

Interceptor ma parametr maxAge, więc tworzymy go sami przez new:

// Użycie w kontrolerze
@Controller('provinces')
export class ProvinceController {
  constructor(private readonly provinceService: ProvinceService) {}

  @Get()
  @UseInterceptors(new CacheHeadersInterceptor(600)) // 10 minut cache
  findAll() {
    return this.provinceService.findAll();
  }

  @Get(':id')
  @UseInterceptors(new CacheHeadersInterceptor(3600)) // 1 godzina cache
  findOne(@Param('id') id: string) {
    return this.provinceService.findOne(id);
  }
}

Przy @UseInterceptors(CacheHeadersInterceptor) NestJS próbowałby wstrzyknąć liczbę do konstruktora. Nagłówki cache warto poznawać w tej kolejności: Cache-Control to podstawa, ETag dokłada identyfikator wersji, Vary: Accept-Encoding rozdziela kopie w cache pośrednich, a If-None-Match wysyła przeglądarka przy ponownym pytaniu.

Dekoratory @Exclude, @Expose, @Transform - podsumowanie

Trzy kluczowe dekoratory z class-transformer:

  • @Exclude() - ukrywa pole z odpowiedzi (jak tajny rozkaz Cezara),
  • @Expose() - jawnie oznacza pole do wysłania (jak publiczny edykt),
  • @Transform() - modyfikuje wartość przed wysłaniem (jak tłumacz Imperium).

Kompletny przykład łączy wszystkie trzy:

// Kompletny przykład
import { Exclude, Expose, Transform } from 'class-transformer';

export class SoldierResponse {
  @Expose()
  id: number;

  @Expose()
  name: string;

  @Expose()
  rank: string;

  @Exclude()
  passwordHash: string;     // Nigdy nie wysyłaj hasła!

  @Exclude()
  internalNotes: string;    // Wewnętrzne notatki

  @Transform(({ value }) => value > 1000 ? 'Veteranus' : 'Tiro', { toPlainOnly: true })
  @Expose()
  experienceLevel: string;  // Transformacja liczbowa -> tekstowa

  @Transform(({ value }) => value?.toISOString(), { toPlainOnly: true })
  @Expose()
  enlistedAt: string;       // Data w formacie ISO
}

passwordHash zniknie jednak tylko wtedy, gdy serializer dostanie instancję klasy - przy zwykłym obiekcie hasło pojedzie do klienta. Polecam Ci zasadę: na zewnątrz wysyłaj wyłącznie DTO, nigdy surowe encje. W następnej lekcji posłańcy dostaną kolejki.

Pamiętaj: mądry pretor nie wysyła pełnych kronik, gdy wystarczy zwięzły raport - i nigdy nie dołącza do niego tajnych rozkazów.

Kod do tej lekcji: src/compression-optimization.ts
// Compression i Response Optimization
import { Injectable } from '@nestjs/common';
import { Exclude, Expose, Transform } from 'class-transformer';

// ===========================================
// 1. Response DTO z serializacja
// ===========================================

class LegionResponseDto {
  @Expose()
  id: number;

  @Expose()
  name: string;

  @Expose()
  province: string;

  // Ukryte pola - nie wysylaj za mury Imperium!
  @Exclude()
  internalCode: string;

  @Exclude()
  secretOrders: string;

  @Transform(({ value }) => Math.round(value))
  @Expose()
  soldiers: number;

  @Expose({ groups: ['admin'] })
  budget: number;
}

// ===========================================
// 2. Pagination pattern
// ===========================================

interface PaginatedResponse<T> {
  data: T[];
  meta: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNextPage: boolean;
  };
}

@Injectable()
class PaginationService {
  paginate<T>(items: T[], page: number, limit: number): PaginatedResponse<T> {
    const total = items.length;
    const totalPages = Math.ceil(total / limit);
    const start = (page - 1) * limit;
    const data = items.slice(start, start + limit);

    return {
      data,
      meta: {
        page,
        limit,
        total,
        totalPages,
        hasNextPage: page < totalPages,
      },
    };
  }
}

// ===========================================
// 3. Demonstracja
// ===========================================

const service = new PaginationService();
const legions = Array.from({ length: 50 }, (_, i) => ({
  id: i + 1,
  name: 'Legion ' + (i + 1),
  province: ['Gallia', 'Hispania', 'Britannia'][i % 3],
  soldiers: Math.floor(Math.random() * 5000) + 1000,
}));

const page1 = service.paginate(legions, 1, 10);
const page2 = service.paginate(legions, 2, 10);

console.log('=== Compression & Response Optimization ===');
console.log('Strona 1:', page1.data.length, 'rekordow');
console.log('Strona 2:', page2.data.length, 'rekordow');
console.log('Total:', page1.meta.total);
console.log('Strony:', page1.meta.totalPages);
console.log('');
console.log('@Exclude() - ukrywa pole z odpowiedzi');
console.log('@Expose() - jawnie oznacza pole');
console.log('@Transform() - modyfikuje wartosc');
console.log('compression() - gzip/deflate middleware');
console.log('Cache-Control, ETag - naglowki cache HTTP');

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Przydatne artykuły