Skip to content

GitLab

backend · Changes

Page history
Update backend authored by Matheus Machado Berwaldt's avatar Matheus Machado Berwaldt
Hide whitespace changes
Inline Side-by-side
backend.md
View page @ c9dd8fc5
......@@ -14,15 +14,108 @@ Esta página centraliza informações sobre o repositório Backend do projeto Po
## Escolha de tecnologias
TODO
Conforme mencionado na página de configuração de ambiente da Wiki, como tecnologias de Backend foram selecionadas a linguagem Java, junto ao framework Spring Boot, para o desenvolvimento da API, e o banco de dados PostgreSQL.
Esta decisão foi tomada com base em dois momentos. Em um primeiro momento, na primeira semana da Sprint 0, cada integrante citou as tecnologias com as quais tinha experiência e com qual *stack* tinha mais interesse em trabalhar (Frontend ou Backend) ao se apresentar. Este levantamento demonstrou que, existiria uma curva de aprendizado menor por grande parte do time já ter utilizado ou visto códigos em Java Spring Boot. Além disso, o Java quanto possue frameworks conhecidos para o desenvolvimento de APIs Backend, o que implica em muitos materiais didáticos e gratuitos para estudo na Internet.
## Organização do repositório
TODO
├── pointtils/ # Aplicação principal
│ ├── src/
│ │ ├── main/
│ │ │ ├── java/com/pointtils/pointtils/
│ │ │ │ ├── src/ # Código fonte principal
│ │ │ │ │ ├── application/ # Lógica de aplicação
│ │ │ │ │ │ ├── controllers/ # Controladores REST
│ │ │ │ │ │ ├── dto/ # Objetos de transferência
│ │ │ │ │ │ ├── mapper/ # Mapeadores DTO-Entity
│ │ │ │ │ │ └── services/ # Serviços de negócio
│ │ │ │ │ ├── core/ # Núcleo do domínio
│ │ │ │ │ │ └── domain/ # Entidades e enums
│ │ │ │ │ └── infrastructure/ # Infraestrutura
│ │ │ │ │ ├── configs/ # Configurações
│ │ │ │ │ └── repositories/ # Repositórios
│ │ ├── resources/ # Arquivos de configuração
│ └── test/ # Testes unitários
├── utils/ # Utilitários e serviços auxiliares
│ ├── sonarqube/ # Configuração SonarQube
│ │ └── Dockerfile
│ └── postgres/ # Configuração PostgreSQL
│ └── Dockerfile
├── docker-compose.yaml # Orquestração unificada de containers
└── sonarqube-docker-compose.yaml # Docker-compose antigo (legado)
## Padrões de código
### Nomenclatura de classes
Classes do projeto devem ser nomeadas em inglês e seguir o padrão **PascalCase**, ou seja, devem iniciar com letra maiúscula e cada palavra ou abreviatura no meio da frase também deve iniciar com letra maiúscula. Por exemplo:
* UserController :heavy_check_mark:
* User_Controller :x:
* Usercontroller :x:
* userController :x:
Além disso, com exceção do pacote model, os nomes das classes devem refletir o pacote onde elas estão localizadas, conforme o exemplo abaixo:
* :file_folder: config: ExemploConfig
* :file_folder: controller: ExemploController
* :file_folder: dt.request: ExemploRequest
* :file_folder: dt.response: ExemploResponse
* :file_folder: exception: ExemploException
* :file_folder: repository: ExemploRepository
* :file_folder: service: ExemploService
* :file_folder: util: ExemploUtil
### Nomenclatura de variáveis
Variáveis devem ser nomeadas em inglês e seguir o padrão **camelCase**, ou seja, devem iniciar com letra minúscula e cada palavra ou abreviatura no meio da frase deve iniciar com letra maiúscula. Por exemplo:
* isAdmin :heavy_check_mark:
* isadmin :x:
* is_Admin :x:
* IsAdmin :x:
A exceção são as variáveis constantes (que devem ser estáticas e finais) e enums, que devem seguir o padrão **SCREAMING_SNAKE_CASE**, onde as palavras no meio da frase são separadas por _underscores_ (_) e as letras devem ser todas maiúsculas. Por exemplo: API_BASE_URL
Além disso, para criar um código limpo e fácil de entender e realizar a manutenção depois, sempre nomeie as variáveis de forma que fique claro o seu propósito/o tipo de informação que ela possui. Para isso, seguem algumas dicas:
* Evitar abreviações.
* Para variáveis booleanas, não nomear apenas com substantivos, para deixar claro que é um booleano. Por exemplo, ao invés de "publish", usem "isPublished".
* Criar variáveis fáceis de pronunciar.
* Evitar dar nomes muito parecidos para duas variáveis.
* Não usar números mágicos. Se existir algum número que precisa ser utilizado no código, criar uma variável para este número para deixar claro o que ele significa.
### Nomenclatura de métodos
Métodos devem ser nomeadas em inglês e seguir o padrão **camelCase**, ou seja, devem iniciar com letra minúscula e cada palavra ou abreviatura no meio da frase deve iniciar com letra maiúscula. Por exemplo:
* findUserByName :heavy_check_mark:
* finduserbyname :x:
* find_User_By_Name :x:
* FindUserByName :x:
Além disso, para facilitar a leitura do código, em uma classe os métodos sempre devem estar organizados na ordem abaixo:
1. Métodos `public`
2. Métodos `protected`
3. Métodos `private`
### Padrões das APIs REST
A API desenvolvida para este projeto deverá seguir o estilo de arquitetura REST, muito utilizado para o desenvolvimento de APIs web, e para isso algumas restrições e boas práticas devem ser seguidos. Neste estilo, as informações gerenciadas pela aplicação e que possuem uma identificação única são chamadas de recursos (pode-se dizer que são mapeamentos conceituais/abstratos às entidades da aplicação), e as URIs da aplicação (_Uniform Resource Identifiers_) devem referenciar estes recursos de forma clara e padronizada.
Abaixo segue um exemplo de uma API fictícia para ilustrar o padrão que deve ser utilizado pela aplicação:
* **GET /v1/books** - buscar lista/coleção de livros
* **GET /v1/books/1** - buscar um livro específico a partir de um identificador único
* **POST /v1/books** - criar/registrar um novo livro
* **PATCH /v1/books/1** - editar um livro específico a partir de um identificador único (atualizações parciais)
* **PUT /v1/books/1** - editar um livro específico a partir de um identificador único (substituindo a representação do recurso pelos novos dados informados)
* **DELETE /v1/books/1** - deletar um livro específico a partir de um identificador único
Os recursos devem ser referenciados como substantivos no plural, e também deve se adicionar o versionamento da API no começo do _path_, conforme exemplos acima. Além disso, caso exista algum recurso que precise ser representado com mais de uma palavra, estas devem ser separadas por hífens, por exemplo: **/v1/loan-contracts**
TODO
Para mais informações, sugere-se a leitura [deste link](https://www.alura.com.br/artigos/rest-principios-e-boas-praticas), que traz algumas boas práticas de forma didática.
## Documentação do Swagger
......