Decorators de Classes e Métodos na Prática: Construindo Frameworks e Injetores de Dependência
Decorators de Classes e Métodos na Prática: Construindo Frameworks e Injetores de Dependência
@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!
📑 Índice do Conteúdo
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:
// 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:
// 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:
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:
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:
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 })));
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 ConstrutorOriginale invoquesuper(...args)para não quebrar testes com o operadorinstanceof. - 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
asynce utilizarawaitao chamarmetodoOriginal.call(this, ...args). Omitir oawaitpode 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/catchtransparentes. - 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.
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.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground 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