Go / 系统课时
理解方法、状态码与幂等语义
理解方法、状态码与幂等语义
HTTP 方法决定请求想做什么,状态码说明服务端如何处理,而幂等性决定同一请求重复执行时应如何看待副作用。本篇把三者放在同一条决策链上,重点解决工程中最常见的重试误区。
学习目标
- 区分常见 HTTP 方法的安全性与幂等性
- 按处理结果选择常见成功、客户端错误和服务端错误状态码
- 判断一次失败请求是否适合自动重试
方法先表达操作语义
“安全”表示客户端请求的语义是只读,不要求改变服务端状态;“幂等”表示对同一目标重复发送语义相同的请求,其预期服务端状态效果与发送一次相同。幂等并不要求每次响应状态码和响应体完全一致。
| 方法 | 安全 | 幂等 | 常见用途 |
|---|---|---|---|
GET |
是 | 是 | 读取资源 |
HEAD |
是 | 是 | 只读取响应元数据 |
POST |
否 | 默认否 | 创建子资源、触发处理 |
PUT |
否 | 是 | 用给定表示创建或整体替换目标资源 |
PATCH |
否 | 不保证 | 对资源做部分修改 |
DELETE |
否 | 是 | 删除目标资源 |
例如对同一 URI 连续发送两次 DELETE,第一次可能返回 204,第二次可能返回 404;两次响应不同,但目标资源最终都处于“不存在”状态,因此 DELETE 仍是幂等方法。
状态码要描述实际结果
状态码应让客户端仅凭协议层信息就能先判断处理类别,再决定是否解析业务数据。常见选择如下。
| 场景 | 常用状态码 | 含义 |
|---|---|---|
| 正常读取或更新 | 200 OK |
请求成功并返回内容 |
| 创建资源 | 201 Created |
新资源已经创建 |
| 异步受理 | 202 Accepted |
已接受,但处理尚未完成 |
| 成功且无正文 | 204 No Content |
请求成功,不返回内容 |
| 请求格式或参数错误 | 400 Bad Request |
客户端请求本身无效 |
| 缺少或无效认证 | 401 Unauthorized |
需要有效认证凭据 |
| 已认证但无权限 | 403 Forbidden |
服务端拒绝执行 |
| 资源不存在 | 404 Not Found |
找不到目标资源 |
| 当前状态冲突 | 409 Conflict |
请求与资源当前状态冲突 |
| 请求过多 | 429 Too Many Requests |
触发限流 |
| 未预期服务端故障 | 500 Internal Server Error |
服务端处理失败 |
| 临时不可用 | 503 Service Unavailable |
服务暂时无法处理 |
不要把所有失败都包装成 200 再靠响应体里的业务码区分,否则代理、监控、重试器和通用 HTTP 客户端都失去了协议层判断依据。
用程序观察重复请求
下面的完整程序故意把 POST /items 设计成每次创建一个新资源,而把 PUT /items/1 设计成把同一资源设置为固定值。连续发送两次后,可以直接观察两种方法的状态效果。
package main
import (
"fmt"
"io"
"net/http"
"net/http/httptest"
"strings"
)
func main() {
nextID := 1
items := map[string]string{}
mux := http.NewServeMux()
mux.HandleFunc("/items", func(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
w.Header().Set("Allow", http.MethodPost)
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
id := fmt.Sprintf("%d", nextID)
nextID++
items[id] = "created"
w.WriteHeader(http.StatusCreated)
_, _ = fmt.Fprintf(w, "id=%s", id)
})
mux.HandleFunc("/items/1", func(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPut {
w.Header().Set("Allow", http.MethodPut)
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
// 两次 PUT 都把资源 1 设置为同一个最终状态。
items["1"] = "blue"
_, _ = fmt.Fprint(w, "id=1 value=blue")
})
server := httptest.NewServer(mux)
defer server.Close()
call := func(method, path string) {
req, err := http.NewRequest(method, server.URL+path, strings.NewReader(""))
if err != nil {
panic(err)
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Printf("%s %s -> %d %s\n", method, path, resp.StatusCode, body)
}
call(http.MethodPost, "/items")
call(http.MethodPost, "/items")
call(http.MethodPut, "/items/1")
call(http.MethodPut, "/items/1")
fmt.Printf("final count=%d item1=%s\n", len(items), items["1"])
}为复现上述请求序列,在源码目录执行:
go run main.go预期输出:
POST /items -> 201 id=1
POST /items -> 201 id=2
PUT /items/1 -> 200 id=1 value=blue
PUT /items/1 -> 200 id=1 value=blue
final count=2 item1=blue重复 POST 创建了两个资源,所以它默认不是幂等操作;重复 PUT 仍把资源 1 保持为 blue,因此满足幂等语义。这里恰好两次 PUT 响应相同,但这不是幂等性的必要条件。
重试要同时看方法和失败类型
幂等方法更适合在连接中断、网关故障或临时不可用后自动重试,因为重复执行不应叠加目标状态效果。但这仍不等于“任何 5xx 都无限重试”:客户端应限制次数、设置退避,并结合超时预算。
429 和 503 如果带有 Retry-After,客户端可以优先遵循服务端建议。大多数确定性的 4xx 表示请求本身需要修改,立即原样重试通常没有意义。对于 POST 这类默认非幂等请求,网络超时尤其危险:服务端可能已经完成创建,只是响应在途中丢失。
需要可靠重试非幂等操作时,应把幂等能力设计进接口,例如客户端发送稳定的幂等键,服务端保存键与处理结果并对重复请求去重。这样重试安全性来自明确的应用协议,而不是仅凭“收到了 500”或“客户端超时”作猜测。
方法描述意图,状态码描述本次结果,幂等语义约束重复执行的状态效果。把这三层分开判断,才能设计出既符合 HTTP 语义、又能安全处理重试与故障的接口。