Exception filters ni nini?

Question

Accepted Answer

**Exception filters** zinakupa udhibiti kamili juu ya jinsi makosa yanavyo **kamatwa na kubadilishwa kuwa majibu (responses)**. Zinakaa mwishoni mwa mzunguko wa maisha wa ombi (request lifecycle), zikikamata exceptions zilizotupwa popote ndani ya ombi na kukuruhusu kubinafsisha muundo wa jibu la kosa, status, na uwekaji logi.

## Exception filter ya msingi

```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,
    });
  }
}
```

Decorator ya `@Catch()` inabainisha ni aina gani za exception ambazo filter hii inazishughulikia, na method ya `catch()` inapokea exception pamoja na context — ikikuruhusu kuunda jibu lolote unalolitaka.

## Kukamata exceptions ZOTE (ikiwa ni pamoja na zisizo za HTTP)

```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: "..." });
  }
}
```

Filter yenye `@Catch()` (bila argument) inashughulikia kila exception — mahali pa kuweka logi za makosa yasiyotarajiwa na kuhakikisha kwamba hata makosa yasiyo ya HTTP yanarudisha jibu safi na salama (bila kuvujisha stack traces kwa wateja).

## Kutumia filters

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

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

Filters kwa kawaida hutumiwa **kwa kiwango cha global (globally)** ili kuhakikisha muundo thabiti wa kosa katika API nzima.

## Kwa nini utumie exception filters?

```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
```

## Filters dhidi ya kutupa exceptions

```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.
```

## Kwa nini ni muhimu

Exception filters ni kipengele muhimu cha NestJS kwa ajili ya kujenga API imara na za kitaalamu zenye **ushughulikiaji wa makosa thabiti na unaodhibitiwa**.

Ingawa safu ya exception iliyojengwa ndani ya NestJS tayari inabadilisha exceptions zilizotupwa kuwa majibu ya HTTP, exception filters zinakupa udhibiti kamili wa kubinafsisha tabia hiyo — jambo ambalo ni muhimu kwa masuala kadhaa halisi: kuhakikisha **muundo thabiti wa jibu la kosa** katika kila endpoint (ili wateja daima wapate makosa katika muundo uleule), **kuweka uwekaji logi wa makosa mahali pamoja** (kunasa kila kosa mahali pamoja badala ya try/catch zilizotawanyika), kushughulikia kwa usalama **makosa yasiyotarajiwa yasiyo ya HTTP** (kuyabadilisha kuwa 500 safi badala ya kuanguka au kuvujisha taarifa), na **usalama** (kuficha stack traces za ndani na taarifa nyeti kutoka kwa wateja huku zikiwekwa logi kwa ndani).

Filter ya "catch-all" ya global ikijumuishwa na kutupa HTTP exceptions mahususi ndani ya code yako ni mtindo wa kawaida wa ushughulikiaji wa makosa wa kiwango cha production.

Kuelewa lini na jinsi ya kutumia filters (dhidi ya kutupa exceptions tu), na kuzitumia kwa kiwango cha global kwa ajili ya uthabiti, ni alama ya programu za NestJS zilizojengwa vizuri na inaonyesha utendaji uliokomaa wa back-end kuhusu suala muhimu lakini mara nyingi linalopuuzwa la ushughulikiaji wa makosa.