【Go语言成长之路】使用 Go 和 Gin 开发 RESTful API

使用 Go 和 Gin 开发 RESTful API

​ 本教程使用Go和 Gin Web Framework （Go语言中优秀的第三方Web框架）编写一个RESTful Web服务API, 实现路由请求、检索请求详细信息、JSON编码响应。

一、前提

• Go 1.16以及之后的版本
• curl工具，在Linux和mac中以及内置好了，而在windows中，win10 17063以及之后的版本已经内置该工具，但如果在该版本之前，则需要进行安装

二、设计API端点

​ 本教程将构建一个 API，提供对Album的访问、添加操作。因此，需要提供端点(endPoint)，客户端可以通过该端点获取和添加用户的相册。

​ 重要的事：开发 API 时，通常从设计端点开始，端点应该设计的易于理解。

​ 以下是本教程中创建的端点:

• /albums
  • GET: 获取所有的相册列表，以JSON字符串返回
  • POST: 根据以 JSON 形式发送的请求数据添加新相册
• /albums/:id
  • GET: 通过ID来获取一个相册，以JSON字符串返回

三、创建项目

首先，将编写的代码创建一个项目

~$ mkdir web-service-gin
~$ cd web-service-gin

其次，创建一个模块来管理依赖：

~/web-service-gin$ go mod init example/web-service-gin
go: creating new go.mod: module example/web-service-gin

此命令创建一个 go.mod 文件，会将需要的依赖项添加到该文件中并且跟踪。

注： 了解更多关于模块依赖管理的信息，请查阅: Managing dependencies

四、运行项目

为了让数据保持简单，本教程将数据存储到内存中进行交互，而在一般更为典型的API将会与数据库(database)进行交互。

注意：将数据存储在内存中意味着每次停止服务器数据都会丢失，然后在启动服务器时重新创建。

4.1 编写代码

使用文本编辑器在 web-service-gin 目录中创建一个名为 main.go 的文件，内容如下:

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
) 
// 1. create album struct, it used to store album data in memory
// album represents data about a record album.
type album struct {
	// Struct tags such as json:"artist" specify what a field’s name should be
	// when the struct’s contents are serialized into JSON.
	// Without them, the JSON would use the struct’s capitalized field names – a style not as common in JSON.
	ID     string  `json:"id"`
	Title  string  `json:"title"`
	Artist string  `json:"artist"`
	Price  float64 `json:"price"`
}

// 2. declare a slice of album structs containing data you'll use to start
// 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},
}

// 3.Write a handler to return all items¶
// When the client makes a request at GET /albums, you want to return all the albums as JSON.
// To do this, you’ll write the following:
// 1.Logic to prepare a response
// 2.Code to map the request path to your logic
// This getAlbums function creates JSON from the slice of album structs, writing the JSON into the response.
// getAlbums responds with the list of all albums as JSON.
func getAlbums(c *gin.Context) { // gin.Context is the most important part of Gin. It carries request details, validates and serializes JSON, and more.
	// The function’s first argument is the HTTP status code you want to send to the client.
	// Note that you can replace Context.IndentedJSON with a call to Context.JSON to send more compact JSON.
	// In practice, the indented form is much easier to work with when debugging and the size difference is usually small.
	c.IndentedJSON(http.StatusOK, albums) //  serialize the struct into JSON and add it to the response.
}

// 4.Write a handler to add a new item¶
// When the client makes a POST request at /albums, you want to add the album described in the request body to the existing albums’ data.
// To do this, you’ll write the following:
// 1.Logic to add the new album to the existing list.
// 2.A bit of code to route the POST request to your logic.
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)
	// Add a 201 status code to the response, along with JSON representing the album you added.
	c.IndentedJSON(http.StatusCreated, newAlbum)
}

// 5. Write a handler to return a specific item¶
// When the client makes a request to GET /albums/[id], you want to return the album whose ID matches the id path parameter.
// 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) {
	// Use Context.Param to retrieve the id path parameter from the URL.
	// When you map this handler to a path, you’ll include a placeholder for the parameter in the path.
	id := c.Param("id")
	// Loop over the list of albums, looking for
	// an album whose ID value matches the parameter.
	// As mentioned above, a real-world service would likely use a database query to perform this lookup.
	for _, a := range albums {
		if a.ID == id {
			c.IndentedJSON(http.StatusOK, a)
			return
		}
	}
	// Return an HTTP 404 error with http.StatusNotFound if the album isn’t found.
	c.IndentedJSON(http.StatusNotFound, gin.H{"message": "album not found"})
}

// 6.assign the handler function to an endpoint path.
func main() {
	// Initialize a Gin router using Default.
	router := gin.Default()
	// This sets up an association in which getAlbums handles requests to the /albums endpoint path.
	router.GET("/albums", getAlbums)
	// Associate the POST method at the /albums path with the postAlbums function.
	router.POST("/albums", postAlbums)
	// In Gin, the colon preceding an item in the path signifies that the item is a path parameter.
	router.GET("/albums/:id", getAlbumByID)

	// Use the Run function to attach the router to an http.Server and start the server.
	router.Run("localhost:8080")
}

4.2 运行代码

1. 追踪依赖

   使用go get命令获取模块中所需要使用到的依赖

   ~/web-service-gin/$ go get .
   go get: added github.com/gin-gonic/gin v1.7.2
   

   注：使用.代表获取当前目录下的所有依赖

2. 运行代码

   ~/web-service-gin/$ go run main.go
   [GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.
   
   [GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
    - using env:   export GIN_MODE=release
    - using code:  gin.SetMode(gin.ReleaseMode)
   
   [GIN-debug] GET    /albums                   --> main.getAlbums (3 handlers)
   [GIN-debug] [WARNING] You trusted all proxies, this is NOT safe. We recommend you to set a value.
   Please check https://pkg.go.dev/github.com/gin-gonic/gin#readme-don-t-trust-all-proxies for details.
   [GIN-debug] Listening and serving HTTP on localhost:8080
   

   运行成功之后，HTTP服务器就成功启动了，然后就可以发送相应的请求。

3. 使用curl命令向web服务器发送请求

   • 发送GET的/albums请求

     $ curl http://localhost:8080/albums
     [
         {
             "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
         }
     ]
     

   • 发送POST的/albums请求

     $ 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}'
     HTTP/1.1 201 Created
     Content-Type: application/json; charset=utf-8
     Date: Tue, 27 Aug 2024 15:34:36 GMT
     Content-Length: 116
     
     {
         "id": "4",
         "title": "The Modern Sound of Betty Carter",
         "artist": "Betty Carter",
         "price": 49.99
     }
     

   • 发送带有参数GET的/albums请求

     $ curl http://localhost:8080/albums/2
     {
         "id": "2",
         "title": "Jeru",
         "artist": "Gerry Mulligan",
         "price": 17.99
     }