我所理解的接口設計

前言

本身作接口開發的時間也算不短了(三年)，想寫這篇文章其實差很少已經有一年多的時間了。我將從下面的方向來對我所理解的接口設計作個總結：

接口參數定義 -> 接口版本化的問題 -> 接口的安全性 -> 接口的代碼設計 -> 接口的可讀性 -> 接口文檔 -> 我遇到的坑

接口參數定義

接口設計中往能夠抽象出一些新的公共參數，從事了近三年的接口開發工做中，我目前能想到了一些較爲常見的公共接口參數以下：

公共參數	含意	定義該參數的意義
timestamp	毫秒級時間戳	1.客戶端的請求時間標示 2.後端能夠作請求過時驗證 3.該參數參與簽名算法增長簽名的惟一性
app_key	簽名公鑰	簽名算法的公鑰，後端經過公鑰能夠獲得對應的私鑰
sign	接口簽名	經過請求的參數和定義好的簽名算法生成接口簽名，做用防止中間人篡改請求參數
did	設備ID	設備的惟一標示，生成規則例如android的mac地址的md5和ios曾今udid(目前沒法獲取)的md5, 1:數據收集 2.便於問題追蹤 3.消息推送標示

接口版本化的問題

接口設計中有個算是歷史上的難題 -> 接口版本化。曾經也去調研了不少關於接口版本化的資料和設計，最後我獲得的結論大體以下：

• 接口的版本區分爲
  • 大版本
    • 原則：大版本的數量最多控制到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 ... 
    }
}

// 等等...

// 前置中間件類
class FrontMiddleware {
    public function run() {
        // 初始化一個：必傳參數校驗的check
        $checkParams   =  new ParamsCheck();
        // 初始化一個：簽名check
        $checkSign     =  new SignCheck();
        // 初始化一個：頻率check
        $checkFrequent =  new FrequentCheck();
        // 等等...

        // 構成對象鏈
        $checkParams->setNext($checkSign)
                    ->setNext($checkFrequent)
                    ...
        // 啓動
        $checkParams->start();
    }
}
複製代碼

接口的可讀性

關於可讀性的不得不提到的就是RESTFUL，這裏我就不討論RESTFUL，你們能夠自行補充相關知識。關於接口設計可讀性的個人一些思考：

• url
  • 非RESTFUL: 資源／資源／操做(動詞)， 例如 content/article/get -> 獲取內容資源下的一篇文章資源
  • RESTFUL: 資源／資源／資源， 例如 get content/article/1 -> 獲取內容資源下文章ID爲1的文章資源
• method
  • 非RESTFUL: get便於查nginx日誌，上傳資源post, 沒啥硬性要求
  • RESTFUL: 符合RESTFUL的思想
• request params: 我的更青睞於下劃線命名，適當的單詞縮寫
• response params: 響應的code要符合http status
  • 200 -> 正常
  • 400 -> 缺乏公共必傳參數或者業務必傳參數
  • 401 -> 接口校驗失敗 例如簽名
  • 403 -> 沒有該接口的訪問權限
  • 499 -> 上游服務響應時間超過接口設置的超時時間
  • 500 -> 代碼錯誤
  • 501 -> 不支持的接口method
  • 502 -> 上游服務返回的數據格式不正確
  • 503 -> 上游服務超時
  • 504 -> 上游服務不可用

// 響應的格式
{
    "code": 200,
    "msg": "ok",
    "data": {

    }
}
複製代碼

接口文檔

好的接口文檔就是生產力， swagger + api blueprint 自行google吧😄

我遇到的坑

這裏遇到的一個比較大的坑就是http協議歷史遺留的bug：

不區分url裏的空格 和加號➕

帶來的問題就是urldecode會把參數裏的+號轉爲空格，因此這種場景的就得使用rawurldecode防止+轉成空格。好比作接口的參數校驗的時候～