编辑“︁Gin CORS中间件”︁

= Gin CORS中间件 =

== 介绍 ==
'''CORS'''（Cross-Origin Resource Sharing，跨源资源共享）是一种安全机制，用于控制不同源的Web应用程序之间的资源访问。在Gin框架中，'''CORS中间件'''允许开发者轻松配置服务器以处理跨域请求，确保前端应用（如React、Vue或Angular）能够安全地与后端API通信。

当浏览器发起跨域请求时，会先发送一个'''预检请求'''（OPTIONS方法）来检查服务器是否允许实际请求。Gin的CORS中间件通过设置HTTP响应头（如`Access-Control-Allow-Origin`）来声明服务器的跨域策略。

== 基本用法 ==
Gin提供了一个内置的CORS中间件，可通过`github.com/gin-contrib/cors`包引入。以下是一个基本配置示例：

<syntaxhighlight lang="go">
package main

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

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

    // 默认配置（允许所有来源）
    r.Use(cors.Default())

    r.GET("/ping", func(c *gin.Context) {
        c.JSON(200, gin.H{
            "message": "pong",
        })
    })

    r.Run(":8080")
}
</syntaxhighlight>

=== 输出示例 ===
当客户端从`http://localhost:3000`发起请求时，响应头将包含：
<pre>
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: *
</pre>

== 自定义配置 ==
开发者可以通过`cors.Config`结构体自定义CORS策略。以下是常见配置选项：

<syntaxhighlight lang="go">
config := cors.Config{
    AllowOrigins:     []string{"https://example.com"},
    AllowMethods:     []string{"GET", "POST", "PUT", "DELETE"},
    AllowHeaders:     []string{"Origin", "Content-Type"},
    ExposeHeaders:    []string{"Content-Length"},
    AllowCredentials: true,
    MaxAge:           12 * time.Hour,
}

r.Use(cors.New(config))
</syntaxhighlight>

=== 参数说明 ===
* '''AllowOrigins'''：允许的源列表（如`["https://example.com"]`），`*`表示允许所有源。
* '''AllowMethods'''：允许的HTTP方法（如`GET`, `POST`）。
* '''AllowHeaders'''：允许的请求头。
* '''ExposeHeaders'''：允许客户端访问的响应头。
* '''AllowCredentials'''：是否允许发送凭据（如Cookies）。
* '''MaxAge'''：预检请求的缓存时间。

== 实际案例 ==
=== 场景：前后端分离项目 ===
假设前端运行在`http://localhost:3000`，后端API在`http://localhost:8080`。配置如下：

<syntaxhighlight lang="go">
config := cors.Config{
    AllowOrigins:     []string{"http://localhost:3000"},
    AllowMethods:     []string{"GET", "POST", "OPTIONS"},
    AllowHeaders:     []string{"Authorization", "Content-Type"},
    ExposeHeaders:    []string{"X-Total-Count"},
    AllowCredentials: true,
}

r.Use(cors.New(config))
</syntaxhighlight>

=== 请求流程 ===
<mermaid>
sequenceDiagram
    participant Client as 客户端 (http://localhost:3000)
    participant Server as 服务器 (http://localhost:8080)
    Client->>Server: OPTIONS /api/data
    Server-->>Client: 204 No Content (包含CORS头)
    Client->>Server: GET /api/data
    Server-->>Client: 200 OK (数据 + CORS头)
</mermaid>

== 常见问题 ==
=== 1. 预检请求失败 ===
如果浏览器控制台出现错误：
<pre>
Access to XMLHttpRequest at 'http://localhost:8080/api' from origin 'http://localhost:3000' has been blocked by CORS policy
</pre>
检查是否：
* 配置了正确的`AllowOrigins`。
* 包含`OPTIONS`方法在`AllowMethods`中。

=== 2. 凭据未发送 ===
如果使用`AllowCredentials: true`，需确保：
* `AllowOrigins`不能为`*`，必须指定具体域名。
* 前端请求设置`withCredentials: true`（如Axios中配置）。

== 数学表达 ==
CORS的预检请求缓存时间（`MaxAge`）可通过以下公式计算：
<math>
T_{\text{cache}} = n \times t
</math>
其中：
* <math>n</math>为时间数值，
* <math>t</math>为单位时间（如`time.Hour`）。

== 总结 ==
Gin的CORS中间件是处理跨域请求的核心工具。通过合理配置，开发者可以：
* 控制允许访问的源、方法和头部。
* 支持凭据传输和缓存优化。
* 适应前后端分离架构的安全需求。

建议在生产环境中严格限制`AllowOrigins`，避免使用通配符`*`以增强安全性。

[[Category:后端框架]]
[[Category:Gin]]
[[Category:Gin中间件]]