前言

官網(wǎng)地址：SW-X框架-專注高性能便捷開發(fā)而生的PHP-SwooleX框架

希望各大佬舉起小手，給小弟一個(gè)star：https://github.com/swoolex/swoolex

1、什么是Restful組件

在SW-X中，Restful組件是對(duì)API返回值結(jié)構(gòu)的封裝支持。
\x\Restful類支持定義返回值的結(jié)構(gòu)、Code->Msg關(guān)聯(lián)、返回值強(qiáng)類型轉(zhuǎn)換、拋出的數(shù)據(jù)類型轉(zhuǎn)換、響應(yīng)的請(qǐng)求頭定義（跨域支持）。

2、Restful的設(shè)置

API返回值的使用，主要依賴/restful/目錄中的config.php配置項(xiàng)目，初始化默認(rèn)配置如下：

<?php
return [
    // 返回值類型 支持 json|xml
    'type' => 'json',
    // 默認(rèn)的返回值格式
    'default' => [
         'force'  => true, // 是否強(qiáng)制返回值 int|double|null類型轉(zhuǎn)換
         'status' => 'code', // 狀態(tài)碼字段名
         'tips'   => 'msg',  // 描述字段名
         'result' => 'data', // 結(jié)果集字段名
         'set'    => [], // 默認(rèn)結(jié)果集
         'headers' => [], // 響應(yīng)頭，可用于跨域設(shè)置（v2.5.23版本前支持）
    ],
]

其中default為默認(rèn)的數(shù)據(jù)結(jié)構(gòu)，當(dāng)我們不使用\x\Restful::make('新的下標(biāo)')指定新的返回值結(jié)構(gòu)時(shí)，默認(rèn)使用該結(jié)構(gòu)，如果我們需要設(shè)置新的返回值結(jié)構(gòu)，只需要復(fù)制default的數(shù)組結(jié)構(gòu)，將下標(biāo)改為新值即可。

同時(shí)，/restful/目錄下還存在一個(gè)default目錄，該目錄是對(duì)應(yīng)default默認(rèn)的返回值結(jié)構(gòu)，用于存放code狀態(tài)碼和msg狀態(tài)說明。

如果設(shè)置了新的數(shù)據(jù)結(jié)構(gòu)，則需要復(fù)制default目錄，并重命名為對(duì)應(yīng)的下標(biāo)名。

下面我們來看下default目錄下的兩個(gè)文件：

Code狀態(tài)碼，/restful/default/code.php：

<?php
// 狀態(tài)碼管理
return [
    'ERROR' => 0, // 默認(rèn)失敗狀態(tài)碼
    'SUCCESS' => 1, // 默認(rèn)成功狀態(tài)碼
];

在實(shí)際應(yīng)用時(shí)，我們只需要通過\x\Restful::狀態(tài)碼鍵名()的方式來讀取對(duì)應(yīng)的狀態(tài)碼值，例如使用SUCCESS的狀態(tài)碼就用\x\Restful::SUCCESS()。

Msg說明，/restful/default/msg.php：

<?php
// 狀態(tài)說明管理
return [
    // 默認(rèn)錯(cuò)誤狀態(tài)碼對(duì)應(yīng)的tips
    'ERROR' => [
        'default' => '請(qǐng)求失敗', // 默認(rèn)值
    ],
    // 默認(rèn)成功狀態(tài)碼對(duì)應(yīng)的tips
    'SUCCESS' => [
        'default' => '請(qǐng)求成功', // 默認(rèn)值
        'test' => '測(cè)試msg',
    ],
];

狀態(tài)碼說明是一個(gè)二維數(shù)組，一維下標(biāo)需要對(duì)應(yīng)狀態(tài)碼的下標(biāo)，同時(shí)必須存在一個(gè)名為default的二維下標(biāo)。

這樣設(shè)計(jì)的初衷是由于，在實(shí)際應(yīng)用中，同一個(gè)狀態(tài)碼可能存在多個(gè)不同的說明，這樣就可以通過指定下標(biāo)讀取對(duì)應(yīng)的說明，當(dāng)不指定時(shí)，讀取default下標(biāo)。

例如：

use x\Restful;

// 讀取的就是SUCCESS['default']說明，默認(rèn)使用default
Restful::code(Restful::SUCCESS())->callback();

// 指定msg下標(biāo)，讀取的就是SUCCESS['test']說明
Restful::code(Restful::SUCCESS())->msg('test')->callback();

3、Restful組件的更多示例

use x\Restful;

// 自定義msg內(nèi)容
return Restful::code(Restful::SUCCESS())->setMsg('把我拋出了，沒用到msg.php里的配置')->callback();

// 自定義拋出類型
return Restful::type('xml')->code(Restful::SUCCESS())->callback();

// 設(shè)置拋出的數(shù)據(jù)集
return Restful::code(Restful::SUCCESS())->data([
    'user_id' => 1,
    'username' => 'SW-X',
])->callback();

// 設(shè)置跨域支持
return Restful::code(Restful::SUCCESS())->header([
    // 接口跨域設(shè)置
    'origin' => '*',
    // 接口數(shù)據(jù)請(qǐng)求類型
    'type' => '',
    // 接口跨域允許請(qǐng)求的類型
    'methods' => 'POST,GET,OPTIONS,DELETE',
    // 接口是否允許發(fā)送 cookies
    'credentials' => 'true',
    // 接口允許自定義請(qǐng)求頭的字段
    'headers' => 'Content-Type,Content-Length,Accept-Encoding,X-Requested-with, Origin, api_key',
])->callback();

4、在控制器中使用Restful的簡(jiǎn)單示例

接回上一篇文章，我們修改shop/select.php路由對(duì)應(yīng)的控制器代碼：

<?php
namespace app\http\v1_0_1\controller\shop;
use x\controller\Http;
// 引入Restful組件
use x\Restful;

class select extends Http
{
    public function index() {
        // Restful組件拋出接口響應(yīng)
        return Restful::code(Restful::SUCCESS())->data([
            'user_id' => '1',
            'username' => 'SW-X',
        ])->callback();
    }
}

輸出結(jié)果：

{
  "code": 1,
  "msg": "請(qǐng)求成功",
  "data": {
    "user_id": 1,
    "username": "SW-X"
  }
}

5、枚舉

如果你不習(xí)慣Restful組件風(fēng)格管理API接口返回值的話，SW-X還支持Enum枚舉定義的方式。

枚舉類必須繼承至\design\Enum基類，官方建議統(tǒng)一定義在/box/enum/目錄下，但不強(qiáng)制要求。

下面我們就在該目錄下，創(chuàng)建一個(gè)ShopEnum類，代碼如下：

<?php
namespace box\enum;
// 必須繼承枚舉基類
use design\Enum;

class ShopEnum extends Enum {
    /*
     * 錯(cuò)誤異常
    */
    const ERROR = 500;
    /**
     * 正常請(qǐng)求
    */
    const SUCCESS = 200;
}

注意上面的注釋風(fēng)格，其注釋內(nèi)容，就是狀態(tài)碼對(duì)應(yīng)的MSG內(nèi)容。

6、枚舉類的使用示例

use box\enum\ShopEnum;
// 獲得對(duì)應(yīng)的Msg內(nèi)容
echo ShopEnum::get(ShopEnum::ERROR);

// 組裝成code-msg-data的數(shù)組結(jié)構(gòu)（該3個(gè)字段名都是系統(tǒng)固定的）
ShopEnum::get(ShopEnum::ERROR, [
    'data' => [
        'user_id' => 1
    ]
]);
結(jié)果集：
array(3) {
  ["code"]=>
  int(500)
  ["msg"]=>
  string(12) "錯(cuò)誤異常"
  ["data"]=>
  array(1) {
    ["user_id"]=>
    int(1)
  }
}

// 自定義數(shù)據(jù)結(jié)構(gòu)：
$ret = [
    'code' => ShopEnum::ERROR,
    'msg' => ShopEnum::get(ShopEnum::ERROR),
    'data => [],
];

7、在控制器中使用枚舉的簡(jiǎn)單示例

接回上一篇文章，我們修改shop/select.php路由對(duì)應(yīng)的控制器代碼：

<?php
namespace app\http\v1_0_1\controller\shop;
use x\controller\Http;
// 引入自定義枚舉類
use box\enum\ShopEnum;

class select extends Http
{

    public function index() {
        $array = ShopEnum::get(ShopEnum::ERROR, [
                'data' => [
                'user_id' => 1
            ]
        ]);
        return $this->fetch(dd($array));
    }
}

輸出結(jié)果：

array(3) {
  ["code"] => int(500)
  ["msg"] => string(12) "錯(cuò)誤異常"
  ["data"] => array(1) {
    ["user_id"] => int(1)
  }
}