如何基於 Notadd 構建 API （Laravel 寫 API）

依劍聽雨發表於2017-03-07
APILaravel

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 開發完成。

本作品採用《CC 協議》，轉載必須註明作者和本文連結

相關文章