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

大家好,我是码农先森。

回想起以前用模版渲染数据的岁月,那时都没有 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」获取完整的实践代码。


欢迎关注、分享、点赞、收藏、在看,我是微信公众号「码农先森」作者。

本作品采用《CC 协议》,转载必须注明作者和本文链接
《L02 从零构建论坛系统》
以构建论坛项目 LaraBBS 为线索,展开对 Laravel 框架的全面学习。应用程序架构思路贴近 Laravel 框架的设计哲学。
《L01 基础入门》
我们将带你从零开发一个项目并部署到线上,本课程教授 Web 开发中专业、实用的技能,如 Git 工作流、Laravel Mix 前端工作流等。
讨论数量: 5

普通接口用这个方式,与金钱相关的这样处理还不够吧

2周前 评论
IT学徒 (作者) 2周前
码农先森 (楼主) 2周前

还是php简单,内置函数多 直接用就行。go/gin好简陋的感觉

2周前 评论
IT学徒 2周前

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容,与人为善,比聪明更重要!