phalapi-入門篇4(國際化高可用和自動生成文檔)

#phalapi-入門篇4(國際化高可用和自動生成文檔)#

##前言## 先在這裏感謝phalapi框架創始人@dogstar,爲咱們提供了這樣一個優秀的開源框架.

在本小節主要講解如何使用phalapi框架自帶的國際化和文檔自動生成,以及這樣作能夠的優勢和好處和能解決哪方面的問題

附上:

官網地址:http://www.phalapi.net/

開源中國Git地址:http://git.oschina.net/dogstar/PhalApi/tree/release

##1. 國際化##

說道國際化你們應該不陌生,對於顯示端(web,andorid,ios)來講就是對顯示的內容能夠任意切換語言,

但對於服務端來講就是對於返回值能夠任意切換語言,來達到給國外友人去使用這種業務,

雖說這種需求是少數,可是在框架內部有提供良好處理國際化這種業務的工具,讓咱們先看看具體是什麼樣子的

你們在init.php下面能夠看到這樣一句話

//翻譯語言包設定
SL('zh_cn');

這句話是指向了**/Language/zh_cn/common.php**文件,打開這個文件能夠發現這樣一組對照關係

return array(
	'Hi {name}, welcome to use PhalApi!' => '{name}您好，歡迎使用PhalApi！',
    'user not exists' => '用戶不存在',
);

咱們看看自帶的Demo例子裏面有使用到第一個,使用方法是這樣的

'content' => T('Hi {name}, welcome to use PhalApi!', array('name' => $this->username)),

你們是否是感受忽然之間發現了什麼,對的就是使用T方法咱們看一下T方法的註釋

/**
 * 快速翻譯
 * [@param](https://my.oschina.net/u/2303379) string $msg 待翻譯的內容
 * [@param](https://my.oschina.net/u/2303379) array $params 動態參數
 */

這裏的$msg 也就是在common.php中的key好比user not exists

$params參數是用來替換key裏面用{name}括弧括起來的參數的傳遞一個數組key就和括弧裏面的參數相同value就是你須要顯示的類容

是否是感受簡單易用啊,那咱們動手實驗一下咱們把zh_cn/common.php加入一條對照

'Login success'                      => '登陸成功',

在en/common.php也加入一條數據

'Login success'                      => 'Login success1',

咱們修改Default.index接口以下

public function index() {
    return T('Login success');
}

咱們看能獲得什麼結果

那咱們把init.php中的**SL('zh_cn');改爲SL('en');**會有什麼結果呢

就能獲得咱們在en/common.php中寫下的Login success1這樣就能夠輕易的切換返回語言從而實現國際化

可是它帶來的好處不只如此,還有易於修改和高可用這兩點好處

先說第一點易於修改:我在原來剛剛開始作項目的時候每一個接口裏面返回值全是寫死的,好比用戶不存在這種等等的錯誤返回,當要修改的時候咱們面臨了一個問題全局替換,這樣是很不可取的因此後面就統一成了一個統一的文件來存放返回結果,當咱們須要把用戶不存在修改爲請確認用戶的真實性這樣的業務的時候,咱們只須要修改一個統一的文件

好處之二就是高可用,高可用的表現又有兩種一種是上面所說的項目內的複用,第二種就是新項目的複用,當你開始一個新項目的時候其實已經有不少返回是通用的了,那麼你就能夠直接使用或者是拷貝過來,不少重複的工做量就能夠省去

##2. 文檔自動生成##

你們能夠發現和index.php以及init.php並行的還有一個checkApiParams.php一直沒有用到,當咱們試着去訪問一下

看到了這樣的頁面,訪問這個文件的時候和訪問接口同樣的默認訪問了Default.index的文檔頁面也有說明

它的機制是經過接口文件上的註釋生成的返回結果

/**
 * 默認接口服務
 * [@return](https://my.oschina.net/u/556800) string title 標題
 * [@return](https://my.oschina.net/u/556800) string content 內容
 * @return string version 版本，格式：X.X.X
 * @return int time 當前時間戳
 */

剖析一下**@return string title** 標題 第一個是必要參數**@return**後面接着一個空格(千萬不能多空格不然會失效)返回類型在接着一個空格返回名稱

請求參數會按照接口文檔中的getRules生成一些限定條件會自動生成說明須要加上**'desc' => 說明就能生成**你們能夠試着訪問一下user.getBaseInfo接口文檔就能看到請求參數是有說明的

使用自動生成文檔的好處在於會時時更新沒必要在開發過程當中要取維護接口文檔而煩惱,還有一點就是容錯高由於是事實的因此不會出現請求參數接口和文檔不一樣步的狀況因此很推薦使用,可是對於返回結果來講須要手工維護不過也比維護文檔來的方便,並且不用下載網上直接看,

其實你們看到/Public/demo/listAllApis.php裏面這個至關於一個導航訪問http://localhost/Public/demo/listAllApis.php能夠看到如下結果

對於這個文件能夠自定義成本身的文檔入口文件,能夠本身劃分模塊而後把接口文檔的地址寫上去名稱和說明這樣也不須要手動在url裏面去輸入接口名稱了

注:在這裏有一個坑,若是要使用自動生成文檔的話須要關掉一些PHP緩存拓展,由於這些拓展在緩存的時候會去除掉註釋以後在緩存會致使返回結果沒法生成,好比opcache.xcache這類的拓展都會致使此類問題

##3. 總結##

本小節主要講解了一下如何使用國際化使用的好處,以及運用官方工具生成及時文檔,在下一章節咱們會講解激動人心的數據庫操做但願你們能持續關注!

注:筆者能力有限有說的不對的地方但願你們可以指出,也但願多多交流!

官網QQ交流羣:421032344 歡迎你們的加入!