Controllers ni nini katika NestJS?

Question

Accepted Answer

**Controllers** hushughulikia **HTTP requests** zinazoingia na hurudisha majibu. Hufafanua njia (routes) za programu yako na hufanya kazi kama mlango wa kuingilia — kupokea requests, kutoa data, kukabidhi kazi kwa services, na kurudisha matokeo. Huweka mambo ya routing yakiwa tofauti na business logic.

## Kufafanua controller

```ts
import { Controller, Get, Post, Body, Param } from "@nestjs/common";

@Controller("users")          // the route PREFIX → all routes start with /users
export class UsersController {
  constructor(private usersService: UsersService) {}   // inject a service via DI

@Get()                       // GET /users
  findAll() {
    return this.usersService.findAll();
  }

@Get(":id")                  // GET /users/:id
  findOne(@Param("id") id: string) {        // extract the route param
    return this.usersService.findOne(id);
  }

@Post()                      // POST /users
  create(@Body() dto: CreateUserDto) {       // extract the request body
    return this.usersService.create(dto);
  }
}
```

## Jinsi inavyofanya kazi: decorators huunganisha methods na routes

```text
@Controller("users") → route prefix /users
@Get() / @Post() / @Put() / @Patch() / @Delete() → HTTP method + sub-path
Combined: @Get(":id") inside @Controller("users") → GET /users/:id
```

Decorators huunganisha class methods na HTTP routes kwa njia ya kutangaza (declarative) — safi na rahisi kusoma, bila usajili wa routes wa mkono.

## Parameter decorators hutoa data ya request

```ts
@Get(":id")
example(
  @Param("id") id: string,        // route parameter (/users/:id)
  @Query("sort") sort: string,    // query string (?sort=name)
  @Body() body: CreateUserDto,    // request body
  @Headers("authorization") auth: string,  // a header
  @Req() req: Request,            // the raw request object (rarely needed)
) {}
```

Parameter decorators za Nest (`@Param`, `@Query`, `@Body`, `@Headers`) hutoa data hasa unayohitaji kwa usafi — bila kuchanganua `req` kwa mkono.

## Controllers zinapaswa kuwa NYEMBAMBA (THIN)

```ts
// ✅ controller delegates to a service — stays thin
@Post()
create(@Body() dto: CreateUserDto) {
  return this.usersService.create(dto);   // business logic lives in the SERVICE
}
// ❌ don't put database queries / business logic directly in the controller
```

Mazoezi bora: weka controllers **zikiwa nyembamba** — hushughulikia mambo ya HTTP (routing, kutoa data, kurudisha majibu) na hukabidhi business logic yote kwa **services**. Mgawanyo huu huweka code ikiwa rahisi kupima (testable) na imepangwa vizuri.

## Kwa nini ni muhimu

Controllers ni kipengele cha msingi cha NestJS — mlango wa kuingilia kwa HTTP requests zote na mahali ambapo routes za API yako hufafanuliwa.

Kuelewa jinsi decorators (`@Controller`, `@Get`/`@Post`, `@Param`/`@Body`/`@Query`) zinavyounganisha methods na routes na kutoa data ya request kwa njia ya kutangaza ni maarifa muhimu ya kila siku ya NestJS — ndiyo jinsi unavyojenga endpoint yoyote.

Muhimu pia ni kanuni ya kuweka controllers **zikiwa nyembamba** (zikishughulikia mambo ya HTTP pekee na kukabidhi business logic kwa services zilizoingizwa), ambayo huonyesha falsafa ya NestJS ya mgawanyo wa majukumu (separation of concerns) na huweka code ikiwa rahisi kudumisha na kupima.

Controllers, pamoja na services na modules, huunda muundo wa msingi wa kila programu ya NestJS, jambo linalozifanya kuwa muhimu kuelewa tangu mwanzo.