Skip to content

3. Capítulo 2 - Introdução ao [NestJS]

3.1. Fontes

Este capítulo se baseia nas seguintes fontes:

3.2. O papel do [NestJS] em uma aplicação web

[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á útil no Capítulo 4, quando encontrarmos exatamente os mesmos conceitos no lado do cliente.

O [NestJS] é concebido principalmente para produzir 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 reúne um conjunto de funcionalidades inter-relacionadas; ele 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, em geral responsável pela lógica de negócio ou pelo acesso a dados, que o [NestJS] pode criar e fornecer (isto é, “injetar”) automaticamente 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 passa automaticamente, sem que você precise escrever new. Isso se chama injeção de dependência por construtor, prática quase universal no NestJS.

3.4. Um primeiro exemplo: o miniprojeto “hello”

Para consolidar esses três conceitos, eis um projeto [NestJS] bem 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]):

1
2
3
4
npm install -g [@nestjs/cli]
nest new hello-nest
cd hello-nest
npm run start:dev

Image

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. Esses quatro arquivos bastam para ilustrar 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 utilizado é importado explicitamente; aqui, [Injectable] é importado de [@nestjs/common], o módulo que contém a maioria dos decoradores e classes utilitárias do [NestJS];
  • linha 4: um decorador é uma anotação colocada imediatamente acima de uma classe, método ou parâmetro TypeScript (precedida do símbolo @), que modifica ou enriquece seu comportamento sem alterar seu código; é o mecanismo no qual se baseia 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 peça em seu construtor, sem que seja preciso escrever new [AppService]();
  • linha 6: : string declara o tipo de retorno, um recurso específico do TypeScript que não existe em JavaScript.

3.4.2. O controller

// src/app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service.js';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) { }

  @Get('hello')
  getHello(): string {
    return this.appService.getHello();
  }
}
  • linha 5: @Controller() decora a classe seguinte para torná-la um controller: o NestJS enviará a ela as requisições HTTP correspondentes às suas rotas. O argumento entre parênteses é um prefixo opcional acrescentado ao início de todas as rotas da classe; aqui ele 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 como parâmetro 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 a 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 quando o servidor estiver em execução. Outros decoradores desempenham 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 fica no serviço, princípio que veremos, em maior escala, no estudo de caso do Capítulo 3.

3.4.3. O módulo

// src/app.module.ts
import { Module } from '@nestjs/common';
import { AppController } from './app.controller.js';
import { AppService } from './app.service.js';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}
  • 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

Com o VSCode, em um terminal aberto na raiz da pasta [hello-nest], digite o seguinte comando:

npm run start:dev

Ao abrir http://localhost:3000/hello em um navegador, você obtém a seguinte resposta:

Image

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 ela 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, 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 aparecem no estudo de caso

Decorador
Papel
[@Get](url), [@Post](url)
associa um método de controller a uma rota HTTP
[@Param]('x')
obtém um segmento variável da URL, por exemplo /getDoctorById/:id
[@Body]()
obtém o corpo JSON de uma requisição POST, desserializado em uma classe
[@Injectable]()
declara um provider (serviço, DAO…)
[@Module]({...})
declara um módulo, um conjunto de controllers e providers

Esses decoradores serão explicados em detalhe, um a um, no ponto exato em que aparecem no código do servidor [RdvMedecins] (Capítulo 4).