TypeStack/routing-controllers para TypeScript: guía completa con ejemplos

1. ¿Qué es y para qué sirve?

TypeStack/routing-controllers es una potente biblioteca para TypeScript que permite crear aplicaciones de servidor en Node.js usando decoradores. Proporciona una forma declarativa de definir rutas, middleware, validación y serialización de datos. En lugar de escribir manualmente los controladores para cada petición HTTP y vincularlos con Express o Koa, simplemente decoras clases y métodos, y la biblioteca genera automáticamente toda la infraestructura necesaria.

¿Para qué sirve? En el desarrollo web moderno con TypeScript, a menudo surge el problema de duplicación de código y la dificultad de mantener proyectos grandes. routing-controllers resuelve esto ofreciendo una arquitectura limpia y modular basada en clases y decoradores. Esto hace que el código sea más legible, testeable y escalable. Puedes reutilizar middleware fácilmente, validar datos de entrada con class-validator y generar documentación OpenAPI (Swagger) de forma automática.

La biblioteca se integra estrechamente con frameworks populares como Express y Koa, y forma parte del ecosistema TypeStack, que también incluye class-validator, class-transformer y typedi. Esto permite construir aplicaciones backend completas con inyección de dependencias, validación y transformación de datos listas para usar.

2. Instalación

Para instalar la biblioteca y sus dependencias, ejecuta los siguientes comandos en la terminal de tu proyecto:

npm install routing-controllers reflect-metadata

También necesitarás instalar uno de los frameworks HTTP compatibles. Se recomienda Express o Koa:

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

O para Koa:

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

No olvides habilitar los decoradores experimentales en tu archivo tsconfig.json:

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

3. Inicio rápido — ejemplo mínimo funcional

Crea un archivo app.ts con el siguiente contenido:

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: 'Juan Pérez' }]);
    }
}

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

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

Ejecuta el servidor con npx ts-node app.ts y abre en tu navegador http://localhost:3000/users. Verás una respuesta JSON con un array de usuarios.

4. Métodos/funciones/clases principales

4.1 @Controller

Firma: @Controller(basePath?: string)

Qué hace: Decorador de clase que marca una clase como controlador. Acepta una ruta base opcional que se añadirá a todas las rutas dentro de la clase.

Ejemplo práctico:

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

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

Firma: