DEV Community: Bruno de Araujo Alves

PostgreSQL + Docker = 💙

Bruno de Araujo Alves — Sun, 13 Sep 2020 18:18:17 +0000

Assim como várias outra técnologias, o PostgreSQL também disponibiliza sua versão conteinerizada, conhecido como imagem, para ser executada usando Docker. Esta prática de conteinerização possibilita uma configuração rápida de ambientes de desenvolvimento, testes e produção.

Os familiarizados ao SGBD sabem que este tem uma ferramenta gráfica de administração que, por sua vez, também disponibiliza uma imagem gratuita e que pode ser utilizado em qualquer sistema operacional que suporte Docker. E os familiarizados ao Docker sabem que existe uma forma simples de executar vários contêineres, o Docker Compose, utilizando um arquivo YAML.

Será demonstrado neste tutorial:

🕛 Criar uma network
🕑 Criar um volume
🕓 Criar contêineres a partir de imagens
🕕 Acessar o banco usando pgAdmin4
🕗 Criar arquivo YAML
🔗 Links

Portanto, é esperado que você tenha conhecimento básico das tecnologias citadas. Certifique-se de que há instalado em sua máquina o Docker e Docker Compose. Ainda, se atente que todos comandos mostrados neste tutorial são executados utilizando um terminal.

🕛 Criar uma network

Network (rede) são pontes de comunicação que possiblitam à contêineres uma conexão entre eles. Geralmente, criasse uma network quando dois ou mias contêineres têm uma relação e comunicam-se. Portanto, para este caso crie uma network chamada postgres-network utilizando o comando abaixo:

docker network create -d bridge postgres-network

Criado a network que será utilizada nesse tutorial, é possível ver quais outras networks estão sendo utilizadas em sua máquina:

docker network ls

NETWORK ID	NAME	DRIVER	SCOPE
a8d59bf0f5bb	bridge	bridge	local
c0beeb145f0d	host	host	local
d539d7388de2	postgres-network	bridge	local

🕑 Criar um volume

Volume é o jeito utilizado no Docker para criar uma armazenamento persistente de dados, ou seja, ao desligar o contêiner os dados continuam existindo.
Para criar um volume utilize o comando abaixo, neste caso será criando um volume chamado postgres-data:

docker volume create --name=postgres-data

Para listar todos volumes existentes em sua máquina utilize o comando:

docker volume ls

DRIVER	VOLUME NAME
local	2b168382f98fc0280482b760893
local	portainer_data
local	postgres-data

🕓 Criar contêineres a partir de imagens

Antes de escolher uma imagem docker para utilizar é preciso se atentar à alguns detalhes:

Imagens docker são construídas em cima de alguma imagem de sistema operacional, geralmente linux, e cada imagem linux tem um tamanho.
Imagens também têm uma versão, geralmente estes são versões do próprio produto/serviço escolhido, e caso não seja especificado uma versão sempre será instalado a última versão estável.

Tendo os detalhes citados acima em mente, neste tutorial será usado a imagem do PostgreSQL versão 12.4, baseada na imagem linux Alpine de ~ 5MB, e para a imagem do pgAdmin4 você irá usar a última versão estável (mais abaixo). Siga o comando a baixo para criar um contêiner do PostgreSQL:

docker run --name postgres --network=postgres-network -e "POSTGRES_PASSWORD=postgresql" -v postgres-data:/var/lib/postgresql/data -p 5440:5432 -d postgres:12.4-alpine

Nesta única linha foi criado e executado um contêiner, em que:

--name, especificao nome do contêiner (postgres)
--network, especificaa rede (postgres_network)
-e, especifica a variável de ambiente do contêiner
- POSTGRES_PASSWORD=postgresql, é a variável de ambiente que especificaa senha necessária para ter acesso ao banco de dados.
-v, especifica o volume utilizado para persistir os dados (postgres-data).
-p, especificaqual porta será exposta (5440:5432), ou seja, será acessível de fora do docker (utilizar em uma aplicação não conteinerizada).
-d, especificaque após criado o contêiner seu terminal se separe do contêiner e você consiga utilizando sem ter que iniciar um novo terminal, ou tenha que parar o contêiner.
postgres:12.4-alpine, por fim o nome da imagem utilizada para criar o contêiner, neste caso a image postgres, versão 12.4 utilizando linux alpine.

É possível ver outras versões de imagens PostgreSQL acessando: https://hub.docker.com/_/postgres

Agora, crie um contêiner utilizando a imagem do pgAdmin4 em sua última versão utilizando o seguinte comando:

docker run --name pgadmin --network=postgres-network -p 15432:80 -e "PGADMIN_DEFAULT_EMAIL=example@example.com" -e "PGADMIN_DEFAULT_PASSWORD=pgadmin1234" -d dpage/pgadmin4

Este comando é muito parecido com o utilizado para criar o contêiner do Postgres. Estão presentes os atributos name, network, p, d, e dessa vez 2 atributos e de variáveis de ambiente:

PGADMIN_DEFAULT_EMAIL, email de login (example@example.com).
PGADMIN_DEFAULT_PASSWORD, senha de login (pgadmin1234)

Também, por último se encontra o nome da imagem utilizada para criar o contêiner (dpage/pgadmin4), como pode ver, desta vez não foi passado nenhuma versão especifica, portanto, por padrão é instalado a última versão estável da imagem, outro jeito de especificar a última versão da imagem é usando dpage/pgadmin:latest.

🕕 Acessar o banco usando pgAdmin4

Já que foi criado os dois contêineres é hora de testar se tudo está funcionando como esperado. Primeiro rode o comando abaixo para listar todos os contêineres em execução em sua máquina:

docker ps

Caso os dois contêineres ainda estejam em execução você deve ver algo similar ao mostrado abaixo:

CONTAINER ID	IMAGE	COMMAND	CREATED	STATUS	PORTS	NAMES
cdb6a40baab2	dpage/pgadmin4	"/entrypoint.sh"	1 minute ago	Up 2 hours	443/tcp, 0.0.0.0:15432->80/tcp	pgadmin
0e4fbee2549d	postgres:alpine	"docker-entrypoint.s…"	4 minutes ago	Up 2 hours	0.0.0.0:5440->5432/tcp	postgres

Usando um navegador acesse http://localhost:15432, repare que a porta é a mesma exposta na criação do contêiner pgadmin (15432).

Adicione o email e senha passados como variáveis de ambiente na criação do contêiner e clique em "login".

email: example@example.com
senha: pgadmin1234

Você será redirecionado para outra página, como esta:

Porém, ainda não há nenhum servidor de banco de dados configurado. Para adicionar um novo, clique com o botão direito em cima do "Servers" no canto superior esquerdo, vá em "Create" e em seguinda em "Server..."

Um modal será aberto onde você irá inserir informações sobre o servidor. No campo "name" adicione um nome de sua preferência e clique na aba "Connection".

Nesta dela siga os passos:

No campo "Host name/address", adicione o nome do contêiner "postgres" (nome do contêiner Postgres).
No campo "Port" utilize a porta interna do contêiner "5432".
Deixe o campo "Maintenance database" como está.
No campo "Username" adicione "postgres".
No campo "Password" adicione a senha usada como variável de ambiente na criação do contêiner do PostgreSQL ("postgresql").

Ao final, clique no botão "Save".

Verá que o servidor foi criado e agora você tem acesso ao banco de dados do mesmo modo se não estivesse usando docker.

Lembre-se que para acesso interno o host do banco de dados é o nome do contêiner (postgres) e a porta é a interna (5432). Já para acesso externo, como em uma aplicação feita em NodeJS, o host é "localhost" ou "127.0.0.1" e a porta é a porta externa especificada na criação do contêiner (5440).

🕗 Criar arquivo YAML

Todo o passo de criação dos contêineres pode ser feito utilizando um arquivo que por convenção/padrão é chamado docker-compose.yml e utiliza o Docker Compose como seu gerenciador, além disso adiciona o conceito de stack.

Stack nada mais é que um conjunto de contêineres que tem uma relação entre si, você pode criar quantas stacks quiser. Lembrando que sempre que criar um arquivo docker-compose.yml, a stack será o nome da pasta em que o arquivo está. Ao criar uma network dentro de uma stack o nome desta network terá como prefixo o nome da stack (exemplo logo abaixo).

Portanto, para começar, crie um arquivo com o nome docker-compose.yml dentro de uma pasta nomeada postgres, sendo assim a stack será postgres.

Em seguida, abra o arquivo em um editor de texto de sua preferência e comece adicionando o básico:

version: "3"

networks:
  network:
    driver: bridge

volumes:
  postgres-data:
    external: true

Em que há:

version - versão do Compose.
networks - networks a serem criadas dentro da stack.
- network - esta network, como dita antes, será nomeada postgres-network, pois será adicionado o prefixo da stack.
volumes - volumes (armazenamentos) a serem criadas dentro da stack.

Rearraje o script do contêiner postgres ao arquivo:

version: "3"

services:
  postgres-compose:
    image: postgres:12.4-alpine
    container_name: postgres
    environment:
      POSTGRES_PASSWORD: "postgresql"
    ports:
      - "5440:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - network

networks:
  network:
    driver: bridge

volumes:
  postgres-data:
    external: true

Como feito antes utilizando o script de uma única linha, será criado um contêiner com o nome "postgres", senha "postgresql", porta "5440:5432", network "postgres-network" (lembre do prefixo), e volume.

Agora é a vez de reescrever script do contêiner do pgadmin:

version: "3"

services:
  postgres-compose:
    image: postgres:12.4-alpine
    container_name: postgres
    environment:
      POSTGRES_PASSWORD: "postgresql"
    ports:
      - "5440:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - network

  pgadmin-compose:
    image: dpage/pgadmin4
    container_name: pgadmin
    environment:
      PGADMIN_DEFAULT_EMAIL: "example@example"
      PGADMIN_DEFAULT_PASSWORD: "pgadmin1234"
    ports:
      - "15432:80"
    depends_on:
      - postgres-compose
    networks:
      - network

networks:
  network:
    driver: bridge

volumes:
  postgres-data:
    external: true

Também, como no contêiner postgres, está tudo bem parecido com escrito anteriormente utilizando uma única linha. O nome, email, senha, porta e network continuam o mesmo, porém também foi adicionado um atributo novo, depends_on, este permite que o contêiner pgadmin não seja criado/iniciado antes do contêiner postgres ser criado/iniciado.

Porém, antes de executar o arquivo será necessário deletar os contêineres já existente afinal não serão mais utilizados como anteriormente, agora eles pertecerão à uma stack. Primeiro pare os dois contêineres docker stop postgres pgadmin em seguida os remova docker rm postgres pgadmin.

Agora, rode o comando para executar o arquivo docker-compose.yml utilizando o Docker Compose:

docker-compose up -d

Este comando faz com que os contêineres configurados no arquivo sejam criandos, caso ainda não exista, e os execute. Ainda, quando algo for alterado no arquivo os contêineres afetados serão reconstruidos.

Em algum momento, caso você queira parar todos os contêineres do arquivo, utilize o comando:

docker-compose down

E para remover:

docker-compose rm

Pessoalmente, gosto de guardar arquivos, scripts e instaladores, pois, estou sempre testando algo novo e algumas vezes isso resulta em ter que formatar o computador. Portanto, já ter um arquivo/script de instalação econimiza bastante tempo, afinal não é preciso ter que ir na internet buscar como configurar ou ter que reconfigurar na mão.

O preguiçoso sempre arruma um jeito de não ter trabalho.

Por fim, agradeço você por ter chegado até aqui, deixe seu comentário e sugestão para os próximos posts, e caso este post tenha te ajudado deixe seu like. 👍

🔗 Links

Site pessoal: baraus.dev
GitHub: @devbaraus
Instagram: @devbaraus

Tutoriais:

Criando um servidor em NodeJS - Parte 2

Bruno de Araujo Alves — Sun, 23 Aug 2020 18:47:21 +0000

Esta é parte 2 do tutorial de como fazer um servidor utilizando NodeJS, Express e um arquivo JSON como banco de dados. Caso você não tenha visto a primeira parte acesse: Criando um servidor em NodeJS - Parte 1

Repositório https://github.com/devbaraus/post_server_node
Meu site baraus.dev

Tabela de conteúdos

Utilizando o Git
Criando arquivo server
Botando a mão na massa
Manipulando o arquivo json
- CRUD
  - LER
  - CRIAR
  - ALTERAR
  - DELETAR
Reorganização de código
- Criando controller
- Criando sistema de rotas
- Limpando o server.js
Recapitulando

Utilizando o Git

Lembre-se de a cada alteração importante no código fazer um commit. Isso permite que caso algo dê errado seja possível recuperar a última versão correta do código.
Para isso utilize os comandos abaixo:

git add . # adiciona todos os arquivos alterados
git commit -am "..." # adicionar uma mensagem ao commit
git push # caso esteja usando github

Criando arquivo server

Já temos nossa organização de pastas criada, package.json criado, pacotes instalados, agora falta apenas criarmos o arquivo server.js e começarmos a codar! :laptop:
Para isso precisamos criar o arquivo server.js dentro da pasta src

touch src/server.js # cria o arquivo dentro da pasta sem precisar entrar nela

Criado o primeiro arquivo do projeto, vamos utilizar o editor de código
VS Code. Para abrirmos a pasta atual no VS Code utilizando o terminal execute o próximo comando

code .  # Abre o editor vscode na pasta atual

Botando a mão na massa

Com a pasta server_node aberta no VS Code como diretório raiz do projeto, procure pelo arquivo server.js dentro da pasta src.

Agora é preciso apenas começar a codar, para isso importamos os pacotes que instalamos anteriormente.

Importe o pacote Express e atribua ele a uma variável, no nosso caso app, como uma função.

Agora, diga ao app escutar requisições na porta 3000, como está abaixo.

// importa pacote express
const express = require('express')
// atribui à app como uma função
const app = express()

// inicia servidor escutando requisições na porta 3000
app.listen(3000,  ()  =>  {
    console.warn(`Servidor escutando na porta 3000`)
})

Agora nosso projeto realmente começou, temos um servidor que escuta na porta 3000 da nossa máquina, porém, ainda falta alguns passos para conseguirmos receber algo.

Vamos configurar mais alguns pacotes para trabalhar junto ao Express.

importamos o cors, pacote que faz com que outras aplicações consigam se comunicar com nosso servidor
importamos o morgan, gerador de logs de requição.
- falamos para o app/express utilizar um formato json para o corpo das requisições HTTP
- falamos para o app/express utilizar o cors em sua execução
- falamos para o app/express utilizar o morgan em sua execução
- finalmente, criamos uma rota com o método GET que retorna 'ok'

// importa pacote express  
const express = require('express')  
// importa pacote cors  
const cors = require('cors')  
// importa pacote morgan  
const morgan = require('morgan')  

// atribui a variavel o express como uma função  
const app = express()  

// app usa corpo em json  
app.use(express.json())  
// app usa cors  
app.use(cors())  
// app usa gerador de log morgan  
app.use(morgan('dev'))

// rota :GET / 
app.get('/', (request, response) => {  
  return response.send('ok')  
})

// inicia servidor escutando requisições na porta 3000  
app.listen(3000, () => {  
  console.warn(`Servidor inicializador na porta 3000`)  
})

Criamos o básico básico de um servidor em node, porém até agora não executamos nosso servidor nenhuma vez. Para isso, no terminal, execute o script start que criamos.

yarn start

Este comando faz com que o NodeJS execute o arquivo server.js. Como um servidor é um programa que fica sempre em execução, apenas interrompido quando há algum erro ou outro programa/usuário força sua interrupção, ele ficará esperando requisições. Portanto, faça uma requisição, pelo próprio navegador, na rota http://localhost:3000. Caso nada tenha dado errado, você receberá um ok na página, em formato HTML.

Usando yarn start nosso servidor nunca para de funcionar, porém também não se reinicia quando fizermos alguma alteração no código, para isso preparamos o script dev. Portanto, interrompa a execução do servidor usando as teclas de atalho CTRL + C no dentro do terminal e execute um novo comando usando yarn:

yarn dev

Manipulando o arquivo json

Já que programamos nossa primeira rota, é hora de realmente retornar ao usuário dados como uma API Rest.
Separei um arquivo json chamado facts.json, com fatos sobre gatos, para funcionar como nosso bancos nesse projeto. Baixe o arquivo e coloque-o na pasta db do nosso projeto e importe dois módulos padrões do NodeJS, abaixo dos antigos imports dentro do arquivo server.js:

path, provê métodos para facilmente trabalhar com caminhos dentro do node
fs, provê métodos para trabalhando com o sistema de arquivos do sistema operacional

// importa módulo path  
const path = require('path')  
// importa módulo fs  
const fs = require('fs')

Logo, utilizamos o modulo path para resolver o caminho relativo do arquivo server.js ao arquivo facts.json e guardamos na variável dbPath.

Dentro do antigo app.get(...) criamos uma nova funcionalidade.

Lemos o arquivo facts.json utilizando o método readFileSync do módulo fs (sempre retorna string)
Fazemos o parse/transformação da string para o formato json
Retornamos o json para o usuário

É pelo navegador, acesse http://localhost:3000/ e veja os mesmos dados do arquivo json sendo mostrado.

// guardamos o caminho para o arquivo json  
const dbPath = path.resolve(__dirname, './db/facts.json')

// rota :GET /  
app.get('/', (request, response) => {  
  // Lê de forma síncrona o arquivo json, como string  
  const data = fs.readFileSync(  
  dbPath,  
  'utf8',  
  )  
  // transforma a string em json  
  const facts = JSON.parse(data)  

  // retorna o json para o usuário  
  return response.json(facts)  
})

Neste ponto é possível ver como funciona um servidor API Rest, o usuário faz uma requisição e o retorno é apenas em json, nada de HTML.

Nosso código está bem enxuto, e queremos isto, algo simples, de fácil entendimento, porém que resolva o proposto. Porém, não estamos tratando nenhuma exceção ou erro que possa acontecer durante a execução.

Para resolver esse problema vamos envolver todo o conteúdo dentro app.get(...) em um try/catch.

// rota :GET /  
app.get('/', (request, response) => {  
  try{  
      // Lê de forma síncrona o arquivo json, como string  
      const data = fs.readFileSync(  
      dbPath,  
      'utf8',  
      )  
      // transforma a string em json  
      const facts = JSON.parse(data)  

      // retorna o json para o usuário  
      return response.json(facts)  
  } catch (e) {  

  }
})

Dessa forma, quando estiver algum erro podemos mandar algum status de resposta http para o usuário. Mas ainda não terminamos, se tudo der certo precisamos enviar um status de resposta ao usuário de código 200, e caso dê algum problema durante a execução do nosso código precisamos tratar de alguma forma e enviar um status de resposta 500.
Para isso utilizaremos alguns status de reposta:

status	quando
200	Fatos encontrados
500	Erro no servidor

// rota :GET /  
app.get('/', (request, response) => {  
  try{  
      // Lê de forma síncrona o arquivo json, como string  
      const data = fs.readFileSync(  
      dbPath,  
      'utf8',  
      )  
      // transforma a string em json  
      const facts = JSON.parse(data)  

      // retorna o json para o usuário com status 200  
      return response.status(200).json(facts) 
  } catch (e) {  
      // print mensagem de erro no terminal  
      console.log(e)  

      // retorna mensagem de erro para o usuário com status 500  
      return response.status(500).json({erro: 'Erro de execução!'})
  }
})

CRUD

A partir deste momento já estamos criando um CRUD (Criar, Ler, Alterar e Deletar).
No passo anterior, criamos a leitura de todos os dados, sem nenhuma especifidade. Então, no próximo criaremos a leitura de um dado apenas, baseado na rota que o usuário acessar, o ID.

LER

app.get('/:id', (request, response) => {...})

Para isso utilizamos os método GET novamente, porém, utilizaremos uma rota dinâmica com :id. Isto significa que agora conseguimos acessar http://localhost:3000/1 ou http://localhost:3000/2, e este número adicional na rota nos dará a capacidade de retornarmos ao usuário o fato de ID igual ao inserido por ele.

Bora codar a requisição do usuário para um fato com ID.

status	quando
200	Fatos encontrados
404	Nenhum fato for encontrado
500	Erro no servidor

// ouve requisições com metodo GET com um parâmetro
app.get('/:id', (request, response) {  
    // pega o ID requisição  
    const { id } = request.params  
    try {  
         // Lê de forma síncrona o arquivo json, como string  
         let data = fs.readFileSync(dbPath, 'utf8')  
         // inicializa uma variável nula  
         let fact = null  

         // transforma a string em json e pega o array facts
         data = JSON.parse(data)['facts']  

         // passa por todos os fatos  
         for (let index in data) {  
             // se encontrar um fato com o mesmo ID que o usuário pediu  
             if (data[index]['id'] == id) {  
                 // a variavel fact recebe o fato com ID
                 fact = data[index]  
                 // para o loop  
                 break  
             }  
        }  
         // caso a variável não tenha recebido nenhum fato  
         if (fact === null) {  
             // retorne uma mensagem de erro com o status 400  
             return response  
             .status(404)  
             .json({ erro: 'Nenhum fato foi encontrado!' })  
        }  
        // retorne o fato encontrado para o usuário  
        return response.json(fact)  
    } catch (e) {  
         // print do erro no terminal  
         console.log(e)  

         // retorne uma mensagem de erro com o status 500  
         return response  
         .status(500)  
         .json({ erro: 'Não foi possível executar esta operação!' })  
    }
}

Temos as duas requisições com o método GET, para quando o usuário pedir todos os fatos e quando pedir apenas um fato com um específico ID.

CRIAR

Precisamos possibilitar que o usuário seja capaz de criar um novo fato.
No corpo da requisição pegaremos todos os campos necessários para criar um novo fato, neste caso, um campo de nome text.
O algoritmo, de forma ampla, para essa funcionalidade é:

ouvir requisições com o método POST
pegar campo text do corpo da requisição
ler arquivo e guardar em uma variável
criar um objeto com as propriedades necessárias, id, text, type e upvotes
adicionar o novo fato à variável com os dados do arquivo .json
sobrescrever o arquivo
retornar o novo fato ao usuário

status	quando
201	Fato criado
500	Erro no servidor

// ouve requisições com metodo POST
app.post('/', (request, response) => {
    // lê o campo text do corpo da requisição  
    const { text } = request.body  
    try {  
      // Lê de forma síncrona o arquivo json, como string  
      let data = fs.readFileSync(dbPath, 'utf8')  

      // transforma a string em json  
      data = JSON.parse(data)  

      // cria um novo fato  
      const newFact = {  
          id: String(data['facts'].length + 1),  
          text: text,  
          type: 'cat',  
          upvotes: 0,  
      }  

      // adiciona o fato ao array de fatos  
      data['facts'].push(newFact)  

      // sobrescreve o arquivo  
      fs.writeFileSync(dbPath, JSON.stringify(data))  

      // retorna o fato criado ao usuário com o status 201  
      return response.status(201).json(newFact)  
    } catch (e) {  
      // print do erro no terminal  
      console.log(e)  

      // retorne uma mensagem de erro com o status 500  
      return response  
      .status(500)  
      .json({ erro: 'Não foi possível executar esta operação!' })  
    }
})

ALTERAR

Já que criamos, precisamos possibilitar que seja alterado algum dado existente, a partir de um ID. Portanto, dessa vez, iremos possibilitar que o usuário altere algum fato em nosso arquivo/banco a partir da rota dinâmica com ID e um corpo com campo text.

O algoritmo, de forma ampla, desta vez é:

ouvir requisições com o método PUT e ID
pegar campo text do corpo da requisição
ler arquivo e guardar em uma variável
criar um objeto recebendo o fato existente e alterando o campo text
adicionar o fato alterado à variável com os dados do arquivo .json
sobrescrever o arquivo
retornar o fato alterado ao usuário

status	quando
201	Fato criado
404	Fato não encontrado
500	Erro no servidor

// ouve requisições com método PUT e ID
app.put('/:id', (request, response) => {  
     // pega o ID da rota
     const { id } = request.params  
     // pega o campo text do corpo da requisição  
     const { text } = request.body  

     try {  
        // Lê de forma síncrona o arquivo json como string  
        let data = fs.readFileSync(dbPath, 'utf8')  

        // inicializa duas variáveis como nulas  
        let fact = null  
        let indexFact = null  

        // transforma a string em json  
        data = JSON.parse(data)  

        // passa por todos os fatos  
        for (let index in data['facts']) {  
            // se encontrar um fato com o mesmo ID que o usuário pediu  
            if (data['facts'][index]['id'] == id) {  
                // variável fact recebe o fato com ID  
                fact = data['facts'][index]  
                // guarda o index do fato em questão  
                indexFact = index  
                // para o loop  
                break  
            }  
        }  
        // se a variável continua nula  
        if (fact === null) {  
            // retorne uma mensagem de erro com o status 404  
            return response  
            .status(404)  
            .json({ erro: 'Nenhum fato foi encontrado!' })  
        }  
        // cria um objeto com o fato existente e altera o campo text
        const updatedFact = {  
            ...data['facts'][indexFact],  
            text: text,  
        }  

        // guarda o objeto atualizado ao array de fatos  
        data['facts'][indexFact] = updatedFact  

        // sobrescreve o arquivo  
        fs.writeFileSync(dbPath, JSON.stringify(data))  

        // retorna o fato atualizado com o status 200  
        return response.status(200).json(updatedFact)  
    } catch (e) {  
        // print do erro no terminal  
        console.log(e)  

        // retorne uma mensagem de erro com o status 500  
        return response  
        .status(500)  
        .json({ erro: 'Não foi possível executar esta operação!' })  
    }
 })

DELETAR

Finalmente, precisamos possibilitar ao usuário a funcionalidade de deletar um fato existe. Esta funcionalidade segue a mesma ideia da alteração, precisando do ID da rota, porém sem nenhum corpo.
O algoritmo dessa funcionalidade, de forma ampla, é:

ouvir requisições com o método DELETE e ID
ler arquivo e guardar em uma variável
remover o fato com ID do array
sobrescrever o arquivo
retornar o um status ao usuário

status	quando
204	Fato deleteado
404	Fato não encontrado
500	Erro no servidor

// ouve requisições com o método DELEte e ID
app.delete('/:id', (request, response) => {  
    // pega o ID da rota 
    const { id } = request.params  
    try {  
        // Lê de forma síncrona o arquivo json como string  
        let data = fs.readFileSync(dbPath, 'utf8')  

        // inicializa uma variável como  
        let indexFact = null  

        // transforma a string em json  
        data = JSON.parse(data)  

        // passa por todos os fatos  
        for (let index in data['facts']) {  
            // se encontrar um fato com o mesmo ID que o usuário pediu  
            if (data['facts'][index]['id'] == id) {  
                // guarda o índice do fato em questão  
                indexFact = index  
                // para o loop  
                break  
            }  
        }  
        // se a variável continua nula  
        if (indexFact == null) {  
            return response  
            .status(404)  
            .json({ erro: 'Nenhum fato foi encontrado!' })  
        }  

        // remove um elemento do array a partir do índice  
        data['facts'].splice(indexFact, 1)  

        // sobrescreve o arquivo  
        fs.writeFileSync(dbPath, JSON.stringify(data))  

        // retorna o status 204  
        return response.sendStatus(204)  
    } catch (e) {  
        // print do erro no terminal  
        console.log(e)  

        // retorne uma mensagem de erro com o status 500  
        return response  
        .status(500)  
        .json({ erro: 'Não foi possível executar esta operação!' })  
    }
})

Reorganização de código

Criando controller

Se você olhar para seu arquivo server.js ele está enorme e é difícil sua leitura, além de que eventualmente nós podemos querer acrescentar mais funcionalidades, portando, mais código ao nosso projeto.
Para uma melhor manutenção é importante separarmos aquilo que é de inicialização/configuração do servidor do que é funcionalidade para o usuário.
Então, nessa fase iremos reorganizar nossos arquivos e fazer uso da pasta controllers criada anteriormente ainda na parte 1.
Para começar, vamos criar um arquivo chamado FactsController.js dentro da pasta controllers.

Dentro deste arquivo importaremos os módulo path e fs, podemos apenas mover os importes do arquivo server.js; Moveremos a variável dbPath para dentro deste arquivo, ajustando o caminho; Criaremos uma classe com nome FactsController e dentro dessa classe criaremos 5 métodos, index, show, create, update e delete, todos com os mesmo parâmetros, request e response, e ao final exportaremos a classe como um módulo.

// importa módulo path  
const path = require('path')  
// importa módulo fs  
const fs = require('fs')
// guardamos o caminho para o arquivo json  
const dbPath = path.resolve(__dirname, '../db/facts.json')

class FactsController{
    index(request, response){
    }
    show(request,response){
    }
    create(request,response){
    }
    update(request,response){
    }
    delete(request,response){
    }
}
modules.export = FactsController

O próximo passo para organizarmos nosso código é mover algumas partes de código que estão no server.js para este arquivo. Portanto, todo o código dentro de app.get('/', (request, response){...}) ficará dentro de index, assim:

index(request, response) {  
    try {  
        // Lê de forma síncrona o arquivo json, como string  
        const data = fs.readFileSync(dbPath, 'utf8')  

        // transforma a string em json  
        const facts = JSON.parse(data)  

        // retorna o json para o usuário com status 200  
        return response.status(200).json(facts)  
    } catch (e) {  
        // print do erro no terminal  
        console.log(e)  

        // retorne uma mensagem de erro com o status 500  
        return response  
        .status(500)  
        .json({ erro: 'Não foi possível executar esta operação!' })  
    }
}

O mesmo será feito para o outro GET, POST, PUT e DELETE. Seguindo o esquema abaixo.

app.get('/:id', (request, reponse)=>{...}) -> show(request, response){...}
app.post('/', (request, reponse)=>{...}) -> create(request, response){...}
app.put('/:id', (request, reponse)=>{...}) -> update(request, response){...}
app.delete('/:id', (request, reponse)=>{...}) -> delete(request, response){...}

Criando sistema de rotas

Nosso controller agora não está se comunicando com o servidor/Express e para deixar nosso código ainda mais limpo criaremos um arquivo chamado routes.js no mesmo diretório do arquivo server.js. Este arquivo irá conter todas as rotas do nosso servidor, podendo, a medida que o servidor for crescendo, ser dividido em mais arquivos.
Nesse arquivo de rotas iremos importar o arquivo FactsController.js como um módulo, usando ./controllers/FactsController para sinalizar que é um módulo criado no projeto. Importaremos também o módulo Express, porém, dessa vez iniciaremos um roteador, e não um servidor; Criaremos nossas rotas e exportaremos o arquivo como um módulo.

const router = require('express').Router()  
const FactsController = require('./controllers/FactsController')  

const factsController = new FactsController()  

// Retorna todos fatos  
router.get('/', factsController.index)  

// Retorna um fato  
router.get('/:id', factsController.show)  

// Cria um novo fato  
router.post('/', factsController.create)  

// Edita um fato  
router.put('/:id', factsController.update)  

// Deleta um fato  
router.delete('/:id', factsController.delete)  

module.exports = router

Limpando o server.js

Dentro do arquivo server.js, agora temos códigos que não estão mais sendo usados pelo servidor. Então vamos dar uma limpa e colocar nosso servidor para funcionar novamente!

Exclua todos os app.get, app.post, app.put e app.delete, importe o arquivo de rotas criado anteriormente e fale para o servidor usar esse arquivo de rotas .

// importa pacote express  
const express = require('express')  
// importa pacote cors  
const cors = require('cors')  
// importa pacote morgan  
const morgan = require('morgan')  
// importa rotas pelo arquivo routes.js  
const routes = require('./routes')  

// atribui a variavel o express como uma função  
const app = express()  

// app usa corpo em json  
app.use(express.json())  
// app usa cors  
app.use(cors())  
// app usa gerador de log morgan  
app.use(morgan('dev'))  

// utilize o arquivo de rotas
app.use('/', routes)  

// inicia servidor escutando requisições na porta 3000  
app.listen(3000, () => {  
    console.warn(`Servidor inicializador na porta 3000`)  
})

Recapitulando

Neste ponto nosso projeto chega ao fim, criamos todas rotas de um CRUD, manipulamos o arquivo JSON e organizamos nossos arquivo de um maneira que seja fácil a manutenção, ainda não é o ideal, mas é o suficiente!

Se você chegou até aqui espero que tenha aprendido como criar um servidor NodeJS e consigar criar o seu próprio sem grandes dificildades.

Estas duas partes foram meus primeiros posts, ainda pretendo criar uma série de posts envolvendo o desenvolvimento de aplicações Back End e Front End.

Deixe seu comentário dizendo o que está bom e o que é preciso melhorar nos posts.

Criando um servidor em NodeJS - Parte 1

Bruno de Araujo Alves — Sun, 23 Aug 2020 18:44:40 +0000

Este tutorial, dividido em duas partes (Parte 2), ensina como iniciar um servidor Rest API em NodeJS da forma mais trivial. Dessa forma, é utilizado apenas um arquivo JSON, dispensando o uso de sistema gerenciador de banco de dados. Assim, este artigo tem o objetivo de auxiliar programadores iniciantes.

Repositório https://github.com/devbaraus/post_server_node
Meu site baraus.dev

Abaixo são listados alguns dos conhecimentos que serão descritos e ensinados neste tutorial:

Boas práticas de programação
Definição de um sistema de pastas simples e eficiente
Iniciar um repositório Git
Iniciar um projeto Node utilizando yarn
Ler e manipular arquivos usando Node
Criar um CRUD (Criar, Ler, Alterar e Deletar) simples
Usar o prompt de comando/terminal

Antes de começar é preciso certificar-se de que alguns programas estão instalados na máquina que será utilizada para realizar este tutorial.

NodeJS, ambiente de execução de código JavaScript. Este programa permite executar JavaScript fora do navegador.
Yarn, gerenciador de pacotes JavaScript.
Git, versionador de código.
Visual Studio Code, editor de código.
Insomnia, ambiente para testar requisições HTTP.

É necessário criar uma conta criada no GitHub. O GitHub é a plataforma de hospedagem de código-fonte e possui controle de versão. Essa plataforma poderá auxiliar no transporte do código para outro lugar, como para a faculdade ou trabalho.

É importante saber o que é um servidor REST, o que é HTTP e como utilizar o Insomnia para fazer requisições ao servidor HTTP. Para isso foram separados alguns links demonstrar o que está sendo montado:

Iniciando o projeto.

Lembrando que os passos a seguir são realizados em um terminal bash, o mesmo utilizado em sistemas operacionais Linux.

Tabela de conteúdos

Criando pastas
Criando um repositório utilizando GitHub
Criando um repositório sem GitHub
Criando package.json usando Yarn
- Instalando os primeiros pacotes
- Scripts
REST com Express
- Domínio
- Porta
- Rota
- Cabeçalhos
  - Métodos
    - GET
    - POST
    - PUT
    - DELETE
- Corpo
- Parâmetros (Query String)
- Recapitulando REST com Express
  - GET
  - GET com parâmetros
  - GET com rota dinâmica
  - POST
  - PUT
  - DELETE
Recapitulando

Criando pastas

Para começar será criada uma pasta inicial chamada server_node. Após criá-la é necessário entrar nela

mkdir server_node # cria pasta server_node
cd server_node # entra na pasta

Depois é criada uma pasta chamada src. Nessa pasta todos os arquivos de desenvolvimento do projeto são depositados.

mkdir src # cria pasta src
cd src # entra na pasta

Por enquanto, tem-se apenas a pasta server_node e dentro dela uma pasta chamada src. Porém, dentro da pasta src ainda deve ser criada uma hierarquia de pastas.

Uma pasta chamada controllers, na qual estarão os códigos que controlaram as funcionalidade do usuário, e outra chamada db. Na pasta db estarão todas a informação do base de dados, neste caso um arquivo .json com alguns dados.

Para criar essas pastas é executado o seguinte comando:

mkdir controllers db # cria as duas pastas em uma linha

Para os próximos passo é necessário que o diretório atual seja a raiz do projeto, ou seja, a pasta server_node. Lembrando que o diretório atual é src dentro de server_node. Para voltar diretórios execute.

cd ../ # volta uma pasta

Criando um repositório utilizando GitHub

Caso você tenha uma conta criada no GitHub, crie um novo repositório com nome server_node, sem gitignore, licença e readme.
Logo após criado o repositório irá aparecer algumas opções para iniciar o mesmo. Copie todo o conteúdo da opção criar um novo repositório usando linha de comando, no meu caso o código é o mostrado abaixo. Cole o conteúdo no terminal e de enter.

echo "# server_node" >> README.md # cria um arquivo com o conteúdo "# server_node"
git init # inicia um repositório git local
git add README.md # adiciona o arquivo ao commit
git commit -m "first commit" # adiciona uma mensagem ao commit
git remote add origin https://github.com/devbaraus/server_node.git # vincula o repositorio do github ao seu repositorio local
git push -u origin master # envia o estado atual do seu repositório para o GitHub

Criando um repositório sem GitHub

Caso você não utilize o GitHub ou qualquer outra plataforma. Apenas copie e cole o código abaixo para iniciar seu versionamento de código local.

git init # inicia repositório git local

Pronto!

Criando package.json usando Yarn

Para iniciarmos um projeto NodeJS é muito simples, apenas precisamos criar um arquivo chamado package.json com algumas propriedades, como:

name, nome do projeto
description, descrição do projeto
version, versão atual do projeto
main, arquivo principal do projeto
author, autor do projeto
license, licença utilizada no projeto
private, se este projeto pode ser publicável ou não
scripts, comandos de execução
dependencies, dependências principais do projeto
devdependencies, dependências apenas utilizadas no desenvolvimento

Embora seja algo simples de se criar na mão, é muito mais fácil utilizando um comando que o Yarn disponibiliza. Este comando se chama yarn init, após executar, será necessário preencher alguns dados, como é mostrado abaixo.

yarn init # inicia repositório git local

question name (server_node):
question version (1.0.0): 0.0.1
question description: Servidor em nodejs
question respository url: https://github.com/devbaraus/post_server_node.git
question author: Bruno de Araujo Alves <devbaraus>
question license (MIT): MIT
question private: false

Preenchido todos os comandos seu arquivo deve se parecer como o mostrado abaixo.

Instalando os primeiros pacotes

Pacotes são módulos, códigos que outras pessoas fizeram para realizar alguma coisa.
Neste projeto utilizaremos poucos pacotes, sendo eles classificados em principais ou desenvolvimento. Como o nome já sugere, pacotes principais são módulos que seu código irá precisar mesmo quando em produção e pacotes de desenvolvimento são módulos que você usará apenas quando estiver programando.
Módulos que usaremos são:

Principais

Express, possibilita criarmos um servidor http utilizando node
cors, possibilita que uma outra aplicação faça requisição ao seu servidor

Para instalar use

yarn add Express cors

Desenvolvimento

morgan, possiblita gerar logs de toda requisição feita ao servidor
nodemon, possibilita que executemos nosso servidor e a cada alteração no código o servidor seja reiniciado.

E para instalar os pacotes em modo de desenvolvimento, apenas adicione mais um argumento -D .

yarn -D add morgan nodemon

Seu package.json deve estar semelhante a este.

Se atente que ao instalar um novo pacote uma pasta chamada node_modules é criada, nela está todos os pacotes baixados. Ainda, note que cada vez que você adiciona ou remove um pacote o arquivo package.json é alterado. Isso serve para caso você precise copiar seu código para outra máquina, você não precise copiar a pasta node_modules junto, e seja necessário apenas executar o comando.

yarn install # instala todos os pacotes do package.json

Com esse comando todos os pacotes que estejam no package.json serão instalados e automaticamente será criada a pasta node_modules.

Scripts

Agora que temos os pacotes instalados podemos criar alguns scripts para executar nosso servidor. Primeiro vamos criar uma nova propriedade no arquivo package.json chamada scripts e esta receber um objeto vazio.

"scripts": {},

Dentro de scripts vamos criar duas propriedades, dev e start.
Dev será o script para executarmos o servidor em desenvolvimento, reiniciando a cada modificação no código.

"scripts": {
    "dev":  "nodemon --watch ./src/**/* ./src/server"
},

E o start será o script que utilizaremos quando quisermos executar nosso servidor em produção.

"scripts":  {
    "dev":  "nodemon --watch ./src/**/* ./src/server",
    "start":  "node ./src/server"
},

Seu package.json agora deve estar semelhante ao mostrado abaixo.

REST com Express

Antes de começarmos a codar precisamos lembrar de alguns conceitos de requisições HTTP.
Para fazermos uma requisição HTTP com Express precisamos lembrar de 6 pontos principais: o domínio, a porta, a rota, os cabeçalhos (headers), o corpo (body) e os parâmetros (query string).

Domínio

Domínio, de forma bem ampla, é o nome do servidor, este é um jeito utilizado para não precisarmos escrever o IP de todo site que quisermos acessar. O domínio, assim como o IP, é único e é reconhecido por toda a internet. Como exemplo, a Google tem um domínio global google.com
que por trás está um IP 172.217.28.78.

A única exceção de domínio e IP que se repete em toda máquina é o local. Toda máquina máquina consegue se acessar usando o domínio local localhost e IP 127.0.0.1, portanto uma máquina não consegue acessar um aplicação de outra máquina utilizando o domínio localhost, pois ela tentará acessar a si mesma.

Porta

Porta, de forma ampla, são conexões de cada aplicação dentro da nossa máquina. Cada aplicação utiliza uma ou mais portas para se comunicar com outra aplicação, internamente ou não. Em nossa máquina temos 65535 portas, sendo 1024 reservados para uso do computador.

Lembrando que por padrão HTTP utiliza a porta 80, por isso muita das vezes não precisamos explicitamente colocar a porta ao acessar um site.
Faça o teste, acesse google.com:80 e depois google.com:82. No primeiro caso você conseguirá acessar o site, porém no seguindo caso o navegador não conseguira acessar nada.

Nesse projeto, nosso servidor utilizamos a porta 3000, porém pode ser alterado para qualquer valor entre 1024 e 65335.

Rota

Rota, é o caminho em que o usuário faz uma requisição ao servidor.
Sendo assim, um caminho dita qual conteúdo você espera que o servidor te retorne.
Como exemplo novamente a Google: google.com/ egoogle.com/doodles/
No primeiro caso falamos ao servidor que esperamos a página de busca do site / , já no segundo caso pedimos ao servidor do google que nos mostre a página doodles /doodles/.

Servidores têm a possibilidade também de criar rotas dinâmicas, estas são rotas geradas automaticamente para requisição de um dado específico mas que o tratamento desse dado é genérico. Como, buscar dados de um usuário específico. O servidor irá retornar os dados apenas daquele usuário, porém o tratamento no servidor é genérico, de forma que consiga buscar qualquer usuário dentro do banco de dados.

Cabeçalhos

Os cabeçalhos têm informações importantes sobre o usuário e também sobre o servidor (no retorno).
Nos cabeçalhos conseguimos encontrar o método/verbo da requisição (GET, POST, PUT, DELETE, entre outros), o tipo do conteúdo da requisição, o tamanho do conteúdo enviado na requisição, qual aplicação fez a requisição, o domínio em que o usuário está, entre outros.

Métodos

Como dito antes, nos cabeçalhos é possível encontrar o método/verbo da requisição, sendo os mais conhecidos:

GET
POST
PUT
DELETE

Embora nem sempre mudamos outros conteúdos do cabeçalho, no servidores com Express sempre precisamos falar quais métodos estamos utilizando para uma determinada rota.

Navegadores por padrão utilizam apenas os métodos GET e POST, portanto, para utilizar outro método é necessário utilizar JavaScript em uma requisição.

GET

Por padrão é utilizado quando queremos apenas o retorno de algum dado/página do servidor.

POST

Utilizado quando estamos enviando dados, como um formulário para servidor. Geralmente usado para criar um dado novo no servidor ou fazer um login de usuário.

PUT

Utilizado quando estamos enviando dados, como um formulário para servidor, porém, desta vez estamos modificando um dado já existente.

DELETE

Utilizado quando queremos deletar um dado existente.

Corpo

Corpo é um espaço na requisição HTTP onde os dados de um formulário são enviados ao servidor. Há vários tipos de conteúdos que podem ser enviados no corpo, por isso do campo tipo de contéudo dentro dos cabeçalhos.

Parâmetros (Query String)

Parâmetros, como o nome já indica, são parâmetros que passamos junto a rota, geralmente são utilizados como filtros para alguma requisição.

Um exemplo de parâmetro sendo passado para o servidor da Bing, onde pedimos ao servidor que nos retorne pesquisas relacionadas a restapi:

www.bing.com/search?q=restapi

Para criar um parâmetro precisamos iniciar com ?, seguido de campo=valor, caso queira adicionar mais parâmetros apenas insiria & seguido de campo=valor, como abaixo:

www.bing.com/search?q=restapi&form=QBLH

Geralmente os parâmetros são utilizados junto ao método GET, para filtragem de resultados no servidor. Porém nada impede de ser usados junto a outro método HTTP.

Recapitulando REST com Express

Agora que foi esclarecido alguns pontos principais de um servidor HTTP. Vamos ver alguns exemplos:

GET

Método: GET
Rota: /nomes:
URL: http//localhost:3000/nomes
Funcionalidade: retornar todos os nomes

app.get('/nomes', (req, res) => {
    ...
})

GET com parâmetros

Método: GET
Rota: /nomes
Parâmetros: ?maxLength=6&fisrtLetter=a
URL: http//localhost:3000/nomes?maxLength=6&fisrtLetter=a
Funcionalidade: retornar todos os nomes com o tamanho máximo de 6 letras que comecem com a letra a

app.get('/nomes', (req, res) => {
    const { maxLength, firstLetter } = req.query // pega os parametros
    ...
})

GET com rota dinâmica

Método: GET
Rota: /nomes/bruno
URL: http//localhost:3000/nomes/bruno
Funcionalidade: retornar informações sobre o nome bruno

app.get('/nomes/:nome', (req, res) => {
    const { nome } = req.params // pega valor da rota dinâmica
    ...
})

POST

Método: POST
Rota: /nomes
Corpo: { nome: 'bruno', significado: 'moreno, escuro' }
URL: http//localhost:3000/nomes
Funcionalidade: criar um novo nome com significado

app.post('/nomes', (req, res) => {
    const { nome, significado } = req.body // pega campos do corpo
    ...
})

PUT

Método: PUT
Rota dinâmica: /nomes/bruno
Corpo: { significado: 'claro' }
URL: http://localhost:3000/nomes/bruno
Funcionalidade: alterar o significado do nome bruno

app.put('/nomes/:nome', (req, res) => {
    const { nome } = req.params // pega valor da rota dinâmica
    const { significado } = req.body // pega o campo do corpo
    ...
})

DELETE

Método: DELETE
Rota dinâmica: /nomes/bruno
URL: http://localhost:3000/nomes/bruno
Funcionalidade: deletar o nome bruno

app.delete('/nomes/:nome', (req, res) => {
    const { nome } = req.params // pega valor da rota dinâmica
    ...
})

Recapitulando

Finalmente, completamos o que foi proposto nessa parte. Criamos nosso sistema de pastas, utilizamos o terminal para executar alguns comandos, inicializamos nosso repositório, iniciamos o projeto com Yarn, instalamos alguns módulos, criamos os scripts que vamos utilizar no projeto e foi explicado por cima como fazer uma requisição HTTP.

Agora estamos prontos para ir para a próxima fase, onde realmente colocamos a mão na massa e criamos nosso primeiro servidor com NodeJS.

Gostaria de agradecer de você ter chegado até aqui! Espero que eu tenha lhe passado algum conhecimento. Então vamos para a parte 2 desse tutorial!