### 前言
官网地址：[SW-X框架-专注高性能便捷开发而生的PHP-SwooleX框架](https://www.sw-x.cn "SW-X框架-专注高性能便捷开发而生的PHP-SwooleX框架")

希望各大佬举起小手，给小弟一个star：[https://github.com/swoolex/swoolex](https://github.com/swoolex/swoolex "https://github.com/swoolex/swoolex")

### 1、什么是Restful组件
在SW-X中，Restful组件是对API返回值结构的封装支持。
`\x\Restful`类支持定义返回值的结构、Code->Msg关联、返回值强类型转换、抛出的数据类型转换、响应的请求头定义（跨域支持）。

### 2、Restful的设置
API返回值的使用，主要依赖`/restful/`目录中的`config.php`配置项目，初始化默认配置如下：
```php
<?php
return [
    // 返回值类型 支持 json|xml
    'type' => 'json',
    // 默认的返回值格式
    'default' => [
    	 'force'  => true, // 是否强制返回值 int|double|null类型转换
         'status' => 'code', // 状态码字段名
         'tips'   => 'msg',  // 描述字段名
         'result' => 'data', // 结果集字段名
         'set'    => [], // 默认结果集
         'headers' => [], // 响应头，可用于跨域设置（v2.5.23版本前支持）
    ],
]
```
其中`default`为默认的数据结构，当我们不使用`\x\Restful::make('新的下标')`指定新的返回值结构时，默认使用该结构，如果我们需要设置新的返回值结构，只需要复制`default`的数组结构，将下标改为新值即可。

同时，`/restful/`目录下还存在一个`default`目录，该目录是对应`default`默认的返回值结构，用于存放`code`状态码和`msg`状态说明。

如果设置了新的数据结构，则需要复制`default`目录，并重命名为对应的下标名。

下面我们来看下`default`目录下的两个文件：

Code状态码，`/restful/default/code.php`：
```php
<?php
// 状态码管理
return [
    'ERROR' => 0, // 默认失败状态码
    'SUCCESS' => 1, // 默认成功状态码
];
```
在实际应用时，我们只需要通过`\x\Restful::状态码键名()`的方式来读取对应的状态码值，例如使用`SUCCESS`的状态码就用`\x\Restful::SUCCESS()`。

Msg说明，`/restful/default/msg.php`：
```php
<?php
// 状态说明管理
return [
	// 默认错误状态码对应的tips
	'ERROR' => [
		'default' => '请求失败', // 默认值
	],
	// 默认成功状态码对应的tips
	'SUCCESS' => [
		'default' => '请求成功', // 默认值
		'test' => '测试msg',
	],
];
```
状态码说明是一个二维数组，一维下标需要对应状态码的下标，同时必须存在一个名为`default`的二维下标。

这样设计的初衷是由于，在实际应用中，同一个状态码可能存在多个不同的说明，这样就可以通过指定下标读取对应的说明，当不指定时，读取`default`下标。

例如：
```php
use x\Restful;

// 读取的就是SUCCESS['default']说明，默认使用default
Restful::code(Restful::SUCCESS())->callback();

// 指定msg下标，读取的就是SUCCESS['test']说明
Restful::code(Restful::SUCCESS())->msg('test')->callback();
```

### 3、Restful组件的更多示例
```php
use x\Restful;

// 自定义msg内容
return Restful::code(Restful::SUCCESS())->setMsg('把我抛出了，没用到msg.php里的配置')->callback();

// 自定义抛出类型
return Restful::type('xml')->code(Restful::SUCCESS())->callback();

// 设置抛出的数据集
return Restful::code(Restful::SUCCESS())->data([
	'user_id' => 1,
	'username' => 'SW-X',
])->callback();

// 设置跨域支持
return Restful::code(Restful::SUCCESS())->header([
	// 接口跨域设置
	'origin' => '*',
	// 接口数据请求类型
	'type' => '',
	// 接口跨域允许请求的类型
	'methods' => 'POST,GET,OPTIONS,DELETE',
	// 接口是否允许发送 cookies
	'credentials' => 'true',
	// 接口允许自定义请求头的字段
	'headers' => 'Content-Type,Content-Length,Accept-Encoding,X-Requested-with, Origin, api_key',
])->callback();
```

### 4、在控制器中使用Restful的简单示例
接回上一篇文章，我们修改`shop/select.php`路由对应的控制器代码：
```php
<?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组件抛出接口响应
		return Restful::code(Restful::SUCCESS())->data([
            'user_id' => '1',
            'username' => 'SW-X',
        ])->callback();
	}
}
```
输出结果：
```
{
  "code": 1,
  "msg": "请求成功",
  "data": {
    "user_id": 1,
    "username": "SW-X"
  }
}
```

### 5、枚举
如果你不习惯Restful组件风格管理API接口返回值的话，SW-X还支持Enum枚举定义的方式。

枚举类必须继承至`\design\Enum`基类，官方建议统一定义在`/box/enum/`目录下，但不强制要求。

下面我们就在该目录下，创建一个`ShopEnum`类，代码如下：
```
<?php
namespace box\enum;
// 必须继承枚举基类
use design\Enum;

class ShopEnum extends Enum {
    /*
     * 错误异常
    */
    const ERROR = 500;
    /**
     * 正常请求
    */
    const SUCCESS = 200;
}
```
注意上面的注释风格，其注释内容，就是状态码对应的MSG内容。

### 6、枚举类的使用示例
```php
use box\enum\ShopEnum;
// 获得对应的Msg内容
echo ShopEnum::get(ShopEnum::ERROR);

// 组装成code-msg-data的数组结构（该3个字段名都是系统固定的）
ShopEnum::get(ShopEnum::ERROR, [
    'data' => [
        'user_id' => 1
    ]
]);
结果集：
array(3) {
  ["code"]=>
  int(500)
  ["msg"]=>
  string(12) "错误异常"
  ["data"]=>
  array(1) {
    ["user_id"]=>
    int(1)
  }
}

// 自定义数据结构：
$ret = [
	'code' => ShopEnum::ERROR,
	'msg' => ShopEnum::get(ShopEnum::ERROR),
	'data => [],
];
```

### 7、在控制器中使用枚举的简单示例
接回上一篇文章，我们修改`shop/select.php`路由对应的控制器代码：
```php
<?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));
	}
}
```
输出结果：
```
array(3) {
  ["code"] => int(500)
  ["msg"] => string(12) "错误异常"
  ["data"] => array(1) {
    ["user_id"] => int(1)
  }
}
```

已有0条评论

添加新评论☺

如果认为本文对您有所帮助请赞助本站

支付宝扫一扫赞助

已有0条评论

添加新评论☺