TypeStack/routing-controllers para TypeScript: guia completo com exemplos

1. O que é e para que serve

TypeStack/routing-controllers é uma biblioteca poderosa para TypeScript que permite criar aplicações server-side em Node.js utilizando decorators. Ela oferece uma forma declarativa de definir rotas, middlewares, validação e serialização de dados. Em vez de escrever manualmente handlers para cada requisição HTTP e conectá-los ao Express ou Koa, você simplesmente anota classes e métodos com decorators, e a biblioteca gera automaticamente toda a infraestrutura necessária.

Para que serve? No desenvolvimento web moderno com TypeScript, é comum enfrentar problemas de duplicação de código e dificuldade de manutenção em projetos grandes. O routing-controllers resolve isso oferecendo uma arquitetura limpa e modular, baseada em classes e decorators. Isso torna o código mais legível, testável e escalável. Você pode reutilizar middlewares facilmente, validar dados de entrada com o class-validator e gerar documentação OpenAPI (Swagger) automaticamente.

A biblioteca se integra perfeitamente com frameworks populares como Express e Koa, e faz parte do ecossistema TypeStack, que inclui também class-validator, class-transformer e typedi. Isso permite construir aplicações backend completas com injeção de dependências, validação e transformação de dados "de fábrica".

2. Instalação

Para instalar a biblioteca e suas dependências, execute os seguintes comandos no terminal do seu projeto:

npm install routing-controllers reflect-metadata

Você também precisará instalar um dos frameworks HTTP suportados. Recomendamos Express ou Koa:

npm install express
npm install @types/express --save-dev

Ou para Koa:

npm install koa
npm install @types/koa --save-dev

Não se esqueça de habilitar os decorators experimentais no seu tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true
  }
}

3. Início rápido — exemplo mínimo funcional

Crie um arquivo app.ts com o seguinte conteúdo:

import 'reflect-metadata';
import { createExpressServer, Get, Controller, Res } from 'routing-controllers';
import { Response } from 'express';

@Controller()
class UserController {
    @Get('/users')
    getAll(@Res() response: Response) {
        return response.json([{ id: 1, name: 'João Silva' }]);
    }
}

const app = createExpressServer({
    controllers: [UserController],
});

app.listen(3000, () => {
    console.log('Servidor rodando em http://localhost:3000');
});

Execute o servidor com o comando npx ts-node app.ts e abra no navegador http://localhost:3000/users. Você verá uma resposta JSON com um array de usuários.

4. Principais métodos/funções/classes

4.1 @Controller

Assinatura: @Controller(basePath?: string)

O que faz: Decorator de classe que marca a classe como um controller. Aceita um caminho base opcional, que será prefixado a todas as rotas dentro da classe.

Exemplo prático:

@Controller('/api')
class ApiController {
    @Get('/status')
    getStatus() {
        return { status: 'OK' };
    }
}
// Rota: GET /api/status

4.2 @Get, @Post, @Put, @Delete, @Patch

Assinatura: