3. Capítulo 2 - Introdução ao [NestJS]
3.1. Fontes
Este capítulo se baseia nas seguintes fontes:
- o site oficial do [NestJS]: nestjs.com e sua documentação docs.nestjs.com;
- o repositório do framework no GitHub: github.com/nestjs/nest.
3.2. O papel do [NestJS] em uma aplicação web
O [NestJS] é um framework Node.js escrito em TypeScript, concebido para construir o lado servidor de uma aplicação web — na maioria das vezes uma API REST (JSON). Ele não reinventa o tratamento do protocolo HTTP: por padrão, apoia-se no Express, um framework Node.js mais rudimentar, responsável por receber as requisições HTTP brutas e respondê-las. O [NestJS] se coloca sobre essa base, oferecendo uma organização de código que nem o Node.js nem o Express impõem por si sós: divisão em módulos, controllers e serviços; injeção de dependência; decoradores…
Sua arquitetura é fortemente inspirada no [Angular] (decoradores, módulos, injeção de dependência) — uma semelhança que nos será muito útil no Capítulo 4, quando encontrarmos exatamente os mesmos conceitos no lado do cliente.
O [NestJS] é concebido principalmente para gerar respostas JSON: por padrão, tudo o que um método de controller retorna é automaticamente convertido em JSON e enviado ao cliente, sem nenhuma configuração especial.
3.3. O modelo de desenvolvimento do [NestJS]
Três conceitos estruturam uma aplicação [NestJS]:
- módulos (decorador @[Module]): um módulo agrupa um conjunto de funcionalidades relacionadas — declara quais controllers e serviços lhe pertencem, de quais outros módulos precisa e o que disponibiliza aos demais. Uma aplicação [NestJS] sempre parte de um módulo raiz, [AppModule], que reúne todos os outros módulos do projeto;
- controllers (decorador @[Controller]): um controller é o ponto de entrada da aplicação — uma classe em que cada método recebe as requisições HTTP correspondentes a uma URL específica e devolve uma resposta ao cliente;
- providers (decorador @[Injectable]): um provider é uma classe comum, normalmente responsável pela lógica de negócio ou pelo acesso a dados, que o [NestJS] pode criar e fornecer automaticamente (isto é, “injetar”) a qualquer controller ou serviço que precise dela.
Na prática, uma classe que precisa de um provider simplesmente o declara como parâmetro de seu construtor — o [NestJS] cria a instância necessária e a repassa automaticamente, sem que você precise escrever new: isso se chama injeção de dependência por construtor, prática quase sempre usada no NestJS.
3.4. Um primeiro exemplo: o miniprojeto “hello”
Para fixar esses três conceitos, eis um projeto [NestJS] muito pequeno, independente do estudo de caso (uma única rota /hello), que você pode criar com (digite estes comandos em uma pasta vazia aberta no VSCode [File/Open Folder]. Esses comandos criam uma pasta chamada [hello-nest]):

Esse comando gera um projeto contendo os seguintes arquivos essenciais: [src/main.ts], src/app.module.ts, src/app.controller.ts, src/app.service.ts. Só esses quatro arquivos já ilustram a arquitetura de uma aplicação [NestJS]: um ponto de entrada ([main.ts]), um módulo raiz (app.module.ts), um controller (app.controller.ts) e um serviço (app.service.ts).
3.4.1. O serviço
// src/app.service.ts
import { Injectable } from '@nestjs/common';
@Injectable()
export class AppService {
getHello(): string {
return 'Hello World!';
}
}
- linha 2: cada elemento usado é importado explicitamente; aqui, [Injectable] é importado de [@nestjs/common], o módulo que contém a maior parte dos decoradores e das classes utilitárias do [NestJS];
- linha 4: um decorador é uma anotação colocada imediatamente acima de uma classe, método ou parâmetro do TypeScript (precedida pelo símbolo @), que modifica ou enriquece seu comportamento sem alterar seu código — o mecanismo sobre o qual se apoia praticamente todo o vocabulário do NestJS. @[Injectable]() marca essa classe como um provider: o [NestJS] a criará por conta própria e a fornecerá automaticamente a qualquer outra classe que a solicite em seu construtor, sem que seja preciso escrever new [AppService]();
- linha 6: : string declara o tipo de retorno — um recurso específico do TypeScript, ausente no JavaScript.
3.4.2. O controller
- linha 5: @Controller() decora a classe seguinte para torná-la um controller: o NestJS lhe enviará as requisições HTTP correspondentes às suas rotas. O argumento entre parênteses é um prefixo opcional adicionado ao início de todas as rotas da classe — aqui está vazio: a rota “hello” responde, portanto, diretamente em /hello;
- linha 7: o construtor declara um parâmetro chamado appService do tipo [AppService], precedido do modificador TypeScript private readonly, que, em uma única linha, o declara E o registra como propriedade da instância (this.appService). O [NestJS] determina que o controller precisa de um [AppService], cria uma instância dele (uma única instância, compartilhada por toda a aplicação) e o fornece automaticamente aqui: é a injeção de dependência por construtor mencionada anteriormente;
- linha 9: [@Get]('hello') associa o método seguinte à rota HTTP GET /hello: é esse decorador que torna a ação acessível no endereço testável http://localhost:3000/hello depois que o servidor é iniciado. Outros decoradores têm o mesmo papel para os demais verbos HTTP: @[Post](), @Put(), @Delete(), @Patch() (usaremos @[Post]() no estudo de caso, para /addAppointment e /deleteAppointment). Observe que, na linha 10, o nome do método [getHello] é irrelevante. Poderia ser qualquer nome;
- Linha 11: o controller delega o trabalho ao serviço injetado em vez de codificar ele mesmo a resposta: permanece uma simples camada de roteamento, enquanto a lógica de negócio reside no serviço — um princípio que veremos em maior escala no estudo de caso do Capítulo 3.
3.4.3. O módulo
- linha 6: @[Module]({...}) decora a classe seguinte para transformá-la em um módulo: ele agrupa uma parte coerente da aplicação e declara, no objeto passado como argumento, o que a compõe. Quatro propriedades são possíveis: controllers (os controllers expostos por este módulo), providers (os serviços fornecidos por este módulo, disponíveis para injeção dentro dele), imports (os outros módulos dos quais este depende) e exports (os providers que este módulo disponibiliza aos módulos que o importam);
- Sem a linha `controllers: [AppController]`, o `[NestJS]` ignoraria esse controller e suas rotas não responderiam a nenhuma requisição; sem `providers: [AppService]`, a injeção de dependência do controller falharia na inicialização.
3.4.4. Execução
No VSCode, em um terminal aberto na raiz da pasta [hello-nest], digite o seguinte comando:
Ao abrir http://localhost:3000/hello em um navegador, você obtém a seguinte resposta:

3.5. Providers e injeção de dependência
Uma classe anotada com @[Injectable]() é um provider: o [NestJS] sabe instanciá-la e injetá-la automaticamente onde for solicitada em um construtor, desde que apareça no array providers de um módulo. Por padrão, um provider do [NestJS] é um singleton: uma única instância é criada quando a aplicação inicia, e essa mesma instância é compartilhada por todos os componentes que precisam dela — um ponto importante para entender o papel do serviço [ApplicationModelService] no estudo de caso (Capítulo 3), que mantém dados em cache quando o servidor inicia.
3.6. Os outros decoradores que aparecerão no estudo de caso
Decorador | Papel |
associa um método de controller a uma rota HTTP | |
recupera um segmento variável da URL, por exemplo /getDoctorById/:id | |
recupera o corpo JSON de uma requisição POST, desserializado em uma classe | |
declara um provider (serviço, DAO…) | |
declara um módulo, um conjunto de controllers e providers |
Esses decoradores serão explicados em detalhes, um a um, no ponto exato em que aparecem no código do servidor [RdvMedecins] (Capítulo 3).