Mitä ovat exception filterit?

Question

Accepted Answer

**Exception filterit** antavat sinulle täyden kontrollin siitä, kuinka virheet **otetaan kiinni ja muunnetaan vastauksiksi**. Ne sijaitsevat request-elinkaaren lopussa, ottaen kiinni poikkeukset, jotka heitetään missä tahansa requestissa, ja antaen sinulle mahdollisuuden mukauttaa virhevastauksen muotoa, status-koodia ja lokitusta.

## Perusesimerkki exception filteristä

```ts
import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from "@nestjs/common";

@Catch(HttpException)                    // catch HttpExceptions specifically
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const request = ctx.getRequest();
    const status = exception.getStatus();

// build a CUSTOM error response shape
    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message: exception.message,
    });
  }
}
```

`@Catch()`-dekoraattori määrittää, mitkä poikkeustyypit tämä filtteri käsittelee, ja `catch()`-metodi vastaanottaa poikkeuksen sekä kontekstin — antaen sinulle mahdollisuuden luoda minkä tahansa vastauksen haluat.

## Kaikkien poikkeusten ottaminen kiinni (mukaan lukien ei-HTTP-poikkeukset)

```ts
@Catch()                                 // no argument = catch EVERYTHING
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const status = exception instanceof HttpException
      ? exception.getStatus()
      : 500;                              // unknown errors → 500
    // log the full error internally, return a safe message to the client
    this.logger.error(exception);
    ctx.getResponse().status(status).json({ statusCode: status, message: "..." });
  }
}
```

Filtteri, jonka `@Catch()` (ei argumenttia) käsittelee jokaisen poikkeuksen — paikka odottamattomien virheiden lokitukselle ja sen varmistamiselle, että jopa ei-HTTP-virheet palauttavat puhtaan, turvallisen vastauksen (ilman stack trace -vuotoja asiakkaille).

## Filtterien soveltaminen

```ts
@UseFilters(HttpExceptionFilter)         // method or controller level
export class UsersController {}

app.useGlobalFilters(new AllExceptionsFilter());   // GLOBAL — app-wide, most common
```

Filtterit yleensä sovelletaan **globaalisti** yhdenmukaisen virheen muodon pakottamiseksi koko API:ssa.

## Miksi käyttää exception filttereitä?

```text
✓ Consistent error response format across ALL endpoints (a standard shape)
✓ Centralized error LOGGING (log every error in one place)
✓ Handle non-HTTP errors safely (turn unexpected errors into clean 500s)
✓ Hide internal details from clients (no leaked stack traces — security)
✓ Add context (request path, timestamp, correlation IDs) to error responses
```

## Filterit verrattuna poikkeusten heittämiseen

```text
Throwing exceptions (NotFoundException, etc.) → SIGNALS an error with a status
Exception filters → control HOW those errors are FORMATTED/logged into responses
→ You throw exceptions in your code; filters customize the resulting response globally.
```

## Miksi sillä on merkitystä

Exception filterit ovat tärkeä NestJS-ominaisuus robustien ja ammattimaisten API:iden rakentamiselle **johdonmukaisella ja hallitulla virheiden käsittelyllä**.

Vaikka NestJS:n sisäänrakennettu exception-kerros jo muuntaa heitetyt poikkeukset HTTP-vastauksiksi, exception filterit antavat sinulle täyden kontrollin mukauttaa tämän toiminnan — mikä on tärkeää useista käytännön syistä: **johdonmukaisen virhevastaus-rakenteen** pakottaminen kaikissa päätteissä (jotta asiakkaat saavat virheet aina samassa muodossa), **virheiden lokituksen keskittäminen** (jokaisen virheen kaappaaminen yhdessä paikassa hajanaisten try/catch-lohkojen sijaan), odottamattomien ei-HTTP-virheiden **turvallinen käsittely** (muuntaminen puhtaaksi 500-vastauksiksi kaatumisen tai yksityiskohtien vuotamisen sijaan), ja **turvallisuus** (sisäisten stack trace -tietojen ja herkkien tietojen piilottaminen asiakkailta samalla kun ne tallennetaan lokiin sisäisesti).

Globaali "catch-all" -filtteri yhdessä tiettyjen HTTP-poikkeusten heittämisen kanssa koodissasi on standardi malli production-level virheiden käsittelyyn.

Ymmärtäminen siitä, milloin ja miten filtereitä käytetään (verrattuna pelkkään poikkeusten heittämiseen), sekä niiden globaali soveltaminen johdonmukaisuuden vuoksi, on hyvin rakennettujen NestJS-sovellusten tunnusmerkki ja heijastaa kypsää back-end-käytäntöä usein huomiotta jätetyn mutta kriittisen virheiden käsittelyn ongelman ratkaisemisesta.