Tutorial: Desenvolvendo uma API RESTful com Go e Gin
Este tutorial apresenta o básico de como escrever uma API de serviço web RESTful com Go e o Gin Web Framework (Gin).
Você vai tirar o melhor proveito deste tutorial se já tiver familiaridade básica com Go e suas ferramentas. Se este for seu primeiro contato com Go, veja Tutorial: Comece com Go para uma introdução rápida.
O Gin simplifica muitas tarefas de programação associadas à criação de aplicações web, incluindo serviços web. Neste tutorial, você vai usar o Gin para rotear requisições, obter detalhes das requisições e serializar JSON para as respostas.
Neste tutorial, você vai criar um servidor de API RESTful com dois endpoints. O seu projeto de exemplo será um repositório de dados sobre discos de jazz vintage.
O tutorial inclui as seguintes seções:
- Projetar os endpoints da API.
- Criar uma pasta para o seu código.
- Criar os dados.
- Escrever um handler para retornar todos os itens.
- Escrever um handler para adicionar um novo item.
- Escrever um handler para retornar um item específico.
Observação: para outros tutoriais, veja Tutoriais.
Para testar este tutorial como um tutorial interativo que você completa no Google Cloud Shell, clique no botão abaixo.
Pré-requisitos
- Go. Recomendamos usar a versão mais recente do Go para seguir este tutorial. Para as instruções de instalação, veja Instalando o Go.
- Uma ferramenta para editar o seu código. Qualquer editor de texto que você tenha vai funcionar bem.
- Um terminal de linha de comando. O Go funciona bem em qualquer terminal no Linux e no Mac, e no PowerShell ou no cmd do Windows.
- A ferramenta curl. No Linux e no Mac, ela normalmente já está instalada. No Windows, ela vem incluída no Windows 10 Insider build 17063 e posteriores. Para versões mais antigas do Windows, talvez seja necessário instalá-la. Para mais detalhes, veja Tar e Curl chegam ao Windows.
Projetar os endpoints da API
Você vai criar uma API que dá acesso a uma loja que vende gravações vintage em vinil. Assim, você precisará fornecer endpoints pelos quais um cliente possa obter e adicionar álbuns para os usuários.
Ao desenvolver uma API, normalmente você começa projetando os endpoints. Os usuários da sua API terão mais sucesso se os endpoints forem fáceis de entender.
Estes são os endpoints que você vai criar neste tutorial.
/albums
GET– Obter uma lista de todos os álbuns, retornada como JSON.POST– Adicionar um novo álbum a partir dos dados da requisição enviados como JSON.
/albums/:id
GET– Obter um álbum pelo seu ID, retornando os dados do álbum como JSON.
Em seguida, você vai criar uma pasta para o seu código.
Criar uma pasta para o seu código
Para começar, crie um projeto para o código que você vai escrever.
-
Abra um prompt de comando e mude para o seu diretório home.
No Linux ou Mac:
$ cdNo Windows:
C:\> cd %HOMEPATH% -
No prompt de comando, crie um diretório para o seu código chamado web-service-gin.
$ mkdir web-service-gin $ cd web-service-gin -
Crie um módulo no qual você possa gerenciar dependências.
Execute o comando
go mod init, informando o caminho do módulo em que o seu código ficará.$ go mod init example/web-service-gin go: creating new go.mod: module example/web-service-ginEste comando cria um arquivo go.mod, no qual as dependências que você adicionar serão listadas para controle. Para saber mais sobre como nomear um módulo com um caminho de módulo, veja Gerenciando dependências.
Em seguida, você vai projetar as estruturas de dados para lidar com os dados.
Criar os dados
Para manter as coisas simples no tutorial, você vai armazenar os dados em memória. Uma API mais típica interagiria com um banco de dados.
Observe que armazenar os dados em memória significa que o conjunto de álbuns será perdido sempre que você parar o servidor, e recriado quando você o iniciar.
Escrever o código
-
Usando o seu editor de texto, crie um arquivo chamado main.go na pasta web-service-gin. Você vai escrever o seu código Go neste arquivo.
-
No main.go, no topo do arquivo, cole a seguinte declaração de pacote.
package mainUm programa independente (em oposição a uma biblioteca) sempre fica no pacote
main. -
Logo abaixo da declaração de pacote, cole a seguinte declaração da struct
album. Você vai usá-la para armazenar os dados dos álbuns em memória.Tags de struct, como
json:"artist", especificam qual deve ser o nome de um campo quando o conteúdo da struct é serializado em JSON. Sem elas, o JSON usaria os nomes dos campos com a inicial maiúscula, um estilo menos comum em JSON.// album represents data about a record album. type album struct { ID string `json:"id"` Title string `json:"title"` Artist string `json:"artist"` Price float64 `json:"price"` } -
Logo abaixo da declaração de struct que você acabou de adicionar, cole o seguinte slice de structs
album, com os dados que você vai usar para começar.// albums slice to seed record album data. var albums = []album{ {ID: "1", Title: "Blue Train", Artist: "John Coltrane", Price: 56.99}, {ID: "2", Title: "Jeru", Artist: "Gerry Mulligan", Price: 17.99}, {ID: "3", Title: "Sarah Vaughan and Clifford Brown", Artist: "Sarah Vaughan", Price: 39.99}, }
Em seguida, você vai escrever o código para implementar o seu primeiro endpoint.
Escrever um handler para retornar todos os itens
Quando o cliente fizer uma requisição em GET /albums, você quer retornar todos os álbuns como JSON.
Para isso, você vai escrever o seguinte:
- Lógica para preparar a resposta
- Código que mapeia o caminho da requisição para a sua lógica
Observe que essa é a ordem inversa da ordem de execução em tempo de execução, mas você está adicionando as dependências primeiro e, depois, o código que depende delas.
Escrever o código
-
Logo abaixo do código da struct que você adicionou na seção anterior, cole o código a seguir para obter a lista de álbuns.
A função
getAlbumscria JSON a partir do slice de structsalbum, escrevendo o JSON na resposta.// getAlbums responds with the list of all albums as JSON. func getAlbums(c *gin.Context) { c.IndentedJSON(http.StatusOK, albums) }Neste código, você:
-
Escreve uma função
getAlbumsque recebe um parâmetrogin.Context. Observe que você poderia ter dado a esta função qualquer nome: nem o Gin nem o Go exigem um formato específico de nome de função.gin.Contexté a parte mais importante do Gin. Ele carrega os detalhes da requisição, valida e serializa JSON, entre outras coisas. (Apesar do nome parecido, isso é diferente do pacote embutidocontextdo Go.) -
Chama
Context.IndentedJSONpara serializar a struct em JSON e adicioná-la à resposta.O primeiro argumento da função é o código de status HTTP que você quer enviar ao cliente. Aqui, você está passando a constante
StatusOK, do pacotenet/http, para indicar200 OK.Observe que você pode substituir
Context.IndentedJSONpor uma chamada aContext.JSONpara enviar um JSON mais compacto. Na prática, a forma indentada é muito mais fácil de trabalhar ao depurar, e a diferença de tamanho costuma ser pequena.
-
-
Perto do topo do main.go, logo abaixo da declaração do slice
albums, cole o código abaixo para associar a função handler a um caminho de endpoint.Isso estabelece uma associação em que
getAlbumstrata as requisições ao caminho de endpoint/albums.func main() { router := gin.Default() router.GET("/albums", getAlbums) router.Run("localhost:8080") }Neste código, você:
-
Inicializa um roteador Gin usando
Default. -
Usa a função
GETpara associar o método HTTPGETe o caminho/albumsa uma função handler.Observe que você está passando o nome da função
getAlbums. Isso é diferente de passar o resultado da função, o que você faria passandogetAlbums()(note os parênteses). -
Usa a função
Runpara anexar o roteador a umhttp.Servere iniciar o servidor.
-
-
Perto do topo do main.go, logo abaixo da declaração de pacote, importe os pacotes de que você vai precisar para dar suporte ao código que acabou de escrever.
As primeiras linhas do código devem ficar assim:
package main import ( "net/http" "github.com/gin-gonic/gin" ) -
Salve o main.go.
Executar o código
-
Comece a rastrear o módulo Gin como dependência.
Na linha de comando, use
go getpara adicionar o módulo github.com/gin-gonic/gin como dependência do seu módulo. Use um argumento de ponto para indicar “obter as dependências do código no diretório atual”.$ go get . go get: added github.com/gin-gonic/gin v1.7.2O Go resolveu e baixou essa dependência para satisfazer a declaração
importque você adicionou na etapa anterior. -
Na linha de comando, no diretório que contém o main.go, execute o código. Use um argumento de ponto para indicar “executar o código no diretório atual”.
$ go run .Com o código em execução, você tem um servidor HTTP ativo para o qual pode enviar requisições.
-
Em uma nova janela de linha de comando, use
curlpara fazer uma requisição ao seu serviço web em execução.$ curl http://localhost:8080/albumsO comando deve exibir os dados com que você populou o serviço.
[ { "id": "1", "title": "Blue Train", "artist": "John Coltrane", "price": 56.99 }, { "id": "2", "title": "Jeru", "artist": "Gerry Mulligan", "price": 17.99 }, { "id": "3", "title": "Sarah Vaughan and Clifford Brown", "artist": "Sarah Vaughan", "price": 39.99 } ]
Você iniciou uma API! Na próxima seção, você vai criar outro endpoint, com código para tratar uma
requisição POST que adiciona um item.
Escrever um handler para adicionar um novo item
Quando o cliente fizer uma requisição POST em /albums, você quer adicionar o álbum descrito no corpo da requisição aos dados de álbuns existentes.
Para isso, você vai escrever o seguinte:
- Lógica para adicionar o novo álbum à lista existente.
- Um pouco de código para direcionar a requisição
POSTpara a sua lógica.
Escrever o código
-
Adicione código para incluir os dados de álbuns na lista de álbuns.
Em algum lugar depois das declarações
import, cole o código a seguir. (O final do arquivo é um bom lugar para esse código, mas o Go não exige uma ordem para declarar funções.)// postAlbums adds an album from JSON received in the request body. func postAlbums(c *gin.Context) { var newAlbum album // Call BindJSON to bind the received JSON to // newAlbum. if err := c.BindJSON(&newAlbum); err != nil { return } // Add the new album to the slice. albums = append(albums, newAlbum) c.IndentedJSON(http.StatusCreated, newAlbum) }Neste código, você:
- Usa
Context.BindJSONpara vincular o corpo da requisição anewAlbum. - Adiciona a struct
albuminicializada a partir do JSON ao slicealbums. - Adiciona um código de status
201à resposta, junto com o JSON que representa o álbum adicionado.
- Usa
-
Altere a função
mainpara incluir a chamada arouter.POST, como no exemplo a seguir.func main() { router := gin.Default() router.GET("/albums", getAlbums) router.POST("/albums", postAlbums) router.Run("localhost:8080") }Neste código, você:
-
Associa o método
POSTno caminho/albumsà funçãopostAlbums.Com o Gin, você pode associar um handler a uma combinação de método HTTP e caminho. Assim, você pode rotear separadamente as requisições enviadas a um mesmo caminho conforme o método que o cliente está usando.
-
Executar o código
-
Se o servidor ainda estiver em execução da seção anterior, pare-o.
-
Na linha de comando, no diretório que contém o main.go, execute o código.
$ go run . -
Em outra janela de linha de comando, use
curlpara fazer uma requisição ao seu serviço web em execução.$ curl http://localhost:8080/albums \ --include \ --header "Content-Type: application/json" \ --request "POST" \ --data '{"id": "4","title": "The Modern Sound of Betty Carter","artist": "Betty Carter","price": 49.99}'O comando deve exibir os cabeçalhos e o JSON do álbum adicionado.
HTTP/1.1 201 Created Content-Type: application/json; charset=utf-8 Date: Wed, 02 Jun 2021 00:34:12 GMT Content-Length: 116 { "id": "4", "title": "The Modern Sound of Betty Carter", "artist": "Betty Carter", "price": 49.99 } -
Como na seção anterior, use
curlpara obter a lista completa de álbuns, o que permite confirmar que o novo álbum foi adicionado.$ curl http://localhost:8080/albums \ --header "Content-Type: application/json" \ --request "GET"O comando deve exibir a lista de álbuns.
[ { "id": "1", "title": "Blue Train", "artist": "John Coltrane", "price": 56.99 }, { "id": "2", "title": "Jeru", "artist": "Gerry Mulligan", "price": 17.99 }, { "id": "3", "title": "Sarah Vaughan and Clifford Brown", "artist": "Sarah Vaughan", "price": 39.99 }, { "id": "4", "title": "The Modern Sound of Betty Carter", "artist": "Betty Carter", "price": 49.99 } ]
Na próxima seção, você vai adicionar código para tratar um GET de um item específico.
Escrever um handler para retornar um item específico
Quando o cliente fizer uma requisição em GET /albums/[id], você quer retornar o álbum cujo ID
corresponde ao parâmetro de caminho id.
Para isso, você vai:
- Adicionar lógica para buscar o álbum solicitado.
- Mapear o caminho para a lógica.
Escrever o código
-
Logo abaixo da função
postAlbumsque você adicionou na seção anterior, cole o código a seguir para buscar um álbum específico.Esta função
getAlbumByIDvai extrair o ID presente no caminho da requisição e, em seguida, localizar o álbum correspondente.// getAlbumByID locates the album whose ID value matches the id // parameter sent by the client, then returns that album as a response. func getAlbumByID(c *gin.Context) { id := c.Param("id") // Loop over the list of albums, looking for // an album whose ID value matches the parameter. for _, a := range albums { if a.ID == id { c.IndentedJSON(http.StatusOK, a) return } } c.IndentedJSON(http.StatusNotFound, gin.H{"message": "album not found"}) }Neste código, você:
-
Usa
Context.Parampara obter o parâmetro de caminhoidda URL. Ao mapear este handler para um caminho, você vai incluir um marcador para o parâmetro nesse caminho. -
Percorre as structs
albumdo slice, procurando uma cujo campoIDtenha o mesmo valor do parâmetroid. Se ela for encontrada, serializa essa structalbumem JSON e a retorna como resposta com o código HTTP200 OK.Como mencionado acima, um serviço do mundo real provavelmente usaria uma consulta a banco de dados para fazer essa busca.
-
Retorna um erro HTTP
404comhttp.StatusNotFoundse o álbum não for encontrado.
-
-
Por fim, altere o
mainpara incluir uma nova chamada arouter.GET, em que o caminho agora é/albums/:id, como mostrado no exemplo a seguir.func main() { router := gin.Default() router.GET("/albums", getAlbums) router.GET("/albums/:id", getAlbumByID) router.POST("/albums", postAlbums) router.Run("localhost:8080") }Neste código, você:
- Associa o caminho
/albums/:idà funçãogetAlbumByID. No Gin, os dois-pontos antes de um item do caminho indicam que esse item é um parâmetro de caminho.
- Associa o caminho
Executar o código
-
Se o servidor ainda estiver em execução da seção anterior, pare-o.
-
Na linha de comando, no diretório que contém o main.go, execute o código para iniciar o servidor.
$ go run . -
Em outra janela de linha de comando, use
curlpara fazer uma requisição ao seu serviço web em execução.$ curl http://localhost:8080/albums/2O comando deve exibir o JSON do álbum cujo ID você usou. Se o álbum não for encontrado, você verá um JSON com uma mensagem de erro.
{ "id": "2", "title": "Jeru", "artist": "Gerry Mulligan", "price": 17.99 }
Conclusão
Parabéns! Você acaba de usar Go e Gin para escrever um serviço web RESTful simples.
Próximos tópicos sugeridos:
- Se você é novo em Go, vai encontrar boas práticas úteis descritas em Effective Go e Como escrever código Go.
- O Go Tour é uma ótima introdução passo a passo aos fundamentos do Go.
- Para saber mais sobre o Gin, veja a documentação do pacote Gin Web Framework ou a documentação do Gin Web Framework.
Código completo
Esta seção contém o código da aplicação que você construiu neste tutorial.
package main
import (
"net/http"
"github.com/gin-gonic/gin"
)
// album represents data about a record album.
type album struct {
ID string `json:"id"`
Title string `json:"title"`
Artist string `json:"artist"`
Price float64 `json:"price"`
}
// albums slice to seed record album data.
var albums = []album{
{ID: "1", Title: "Blue Train", Artist: "John Coltrane", Price: 56.99},
{ID: "2", Title: "Jeru", Artist: "Gerry Mulligan", Price: 17.99},
{ID: "3", Title: "Sarah Vaughan and Clifford Brown", Artist: "Sarah Vaughan", Price: 39.99},
}
func main() {
router := gin.Default()
router.GET("/albums", getAlbums)
router.GET("/albums/:id", getAlbumByID)
router.POST("/albums", postAlbums)
router.Run("localhost:8080")
}
// getAlbums responds with the list of all albums as JSON.
func getAlbums(c *gin.Context) {
c.IndentedJSON(http.StatusOK, albums)
}
// postAlbums adds an album from JSON received in the request body.
func postAlbums(c *gin.Context) {
var newAlbum album
// Call BindJSON to bind the received JSON to
// newAlbum.
if err := c.BindJSON(&newAlbum); err != nil {
return
}
// Add the new album to the slice.
albums = append(albums, newAlbum)
c.IndentedJSON(http.StatusCreated, newAlbum)
}
// getAlbumByID locates the album whose ID value matches the id
// parameter sent by the client, then returns that album as a response.
func getAlbumByID(c *gin.Context) {
id := c.Param("id")
// Loop through the list of albums, looking for
// an album whose ID value matches the parameter.
for _, a := range albums {
if a.ID == id {
c.IndentedJSON(http.StatusOK, a)
return
}
}
c.IndentedJSON(http.StatusNotFound, gin.H{"message": "album not found"})
}
