我所理解的接口设计

前言

自己做接口开发的时间也算不短了(三年)，想写这篇文章其实差不多已经有一年多的时间了。我将从下面的方向来对我所理解的接口设计做个总结：

接口参数定义 -> 接口版本化的问题 -> 接口的安全性 -> 接口的代码设计 -> 接口的可读性 -> 接口文档 -> 我遇到的坑

接口参数定义

接口设计中往可以抽象出一些新的公共参数，从事了近三年的接口开发工作中，我目前能想到了一些较为常见的公共接口参数如下：

接口版本化的问题

接口设计中有个算是历史上的难题 -> 接口版本化。曾经也去调研了很多关于接口版本化的资料和设计，最后我得到的结论大致如下：

接口的版本区分为：

大版本

原则：大版本的数量最多控制到5个以内(我个人跟倾向于3个)，超过版本限制的版本提示升级到新版本

方案：

• uri携带版本号，例如：v1/user/get

• 请求参数，例如：user/get?v=1.0

小版本

原则：自己把控吧😄

方案：

• uri携带版本号，例如：v1/user/get_01

• 请求参数，小数点右边就是小版本，例如：user/get?v=1.1

接口的安全性

接口的设计肯定绕不开安全这两个字，为了达到尽可能的安全，我们需要 尽可能的增加被攻击的难度 ，以下是我了解和使用到的一些常见的手段去增加接口的安全性(https这里就不讨论了)：

过期验证／签名验证／重放攻击／限流／转义

伪代码如下：

// 过期验证
if (microtime(true)*1000 - $_REQUEST['timestamp'] > 5000) {
    throw new \Exception(401, 'Expired request');
}

// 签名验证(公钥校验省略)
$params = ksort($_REQUEST);
unset($params['sign']);
$sign = md5(sha1(implode('-', $params) . $_REQUEST['app_key']));
if ($sign !== $_REQUEST['sign']) {




    
    throw new \Exception(401, 'Invalid sign');
}

/**
 * 重放攻击
 * @params noise string 随机字符串或随机正整数，与 Timestamp 联合起来, 用于防止重放攻击 例如腾讯云是6位随机正整数
 */
$key = md5("{$_REQUEST['REQUEST_URI']}-{$_REQUEST['timestamp']}-{$_REQUEST['noise']}-{$_REQUEST['did']}");
if ($redisInstance->exists($key)) {
    throw new \Exception(401, 'Repeated request');
}

// 限流
$key = md5("{$_REQUEST['REQUEST_URI']}-{$_REQUEST['REMOTE_ADDR']}-{$_REQUEST['did']}");
if ($redisInstance->get($key) > 60) {
    throw new \Exception(401, 'Request limit');
}
$redisInstance->incre($key);

// 转义
$username = htmlspecialchars($_REQUEST['username']);

接口的代码设计 -> 解耦业务 即插即用

这个过程的关键字：抽象成类 前置中间件 注入

接着就是我们代码设计的层面了，如何抽象公共的部分与业务代码解耦。

一般写法, 定义个全局函数，然后每个接口开始时调用该函数：

// 全局定义一个函数
function check () {
    // 校验公共参数
    # code ...
    // 校验签名
    # code ...
    // 校验频率
    # code ...
    // 等等...
}

二般写法, 定义个父类方法，然后每个接口类继承该接口，构造函数调用改方法，其实和上面的换汤不换药：

// 父类方法
class father
{
    public function __construct()
    {
        $this->check();
    }
    public function check () {
        // 校验公共参数
        # code ...
        // 校验签名
        




    
# code ...
        // 校验频率
        # code ...
        // 等等...
    }
}

重点来了，我提倡的第三般写法，对象链和前置中间件：

/**
 * 检验抽象类
 */
abstract class Check
{
    /**
     * 下一个check实体
     *
     * @var object
     */
    private $nextCheckInstance;
    /**
     * 校验方法
     *
     * @param Request $request 请求对象
     */
    abstract public function operate(Request $request);
    




    
/**
     * 设置责任链上的下一个对象
     *
     * @param Check $check
     */
    public function setNext(Check $check)
    {
        $this->nextCheckInstance = $check;
        return $check;
    }
    /**
     * 启动
     *
     * @param Request $request 请求对象
     */
    public function start(Request $request)
    {
        $this->doCheck($request);
        // 调用下一个对象
        if (! empty($this->nextCheckInstance)) {
            $this->nextCheckInstance->start($request);
        }
    }
}
// 校验公共参数类
class ParamsCheck extends Check
{
    public function operate()
    {
       // 校验公共参数
        # code ... 
    }
}
// 校验签名类
class SignCheck extends Check
{
    public function operate()
    {
       // 校验签名
        # code ... 
    }
}