Go(Golang)是最近流行起来,且相对较新的编程语言。
它小而稳定,使用和学习简单,速度快,经过编译(原生代码),并大量用于云工具和服务(Docker、Kubernetes...)。
考虑到它所带来的所有好处,没有理由不去尝试一下。
在本教程中,我们将建立一个简单的图书商店 REST API。
程序员宝藏库:https://github.com/Jackpopc/CS-Books-Store
1. 准备工作
在我们开始之前,我们需要事先做一些准备工作:
浏览器
gorilla/handlers
gorilla/mux
做好这些准备,我们就可以开始 Go 之旅了!
2. 应用结构
你现在应该已经安装好 Go,并且做好了事先准备工作。
打开你最喜欢的 IDE(Visual Studio Code, GoLand, ...),创建一个新的项目。
正如我前面提到的,我们的想法是通过使用 Mux 建立一个简单的 REST API,用于图书商店管理。
一旦你创建了你的空白项目,在其中创建以下结构:
├── main.go
└── src
├── app.go
├── data.go
├── handlers.go
├── helpers.go
└── middlewares.go
复制代码
Go 工具包和模块
我们先来了解一下 Go 模块和包,如果你熟悉 Python,你可能会对这些东西有一个概念,因为它们的操作很相似。
描述 Go 包的最好方法是,它是同一目录下的源文件的集合,被编译成一个可重复使用的单元。
这意味着所有有类似用途的文件都应该放在一个包里。
按照我们上面的结构,src
是我们的包之一。
Go 模块是 Go 包及其依赖关系的集合,这意味着一个模块可以由多个包组成。
为了便于理解,你可以把我们的整个应用程序看成是一个 Go 模块。
让我们在项目根目录下执行这个命令来创建我们的模块。
你应该在你的根目录中看到一个新文件,名为go.mod
。
3. 构建 API
现在是时候开始构建我们的应用程序了。
打开你的main.go
文件,在其中插入以下代码。
package main
import"bookstore/src"
func main() {
src.Start()
}
复制代码
我们声明了我们的主 Go 包(package main
),并将我们的src
包与模块bookstore
的前缀一起导入。
在函数main()
中,我们将运行包src
的Start()
函数。
这是我们的入口文件(main.go
)的唯一职责--启动 API。
路线和处理程序
现在我们需要创建我们的 API 路由器(Mux
),并通过创建一些端点和它们的处理程序来配置它。
在你的 src 包中打开app.go
并在其中插入以下代码。
package src
import (
"github.com/gorilla/handlers"
"github.com/gorilla/mux"
"log"
"net/http"
"os"
)
func Start() {
router := mux.NewRouter()
router.Use(commonMiddleware)
router.HandleFunc("/book", getAllBooks).Methods(http.MethodGet)
router.HandleFunc("/book", addBook).Methods(http.MethodPost)
router.HandleFunc("/book/{book_id:[0-9]+}", getBook).Methods(http.MethodGet)
router.HandleFunc("/book/{book_id:[0-9]+}", updateBook).Methods(http.MethodPut)
router.HandleFunc("/book/{book_id:[0-9]+}", deleteBook).Methods(http.MethodDelete)
log.Fatal(http.ListenAndServe("localhost:5000", handlers.LoggingHandler(os.Stdout, router)))
}
复制代码
如你所见,我们声明app.go
是 src 包的一部分,它包含了我们在main.go
文件中使用的Start()
函数。
我们还导入两个外部模块,我们需要程序中需要依赖到的mux
和handlers
。
在你的终端中执行以下命令:
go get github.com/gorilla/handlers
go get github.com/gorilla/mux
复制代码
你的go.mod
文件应该也同步了,现在它应该是这样的:
module bookstore
go1.17
require (
github.com/gorilla/handlers v1.5.1
github.com/gorilla/mux v1.8.0
)
require github.com/felixge/httpsnoop v1.0.1// indirect
复制代码
让我们深入了解一下我们的Start()
函数。
首先,我们声明了一个新的Mux
路由器变量,它将负责路由和处理整个 API 的请求。
然后,我们告诉Mux
,我们要用到一个中间件,它将在每个来到我们 API 的请求中执行下面这一行:
router.Use(commonMiddleware)
复制代码
稍后会有更多关于中间件的内容。
继续分析我们的代码,我们可以看到我们在哪里创建端点以及处理程序(回调函数)和一些原始的验证,例如:
router.HandleFunc("/book/{book_id:[0-9]+}", updateBook).Methods(http.MethodPut)
复制代码
一旦用户在/book/123
(或任何其他数字)路径上用PUT
方法点击我们的服务器,这个端点就会启动。
然后,它将把请求传递给updateBook
处理函数进行进一步处理。
book_id
变量必须是一个数字,因为我们在变量名声明后指定了一个简单的验证。
最后,我们将在特定的主机和端口组合上运行我们的服务器,并让它把所有的东西都记录到我们的终端。
中间件
我们都知道,REST APIs 在接受请求和返回响应时大多使用 JSON。
这是通过使用Content-Type
头信息传达给我们的浏览器/HTTP 客户端的。
由于我们的 API 将只使用 JSON 表示的数据,我们可以使用一个中间件,以确保我们的内容类型始终被设置为 JSON。
如前所述,app.go
的Start()
方法包含这一行:
router.Use(commonMiddleware)
复制代码
让我们打开我们的middlewares.go
文件并创建所需的函数:
package src
import"net/http"
func commonMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("content-type", "application/json; charset=utf-8")
w.Header().Set("x-content-type-options", "nosniff")
next.ServeHTTP(w, r)
})
}
复制代码
一旦用户点击我们在Start()
函数中向 Mux 路由器注册的任何一个端点,中间件将拦截该请求并添加我们在commonMiddleware
函数中指定的两个头信息。
然后,它将把修改后的请求进一步传递给被请求端点的处理函数或另一个中间件。
静态数据
由于我们不会使用任何数据存储服务(数据库、缓存......),我们需要有某种静态数据。
另外,我们将为自定义响应创建一个数据类型,我将在后面解释。
打开src
包内的data.go
,在其中放入以下内容。
package src
type Book struct {
Id int`json:"id"`
Title string`json:"title"`
Author string`json:"author"`
Genre string`json:"genre"`
}
var booksDB = []Book{
{Id: 123, Title: "The Hobbit", Author: "J. R. R. Tolkien", Genre: "Fantasy"},
{Id: 456, Title: "Harry Potter and the Philosopher's Stone", Author: "J. K. Rowling", Genre: "Fantasy"},
{Id: 789, Title: "The Little Prince", Author: "Antoine de Saint-Exupéry", Genre: "Novella"},
}
复制代码
我们刚刚创建了一个数据结构,它将在我们的 API 中保存一本书所需的信息。
我还创建了 json 标签,如果数据类型将以 JSON 形式传递,它将把字段名翻译成 JSON 表示。此外,还创建了一个原始的图书存储系统(在内存中)和一些初始图书数据(booksDB)。
把这段代码添加到上面的表格下面:
type CustomResponse struct {
Code int `json:"code"`
Message string `json:"message"`
Description string `json:"description,omitempty"`
}
var responseCodes = map[int]string {
400: "Bad Request",
401: "Unauthorized",
403: "Forbidden",
404: "Not Found",
409: "Conflict",
422: "Validation Error",
429: "Too Many Requests",
500: "Internal Server Error",
}
复制代码
我们刚刚做了一个新的数据结构,将统一我们的 API 将返回的错误/响应,稍后会有更多这方面的内容。
辅助工具
我们将需要一些辅助工具来充分利用我们的 API。例如,我们将需要检查具有给定 ID 的书是否存在(添加新书,修改现有的书)、需要删除一个具有给定 ID 的书(删除书)、需要为给定的 HTTP 状态代码返回一个自定义的 JSON 响应。
打开 src 包中的helpers.go
,在里面插入以下内容:
package src
import (
"encoding/json"
"net/http"
)
func removeBook(s []Book, i int) []Book {
if i != len(s)-1 {
s[i] = s[len(s)-1]
}
return s[:len(s)-1]
}
func checkDuplicateBookId(s []Book, id int) bool {
for _, book := range s {
if book.Id == id {
return true
}
}
return false
}
func JSONResponse(w http.ResponseWriter, code int, desc string) {
w.WriteHeader(code)
message, ok := responseCodes[code]
if !ok {
message = "Undefined"
}
r := CustomResponse{
Code: code,
Message: message,
Description: desc,
}
_ = json.NewEncoder(w).Encode(r)
}
复制代码
removeBook
函数会遍历Book
,如果它不是片段的最后一个元素,它将把它移到片段的末尾并返回一个没有它的新片段(避免最后一个元素)。
checkDuplicateBookId
函数将返回一个 bool 值(真或假),这取决于给定的 id 是否存在于Book
中。
JSONResponse
函数负责使用我们先前创建的CustomResponse
和responseCodes
。它将返回一个 CustomResponse 的 JSON 表示,其中包含了 responseCodes 将提供的状态代码和消息。
这样,我们将避免在我们的 API 中对相同的 HTTP 状态代码有不同的消息。
处理程序
现在来到了最后一步,把端点处理程序放在一起。
打开你的handlers.go
,让我们在其中输入一些代码:
package src
import (
"encoding/json"
"github.com/gorilla/mux"
"net/http"
"strconv"
)
复制代码
获取单本图书
func getBook(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
bookId, _ := strconv.Atoi(vars["book_id"])
for _, book := range booksDB {
if book.Id == bookId {
_ = json.NewEncoder(w).Encode(book)
return
}
}
JSONResponse(w, http.StatusNotFound, "")
}
复制代码
我们从 Mux 路由器获得传递的变量,把它从字符串转换为 int 值。然后,遍历我们的 booksDB,寻找匹配的书籍 ID。如果它存在,返回它 - 如果不存在,我们返回404: Not Found
错误。
获取所有图书
func getAllBooks(w http.ResponseWriter, r *http.Request) {
_ = json.NewEncoder(w).Encode(booksDB)
}
复制代码
是不是很简单?将 booksDB 转换为 JSON,并将其返回给用户。
添加一本新图书
func addBook(w http.ResponseWriter, r *http.Request) {
decoder := json.NewDecoder(r.Body)
var b Book
err := decoder.Decode(&b)
if err != nil {
JSONResponse(w, http.StatusBadRequest, "")
return
}
if checkDuplicateBookId(booksDB, b.Id) {
JSONResponse(w, http.StatusConflict, "")
return
}
booksDB = append(booksDB, b)
w.WriteHeader(201)
_ = json.NewEncoder(w).Encode(b)
}
复制代码
由于这是在 POST 方法上触发的,用户必须在请求体中提供符合 Book 结构的 JSON 数据。
{
"id": 999,
"title": "SomeTitle",
"author": "SomeAuthor",
"genre": "SomeGenre"
}
复制代码
一旦我们根据我们的图书结构解码并验证 JSON 主体(如果失败,我们将返回400: Bad Request error
),我们需要检查具有相同 ID 的图书是否已经存在。如果是这样,我们将返回409: Conflict error back
。反之,将用用户提供的书追加我们的 booksDB,并将其 JSON 表示返回给用户。
更新现有书籍
func updateBook(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
bookId, _ := strconv.Atoi(vars["book_id"])
decoder := json.NewDecoder(r.Body)
var b Book
err := decoder.Decode(&b)
if err != nil {
JSONResponse(w, http.StatusBadRequest, "")
return
}
for i, book := range booksDB {
if book.Id == bookId {
booksDB[i] = b
_ = json.NewEncoder(w).Encode(b)
return
}
}
JSONResponse(w, http.StatusNotFound, "")
}
复制代码
与 addBook 函数处理程序几乎相同,但有一个主要区别。
要更新这本书,它必须已经存在(ID 必须在 booksDB 中)。
如果它存在,我们将更新现有书籍的值,否则,我们将返回404: Not Found
错误。
删除现有书籍
func deleteBook(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
bookId, _ := strconv.Atoi(vars["book_id"])
for i, book := range booksDB {
if book.Id == bookId {
booksDB = removeBook(booksDB, i)
_ = json.NewEncoder(w).Encode(book)
return
}
}
JSONResponse(w, http.StatusNotFound, "")
}
复制代码
在我们得到 book_id 变量的整数值后,我们遍历 booksDB,找到用户想删除的书。
如果它存在,我们利用我们的辅助函数removeBook
,从 Book 结构片中删除该书。如果它不存在,我们将返回404: Not Found
错误。
4. 运行和测试 API
现在我们的 API 已经完成,让我们来运行一下,在你的终端执行这个程序:
启动你最喜欢的 HTTP 客户端(Insomnia, Postman, ...),试试我们创建的一些接口吧
评论