PhalApi（π框架） - V1.4.0
PhalApi辣苏，簡(jiǎn)稱π框架肝箱，是一個(gè)PHP輕量級(jí)開源接口框架哄褒，專注于接口開發(fā)，致力讓接口開發(fā)更簡(jiǎn)單狭园。它：
1读处、致力于快速、穩(wěn)定唱矛、持續(xù)交付有價(jià)值的接口服務(wù)、關(guān)注于測(cè)試驅(qū)動(dòng)開發(fā)井辜、領(lǐng)域驅(qū)動(dòng)設(shè)計(jì)绎谦、極限編程、敏捷開發(fā)
2粥脚、有眾多的擴(kuò)展類庫(kù)窃肠，與更多開源項(xiàng)目一起提供高效便捷的解決方案
3、支持HTTP刷允、SOAP和RPC協(xié)議冤留，可用于快速搭建微服務(wù)、RESTful接口或Web Services
PhalApi代碼開源树灶、產(chǎn)品開源纤怒、思想開源，請(qǐng)放心使用天通。更多請(qǐng)?jiān)L問PhalApi官網(wǎng)泊窘。再次感謝開源中國(guó)、各位貢獻(xiàn)者和同學(xué)像寒。
導(dǎo)讀
本文內(nèi)容主要分為三部分烘豹，即：
PART 1：安裝、在線體驗(yàn)與在線接口文檔
PART 2：快速開發(fā)诺祸、單元測(cè)試携悯、目錄結(jié)構(gòu)、SDK包和Library擴(kuò)展類庫(kù)
PART 3：背景回顧筷笨、貢獻(xiàn)者憔鬼、許可與更新日記
更多請(qǐng)?jiān)L問在線文檔。
1-1奥秆、安裝
請(qǐng)從release分支拉取發(fā)布版本的代碼
推薦部署于Linux服務(wù)器
建議PHP >= 5.3.3
將代碼下載解壓到服務(wù)器后逊彭，打開瀏覽器，訪問安裝向?qū)Вㄍ扑]使用nginx构订，并將根目錄設(shè)置為Public）：
http://localhost/PhalApi/Public/install/
訪問默認(rèn)接口服務(wù)侮叮，驗(yàn)證是否安裝成功：
http://localhost/PhalApi/Public/demo/
更多其他創(chuàng)建項(xiàng)目的方式，請(qǐng)?jiān)L問創(chuàng)建一個(gè)自己的項(xiàng)目悼瘾。
框架升級(jí)與框架共享
我們會(huì)盡最大的努力保證完美兼容性的升級(jí)囊榜。當(dāng)框架有新版本需要升級(jí)時(shí)审胸，只需要簡(jiǎn)單一步：更新替換./PhalApi/PhalApi核心框架目錄即可。
如果需要多個(gè)項(xiàng)目共享使用PhalApi框架卸勺，可以把./PhalApi/PhalApi移到任何位置砂沛，然后對(duì)應(yīng)修改./PhalApi/Public/init.php文件中引入路徑即可（但會(huì)導(dǎo)致部分腳本命令不可用）。如：
require_once API_ROOT . '/path/to/PhalApi/PhalApi.php';
1-2曙求、在線體驗(yàn)
默認(rèn)的接口服務(wù)：
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": ""
}
故意請(qǐng)求一個(gè)非法的服務(wù)：
http://demo.phalapi.net/?service=Demo.None
{
"ret": 400,
"data": [],
"msg": "非法請(qǐng)求：服務(wù)Demo.None不存在"
}
1-3悟狱、在線接口文檔（自動(dòng)生成）
按框架指定的格式完成接口代碼編寫后静浴，PhalApi會(huì)自動(dòng)生成在線接口列表文檔和在線接口詳情文檔，以方便客戶端實(shí)時(shí)查看最新的接口簽名和返回字段挤渐。
(1) 在線接口列表文檔
訪問對(duì)應(yīng)項(xiàng)目路徑下的listAllApis.php可查看此項(xiàng)目下全部的接口服務(wù)苹享，如訪問：
http://demo.phalapi.net/listAllApis.php
(2) 在線接口詳情文檔
訪問對(duì)應(yīng)項(xiàng)目路徑下的checkApiParams.php，并傳遞?service=xxx.xxx參數(shù)即可查看具體的接口文檔浴麻，如訪問：
http://demo.phalapi.net/checkApiParams.php?service=Default.Index
2-1得问、快速開發(fā)
(1) 編寫一個(gè)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，此示例中對(duì)應(yīng)的鏈接為：
http://localhost/Public/demo/?service=Welcome.Say
(3) 接口返回
結(jié)果默認(rèn)以JSON格式返回软免，即：
{"ret":200,"data":{"title":"Hello World!"},"msg":""}
(4) 運(yùn)行截圖
2-2宫纬、接口單元測(cè)試
不能被測(cè)試的代碼，不是好代碼或杠。
在使用此框架進(jìn)行接口開發(fā)時(shí)哪怔，我們強(qiáng)烈建議使用測(cè)試驅(qū)動(dòng)開發(fā)（TDD），以便于不斷積累形成接口測(cè)試體系向抢，保證接口向前向后兼容认境。例如對(duì)接口/?service=User.GetBaseInfo&userId=1進(jìn)行單元測(cè)試時(shí)，按：構(gòu)造-操作-檢驗(yàn)（BUILD-OPERATE-CHECK）模式挟鸠，即：
/**
* @group testGetBaseInfo
*/
public function testGetBaseInfo()
{
//Step 1. 構(gòu)建請(qǐng)求URL
$str = 'service=User.GetBaseInfo&userId=1';
//Step 2. 執(zhí)行請(qǐng)求（模擬接口請(qǐng)求）
$rs = PhalApi_Helper_TestRunner::go($url);
//Step 3. 驗(yàn)證
$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']);
}
運(yùn)行效果：
對(duì)于框架的核心代碼叉信，我們也一直堅(jiān)持著單元測(cè)試，其核心框架代碼的單元測(cè)試覆蓋率可高達(dá)96%以上艘希。
2-3硼身、主要目錄結(jié)構(gòu)
.
│
├── PhalApi? ? ? ? //PhalApi框架，后期可以整包升級(jí)
├── Library? ? ? ? //PhalApi擴(kuò)展類庫(kù)覆享，可根據(jù)需要自由添加擴(kuò)展
├── SDK? ? ? ? ? ? //PhalApi提供的SDK包佳遂，客戶可根據(jù)需要選用
│
│
├── Public? ? ? ? ? //對(duì)外訪問目錄，建議隱藏PHP實(shí)現(xiàn)
│? └── demo? ? ? ? //Demo服務(wù)訪問入口
│
│
├── Config? ? ? ? ? //項(xiàng)目接口公共配置撒顿，主要有：app.php, sys.php, dbs.php
├── Data? ? ? ? ? ? //項(xiàng)目接口公共數(shù)據(jù)
├── Language? ? ? ? //項(xiàng)目接口公共翻譯
├── Runtime? ? ? ? //項(xiàng)目接口運(yùn)行文件目錄丑罪，用于存放日記，可軟鏈到別的區(qū)
│
│
└── Demo? ? ? ? ? ? //應(yīng)用接口服務(wù)，名稱自取吩屹，可多組
├── Api? ? ? ? ? ? //接口響應(yīng)層
├── Domain? ? ? ? ? //接口領(lǐng)域?qū)?/p>
├── Model? ? ? ? ? //接口持久層
└── Tests? ? ? ? ? //接口單元測(cè)試
2-4跪另、基于接口查詢語言（ASL）的SDK包支持
目前已提供的SDK有：
C#版
JS版
Golang版
React-Native版
Python版
基于接口查詢語言，可用一句話來描述接口請(qǐng)求煤搜，如JAVA的請(qǐng)求示例：
PhalApiClientResponse response = PhalApiClient.create()
.withHost("http://demo.phalapi.net/")
.withService("Default.Index")? ? ? ? ? //接口服務(wù)
.withParams("username", "dogstar")? ? //接口參數(shù)
.withTimeout(3000)? ? ? ? ? ? ? ? ? ? //接口超時(shí)
.request();
2-5免绿、PhalApi-Library擴(kuò)展類庫(kù)
PhalApi框架擴(kuò)展類庫(kù)，致力于與開源項(xiàng)目一起提供高效便捷的解決方案擦盾，更多請(qǐng)查看：PhalApi-Library嘲驾。
3-1、背景回顧
過去十年厌衙，是互聯(lián)網(wǎng)時(shí)代距淫；如今的十年，是移動(dòng)時(shí)代婶希。
在iOS、Android蓬衡、Windows Phone喻杈、PC版、Web版等各種終端和各種垂直應(yīng)用不停更新迭代的大背景下狰晚，顯然很是需要一組乃至一系列穩(wěn)定的后臺(tái)接口支撐筒饰。接口，顯然是如此重要壁晒，正如Jaroslav Tulach在《軟件框架設(shè)計(jì)的藝術(shù)》一書中說的：API就如同恒星瓷们，一旦出現(xiàn)，便與我們永恒共存秒咐。
所以谬晕，這里希望通過提供一個(gè)快速可用的后臺(tái)接口開發(fā)框架，可以：
一來携取，支撐輕量級(jí)項(xiàng)目后臺(tái)接口的快速開發(fā)攒钳；
二來，闡明如何進(jìn)行接口開發(fā)雷滋、設(shè)計(jì)和維護(hù)不撑，以很好支持海量訪問、大數(shù)據(jù)晤斩、向前向后兼容等焕檬；
三來，順便分享一些好的思想澳泵、技巧和有用的工具实愚、最佳實(shí)踐。
如果您有接口項(xiàng)目開發(fā)的需要，又剛好需要一個(gè)PHP接口框架爆侣，歡迎使用萍程！我們也致力于將PhalApi維護(hù)成像恒星一樣：不斷更新，保持生氣兔仰；為接口負(fù)責(zé)茫负，為開源負(fù)責(zé)！
3-2乎赴、加入我們
顯然忍法，這只是一個(gè)開始，我們要走的路還很長(zhǎng)榕吼。PhalApi是我們（開發(fā)團(tuán)隊(duì)）的框架饿序，更是我們（所有人）的框架。在一個(gè)人還年輕的時(shí)候羹蚣，我覺得原探，就應(yīng)該著手致力做一些對(duì)社會(huì)有意義的事情，一如開源顽素。歡迎&期待你的加入咽弦！
在加入前，可先查看致框架貢獻(xiàn)者：加入PhalApi開源指南胁出。至此型型，感謝以下貢獻(xiàn)者（排名不分先后）：
Aevit
dogstar
George
Scott
Summer
zz.guo（郭了個(gè)治浩）
小艾
大蟬
冰霜
火柴
黃苗筍
文振熙（喵了個(gè)咪）
愛編程的小逗比
... ...
PhalApi是開源框架全蝶，承諾永遠(yuǎn)免費(fèi)闹蒜，使用GPL協(xié)議，更多請(qǐng)?jiān)L問許可抑淫。
此更新日記，主要是為了說明丈冬，我們一直在努力更新和維護(hù)嘱函。
