Leodario.com

Leodario.com – Tudo sobre Tecnologia

Aula 45 – API JavaScript, Node.js e Express – Express Generator – Scaffolding automático

Imagem destacada da aula de API

Introdução (3 min)

Prezados alunos, sejam bem-vindos à nossa Aula 45! Hoje, desvendaremos um dos segredos para a agilidade e a consistência no desenvolvimento de APIs modernas: o Express Generator. Imagine que você está prestes a construir uma casa. Você poderia começar do zero, desenhando cada parede, cada viga, cada instalação. Ou, você poderia utilizar um kit de construção pré-fabricado, um esqueleto robusto que já oferece a fundação e a estrutura principal, permitindo que você se concentre nos detalhes e na personalização. É exatamente isso que o Express Generator proporciona no universo do desenvolvimento de aplicações web e APIs com Node.js.

No cenário das APIs modernas, onde a velocidade de entrega e a padronização são vitais, iniciar um projeto a partir de uma estrutura bem definida e testada é um divisor de águas. Ele nos poupa do trabalho repetitivo de configurar arquivos básicos, diretórios e dependências, permitindo que nos dediquemos imediatamente à lógica de negócio que realmente agrega valor. Em vez de “reinventar a roda” a cada novo projeto, utilizamos um molde de alta qualidade.

Nesta aula prática, você irá aprender a gerar, configurar e executar um esqueleto de aplicação Express.js completo e pronto para expansão. Veremos como essa ferramenta se encaixa perfeitamente no ecossistema Node.js e Express, atuando como um catalisador para a criação de serviços web e APIs robustas, prontas para serem escaladas e mantidas com excelência.

Conceito Fundamental (7 min)

O conceito central que abordaremos é o de scaffolding automático. Em desenvolvimento de software, scaffolding refere-se à geração automática de um esqueleto de projeto, incluindo arquivos, pastas e configurações básicas. O Express Generator é a ferramenta oficial de scaffolding para aplicações Express.js, um framework web para Node.js.

Ele opera como uma ferramenta de linha de comando (CLI – Command Line Interface) que, ao ser executada, constrói uma estrutura de diretórios e arquivos padronizada. Esta estrutura inclui:

    • Um arquivo principal de aplicação (app.js), onde as configurações do Express são definidas.
    • Um diretório para rotas (routes/), separando a lógica de endpoint.
    • Um diretório para visualizações (views/), caso sua aplicação sirva páginas web.
    • Um diretório para recursos estáticos (public/), como CSS, JavaScript do lado do cliente e imagens.
    • Um arquivo package.json, listando as dependências do projeto e scripts de execução.
    • Um ponto de entrada para o servidor (bin/www), que inicializa a aplicação.

A terminologia da indústria é clara: estamos utilizando um gerador de boilerplate (código padrão repetitivo) que automatiza a criação do esqueleto de um projeto. Isso é particularmente útil para MVPs (Minimum Viable Products), prototipagem rápida e para garantir a consistência em projetos desenvolvidos por equipes, seguindo as melhores práticas do Express desde o primeiro momento.

Casos de Uso Reais em Produção:

    • Início Rápido de Novas APIs: Equipes podem rapidamente spin up novos microsserviços ou APIs, já com uma base sólida.
    • Padronização de Projetos: Garante que todos os novos projetos sigam uma estrutura uniforme, facilitando a manutenção e a colaboração.
    • Educação e Treinamento: Excelente para quem está aprendendo Express, pois fornece um projeto funcional para explorar.

Integração com Outras Tecnologias:

O Express Generator fornece a base. Sobre ela, você pode integrar facilmente:

    • Bancos de dados (MongoDB com Mongoose, PostgreSQL com Sequelize, etc.).
    • Sistemas de autenticação (JWT, OAuth).
    • Ferramentas de ORM/ODM.
    • Bibliotecas de validação de entrada (Joi, Express-Validator).
    • Sistemas de logging (Winston, Morgan).

Vantagens e Desvantagens:

    • Vantagens:
      • Aceleração: Reduz significativamente o tempo de configuração inicial.
      • Padronização: Promove uma estrutura de projeto consistente.
      • Melhores Práticas: Inclui configurações recomendadas para Express.js.
      • Menos Erros: Evita erros comuns de configuração manual.
    • Desvantagens:
      • Curva de Aprendizagem: Para iniciantes, pode ser necessário entender a estrutura gerada antes de modificá-la.
      • Código Adicional: Para projetos muito pequenos, algumas partes geradas (como um view engine) podem ser desnecessárias e precisar de remoção manual.
      • Opinião: Impõe uma certa estrutura, o que pode não agradar a todos os desenvolvedores que preferem total liberdade.

Implementação Prática (10 min)

Agora, vamos colocar a mão na massa e gerar nosso primeiro projeto Express.js com o Express Generator. Siga os passos cuidadosamente.

Passo 1: Instalação do Express Generator

Primeiro, precisamos instalar o Express Generator globalmente em sua máquina. Isso nos possibilita usá-lo em qualquer diretório via linha de comando.

npm install -g express-generator

Este comando instala o pacote express-generator de forma global, o que significa que o executável express estará disponível em seu terminal.

Passo 2: Gerando um Novo Projeto Express.js

Vamos criar uma nova aplicação. Para uma API RESTful pura, que não serve páginas web renderizadas no servidor, podemos usar a opção --no-view. Vamos chamar nossa aplicação de minha-api-enterprise.

express --no-view minha-api-enterprise

Este comando fará o scaffolding do projeto. A opção --no-view é essencial para quem desenvolve APIs, pois evita a inclusão de um motor de templates (como Pug ou EJS), simplificando a estrutura para nosso propósito principal.

Passo 3: Navegando e Instalando Dependências

Após a geração, entre no diretório do seu novo projeto e instale as dependências listadas no package.json.

cd minha-api-enterprise
npm install

O npm install baixará e instalará todos os módulos Node.js necessários para que sua aplicação Express funcione corretamente (como o próprio express, morgan para logging, e outros middlewares).

Passo 4: Executando a Aplicação

Agora, podemos iniciar o servidor web.

npm start

Você deverá ver uma mensagem no terminal indicando que o servidor está rodando. Por padrão, ele tenta escutar na porta 3000. Abra seu navegador em http://localhost:3000 e você verá uma resposta “Cannot GET /”, pois não há rota definida para a raiz.

Análise da Estrutura Gerada (minha-api-enterprise):

minha-api-enterprise/
├── bin/
│   └── www               # Ponto de entrada do servidor e configuração da porta
├── public/               # Diretório para arquivos estáticos (CSS, JS cliente, imagens) - vazio com --no-view, mas permanece
├── routes/
│   ├── index.js          # Exemplo de rota, para a URL '/'
│   └── users.js          # Exemplo de rota, para a URL '/users'
├── app.js                # Arquivo principal: Configura o Express, middlewares e rotas
├── package.json          # Metadados do projeto e dependências
└── package-lock.json     # Registro exato das dependências instaladas

Configurações Específicas para HostGator Plano M:

Para um ambiente de produção como o HostGator Plano M, onde o ambiente de execução pode impor a porta em que sua aplicação deve rodar, é imprescindível configurar a porta dinamicamente. O Express Generator já lida com isso de forma excelente no arquivo bin/www:

// bin/www - Trecho relevante
var port = normalizePort(process.env.PORT || '3000');
app.set('port', port);
// ...
var server = http.createServer(app);
server.listen(port);
// ...

Observe process.env.PORT || '3000'. Isso significa que sua aplicação tentará usar a porta definida pela variável de ambiente PORT (que será configurada pelo seu provedor de hospedagem, como a HostGator), ou, se essa variável não existir (como em seu ambiente de desenvolvimento local), ela padronizará para a porta 3000. Essa é uma melhor prática enterprise crucial para a portabilidade da sua aplicação.

Modificando e Adicionando Rotas:

Vamos adicionar uma rota simples para nossa API no arquivo routes/index.js para retornar um JSON. Isso é mais adequado para APIs RESTful do que a resposta padrão gerada.

// routes/index.js - Modificado para uma API
var express = require('express');
var router = express.Router();


/ GET home page. /
router.get('/', function(req, res, next) {
  // Em vez de renderizar uma view, enviamos uma resposta JSON
  res.status(200).json({
    message: 'Bem-vindo à sua API Express Gerada!',
    version: '1.0.0',
    status: 'online'
  });
});


module.exports = router;

Agora, vamos criar uma nova rota para “produtos” para demonstrar como expandir a API.

Crie um novo arquivo routes/products.js:

// routes/products.js
var express = require('express');
var router = express.Router();


// Dados de exemplo (simulando um banco de dados)
const products = [
  { id: 1, name: 'Notebook Dell', price: 5500.00 },
  { id: 2, name: 'Monitor LG Ultrawide', price: 1800.00 },
  { id: 3, name: 'Teclado Mecânico HyperX', price: 450.00 }
];


/ GET all products listing. /
router.get('/', function(req, res, next) {
  // Exemplo de logging profissional
  console.log('Requisição recebida para /products');
  res.status(200).json(products);
});


/ GET a single product by ID. /
router.get('/:id', function(req, res, next) {
  const productId = parseInt(req.params.id);
  // Validação de entrada robusta
  if (isNaN(productId)) {
    return res.status(400).json({ error: 'ID de produto inválido. Deve ser um número inteiro.' });
  }


  const product = products.find(p => p.id === productId);


  if (product) {
    res.status(200).json(product);
  } else {
    // Error handling impressionante: Retorna status 404 e mensagem clara
    res.status(404).json({ error: Produto com ID ${productId} não encontrado. });
  }
});


module.exports = router;

Para que esta nova rota seja acessível, precisamos registrá-la em app.js. Abra app.js e adicione a nova rota:

// app.js - Trecho relevante para adicionar a rota de produtos
var express = require('express');
var path = require('path');
var cookieParser = require('cookie-parser');
var logger = require('morgan'); // Para logging de requisições


var indexRouter = require('./routes/index'); // Importa a rota index
var usersRouter = require('./routes/users'); // Importa a rota users
var productsRouter = require('./routes/products'); // <-- Importa a nova rota de produtos


var app = express();


app.use(logger('dev')); // Middleware de logging
app.use(express.json()); // Habilita o parsing de JSON no corpo das requisições
app.use(express.urlencoded({ extended: false }));
app.use(cookieParser());
app.use(express.static(path.join(__dirname, 'public'))); // Serve arquivos estáticos


app.use('/', indexRouter); // Usa a rota index para '/'
app.use('/users', usersRouter); // Usa a rota users para '/users'
app.use('/products', productsRouter); // <-- Usa a nova rota de produtos para '/products'


// Middleware para tratamento de erros 404 (recurso não encontrado)
app.use(function(req, res, next) {
  res.status(404).json({ error: 'Recurso não encontrado. Verifique a URL.' });
});


// Middleware genérico de tratamento de erros
app.use(function(err, req, res, next) {
  // Apenas em desenvolvimento, detalhamos o erro. Em produção, logamos e retornamos uma mensagem genérica.
  res.locals.message = err.message;
  res.locals.error = req.app.get('env') === 'development' ? err : {};


  console.error('Erro na aplicação:', err); // Logging profissional do erro


  // Renderiza a página de erro ou envia um JSON de erro
  res.status(err.status || 500).json({
    error: 'Ocorreu um erro interno no servidor.',
    details: req.app.get('env') === 'development' ? err.message : undefined
  });
});


module.exports = app;

Reinicie sua aplicação (Ctrl+C e depois npm start).

Agora você pode testar:

Melhores Práticas Enterprise:

    • Variáveis de Ambiente: Use dotenv para gerenciar variáveis de ambiente localmente. Crie um arquivo .env na raiz do projeto e configure, por exemplo, PORT=3001. Lembre-se de adicionar .env ao seu .gitignore. Para usar dotenv, instale-o (npm install dotenv) e adicione require('dotenv').config(); no topo de bin/www ou app.js.
    • Estrutura Modular: Mantenha as rotas, controladores e serviços em arquivos separados para melhor organização, como fizemos com products.js.
    • Logging Profissional: O morgan já está configurado (app.use(logger('dev'));). Para logs mais complexos e persistentes, integre com bibliotecas como Winston ou Pino.
    • Validação de Entrada: Como demonstrado em products.js, valide sempre as entradas do usuário para evitar dados inválidos e vulnerabilidades.

Considerações sobre Testes Básicos:

Embora o Express Generator não inclua um framework de testes por padrão, a estrutura gerada é ideal para testes. Para verificar a funcionalidade da API, podemos usar curl ou ferramentas como Postman ou Insomnia. Para testes automatizados, você poderia integrar bibliotecas como Mocha, Chai e Supertest para testar suas rotas e lógica de negócio.

Exercício Hands-On (5 min)

Desafio Prático:

Sua tarefa agora é construir um novo projeto Express Generator para uma API de “livros”.

    • Gere uma nova aplicação Express sem views, com o nome minha-api-livros.
    • Entre no diretório e instale as dependências.
    • Inicie a aplicação e verifique que está funcionando.
    • Crie um novo arquivo de rota routes/books.js.
    • Neste arquivo, implemente uma rota GET /books que retorna um array de objetos JSON de livros (com id, title e author).
    • Implemente também uma rota GET /books/:id que retorna um livro específico pelo seu ID. Inclua validação de ID e tratamento para livros não encontrados.
    • Registre a nova rota /books no arquivo principal app.js.

Solução Detalhada Passo a Passo:

    • Gerar a Aplicação:

      express --no-view minha-api-livros
cd minha-api-livros
npm install
npm start

      Verifique em http://localhost:3000 (ou na porta que o ambiente indicar) que a aplicação está no ar.

    • Criar routes/books.js:

      Crie o arquivo minha-api-livros/routes/books.js com o seguinte conteúdo:

      // routes/books.js
var express = require('express');
var router = express.Router();
      

      const books = [
  { id: 1, title: 'O Senhor dos Anéis', author: 'J.R.R. Tolkien' },
  { id: 2, title: '1984', author: 'George Orwell' },
  { id: 3, title: 'Orgulho e Preconceito', author: 'Jane Austen' }
];
      

      / GET all books listing. /
router.get('/', function(req, res, next) {
  console.log('Requisição recebida para /books');
  res.status(200).json(books);
});
      

      / GET a single book by ID. /
router.get('/:id', function(req, res, next) {
  const bookId = parseInt(req.params.id);
  if (isNaN(bookId)) {
    return res.status(400).json({ error: 'ID de livro inválido. Deve ser um número inteiro.' });
  }
      

        const book = books.find(b => b.id === bookId);
      

        if (book) {
    res.status(200).json(book);
  } else {
    res.status(404).json({ error: Livro com ID ${bookId} não encontrado. });
  }
});
      

      module.exports = router;

    • Registrar Rota em app.js:

      Abra minha-api-livros/app.js e adicione as seguintes linhas:

      // app.js - Trecho relevante
// ... outras importações ...
var productsRouter = require('./routes/products'); // Se você fez o exercício anterior
var booksRouter = require('./routes/books'); // <-- Importa a nova rota de livros
      

      var app = express();
// ... outros middlewares ...
      

      app.use('/', indexRouter);
app.use('/users', usersRouter);
app.use('/products', productsRouter); // Se você fez o exercício anterior
app.use('/books', booksRouter); // <-- Usa a nova rota de livros
      

      // ... tratamento de erros ...

Como Testar e Validar o Resultado:

Após salvar as alterações em routes/books.js e app.js, reinicie sua aplicação (Ctrl+C e npm start).

Utilize um navegador ou uma ferramenta como Postman/Insomnia/curl para acessar os seguintes endpoints:

Troubleshooting dos Erros Mais Comuns:

    • “Cannot GET /books”: Verifique se você importou booksRouter e o usou com app.use('/books', booksRouter); em app.js. Certifique-se também de que o servidor foi reiniciado após as alterações.
    • “Router.use() requires middleware functions but got a Object”: Isso geralmente significa que você esqueceu de exportar o router de books.js (module.exports = router;) ou o importou incorretamente em app.js.
    • Porta em uso: Se você vir um erro como “EADDRINUSE”, significa que o servidor anterior não foi encerrado corretamente. Tente mudar a porta no bin/www (apenas para teste, use process.env.PORT em produção) ou espere um pouco para a porta ser liberada.

Próximos Passos Sugeridos:

Com esta base sólida, você está pronto para expandir sua API. Alguns próximos passos incluem:

    • Conexão com Banco de Dados: Integrar com um banco de dados como MongoDB (usando Mongoose), PostgreSQL (usando Sequelize) ou MySQL.
    • Criação (POST), Atualização (PUT/PATCH) e Deleção (DELETE): Implementar todos os verbos HTTP para operações CRUD completas.
    • Autenticação e Autorização: Adicionar segurança à sua API utilizando tokens JWT (JSON Web Tokens) ou OAuth.
    • Validação de Esquemas: Usar bibliotecas como Joi ou Express-Validator para validação mais complexa do corpo das requisições (req.body).
    • Documentação de API: Gerar documentação interativa para sua API usando Swagger/OpenAPI.
    • Testes Automatizados: Escrever testes unitários e de integração para suas rotas e lógica de negócio usando frameworks como Mocha e Supertest.

Parabéns por dominar o Express Generator! Esta ferramenta viabiliza o desenvolvimento rápido e estruturado, um atributo imprescindível para qualquer desenvolvedor de backend profissional.

🚀 Pronto para a próxima aula?

Continue sua jornada no desenvolvimento de APIs e domine Node.js & Express!

📚 Ver todas as aulas

Categories:

Tags:

, , , ,

Leodario