Metaprogramação com reflect-metadata: Injeção de Dependências e Reflection no TypeScript
Metaprogramação com reflect-metadata: Injeção de Dependências e Reflection no TypeScript
reflect-metadata e a API de Reflection. Você aprenderá como o compilador pode preservar tipos em tempo de execução e como construir um Contêiner de Injeção de Dependências recursivo automático!
📑 Índice do Conteúdo
1. O Enigma do Apagamento de Tipos (Type Erasure) e a Necessidade de Reflection
Como aprendemos desde o Módulo 1, o TypeScript adota uma regra fundamental de compilação conhecida como Type Erasure (Apagamento de Tipos): quando seu código .ts é transpilado para .js puro, todas as interfaces, anotações de tipos e generics são completamente descartados.
Isso levanta uma questão intrigante para quem desenvolve backends robustos: “Como frameworks como o NestJS conseguem olhar para o construtor de uma classe e saber exatamente quais dependências devem ser instanciadas e injetadas automaticamente, sem que o programador precise passar configurações manuais?”
A resposta é a Metaprogramação por Reflexão (Reflection) viabilizada pela biblioteca reflect-metadata!
2. A Flag emitDecoratorMetadata no tsconfig.json
Para que o TypeScript preserve metadados sobre tipos em tempo de compilação, habilitamos uma diretiva especial em nosso arquivo tsconfig.json:
{
"compilerOptions": {
"target": "ES2022",
"experimentalDecorators": true,
"emitDecoratorMetadata": true
}
}
Reflect em tempo de execução, você deve instalar o pacote via npm install reflect-metadata e importá-lo uma única vez no arquivo principal da sua aplicação (ex: import "reflect-metadata"; no topo do main.ts ou index.ts).
3. As Três Chaves Mágicas Emitidas pelo Compilador
Quando emitDecoratorMetadata: true está ativo e aplicamos um decorator a uma classe ou método, o compilador do TypeScript gera automaticamente três entradas de metadados sob o capô:
| Chave de Metadado | O Que Ela Revela em Runtime | Exemplo de Retorno |
|---|---|---|
"design:type" |
O construtor do tipo da propriedade ou membro decorado. | String, Number, Date, Object |
"design:paramtypes" |
Um array com os construtores de todos os parâmetros recebidos. | [ServicoAuth, RepositorioUsuario] |
"design:returntype" |
O construtor do tipo do valor retornado pelo método. | Promise, Boolean, Object |
4. A API Fundamental de reflect-metadata
O objeto global Reflect passa a expor funções para gravar e consultar metadados arbitrários em classes e membros:
// 1. Gravando metadado customizado em uma classe:
Reflect.defineMetadata("papelMinimo", "ADMIN", RelatorioFinanceiro);
// 2. Lendo o metadado gravado:
const papel = Reflect.getMetadata("papelMinimo", RelatorioFinanceiro); // ___WZW_STR_1___
// 3. Verificando se o metadado existe:
const existe = Reflect.hasMetadata("papelMinimo", RelatorioFinanceiro); // true
5. Construindo um Contêiner IoC com Auto-Wiring Recursivo
Agora vamos ao ápice da engenharia: criaremos um Contêiner de Injeção de Dependências (IoC Container) corporativo com resolução recursiva automática (Auto-Wiring). O contêiner inspecionará os parâmetros do construtor de qualquer classe via design:paramtypes e instanciará todas as suas dependências em cascata:
// Tipo para qualquer construtor instanciável
type TipoConstrutor<T = any> = new (...args: any[]) => T;
// Decorator que marca a classe como gerenciável pelo contêiner
function Injectable(): ClassDecorator {
return (target: Function) => {
// A presença do decorator força o TS a emitir os metadados design:paramtypes!
};
}
class AutoIoCContainer {
// Cache de Singletons já instanciados
private static instancias = new Map<TipoConstrutor, any>();
public static resolver<T>(Alvo: TipoConstrutor<T>): T {
// 1. Se já foi instanciado, retorna a instância em cache (Singleton)
if (this.instancias.has(Alvo)) {
return this.instancias.get(Alvo);
}
// 2. Lê os tipos dos parâmetros exigidos pelo construtor da classe
const parametrosTipos: TipoConstrutor[] =
Reflect.getMetadata("design:paramtypes", Alvo) || [];
console.log(`[IoC] Resolvendo ${Alvo.name}... Dependências detectadas:`,
parametrosTipos.map(p => p.name));
// 3. Resolve recursivamente cada dependência necessária
const dependenciasResolvidas = parametrosTipos.map(dep => this.resolver(dep));
// 4. Cria a nova instância injetando as dependências prontas
const novaInstancia = new Alvo(...dependenciasResolvidas);
// 5. Guarda em cache e retorna
this.instancias.set(Alvo, novaInstancia);
return novaInstancia;
}
}
6. Exemplo Enterprise: Arquitetura de 3 Camadas Resolvida Automaticamente
Vamos testar nosso contêiner com uma arquitetura real de três camadas (Log > Banco > Repositório > Serviço). Repare que não precisamos configurar manualmente nenhuma injeção: o contêiner faz tudo sozinho!
// 1. Serviço de Log (Sem dependências)
@Injectable()
class ServicoLogger {
public registrar(msg: string): void {
console.log(`[LOG CORPORATIVO - ${new Date().toLocaleTimeString()}]: ${msg}`);
}
}
// 2. Camada de Banco de Dados (Depende de ServicoLogger)
@Injectable()
class ConexaoBancoDados {
constructor(private logger: ServicoLogger) {
this.logger.registrar("Conexão com PostgreSQL estabelecida com sucesso.");
}
public consultar(sql: string): any[] {
this.logger.registrar(`Executando query: ${sql}`);
return [{ id: 1, nome: "Web-ZoneWare", status: "ATIVO" }];
}
}
// 3. Repositório de Dados (Depende de ConexaoBancoDados e ServicoLogger)
@Injectable()
class UsuarioRepositorio {
constructor(
private banco: ConexaoBancoDados,
private logger: ServicoLogger
) {}
public buscarTodos() {
this.logger.registrar("Buscando registros na tabela usuarios...");
return this.banco.consultar("SELECT * FROM usuarios WHERE ativo = true;");
}
}
// 4. Serviço de Domínio de Alto Nível (Depende de UsuarioRepositorio e ServicoLogger)
@Injectable()
class UsuarioControllerService {
constructor(
private repo: UsuarioRepositorio,
private logger: ServicoLogger
) {}
public listarUsuariosAtivos() {
this.logger.registrar("Iniciando listagem de usuários ativos.");
return this.repo.buscarTodos();
}
}
// =======================================================
// A MÁGICA DO AUTO-WIRING EM AÇÃO:
// Pedimos apenas o controlador de topo. O Contêiner resolve toda a árvore!
// =======================================================
console.log("=== INICIANDO RESOLUÇÃO DE DEPENDÊNCIAS ===");
const appService = AutoIoCContainer.resolver(UsuarioControllerService);
const resultado = appService.listarUsuariosAtivos();
console.log("Resultado obtido:", resultado);
7. Armadilhas Comuns e Boas Práticas Sênior
- Interfaces Não Existem em Runtime: Se o construtor da sua classe receber uma
interfaceem vez de uma classe concreta (ex:constructor(private repo: IUsuarioRepo)), o TypeScript emitiráObjectemdesign:paramtypes. Para injetar por abstração de interface, utilize tokens de injeção nomeados (como@Inject("IUsuarioRepo")). - Dependências Circulares (Circular Dependencies): Se a classe
Adepender da classeB, e a classeBdepender da classeA, a resolução recursiva entrará em loop infinito. Frameworks como NestJS utilizam a funçãoforwardRef(() => Classe)para contornar essa situação. - Conexão com o Futuro: A especificação de Decorator Metadata nativa está avançando no TC39 Stage 3 (via
context.metadata). Conhecerreflect-metadatagarante compatibilidade absoluta com os maiores frameworks corporativos atuais enquanto você se prepara para as futuras evoluções da linguagem.
Resumo da Lição 40 e Conclusão do Módulo 5 (Marco de 80%!)
- Reflection permite que o código inspecione tipos e anotações em tempo de execução.
- A flag
emitDecoratorMetadatainstrui o compilador a salvar os tipos em metadados (design:type,design:paramtypes,design:returntype). - O pacote
reflect-metadatafornece os métodosdefineMetadataegetMetadata. - É a engrenagem oculta que alimenta a Injeção de Dependências automática (IoC) em NestJS, Angular e TypeORM.
- Com esta aula, dominamos completamente Utility Types, Decorators e Metaprogramação Avançada!
📝 Exercício Prático Desafiador da Lição 40
1. Crie uma anotação customizada de validação chamada @TamanhoMinimo(caracteres: number) que utilize Reflect.defineMetadata("validacao:minimo", caracteres, target, propertyKey) em uma propriedade de classe.
2. Crie uma função validadora global validarEntidade(instancia: any): string[] que leia todos os metadados de validação das propriedades da instância e retorne um array com as mensagens de erro caso algum campo de texto não atinja o tamanho mínimo estipulado.
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