1. 引言

本文將從Web應(yīng)用程序處理請求時需要用戶信息，同時HTTP又是無狀態(tài)協(xié)議這個矛盾點出發(fā)。從該問題出發(fā)，簡單描述了解決該問題的Token 機(jī)制，進(jìn)而引出Cookie的實現(xiàn)方案。

基于此我們將詳細(xì)描述Cookie的規(guī)范，然后詳細(xì)描述具體的實現(xiàn)方式，進(jìn)一步描述Gin 框架對Cookie 操作提供的API，最終提供了一個詳細(xì)的代碼實現(xiàn)。

我們還將詳細(xì)描述Gin 框架提供API 的實現(xiàn)原理，幫助用戶更好得使用這兩個API。

2. 問題引入

在 如何使用Gin搭建一個Go Web應(yīng)用程序 一文中，我們已經(jīng)了解了如何使用Gin 搭建一個簡單的Web應(yīng)用程序。然而，在現(xiàn)實的Web應(yīng)用程序中，大部分功能都是需要用戶的身份信息才能處理。舉例來說，在一個視頻網(wǎng)站查看用戶最近觀看記錄，如果缺少用戶身份信息，此時將無法對請求進(jìn)行處理。

但是HTTP協(xié)議的設(shè)計，是無狀態(tài)的，也就是每次請求都是獨立的?；诖?，應(yīng)該有一套機(jī)制，能夠在用戶身份認(rèn)證成功后，給用戶分配一個Token，后續(xù)用戶在每次請求時，都攜帶上該Token，使得服務(wù)器能夠從請求中獲取用戶信息，解決HTTP無狀態(tài)問題。大概流程如下:

上面流程中，需要服務(wù)端按照某個協(xié)議，向客戶端返回Token；客戶端通過該協(xié)議，成功解析出服務(wù)端返回的Token，然后在每次請求中攜帶該Token。然后服務(wù)器端再根據(jù)協(xié)議，從中解析出Token 信息，獲取請求用戶信息。

當(dāng)前常用的有Cookie ，Jwt，OAuth2.0 等標(biāo)準(zhǔn)，其各有優(yōu)缺點。其中Cookie 是一種存儲在客戶端瀏覽器中的數(shù)據(jù)。服務(wù)端可以通過設(shè)置HTTP響應(yīng)頭將Token 存儲在Cookie當(dāng)中，并在后續(xù)請求中從Cookie 中讀取Token。而JWT 則是一種基于JSON格式的安全令牌，可用于在客戶端和服務(wù)端之間傳遞信息。

之前，我們在 一文讀懂Cookie 中，已經(jīng)了解Cookie的相關(guān)內(nèi)容?；诖耍覀冞@次使用Cookie 來實現(xiàn)上述所說的流程，按照Cookie的規(guī)范來實現(xiàn)Token的返回和請求中Token 的解析。

3. 實現(xiàn)

3.1 Cookie規(guī)范說明

這里我們對HTTP協(xié)議中的Cookie 規(guī)范再補充一下，這里分為兩部分，第一部分是服務(wù)端如何向客戶端發(fā)送 Cookie ，第二部分是客戶端向服務(wù)端發(fā)送請求時如何攜帶Cookie 信息。

對于服務(wù)端向客戶端發(fā)送Cookie的手段，HTTP協(xié)議存在一個Set-Cookie 的頭部字段，服務(wù)器可以通過Set-Cookie 頭部字段將Cookie發(fā)送給客戶端。例如下面這個例子:

Set-Cookie: username=abc; expires=Wed, 09 Jun 2023 10:18:14 GMT; path=/

在這個例子中，服務(wù)器設(shè)置了一個名為username的Cookie，它的值是abc，過期時間是2023年6月9日，路徑為/ 。瀏覽器在接收到該Cookie 時，便將其保存起來。

客戶端請求時攜帶Cookie的方式，則是通過HTTP協(xié)議中的Cookie頭部字段，客戶端可以通過該頭部字段攜帶信息給服務(wù)器端，比如下面這個例子:

Cookie: sessionid=1234

在這個例子中，HTTP請求中攜帶了一個name 為sessionid ，value 為 1234 的 Cookie。當(dāng)服務(wù)器端接收到該HTTP 請求后，從中解析出Cookie的信息，然后基于此實現(xiàn)后續(xù)的流程。

3.2 實現(xiàn)說明

回看上述流程，主要分為兩個大部分: 客戶端和服務(wù)器端。在客戶端部分，關(guān)鍵任務(wù)包括保存瀏覽器返回的Cookie信息以及在請求時攜帶Cookie 信息給服務(wù)器。對于服務(wù)器端，則是在通過身份校驗之后，能夠按照規(guī)范客戶端返回Cookie，并在接收到請求時，能夠正確解析出請求中的 Cookie 信息，識別出用戶信息。

對于客戶端部分，在瀏覽器接收到HTTP響應(yīng)時，如果響應(yīng)體中有Set-Cookie 頭部字段，瀏覽器會自動保存Cookie信息；客戶端發(fā)起請求時，需要將 Cookie 信息傳遞給服務(wù)器。此時瀏覽器會自動攜帶通過校驗的Cookie。如果通過校驗，此時會在HTTP請求頭中攜帶Cookie信息給服務(wù)端，下面是一個大概的校驗流程:

image.png

在整個流程中，客戶端保存Token信息和在請求時攜帶Token信息這兩部分工作，瀏覽器已經(jīng)幫我們實現(xiàn)了。剩下的工作集中在服務(wù)端的，主要涉及按照Cookie的規(guī)范給客戶端返回用戶標(biāo)識，并在接收到客戶端請求時從HTTP請求中讀取Cookie以獲取到用戶的信息。與Cookie相關(guān)的詳細(xì)內(nèi)容可以參考文章一文讀懂Cookie。

因此下面我們需要做的兩件事情，其一，服務(wù)器需要按照Cookie的規(guī)范往客戶端發(fā)送Cookie的內(nèi)容；其次，服務(wù)器在處理請求時，需要從HTTP請求頭中讀取出Cookie的信息，成功識別用戶身份。

Gin 框架中提供了一些API，能夠幫助我們在服務(wù)端，按照Cookie規(guī)范給客戶端發(fā)送Cookie 信息，同時也有API 能夠幫助我們解析Cookie 的信息。下面我們先來了解相關(guān)的API，然后再基于這些API ，搭建一個能夠自動識別用戶信息的 Web 應(yīng)用程序。

3.3 API說明

3.3.1 SetCookie

gin.Context 對象中的 SetCookie 方法用于向客戶端返回響應(yīng)的同時，在Set-Cookie頭部攜帶Cookie 信息。下面是該方法的詳細(xì)說明：

func (c *Context) SetCookie(name, value string, maxAge int, path, domain string, secure, httpOnly bool)

• name：cookie 的名稱（必須）。
• value：cookie 的值（必須）。
• maxAge：cookie 的過期時間，以秒為單位。如果為負(fù)數(shù)，則表示會話 cookie（在瀏覽器關(guān)閉之后刪除），如果為零，則表示立即刪除 cookie（可選，默認(rèn)值為-1）。
• path：cookie 的路徑。如果為空字符串，則使用當(dāng)前請求的 URI 路徑作為默認(rèn)值（可選，默認(rèn)值為空字符串）。
• domain：cookie 的域名。如果為空字符串，則不設(shè)置域名（可選，默認(rèn)值為空字符串）。
• secure：指定是否僅通過 HTTPS 連接發(fā)送 cookie。如果為 true，則僅通過 HTTPS 連接發(fā)送 cookie；否則，使用 HTTP 或 HTTPS 連接都可以發(fā)送 cookie（可選，默認(rèn)值為 false）。
• httpOnly：指定 cookie 是否可通過 JavaScript 訪問。如果為 true，則無法通過 JavaScript 訪問 cookie；否則，可以通過 JavaScript 訪問 cookie（可選，默認(rèn)值為 true）。

在處理函數(shù)中，通過調(diào)用SetCookie 方法，便可以向客戶端發(fā)送一個HTTP cookie。這里舉一個代碼示例，來幫助讀者更好得理解該API，下面舉一個代碼示例，如下:

func main() {
  router := gin.Default()
  
  router.GET("/set-cookie", func(c *gin.Context) {
    c.SetCookie("user", "john", 3600, "/", "", false, true)
    c.String(http.StatusOK, "cookie set successfully")
  })
  
  router.Run(":8080")
}

在這個示例中，使用 SetCookie 方法設(shè)置一個名為user的 cookie。這個 cookie 的值是john，在 1 小時后過期。該代碼還設(shè)置了路徑為“/”以及HttpOnly屬性為true。

下面啟動該服務(wù)器，客戶端向服務(wù)端發(fā)送請求，請求路徑為/set-cookie，上面的處理函數(shù)將會被執(zhí)行，然后我們來看其響應(yīng)內(nèi)容:

# 1. 發(fā)送請求
curl -i http://localhost:8080/set-cookie
# 2. 返回響應(yīng)
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Set-Cookie: user=john; Path=/; Max-Age=3600; HttpOnly
Date: Sun, 20 Aug 2023 07:39:15 GMT
Content-Length: 23

cookie set successfully

查看上面第6行，可以看到，我們通過SetCookie方法，成功設(shè)置了一個Cookie，然后以在HTTP頭部的形式返回。

3.1.2 Cookie方法

往客戶端返回Cookie后，瀏覽器會將Cookie保存起來，然后在下次請求時將Cookie跟隨請求一起發(fā)送給服務(wù)器端。

在HTTP無狀態(tài)協(xié)議的情況下，我們使用Cookie 來識別用戶信息，此時服務(wù)器端需要正確解析出HTTP 頭部中Cookie的信息，Gin 框架中的gin.Context 提供了Cookie方法，方便我們獲取到Cookie的信息。下面是該方法的定義說明:

func (c *Context) Cookie(name string) (string, error) 

使用Cookie方法可以獲取指定名稱的Cookie值，如果不存在指定名字的Cookie，此時將會返回錯誤。下面給一個簡單示例代碼的說明:

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

    // 定義路由
    router.GET("/cookie", func(c *gin.Context) {
        // 獲取名為 "username" 的 cookie
        cookie, err := c.Cookie("username")
        if err != nil {
            // 如果 cookie 不存在，則返回錯誤信息
            c.JSON(http.StatusBadRequest, gin.H{"error": "Bad request"})
            return
        }

        // 在響應(yīng)中返回 cookie 值
        c.JSON(http.StatusOK, gin.H{"username": cookie})
    })

    router.Run(":8080")
}

在上述示例中，我們定義了一個 /cookie 路由，使用 c.Cookie("username") 方法來獲取名為 username 的 Cookie 值。如果 Cookie 不存在，則返回一個錯誤響應(yīng)。否則，我們將在響應(yīng)中返回 Cookie 的值。

下面我們通過curl 命令來對/cookie 請求，通過 -b 標(biāo)識來攜帶cookie 值:

# -v, --verbose 這個參數(shù)會打開curl的詳細(xì)模式，輸出一些額外的信息，包括HTTP請求和響應(yīng)頭信息。
curl -b -v -b "username=hello cookie;" http://localhost:8080/cookie

下面我們來看具體的請求體和響應(yīng)體的內(nèi)容:

GET /cookie HTTP/1.1
Host: localhost:8080
User-Agent: curl/7.79.1
Accept: */*
Cookie: username=hello cookie;

可以看到，我們請求體攜帶了Cookie 字段，Cookie 的名稱為 username，我們前面服務(wù)器端便是嘗試獲取名為 username 的 Cookie，下面我們看請求的響應(yīng)體，看是否成功解析了HTTP 請求 Cookie的內(nèi)容:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sun, 20 Aug 2023 08:12:45 GMT
Content-Length: 27

{"username":"hello cookie"}

可以看到，服務(wù)端程序通過Cookie方法成功解析了HTTP請求頭部中Cookie字段的值，然后將解析的結(jié)果正常返回客戶端。

3.4 代碼實現(xiàn)

下面我們來搭建一個基于Cookie 實現(xiàn)用戶身份驗證的Web 應(yīng)用程序，首先需要一個登錄頁面，用于驗證用戶身份信息，驗證通過后，我們將通過Cookie 給客戶端返回一個 Token。

同時，我們還需要創(chuàng)建一個頁面，需要驗證用戶身份信息，在驗證過程中，我們會檢查用戶請求中是否攜帶Cookie，同時Cookie 中攜帶的數(shù)據(jù)是否正確，基于此實現(xiàn)用戶身份的驗證。下面是一個簡單代碼的示例:

func main() {
   route := gin.Default()
   
   route.GET("/login", func(c *gin.Context) {
      // HTTP 響應(yīng)中攜帶 Cookie
      // Set cookie {"label": "ok" }, maxAge 30 seconds.
      c.SetCookie("label", "ok", 30, "/", "localhost", false, true)
      c.String(200, "Login success!")
   })

   route.GET("/home", func(c *gin.Context) {
      // 獲取 name = label 的 Cookie 的 value
      if cookie, err := c.Cookie("label"); err == nil {
         // 判斷 Cookie的value 是否滿足預(yù)期
         if cookie == "ok" {
            c.JSON(200, gin.H{"data": "Your home page"})
         }
      } else {
         c.JSON(http.StatusForbidden, gin.H{"error": "Forbidden with no cookie"})
      }
   })

   route.Run(":8080")
}

首先是一個/login 請求路由，通過SetCookie 方法給客戶端返回Cookie，基于此返回用戶Token。

然后/home 路由的處理，則是通過gin.Context中Cookie 方法獲取到HTTP請求頭部中Cookie的信息 ，然后驗證Cookie 中的value是否滿足預(yù)期。

這個是一個簡單的代碼示例，比如用戶身份認(rèn)證機(jī)制等，則需要自行完善，這里不再完整展示。

4. 原理

下面將簡單描述gin.Context 對象中SetCookie 方法和Cookie方法的實現(xiàn)原理，幫助讀者更好使用這兩個API。

4.1 SetCookie方法

SetCookie 方法的實現(xiàn)原理如下，首先，SetCookie 方法會創(chuàng)建一個http.Cookie對象，并設(shè)置其名稱、值、路徑、域名、過期時間等屬性。例如，以下代碼創(chuàng)建了一個名為sessionid的Cookie:

cookie := &http.Cookie{
    Name:    "sessionid",
    Value:   "1234",
    Expires: time.Now().Add(24 * time.Hour),
    Path:    "/",
    Domain:  "",
    Secure:  false,
    HttpOnly:true,
}

接下來，將上述Cookie對象轉(zhuǎn)換為字符串格式，并設(shè)置到HTTP響應(yīng)頭的Set-Cookie字段中。代碼實現(xiàn)如下：

func SetCookie(w ResponseWriter, cookie *Cookie) {
   if v := cookie.String(); v != "" {
      w.Header().Add("Set-Cookie", v)
   }
}

這里第三行將Cookie 存儲到Header 對象當(dāng)中，Header 是專門用于存儲HTTP響應(yīng)頭部的信息。調(diào)用Add 方法時，會根據(jù)指定的Key，在 Header 對象中查找相應(yīng)的值列表。如果這個鍵不存在，則會在 Header 對象中創(chuàng)建一個新的值列表；否則，會在已有的值列表末尾添加新的值，大概流程如下:

image.png

在返回HTTP響應(yīng)時，會遍歷Header 對象，填充HTTP響應(yīng)頭部信息，然后返回給客戶端，比如上面Header 生成的HTTP響應(yīng)頭部如下:

Set-Cookie: v1
Set-Cookie: v2
Agent: Windows

SetCookie 方法便是通過上述所說流程，將Cookie 的信息設(shè)置到HTTP響應(yīng)體頭部當(dāng)中去，然后返回給客戶端。

4.2 Cookie方法

在調(diào)用 Cookie() 方法時，系統(tǒng)會首先檢查請求頭部中是否包含名為 Cookie的字段。如果該字段不存在，則返回空字符串。

如果請求頭部中包含 Cookie 字段，同時Cookie 的name 為調(diào)用Cookie() 方法指定的值，則系統(tǒng)會解析該字段并將其轉(zhuǎn)換為一個 http.Cookie 對象。這個對象包含了所有的 Cookie 屬性，例如名稱、值、路徑、過期時間、域名等等。最后，返回轉(zhuǎn)換后的http.Cookie 對象中值，大概流程如下:

image.png

總的來說，Cookie() 方法的實現(xiàn)原理比較簡單，它只是通過查找 HTTP 請求頭部中的 Cookie 信息，并將其轉(zhuǎn)換為 http.Cookie 對象來獲取請求中特定 Cookie 值。

5. 總結(jié)

在本文中，我們深入探討了Web應(yīng)用程序在處理用戶信息時所面臨的挑戰(zhàn)，特別是在HTTP協(xié)議作為無狀態(tài)協(xié)議的背景下。我們從這一矛盾出發(fā)，介紹了解決方案中的Token機(jī)制，并引出了基于Cookie的實現(xiàn)方案。

我們詳細(xì)闡述了Cookie的規(guī)范，包括服務(wù)端如何發(fā)送Cookie以及客戶端如何在請求中攜帶Cookie信息。

我們進(jìn)一步深入探討了具體的實現(xiàn)方式，并介紹了Gin框架提供的API，這些API使得在服務(wù)端按照Cookie規(guī)范發(fā)送和解析Cookie變得更加容易。通過一個實際的代碼示例，我們演示了如何使用這些API來構(gòu)建一個基于Cookie實現(xiàn)用戶身份驗證的Web應(yīng)用程序。

在探討API的使用之余，我們也深入剖析了Gin框架提供的API的實現(xiàn)原理，為讀者提供了更深層次的理解。

基于此，完成了對Gin中Cookie支持的介紹，希望對你有所幫助。

本文由博客一文多發(fā)平臺 OpenWrite 發(fā)布！