丰满爆乳一区二区三区,亚洲av无码专区在线亚,无码中文人妻在线一区

Api接口服務(wù)層

Api接口層稱為接口服務(wù)層，負(fù)責(zé)對客戶端的請求進(jìn)行響應(yīng)，處理接收客戶端傳遞的參數(shù)，進(jìn)行高層決策并對領(lǐng)域業(yè)務(wù)層進(jìn)行調(diào)度，最后將處理結(jié)果返回給客戶端。

接口參數(shù)規(guī)則配置

接口參數(shù)，對于接口服務(wù)本身來說，是非常重要的。對于外部調(diào)用的客戶端來說，同等重要。對于接口參數(shù)，我們希望能夠既減輕后臺開發(fā)對接口參數(shù)獲取、判斷、驗(yàn)證、文檔編寫的痛苦；又能方便客戶端快速調(diào)用，明確參數(shù)的意義。由此，我們引入了參數(shù)規(guī)則這一概念，即：通過配置參數(shù)的規(guī)則，自動實(shí)現(xiàn)對參數(shù)的獲取和驗(yàn)證，同時自動生成在線接口文檔。

一個簡單的示例

假設(shè)我們現(xiàn)在需要提供一個用戶登錄的接口，接口參數(shù)有用戶名和密碼，那么新增的接口類和規(guī)則如下：

// 文件 ./src/app/Api/User.php
<?php
namespace App\Api;


use PhalApi\Api;


class User extends Api {


    public function getRules() {
        return array(
            'login' => array(
                'username' => array('name' => 'username'),
                'password' => array('name' => 'password'),
            ),
        );
    }


    public function login() {
        return array('username' => $this->username, 'password' => $this->password);
    }                               
}

當(dāng)請求此接口服務(wù)，并類似這樣帶上username和password參數(shù)時：

/?s=User.Login&username=dogstar&password=123456

就可以得到這樣的返回結(jié)果。

{"ret":0,"data":{"username":"dogstar","password":"123456"},"msg":""}

參數(shù)規(guī)則格式

參數(shù)規(guī)則是針對各個接口服務(wù)而配置的多維規(guī)則數(shù)組，由接口類的getRules()方法返回。其中，

一維下標(biāo)是接口類的方法名，對應(yīng)接口服務(wù)的Action；
二維下標(biāo)是類屬性名稱，對應(yīng)在服務(wù)端獲取通過驗(yàn)證和轉(zhuǎn)換化的最終客戶端參數(shù)；
三維下標(biāo)name是接口參數(shù)名稱，對應(yīng)外部客戶端請求時需要提供的參數(shù)名稱。

小結(jié)如下：

    public function getRules() {
        return array(
            '接口類方法名' => array(
                '接口類屬性' => array('name' => '接口參數(shù)名稱', ... ... ),
            ),
        );
    }

在接口實(shí)現(xiàn)類里面getRules()成員方法配置參數(shù)規(guī)則后，便可以通過類屬性的方式，根據(jù)配置指定的名稱獲取對應(yīng)的接口參數(shù)，如上面的：$this->username和$this->password。

三級參數(shù)規(guī)則配置

參數(shù)規(guī)則主要有三種，分別是：系統(tǒng)參數(shù)規(guī)則、應(yīng)用參數(shù)規(guī)則、接口參數(shù)規(guī)則。

系統(tǒng)參數(shù)

系統(tǒng)參數(shù)是指被框架保留使用的參數(shù)。目前已被PhalApi占用的系統(tǒng)參數(shù)只有一個，即：service參數(shù)（縮寫為s參數(shù)），前面已有介紹。

應(yīng)用參數(shù)

應(yīng)用參數(shù)是指在一個接口系統(tǒng)中，全部項(xiàng)目的全部接口都需要的參數(shù)，或者通用的參數(shù)。假如我們的商城接口系統(tǒng)中全部的接口服務(wù)都需要必須的簽名sign參數(shù)，以及非必須的版本號，則可以在./config/app.php中的apiCommonRules進(jìn)行應(yīng)用參數(shù)規(guī)則的配置：

<?php
return array(
    /**
     * 應(yīng)用接口層的統(tǒng)一參數(shù)
     */
    'apiCommonRules' => array(
        //簽名
        'sign' => array(
            'name' => 'sign', 'require' => true,
        ),
        //客戶端App版本號，默認(rèn)為：1.4.0
        'version' => array(
            'name' => 'version', 'default' => '1.4.0', 
        ),
    ),
)

接口參數(shù)

接口參數(shù)是指各個具體的接口服務(wù)所需要的參數(shù)，為特定的接口服務(wù)所持有，獨(dú)立配置。并且進(jìn)一步在內(nèi)部又細(xì)分為兩種：

通用接口參數(shù)規(guī)則：使用*作為下標(biāo)，對當(dāng)前接口類全部的方法有效。
指定接口參數(shù)規(guī)則：使用方法名作為下標(biāo)，只對接口類的特定某個方法有效。

例如為了加強(qiáng)安全性，需要為全部的用戶接口服務(wù)都加上長度為4位的驗(yàn)證碼參數(shù)：

    public function getRules() {
        return array(
            '*' => array(
                'code' => array('name' => 'code', 'require' => true, 'min' => 4, 'max' => 4),
            ),
            'login' => array(
                'username' => array('name' => 'username', 'require' => true),
                'password' => array('name' => 'password', 'require' => true, 'min' => 6),
            ),
        );
    }

現(xiàn)在，當(dāng)再次請求用戶登錄接口，除了要提供用戶名和密碼外，我們還要提供驗(yàn)證碼code參數(shù)。并且，對于Api\User類的其他方法也一樣。

多個參數(shù)規(guī)則時的優(yōu)先級

當(dāng)同一個參數(shù)規(guī)則分別在應(yīng)用參數(shù)、通用接口參數(shù)及指定接口參數(shù)出現(xiàn)時，后面的規(guī)則會覆蓋前面的，即具體化的規(guī)則會替換通用的規(guī)則，以保證接口參數(shù)滿足特定場合的定制要求。

簡而言之，多個參數(shù)規(guī)則的優(yōu)先級從高到下，分別是（正如你想到的那樣）：

1、指定接口參數(shù)規(guī)則
2、通用接口參數(shù)規(guī)則
3、應(yīng)用參數(shù)規(guī)則
4、系統(tǒng)參數(shù)規(guī)則

參數(shù)規(guī)則配置詳細(xì)說明

具體的參數(shù)規(guī)則，根據(jù)不同的類型有不同的配置選項(xiàng)，以及一些公共的配置選項(xiàng)。目前，主要的類型有：字符串、整數(shù)、浮點(diǎn)數(shù)、布爾值、時間戳/日期、數(shù)組、枚舉類型、文件上傳和回調(diào)函數(shù)。

類型 type	參數(shù)名稱 name	是否必須 require	默認(rèn)值 default	最小值 min，最大值 max	更多配置選項(xiàng)（無特殊說明，均為可選）
字符串	string	TRUE/FALSE，默認(rèn)FALSE	應(yīng)為字符串	可選	regex選項(xiàng)用于配置正則匹配的規(guī)則；format選項(xiàng)用于定義字符編碼的類型，如utf8、gbk、gb2312等
整數(shù)	int	TRUE/FALSE，默認(rèn)FALSE	應(yīng)為整數(shù)	可選	---
浮點(diǎn)數(shù)	float	TRUE/FALSE，默認(rèn)FALSE	應(yīng)為浮點(diǎn)數(shù)	可選	---
布爾值	boolean	TRUE/FALSE，默認(rèn)FALSE	true/false	---	以下值會轉(zhuǎn)換為TRUE：ok，true，success，on，yes，1，以及其他PHP作為TRUE的值
時間戳/日期	date	TRUE/FALSE，默認(rèn)FALSE	日期字符串	可選，僅當(dāng)為format配置為timestamp時才判斷，且最值應(yīng)為時間戳	format選項(xiàng)用于配置格式，為timestamp時會將字符串的日期轉(zhuǎn)換為時間戳
數(shù)組	array	TRUE/FALSE，默認(rèn)FALSE	字符串或者數(shù)組，為非數(shù)組會自動轉(zhuǎn)換/解析成數(shù)組	可選，判斷數(shù)組元素個數(shù)	format選項(xiàng)用于配置數(shù)組和格式，為explode時根據(jù)separator選項(xiàng)將字符串分割成數(shù)組, 為json時進(jìn)行JSON解析
枚舉	enum	TRUE/FALSE，默認(rèn)FALSE	應(yīng)為range選項(xiàng)中的某個元素	---	必須的range選項(xiàng)，為一數(shù)組，用于指定枚舉的集合
文件	file	TRUE/FALSE，默認(rèn)FALSE	數(shù)組類型	可選，用于表示文件大小范圍，單位為B	range選項(xiàng)用于指定可允許上傳的文件類型；ext選項(xiàng)用于表示需要過濾的文件擴(kuò)展名
回調(diào)	callable/callback	TRUE/FALSE，默認(rèn)FALSE	---	---	callable/callback選項(xiàng)用于設(shè)置回調(diào)函數(shù)，params選項(xiàng)為回調(diào)函數(shù)的第三個參數(shù)（另外第一個為參數(shù)值，第二個為所配置的規(guī)則）

公共配置選項(xiàng)

公共的配置選項(xiàng)，除了上面的類型、參數(shù)名稱、是否必須、默認(rèn)值，還有說明描述、數(shù)據(jù)來源。下面分別簡單說明。

類型 type
用于指定參數(shù)的類型，可以是string、int、float、boolean、date、array、enum、file、callable，或者自定義的類型。未指定時，默認(rèn)為字符串。
參數(shù)名稱 name
接口參數(shù)名稱，即客戶端需要傳遞的參數(shù)名稱。與PHP變量規(guī)則一樣，以下劃線或字母開頭。此選項(xiàng)必須提供，否則會提示錯誤。
是否必須require
為TRUE時，表示此參數(shù)為必須值；為FALSE時，表示此參數(shù)為可選。未指定時，默認(rèn)為FALSE。
默認(rèn)值 default
未提供接口參數(shù)時的默認(rèn)值。未指定時，默認(rèn)為NULL。
最小值 min，最大值 max
部分類型適用。用于指定接口參數(shù)的范圍，比較時采用的是閉區(qū)間，即范圍應(yīng)該為：[min, max]。也可以只使用min或max，若只配置了min，則表示：[min, +∞)；若只配置了maz，則表示：(-∞, max]。

說明描述 desc
用于自動生成在線接口詳情文檔，對參數(shù)的含義和要求進(jìn)行扼要說明。未指定時，默認(rèn)為空字符串。
數(shù)據(jù)來源 source
指定當(dāng)前單個參數(shù)的數(shù)據(jù)來源，可以是post、get、cookie、server、request、header、或其他自定義來源。未指定時，默認(rèn)為統(tǒng)一數(shù)據(jù)源。目前支持的source與對應(yīng)的數(shù)據(jù)源映射關(guān)系如下：

source 對應(yīng)的數(shù)據(jù)源

post $_POST

get $_GET

cookie $_COOKIE

server $_SERVER

request $_REQUEST

header $_SERVER['HTTP_X']

source	對應(yīng)的數(shù)據(jù)源
post	$_POST
get	$_GET
cookie	$_COOKIE
server	$_SERVER
request	$_REQUEST
header	$_SERVER['HTTP_X']

通過source參數(shù)可以輕松、更自由獲取不同來源的參數(shù)。以下是一些常用的配置示例。

// 獲取HTTP請求方法，判斷是POST還是GET
'method' => array('name' => 'REQUEST_METHOD', 'source' => 'server'),


// 獲取COOKIE中的標(biāo)識
'is_new_user' => array('name' => 'is_new_user', 'source' => 'cookie'),


// 獲取HTTP頭部中的編碼，判斷是否為utf-8
'charset' => array('name' => 'Accept-Charset', 'source' => 'header'),

若配置的source為無效或非法時，則會拋出異常。如配置了'source' => 'NOT_FOUND'，會得到：

"msg": "服務(wù)器運(yùn)行錯誤: 參數(shù)規(guī)則中未知的數(shù)據(jù)源：NOT_FOUND"

9種參數(shù)類型

對于各種參數(shù)類型，結(jié)合示例說明如下。

字符串 string

當(dāng)一個參數(shù)規(guī)則未指定類型時，默認(rèn)為string。如最簡單的：

array('name' => 'username')

溫馨提示：這一小節(jié)的參數(shù)規(guī)則配置示例，都省略了類屬性，以關(guān)注配置本身的內(nèi)容。

這樣就配置了一個參數(shù)規(guī)則，接口參數(shù)名字叫username，類型為字符串。

一個完整的寫法可以為：

array('name' => 'username', 'type' => 'string', 'require' => true, 'default' => 'nobody', 'min' => 1, 'max' => 10)

這里指定了為必選參數(shù)，默認(rèn)值為nobody，且最小長度為1個字符，最大長度為10個字符，若傳遞的參數(shù)長度過長，如&username=alonglonglonglongname，則會異常失敗返回：

"msg": "非法請求：username.len應(yīng)該小于等于10, 但現(xiàn)在username.len = 21"

當(dāng)需要驗(yàn)證的是中文的話，由于一個中文字符會占用3個字節(jié)。所以在min和max驗(yàn)證的時候會出現(xiàn)一些問題。為此，PhalApi提供了format配置選項(xiàng)，用于指定字符集。如：

array('name' => 'username', 'type' => 'string', 'format' => 'utf8', 'min' => 1, 'max' => 10)

我們還可以使用regex下標(biāo)來進(jìn)行正則表達(dá)式的驗(yàn)證，一個郵箱的例子是：

array('name' => 'email', 'regex' => "/^([0-9A-Za-z\\-_\\.]+)@([0-9a-z]+\\.[a-z]{2,3}(\\.[a-z]{2})?)$/i")

整型 int

整型即自然數(shù)，包括正數(shù)、0和負(fù)數(shù)。如通常數(shù)據(jù)庫中的id，即可配置成：

array('name' => 'id', 'type' => 'int', 'require' => true, 'min' => 1)

當(dāng)傳遞的參數(shù)，不在其配置的范圍內(nèi)時，如&id=0，則會異常失敗返回：

"msg": "非法請求：id應(yīng)該大于或等于1, 但現(xiàn)在id = 0"

另外，對于常見的分頁參數(shù)，可以這樣配置：

array('name' => 'page_num', 'type' => 'int', 'min' => 1, 'max' => 20, 'default' => 20)

即每頁數(shù)量最小1個，最大20個，默認(rèn)20個。

浮點(diǎn) float

浮點(diǎn)型，類似整型的配置，此處略。

布爾值 boolean

布爾值，主要是可以對一些字符串轉(zhuǎn)換成布爾值，如ok，true，success，on，yes，以及會被PHP解析成true的字符串，都會轉(zhuǎn)換成TRUE。如通常的“是否記住我”參數(shù)，可配置成：

array('name' => 'is_remember_me', 'type' => 'boolean', 'default' => TRUE)

則以下參數(shù)，最終服務(wù)端會作為TRUE接收。

?is_remember_me=ok
?is_remember_me=true
?is_remember_me=success
?is_remember_me=on
?is_remember_me=yes
?is_remember_me=1

日期 date

日期可以按自己約定的格式傳遞，默認(rèn)是作為字符串，此時不支持范圍檢測。例如配置注冊時間：

array('name' => 'register_date', 'type' => 'date')

對應(yīng)地，register_date=2015-01-31 10:00:00則會被獲取到為："2015-01-31 10:00:00"。

當(dāng)需要將字符串的日期轉(zhuǎn)換成時間戳?xí)r，可追加配置選項(xiàng)'format' => 'timestamp'，則配置成：

array('name' => 'register_date', 'type' => 'date', 'format' => 'timestamp')

則上面的參數(shù)再請求時，則會被轉(zhuǎn)換成：1422669600。

此時作為時間戳，還可以添加范圍檢測，如限制時間范圍在31號當(dāng)天：

array('name' => 'register_date', 'type' => 'date', 'format' => 'timestamp', 'min' =>  1422633600, 'max' => 1422719999)

當(dāng)配置的最小值或最大值為字符串的日期時，會自動先轉(zhuǎn)換成時間戳再進(jìn)行檢測比較。如可以配置成：

array('name' => 'register_date', ... ... 'min' => '2015-01-31 00:00:00', 'max' => '2015-01-31 23:59:59')

數(shù)組 array

很多時候在接口進(jìn)行批量獲取時，都需要提供一組參數(shù)，如多個ID，多個選項(xiàng)。這時可以使用數(shù)組來進(jìn)行配置。如：

array('name' => 'uids', 'type' => 'array', 'format' => 'explode', 'separator' => ',')

這時接口參數(shù)&uids=1,2,3則會被轉(zhuǎn)換成：

array ( 0 => '1', 1 => '2', 2 => '3', )

如果設(shè)置了默認(rèn)值，那么默認(rèn)值會從字符串，根據(jù)相應(yīng)的format格式進(jìn)行自動轉(zhuǎn)換。如：

array( ... ... 'default' => '4,5,6')

那么在未傳參數(shù)的情況下，自動會得到：

array ( 0 => '4', 1 => '5', 2 => '6', )

又如接口需要使用JSON來傳遞整塊參數(shù)時，可以這樣配置：

array('name' => 'params', 'type' => 'array', 'format' => 'json')

對應(yīng)地，接口參數(shù)¶ms={"username":"test","password":"123456"}則會被轉(zhuǎn)換成：

array ( 'username' => 'test', 'password' => '123456', )

溫馨提示：使用JSON傳遞參數(shù)時，建議使用POST方式傳遞。若使用GET方式，須注意參數(shù)長度不應(yīng)超過瀏覽器最大限制長度，以及URL編碼問。

若使用JSON格式時，設(shè)置了默認(rèn)值為：

array( ... ... 'default' => '{"username":"dogstar","password":"xxxxxx"}')

那么在未傳參數(shù)的情況下，會得到轉(zhuǎn)換后的：

array ( 'username' => 'dogstar', 'password' => 'xxxxxx', )

特別地，當(dāng)配置成了數(shù)組卻未指定格式format時，接口參數(shù)會轉(zhuǎn)換成只有一個元素的數(shù)組，如接口參數(shù)：&name=test，會轉(zhuǎn)換成：

array ( 0 => 'test' )

枚舉 enum

在需要對接口參數(shù)進(jìn)行范圍限制時，可以使用此枚舉型。如對于性別的參數(shù)，可以這樣配置：

array('name' => 'sex', 'type' => 'enum', 'range' => array('female', 'male'))

當(dāng)傳遞的參數(shù)不合法時，如&sex=unknow，則會被攔截，返回失敗：

"msg": "非法請求：參數(shù)sex應(yīng)該為：female/male，但現(xiàn)在sex = unknow"

關(guān)于枚舉類型的配置，這里需要特別注意配置時，應(yīng)盡量使用字符串的值。因?yàn)橥ǔ６?，接口通過GET/POST方式獲取到的參數(shù)都是字符串的，而如果配置規(guī)則時指定范圍用了整型，會導(dǎo)致底層規(guī)則驗(yàn)證時誤判。例如接口參數(shù)為&type=N，而接口參數(shù)規(guī)則為：

array('name' => 'type', 'type' => 'enum', 'range' => array(0, 1, 2))

則會出現(xiàn)以下這樣的誤判：

var_dump(in_array('N', array(0, 1, 2))); // 結(jié)果為true，因?yàn)?'N' == 0

為了避免這類情況發(fā)生，應(yīng)該使用使用字符串配置范圍值，即可這樣配置：

array('name' => 'type', 'type' => 'enum', 'range' => array(`0`, `1`, `2`))

文件 file

在需要對上傳的文件進(jìn)行過濾、接收和處理時，可以使用文件類型，如：

array(
    'name' => 'upfile', 
    'type' => 'file', 
    'min' => 0, 
    'max' => 1024 * 1024, 
    'range' => array('image/jpeg', 'image/png') , 
    'ext' => array('jpeg', 'png')
)

其中，min和max分別對應(yīng)文件大小的范圍，單位為字節(jié)；range為允許的文件類型，使用數(shù)組配置，且不區(qū)分大小寫。

如果成功，返回的值對應(yīng)的是$_FILES["upfile"]，即會返回：

array(
     'name' => ..., // 被上傳文件的名稱
     'type' => ..., // 被上傳文件的類型
     'size' => ..., // 被上傳文件的大小，以字節(jié)計
     'tmp_name' => ..., // 存儲在服務(wù)器的文件的臨時副本的名稱
)

對應(yīng)的是：

$_FILES["upfile"]["name"] - 被上傳文件的名稱
$_FILES["upfile"]["type"] - 被上傳文件的類型
$_FILES["upfile"]["size"] - 被上傳文件的大小，以字節(jié)計
$_FILES["upfile"]["tmp_name"] - 存儲在服務(wù)器的文件的臨時副本的名稱
$_FILES["upfile"]["error"] - 由文件上傳導(dǎo)致的錯誤代碼

參考：以上內(nèi)容來自W3School，文件上傳時請使用表單上傳，并enctype 屬性使用"multipart/form-data"。更多請參考PHP 文件上傳。

若需要配置默認(rèn)值default選項(xiàng)，則也應(yīng)為一數(shù)組，且其格式應(yīng)類似如上。

其中，ext是對文件后綴名進(jìn)行驗(yàn)證，當(dāng)如果上傳文件后綴名不匹配時將拋出異常。文件擴(kuò)展名的過濾可以類似這樣進(jìn)行配置：

單個后綴名 - 數(shù)組形式
```
'ext' => array('jpg')
```

單個后綴名 - 字符串形式
```
'ext' => 'jpg'
```

多個后綴名 - 數(shù)組形式

'ext' => array('jpg', 'jpeg', 'png', 'bmp')

多個后綴名 - 字符串形式（以英文逗號分割）
```
'ext' => 'jpg,jpeg,png,bmp' 
```

回調(diào) callable/callback

當(dāng)需要利用已有函數(shù)進(jìn)行自定義驗(yàn)證時，可采用回調(diào)參數(shù)規(guī)則，如配置規(guī)則：

array('name' => 'version', 'type' => 'callable', 'callback' => 'App\\Common\\Request\\Version::formatVersion')

然后，回調(diào)時將調(diào)用下面這個新增的類函數(shù)：

<?php
namespace App\Common\Request;


use PhalApi\Exception\BadRequestException;


class Version {


    public static function formatVersion($value, $rule) {
        if (count(explode('.', $value)) < 3) {
            throw new BadRequestException('版本號格式錯誤');
        }
        return $value;
    }
}

回調(diào)函數(shù)的簽名為：function format($value, $rule, $params)，第一個為參數(shù)原始值，第二個為所配置的規(guī)則，第三個可選參數(shù)為配置規(guī)則中的params選項(xiàng)。最后應(yīng)返回轉(zhuǎn)換后的參數(shù)值。

接口返回

回顧一下，在PhalApi中，掊口返回的結(jié)果的結(jié)構(gòu)為：

{
    "ret": 200, // 狀態(tài)碼
    "data": {
        // 業(yè)務(wù)數(shù)據(jù)
    },
    "msg": "" // 錯誤提示信息
}

正常情況下的返回

正常情況下，在Api層返回的數(shù)據(jù)結(jié)果，會在返回結(jié)果的data字段中體現(xiàn)。例如：

class Hello extends Api {


    public function world() {
        return array('title' => 'Hello World!');
    }
}

對應(yīng)：

{
    "ret": 200,
    "data": {
        "title": "Hello World!"
    },
    "msg": ""
}

成功返回時，狀態(tài)碼ret為200，并且錯誤信息msg為空。

失敗情況下的返回

對于異常情況，包括系統(tǒng)錯誤或者應(yīng)用層的錯誤，可以通過拋出PhalApi\Exception系列的異常，中斷請求并返回相關(guān)的錯誤信息。例如：

class Hello extends Api {


    public function fail() {
        throw new BadRequestException('簽名失敗', 1);
    }
}

會得到以下結(jié)果輸出：

{
    "ret": 401,
    "data": [],
    "msg": "Bad Request: 簽名失敗"
}

注釋與在線文檔

PhalApi提供了自動生成的在線接口文檔，對于每一個接口服務(wù)，都有對應(yīng)的在線接口詳情文檔。如默認(rèn)接口服務(wù)Site.Index的在線接口詳情文檔為：

此在線接口詳情文檔，從上到下，依次說明如下。

接口服務(wù)名稱

接口服務(wù)名稱是指用于請求時的名稱，對應(yīng)s參數(shù)（或service參數(shù)）。接口服務(wù)的中文名稱，為不帶任何注解的注釋，通常為接口類成員函數(shù)的第一行注釋。

class Site extends Api {


    /**
     * 默認(rèn)接口服務(wù)
     */
    public function index() {
    }
}

接口說明

接口說明對應(yīng)接口類成員函數(shù)的@desc注釋。

class Site extends Api {


    /**
     * 默認(rèn)接口服務(wù)
     * @desc 默認(rèn)接口服務(wù)，當(dāng)未指定接口服務(wù)時執(zhí)行此接口服務(wù)
     */
    public function index() {
    }
}

接口參數(shù)

接口參數(shù)是根據(jù)接口類配置的參數(shù)規(guī)則自動生成，即對應(yīng)當(dāng)前接口類getRules()方法中的返回。其中最后的“說明” 字段對應(yīng)參數(shù)規(guī)則中的desc選項(xiàng)?？梢耘渲枚鄠€參數(shù)規(guī)則。此外，配置文件./config/app.php中的公共參數(shù)規(guī)則也會顯示在此接口參數(shù)里。

class Site extends Api {


    public function getRules() {
        return array(
            'index' => array(
                'username'  => array('name' => 'username', 'default' => 'PHPer', ),
            ),
        );
    }
}

返回結(jié)果

返回結(jié)果對應(yīng)接口類成員函數(shù)的@return注釋，可以有多組，格式為：@return 返回類型返回字段說明。

class Site extends Api {


    /**
     * 默認(rèn)接口服務(wù)
     * @desc 默認(rèn)接口服務(wù)，當(dāng)未指定接口服務(wù)時執(zhí)行此接口服務(wù)
     * @return string title 標(biāo)題
     * @return string content 內(nèi)容
     * @return string version 版本，格式：X.X.X
     * @return int time 當(dāng)前時間戳
     */
    public function index() {
    }
}

異常情況

異常情況對應(yīng)@exception注釋，可以有多組，格式為：@exception 錯誤碼錯誤描述信息。例如：

    /**
     * @exception 406 簽名失敗
     */
    public function index() {

刷新后，可以看到新增的異常情況說明。

公共注釋

對于當(dāng)前類的全部函數(shù)成員的公共@exception異常情況注釋和@return返回結(jié)果注釋，可在類注釋中統(tǒng)一放置。而對于多個類公共的@exception和@return```注釋，則可以在父類的類注釋中統(tǒng)一放置。

也就是說，通過把@exception注解和@return注解移到類注釋，可以添加全部函數(shù)成員都適用的注解。例如，Api\User類的全部接口都返回code字段，且都返回400和500異常，則可以：

<?php
namespace App\Api;


use PhalApi\Api;


/**
 * @return int code 操作碼，0表示成功
 * @exception 400 參數(shù)傳遞錯誤
 * @exception 500 服務(wù)器內(nèi)部錯誤
 */


class User extends Api {

這樣就不需要在每個函數(shù)成員的注釋中重復(fù)添加注解。此外，也可以在父類的注釋中進(jìn)行添加。對于相同異常碼的@exception注解，子類的注釋會覆蓋父類的注釋，方法的注釋會覆蓋類的注釋；而對于相同的返回結(jié)果@return注釋，也一樣。

需要注意的是，注釋必須是緊挨在類的前面，而不能是在namespace前面，否則會導(dǎo)致注釋解析失敗。

1.5 PhalApi 2.x Api接口層

Api接口服務(wù)層

接口參數(shù)規(guī)則配置

一個簡單的示例

參數(shù)規(guī)則格式

三級參數(shù)規(guī)則配置

系統(tǒng)參數(shù)

應(yīng)用參數(shù)

接口參數(shù)

多個參數(shù)規(guī)則時的優(yōu)先級

參數(shù)規(guī)則配置詳細(xì)說明

公共配置選項(xiàng)

9種參數(shù)類型

接口返回

正常情況下的返回

失敗情況下的返回

注釋與在線文檔

接口服務(wù)名稱

接口說明

接口參數(shù)

返回結(jié)果

異常情況

公共注釋