vault backup: 2026-04-28 08:53:28
This commit is contained in:
@@ -54,16 +54,7 @@ v3 := r.Group("/api/v3") // ← 分组注册下很容易忘记加 cors()
|
||||
|
||||
**3. OPTIONS 预检拦截天然正确**
|
||||
|
||||
CORS 的核心逻辑是在最外层处理 `OPTIONS` 预检请求：
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
OPTIONS["OPTIONS 预检请求"] --> CORS["全局 CORS 中间件<br/>c.AbortWithStatus(204)"]
|
||||
OPTIONS --> SKIP["不进入后续中间件和 handler"]
|
||||
|
||||
style CORS fill:#90EE90
|
||||
style SKIP fill:#FFB6C1
|
||||
```
|
||||
CORS 的核心逻辑是在最外层处理 `OPTIONS` 预检请求——预检触发条件、两轮对话机制、Header 语义详见 [[BACKEND/GIN/3-middleware/cors-registration-scope/cors-preflight|cors-preflight]]。
|
||||
|
||||
放在全局中间件中，预检请求在最早阶段被拦截，不会消耗后续中间件的算力。
|
||||
|
||||
@@ -96,6 +87,7 @@ v2 := r.Group("/api/v2", corsStrict([]string{"https://app.example.com"}))
|
||||
|
||||
## 关联笔记
|
||||
|
||||
- [[GIN/3-middleware/cors-preflight]] — OPTIONS 预检请求完整机制（触发条件、两轮对话、Max-Age 缓存）
|
||||
- [[GIN/3-middleware]] — 中间件三级作用域机制
|
||||
- [[GIN/3-middleware-abort]] — `c.Abort()` 终止机制
|
||||
- [[middleware-abort]] — `c.Abort()` 终止机制
|
||||
- [[GIN/gin-architecture]] — 中间件链底层执行机制
|
||||
|
||||
@@ -0,0 +1,184 @@
|
||||
---
|
||||
tags: [后端, Go, Gin, CORS, 跨域, 预检]
|
||||
create time: 2026-04-27 13:00
|
||||
---
|
||||
|
||||
# CORS OPTIONS 预检请求详解
|
||||
|
||||
## 概述
|
||||
|
||||
当浏览器发起**跨域非简单请求**时，会在实际请求之前先发送一个 `OPTIONS` 预检请求，询问服务端是否允许该操作。本文完整解析预检触发条件、两轮对话流程及底层机制。
|
||||
|
||||
## 正文
|
||||
|
||||
### 什么时候触发预检？
|
||||
|
||||
并非所有跨域请求都经过预检。以下四种情况**之一满足即触发**：
|
||||
|
||||
| 触发条件 | 说明 |
|
||||
|---------|------|
|
||||
| 方法不是简单方法 | 使用了 `PUT`、`DELETE`、`PATCH`、`HEAD` 等 |
|
||||
| 请求头包含自定义 Header | 如 `X-Token`、`Authorization`（`Accept`/`Content-Type`/`Language` 除外） |
|
||||
| `Content-Type` 是非简单类型 | 如 `application/json`；`text/plain`、`multipart/form-data`、`application/x-www-form-urlencoded` 是简单类型 |
|
||||
| 跨域且携带凭证 | `withCredentials: true` 或 `credentials: "include"` |
|
||||
|
||||
> **思考**：为什么同源请求不需要预检？因为同源策略本身就已经限制了跨站操作的安全性，不需要额外协商。
|
||||
|
||||
### 预检的两轮对话
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant B as 浏览器
|
||||
participant S as 服务端
|
||||
|
||||
B->>S: OPTIONS /api/resource
|
||||
Note over B,S: Origin<br/>Access-Control-Request-Method<br/>Access-Control-Request-Headers
|
||||
S-->>B: 204 No Content
|
||||
Note over B,S: Access-Control-Allow-Origin<br/>Access-Control-Allow-Methods<br/>Access-Control-Allow-Headers<br/>Access-Control-Max-Age
|
||||
B->>S: PUT /api/resource
|
||||
Note over B,S: Origin<br/>X-Token: xxx
|
||||
S-->>B: 200 OK + CORS headers
|
||||
|
||||
rect rgba(200, 255, 200, 0.3)
|
||||
Note over B,B: ① 预检请求
|
||||
end
|
||||
rect rgba(255, 255, 200, 0.3)
|
||||
Note over S,S: ② 预检响应
|
||||
end
|
||||
rect rgba(200, 200, 255, 0.3)
|
||||
Note over B,B: ③ 实际请求
|
||||
end
|
||||
rect rgba(255, 200, 200, 0.3)
|
||||
Note over S,S: ④ 实际响应
|
||||
end
|
||||
```
|
||||
|
||||
#### ① 预检请求 — 浏览器发问
|
||||
|
||||
```http
|
||||
OPTIONS /api/resource HTTP/1.1
|
||||
Host: api.example.com
|
||||
Origin: https://app.example.com
|
||||
Access-Control-Request-Method: PUT
|
||||
Access-Control-Request-Headers: X-Token, Content-Type
|
||||
```
|
||||
|
||||
两个关键自定义 Header 由浏览器**自动添加**，开发者无法操控：
|
||||
- `Access-Control-Request-Method` — 打算用的 HTTP 方法
|
||||
- `Access-Control-Request-Headers` — 打算带的自定义 Header 列表
|
||||
|
||||
#### ② 预检响应 — 服务端答复
|
||||
|
||||
```http
|
||||
HTTP/1.1 204 No Content
|
||||
Access-Control-Allow-Origin: https://app.example.com
|
||||
Access-Control-Allow-Methods: PUT, GET, POST, DELETE
|
||||
Access-Control-Allow-Headers: X-Token, Content-Type
|
||||
Access-Control-Max-Age: 86400
|
||||
```
|
||||
|
||||
注意用 `204 No Content`——预检**没有响应体**，因为还没确认要处理实际请求。
|
||||
|
||||
#### ③ 实际请求 — 预检通过后才发
|
||||
|
||||
```http
|
||||
PUT /api/resource HTTP/1.1
|
||||
Host: api.example.com
|
||||
Origin: https://app.example.com
|
||||
X-Token: eyJhbG...
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
如果预检失败（收到非 2xx 或缺少必要 header），浏览器直接**静默拒绝**，不会发送实际请求。
|
||||
|
||||
#### ④ 实际响应 — 浏览器二次校验
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Access-Control-Allow-Origin: https://app.example.com
|
||||
Access-Control-Allow-Credentials: true
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
浏览器的实际请求**不经过预检**，但浏览器仍会检查响应中的 CORS header 是否匹配当前页面来源。
|
||||
|
||||
### 关键 Header 速查
|
||||
|
||||
| 请求/Header | 方向 | 作用 |
|
||||
|-------------|------|------|
|
||||
| `Origin` | → 和 ↩ | 当前页面的源（协议+域名+端口），**不可自定义** |
|
||||
| `Access-Control-Allow-Origin` | ↩ | 允许的源；与 `credentials: true` 搭配时不能为 `*` |
|
||||
| `Access-Control-Allow-Methods` | ↩ | 预检通过的 HTTP 方法列表（逗号分隔） |
|
||||
| `Access-Control-Allow-Headers` | ↩ | 预检通过的自定义 Header 列表 |
|
||||
| `Access-Control-Max-Age` | ↩ | 预检结果缓存时长（秒），期间不再发 OPTIONS |
|
||||
| `Access-Control-Allow-Credentials` | ↩ | 是否允许带 Cookie/认证信息 |
|
||||
| `Access-Control-Expose-Headers` | ↩ | 允许 JS `getResponseHeader()` 读取的响应头白名单 |
|
||||
|
||||
> **常见坑**：`Allow-Credentials: true` 时 `Allow-Origin` 必须写死具体域名，不能用 `*`。这是浏览器强制校验的安全策略。
|
||||
|
||||
### Max-Age 缓存机制
|
||||
|
||||
浏览器会对成功的预检结果做缓存：
|
||||
|
||||
- `Max-Age: 86400` = 24 小时内再次访问同一路径，浏览器**跳过预检**直接发实际请求
|
||||
- 不同路径、不同方法、不同 Origin 视为不同的预检条目，各自独立缓存
|
||||
- 如果服务端返回 `Max-Age: 0`，浏览器每次都会预检
|
||||
|
||||
这也是为什么优化跨域性能时，把 `Max-Age` 设置大一些比取消中间件顺序更有意义。
|
||||
|
||||
### Gin 中的实现要点
|
||||
|
||||
对应的中间件逻辑非常简单——**只要区分是否是 OPTIONS 请求**：
|
||||
|
||||
```go
|
||||
func CORSMiddleware() gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
if c.Request.Method == http.MethodOptions {
|
||||
// 预检请求：只设 header + 拦截
|
||||
c.Header("Access-Control-Allow-Origin", "*")
|
||||
c.Header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
|
||||
c.Header("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Token")
|
||||
c.AbortWithStatus(http.StatusNoContent) // 204, 无 Body
|
||||
return
|
||||
}
|
||||
// 实际请求：正常走链，但响应头里也要注入 CORS（供浏览器校验）
|
||||
c.Header("Access-Control-Allow-Origin", "*")
|
||||
c.Next()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
核心就两件事：
|
||||
- **OPTIONS → 只设 header，`c.Abort()` 终止链**，不进任何 handler
|
||||
- **其他方法 → 正常请求，但 `c.Header()` 注入 header 到最终响应**（浏览器的实际请求需要这些 header 来确认服务端确实允许）
|
||||
|
||||
这就是为什么它适合注册为全局中间件——不在路由匹配前拦截预检的话，Gin 会因为找不到 `OPTIONS` 路由而返回 405/404，浏览器认为预检失败就直接阻塞了后续所有请求。
|
||||
|
||||
### 前后端对照
|
||||
|
||||
同一接口的完整交互视角（前端发起）：
|
||||
|
||||
```ts
|
||||
// 前端代码
|
||||
fetch("https://api.example.com/resource", {
|
||||
method: "PUT",
|
||||
credentials: "include", // ← 触发携带凭证模式
|
||||
headers: {
|
||||
"Content-Type": "application/json", // ← 触发预检（非简单 Content-Type）
|
||||
"X-Token": token, // ← 触发预检（自定义 Header）
|
||||
},
|
||||
body: JSON.stringify({ name: "updated" }),
|
||||
})
|
||||
```
|
||||
|
||||
上述代码在实际发 `PUT` 请求前，浏览器必定先发一轮 `OPTIONS`。如果把其中任意一个触发条件去掉（比如改用 `GET` + `text/plain`），就可以省去预检往返。
|
||||
|
||||
## 关联笔记
|
||||
|
||||
- [[cors-registration-scope]] — 全局 vs 分组注册 CORS 中间件的取舍
|
||||
- [[GIN/3-middleware]] — 中间件三级作用域机制
|
||||
- [[middleware-abort]] — `c.Abort()` 终止机制
|
||||
- [[GIN/3-middleware]] — 中间件三级作用域机制
|
||||
- [[middleware-abort]] — `c.Abort()` 终止机制
|
||||
@@ -102,4 +102,4 @@ func (c *Context) Next() {
|
||||
## 关联笔记
|
||||
|
||||
- [[GIN/3-middleware]] — 中间件完整机制
|
||||
- [[GIN/3-middleware-abort]] — `c.Abort()` 终止机制详解
|
||||
- [[middleware-abort]] — `c.Abort()` 终止机制详解
|
||||
|
||||
@@ -0,0 +1,130 @@
|
||||
---
|
||||
tags: [后端, Go, Gin, 中间件, 架构]
|
||||
create time: 2026-04-27 12:51
|
||||
---
|
||||
|
||||
# c.Abort() 终止机制
|
||||
|
||||
## 概述
|
||||
|
||||
本文档解答中间件文档中的思考题：当中间件 A 调用 `c.Abort()` 后，后续中间件、handler 以及 A 自身代码的执行情况。
|
||||
|
||||
## 正文
|
||||
|
||||
### 思考题
|
||||
|
||||
如果中间件 A 中调用了 `c.Abort()`（不调用 `c.Next()`），中间件 B 和 handler 还会执行吗？那 A 中 `c.Abort()` 之后的代码还会执行吗？
|
||||
|
||||
**两个问题的答案都是「不会执行」。**
|
||||
|
||||
### 1. 中间件 B 和 handler 还会执行吗？
|
||||
|
||||
**不会。** `c.Abort()` 会立即终止整个中间件链。
|
||||
|
||||
要理解原因，需要看 `c.Next()` 的内部实现——它按索引遍历 `c.handlers` 切片：
|
||||
|
||||
```go
|
||||
func (c *Context) Next() {
|
||||
c.index++
|
||||
for ; c.index < int8(len(c.handlers)); c.index++ {
|
||||
c.handlers[c.index](c)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`c.Abort()` 内部做了两件事：
|
||||
|
||||
1. 设置 `c.IsAborted = true` 标记
|
||||
2. **将 `c.index` 设置为 handler 链的长度**，使得 `c.Next()` 的 for 循环条件立即不满足
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph 正常流程
|
||||
N1["c.index = 0"] --> N2["c.handlers[0] 执行"] --> N3["c.Next() → c.index++"] --> N4["c.handlers[1] 执行"] --> N5["继续..."]
|
||||
end
|
||||
|
||||
subgraph Abort 流程
|
||||
A1["c.index = 0"] --> A2["c.handlers[0] 执行"] --> A3["c.Abort()"] --> A4["c.index 设为链长度"] --> A5["c.Next() → for 条件不满足，直接退出"]
|
||||
end
|
||||
|
||||
style A4 fill:#FF6B6B
|
||||
style A5 fill:#FFD700
|
||||
```
|
||||
|
||||
所以中间件 B 和 handler **都会被跳过**。
|
||||
|
||||
### 2. A 中 c.Abort() 之后的代码还会执行吗？
|
||||
|
||||
**不应该执行。** 因为 `c.Abort()` 调用之后紧接着就是 `return`：
|
||||
|
||||
```go
|
||||
func jwtAuth() gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
token := c.GetHeader("Authorization")
|
||||
if token == "" {
|
||||
c.JSON(http.StatusUnauthorized, gin.H{"code": 401, "message": "missing token"})
|
||||
c.Abort()
|
||||
return // ← 立即返回，后面的代码不会执行
|
||||
}
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 忘记 return 的后果
|
||||
|
||||
如果忘记写 `return`，Go 语法层面 `c.Abort()` 之后的代码**仍然会执行**，但后续再调用 `c.Next()` 时中间件链会被终止。这会导致**后置处理逻辑意外执行**，是典型的 Bug：
|
||||
|
||||
```go
|
||||
// 危险写法！
|
||||
func badMiddleware() gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
start := time.Now()
|
||||
|
||||
if someCondition {
|
||||
c.Abort()
|
||||
// 忘记 return → 继续执行下面代码
|
||||
}
|
||||
|
||||
c.Next() // ← 由于 c.index 已被设为链长度，这里不会进入下一个中间件
|
||||
// 但「下面的」后置代码会执行！
|
||||
|
||||
// 这段后置代码在不应该执行的时候被执行了
|
||||
log.Printf("耗时: %v", time.Since(start))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. AbortWithStatus
|
||||
|
||||
Gin 还提供了 `c.AbortWithStatus(code)`，它在调用 `c.Abort()` 的同时写入响应状态码（body 为空），适合预检请求等场景：
|
||||
|
||||
```go
|
||||
func cors() gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
if c.Request.Method == "OPTIONS" {
|
||||
c.AbortWithStatus(http.StatusNoContent)
|
||||
return // 同样需要 return
|
||||
}
|
||||
c.Next()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
也有 `c.AbortWithStatusJSON(code, json)`，在 Abort 的同时写入 JSON 响应体。
|
||||
|
||||
## 总结
|
||||
|
||||
| 调用 `c.Abort()` 后 | 结果 |
|
||||
|---|---|
|
||||
| 后续中间件（B、C…） | ❌ 不执行 |
|
||||
| Handler | ❌ 不执行 |
|
||||
| 后续中间件链中的 `c.Next()` | ❌ 不会进入下一个 |
|
||||
| A 中 `c.Abort()` 之后的代码 | ❌ 不应该执行（必须紧跟 `return`） |
|
||||
|
||||
**核心规则：`c.Abort()` 之后必须紧跟 `return`。** 这是 Gin 中间件写作的铁律。
|
||||
|
||||
## 关联笔记
|
||||
|
||||
- [[GIN/3-middleware]] — 中间件完整机制，包含 Abort 的思考题
|
||||
- [[GIN/4-context-lifecycle]] — Context 的深拷贝原理
|
||||
Reference in New Issue
Block a user