Kurs NestJS · Moduł 8: Cache i wydajność
Compression i Response Optimization - przyspieszenie posłańców Imperium
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?