PHP转Go系列 | ThinkPHP与Gin框架之API接口签名设计实践

来源：cnblogs　　作者：Yxh_blogs　　时间：2024/7/8 9:54:23　　对本文有异议

大家好，我是码农先森。

回想起以前用模版渲染数据的岁月，那时都没有 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:app\middleware\ApiSign 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 app\middleware;
use think\facade\Env;
use think\facade\Cache;
class ApiSign
{
    /**
     * 处理请求
     *
     * @param \think\Request $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」获取完整的实践代码。