PhalApi（π框架） - V1.4.0
PhalApi，簡稱π框架，是一個PHP輕量級開源接口框架，專注于接口開發(fā)，致力讓接口開發(fā)更簡單。它：
1、致力于快速、穩(wěn)定、持續(xù)交付有價值的接口服務、關注于測試驅動開發(fā)、領域驅動設計、極限編程、敏捷開發(fā)
2、有眾多的擴展類庫，與更多開源項目一起提供高效便捷的解決方案
3、支持HTTP、SOAP和RPC協(xié)議，可用于快速搭建微服務、RESTful接口或Web Services
PhalApi代碼開源、產(chǎn)品開源、思想開源，請放心使用。更多請訪問PhalApi官網(wǎng)。再次感謝開源中國、各位貢獻者和同學。
導讀
本文內(nèi)容主要分為三部分，即：
PART 1：安裝、在線體驗與在線接口文檔
PART 2：快速開發(fā)、單元測試、目錄結構、SDK包和Library擴展類庫
PART 3：背景回顧、貢獻者、許可與更新日記
更多請訪問在線文檔。
1-1、安裝
請從release分支拉取發(fā)布版本的代碼
推薦部署于Linux服務器
建議PHP >= 5.3.3
將代碼下載解壓到服務器后，打開瀏覽器，訪問安裝向導（推薦使用nginx，并將根目錄設置為Public）：
http://localhost/PhalApi/Public/install/
訪問默認接口服務，驗證是否安裝成功：
http://localhost/PhalApi/Public/demo/
更多其他創(chuàng)建項目的方式，請訪問創(chuàng)建一個自己的項目。
框架升級與框架共享
我們會盡最大的努力保證完美兼容性的升級。當框架有新版本需要升級時，只需要簡單一步：更新替換./PhalApi/PhalApi核心框架目錄即可。
如果需要多個項目共享使用PhalApi框架，可以把./PhalApi/PhalApi移到任何位置，然后對應修改./PhalApi/Public/init.php文件中引入路徑即可（但會導致部分腳本命令不可用）。如：
require_once API_ROOT . '/path/to/PhalApi/PhalApi.php';
1-2、在線體驗
默認的接口服務：
http://demo.phalapi.net/
帶參數(shù)的示例接口：
http://demo.phalapi.net/?service=Default.Index&username=oschina
{
"ret": 200,
"data": {
"title": "Hello World!",
"content": "oschina您好，歡迎使用PhalApi！",
"version": "1.3.4",
"time": 1473863280
},
"msg": ""
}
故意請求一個非法的服務：
http://demo.phalapi.net/?service=Demo.None
{
"ret": 400,
"data": [],
"msg": "非法請求：服務Demo.None不存在"
}
1-3、在線接口文檔（自動生成）
按框架指定的格式完成接口代碼編寫后，PhalApi會自動生成在線接口列表文檔和在線接口詳情文檔，以方便客戶端實時查看最新的接口簽名和返回字段。
(1) 在線接口列表文檔
訪問對應項目路徑下的listAllApis.php可查看此項目下全部的接口服務，如訪問：
http://demo.phalapi.net/listAllApis.php
(2) 在線接口詳情文檔
訪問對應項目路徑下的checkApiParams.php，并傳遞?service=xxx.xxx參數(shù)即可查看具體的接口文檔，如訪問：
http://demo.phalapi.net/checkApiParams.php?service=Default.Index
2-1、快速開發(fā)
(1) 編寫一個Hello World!接口
以下代碼需要放置到接口類文件./Demo/Api/Welcome.php中：
class Api_Welcome extends PhalApi_Api {
public function say() {
$rs = array();
$rs['title'] = 'Hello World!';
return $rs;
}
}
(2) 訪問接口
接口訪問的格式為：接口域名 + 入口路徑 + ?service=XXX.XXX，此示例中對應的鏈接為：
http://localhost/Public/demo/?service=Welcome.Say
(3) 接口返回
結果默認以JSON格式返回，即：
{"ret":200,"data":{"title":"Hello World!"},"msg":""}
(4) 運行截圖
2-2、接口單元測試
不能被測試的代碼，不是好代碼。
在使用此框架進行接口開發(fā)時，我們強烈建議使用測試驅動開發(fā)（TDD），以便于不斷積累形成接口測試體系，保證接口向前向后兼容。例如對接口/?service=User.GetBaseInfo&userId=1進行單元測試時，按：構造-操作-檢驗（BUILD-OPERATE-CHECK）模式，即：
/**
* @group testGetBaseInfo
*/
public function testGetBaseInfo()
{
//Step 1. 構建請求URL
$str = 'service=User.GetBaseInfo&userId=1';
//Step 2. 執(zhí)行請求（模擬接口請求）
$rs = PhalApi_Helper_TestRunner::go($url);
//Step 3. 驗證
$this->assertNotEmpty($rs);
$this->assertArrayHasKey('code', $rs);
$this->assertArrayHasKey('msg', $rs);
$this->assertArrayHasKey('info', $rs);
$this->assertEquals(0, $rs['code']);
$this->assertEquals('dogstar', $rs['info']['name']);
$this->assertEquals('oschina', $rs['info']['from']);
}
運行效果：
對于框架的核心代碼，我們也一直堅持著單元測試，其核心框架代碼的單元測試覆蓋率可高達96%以上。
2-3、主要目錄結構
.
│
├── PhalApi? ? ? ? //PhalApi框架，后期可以整包升級
├── Library? ? ? ? //PhalApi擴展類庫，可根據(jù)需要自由添加擴展
├── SDK? ? ? ? ? ? //PhalApi提供的SDK包，客戶可根據(jù)需要選用
│
│
├── Public? ? ? ? ? //對外訪問目錄，建議隱藏PHP實現(xiàn)
│? └── demo? ? ? ? //Demo服務訪問入口
│
│
├── Config? ? ? ? ? //項目接口公共配置，主要有：app.php, sys.php, dbs.php
├── Data? ? ? ? ? ? //項目接口公共數(shù)據(jù)
├── Language? ? ? ? //項目接口公共翻譯
├── Runtime? ? ? ? //項目接口運行文件目錄，用于存放日記，可軟鏈到別的區(qū)
│
│
└── Demo? ? ? ? ? ? //應用接口服務，名稱自取，可多組
├── Api? ? ? ? ? ? //接口響應層
├── Domain? ? ? ? ? //接口領域層
├── Model? ? ? ? ? //接口持久層
└── Tests? ? ? ? ? //接口單元測試
2-4、基于接口查詢語言（ASL）的SDK包支持
目前已提供的SDK有：
C#版
JS版
Golang版
React-Native版
Python版
基于接口查詢語言，可用一句話來描述接口請求，如JAVA的請求示例：
PhalApiClientResponse response = PhalApiClient.create()
.withHost("http://demo.phalapi.net/")
.withService("Default.Index")? ? ? ? ? //接口服務
.withParams("username", "dogstar")? ? //接口參數(shù)
.withTimeout(3000)? ? ? ? ? ? ? ? ? ? //接口超時
.request();
2-5、PhalApi-Library擴展類庫
PhalApi框架擴展類庫，致力于與開源項目一起提供高效便捷的解決方案，更多請查看：PhalApi-Library。
3-1、背景回顧
過去十年，是互聯(lián)網(wǎng)時代；如今的十年，是移動時代。
在iOS、Android、Windows Phone、PC版、Web版等各種終端和各種垂直應用不停更新迭代的大背景下，顯然很是需要一組乃至一系列穩(wěn)定的后臺接口支撐。接口，顯然是如此重要，正如Jaroslav Tulach在《軟件框架設計的藝術》一書中說的：API就如同恒星，一旦出現(xiàn)，便與我們永恒共存。
所以，這里希望通過提供一個快速可用的后臺接口開發(fā)框架，可以：
一來，支撐輕量級項目后臺接口的快速開發(fā)；
二來，闡明如何進行接口開發(fā)、設計和維護，以很好支持海量訪問、大數(shù)據(jù)、向前向后兼容等；
三來，順便分享一些好的思想、技巧和有用的工具、最佳實踐。
如果您有接口項目開發(fā)的需要，又剛好需要一個PHP接口框架，歡迎使用！我們也致力于將PhalApi維護成像恒星一樣：不斷更新，保持生氣；為接口負責，為開源負責！
3-2、加入我們
顯然，這只是一個開始，我們要走的路還很長。PhalApi是我們（開發(fā)團隊）的框架，更是我們（所有人）的框架。在一個人還年輕的時候，我覺得，就應該著手致力做一些對社會有意義的事情，一如開源。歡迎&期待你的加入！
在加入前，可先查看致框架貢獻者：加入PhalApi開源指南。至此，感謝以下貢獻者（排名不分先后）：
Aevit
dogstar
George
Scott
Summer
zz.guo（郭了個治浩）
小艾
大蟬
冰霜
火柴
黃苗筍
文振熙（喵了個咪）
愛編程的小逗比
... ...
PhalApi是開源框架，承諾永遠免費，使用GPL協(xié)議，更多請訪問許可。
此更新日記，主要是為了說明，我們一直在努力更新和維護。
