基于Hmac-SHA256实现API请求签名验证，客户端按参数名排序拼接待签名字符串，结合http方法、路径、时间戳、nonce等生成签名；服务端通过中间件校验accessKey、时间窗口、nonce唯一性，并重新计算签名比对，确保请求合法性与防重放攻击。
在使用 golang 开发 API 接口时，为了保证请求的合法性和安全性，通常会引入请求签名验证机制。这种机制可以防止请求被篡改或重放攻击。下面介绍一种常见的实现方式：基于 HMAC-SHA256 算法的签名验证流程。
1. 签名的基本原理
客户端和服务器共享一个密钥（secretKey），每次请求时，客户端根据请求参数和时间戳生成签名，并将签名随请求发送。服务端收到请求后，使用相同的算法和密钥重新计算签名，并与客户端传来的签名比对。
核心要素包括：
- 请求参数：所有参与签名的参数需按规则排序
- 时间戳（timestamp）：防止重放攻击
- 随机字符串（nonce）：增加唯一性
- API密钥（accessKey 和 secretKey）：用于身份识别和签名计算
- HTTP方法、路径、Body（如需要）：确保请求完整性
2. 客户端生成签名
假设客户端要发送一个 POST 请求到 /api/v1/order，携带参数：
立即学习“go语言免费学习笔记（深入）”；
accessKey=abc123×tamp=1712345678&nonce=randomxyz&amount=100&product=phone步骤如下：
- 将所有参数按字段名字母升序排序
- 拼接成 query String 格式（不编码 key 和 value，或统一 URL 编码）
- 构造待签名字符串，例如：
POST&/api/v1/order&accessKey=abc123&amount=100&nonce=randomxyz&product=phone×tamp=1712345678 - 使用 secretKey 对该字符串进行 HMAC-SHA256 计算，并转为十六进制小写字符串
- 将生成的 signature 添加到请求头或参数中发送
示例代码（客户端）：
package main import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "fmt" "sort" "strings" ) func generateSignature(httpMethod, uri, secretKey string, params map[string]string) string { var keys []string for k := range params { keys = append(keys, k) } sort.Strings(keys) var pairs []string for _, k := range keys { pairs = append(pairs, fmt.Sprintf("%s=%s", k, params[k])) } queryString := strings.Join(pairs, "&") signStr := fmt.Sprintf("%s&%s&%s", httpMethod, uri, queryString) h := hmac.New(sha256.New, []byte(secretKey)) h.Write([]byte(signStr)) return hex.EncodeToString(h.Sum(nil)) } func main() { params := map[string]string{ "accessKey": "abc123", "timestamp": "1712345678", "nonce": "randomxyz", "amount": "100", "product": "phone", } sig := generateSignature("POST", "/api/v1/order", "my_secret_key_123", params) fmt.Println("Signature:", sig) }3. 服务端验证签名
服务端接收到请求后，执行类似步骤：
- 从请求中提取 accessKey，查询对应 secretKey
- 校验 timestamp 是否在允许的时间窗口内（如 ±5 分钟）
- 检查 nonce 是否已使用过（可缓存一段时间，防重放）
- 用相同规则拼接参数并生成签名
- 使用 hmac.Equal 安全比较签名是否一致
gin 框架中的中间件示例：
package main import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "net/http" "sort" "strings" "time" "github.com/gin-gonic/gin" ) var secretKeyMap = map[string]string{ "abc123": "my_secret_key_123", } func SignVerifyMiddleware() gin.HandlerFunc { return func(c *gin.Context) { accessKey := c.PostForm("accessKey") timestampStr := c.PostForm("timestamp") nonce := c.PostForm("nonce") clientSig := c.GetHeader("X-Signature") if accessKey == "" || timestampStr == "" || nonce == "" || clientSig == "" { c.jsON(401, gin.H{"error": "missing required fields"}) c.Abort() return } secretKey, exists := secretKeyMap[accessKey] if !exists { c.json(401, gin.H{"error": "invalid accessKey"}) c.Abort() return } // 验证时间戳 timestamp, err := time.Parseunix(timestampStr, 10) if err != nil || time.Since(timestamp).Abs() > 5*time.Minute { c.JSON(401, gin.H{"error": "timestamp invalid"}) c.Abort() return } // TODO: 使用 redis 或内存缓存检查 nonce 是否重复 // 收集所有 form 参数（可根据实际需求扩展支持 query、JSON 等） params := make(map[string]string) c.Request.ParseForm() for k, v := range c.Request.PostForm { if len(v) > 0 { params[k] = v[0] } } delete(params, "") // 清理空key // 生成待签名字符串（同客户端） var keys []string for k := range params { keys = append(keys, k) } sort.Strings(keys) var pairs []string for _, k := range keys { pairs = append(pairs, fmt.Sprintf("%s=%s", k, params[k])) } queryString := strings.Join(pairs, "&") signStr := fmt.Sprintf("%s&%s&%s", c.Request.Method, c.Request.URL.Path, queryString) h := hmac.New(sha256.New, []byte(secretKey)) h.Write([]byte(signStr)) serverSig := hex.EncodeToString(h.Sum(nil)) // 安全比较 if !hmac.Equal([]byte(serverSig), []byte(clientSig)) { c.JSON(401, gin.H{"error": "signature mismatch"}) c.Abort() return } c.Next() } }4. 安全建议与注意事项
- 使用 https：防止密钥和签名在传输中泄露
- 限制 timestamp 有效期：通常设置为 ±5 分钟
- 使用唯一 nonce 并去重：可用 Redis 记录一段时间内的 nonce
- 敏感操作加动态 Token：如短信验证码、二次确认等
- 避免日志记录 secretKey 或完整签名字符串
- 参数编码一致性：客户端和服务端必须使用相同的编码规则
基本上就这些。通过上述方式，可以在 golang 项目中实现一套简单而有效的请求签名验证机制，提升接口安全性。