1.3 PhalApi 2.x 如何請求接口服務(wù)

如何請求接口服務(wù)

HTTP協(xié)議下的請求方式

對于PhalApi，默認(rèn)是通過HTTP協(xié)議進(jìn)行通信的。根據(jù)接口服務(wù)的具體實(shí)現(xiàn)，可以使用GET或POST方式請求。

訪問入口

如前面所言，PhalApi推薦將系統(tǒng)對外可訪問的根目錄設(shè)置為/path/to/phalapi/public。PhalApi的統(tǒng)一訪問入口文件是/path/to/phalapi/index.php文件。

當(dāng)配置的域名為：dev.phalapi.net，并且已將根目錄設(shè)置到public，此時訪問的URL是：

http://dev.phalapi.net

當(dāng)未配置域名，亦未配置根目錄時，此時訪問的URL是（顯然更長更不優(yōu)雅）：

http://localhost/phalapi/public/index.php

如果尚未安裝，請先閱讀下載與安裝。

如何指定待請求的接口服務(wù)？

默認(rèn)情況下，可以通過s參數(shù)指定待請求的接口服務(wù)，當(dāng)s未傳時，缺省使用默認(rèn)接口服務(wù)，即：App.Site.Index。以下三種方式是等效的，都是請求默認(rèn)接口服務(wù)。

• 未傳s參數(shù)
• ?s=Site.Index，省略命名空間，默認(rèn)使用App
• ?s=App.Site.Index，帶有命名空間前綴

也就是說，當(dāng)請求除默認(rèn)接口服務(wù)以外的接口服務(wù)時，其格式可以二選一：

• ?s=Class.Action
• 或者：?s=Namespace.Class.Action

其中，Namespace表示命名空間前綴，Class為接口服務(wù)類名，Action為接口服務(wù)方法名，這三者通常首字母大寫，并使用英文點(diǎn)號分割。最終執(zhí)行的類方法是：Namespace/Api/Class::Action()。需要注意的是：

溫馨提示：s參數(shù)為service參數(shù)的縮寫，即使用?s=Class.Action等效于?service=Class.Action，兩者都存在時優(yōu)先使用service參數(shù)。

關(guān)于Namespace命名空間

Namespace是指命名空間中/Api/的前半部分。并且需要在根目錄下的composer.json文件中進(jìn)行autoload的注冊，以便能正常自動加載類文件。如默認(rèn)已經(jīng)注冊的App命名空間：

{
    "autoload": {
        "psr-4": {
            "App\\": "src/app"
        }
    }
}

當(dāng)命名空間存在子命名空間時，在請求時使用下劃線分割。反過來，當(dāng)不存在多級命名空間時，命名空間不應(yīng)該含有下劃線。

關(guān)于Class接口服務(wù)類名

Class接口服務(wù)類名是指命名空間中/Api/的后半部分，并且必須是PhalApi/Api的子類。當(dāng)命名空間存在子命名空間時，在請求時同樣改用下劃線分割。類似的，當(dāng)不存在多級命名空間時，命名空間不應(yīng)該含有下劃線。

關(guān)于Action接口服務(wù)方法名

待請求的Action，應(yīng)該是public訪問級別的類方法，并且不能是PhalApi/Api已經(jīng)存在的方法。

一些示例

以下是一些綜合的示例。

上面示例中假設(shè)，已經(jīng)在composer.json中配置有：

{
    "autoload": {
        "psr-4": {
            "App\\": "src/app",
            "User\\": "src/user",
            "Company\\User\\": "src/company_user"
        }
    }
}

擴(kuò)展：如何定制接口服務(wù)的傳遞方式？

雖然我們約定統(tǒng)一使用?s=Namespace.Class.Action的格式來傳遞接口服務(wù)名稱，但如果項目有需要，也可以采用其他方式來傳遞。例如類似于Yii框架的請求格式：?r=Namespace/Class/Action。

如果需要定制傳遞接口服務(wù)名稱的方式，可以重寫PhalApi\Request::getService()方法。以下是針對改用斜杠分割，并換用r參數(shù)名字的實(shí)現(xiàn)代碼片段。

// 文件 ./src/app/Common/Request.php


<?php
namespace App\Common;


class Request extends \PhalApi\Request {


    public function getService() {
        // 優(yōu)先返回自定義格式的接口服務(wù)名稱
        $service = $this->get('r');
        if (!empty($service)) {
            $namespace = count(explode('/', $service)) == 2 ? 'App.' : '';
            return $namespace . str_replace('/', '.', $service);
        }


        return parent::getService();
    }
}

實(shí)現(xiàn)好自定義的請求類后，需要在項目的DI配置文件./config/di.php進(jìn)行注冊。在最后的加上一行：

$di->request = new App\Common\Request();

這時，便可以通過新的方式來進(jìn)行接口服務(wù)的請求的了。即：

這里有幾個注意事項：

• 1、重寫后的方法需要轉(zhuǎn)換為原始的接口服務(wù)格式，即：Namespace.Class.Action，注意別遺漏命名空間。
• 2、為保持兼容性，在取不到自定義的接口服務(wù)名稱參數(shù)時，應(yīng)該返回parent::getService()。

是不是覺得很好玩？可以立馬親自嘗試一下哦。定制你最喜歡的請求方式。

在線接口文檔

PhalApi提供一些非常實(shí)用而又貼心的功能特性，其中最具特色的就是自動生成的在線可視化文檔。在線接口文檔主要分為兩大類，分別是：

• 在線接口列表文檔
• 在線接口詳情文檔

當(dāng)客戶端不知道有哪些接口服務(wù)，或者需要查看某個接口服務(wù)的說明時，可借助此在線接口文檔。訪問在線接口列表文檔的URL是：

http://dev.phalapi.net/docs.php

打開后，便可看到類似下面這樣的在線接口文檔。

此在線文檔是實(shí)時生成的，可根據(jù)接口源代碼以及注釋自動生成。當(dāng)有新增接口服務(wù)時，刷新后便可立即看到效果。通過在接口列表文檔，可點(diǎn)擊進(jìn)入相應(yīng)的接口詳情文檔頁面。

溫馨提示：如果打開在線文檔，未顯示任何接口服務(wù)，請確保服務(wù)環(huán)境是否已關(guān)閉PHP的opcache緩存。

如何生成離線文檔？

上面在線的接口文檔，也可以一鍵生成離線版的HTML文檔，方便傳閱，離線查看。

當(dāng)需要生成離線文檔時，可以在終端，執(zhí)行以下命令：

phalapi$ php ./public/docs.php 


Usage:


生成展開版：  php ./public/docs.php expand
生成折疊版：  php ./public/docs.php fold


腳本執(zhí)行完畢！離線文檔保存路徑為：/path/to/phalapi/public/docs

執(zhí)行后，可以看到類似上面的提示和結(jié)果輸出。再查看生成的離線文檔，可以看到類似有：

phalapi$ tree ./public/docs
./public/docs
├── App.Examples_CURD.Delete.html
├── App.Examples_CURD.Get.html
├── App.Examples_CURD.GetList.html
├── App.Examples_CURD.Insert.html
├── App.Examples_CURD.Update.html
├── App.Examples_Upload.Go.html
├── App.Site.Index.html
└── index.html

最后，可以在頁面訪問此離線版文檔，如訪問鏈接：

http://dev.phalapi.net/docs/index.html

也可以將此docs目錄打包，在本地打開訪問查看。