第一部分：技術棧概述

1. Go語言簡介

Go（又稱Golang）是Google開發的一門靜態類型、編譯型編程語言，具有以下特點：

• 高性能：編譯為機器碼，執行效率接近C/C++

• 簡潔語法：沒有復雜的OOP概念，學習曲線平緩

• 原生并發：goroutine和channel實現高效并發

• 強大標準庫：內置HTTP、JSON、加密等常用功能

• 跨平臺：可編譯為Windows、Linux、macOS等平臺的可執行文件

2. Gin框架介紹

Gin是一個用Go編寫的高性能HTTP Web框架：

• 極速路由：基于httprouter，路由匹配速度極快

• 中間件支持：方便擴展認證、日志等功能

• JSON友好：內置高效JSON處理

• 適合API開發：輕量級設計，專注于HTTP服務

3. 開發工具鏈

• VSCode：輕量級代碼編輯器，配合Go插件提供智能提示

• Apifox：API調試工具，可替代Postman，支持：

  • 接口測試

  • 文檔生成

  • Mock數據

  • 團隊協作

第二部分：項目構建

1.創建項目

mkdir gin-api-demo
cd gin-api-demo
go mod init gin-api-demo 
//是一個 Go 語言的模塊初始化命令，用于創建一個新的 Go 模塊（module）。這個命令會生成一個 go.mod 文件，該文件用于管理項目的依賴關系。go get -u github.com/gin-gonic/gin 
//用于下載并安裝 Gin 框架，-u 表示 "update"（更新）,如果當前目錄有 go.mod 文件，會自動添加 Gin 作為依賴項，并記錄版本號,同時生成/更新 go.sum 文件，記錄依賴包的哈希校驗值（確保安全性）go mod tidy
//Go 模塊（module）管理中的一個重要命令，用于整理和優化項目的依賴關系
//添加缺失的依賴，移除未使用的依賴，同步依賴版本

2.創建main.go文件

package mainimport ("net/http""github.com/gin-gonic/gin"
)func main() {r := gin.Default()// 定義路由r.GET("/", func(c *gin.Context) {c.JSON(http.StatusOK, gin.H{"message": "Hello, Gin!",})})// 啟動服務器（默認 8080 端口）r.Run()
}

3.運行

go run main.go

瀏覽器訪問?http://localhost:8080

第三部分：用戶管理API

1.定義用戶結構體

在?main.go?中添加：

type User struct {ID   string `json:"id"`Name string `json:"name"`Age  int    `json:"age"`
}var users = []User{{ID: "1", Name: "張三", Age: 20},{ID: "2", Name: "李四", Age: 25},
}

2.獲取所有用戶（GET/users）

r.GET("/users", func(c *gin.Context) {c.JSON(http.StatusOK, users)
})

3.創建用戶（POST/users）

r.POST("/users", func(c *gin.Context) {var newUser Userif err := c.ShouldBindJSON(&newUser); err != nil {c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})return}users = append(users, newUser)c.JSON(http.StatusCreated, newUser)
})

4.獲取單個用戶（GET /users/:id）

r.GET("/users/:id", func(c *gin.Context) {id := c.Param("id")for _, user := range users {if user.ID == id {c.JSON(http.StatusOK, user)return}}c.JSON(http.StatusNotFound, gin.H{"error": "User not found"})
})

5.完整代碼

package mainimport ("net/http""github.com/gin-gonic/gin"
)type User struct {ID   string `json:"id"`Name string `json:"name"`Age  int    `json:"age"`
}var users = []User{{ID: "1", Name: "張三", Age: 20},{ID: "2", Name: "李四", Age: 25},
}func main() {r := gin.Default()r.GET("/", func(c *gin.Context) {c.JSON(http.StatusOK, gin.H{"message": "Hello, Gin!",})})r.GET("/users", func(c *gin.Context) {c.JSON(http.StatusOK, users)})r.POST("/users", func(c *gin.Context) {var newUser Userif err := c.ShouldBindJSON(&newUser); err != nil {c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})return}users = append(users, newUser)c.JSON(http.StatusCreated, newUser)})r.GET("/users/:id", func(c *gin.Context) {id := c.Param("id")for _, user := range users {if user.ID == id {c.JSON(http.StatusOK, user)return}}c.JSON(http.StatusNotFound, gin.H{"error": "User not found"})})r.Run()
}

第四部分：使用 Apifox 測試 API

1.啟動服務

go run main.go

2.在 Apifox 中測試

1. 新建項目?→?新建接口

2. 測試?GET /users

   • 方法:?GET

   • URL:?http://localhost:8080/users

   • 點擊?發送，應該返回用戶列表

3.測試?POST /users

• 方法:?POST

• URL:?http://localhost:8080/users

• Body (JSON):

{"id": "3","name": "王五","age": 30
}

• 點擊?發送，應該返回創建的用戶

可以看到狀態碼響應不對，可以進行修改

4.測試 GET?/users/：id

• 方法:?GET

• URL:?http://localhost:8080/users/1

• 點擊?發送，應該返回 ID 為 1 的用戶

第五部分：生成Swagger 文檔導入 Apifox

1.安裝 Swagger 工具

//安裝 swag 命令行工具
go install github.com/swaggo/swag/cmd/swag@latest
//驗證安裝
swag --version  # 應輸出版本號（如 v1.16.3）
//安裝 Gin 的 Swagger 依賴
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

2.為代碼添加 Swagger 注釋

(1) 在 main.go 頂部添加全局注釋
// @title          用戶管理 API（Swagger 版）
// @version        1.0
// @description    這是一個使用 Gin 和 Swagger 實現的用戶管理 API
// @host      localhost:8080
// @BasePath  /
func main() {r := gin.Default()// ...（原有代碼）
}(2) 為每個路由添加注釋
示例 1：GET /users（獲取所有用戶）
// GetUsers 獲取所有用戶
// @Summary      獲取用戶列表
// @Description  返回所有用戶數據
// @Tags         users
// @Accept       json
// @Produce      json
// @Success      200  {array}   User
// @Router       /users [get]
func GetUsers(c *gin.Context) {c.JSON(http.StatusOK, users)
}
示例 2：POST /users（創建用戶）
// CreateUser 創建用戶
// @Summary      創建新用戶
// @Description  接收 JSON 數據并創建用戶
// @Tags         users
// @Accept       json
// @Produce      json
// @Param        user  body      User  true  "用戶信息"
// @Success      201  {object}  User
// @Failure      400  {object}  map[string]string
// @Router       /users [post]
func CreateUser(c *gin.Context) {var newUser Userif err := c.ShouldBindJSON(&newUser); err != nil {c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})return}users = append(users, newUser)c.JSON(http.StatusCreated, newUser)
}
示例 3：GET /users/:id（獲取單個用戶）
// GetUserByID 獲取單個用戶
// @Summary      根據ID獲取用戶
// @Description  返回指定ID的用戶數據
// @Tags         users
// @Accept       json
// @Produce      json
// @Param        id   path      string  true  "用戶ID"
// @Success      200  {object}  User
// @Failure      404  {object}  map[string]string
// @Router       /users/{id} [get]
func GetUserByID(c *gin.Context) {id := c.Param("id")for _, user := range users {if user.ID == id {c.JSON(http.StatusOK, user)return}}c.JSON(http.StatusNotFound, gin.H{"error": "User not found"})
}

3.生成 Swagger 文檔

//(1) 運行 swag init
swag init
//生成文件：
docs/
├── docs.go       # Go 代碼
├── swagger.json  # Swagger 文檔（JSON 格式）
└── swagger.yaml  # Swagger 文檔（YAML 格式）//(2) 導入 docs 包到 main.go
import (swaggerFiles "github.com/swaggo/files"     // Swagger UI 靜態文件ginSwagger "github.com/swaggo/gin-swagger" // Gin 的 Swagger 中間件_ "github.com/gin-api-demo/docs"替換為你的模塊名（和 go.mod 一致）// ...其他導入
)//(3)打開項目根目錄的 go.mod 文件，第一行應類似：
module github.com/你的用戶名/gin-api-demo  （沒有用戶名就不寫）//(4) 添加 Swagger UI 路由
func main() {r := gin.Default()r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))// ...（其他路由）r.Run()
}//最后來一下go mod tidy   養成好習慣

4.運行并訪問 Swagger UI

//(1) 啟動服務器
go run main.go
//(2) 訪問 Swagger UI
http://localhost:8080/swagger/index.html

?5.導入 Swagger 到 Apifox

(1) 導出?swagger.json

文件路徑：docs/swagger.json。

(2) 在 Apifox 中導入

1. 打開 Apifox → 項目 → 導入 → 選擇?swagger.json。

2. 點擊?確定，Apifox 會自動解析所有接口。

(3) 在 Apifox 中測試

• 查看自動生成的接口文檔。

• 直接發送請求測試（無需手動配置參數）。

總結：swagger文檔和apifox搭配可以更加方便導入項目的接口。