Decorators de Classes e Métodos no TypeScript: Guia
⚡ Curso de TypeScript • Web-ZoneWare

Decorators de Classes e Métodos na Prática: Construindo Frameworks e Injetores de Dependência

Lição 38 de 50

Decorators de Classes e Métodos na Prática: Construindo Frameworks e Injetores de Dependência

Módulo 5: Utility Types, Decorators & Metaprogramação
Lição 38 de 50
Nível: Avançado
⏱ Tempo de Leitura e Prática: 30 minutos

Decorators de Classes e Métodos na Prática: Construindo Frameworks e Injetores de Dependência

💡
O Que Você Vai Aprender Hoje: Agora que compreendemos a especificação nativa dos Decorators no TypeScript 5.0+, é hora de construir arquiteturas do mundo real. Nesta aula prática e aprofundada, você aprenderá a criar Decorators de Classe que estendem construtores dinamicamente, injetores de dependência no padrão @Injectable, e Decorators de Métodos para autorização por papéis (RBAC – Role-Based Access Control) e tratamento global de exceções assíncronas!

1. Decorators de Classe: Transformando o Construtor

Um Decorator de Classe é aplicado imediatamente antes da declaração da classe. Ele recebe o construtor da classe e um ClassDecoratorContext. O recurso mais poderoso do decorator de classe é a possibilidade de retornar uma nova subclasse que substitui o construtor original, injetando novas propriedades ou comportamentos de inicialização:

TypeScript: Estendendo Classes com Decorator

TypeScript 31 linhas
// Tipo auxiliar genérico para qualquer construtor de classe instanciável
type ConstrutorGenerico = new (...args: any[]) => any;
 
// Decorator que injeta metadados de auditoria e data de criação em qualquer classe
function EntidadeAuditavel<T extends ConstrutorGenerico>(
    ConstrutorOriginal: T,
    context: ClassDecoratorContext
) {
    console.log(`[DECORATOR DE CLASSE] Decorando classe: ${context.name}`);
 
    // Retornamos uma classe derivada anônima que estende a original
    return class extends ConstrutorOriginal {
        public readonly dataCriacao = new Date();
        public readonly idInterno = `ENT-${Math.random().toString(36).substring(2, 9)}`;
 
        constructor(...args: any[]) {
            super(...args);
            console.log(`[INSTANCIAÇÃO] Nova entidade criada com ID: ${this.idInterno}`);
        }
    };
}
 
@EntidadeAuditavel
class ProdutoEstoque {
    constructor(public nome: string, public preco: number) {}
}
 
const prod = new ProdutoEstoque("Monitor Ultrawide 34"", 2890);
console.log("Nome do produto:", prod.nome);
// As propriedades injetadas existem na instância em runtime!
console.log("ID interno gerado:", (prod as any).idInterno);

2. Padrão Inversão de Controle (IoC) e @Injectable

Em frameworks enterprise como NestJS e Angular, as classes de serviço não são instanciadas manualmente com new. Em vez disso, um Contêiner de Injeção de Dependências (IoC Container) gerencia seus ciclos de vida. Criar um decorator @Injectable no TypeScript 5.0 é surpreendentemente limpo:

TypeScript: Contêiner IoC e Decorator @Injectable

TypeScript 35 linhas
// Registro central de instâncias únicas (Singleton Registry)
class ConteinerIoC {
    private static instancias: Map<Function, any> = new Map();
 
    public static registrar(servico: Function): void {
        console.log(`[IoC] Serviço registrado: ${servico.name}`);
    }
 
    public static resolver<T>(ServicoClasse: new () => T): T {
        if (!this.instancias.has(ServicoClasse)) {
            console.log(`[IoC] Criando instância única (Singleton) de: ${ServicoClasse.name}`);
            this.instancias.set(ServicoClasse, new ServicoClasse());
        }
        return this.instancias.get(ServicoClasse);
    }
}
 
// Decorator de classe que auto-registra o serviço no contêiner
function Injectable(target: Function, context: ClassDecoratorContext) {
    ConteinerIoC.registrar(target);
}
 
@Injectable
class ServicoEmail {
    public enviar(mensagem: string): void {
        console.log(`[EMAIL DISPARADO]: ${mensagem}`);
    }
}
 
// Resolução desacoplada pelo contêiner:
const servicoEmail1 = ConteinerIoC.resolver(ServicoEmail);
const servicoEmail2 = ConteinerIoC.resolver(ServicoEmail);
 
servicoEmail1.enviar("Bem-vindo à Web-ZoneWare Academy!");
console.log("Mesma instância?", servicoEmail1 === servicoEmail2); // true (Singleton perfeito!)

3. Decorators de Método para Segurança e RBAC (Role-Based Access Control)

Em sistemas web protegidos, nunca queremos espalhar verificações repetitivas como if (usuario.cargo !== "ADMIN") return 403; dentro de cada método de controlador. Os Decorators de Método permitem criar uma camada de guarda declarativa:

TypeScript: Decorator de Autorização @RequerPermissao

TypeScript 47 linhas
interface ContextoRequisicaoUsuario {
    usuarioId: string;
    roles: Array<"ADMIN" | "FINANCEIRO" | "OPERADOR" | "CLIENTE">;
}
 
// Decorator Factory que aceita as roles mínimas exigidas
function RequerPermissao(...rolesPermitidas: Array<"ADMIN" | "FINANCEIRO" | "OPERADOR" | "CLIENTE">) {
    return function (
        metodoOriginal: Function,
        context: ClassMethodDecoratorContext
    ) {
        const nomeMetodo = String(context.name);
 
        return function (this: any, ctxRequisicao: ContextoRequisicaoUsuario, ...restoArgs: any[]) {
            const temPermissao = ctxRequisicao.roles.some(r => rolesPermitidas.includes(r));
 
            if (!temPermissao) {
                const msg = `[ACESSO NEGADO] Usuário ${ctxRequisicao.usuarioId} sem privilégios para executar "${nomeMetodo}".`;
                console.error(msg);
                throw new Error(msg);
            }
 
            console.log(`[ACESSO AUTORIZADO] Executando ${nomeMetodo}...`);
            return metodoOriginal.call(this, ctxRequisicao, ...restoArgs);
        };
    };
}
 
class ControladorFinanceiro {
    @RequerPermissao("ADMIN", "FINANCEIRO")
    public emitirEstorno(ctx: ContextoRequisicaoUsuario, transacaoId: string): boolean {
        console.log(`Estorno da transação ${transacaoId} aprovado.`);
        return true;
    }
}
 
const controller = new ControladorFinanceiro();
 
// 1. Chamada autorizada (Usuário é FINANCEIRO):
controller.emitirEstorno({ usuarioId: "usr_99", roles: ["FINANCEIRO"] }, "TX-88001");
 
// 2. Chamada bloqueada (Usuário é apenas CLIENTE):
try {
    controller.emitirEstorno({ usuarioId: "usr_10", roles: ["CLIENTE"] }, "TX-88002");
} catch (e: any) {
    console.log("Operação bloqueada com segurança:", e.message);
}

4. Decorators Assíncronos e Tratamento Global de Erros

Operações de rede e banco de dados podem falhar por instabilidade de rede ou dados corrompidos. Podemos criar um decorator assíncrono @TratarErrosApi que intercepta Promises rejeitadas e padroniza a resposta de erro:

TypeScript: Interceptação Assíncrona com Decorator de Método

TypeScript 47 linhas
interface RespostaApiPadrao<T> {
    sucesso: boolean;
    dados?: T;
    erro?: string;
    timestamp: string;
}
 
function TratarErrosApi(
    metodoOriginal: Function,
    context: ClassMethodDecoratorContext
) {
    return async function (this: any, ...args: any[]): Promise<RespostaApiPadrao<any>> {
        try {
            const resultado = await metodoOriginal.call(this, ...args);
            return {
                sucesso: true,
                dados: resultado,
                timestamp: new Date().toISOString()
            };
        } catch (erro: any) {
            console.error(`[FALHA CAPTURADA EM ${String(context.name)}]:`, erro.message);
            return {
                sucesso: false,
                erro: erro.message ?? "Erro interno no servidor.",
                timestamp: new Date().toISOString()
            };
        }
    };
}
 
class ApiUsuariosController {
    @TratarErrosApi
    public async buscarUsuarioPorId(id: number) {
        if (id <= 0) {
            throw new Error("Identificador de usuário inválido.");
        }
        return { id, nome: "Renata Oliveira", ativo: true };
    }
}
 
const api = new ApiUsuariosController();
 
// Teste de sucesso:
api.buscarUsuarioPorId(42).then(resp => console.log("Resposta 1:", resp));
 
// Teste com erro tratado automaticamente sem quebrar o processo:
api.buscarUsuarioPorId(-1).then(resp => console.log("Resposta 2 (Tratada):", resp));

5. Exemplo Enterprise: Mini-Framework de Rotas Estilo NestJS

Vejamos a união arquitetural perfeita: combinamos Decorators de Classe (@Controller) com Decorators de Método (@Get e @Post) para construir um sistema de roteamento HTTP declarativo:

TypeScript: Roteamento Declarativo com Decorators TS 5.0

TypeScript 56 linhas
interface DefinicaoRota {
    metodoHttp: "GET" | "POST" | "PUT" | "DELETE";
    caminhoCompleto: string;
    handlerNome: string;
    acao: Function;
}
 
// Registro global de rotas da aplicação
const tabelaRotas: DefinicaoRota[] = [];
 
// 1. Decorator de Classe para o prefixo do Controller
function Controller(prefixoBase: string) {
    return function (target: Function, context: ClassDecoratorContext) {
        // Vincula o prefixo base a todas as rotas registradas por esta classe
        console.log(`[ROTA CONTROLLER] Registrado prefixo: ${prefixoBase}`);
    };
}
 
// 2. Decorator Factory de Método para requisições GET
function Get(caminho: string) {
    return function (metodoOriginal: Function, context: ClassMethodDecoratorContext) {
        const nomeMetodo = String(context.name);
        
        // Registra a rota imediatamente na inicialização
        context.addInitializer(function () {
            tabelaRotas.push({
                metodoHttp: "GET",
                caminhoCompleto: caminho,
                handlerNome: nomeMetodo,
                acao: metodoOriginal
            });
        });
 
        return metodoOriginal;
    };
}
 
// 3. Aplicação em uma classe de serviço web:
@Controller("/api/v1/pedidos")
class PedidosController {
    @Get("/listar")
    public listarTodosPedidos(): string[] {
        return ["PED-01", "PED-02", "PED-03"];
    }
 
    @Get("/estatisticas")
    public obterEstatisticas(): { totalVendas: number } {
        return { totalVendas: 145000 };
    }
}
 
// Ao instanciar a classe, os initializers registram as rotas na tabela:
const controladorPedidos = new PedidosController();
 
console.log("Rotas HTTP Registradas no Sistema:");
console.table(tabelaRotas.map(r => ({ Metodo: r.metodoHttp, Rota: r.caminhoCompleto, Handler: r.handlerNome })));
⚗️ Teste no Playground IDE Web-ZoneWare
Compile Decorators de Classes e Métodos, teste interceptadores RBAC e veja roteamento declarativo ao vivo.

Abrir Playground TypeScript →

6. Armadilhas Comuns e Boas Práticas Sênior

  • Preservação de Subclasses e Prototype Chain: Ao retornar uma subclasse em um decorator de classe, garanta que ela use extends ConstrutorOriginal e invoque super(...args) para não quebrar testes com o operador instanceof.
  • Não Perca o Retorno em Métodos Assíncronos: Se o método decorado for assíncrono, a função wrapper de substituição deve ser marcada com async e utilizar await ao chamar metodoOriginal.call(this, ...args). Omitir o await pode resultar em vazamento de Promises não tratadas.
  • Evite Efeitos Colaterais Excessivos em Tempo de Carregamento: A execução dos decorators ocorre assim que a classe é avaliada pelo interpretador (tempo de importação do módulo). Evite disparar conexões pesadas de rede durante a anotação; prefira usar context.addInitializer() para adiar a execução para o momento da instanciação.

Resumo da Lição 38

  • Decorators de Classe podem inspecionar o construtor ou retornar uma nova subclasse derivada para injetar propriedades adicionais.
  • São a base do padrão Inversão de Controle (IoC) e injeção de dependências (@Injectable).
  • Decorators de Método interceptam a execução original, viabilizando autenticação, autorização por papéis (RBAC) e telemetria declarativa.
  • Permitem tratamento assíncrono padronizado de erros, envelopando chamadas em blocos try/catch transparentes.
  • A composição de decorators de classe e método viabiliza o desenvolvimento de mini-frameworks de roteamento no estilo NestJS.

📝 Exercício Prático Desafiador da Lição 38

1. Crie um Decorator de Método chamado @Memoize que crie um cache em memória para os resultados de um método com base nos argumentos recebidos. Se o método for chamado novamente com os mesmos parâmetros, ele deve retornar imediatamente o valor memorizado sem reexecutar o cálculo!

2. Aplique seu decorator em um método que calcula o n-ésimo número da sequência de Fibonacci e comprove no console a redução drástica de execuções.

🛠️ Laboratório Prático & Prática Imediata

Aplique o que você aprendeu nesta lição

Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.

💻 Desenvolvedor & Código

Editor de Códigos Web Online

Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.

Abrir Ferramenta Online
⚡ Live Code Studio

Playground Web Online

Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.

⚡ Codificar no Playground IDE
Foto de Web-Zoneware
✓ Verificado
🎓 Tutor & Coordenador da Web Academy

Web-Zoneware

Tutor Técnico & Desenvolvedor Full-Stack

Desenvolvedor web e instrutor focado na formação prática de novos programadores. Defensor ferrenho de código semântico, arquitetura limpa e acessibilidade W3C/WCAG, dedicando-se a construir cursos estruturados em metodologia passo a passo com execução ao vivo no Playground IDE.

Especialidades: HTML5 Semântico CSS3 & Flexbox/Grid JavaScript Moderno Acessibilidade WCAG 2.2 Didática Prática
Rolar para cima