PhalApi（π框架） - V1.4.0

PhalApi，簡稱π框架，是一個PHP輕量級開源介面框架，專注於介面開發，致力讓介面開發更簡單。它：

1、致力於快速、穩定、持續交付有價值的介面服務、關注於測試驅動開發、領域驅動設計、極限程式設計、敏捷開發

2、有眾多的擴充套件類庫，與更多開源專案一起提供高效便捷的解決方案

3、支援HTTP、SOAP和RPC協議，可用於快速搭建微服務、RESTful介面或Web Services

PhalApi程式碼開源、產品開源、思想開源，請放心使用。更多請訪問PhalApi官網。再次感謝開源中國、各位貢獻者和同學。

導讀

本文內容主要分為三部分，即：

PART 1：安裝、線上體驗與線上介面文件

PART 2：快速開發、單元測試、目錄結構、SDK包和Library擴充套件類庫

PART 3：背景回顧、貢獻者、許可與更新日記

更多請訪問線上文件。

1-1、安裝

請從release分支拉取釋出版本的程式碼

推薦部署於Linux伺服器

建議PHP >= 5.3.3

將程式碼下載解壓到伺服器後，開啟瀏覽器，訪問安裝嚮導（推薦使用nginx，並將根目錄設定為Public）：

http://localhost/PhalApi/Public/install/

訪問預設介面服務，驗證是否安裝成功：

http://localhost/PhalApi/Public/demo/

更多其他建立專案的方式，請訪問建立一個自己的專案。

框架升級與框架共享

我們會盡最大的努力保證完美相容性的升級。當框架有新版本需要升級時，只需要簡單一步：更新替換./PhalApi/PhalApi核心框架目錄即可。

如果需要多個專案共享使用PhalApi框架，可以把./PhalApi/PhalApi移到任何位置，然後對應修改./PhalApi/Public/init.php檔案中引入路徑即可（但會導致部分指令碼命令不可用）。如：

require_once API_ROOT . '/path/to/PhalApi/PhalApi.php';

1-2、線上體驗

預設的介面服務：

http://demo.phalapi.net/

帶引數的示例介面：

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引數即可檢視具體的介面文件，如訪問：

http://demo.phalapi.net/checkApiParams.php?service=Default.Index

2-1、快速開發

(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、介面單元測試

不能被測試的程式碼，不是好程式碼。

在使用此框架進行介面開發時，我們強烈建議使用測試驅動開發（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. 執行請求（模擬介面請求）

$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擴充套件類庫，可根據需要自由新增擴充套件

├── SDK            //PhalApi提供的SDK包，客戶可根據需要選用

│

│

├── Public          //對外訪問目錄，建議隱藏PHP實現

│  └── demo        //Demo服務訪問入口

│

│

├── Config          //專案介面公共配置，主要有：app.php, sys.php, dbs.php

├── Data            //專案介面公共資料

├── Language        //專案介面公共翻譯

├── Runtime        //專案介面執行檔案目錄，用於存放日記，可軟鏈到別的區

│

│

└── Demo            //應用介面服務，名稱自取，可多組

├── Api            //介面響應層

├── Domain          //介面領域層

├── Model          //介面持久層

└── Tests          //介面單元測試

以下為一示例目錄結構圖解：

2-4、基於介面查詢語言（ASL）的SDK包支援

目前已提供的SDK有：

JAVA版

Objective-c版

PHP版

C#版

JS版

Golang版

React-Native版

Ruby版

Python版

基於介面查詢語言，可用一句話來描述介面請求，如JAVA的請求示例：

PhalApiClientResponse response = PhalApiClient.create()

.withHost("http://demo.phalapi.net/")

.withService("Default.Index")          //介面服務

.withParams("username", "dogstar")    //介面引數

.withTimeout(3000)                    //介面超時

.request();

2-5、PhalApi-Library擴充套件類庫

PhalApi框架擴充套件類庫，致力於與開源專案一起提供高效便捷的解決方案，更多請檢視：PhalApi-Library。

3-1、背景回顧

過去十年，是網際網路時代；如今的十年，是移動時代。

在iOS、Android、Windows Phone、PC版、Web版等各種終端和各種垂直應用不停更新迭代的大背景下，顯然很是需要一組乃至一系列穩定的後臺介面支撐。介面，顯然是如此重要，正如Jaroslav Tulach在《軟體框架設計的藝術》一書中說的：API就如同恆星，一旦出現，便與我們永恆共存。

所以，這裡希望通過提供一個快速可用的後臺介面開發框架，可以：

一來，支撐輕量級專案後臺介面的快速開發；

二來，闡明如何進行介面開發、設計和維護，以很好支援海量訪問、大資料、向前向後相容等；

三來，順便分享一些好的思想、技巧和有用的工具、最佳實踐。

如果您有介面專案開發的需要，又剛好需要一個PHP介面框架，歡迎使用！我們也致力於將PhalApi維護成像恆星一樣：不斷更新，保持生氣；為介面負責，為開源負責！

3-2、加入我們

顯然，這只是一個開始，我們要走的路還很長。PhalApi是我們（開發團隊）的框架，更是我們（所有人）的框架。在一個人還年輕的時候，我覺得，就應該著手致力做一些對社會有意義的事情，一如開源。歡迎&期待你的加入！

在加入前，可先檢視致框架貢獻者：加入PhalApi開源指南。至此，感謝以下貢獻者（排名不分先後）：

Aevit

dogstar

George

Scott

Summer

zz.guo（郭了個治浩）

小艾

大蟬

冰霜

火柴

黃苗筍

文振熙（喵了個咪）

愛程式設計的小逗比

... ...

3-3、許可

PhalApi是開源框架，承諾永遠免費，使用GPL協議，更多請訪問許可。

3-4、更新日記

此更新日記，主要是為了說明，我們一直在努力更新和維護。