DEV Community: Maria Leitão

Documentando uma API com Java Spring Boot usando Swagger

Maria Leitão — Tue, 30 Jul 2024 22:26:11 +0000

Passos para documentar uma RESTful API em Java Spring Boot com Swagger

Adicionar dependências do Swagger

Adicione as dependências do Swagger no arquivo pom.xml:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Configurar o Swagger

Crie uma classe de configuração do Swagger:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("My API")
                        .description("This is a RESTful API in Java Spring Boot using Swagger")
                        .version("1.0")
                        .contact(new springfox.documentation.service.Contact("API Support", "", "support@example.com"))
                        .build());
    }
}

Adicionar Anotações Swagger para Descrever Endpoints, Parâmetros e Respostas

Anotações de Operação:

Para cada endpoint, adicione anotações com detalhes da requisição HTTP, caminho e um resumo básico.

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/movies")
@Api(tags = "Movies")
public class MovieController {

    @ApiOperation(value = "Get a list of movies", notes = "Retrieves a list of movies")
    @GetMapping
    public List<Movie> getMovies() {
        // code ...
    }

    @ApiOperation(value = "Get a movie by ID", notes = "Retrieves a movie by its ID")
    @GetMapping("/{id}")
    public Movie getMovie(
            @ApiParam(value = "ID of the movie to be obtained", required = true) 
            @PathVariable String id) {
        // code ...
    }
}

Definindo Modelos de Resposta:

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "Details about the Movie")
public class Movie {

    @ApiModelProperty(notes = "The unique ID of the movie")
    private String id;

    @ApiModelProperty(notes = "The name of the movie")
    private String name;

    // getters and setters
}

@ApiModel(description = "Details about the ErrorResponse")
public class ErrorResponse {

    @ApiModelProperty(notes = "The error code")
    private int code;

    @ApiModelProperty(notes = "The error message")
    private String message;

    // getters and setters
}

Gerar a Documentação do Swagger

Inicie a aplicação Spring Boot e acesse a interface Swagger UI no navegador:

http://localhost:8080/swagger-ui.html

Boas Práticas de Documentação

Use linguagem descritiva e sucinta para ajudar no entendimento da API.
Organize a ordem das anotações de forma lógica para seguir um fluxo claro e padronizado, facilitando a manutenção.
Atualize a documentação sempre que houverem mudanças na API para mantê-la consistente e útil.

Seguindo esses passos, você poderá documentar sua API em Java Spring Boot usando Swagger de maneira eficaz e clara.

Building a Simple Load Balancer in Go

Maria Leitão — Thu, 11 Jul 2024 17:27:13 +0000

Load balancing is an essential component in distributed systems, ensuring that incoming requests are evenly distributed across multiple backend servers. In this post, we’ll build a simple, thread-safe load balancer in Go using a round-robin algorithm. We’ll walk through the code step-by-step, explaining how each part works and how you can adapt it to fit your needs.

You can clone the project from my GitHub repository.

What We’ll Build

Our load balancer will:

Distribute incoming HTTP requests among multiple backend servers.
Use a round-robin algorithm to ensure even distribution.
Be thread-safe, using sync.Mutex for safe access to shared resources.
Allow dynamic addition and removal of backend servers.

Prerequisites

Make sure you have Go 1.16 or later installed on your machine.

Code Overview

Here’s the complete code for our load balancer:

package main

import (
    "fmt"
    "net/http"
    "net/http/httputil"
    "net/url"
    "sync"
)

// Server interface defines the methods that a backend server should implement.
type Server interface {
    Address() string
    IsAlive() bool
    Serve(rw http.ResponseWriter, r *http.Request)
}

// SimpleServer implements the Server interface and represents a single backend server.
type SimpleServer struct {
    address string
    proxy   *httputil.ReverseProxy
}

// Address returns the address of the server.
func (s *SimpleServer) Address() string {
    return s.address
}

// IsAlive returns the health status of the server. Always returns true in this example.
func (s *SimpleServer) IsAlive() bool {
    return true
}

// Serve forwards the request to the backend server using the reverse proxy.
func (s *SimpleServer) Serve(rw http.ResponseWriter, r *http.Request) {
    s.proxy.ServeHTTP(rw, r)
}

// LoadBalancer manages the distribution of requests to multiple backend servers.
type LoadBalancer struct {
    port            string
    roundRobinCount int
    servers         []Server
    mu              sync.Mutex
}

// NewLoadBalancer creates a new LoadBalancer instance.
func NewLoadBalancer(port string, servers []Server) *LoadBalancer {
    return &LoadBalancer{
        port:            port,
        roundRobinCount: 0,
        servers:         servers,
    }
}

// NewSimpleServer creates a new SimpleServer instance.
func NewSimpleServer(address string) *SimpleServer {
    serverURL, err := url.Parse(address)
    if err != nil {
        panic(fmt.Sprintf("Error parsing server URL %s: %v", address, err))
    }

    return &SimpleServer{
        address: address,
        proxy:   httputil.NewSingleHostReverseProxy(serverURL),
    }
}

// getNextAvailableServer returns the next available server using a round-robin algorithm.
func (lb *LoadBalancer) getNextAvailableServer() Server {
    lb.mu.Lock()
    defer lb.mu.Unlock()

    for i := 0; i < len(lb.servers); i++ {
        server := lb.servers[lb.roundRobinCount%len(lb.servers)]
        lb.roundRobinCount++
        if server.IsAlive() {
            return server
        }
    }

    if len(lb.servers) > 0 {
        return lb.servers[0]
    }

    return nil
}

// serveProxy forwards the request to the next available backend server.
func (lb *LoadBalancer) serveProxy(rw http.ResponseWriter, r *http.Request) {
    targetServer := lb.getNextAvailableServer()
    if targetServer == nil {
        http.Error(rw, "No available servers", http.StatusServiceUnavailable)
        return
    }

    fmt.Printf("Forwarding request to address %s\n", targetServer.Address())
    targetServer.Serve(rw, r)
}

func main() {
    // List of backend servers.
    servers := []Server{
        NewSimpleServer("https://www.facebook.com"),
        NewSimpleServer("http://www.bing.com"),
        NewSimpleServer("https://www.google.com"),
    }
    lb := NewLoadBalancer("8000", servers)
    handleRedirect := func(rw http.ResponseWriter, r *http.Request) {
        lb.serveProxy(rw, r)
    }
    http.HandleFunc("/", handleRedirect)

    fmt.Printf("Serving requests at 'localhost:%v'\n", lb.port)
    http.ListenAndServe(":"+lb.port, nil)
}

Step-by-Step Explanation

1. Server Interface

The Server interface defines the methods that any backend server should implement:

type Server interface {
    Address() string
    IsAlive() bool
    Serve(rw http.ResponseWriter, r *http.Request)
}

2. SimpleServer Struct

The SimpleServer struct implements the Server interface. It holds the server address and a reverse proxy to forward requests:

type SimpleServer struct {
    address string
    proxy   *httputil.ReverseProxy
}

func (s *SimpleServer) Address() string {
    return s.address
}

func (s *SimpleServer) IsAlive() bool {
    return true
}

func (s *SimpleServer) Serve(rw http.ResponseWriter, r *http.Request) {
    s.proxy.ServeHTTP(rw, r)
}

3. LoadBalancer Struct

The LoadBalancer struct manages the distribution of requests to multiple backend servers. It uses a round-robin algorithm to select the next available server:

type LoadBalancer struct {
    port            string
    roundRobinCount int
    servers         []Server
    mu              sync.Mutex
}

func NewLoadBalancer(port string, servers []Server) *LoadBalancer {
    return &LoadBalancer{
        port:            port,
        roundRobinCount: 0,
        servers:         servers,
    }
}

func (lb *LoadBalancer) getNextAvailableServer() Server {
    lb.mu.Lock()
    defer lb.mu.Unlock()

    for i := 0; i < len(lb.servers); i++ {
        server := lb.servers[lb.roundRobinCount%len(lb.servers)]
        lb.roundRobinCount++
        if server.IsAlive() {
            return server
        }
    }

    if len(lb.servers) > 0 {
        return lb.servers[0]
    }

    return nil
}

func (lb *LoadBalancer) serveProxy(rw http.ResponseWriter, r *http.Request) {
    targetServer := lb.getNextAvailableServer()
    if targetServer == nil {
        http.Error(rw, "No available servers", http.StatusServiceUnavailable)
        return
    }

    fmt.Printf("Forwarding request to address %s\n", targetServer.Address())
    targetServer.Serve(rw, r)
}

4. Main Function

The main function initializes the load balancer with a list of backend servers and starts the HTTP server:

func main() {
    servers := []Server{
        NewSimpleServer("https://www.facebook.com"),
        NewSimpleServer("http://www.bing.com"),
        NewSimpleServer("https://www.google.com"),
    }
    lb := NewLoadBalancer("8000", servers)
    handleRedirect := func(rw http.ResponseWriter, r *http.Request) {
        lb.serveProxy(rw, r)
    }
    http.HandleFunc("/", handleRedirect)

    fmt.Printf("Serving requests at 'localhost:%v'\n", lb.port)
    http.ListenAndServe(":"+lb.port, nil)
}

Adapting the Load Balancer

This basic load balancer can be extended in several ways:

Health Checks: Implement health checks to periodically check the status of backend servers and mark them as unavailable if they fail.
Dynamic Server Management: Add endpoints to dynamically add or remove backend servers.
Load Balancing Algorithms: Implement different load balancing algorithms like least connections, IP hash, etc.

Conclusion

We’ve built a simple load balancer in Go that uses a round-robin algorithm to distribute incoming requests. This example serves as a starting point, and you can extend it to meet more complex requirements. Happy coding!

ACID: O Pilar dos Bancos de Dados Relacionais

Maria Leitão — Wed, 10 Jul 2024 15:05:00 +0000

O Que é ACID em Bancos de Dados Relacionais?

Se você já trabalhou com bancos de dados relacionais, provavelmente já se deparou com a sigla ACID. Mas o que exatamente isso significa e por que é tão importante? Vamos explorar cada componente de ACID e entender o seu papel nos sistemas de banco de dados.

O que é ACID?

ACID é um acrônimo que representa quatro propriedades fundamentais garantidas pelos sistemas de banco de dados relacionais para garantir a integridade e a confiabilidade das transações. Estas propriedades são: Atomicidade, Consistência, Isolamento e Durabilidade.

Componentes do ACID

Atomicidade (Atomicity):

Conceito: Assegura que todas as operações dentro de uma transação são completadas com sucesso ou nenhuma delas é aplicada.
Exemplo real: Em uma transação de transferência bancária, se a transferência do valor da Conta A para a Conta B falhar, nenhuma das contas deve ser alterada.

Consistência (Consistency):

Conceito: Garante que uma transação leva o banco de dados de um estado válido para outro estado válido, preservando as regras de integridade.
Exemplo real: Após uma transação, todas as regras de integridade, como restrições e gatilhos, são respeitadas. Se um depósito for feito, o saldo total do banco deve refletir essa mudança.

Isolamento (Isolation):

Conceito: Assegura que as operações de uma transação são isoladas de outras transações simultâneas. As transações não devem interferir umas com as outras.
Exemplo real: Se duas pessoas estão comprando o último item disponível em uma loja online ao mesmo tempo, o sistema deve garantir que apenas uma transação finalize a compra.

Durabilidade (Durability):

Conceito: Garante que uma vez que uma transação foi concluída com sucesso, suas alterações são permanentes, mesmo em caso de falha do sistema.
Exemplo real: Após a confirmação de um pedido em um e-commerce, os detalhes do pedido devem permanecer registrados, mesmo que ocorra uma queda de energia logo em seguida.

Importância do ACID

Confiabilidade: ACID é crucial para garantir que os bancos de dados se comportem de maneira previsível e confiável.
Integridade de Dados: Mantém a integridade dos dados, assegurando que eles não fiquem em um estado incorreto.
Segurança: Proporciona uma camada adicional de segurança, garantindo que as transações sejam corretamente registradas e mantidas.

Conclusão

As propriedades ACID são muito importante nos bancos de dados relacionais, já que garantem que as transações serão realizadas de forma segura, confiável e eficiente. Compreender ACID é fundamental para qualquer profissional que trabalhe com bancos de dados, pois garante a integridade e a consistência dos dados, aspectos que são vitais em qualquer aplicação crítica.

Documentando uma API com Go Swagger

Maria Leitão — Thu, 04 Jul 2024 16:34:26 +0000

Passos para documentar uma RESTful API em Go com Swagger

Instalar o Swagger Tools

go get -u github.com/swaggo/swag/cmd/swag

Adicionar Swagger Annotations para descrever endpoints, parâmetros e respostas

Swagger Info Annotation:

No topo do arquivo main.go ou em um arquivo específico, adicione informações como versão, título e descrição.

// @title My API
// @version 1.0
// @description This is a RESTful API in Go using Swagger
// @contact.name API Support
// @contact.email support@example.com
// @host localhost:8000
// @BasePath /v1

Operation Annotations:

Para cada endpoint, anote a function com os detalhes da requisição HTTP, path, e um resumo básico.

// @Summary Get a list of movies
// @Description Retrieves a list of movies
// @Tags movies
// @Accept json
// @Produce json
// @Success 200 {array} Movie
// @Router /movies [get]
func getMovies(w http.ResponseWriter, r *http.Request) {
    // code ...
}

Parameter Annotations:

Descreva o path, a query, e o body da requisição.

// previous Operation Annotations...

// @Param id path string true "Movie ID"
// @Success 200 {object} Movie
// @Failure 404 {object} ErrorResponse
// @Router /movies/{id} [get]
func getMovie(w http.ResponseWriter, r *http.Request) {
    // code ...
}

Response Annotations:

Defina a estrutura de responses retornadas pelos endpoints da API.

// Movie struct
// @Description structure of Movie
type Movie struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

// ErrorResponse struct
// @Description structure of ErrorResponse
type ErrorResponse struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
}

Gerar a Documentação do Swagger:

Rode o comando swag init no diretório do projeto pra gerar o Swagger JSON e YAML baseados nas anotações. Se houverem mudanças nas anotações, esse comando deve ser rodado novamente.

swag init

Suba a aplicação e entrar na Swagger UI (http://localhost:8000/swagger/index.html) pra interagir com a documentação.

Boas práticas de documentação:

Use linguagem descritiva e sucinta pra ajudar no entendimento da API.
Organize a ordem das anotações de forma lógica pra seguir um fluxo claro e padronizado, facilitando a manutenção.