Skip to content

GitLab

Backend · Changes

Page history
variaveis -> metodos no Nomenclatura de métodos authored by Vitor Jacom de Souza's avatar Vitor Jacom de Souza
Show whitespace changes
Inline Side-by-side
Backend.md
View page @ 49359204
<table>
<tr>
<th> [Home](home) </th>
<th> [Escopo e Cronograma](Escopo e Cronograma) </th>
<th> [Processo](Processo) </th>
<th> [Design/Mockups](Design & Mockups) </th>
<th> [Configuração](Configuracao) </th>
<th> [Arquitetura](Arquitetura) </th>
<th> [Infra](Infraestrutura) </th>
<th> [Código](Codigo) </th>
<th> [BD](Banco de dados) </th>
<th> [Backend](Backend) </th>
<th> [Frontend](Frontend) </th>
<th> [Qualidade](Qualidade) </th>
</tr>
<tr>
<th>
[Home](home)
</th>
<th>
[Escopo e Cronograma](Escopo%20e%20Cronograma)
</th>
<th>
[Processo](Processo)
</th>
<th>
[Design/Mockups](Design%20&%20Mockups)
</th>
<th>
[Configuração](Configuracao)
</th>
<th>
[Arquitetura](Arquitetura)
</th>
<th>
[Infra](Infraestrutura)
</th>
<th>
[Código](Codigo)
</th>
<th>
[BD](Banco%20de%20dados)
</th>
<th>
[Backend](Backend)
</th>
<th>
[Frontend](Frontend)
</th>
<th>
[Qualidade](Qualidade)
</th>
</tr>
</table>
## Backend
......@@ -37,11 +73,11 @@ Esta página centraliza informações sobre o [repositório Backend do projeto L
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.
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
O projeto Spring Boot do repositório de Backend do projeto está organizado seguindo um padrão *Controller-Service-Repository*, e esse padrão está refletido na organzação de pacotes do projeto. Optou-se por esse padrão pois, ainda que este padrão possa trazer problemas como acoplamento de regras de negócio e tecnologias de ORM (sendo estes problemas que poderiam ser resolvidos com um padrão de arquitetura limpa), ele segmenta o código em camadas visando uma separação de preocupações/responsabilidades (*Separation of concerns*). Além disso, é um padrão fácil de entender para desenvolvedores que não possuem muita experiência com Spring Boot ou com o desenvolvimento de APIs em geral.
O projeto Spring Boot do repositório de Backend do projeto está organizado seguindo um padrão _Controller-Service-Repository_, e esse padrão está refletido na organzação de pacotes do projeto. Optou-se por esse padrão pois, ainda que este padrão possa trazer problemas como acoplamento de regras de negócio e tecnologias de ORM (sendo estes problemas que poderiam ser resolvidos com um padrão de arquitetura limpa), ele segmenta o código em camadas visando uma separação de preocupações/responsabilidades (_Separation of concerns_). Além disso, é um padrão fácil de entender para desenvolvedores que não possuem muita experiência com Spring Boot ou com o desenvolvimento de APIs em geral.
Diante disso, os pacotes do projeto estão divididos da forma abaixo:
......@@ -88,7 +124,7 @@ Variáveis devem ser nomeadas em inglês e seguir o padrão **camelCase**, ou se
* 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
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:
......@@ -100,7 +136,7 @@ Além disso, para criar um código limpo e fácil de entender e realizar a manut
### Nomenclatura de métodos
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:
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:
......@@ -110,12 +146,12 @@ Variáveis devem ser nomeadas em inglês e seguir o padrão **camelCase**, ou se
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`
1. Métodos `protected`
1. Métodos `private`
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.
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:
......@@ -126,7 +162,7 @@ Abaixo segue um exemplo de uma API fictícia para ilustrar o padrão que deve se
* **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**
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**
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.
......@@ -165,7 +201,7 @@ A API disponibiliza várias anotações que podem ser utilizadas para validar di
* @Min: verifica se a variável/atributo tem valor igual ou maior que o valor mínimo informado.
* @Max: verifica se a variável/atributo tem valor igual ou menor que o valor máximo informado.
Supondo um cenário onde existe um *endpoint* de uma aplicação de biblioteca, para registro de novos livros, onde se recebe um corpo de requisição JSON, para realizar a validação precisariam ser feitos os ajustes abaixo:
Supondo um cenário onde existe um _endpoint_ de uma aplicação de biblioteca, para registro de novos livros, onde se recebe um corpo de requisição JSON, para realizar a validação precisariam ser feitos os ajustes abaixo:
1. Na classe DTO que modela os dados do corpo da requisição, adicionar as anotações nos atributos que se deseja validar.
......@@ -179,13 +215,13 @@ Supondo um cenário onde existe um *endpoint* de uma aplicação de biblioteca,
private Integer releaseYear;
}
```
1. Adicionar a anotação @Valid no método do controller onde se recebe o corpo da requisição. `java @PostMapping public BookResponse createBook(@Valid @RequestBody BookRequest bookRequest) { ... } `Para mais informações, leia [esta página](https://www.baeldung.com/java-validation).
2. Adicionar a anotação @Valid no método do controller onde se recebe o corpo da requisição. `java @PostMapping public BookResponse createBook(@Valid @RequestBody BookRequest bookRequest) { ... } `Para mais informações, leia [esta página](https://www.baeldung.com/java-validation).
## Documentação do Swagger
A ferramenta Swagger (OpenAPI) já foi configurada na aplicação, para documentação da API e para permitir testar requisições HTTP via interface gráfica. Diante disso, novos *controllers* REST que forem criados já vão ser exibidos na [url do Swagger](http://localhost:8080/swagger-ui/index.html) sem precisar de nenhuma configuração adicional.
A ferramenta Swagger (OpenAPI) já foi configurada na aplicação, para documentação da API e para permitir testar requisições HTTP via interface gráfica. Diante disso, novos _controllers_ REST que forem criados já vão ser exibidos na [url do Swagger](http://localhost:8080/swagger-ui/index.html) sem precisar de nenhuma configuração adicional.
No entanto, para garantir que a API esteja bem documentada, sugere-se utilizar as anotações da API do Swagger para descrever melhor quais são os propósitos de cada *endpoint* e quais são os significados de cada parâmetro de requisição e código de resposta. Seguem alguns exemplos de anotação abaixo:
No entanto, para garantir que a API esteja bem documentada, sugere-se utilizar as anotações da API do Swagger para descrever melhor quais são os propósitos de cada _endpoint_ e quais são os significados de cada parâmetro de requisição e código de resposta. Seguem alguns exemplos de anotação abaixo:
* @Operation: usada para descrever uma operação no Swagger (adicionar resumo, tags, etc)
* @Parameter: usada para descrever um parâmetro de uma requisição HTTP (propósito do parâmetro, exemplo de valor, etc)
......