Gin - HTTP 方法

HTTP 请求方法

HTTP 定义了一组 请求方法（Request Methods），用于明确客户端希望服务器执行的动作是什么，以及请求成功后期望得到什么结果。每种方法都有自己的语义，但也存在一些跨方法共享的特性，例如：

• 安全（Safe）：调用不会修改服务器端状态，如 GET、HEAD。
• 幂等（Idempotent）：多次调用与一次调用的效果一致，如 PUT、DELETE。
• 可缓存（Cacheable）：响应可被缓存，如 GET、HEAD。

常用 HTTP 方法及语义

下面是最常用的 HTTP 方法，以及它们在实际 API 设计中的语义含义：

• GET
  用于获取指定资源的表示形式。应当是只读操作，不应携带请求体。
• HEAD
  与 GET 类似，但只返回响应头，不返回响应体，用于轻量级检查资源状态（如检测是否更新）。
• POST
  向服务器提交数据，通常用于创建资源、触发动作或提交表单。一般会修改服务器状态。
• PUT
  使用请求体的内容替换目标资源的完整表示，是一个典型的 幂等操作。
• DELETE
  删除指定资源，通常也是幂等的。
• CONNECT
  建立到目标资源的 TCP 隧道，常见于 HTTPS 代理。
• OPTIONS
  查询服务器对某个资源支持哪些方法，常用于跨域（CORS）的预检请求。
• TRACE
  回显服务器收到的请求，用于调试链路中的修改。出于安全原因一般禁用。
• PATCH
  对资源进行部分更新（局部修改），不同于 PUT 的整资源替换。

Gin 中的请求方法使用

Gin 框架对常用的 7 个 HTTP 方法提供了直接封装，让你可以用非常直观的方式声明路由。

下面的示例展示了如何统一使用一个 handler 方法，根据请求方法返回不同的提示。

package main

import (
	"fmt"

	"github.com/gin-gonic/gin"
)

func outputHandler(c *gin.Context) {
	method := c.Request.Method
	c.JSON(200, gin.H{
		"message": fmt.Sprintf(`You are requested by the %s method`, method),
	})
}

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

	r.GET("/someGet", outputHandler)
	r.POST("/somePost", outputHandler)
	r.PUT("/somePut", outputHandler)
	r.DELETE("/someDelete", outputHandler)
	r.PATCH("/somePatch", outputHandler)
	r.HEAD("/someHead", outputHandler)
	r.OPTIONS("/someOptions", outputHandler)

	r.Run(":8080")
}

我们通过将逻辑统一放在 outputHandler 中，避免重复编写类似的回调。

特殊方法：Handle 与 Any

除了常规的路由绑定方式外，Gin 还提供了两种更灵活的路由注册方式：Handle 与 Any。

Handle：可绑定任意 HTTP 方法

当你需要绑定一些不常见或框架默认未封装的 HTTP 方法（例如 CONNECT）时，可以使用 Handle：

package main

import (
	"fmt"

	"github.com/gin-gonic/gin"
)

func outputHandler(c *gin.Context) {
	method := c.Request.Method
	c.JSON(200, gin.H{
		"message": fmt.Sprintf(`You are requested by the %s method`, method),
	})
}

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

	r.Handle("GET", "/handle/someGet", outputHandler)
	r.Handle("POST", "/handle/somePost", outputHandler)
	r.Handle("PUT", "/handle/somePut", outputHandler)
	r.Handle("DELETE", "/handle/someDelete", outputHandler)
	r.Handle("PATCH", "/handle/somePatch", outputHandler)
	r.Handle("HEAD", "/handle/someHead", outputHandler)
	r.Handle("OPTIONS", "/handle/someOptions", outputHandler)
	r.Handle("CONNECT", "/handle/someConnect", outputHandler)

	r.Run(":8080")
}

效果截图：

Handle 适用于：

• 支持不常用的 HTTP 方法
• 在运行时动态注册方法字符串
• 对方法名进行封装或扩展

Any：一次性绑定所有常见方法

Any 会自动绑定当前 Gin 支持的全部 9 个方法（GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS、CONNECT、TRACE），让你用一个 handler 处理所有方法。

r.Any("/someAny", outputHandler)

启动后显示：

请求不同方法示例：

Any 常用于：

• 开发调试阶段快速测试 request method
• 代理/转发服务
• 某些统一入口网关场景

但在设计正式 API 上不推荐滥用，因为会削弱接口语义。