如何使用 Go 构建 API
设置 Go 环境
构建 API
结论
你是否曾觉得构建 API 就像编写只有少数人才能理解的秘密代码？作为一名 Web 开发者👨🏾💻和技术撰稿人📝，我深有体会。但别担心，我的朋友！在本文中，我将向你展示 Go 如何帮助你揭开 API 开发的神秘面纱，并使其变得人人都能轻松上手。
让我们一起深入探索 API 和 Go 的世界，发现如何轻松创建强大高效的 API。
解释什么是 API 以及它为什么有用
API是一组用于构建软件应用程序的协议、例程和代码。API 规定了软件组件之间如何交互和通信，使开发人员能够更轻松地构建复杂的软件系统。API 为软件交换数据和执行功能提供了一种标准化的方式，使开发人员能够更轻松地创建新应用程序、集成现有系统以及实现流程自动化。
API之所以有用，是因为它们允许开发者创建能够与其他软件系统、服务和数据源交互的应用程序。这意味着开发者无需每次构建新应用程序时都从零开始，而是可以利用现有的代码、数据和功能来创建创新产品。API还使开发者能够构建可扩展、模块化和易于维护的软件产品，从而更轻松地随着时间的推移添加新功能。
简要介绍 Go 语言及其在构建 API 方面的优势
Go是一种由Google开发的现代编程语言，因其在构建 API 方面的出色表现而备受开发者青睐。Go 是一种编译型语言，这意味着它可以生成快速高效的代码，并可在多种平台上运行。此外，Go 的设计也兼顾了易读性和易写性，使其成为构建大型复杂软件系统的理想选择。
使用 Go 构建 API 的关键优势之一在于其对并发的出色支持。并发是指同时运行多个任务的能力，而 Go 使得编写能够充分利用多核处理器和其他硬件资源的代码变得轻而易举。这意味着 Go API 可以处理高流量和高请求量，而不会出现速度下降或崩溃的情况。
使用 Go 构建 API 的另一个优势在于其内置对JSON（JavaScript 对象表示法）的支持。JSON 是一种轻量级数据格式，广泛用于 Web 应用程序中的数据交换。Go 对 JSON 的支持使得创建能够接收和返回此格式数据的 API 变得轻而易举，从而简化了 API 的构建和与其他软件系统的集成过程。
总的来说，Go 是一种功能强大且灵活的语言，非常适合构建 API。它的速度、并发支持和内置的 JSON 支持使其成为希望创建可扩展、高性能 API 的开发人员的绝佳选择。
设置 Go 环境
- 安装 Go
第一步是在您的计算机上下载并安装 Go 语言。您可以从Go 官方网站下载最新版本。下载完成后，请按照适用于您操作系统的安装说明进行操作。
- 配置环境变量
安装 Go 之后，需要配置环境变量。在 Windows 系统中，右键单击“我的电脑”，选择“属性”。然后，点击“高级系统设置”，再点击“环境变量”。将 Go 的 bin 文件夹路径添加到“Path”变量中。
在 Linux 和 macOS 系统中，您需要编辑主目录中的 `.htm`.bashrc或 `.mts`.bash_profile文件，并添加以下几行：
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin
- 设置工作区
接下来，你需要为你的 Go 项目设置一个工作区。工作区是一个包含你的 Go 源代码文件和二进制文件的目录。
go-workspace在您的用户目录中创建一个名为“”的目录：
$ mkdir ~/go-workspace
在这个目录下，创建三个子目录：src，，pkg和bin。
$ cd ~/go-workspace
$ mkdir src pkg bin
您已准备好开始使用 Go 构建 API！
构建 API
- 选择一个框架（例如，Gorilla mux、Echo、Gin）
现在我们已经搭建好了 Go 环境，可以开始构建 API 了。第一步是选择一个框架。Go 语言中有很多流行的 API 构建框架，例如Gorilla mux、Echo和Gin。本文将使用Gin Gorilla mux。
- 创建基本服务器
要创建一个基本服务器，我们需要导入必要的软件包并定义一个主函数。主函数是程序的入口点。以下是一个使用 Gorilla mux 的基本服务器示例：
package main
import (
"fmt"
"net/http"
"github.com/gorilla/mux"
)
func main() {
router := mux.NewRouter()
router.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprint(w, "Hello, World!")
})
http.ListenAndServe(":8000", router)
}
这段代码导入了“fmt”、“net/http”和“github.com/gorilla/mux”包，定义了一个使用 Gorilla mux 创建一个新路由器的主函数，为“/”路由添加了一个处理函数，该函数将“Hello, World!”写入响应写入器，并启动了一个监听端口 8000 的 HTTP 服务器。
- 为不同的端点添加路由和处理程序
要为不同的端点添加路由和处理程序，我们需要定义额外的处理函数并将其注册到路由器中。
// Define a handler function for the /users endpoint
func getUsersHandler(w http.ResponseWriter, r *http.Request) {
// Get the list of users from the database
users := getUsersFromDB()
// Convert the list of users to JSON format
usersJSON, err := json.Marshal(users)
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
// Set the content type of the response to JSON
w.Header().Set("Content-Type", "application/json")
// Write the JSON response to the client
w.Write(usersJSON)
}
// Register the /users endpoint with the router
r.HandleFunc("/users", getUsersHandler).Methods(http.MethodGet)
在这个例子中，我们定义了一个getUsersHandler函数，该函数从数据库中检索用户列表，将其转换为 JSON 格式，并将其写入响应。然后，我们通过调用该函数向路由器注册此处理程序函数r.HandleFunc("/users", getUsersHandler).Methods(http.MethodGet)。
类似地，我们可以为其他端点定义和注册处理函数，例如/users/{id}通过 ID 检索特定用户，/users使用 HTTP POST 方法创建新用户，/users/{id}使用 HTTP PUT 方法更新用户，以及/users/{id}使用 HTTP DELETE 方法删除用户。
- 实施 CRUD 操作：
为了实现 CRUD 操作（创建、读取、更新、删除），我们需要为每个操作定义处理函数，并将它们注册到路由器中。
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"github.com/gorilla/mux"
)
type Book struct {
ID string `json:"id,omitempty"`
Title string `json:"title,omitempty"`
Author string `json:"author,omitempty"`
Publisher *Company `json:"publisher,omitempty"`
}
type Company struct {
Name string `json:"name,omitempty"`
Address string `json:"address,omitempty"`
}
var books []Book
func GetBooks(w http.ResponseWriter, r *http.Request) {
json.NewEncoder(w).Encode(books)
}
func GetBook(w http.ResponseWriter, r *http.Request) {
params := mux.Vars(r)
for _, item := range books {
if item.ID == params["id"] {
json.NewEncoder(w).Encode(item)
return
}
}
json.NewEncoder(w).Encode(&Book{})
}
func CreateBook(w http.ResponseWriter, r *http.Request) {
var book Book
_ = json.NewDecoder(r.Body).Decode(&book)
books = append(books, book)
json.NewEncoder(w).Encode(book)
}
func UpdateBook(w http.ResponseWriter, r *http.Request) {
params := mux.Vars(r)
for index, item := range books {
if item.ID == params["id"] {
books = append(books[:index], books[index+1:]...)
var book Book
_ = json.NewDecoder(r.Body).Decode(&book)
book.ID = params["id"]
books = append(books, book)
json.NewEncoder(w).Encode(book)
return
}
}
json.NewEncoder(w).Encode(books)
}
func DeleteBook(w http.ResponseWriter, r *http.Request) {
params := mux.Vars(r)
for index, item := range books {
if item.ID == params["id"] {
books = append(books[:index], books[index+1:]...)
break
}
}
json.NewEncoder(w).Encode(books)
}
func main() {
router := mux.NewRouter()
books = append(books, Book{ID: "1", Title: "Book One", Author: "John Doe", Publisher: &Company{Name: "Publisher One", Address: "Address One"}})
books = append(books, Book{ID: "2", Title: "Book Two", Author: "Jane Smith", Publisher: &Company{Name: "Publisher Two", Address: "Address Two"}})
router.HandleFunc("/books", GetBooks).Methods("GET")
router.HandleFunc("/books/{id}", GetBook).Methods("GET")
router.HandleFunc("/books", CreateBook).Methods("POST")
router.HandleFunc("/books/{id}", UpdateBook).Methods("PUT")
router.HandleFunc("/books/{id}", DeleteBook).Methods("DELETE")
log.Fatal(http.ListenAndServe(":8000", router))
}
这段代码定义了一个Book包含ID`books`、Title`books`、` Authorbooks` 和Publisher`books` 字段的结构体。然后，它定义了用于获取所有书籍、通过 ID 获取特定书籍、创建新书籍、更新现有书籍和删除书籍的处理函数。这些处理函数使用 Gorilla mux 的 `getVariable`Vars函数从 URL 中提取变量，并使用json`json` 包对 JSON 数据进行编码和解码。最后，设置了一个路由器，并将处理函数注册到相应的 HTTP 方法和 URL 路径中，从而使 API 能够接收和响应请求。这创建了一个功能齐全的 RESTful API，可以部署到服务器，供客户端对书籍集合执行 CRUD 操作。
通过这个示例，您可以开始使用 Go 和 Gorilla mux 构建自己的 API，并根据您的特定需求进行自定义。
处理错误和异常
处理错误和异常是构建任何软件的关键环节，API 也不例外。构建 API 时，必须预先考虑并处理运行时可能出现的错误和异常。
以下是一些在 Go API 中处理错误和异常的技巧：
- 处理函数中的错误处理：
在 Go API 中处理错误和异常的一种方法是使用处理函数中的错误处理。
func getUser(w http.ResponseWriter, r *http.Request) {
// ...code to get user by ID...
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
// ...return user as JSON...
}
如果在获取用户时发生错误，则会返回 HTTP 500 内部服务器错误。
- 自定义错误类型：
在 Go 语言中，您可以定义自定义错误类型来表示 API 中可能发生的特定错误。
type UserNotFoundError struct {
ID int
}
func (e UserNotFoundError) Error() string {
return fmt.Sprintf("user with ID %d not found", e.ID)
}
定义了一个自定义错误类型UserNotFoundError，用于表示找不到具有给定 ID 的用户时发生的错误。它可以在处理函数中使用：
func getUser(w http.ResponseWriter, r *http.Request) {
// ...code to get user by ID...
if err != nil {
if _, ok := err.(UserNotFoundError); ok {
http.Error(w, err.Error(), http.StatusNotFound)
return
}
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
// ...return user as JSON...
}
如果发生此类型的错误UserNotFoundError，则会返回 HTTP 404 Not Found 错误。
- 恐慌之后再恢复：
处理 Go API 中的错误和异常的另一种方法是使用 panic 和 recover 机制。
func getUser(w http.ResponseWriter, r *http.Request) {
defer func() {
if r := recover(); r != nil {
log.Println("recovered from panic:", r)
http.Error(w, "Internal Server Error", http.StatusInternalServerError)
}
}()
// ...code that may panic...
}
如果处理函数中发生 panic，则会被捕获并记录，并向客户端返回 HTTP 500 内部服务器错误。
通过实施这些技术，您可以确保您的 Go API 具有健壮性，并且能够优雅地处理错误和异常。
与数据库集成
与数据库集成是构建生产级 API 的关键步骤。有很多数据库可供选择，例如MySQL、PostgreSQL、MongoDB等。在本节中，我们将介绍将 Go 与数据库集成的步骤。
- 选择数据库（例如，MySQL、PostgreSQL、MongoDB）
数据库的选择取决于项目的具体需求。例如，如果应用程序需要高度关系型的数据模型，那么基于 SQL 的数据库（例如 MySQL 或 PostgreSQL）可能是最佳选择。另一方面，如果数据更偏向文档型或非结构化，那么 NoSQL 数据库（例如 MongoDB）可能更合适。选择数据库时，必须考虑性能、可扩展性和成本等因素，并充分满足项目的需求。
- 安装必要的驱动程序
要与特定数据库集成，我们需要安装相应的驱动程序或软件包。例如，要使用 MySQL，我们可以安装“go-sql-driver/mysql”软件包。类似地，我们可以使用“pq”软件包连接到 PostgreSQL，或者使用“mongo-go-driver”软件包连接到 MongoDB。
- 创建数据库连接
安装好必要的软件包后，我们就可以创建数据库连接了。连接字符串通常包含连接数据库所需的凭据，例如用户名、密码和数据库名称。
创建与 MySQL 数据库的连接：
import (
"database/sql"
_ "github.com/go-sql-driver/mysql"
)
func main() {
db, err := sql.Open("mysql", "user:password@tcp(host:port)/database")
if err != nil {
// handle error
}
defer db.Close()
// do something with db
}
- 执行数据库操作（例如，查询、插入、更新、删除）
建立连接后，即可执行查询、插入、更新和删除数据等数据库操作。
一个从 MySQL 数据库中检索所有用户的函数：
func getUsers(db *sql.DB) ([]User, error) {
var users []User
rows, err := db.Query("SELECT * FROM users")
if err != nil {
return nil, err
}
defer rows.Close()
for rows.Next() {
var user User
err := rows.Scan(&user.ID, &user.Name, &user.Email)
if err != nil {
return nil, err
}
users = append(users, user)
}
return users, nil
}
将 Go 与数据库集成是构建生产就绪型 API 的关键步骤。
选择合适的数据库，安装必要的驱动程序，创建连接，并实现数据库操作。
添加身份验证和授权
为 API 添加身份验证和授权功能对于确保对敏感数据的安全访问和控制至关重要。以下是具体操作方法：
- 选择一种身份验证和授权方法（例如 JWT、OAuthz）
首先，选择一种符合 API 需求的身份验证和授权方法。常用方法包括 JWT（JSON Web Tokens）、OAuth2 和基本身份验证。
- 实现身份验证和授权中间件
接下来，您需要实现中间件函数来处理身份验证和授权。这些函数应检查有效的身份验证凭据，并根据用户的角色和权限授权对端点的访问。
一个基本的 JWT 身份验证中间件功能：
func RequireTokenAuthentication(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
authHeader := r.Header.Get("Authorization")
if authHeader == "" {
http.Error(w, "Missing authorization header", http.StatusUnauthorized)
return
}
token, err := jwt.Parse(authHeader, func(token *jwt.Token) (interface{}, error) {
if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
return nil, fmt.Errorf("Unexpected signing method: %v", token.Header["alg"])
}
return []byte("secret"), nil
})
if err != nil {
http.Error(w, "Invalid token", http.StatusUnauthorized)
return
}
if !token.Valid {
http.Error(w, "Invalid token", http.StatusUnauthorized)
return
}
context.Set(r, "decoded", token.Claims)
next.ServeHTTP(w, r)
})
}
- 为端点添加身份验证和授权功能
中间件实现完成后，我们可以将其添加到所需的端点。例如，要将对特定端点的访问限制为具有特定角色的已认证用户，我们可以使用该RequireTokenAuthentication 中间件并添加角色检查：
router.HandleFunc("/protected", RequireTokenAuthentication(ProtectedHandler)).Methods("GET")
测试 API
为了确保 API 正常运行，我们需要编写测试。彻底测试至关重要，它可以确保 API 按预期工作，并在任何错误或问题影响用户之前将其捕获。
测试可以分为单元测试（针对各个处理程序和端点）和集成测试（针对整个 API）。GoConvey 和 Ginkgo 等测试框架可以帮助我们编写和运行测试。
- 为端点和处理程序编写单元测试。
单元测试侧重于测试代码中的各个函数或组件。对于我们的 API，我们需要为每个端点和处理函数编写单元测试，以确保它们能够正常工作。
以下是一个处理程序的测试函数：
func TestProtectedHandler(t *testing.T) {
token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
"username": "testuser",
"role": "admin",
"exp": time.Now().Add(time.Hour * 24).Unix(),
})
tokenString, err := token.SignedString([]byte("secret"))
if err != nil {
t.Fatalf("Error signing token: %v", err)
}
req, err := http.NewRequest("GET", "/protected", nil)
if err != nil {
t.Fatalf("Error creating request: %v", err)
}
req.Header.Set("Authorization", "Bearer "+tokenString)
rr := httptest.NewRecorder()
handler := http.HandlerFunc(ProtectedHandler)
handler.ServeHTTP(rr, req)
if status := rr.Code; status != http.StatusOK {
t.Errorf("Handler returned wrong status code: got %v want %v", status, http.StatusOK)
}
expected := `{"message":"Hello, authenticated user!"}`
if rr.Body.String() != expected {
t.Errorf("Handler returned unexpected body: got %v want %v", rr.Body.String(), expected)
}
}
- 编写 API 集成测试：
另一方面，集成测试则对整个 API 进行测试，以确保所有组件都能正确协同工作。以下是
一个使用 Ginkgo 测试框架的集成测试示例：
var _ = Describe("API", func() {
var (
apiURL string
api *API
)
BeforeEach(func() {
apiURL = "http://localhost:8080"
api = NewAPI()
go api.Start()
time.Sleep(1 * time.Second)
})
AfterEach(func() {
api.Stop()
})
Describe("GET /users", func() {
It("returns a list of users", func() {
resp, err := http.Get(fmt.Sprintf("%s/users", apiURL))
Expect(err).NotTo(HaveOccurred())
defer resp.Body.Close()
Expect(resp.StatusCode).To(Equal(http.StatusOK))
bodyBytes, err := ioutil.ReadAll(resp.Body)
Expect(err).NotTo(HaveOccurred())
bodyString := string(bodyBytes)
Expect(bodyString).To(ContainSubstring("John Doe"))
Expect(bodyString).To(ContainSubstring("johndoe@example.com"))
})
})
})
测试是构建强大 API 的重要组成部分，使用 GoConvey 或 Ginkgo 等测试框架可以使测试过程更轻松、更有效。
部署 API
太好了！一旦我们的 API 开发、测试完毕并准备好投入生产环境，我们就需要部署它，以便我们的客户可以访问它。根据您的项目需求和基础设施能力，您可以选择多种部署方法。（例如，Docker、Heroku、AWS）
我们将介绍在 Heroku（一个流行的平台即服务 (PaaS) 提供商）上部署 API 的步骤。
-
创建 Heroku 帐户：
首先，如果您还没有 Heroku 帐户，请创建一个。访问Heroku 网站并注册一个免费帐户。 -
安装Heroku CLI：
接下来，请按照 Heroku 网站上的说明下载并安装 Heroku CLI。安装此 CLI 后，我们将能够通过终端与 Heroku 进行交互。 -
创建新的 Heroku 应用：
安装好 Heroku CLI 后，在终端中运行以下命令来创建一个新的 Heroku 应用：
heroku create <app-name>
替换<app-name>为您想要为应用命名的名称。这将在 Heroku 上创建一个新应用，并为您提供一个访问该应用的 URL。
- 设置环境变量：如果您的 API 使用任何环境变量，例如数据库连接字符串或身份验证密钥，您也需要在 Heroku 上进行设置。您可以通过在终端中运行以下命令来完成此操作：
heroku config:set <KEY>=<VALUE>
将 `<name>`替换<KEY>为你的环境变量名称，将 ` <value>` 替换<VALUE>为其值。
-
将代码提交到 Git：
在将应用部署到 Heroku 之前，我们需要将代码提交到 Git。请确保您的代码位于 Git 仓库中，并提交您所做的任何更改。 -
部署应用：
代码提交到 Git 后，即可在终端运行以下命令将应用部署到 Heroku：
git push heroku master
这将把你的代码推送到 Heroku 并触发构建过程。构建完成后，你的应用就可以在 Heroku 上运行了。
- 扩展您的应用：如果您的应用流量很高，您可以通过在终端中运行以下命令来扩展其规模：
heroku ps:scale web=<number-of-instances>
替换<number-of-instances>为您想要运行的实例数量。
恭喜！您已成功将 API 部署到 Heroku。现在您可以使用 Heroku 提供的 URL 访问它。
结论
在本教程中，我们介绍了使用 Go 构建 API 的基础知识。首先，我们理解了 API 的概念及其用途。然后，我们探讨了使用 Go 构建 API 的优势，并搭建了开发环境。
我们学习了如何选择框架、创建基本服务器、为不同的端点添加路由和处理程序、实现 CRUD 操作、处理错误和异常、与数据库集成以及添加身份验证和授权。最后，我们讲解了如何使用 Docker 测试和部署 API。
虽然本教程已经涵盖了很多内容，但关于使用 Go 构建 API 还有很多东西需要学习。要继续你的学习之旅，请查看下面列出的其他资源：
感谢您的阅读，希望这篇教程对您有所帮助。如果您有任何问题或意见，欢迎通过LinkedIn或Twitter与我联系。
你可以请我喝杯咖啡/买本书来支持我:)
图片来自Freepik
文章来源：https://dev.to/envitab/how-to-build-an-api-using-go-ffk