README

该包是为了方便处理API请求而设计的。目前，该模块仅提供了一个控制器，包含一系列方法，帮助组织AJAX请求的处理。

安装

composer require kodicms/laravel-api

添加外观到别名

'RouteAPI' => KodiCMS\API\RouteApiFacade::class,

修改文件 app\Exceptions\Handler.php

	...

	use KodiCMS\API\Http\Response as APIResponse;
	use KodiCMS\API\Exceptions\Exception as APIException;

	...

	/**
	 * Render an exception into an HTTP response.
	 *
	 * @param  \Illuminate\Http\Request $request
	 * @param  \Exception               $e
	 *
	 * @return \Illuminate\Http\Response
	 */
	public function render($request, \Exception $e)
	{
		if ($request->ajax() OR ($e instanceof APIException)) {
			return (new APIResponse(config('app.debug')))
				->createExceptionResponse($e);
		}

		...
	}

描述

控制器

控制器需要继承自 KodiCMS\API\Http\Controllers\Controller，之后它将开始以特定格式返回所有响应（错误等），并可以选择响应类型（json，xml，yaml）

响应示例

{
	code: 200,
	content: '....',
	type: 'content',
	method: '...'
}

响应代码

• 200 - 正常
• 110 - 请求中未传递必需的参数
• 120 - 验证错误
• 130 - 未知错误
• 140 - 令牌错误
• 150 - 尝试在模型中设置受保护的字段值
• 220 - 权限错误
• 403 - 未授权
• 404 - 页面未找到

响应类型

• error - 错误
• content - 响应
• redirect - 重定向

不同代码的响应示例（JSON格式）

// 200
{
	code: 200,
	content: '....',
	type: 'content',
	method: '...'
}

// 200/Redirect
{
	code: 200,
	targetUrl: '....',
	content: '....',
	type: 'redirect',
	method: '...'
}

// 110
{
	code: 110,
	type: 'error',
	failed_rules: {...}, // поля, которые не прошли валидацию с текстом ошибки
	message: ... // текст ошибки
	...
}

// 120
{
	code: 120,
	type: 'error',
	errors: {...}, // текст ошибок
	failed_rules: {...} поля, которые не прошли валидацию с текстом ошибки
	...
}

// Другие ошибки
{
	type: 'error',
	message: ... // текст ошибки
	...
}

实用方法

• getParameter($key, $default = NULL, $isRequired = false) - 获取请求中传递的参数
• getRequiredParameter($key, $rules = true) - 获取必需的参数，第二个参数可以指定验证规则（true == 'required'），抛出错误110
• setMessage($message) - 将消息传递到响应
• setErrors(array $errors) - 将错误传递到响应
• setContent($data) - 将数据传递到响应。如果传递的是 view，则将其转换为HTML

实用参数

• jsonResponse - 将要传递到响应并转换为JSON的数据
• requiredFields - 期望的字段，形式为 ['action' => ['param1', 'param2']]

路由器

为API模块创建了一个外观 RouteAPI，用于添加API路由，它将自动为新路由添加响应类型选择（json，xml，yaml）的能力。

API请求可以按以下方式执行

• site.com/api.refresh.key => json,
• site.com/api.refresh.key.json => json,
• site.com/api.refresh.key.xml => xml,
• site.com/api.refresh.key.yaml => yaml

示例

RouteAPI::post('refresh.key', ['as' => 'api.refresh.key', 'uses' => 'API\KeysController@postRefresh']);

// Что равнозначно
Route::post('api.refresh.key{type?}', ['as' => 'api.refresh.key', 'uses' => 'API\KeysController@postRefresh'])->where('type', '\.[a-z]');

返回数据的控制器示例

use KodiCMS\API\Http\Controllers\Controller;
class PageController extends Controller
{
	public function getSearch()
	{
		$query = $this->getRequiredParameter('search');

		...

		$this->setContent(view('pages.children'));
	}
}

// return JsonResponse

{
	code: 200,
	content: 'html data',
	method: 'get',
	type: 'content'
}

以任意形式返回数据的控制器示例

use KodiCMS\API\Http\Controllers\Controller;

class MessageController extends Controller
{
	public function sendMessage()
	{
		$message = $this->getRequiredParameter('message');

		...

		$this->testParam = '...';
		// или
		$this->jsonResponse['testParam'] = '...';

		$this->setMessage($message);
	}
}


// return JsonResponse

{
	code: 200,
	content: null,
	testParam: '...'
	type: 'content',
	method: 'post',
	message: 'message text'
}

带有重定向的控制器示例

use KodiCMS\API\Http\Controllers\Controller;
class MessageController extends Controller
{
	public function sendMessage()
	{
		$message = $this->getRequiredParameter('message');

		...

		return redirect('...');
	}
}

// return JsonResponse

{
	code: 200,
	targetUrl: '....',
	content: '....',
	method: 'post',
	type: 'redirect'
}

输出HTML的控制器示例

use KodiCMS\API\Http\Controllers\Controller;
class MessageController extends Controller
{
	public function sendMessage()
	{
		$message = $this->getRequiredParameter('message');

		...

		return view('.....');
	}
}

// return JsonResponse

'html content'

异常

API模块有自己的异常类 KodiCMS\API\Exceptions\Exception，最好从该类继承API控制器使用的异常。该类包含一个 responseArray 方法，其中包含将传递到 Response 的参数列表

/**
 * @var int
 */
protected $code = Response::ERROR_UNKNOWN;

public function responseArray()
{
	return [
		'code' => $this->getCode(),
		'type' => Response::TYPE_ERROR,
		'message' => $this->getMessage(),
	];
}

自定义异常类示例

use KodiCMS\API\Exceptions\Exception;
use KodiCMS\API\Http\Response;

class ValidationException extends Exception
{
	/**
	 * @var int
	 */
	protected $code = Response::ERROR_VALIDATION;

	public function getFailedRules()
	{
		...
	}

	public function getErrorMessages()
	{
		...
	}

	/**
	 * @return array
	 */
	public function responseArray()
	{
		$data = parent::responseArray();
		$data['failed_rules'] = $this->getFailedRules();
		$data['errors'] = $this->getErrorMessages();

		return $data;
	}
}