Roteador de Aplicação

Publicado em

08/03/2025

Roteador de Aplicação

O Roteador de Aplicação do Igniter é um componente central que conecta seus controladores ao seu framework HTTP. Ele fornece uma maneira limpa e segura em termos de tipos para definir suas rotas de API e lidar com requisições recebidas.

Configurando o Roteador de Aplicação

O primeiro passo é inicializar seu roteador conectando-o aos seus controladores:

// src/igniter.router.ts
import { igniter } from '@/igniter'
import { userController } from '@/features/user/controllers/user.controller'
import { notesController } from '@/features/notes/controllers/notes.controller'
import { authController } from '@/features/auth/controllers/auth.controller'

/**
 * @description Initialize the Igniter Router
 * @see https://github.com/felipebarcelospro/igniter-js
 */
export const AppRouter = igniter.router({
  baseURL: process.env.IGNITER_APP_URL || 'http://localhost:3000',
  basePATH: process.env.IGNITER_APP_BASE_PATH || '/api/v1',
  controllers: {
    users: userController,
    notes: notesController,
    auth: authController
  }
})

A configuração do roteador inclui:

  • baseURL: A URL base da sua aplicação (por exemplo, http://localhost:3000)
  • basePATH: O caminho base para suas rotas de API (por exemplo, /api/v1)
  • controllers: Um objeto mapeando nomes de controladores para suas implementações

Integrando com Frameworks HTTP

O Roteador de Aplicação do Igniter pode ser integrado com vários frameworks HTTP. Aqui estão exemplos para frameworks comuns:

Express

// src/server.ts
import express from 'express'
import { AppRouter } from '@/igniter.router'

const app = express()

// Use o roteador Igniter com Express
app.use(async (req, res) => {
  const response = await AppRouter.handler(req)
  res.status(response.status).json(response)
})

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

Next.js Route Handlers

// src/app/api/v1/[[...all]]/route.ts
import { AppRouter } from '@/igniter.router'
import { nextRouteHandlerAdapter } from '@igniter-js/core/adapters/next'

export const { GET, POST, PUT, DELETE } = nextRouteHandlerAdapter(AppRouter)

Bun

// src/server.ts
import { AppRouter } from '@/igniter.router'

Bun.serve({
  fetch: AppRouter.handler
})

Manipulação de Rotas

O Roteador de Aplicação manipula automaticamente o roteamento com base no caminho e método definidos em seus controladores. Por exemplo, se você tem um controlador com as seguintes ações:

const userController = igniter.controller({
  path: '/users',
  actions: {
    list: igniter.query({
      path: '/',
      handler: async (ctx) => {
        // Handle GET /api/v1/users
      }
    }),
    get: igniter.query({
      path: '/:id',
      handler: async (ctx) => {
        // Handle GET /api/v1/users/:id
      }
    }),
    create: igniter.mutation({
      path: '/',
      method: 'POST',
      handler: async (ctx) => {
        // Handle POST /api/v1/users
      }
    })
  }
})

O Roteador de Aplicação criará automaticamente as seguintes rotas:

  • GET /api/v1/users - Manipulada pela ação list
  • GET /api/v1/users/:id - Manipulada pela ação get
  • POST /api/v1/users - Manipulada pela ação create

Segurança de Tipos

Um dos principais benefícios do Roteador de Aplicação do Igniter é a segurança de tipos. O roteador fornece inferência completa de tipos para suas rotas de API, garantindo que seu código cliente esteja sempre sincronizado com seu código de servidor.

// The router type can be used to infer types for your API client
import { AppRouter } from '@/igniter.router'
import { createIgniterClient } from '@igniter-js/core/client'

export const api = createIgniterClient(AppRouter)

// Now your API client has full type inference
const result = await api.users.get.call({ params: { id: '123' } })
// result is fully typed based on the return type of your handler

Tratamento de Erros

O Roteador de Aplicação inclui tratamento de erros integrado. Se ocorrer um erro em sua ação do controlador, o roteador o capturará automaticamente e retornará uma resposta de erro apropriada.

const errorHandler = igniter.procedure({
  handler: async (_, ctx) => {
    try {
      return await ctx.next()
    } catch (error) {
      // Log the error
      console.error('API Error:', error)
      
      // Return a friendly error response
      if (error instanceof ValidationError) {
        return ctx.response.badRequest(error.message)
      }
      
      if (error instanceof NotFoundError) {
        return ctx.response.notFound(error.message)
      }
      
      // Default error response
      return ctx.response.internalServerError('An unexpected error occurred')
    }
  }
})

// Use the error handler in your router
export const AppRouter = igniter.router({
  baseURL: 'http://localhost:3000',
  basePATH: '/api/v1',
  controllers: {
    users: userController
  },
  use: [errorHandler()]
})

Configuração Avançada

Middleware

Você pode adicionar middleware global ao seu roteador usando a opção use:

export const AppRouter = igniter.router({
  baseURL: 'http://localhost:3000',
  basePATH: '/api/v1',
  controllers: {
    users: userController
  },
  use: [
    logger(),
    rateLimiter(),
    cors()
  ]
})

Transformadores de Resposta Personalizados

Você pode personalizar como as respostas são transformadas antes de serem enviadas ao cliente:

export const AppRouter = igniter.router({
  baseURL: 'http://localhost:3000',
  basePATH: '/api/v1',
  controllers: {
    users: userController
  },
  transformResponse: (response) => {
    // Add a timestamp to all responses
    return {
      ...response,
      timestamp: new Date().toISOString()
    }
  }
})

Melhores Práticas

  1. Organize Controladores por Recurso: Agrupe controladores relacionados com base em recursos ou domínios.

  2. Use Nomenclatura Consistente: Use convenções de nomenclatura consistentes para seus controladores e ações.

  3. Aproveite a Segurança de Tipos: Aproveite o sistema de tipos do TypeScript para garantir que sua API seja segura em termos de tipos.

  4. Implemente Tratamento de Erros: Sempre implemente tratamento adequado de erros para fornecer mensagens de erro significativas aos clientes.

  5. Use Variáveis de Ambiente: Armazene valores de configuração como baseURL e basePATH em variáveis de ambiente para flexibilidade em diferentes ambientes.

  6. Mantenha o Roteador Simples: O roteador deve ser uma camada fina que conecta controladores a frameworks HTTP. Lógica complexa deve estar em controladores ou procedimentos.

PRO

Quer desenvolver um SaaS em um final de semana?

Um único comando no terminal e pronto, você já tem seu projeto criado, com site, blog, central de ajuda, autenticação, onboarding, dashboard, emails... Para resumir, é assim que eu crio os meus SaaS em um Final de Semana.

Conheça minha estratégia

Você também pode gostar

Sistema de Assinaturas

E-mails Transacionais

Variáveis de Ambiente