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 设计成把同一资源设置为固定值。连续发送两次后,可以直接观察两种方法的状态效果。

go
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"])
}

为复现上述请求序列,在源码目录执行:

bash
go run main.go

预期输出:

text
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 语义、又能安全处理重试与故障的接口。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

理解方法、状态码与幂等语义

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通