- Descrição do projeto
- Pré-requisitos
- Tecnologias
- Iniciando o uso deste projeto
- Arquitetura do projeto
- Banco de dados
- Migrations com Flyway
- Sobre padrões no versionamento do código
Projeto template base para novas solução de API REST com as seguintes pré-configurações:
- Arquitetura em 3 camadas
- Docker para a aplicação
- Docker para o banco de dados com PostgreSQL
- Consultas com ORM configuradas
- Open API docs com Swagger
- Migrations com Flyway
- Spring Boot
Como pré requisitos temos os seguintes itens:
- Java 11 ou superior
- Docker
- Maven
- Flyway
As seguintes ferramentas foram usadas na construção do projeto:
git clone git@github.com:dbserver/dbcamp-template-api.gitcd dbcamp-template-apimvn install:install-file -Dfile=./pom.xml -DpomFile=./pom.xmlmvn clean packagejava -jar target/template-0.0.1-SNAPSHOT.jarO servidor inciará na porta:4767 - acesse http://localhost:4767
Para acessar o Open APi (swagger) da aplicação acesso o link abaixo;
http://localhost:4767/swagger-ui/index.html
Para acessar o APi docs (json file) da aplicação acesso o link abaixo;
http://localhost:4767/v3/api-docs
A arquitetura do projeto da-se com uma divisão em 3 camadas com responsabilidades distintas:
Mantenha essa camada o mais fina possível e limitada à mecânica das operações MVC, por exemplo, recebendo e validando as entradas, manipulando o objeto modelo, retornando o objeto MovedAndView apropriado e assim por diante. Todas as operações relacionadas ao negócio devem ser feitas em classes de serviço. As classes do controlador geralmente são colocadas em um pacote do controlador.
Cálculos, transformações de dados, processos de dados e validações entre registros (regras de negócios) geralmente são feitos nessa camada. Eles são chamados pelas classes do controlador e podem chamar repositórios ou outros serviços. As classes de serviço geralmente são colocadas em um pacote de serviço.
A responsabilidade dessa camada é limitada às operações Criar, Recuperar, Atualizar e Excluir (CRUD) em uma fonte de dados, que geralmente é um banco de dados relacional ou não relacional. As classes de repositório geralmente são colocadas em um pacote de repositório.
- Abra uma nova janela de comando e execute o comando abaixo.
docker pull postgres- Verificando se a o download da imagem foi realizado com sucesso.
docker images- Verifique se a imagem do postgres aparece conforme abaixo
postgres latest 80c558ffdc31 7 days ago 379MB
docker run --name postgresql -e POSTGRES_USER=templateuser -e POSTGRES_PASSWORD=templatepassword -p 5432:5432 -d postgresNo comando dado acima,
- PostgreSQL é o nome do Docker Container.
- -e POSTGRES_USER é o parâmetro que define um nome de usuário exclusivo para o banco de dados Postgres.
- -e POSTGRES_PASSWORD é o parâmetro que permite definir a senha do banco de dados Postgres.
- -p 5432:5432 é o parâmetro que estabelece uma conexão entre a porta do host e a porta do contêiner do Docker. Nesse caso, ambas as portas são fornecidas como 5432, o que indica que as solicitações enviadas às portas do host serão redirecionadas automaticamente para a porta do contêiner do Docker. Além disso, 5432 também é a mesma porta onde o PostgreSQL estará aceitando requisições do cliente.
- -d é o parâmetro que executa o Docker Container no modo desanexado, ou seja, em segundo plano. Se você acidentalmente fechar ou encerrar o Prompt de Comando, o Docker Container ainda será executado em segundo plano.
- Postgres é o nome da imagem do Docker que foi baixada anteriormente para executar o Docker Container.
Para validar se o banco de dados foi executado com sucesso execute o comando abaixo
docker ps --filter "name=postgresql"Deve ser exibido algo similar o abaixo
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
f33be708db53 postgres "docker-entrypoint.s…" 4 minutes ago Up 4 minutes 0.0.0.0:5432->5432/tcp postgresql
Para gerenciar, executar scripts sugerimos a utilização do DBeaver
- Realize a instalação do flyway de acordo com o seu sistema operacional nesse link aqui
- Verifique se o comando flyway é reconhecido no terminal executando
flyway -vObservações importantes:
- O Flyway vem desabilitado para auto migrations por padrão, logo você terá que realizar as migrations manualmente
- As migrações pendentes em uma única transação em vez de uma transação por migrações pendentes. Portanto, se uma migração falhar, todas as migrações executadas antes serão revertidas.
Já existe uma pasta criada onde colocar o arquivo de migração; está localizado em resources/db/migration. No entanto, o nome do arquivo deve seguir um padrão específico:
- Parte 1: É a letra "v" em maiúscula. O nome sempre começa com esta letra.
- Parte 2: É a versão de migração; pode ser 1, 001, 1.2.3, 2021.09.24.12.55.32, ... você entendeu.
- Parte 3: São os dois sublinhados (_)
- Parte 4: A descrição da migração; você pode separar as palavras com um sublinhado ou um espaço.
- Parte 5: É a extensão do arquivo.sql
Para criar arquivos de migrations siga os passos abaixo
- Crie um arquivo de migration com o padrão de nome descrito acima dentro do caminmho resources/db/migration
- Execute o comando abaixo para executar as migrações
flyway migrate -configFiles=flyway.propertiesObservação: você deve estar no diretório do projeto para executar o comando.
Pode acontecer que você queira reverter uma migração; execute o comando abaixo:
flyway undo -configFiles=flyway.propertiesÉ desejado que seja utilizado o padrão de Commits Semânticos. Pode entender melhor nesse link