# 如何請求接口服務
## HTTP協議下的請求方式
對于PhalApi，默認是通過HTTP協議進行通信的。根據接口服務的具體實現，可以使用GET或POST方式請求。
## 訪問入口
如前面所言，PhalApi推薦將系統對外可訪問的根目錄設置為/path/to/phalapi/public。PhalApi的統一訪問入口文件是/path/to/phalapi/index.php文件。
當配置的域名為：dev.phalapi.net，并且已將根目錄設置到public，此時訪問的URL是：
```
http://dev.phalapi.net
```
當未配置域名，亦未配置根目錄時，此時訪問的URL是（顯然更長更不優雅）：
```
http://localhost/phalapi/public/index.php
```
如果尚未安裝，請先閱讀[下載與安裝](download-and-setup)。
## 如何指定待請求的接口服務？
默認情況下，可以通過s參數指定待請求的接口服務，當s未傳時，缺省使用默認接口服務，即：App.Site.Index。以下三種方式是等效的，都是請求默認接口服務。
+ 未傳s參數
+ ?s=Site.Index，省略命名空間，默認使用App
+ ?s=App.Site.Index，帶有命名空間前綴
也就是說，當請求除默認接口服務以外的接口服務時，其格式可以二選一：
+ ?s=Class.Action
+ 或者：?s=Namespace.Class.Action
其中，Namespace表示命名空間前綴，Class為接口服務類名，Action為接口服務方法名，這三者通常首字母大寫，并使用英文點號分割。最終執行的類方法是：Namespace/Api/Class::Action()。需要注意的是：
> 溫馨提示：s參數為service參數的縮寫，即使用```?s=Class.Action```等效于```?service=Class.Action```，兩者都存在時優先使用service參數。
### 關于Namespace命名空間
Namespace是指命名空間中```/Api/```的前半部分。并且需要在根目錄下的composer.json文件中進行autoload的注冊，以便能正常自動加載類文件。如默認已經注冊的App命名空間：
```
{
"autoload": {
"psr-4": {
"App\\": "src/app"
}
}
}
```
當命名空間存在子命名空間時，在請求時使用下劃線分割。反過來，當不存在多級命名空間時，命名空間不應該含有下劃線。
### 關于Class接口服務類名
Class接口服務類名是指命名空間中```/Api/```的后半部分，并且必須是[PhalApi/Api](https://github.com/phalapi/kernal/blob/master/src/Api.php)的子類。當命名空間存在子命名空間時，在請求時同樣改用下劃線分割。類似的，當不存在多級命名空間時，命名空間不應該含有下劃線。
### 關于Action接口服務方法名
待請求的Action，應該是public訪問級別的類方法，并且不能是[PhalApi/Api](https://github.com/phalapi/kernal/blob/master/src/Api.php)已經存在的方法。
### 一些示例
以下是一些綜合的示例。
PhalApi 2.x 請求的s參數|對應的文件|執行的類方法
---|---|---
無|./src/app/Api/Site.php|Site::Index()
?s=Site.Index|./src/app/Api/Site.php|Site::index()
?s=Weibo.Login|./src/Api/Weibo.php|Weibo::login()
?s=User.Weibo.Login|./src/user/Api/Weibo.php|Weibo::login()
?s=Company_User.Third_Weibo.Login|./src/company_user/Api/Third/Weibo.php|Weibo::login()
上面示例中假設，已經在composer.json中配置有：
```
{
"autoload": {
"psr-4": {
"App\\": "src/app",
"User\\": "src/user",
"Company\\User\\": "src/company_user"
}
}
}
```
## 擴展：如何定制接口服務的傳遞方式？
雖然我們約定統一使用```?s=Namespace.Class.Action```的格式來傳遞接口服務名稱，但如果項目有需要，也可以采用其他方式來傳遞。例如類似于Yii框架的請求格式：```?r=Namespace/Class/Action```。
如果需要定制傳遞接口服務名稱的方式，可以重寫[PhalApi\Request::getService()](https://github.com/phalapi/kernal/blob/master/src/Request.php)方法。以下是針對改用斜杠分割，并換用r參數名字的實現代碼片段。
```php
// 文件 ./src/app/Common/Request.php
<?php
namespace App\Common;
class Request extends \PhalApi\Request {
public function getService() {
// 優先返回自定義格式的接口服務名稱
$service = $this->get('r');
if (!empty($service)) {
$namespace = count(explode('/', $service)) == 2 ? 'App.' : '';
return $namespace . str_replace('/', '.', $service);
}
return parent::getService();
}
}
```
實現好自定義的請求類后，需要在項目的DI配置文件[./config/di.php](https://github.com/phalapi/phalapi/blob/master/config/di.php)進行注冊。在最后的加上一行：
```php
$di->request = new App\Common\Request();
```
這時，便可以通過新的方式來進行接口服務的請求的了。即：
原來的方式|現在的方式
---|---
?s=Site.Index|?r=Site/Index
?s=App.Site.Index|?r=App/Site/Index
?s=Hello.World|?r=Hello/World
?s=App.Hello.World|?r=App/Hello/World
這里有幾個注意事項：
+ 1、重寫后的方法需要轉換為原始的接口服務格式，即：Namespace.Class.Action，注意別遺漏命名空間。
+ 2、為保持兼容性，在取不到自定義的接口服務名稱參數時，應該返回```parent::getService()```。
是不是覺得很好玩？可以立馬親自嘗試一下哦。定制你最喜歡的請求方式。
## 在線接口文檔
PhalApi提供一些非常實用而又貼心的功能特性，其中最具特色的就是自動生成的在線可視化文檔。在線接口文檔主要分為兩大類，分別是：
+ 在線接口列表文檔
+ 在線接口詳情文檔
當客戶端不知道有哪些接口服務，或者需要查看某個接口服務的說明時，可借助此在線接口文檔。訪問在線接口列表文檔的URL是：
```
http://dev.phalapi.net/docs.php
```
打開后，便可看到類似下面這樣的在線接口文檔。
此在線文檔是實時生成的，可根據接口源代碼以及注釋自動生成。當有新增接口服務時，刷新后便可立即看到效果。通過在接口列表文檔，可點擊進入相應的接口詳情文檔頁面。
> 溫馨提示：如果打開在線文檔，未顯示任何接口服務，請確保服務環境是否已關閉PHP的opcache緩存。
### 如何生成離線文檔？
上面在線的接口文檔，也可以一鍵生成離線版的HTML文檔，方便傳閱，離線查看。
當需要生成離線文檔時，可以在終端，執行以下命令：
```bash
phalapi$ php ./public/docs.php
Usage:
生成展開版： php ./public/docs.php expand
生成折疊版： php ./public/docs.php fold
腳本執行完畢！離線文檔保存路徑為：/path/to/phalapi/public/docs
```
執行后，可以看到類似上面的提示和結果輸出。再查看生成的離線文檔，可以看到類似有：
```bash
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目錄打包，在本地打開訪問查看。
