Forem: Marcelo Pinheiro

Começando com Go - parte 2 - Estruturando a API

Marcelo Pinheiro — Wed, 17 Mar 2021 09:29:45 +0000

Fala meus consagrados e consagradas, beleza?

Bom, como eu havia dito ontem, hoje vamos criar nosso primeiro endpoint dentro da estrutura de clean architecture que estamos utilizando. Bora lá?

Rápida explicação sobre camadas de apresentação

Dentro da pasta api que havia sido criada, vamos criar uma outra pasta que vai guardar a implementação das nossas rotas. Seria o que chamamos da camada de apresentação.

No clean architecture, podemos ter várias camadas de apresentação diferentes (por exemplo, API, Mensageria e Linha de comando), e o tchan é que, neste caso, todas elas, caso tenham o mesmo propósito, implementam o mesmo caso de uso que é onde realmente mora nossa lógica de negócio.

Isso aumenta o aproveitamento de código, facilita o teste e ajuda o projeto a crescer de forma orgânica, sem bagunçar. Fique tranquilo se isso soa grego ainda, muito em breve nós vamos ver exemplos práticos do que eu to falando. Por enquanto, vamos nos ater aos detalhes de implementação.

Criando a estrutura

Como já explicado, dentro da pasta api, crie um outro diretório chamado handler, que é o diretório que vai guardar os nossos arquivos de rotas de api e lidar com a implementação delas (por isso o nome handler)

cd management_api/api
mkdir handler

Agora nós vamos dividir o que a nossa api tem que servir por domínio. E um domínio óbvio é o de empresas. Estamos escrevendo um Saas (software as a service, ou software como serviço, se você quiser saber mais, o link é este: https://neilpatel.com/br/blog/saas/) para ajudar empresas a se comunicarem melhor e mais efetivamente com seus clientes. Logo, uma empresa precisa conseguir se cadastrar no nosso sistema para, depois, poder cadastrar seus clientes, envios, e todo o resto em que vamos chegar. Dito isto, vamos criar o arquivo que vai lidar com todos os endpoints relacionados a empresa.

Dentro da pasta handler, crie um arquivo chamado company.go. E vamos começar a implementar nossa primeira rota. Vou fazer no mesmo modelo da parte 1, onde eu coloco o código comentado e explico o que cada linha faz.

//Especificamos que estas funções pertencem ao pacote handler.
//É dessa forma que vamos importar o que precisamos depois
package handler

import (
    "io"
    "net/http"

    "github.com/codegangsta/negroni"
    "github.com/gorilla/mux"
)

// Especificamos a função "createCompany()" e o tipo de retorno dela é http.Handler (vou explicar mais abaixo)
func createCompany() http.Handler {
        //Crio um handler http que responde uma string com o valor "teste"
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        io.WriteString(w, "Teste")
    })
}

//Crio uma função para especificar minhas rotas e passar a requisição para os handlers corretos
func MakeCompanyHandlers(router *mux.Router, n *negroni.Negroni) {
    router.Handle("/v1/company", n.With(
        negroni.Wrap(createCompany()),
    )).Methods("POST", "OPTIONS").Name("createCompany")
}

Alguns pontos importantes sobre o código acima:

http.Handler

Na função createCompany, nós retornamos um http.Handler. O tipo http.Handler é responsável por captar uma requisição (http.Request) e um "escritor" de resposta (http.ResponseWriter), dessa forma ele consegue ler os dados que vieram da requisição, como por exemplo, o body, e também responder a essa requisição, enviando também o body ou status code. Esse tipo (o http.Handler) é retornado da função http.HandlerFunc, que recebe como parâmetro outra função com a implementação do handler (neste caso, passamos uma função anônima, ou seja, não demos nome para ela e a implementação dela ja está especificada) e passa para esta função estes dois objetos que especifiquei mais acima. Uma forma mais fácil de entender o conceito é se não utilizarmos uma função anônima, como abaixo:

//Essa é a função handler que contém a implementação
func createCompanyHandler(w http.ResponseWriter, r *http.Request) {
    io.WriteString(w, "Teste")
}

//Essa é a função que transforma o handler acima em um http.Handler
func createCompany() http.Handler {
    //Era na linha abaixo, no lugar de createCompanyHandler, que estávamos passando a função anônima
    return http.HandlerFunc(createCompanyHandler)
}

Eu não vou seguir assim porque separar a implementação e a transformação em http.Handler faria nosso código ficar confuso e cheio de referências desnecessárias. Mas a ideia foi explicar este ponto de forma mais clara.

MakeCompanyHandlers

Bom, a função createCompany cria uma implementação que pode ser atrelada a uma rota, mas ainda não foi atrelada a nenhuma. Por enquanto, ela é só uma função sem aplicação. E é aí que surge a MakeCompanyHandlers. Essa função recebe um objeto mux.Router(lembra, lá no arquivo main.go, que criamos um router mux? Esse cara que ela recebe) e um personagem novo, o negroni.Negroni.

O mux.Router é um roteador simples, onde eu especifico as rotas e passo um handler para tratá-las. Condiz bem com o que a gente ta precisando, né?

Mas o que raios faz esse negroni? Bom, para entender o que ele faz, precisamos entender o que é uma middleware no contexto de api.

Middlewares são processos ou lógicas que precisam ser executados sempre que uma ou mais rotas são chamadas, mas que não fazem parte da implementação destas rotas. Por exemplo, um processo de autenticação das minhas rotas. Eu poderia, em todas as rotas que eu criar, validar se o usuário está logado, por exemplo. Mas eu teria que repetir o mesmo código em todas as minhas rotas, e repetir código nunca é bom por muitas razões, entre elas, se um dia eu mudasse a minha autenticação, teria que mudar em todas as rotas que criei. Isso, além de criar acoplamento no código (acoplamento é quando códigos que não deveriam depender um do outro, dependem), atrapalhando os testes, dificultando a manutenção, etc etc etc.

É por isso que utilizamos middlewares. No caso acima, eu apenas criaria um middleware responsável por autenticar o usuário antes de chamar a rota que eu preciso. Assim, se o usuário não estivesse logado, o middleware já pararia esse cara. E a minha rota ficaria só com o código que ela tem que ficar, sem se preocupar com autenticação.

E esse é o papel do negroni: prover uma estrutura simples para criarmos middlewares. No código, eu encapsulo a nossa função createCompany com o negroni utilizando a função negroni.Wrap, que converte um http.Handler (lembra dele?) em um negroni.Handler, e depois "registro" esse negroni.Handler na instância do negroni que recebi via parâmetro da função MakeCompanyHandlers para que ela "registre" esse novo handler e possa chamá-lo quando implementarmos um middleware.

O restante é bem simples, chamo a função router.Handle com a rota que eu quero servir a implementação da nossa createCompany(no caso, v1/company), especifico quais métodos HTTP ela deve responder (POST e OPTIONS) e dou um nome para essa rota (createCompany).

Ufa ... Bora terminar de implementar isso aí.

Integrando nossa rota

Voltando para o arquivo management_api/api/main.go, a primeira coisa que vamos fazer é gerar uma instância da classe (posso chamar assim em go? Não sei. Mas vou chamar de classe mesmo assim. Depois a turma me corrige) do negroni e depois, chamar a função MakeCompanyHandlers passando como parâmetro o router que já tínhamos e a instância do negroni.

//instancia o mux e o negroni
r := mux.NewRouter()
n := negroni.New()

//Chamo a função MakeCompanyHandlers que registra nossas rotas
handler.MakeCompanyHandlers(r, n)

o arquivo main.go inteiro fica assim

package main

import (
    "io"
    "log"
    "net/http"
    "os"
    "strconv"
    "time"

    "github.com/gorilla/context"
    "github.com/gorilla/mux"
    "github.com/marcelocpinheiro/communication-engine/management_api/config"
)

func main() {
    //instancia o mux e o negroni
    r := mux.NewRouter()
    n := negroni.New()

    //Chamo a função MakeCompanyHandlers que registra nossas rotas
    handler.MakeCompanyHandlers(r, n)

    // Repassa as rotas para o roteador
    http.Handle("/", r)

    // Cria um handler para a url "/ping", escreve "running" na tela e retorna o status 200
    r.HandleFunc("/ping", func(w http.ResponseWriter, r *http.Request) {
        io.WriteString(w, "Running")
        w.WriteHeader(http.StatusOK)
    })

    // Cria um logger para a aplicação
    logger := log.New(os.Stderr, "logger: ", log.Lshortfile)

    // Instancia um novo servidor com configurações específicas de timeout, endereço, log e handler
    srv := &http.Server{
        ReadTimeout:  5 * time.Second,
        WriteTimeout: 10 * time.Second,
        Addr:         ":" + strconv.Itoa(config.API_PORT),
        Handler:      context.ClearHandler(http.DefaultServeMux),
        ErrorLog:     logger,
    }

    //Printa no terminal a porta que a aplicação está ouvindo
    log.Printf("Listening on port %d", config.API_PORT)

   //inicia o servidor e, se houver erro, mata a aplicação e printa o erro
    err := srv.ListenAndServe()
    if err != nil {
        log.Fatal(err.Error())
    }
}

E é isso. Bora rodar?

go run management_api/api/main.go

Quando ver que tá rodando, bora criar uma requisição POST. Eu utilizo o Curl, mas você pode usar o Insomnia, o próprio Postman, fica a seu critério.

Anyway, o comando que você tem que rodar é

curl --location --request POST 'http://localhost:8080/v1/company'

Se tudo deu certo, agora você está vendo a resposta Teste, que é o que retornamos na nossa função createCompany lá no arquivo company.go, indicando que está tudo funcionando.

Fique ligado para acompanhar a série, e siga @devmediano no instagram, devo estar postando mais sobre essa série por lá.

No próximo post vamos criar a implementação do nosso primeiro endpoint, armazenar a empresa na base de dados, retornar um json e também criar um endpoint de listagem de empresas. Até lá!

Começando com Go - parte 1 - O início

Marcelo Pinheiro — Tue, 16 Mar 2021 10:01:32 +0000

Salve, meu povo, tudo certo? Espero que sim.

Bom, eu resolvi começar a aprender Golang, a linguagem para backend criada pelo Google. Não vou entrar em detalhes do que é a linguagem ou do porquê de eu decidir começar a aprendê-la. Tem materiais por aí muito melhor escritos do que qualquer coisa que eu pudesse colocar aqui. A intenção desta série é ir acompanhando e documentando meu desenvolvimento e descobertas e quem sabe, servir para alguém que estiver nessa mesma jornada.

O que vou construir?

Uma plataforma SaaS multitenancy que se integra a varias formas de envio de mensagem (E-mail, SMS, Voz, qualquer jeito que exista de se comunicar com um cliente) e, de forma escalável centralize estes envios, através de um api. Também teremos um portal em que seja possível administrar os meus envios, clientes, aplicações que poderão utilizar a api da ferramenta, etc.

Tenho algumas premissas para esta construção:

Implementação de uma base de dados (Postgres) com migrações
Implementação de uma mensageria (Rabbitmq) para gerenciar as solicitações de envio vindos da API.
Arquitetura escalável (microsserviços)
Docker
API Rest documentada com Swagger
Clean Architecture
Monorepo
Coverage de testes unitários acima de 80%

O resto, vamos ajustando durante essa jornada. Bora lá?

Antes: instale o go

Não é o propósito desta postagem explicar a instalação, tampouco como iniciar um projeto (dependencias, etc). A documentação é bem completa, da uma passada lá :D (btw, o link é: https://golang.org/)

No entanto, uma coisa que está me ajudando muito é utilizar as extensões de golang do vscode. Poupei bastante tempo com a questão das dependências do projeto.

Começando: estruturação

Sempre tive uma ótima experiência com clean architecture quando o assunto é organização do projeto. O software cresce de forma orgânica, fácil de ler e documentada. Como não vou inventar a roda, vou basear toda a minha estrutura do projeto no repositório https://github.com/eminetto/clean-architecture-go-v2 (Obrigado, eminetto). Achei a estrutura simples yet completa, me parece ser um bom início.

Então, começando:

A primeira coisa que fiz foi criar um diretório chamado communication-engine, que vai ser a raiz do meu projeto e dentro dele, um diretório management_api, que vai ser o diretório que vai guardar a minha api responsável por servir, futuramente, a aplicação front-end.

mkdir -p communication-engine/management_api

Dentro da pasta management_api, eu criei dos diretórios, o api, que vai guardar todos os meus arquivos relacionados a api (handlers, middlewares, modelos de apresentação, etc) e também a pasta config, cujo propósito é autodescritivo.

cd communication-engine/management_api
mkdir api
mkdir config

Na pasta config, eu criei o arquivo config_dev.go, com o seguinte conteúdo

package config

const (
    DB_USER     = "communication_engine"
    DB_PASSWORD = "communication_engine"
    DB_DATABASE = "communication_engine"
    DB_HOST     = "127.0.0.1"
    API_PORT    = 8080
)

Já na pasta api, o primeiro arquivo que criei foi o main.go, que vai ser o arquivo de entrada da nossa api. A implementação dele, por enquanto, é bem simples:

package main

import (
    "io"
    "log"
    "net/http"
    "os"
    "strconv"
    "time"

    "github.com/gorilla/context"
    "github.com/gorilla/mux"
    "github.com/marcelocpinheiro/communication-engine/management_api/config"
)

func main() {
    //Instância um novo roteador MUX, um roteador http para go
    r := mux.NewRouter()

    // Repassa as rotas para o roteador
    http.Handle("/", r)

    // Cria um handler para a url "/ping", escreve "running" na tela e retorna o status 200
    r.HandleFunc("/ping", func(w http.ResponseWriter, r *http.Request) {
        io.WriteString(w, "Running")
        w.WriteHeader(http.StatusOK)
    })

    // Cria um logger para a aplicação
    logger := log.New(os.Stderr, "logger: ", log.Lshortfile)

    // Instancia um novo servidor com configurações específicas de timeout, endereço, log e handler
    srv := &http.Server{
        ReadTimeout:  5 * time.Second,
        WriteTimeout: 10 * time.Second,
        Addr:         ":" + strconv.Itoa(config.API_PORT),
        Handler:      context.ClearHandler(http.DefaultServeMux),
        ErrorLog:     logger,
    }

    //Printa na tela a porta que a aplicação está ouvindo
    log.Printf("Listening on port %d", config.API_PORT)

   //inicia o servidor e, se houver erro, mata a aplicação e printa o erro
    err := srv.ListenAndServe()
    if err != nil {
        log.Fatal(err.Error())
    }
}

Importante: A importação da config se você estiver replicando esse projeto vai ser de acordo com o endereço de repositório que você especificou para o seu projeto, o que obviamente vai ser diferente do meu (espero).

Vamos ver se isso está funcionando?

go run management_api/api/main.go

Se tudo está certo, você deve estar vendo o seguinte output na sua tela:

2021/03/16 09:55:57 Listening on port 8080

E aí, o que resta é abrir o seu browser e bater na url http://localhost:8080/ping. Você deve ver a palavra "Running" na tela. É isso, criamos o primeiro endpoint.

Fique ligado para acompanhar a série, e siga @devmediano no instagram, devo estar postando mais sobre essa série por lá.

No próximo post vamos criar o primeiro endpoint dentro da estrutura do router, e já responder requisições post dentro da estrutura do clean architecture que está sendo utilizada. Até lá!