GO：Hello Gin 2.入门篇——中间件、文件上传、静态资源

基础知识

中间件（Middleware）

中间件（Middleware）是一种位于请求处理流程中的软件组件，它可以在请求到达最终处理程序之前或响应发送给客户端之后执行特定的功能。中间件的概念在许多Web开发框架中都有应用，如Express.js（Node.js）、Django（Python）、Gin（Go）等，它们提供了一种灵活的方式来处理HTTP请求和响应，例如日志记录、身份验证、会话管理、数据验证、CORS设置等。

中间件的工作原理

• 链式处理：中间件通常以链式的方式组织，一个请求通过这个链条时，可以被一个或多个中间件依次处理。每个中间件可以决定是否将请求传递给链中的下一个中间件，或者直接返回响应结束请求处理流程。
• 请求预处理：在请求到达最终的处理函数之前，中间件可以对请求进行预处理，如解析请求体、验证用户身份、记录请求日志等。
• 响应后处理：在最终的处理函数生成响应后，中间件还可以对响应进行后处理，如添加HTTP头、压缩响应体、记录响应日志等。
• 错误处理：中间件还常用于统一的错误处理，捕获处理过程中出现的异常或错误，并返回统一格式的错误响应。

中间件的特点

• 重用性：中间件封装了通用的功能，可以在不同的应用或请求处理流程中重用。
• 灵活性：可以根据需要灵活地添加、移除或更改中间件，调整请求处理流程。
• 解耦性：中间件帮助将应用逻辑分解为更小、更易于管理的部分，增强了代码的模块化和可维护性。

Multipart/Urlencoded

Multipart/Urlencoded是两种常见的HTTP请求内容类型（Content-Type），它们通常用于Web表单数据的提交。在Web开发中，理解这两种内容类型及其用途非常重要。

application/x-www-form-urlencoded

• Content-Type: application/x-www-form-urlencoded
• 用途: 这是最常见的内容类型之一，用于提交表单数据。当你在HTML表单中不设置enctype属性时，默认就是使用这种方式提交数据。
• 特点: 表单数据会被编码为键值对，类似key1=value1&key2=value2。字符会被编码成%XX格式，其中XX是字符的ASCII码的十六进制表示。例如，空格会被编码为%20。
• 适用场景: 适用于提交简单的文本数据，但不适合用来传输大型的二进制数据，如文件上传。

multipart/form-data

• Content-Type: multipart/form-data
• 用途: 这种内容类型用于当表单中有文件上传操作时，或者表单数据较为复杂（例如，包含大量数据或JSON对象）时。在HTML表单中，通过设置enctype="multipart/form-data"来启用。
• 特点: 数据被分割成多个部分（parts），每个部分对应表单的一个字段，并且每部分都有自己的Content-Type。这种方式允许在一个请求中同时发送文本和二进制数据（如文件）。
• 适用场景: 主要用于文件上传，或当表单数据非常复杂时。

Gin代码示例

1. 模型绑定和验证

Gin允许您将请求的数据（如JSON、XML或表单数据）自动绑定到Go的结构体中，并且可以利用标签（Tag）来对数据进行验证。

示例代码：

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
    "github.com/go-playground/validator/v10"
)

type LoginForm struct {
    User     string `form:"user" binding:"required"`
    Password string `form:"password" binding:"required"`
}

func main() {
    r := gin.Default()
    r.POST("/login", func(c *gin.Context) {
        var form LoginForm
        if err := c.ShouldBind(&form); err != nil {
            if _, ok := err.(validator.ValidationErrors); ok {
                c.JSON(http.StatusBadRequest, gin.H{"error": "All fields are required."})
                return
            }
            c.JSON(http.StatusInternalServerError, gin.H{"error": "An error occurred."})
            return
        }
        c.JSON(http.StatusOK, gin.H{"status": "You are logged in"})
    })
    r.Run()
}

2. 上传文件

处理文件上传是Web开发中的常见需求。Gin提供了简单的API来处理单文件和多文件上传。

示例代码：

package main

import (
    "github.com/gin-gonic/gin"
    "net/http"
)

func main() {
    r := gin.Default()
    r.POST("/upload", func(c *gin.Context) {
        file, _ := c.FormFile("file")
        c.SaveUploadedFile(file, file.Filename)
        c.String(http.StatusOK, "File uploaded successfully: "+file.Filename)
    })
    r.Run()
}

3. 使用中间件

中间件是Gin处理HTTP请求的关键组成部分，它可以处理请求、修改请求或响应，并决定是否将请求传递给下一个处理函数。

示例代码：

package main

import (
    "github.com/gin-gonic/gin"
    "log"
    "time"
)

func LoggerMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        t := time.Now()
        c.Set("example", "12345")  // 在中间件中设置值
        c.Next()  // 处理请求

        latency := time.Since(t)
        log.Print(latency)

        // 请求处理后的操作
        status := c.Writer.Status()
        log.Println(status)
    }
}

func main() {
    r := gin.Default()
    r.Use(LoggerMiddleware())  // 使用自定义中间件
    r.GET("/test", func(c *gin.Context) {
        example := c.MustGet("example").(string)
        c.String(http.StatusOK, "Middleware test "+example)
    })
    r.Run()
}

4. 自定义中间件

自定义中间件的示例已经在之前的解释中提及，这里我将提供一个额外的示例，展示如何创建一个简单的认证中间件：

package main

import (
    "github.com/gin-gonic/gin"
    "net/http"
)

// AuthMiddleware 是一个简单的认证中间件示例
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 检查请求头中是否包含特定的认证token
        token := c.GetHeader("Authorization")
        if token != "Bearer some-secret-token" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Unauthorized"})
            return
        }
        c.Next() // 如果认证成功，则继续处理请求
    }
}

func main() {
    r := gin.Default()
    r.Use(AuthMiddleware()) // 应用认证中间件

    r.GET("/protected", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"message": "You are authorized to see this message"})
    })

    r.Run()
}

5. 日志记录

Gin框架自带的日志记录功能足够强大，但如果你想要自定义日志记录方式，可以通过编写自定义中间件来实现。以下示例展示如何记录每个请求的处理时间：

package main

import (
    "github.com/gin-gonic/gin"
    "log"
    "time"
)

// LoggerMiddleware 记录每个请求的处理时间
func LoggerMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        startTime := time.Now()
        c.Next() // 处理请求
        endTime := time.Since(startTime)
        log.Printf("请求 %s 处理时间 %v", c.Request.URL.Path, endTime)
    }
}

func main() {
    r := gin.Default()
    r.Use(LoggerMiddleware()) // 使用自定义的日志中间件

    r.GET("/ping", func(c *gin.Context) {
        c.String(http.StatusOK, "pong")
    })

    r.Run()
}

6. Multipart/Urlencoded绑定

处理来自表单的复杂数据时，可以使用Multipart/Urlencoded绑定。以下示例展示了如何绑定表单数据到Go的结构体中：

package main

import (
    "github.com/gin-gonic/gin"
    "net/http"
)

type ProfileForm struct {
    Name    string `form:"name" binding:"required"`
    Age     int    `form:"age" binding:"required,gt=0"`
    Email   string `form:"email" binding:"required,email"`
}

func main() {
    r := gin.Default()

    r.POST("/profile", func(c *gin.Context) {
        var form ProfileForm
        // 绑定表单数据至结构体
        if err := c.ShouldBind(&form); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        c.JSON(http.StatusOK, gin.H{"message": "Profile updated", "data": form})
    })

    r.Run()
}

7. 绑定表单数据至自定义结构体

绑定表单数据到自定义结构体是一个常见的需求，特别是在处理表单提交的Web应用中。在Gin框架中，你可以通过ShouldBind、ShouldBindJSON、ShouldBindXML等方法，根据请求的内容类型自动选择合适的绑定器来实现。以下是一个使用ShouldBind方法绑定表单数据到自定义结构体的示例，这个方法会根据请求的Content-Type自动选择是使用JSON绑定、表单绑定还是XML绑定。

package main

import (
	"github.com/gin-gonic/gin"
	"net/http"
)

// LoginForm 定义了登录表单的结构，用于绑定表单数据
type LoginForm struct {
	Username string `form:"username" binding:"required"`
	Password string `form:"password" binding:"required"`
}

func main() {
	r := gin.Default()

	r.POST("/login", func(c *gin.Context) {
		var form LoginForm
		// 使用ShouldBind绑定表单数据到LoginForm结构体
		if err := c.ShouldBind(&form); err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		// 假设这里是一些业务逻辑处理，例如验证用户名和密码
		// ...

		// 响应客户端
		c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
	})

	r.Run() // 默认监听并在 0.0.0.0:8080 上启动服务
}

这个示例中，我们定义了一个LoginForm结构体，它包含了Username和Password两个字段，这些字段通过form标签与客户端提交的表单数据中的键对应起来。当客户端向/login路由发送POST请求并提交表单数据时，ShouldBind方法会尝试将请求中的数据绑定到LoginForm实例上。如果绑定成功，就可以在处理函数中使用这些数据了。如果绑定失败（例如，因为缺少某个必要的字段），则会响应一个错误。

8. 路由组

路由组是一种组织路由的方式，使得可以共享中间件或路径前缀。

示例代码：

package main

import (
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()

    // 创建一个路由组
    v1 := r.Group("/v1")
    {
        v1.POST("/login", loginEndpoint)
        v1.POST("/submit", submitEndpoint)
        v1.POST("/read", readEndpoint)
    }

    // 创建另一个路由组
    v2 := r.Group("/v2")
    {
        v2.POST("/login", loginEndpoint)
        v2.POST("/submit", submitEndpoint)
        v2.POST("/read", readEndpoint)
    }

    r.Run()
}

func loginEndpoint(c *gin.Context) {
    c.String(200, "Login")
}

func submitEndpoint(c *gin.Context) {
    c.String(200, "Submit")
}

func readEndpoint(c *gin.Context) {
    c.String(200, "Read")
}

9. 静态资源嵌入

将静态资源（如HTML、CSS、JavaScript文件）嵌入到Go应用中，可以使用go:embed特性。

示例代码：

package main

import (
    "embed"
    "github.com/gin-gonic/gin"
    "net/http"
)

//go:embed assets/*
var fs embed.FS

func main() {
    r := gin.Default()

    // 使用http.FS将嵌入的文件系统转换成http.FileSystem
    r.StaticFS("/assets", http.FS(fs))

    r.Run()
}

综合代码示例

这个示例将包含用户注册、登录、上传头像以及访问一个受保护的路由。我们还会使用中间件来处理日志记录和简单的认证。

为了简化示例，我们将不会实际连接数据库，而是使用一个简单的内存数据结构来模拟用户存储。此外，上传的文件将被保存在本地文件系统中。

项目结构：

/gin-demo
    /assets  // 存放静态资源
    /uploads // 存放用户上传的文件
    main.go

可以使用命令新建

# debian/ubuntu
mkdir -p gin-demo/assets gin-demo/uploads
touch gin-demo/main.go
# win
mkdir gin-demo\assets gin-demo\uploads
type nul > gin-demo\main.go

主要逻辑：

1. 静态资源服务：使用embed包嵌入静态资源（如图片、JS、CSS文件），并通过/assets路径提供访问。
2. 用户注册与登录：
   • 允许用户通过提交表单进行注册，将用户名和密码存储在内存中的users映射里。
   • 登录时检查提交的用户名和密码，如果匹配则返回登录成功的消息。
3. 文件上传：提供了一个文件上传的接口，用户可以上传文件，服务器将文件保存在本地的./uploads目录下。
4. 受保护的路由：通过一个简单的认证中间件AuthMiddleware，对特定的路由（如/profile）进行保护。只有在请求头中包含正确的Authorization令牌时，用户才能访问这些路由。
5. 日志中间件：为每个请求打印日志，包括客户端IP、请求方法、路径、响应状态码和请求处理时间。
6. 启动服务：应用监听在0.0.0.0:8080地址，等待处理入站的HTTP请求。

代码

main.go

package main

import (
    "embed"
    "fmt"
    "github.com/gin-gonic/gin"
    "log"
    "net/http"
    "os"
    "path/filepath"
    "time"
)

//go:embed assets/*
var fs embed.FS

type User struct {
    Username string `form:"username" binding:"required"`
    Password string `form:"password" binding:"required"`
}

var users = make(map[string]string) // 模拟用户存储

func main() {
    r := gin.Default()

    // 日志中间件
    r.Use(func(c *gin.Context) {
        startTime := time.Now()
        c.Next()
        log.Printf("[%s] \"%s %s\" %d %s", c.ClientIP(), c.Request.Method, c.Request.URL.Path, c.Writer.Status(), time.Since(startTime))
    })

    // 静态资源
    r.StaticFS("/assets", http.FS(fs))

    // 用户注册
    r.POST("/register", func(c *gin.Context) {
        var newUser User
        if err := c.ShouldBind(&newUser); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        // 简化示例，不处理用户已存在的情况
        users[newUser.Username] = newUser.Password
        c.JSON(http.StatusOK, gin.H{"message": "Registration successful"})
    })

    // 用户登录
    r.POST("/login", func(c *gin.Context) {
        var loginUser User
        if err := c.ShouldBind(&loginUser); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        password, ok := users[loginUser.Username]
        if !ok || password != loginUser.Password {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Unauthorized"})
            return
        }
        c.JSON(http.StatusOK, gin.H{"message": "Login successful"})
    })

    // 文件上传
    r.POST("/upload", func(c *gin.Context) {
        file, err := c.FormFile("file")
        if err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        filename := filepath.Base(file.Filename)
        if err := c.SaveUploadedFile(file, "./uploads/"+filename); err != nil {
            c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
            return
        }
        c.JSON(http.StatusOK, gin.H{"message": "File uploaded successfully", "filename": filename})
    })

    // 受保护的路由
    authorized := r.Group("/", AuthMiddleware())
    authorized.GET("/profile", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"message": "Welcome to your profile"})
    })

    r.Run() // 监听并在 0.0.0.0:8080 上启动服务
}

// AuthMiddleware 是一个简单的认证中间件示例
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 这里简化认证过程，实际应用中应该使用更安全的认证方式
        token := c.GetHeader("Authorization")
        if token != "Bearer secret-token" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Unauthorized"})
            return
        }
        c.Next()
    }
}

1. 运行你的Go程序：go run main.go。
2. 使用Postman或任何其他HTTP客户端工具，测试各个API端点：
   • POST /register：注册新用户。
   • POST /login：用户登录。
   • POST /upload：上传文件（需要在请求头中添加Authorization: Bearer secret-token）。
   • GET /profile：访问受保护的个人资料页面（需要在请求头中添加Authorization: Bearer secret-token）。