如何基于 Notadd 構建 API
Notadd 底層實現了 passport 機制,有統一的授權管理,主要支持兩種方式進行 API 授權,一個是 client,領一個是 passport,這個在其他文檔中有做詳細的說明。
這里主要說的是,如何基于 Notadd 進行 API 接口的開發。
業務邏輯
熟悉 Laravel 的同學都應該知道,Laravel 遵循這樣的業務邏輯實現:
路由(route) -> 控制器(controller) -> 業務邏輯(model) -> 數據輸出(view)
而 Notadd 的 API 業務邏輯實現同樣遵循類似的流程:
路由(route) -> 控制器(controller) -> API 處理器(handler) -> 模型(model) -> 數據輸出(json)
其中,主要的差異在于,API 處理器提供了對數據輸出格式的輸出,返回的數據格式統一為:
['code' => 200, // API 接口返回的狀態碼,默認為 200'data' => [], // API 接口返回的數據,主要為數組形式'message' => 'success!', // API 接口返回的提示信息,可以包含錯誤信息或成功信息
]
路由
Notadd 在實現 API 授權的時候,使用的是有 路由中間件(middleware) 的方式來實現的。
具體實現方式,是在路由的中間配置參數中添加 auth:api 。
例如,在實現 api/setting/all 和 api/setting/set 兩個 API 的時候,添加 auth:api 的中間件,代碼參考如下:
$this->router->group(['middleware' => ['auth:api', 'web'], 'prefix' => 'api/setting'], function () {$this->router->post('all', 'Notadd\Foundation\Setting\Controllers\SettingController@all');$this->router->post('set', 'Notadd\Foundation\Setting\Controllers\SettingController@set');
});
Notadd 針對需要跨域的 API 還提供了 cross 的路由中間件,以實現 API 跨域的功能。
例如,為前兩個 API 提供跨域的功能實現,代碼參考如下:
$this->router->group(['middleware' => ['auth:api', 'cross', 'web'], 'prefix' => 'api/setting'], function () {$this->router->post('all', 'Notadd\Foundation\Setting\Controllers\SettingController@all');$this->router->post('set', 'Notadd\Foundation\Setting\Controllers\SettingController@set');
});
控制器
由于有了獨立的 API處理器 ,控制器層可以制作簡單處理,僅需向控制器注入 handler,并由 handler 提供的輔助方法返回 API 數據給前臺,即可。
例如,在前面路由調用的 SettingController 中,僅需要注入 AllHandler ,使用方法 toResponse 和 generateHttpResponse 來返回結果給前臺,代碼參考如下:
<?php
/*** This file is part of Notadd.** @author TwilRoad <269044570@qq.com>* @copyright (c) 2016, iBenchu.org* @datetime 2016-11-08 17:01*/
namespace Notadd\Foundation\Setting\Controllers;use Notadd\Foundation\Routing\Abstracts\Controller;
use Notadd\Foundation\Setting\Contracts\SettingsRepository;
use Notadd\Foundation\Setting\Handlers\AllHandler;
use Notadd\Foundation\Setting\Handlers\SetHandler;/*** Class SettingController.*/
class SettingController extends Controller
{/*** @var \Notadd\Foundation\Setting\Contracts\SettingsRepository*/protected $settings;/*** SettingController constructor.** @param \Notadd\Foundation\Setting\Contracts\SettingsRepository $settings** @throws \Illuminate\Contracts\Container\BindingResolutionException*/public function __construct(SettingsRepository $settings){parent::__construct();$this->settings = $settings;}/*** All handler.** @param \Notadd\Foundation\Setting\Handlers\AllHandler $handler** @return \Notadd\Foundation\Passport\Responses\ApiResponse* @throws \Exception*/public function all(AllHandler $handler){return $handler->toResponse()->generateHttpResponse();}/*** Set handler.** @param \Notadd\Foundation\Setting\Handlers\SetHandler $handler** @return \Notadd\Foundation\Passport\Responses\ApiResponse* @throws \Exception*/public function set(SetHandler $handler){return $handler->toResponse()->generateHttpResponse();}
}
API Handler 和模型
在 API Handler中提供了模型的操作接口。
在 Notadd 中,提供了兩類 API Handler,一類是 DataHandler,另一類是 SetHandler,顧名思義,DataHandler 僅提供數據返回接口,而 SetHandler 不僅提供數據返回接口,還提供其他操作處理的接口。
具體差異體現在,DataHandler 在返回數據接口時僅調用方法 data,而 SetHandler 在調用 data 方法前還有調用 execute 方法。
例如,在前面的 SettingController 中使用的 AllHandler 為 DataHandler 類 Handler,提供返回所有 配置項 的 API 功能,SetHandler 為 SetHandler 類 Handler,提供 修改配置項 并返回所有 配置項 的 API 功能。
AllHandler 的代碼如下:
<?php
/*** This file is part of Notadd.** @author TwilRoad <269044570@qq.com>* @copyright (c) 2016, iBenchu.org* @datetime 2016-11-23 14:44*/
namespace Notadd\Foundation\Setting\Handlers;use Illuminate\Container\Container;
use Notadd\Foundation\Passport\Abstracts\DataHandler;
use Notadd\Foundation\Setting\Contracts\SettingsRepository;/*** Class AllHandler.*/
class AllHandler extends DataHandler
{/*** @var \Notadd\Foundation\Setting\Contracts\SettingsRepository*/protected $settings;/*** AllHandler constructor.** @param \Illuminate\Container\Container $container* @param \Notadd\Foundation\Setting\Contracts\SettingsRepository $settings*/public function __construct(Container $container,SettingsRepository $settings) {parent::__construct($container);$this->settings = $settings;}/*** Http code.** @return int*/public function code() // 定義 API 操作結果的狀態碼{return 200;}/*** Data for handler.** @return array*/public function data() // 定義 API 返回的數據{return $this->settings->all()->toArray();}/*** Errors for handler.** @return array*/public function errors() // 定義 API 操作失敗時返回的信息{return ['獲取全局設置失敗!',];}/*** Messages for handler.** @return array*/public function messages() // 定義 API 操作成功時返回的信息{return ['獲取全局設置成功!',];}
}
SetHandler 的代碼如下:
<?php
/*** This file is part of Notadd.** @author TwilRoad <269044570@qq.com>* @copyright (c) 2016, iBenchu.org* @datetime 2016-11-23 15:09*/
namespace Notadd\Foundation\Setting\Handlers;use Illuminate\Container\Container;
use Notadd\Foundation\Passport\Abstracts\SetHandler as AbstractSetHandler;
use Notadd\Foundation\Setting\Contracts\SettingsRepository;/*** Class SetHandler.*/
class SetHandler extends AbstractSetHandler
{/*** @var \Notadd\Foundation\Setting\Contracts\SettingsRepository*/protected $settings;/*** SetHandler constructor.** @param \Illuminate\Container\Container $container* @param \Notadd\Foundation\Setting\Contracts\SettingsRepository $settings*/public function __construct(Container $container,SettingsRepository $settings) {parent::__construct($container);$this->settings = $settings;}/*** Data for handler.** @return array*/public function data() // 定義 API 返回的數據{return $this->settings->all()->toArray();}/*** Errors for handler.** @return array*/public function errors() // 定義 API 操作失敗時返回的信息{return ['修改設置失敗!',];}/*** Execute Handler.** @return bool*/public function execute() // 定義 API 執行的修改操作{$this->settings->set('site.enabled', $this->request->input('enabled'));$this->settings->set('site.name', $this->request->input('name'));$this->settings->set('site.domain', $this->request->input('domain'));$this->settings->set('site.beian', $this->request->input('beian'));$this->settings->set('site.company', $this->request->input('company'));$this->settings->set('site.copyright', $this->request->input('copyright'));$this->settings->set('site.statistics', $this->request->input('statistics'));return true;}/*** Messages for handler.** @return array*/public function messages() // 定義 API 操作成功時返回的信息{return ['修改設置成功!',];}
}
數據輸出
API 結果的數據輸出,已經在 控制器(controller) 中做了處理。
至此,一個完整的 API 開發完成。