大家好，我是码农先森。
回想起以前用模版渲染数据的岁月，那时都没有 API 接口开发的概念。PHP 服务端和前端 HTML、CSS、JS 代码混合式开发，也不分前端、后端程序员，大家都是全干工程师。随着前后端分离、移动端开发的兴起，用后端渲染数据的开发方式效率低下，已经不能满足业务对需求快速上线的要求了。于是为了前后端的高效协同开发引入了 API 接口，只要在开发需求之前约定好数据传参，之后便可以开始启动自己的开发任务且互不干涉，最后再进行统一的接口联调。
根据熵增原则，如果任何事情不加以规则来限制，则都会朝着泛滥的方式发展。同样 API 接口开发也会出现这样的情况，由于每个人的开发习惯不同，导致 API 接口的开发格式五花八门，联调过程困难重重。无规矩不成方圆，因此为了规范 API 接口开发的形式，同时也结合我平时的项目开发经验。总结了一些 API 接口开发的实践经验，希望对大家能有所帮助。
话不多说，开整！
这次主要的实践内容是 API 接口签名设计，以下是一些关键的步骤：
- 给前端分配一个 AppKey，这个 AppKey 需要带在 HTTP Header 头中进行传输。
- 在前端的传参中需要额外增加 时间戳 timestamp、随机字符串 nonce 参数。
- 将前端的所有参数排序后拼接成一个字符串，再使用 MD5 加密函数生成 sign 签名字符串。
- 服务端接收到参数后，先验证 AppKey 是否一致。
- 再验证前端所传的时间戳参数是否还在有效期。
- 之后在服务端使用同样的加密算法生成 sign 签名串，再与前端的 sign 签名串比对。
- 最后判断前端所传的随机字符串是否已被使用，一次请求有效。
接下来开始在 ThinkPHP 和 Gin 框架中进行实现，文中只展示了核心的代码，完整代码的获取方式放在了文章末尾。
我们先熟悉一下项目结构核心的目录，有助于理解文中的内容。一个正常的请求首先要经过路由 route 再到中间件 middleware 最后到控制器 controller，API 接口的签名验证是在中间件 middleware 中实现，作为一个中间层在整个请求链路中起着承上启下的重要作用。
[manongsen@root php_to_go]$ tree -L 2 . ├── go_sign │ ├── app │ │ ├── controller │ │ │ └── user.go │ │ ├── middleware │ │ │ └── api_sign.go │ │ ├── config.go │ │ └── route.go │ ├── go.mod │ ├── go.sum │ └── main.go └── php_sign │ ├── app │ │ ├── controller │ │ │ └── User.php │ │ ├── middleware │ │ │ └── ApiSign.php │ │ └── middleware.php │ ├── composer.json │ ├── composer.lock │ ├── config │ ├── route │ │ └── app.php │ ├── think │ ├── vendor │ └── .env ThinkPHP
使用 composer 创建基于 ThinkPHP 框架的 php_sign 项目。
[manongsen@root ~]$ pwd /home/manongsen/workspace/php_to_go/php_sign [manongsen@root php_sign]$ composer create-project topthink/think php_sign 随机字符串需要用到 Redis 进行存储，所以这里需要安装 Redis 扩展包，便于操作 Redis。
[manongsen@root php_sign]$ composer require predis/predis 在项目 php_sign 下创建 ApiSign 中间件。
[manongsen@root php_sign]$ php think make:middleware ApiSign Middleware:appmiddlewareApiSign created successfully. 在项目 php_sign 下复制一个 env 配置文件，并且定义好 AppKey。
[manongsen@root php_sign]$ cp .example.env .env API 接口签名的验证是放在框架的中间件中进行实现的，其中时间戳的有效时间设置的是 2 秒，有些朋友会有疑惑为什么是 2 秒？3 秒、5 秒不行吗？这里的有效时间是基于网络通信的延时考虑的，根据普遍情况延时大概是 2 秒。如果你的服务延时比较长，也可以设置长一些，并没有一个定量的值，话说到这里也提醒一下如果你的接口延时超过 2 秒，大概率需要优化一下代码了。此外，还有一个随机字符串参数，这个参数的目的是为了防止接口被重放，如果做过爬虫的朋友可能对这个会深有感触，这也是防范爬虫的一种手段。
<?php declare (strict_types = 1); namespace appmiddleware; use thinkfacadeEnv; use thinkfacadeCache; class ApiSign { /** * 处理请求 * * @param thinkRequest $request * @param Closure $next * @return Response */ public function handle($request, Closure $next) { /*********************** 验证AppKey参数 ******************/ $headers = $request->header(); if (!isset($headers["app-key"])) { return json(["code" => 400, "msg" => "秘钥参数缺失"]); } $reqAppKey = $headers["app-key"]; $vfyAppKey = Env::get("APP_KEY"); if ($reqAppKey != $vfyAppKey) { return json(["code" => 400, "msg" => "签名秘钥无效"]); } /*********************** 验证时间戳参数 *******************/ $params = $request->param(); if (!isset($params["timestamp"])) { return json(["code" => 400, "msg" => "时间参数缺失"]); } $timestamp = $params["timestamp"]; $nowTime = time(); if (($nowTime-$timestamp) > 2) { return json(["code" => 400, "msg" => "时间参数过期"]); } /*********************** 验证签名串参数 *******************/ if (!isset($params["sign"])) { return json(["code" => 400, "msg" => "签名参数缺失"]); } $reqSign = $params["sign"]; unset($params["sign"]); // 将参数进行排序 ksort($params); $paramStr = http_build_query($params); // md5 加密处理 $vfySign = md5($paramStr . "&app_key={$vfyAppKey}"); // 比较签名参数 if ($reqSign != $vfySign) { return json(["code" => 400, "msg" => "签名验证失败"]); } /*********************** 验证随机串参数 *******************/ if (!isset($params["nonce_str"])) { return json(["code" => 400, "msg" => "随机串参数缺失"]); } $nonceStr = $params["nonce_str"]; // 判断 nonce_str 随机字符串是否被使用 $redis = Cache::store('redis')->handler(); $flag = $redis->exists($nonceStr); if ($flag) { return json(["code" => 400, "msg" => "随机串参数无效"]); } // 存储 nonce_str 随机字符串 $redis->set($nonceStr, $timestamp, 2); return $next($request); } } 启动 php_sign 服务。
[manongsen@root php_sign]$ php think run ThinkPHP Development server is started On <http://0.0.0.0:8000/> You can exit with `CTRL-C` Document root is: /home/manongsen/workspace/php_to_go/php_sign/public [Wed Jul 3 22:02:16 2024] PHP 8.3.4 Development Server (http://0.0.0.0:8000) started 使用 Postman 工具进行测试验证，通过构造正确的参数，便可以成功的返回数据。
Gin
通过 go mod 初始化 go_sign 项目。
[manongsen@root ~]$ pwd /home/manongsen/workspace/php_to_go/go_sign [manongsen@root go_sign]$ go mod init go_sign 安装 Gin 框架库，这里与 ThinkPHP 不一样的是 Gin 框架是以第三库的形式在 gin_sign 项目中进行引用的。
[manongsen@root go_sign]$ go get github.com/gin-gonic/gin 安装 Redis 操作库，与在 ThinkPHP 框架中一样也要使用到 Redis。
[manongsen@root go_sign]$ go get github.com/go-redis/redis 这是在 Gin 框架中利用中间件来进行 API 接口签名验证，从代码量上来看就比 PHP 要多了。其中还需要自行合并 GET 和 POST 参数，方便在中间件中统一进行签名处理。对参数的拼接也没有类似 http_build_query 的方法，总体上来说在 Go 中进行签名验证需要繁琐不少。
package middleware import ( "bytes" "crypto/md5" "encoding/json" "fmt" "go_sign/app" "io/ioutil" "net/http" "sort" "strconv" "strings" "time" "github.com/gin-gonic/gin" ) func ApiSign() gin.HandlerFunc { return func(c *gin.Context) { /*************************** 验证AppKey参数 **************************/ reqAppKey := c.Request.Header.Get("app-key") if len(reqAppKey) == 0 { c.JSON(http.StatusOK, gin.H{"code": 400, "msg": "秘钥参数缺失"}) c.Abort() return } vfyAppKey := app.APP_KEY if reqAppKey != vfyAppKey { c.JSON(http.StatusOK, gin.H{"code": 400, "msg": "秘钥参数无效"}) c.Abort() return } // 获取请求参数 params := mergeParams(c) /*************************** 验证时间戳参数 **************************/ if _, ok := params["timestamp"]; !ok { c.JSON(http.StatusOK, gin.H{"code": 400, "msg": "时间参数无效"}) c.Abort() return } timestampStr := fmt.Sprintf("%v", params["timestamp"]) timestampInt, err := strconv.ParseInt(timestampStr, 0, 64) if err != nil { c.JSON(http.StatusOK, gin.H{"code": 400, "msg": "时间参数无效"}) c.Abort() return } nowTime := time.Now().Unix() if nowTime-timestampInt > 2 { c.JSON(http.StatusOK, gin.H{"code": 400, "msg": "时间参数过期"}) c.Abort() return } /*************************** 验证签名串参数 **************************/ if _, ok := params["sign"]; !ok { c.JSON(http.StatusOK, gin.H{"code": 400, "msg": "签名参数无效"}) c.Abort() return } reqSign := fmt.Sprintf("%v", params["sign"]) // 针对 dataMap 进行排序 dataMap := params keys := make([]string, len(dataMap)) i := 0 for k := range dataMap { keys[i] = k i++ } sort.Strings(keys) var buf bytes.Buffer for _, k := range keys { if k != "sign" && !strings.HasPrefix(k, "reserved") { buf.WriteString(k) buf.WriteString("=") buf.WriteString(fmt.Sprintf("%v", dataMap[k])) buf.WriteString("&") } } bufStr := buf.String() dataStr := bufStr + "app_key=" + app.APP_KEY // 进行 md5 加密处理 data := []byte(dataStr) has := md5.Sum(data) vfySign := fmt.Sprintf("%x", has) // 将[]byte转成16进制 if reqSign != vfySign { c.JSON(http.StatusOK, gin.H{"code": 400, "msg": "签名验证失败"}) c.Abort() return } /*************************** 验证随机串参数 **************************/ if _, ok := params["nonce_str"]; !ok { c.JSON(http.StatusOK, gin.H{"code": 400, "msg": "随机串参数缺失"}) c.Abort() return } nonceStr := fmt.Sprintf("%v", params["nonce_str"]) // 判断是否存在 nonce_str 随机字符串 flag, _ := app.RedisConn.Exists(nonceStr).Result() if flag > 0 { c.JSON(http.StatusOK, gin.H{"code": 400, "msg": "随机串参数无效"}) c.Abort() return } // 存储nonce_str随机字符串 app.RedisConn.Set(nonceStr, timestampInt, time.Second*2).Result() c.Next() } } // 将 GET 和 POST 的参数合并到同一 Map func mergeParams(c *gin.Context) map[string]interface{} { var ( dataMap = make(map[string]interface{}) queryMap = make(map[string]interface{}) postMap = make(map[string]interface{}) ) contentType := c.ContentType() for k := range c.Request.URL.Query() { queryMap[k] = c.Query(k) } if contentType == "application/json" { if c.Request != nil && c.Request.Body != nil { bodyBytes, _ := ioutil.ReadAll(c.Request.Body) if len(bodyBytes) > 0 { if err := json.NewDecoder(bytes.NewBuffer(bodyBytes)).Decode(&postMap); err != nil { return nil } c.Request.Body = ioutil.NopCloser(bytes.NewBuffer(bodyBytes)) } } } else if contentType == "multipart/form-data" { for k, v := range c.Request.PostForm { if len(v) > 1 { postMap[k] = v } else if len(v) == 1 { postMap[k] = v[0] } } } else { for k, v := range c.Request.PostForm { if len(v) > 1 { postMap[k] = v } else if len(v) == 1 { postMap[k] = v[0] } } } // 优先级：以post优先级最高，会覆盖get参数 for k, v := range queryMap { dataMap[k] = v } for k, v := range postMap { dataMap[k] = v } return dataMap } 启动 gin_sin 服务。
[manongsen@root go_sign]$ go run main.go [GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached. [GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production. - using env: export GIN_MODE=release - using code: gin.SetMode(gin.ReleaseMode) [GIN-debug] GET /user/info --> go_sign/app/controller.UserInfo (4 handlers) [GIN-debug] [WARNING] You trusted all proxies, this is NOT safe. We recommend you to set a value. Please check https://pkg.go.dev/github.com/gin-gonic/gin#readme-don-t-trust-all-proxies for details. [GIN-debug] Listening and serving HTTP on :8001 同样也使用 Postman 工具进行测试验证，通过构造正确的参数，便可以成功的返回数据。
结语
数据安全一直是个热门的话题，API 接口在数据的传输上扮演着至关重要的角色。为了 API 接口的安全性、健壮性，完整性，往往需要将网络上的数据进行签名加密传输。同时为了防止 API 接口被重放爬虫伪造等类似恶意攻击的手段，还要在接口设计时增加有效时间、随机字符串、签名串等参数，来保障数据的安全性。这一次的 API 接口签名设计实践，大家也可以手动尝试实验一下，希望对大家的日常工作能有所帮助。最后感兴趣的朋友可以在微信公众号内回复「4867」获取完整的实践代码。
欢迎关注、分享、点赞、收藏、在看，我是微信公众号「码农先森」作者。
![洛谷 P11345 [KTSC 2023 R2] 基地简化 题解](http://www.itfaba.com/wp-content/themes/kemi/timthumb.php?src=http://www.itfaba.com/wp-content/themes/kemi/img/random/2.jpg&w=218&h=124&zc=1)
