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

前言

先在這里感謝phalapi框架創(chuàng)始人@dogstar,為我們提供了這樣一個優(yōu)秀的開源框架.

在本小節(jié)主要講解如何使用phalapi框架自帶的國際化和文檔自動生成,以及這樣做可以的優(yōu)點和好處和能解決哪方面的問題

附上:

官網(wǎng)地址:http://www.phalapi.net/

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

1. 國際化

說道國際化大家應(yīng)該不陌生,對于顯示端(web,andorid,ios)來說就是對顯示的內(nèi)容可以任意切換語言,

但對于服務(wù)端來說就是對于返回值可以任意切換語言,來達(dá)到給國外友人去使用這種業(yè)務(wù),

雖然說這種需求是少數(shù),但是在框架內(nèi)部有提供良好處理國際化這種業(yè)務(wù)的工具,讓我們先看看具體是什么樣子的

大家在init.php下面可以看到這樣一句話

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

這句話是指向了/Language/zh_cn/common.php文件,打開這個文件可以發(fā)現(xiàn)這樣一組對照關(guān)系

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)),

大家是不是感覺突然之間發(fā)現(xiàn)了什么,對的就是使用T方法我們看一下T方法的注釋

/**
 * 快速翻譯
 * @param string $msg 待翻譯的內(nèi)容
 * @param array $params 動態(tài)參數(shù)
 */

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

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

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

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

在en/common.php也加入一條數(shù)據(jù)

'Login success'                      => 'Login success1',

我們修改Default.index接口如下

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

我們看能得到什么結(jié)果

那我們把init.php中的SL('zh_cn');改成SL('en');會有什么結(jié)果呢

就能得到我們在en/common.php中寫下的Login success1這樣就可以輕易的切換返回語言從而實現(xiàn)國際化

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

先說第一點易于修改:我在原來剛剛開始做項目的時候每個接口里面返回值全是寫死的,比如用戶不存在這種等等的錯誤返回,當(dāng)要修改的時候我們面臨了一個問題全局替換,這樣是很不可取的所以后面就統(tǒng)一成了一個統(tǒng)一的文件來存放返回結(jié)果,當(dāng)我們需要把用戶不存在修改成請確認(rèn)用戶的真實性這樣的業(yè)務(wù)的時候,我們只需要修改一個統(tǒng)一的文件

好處之二就是高可用,高可用的表現(xiàn)又有兩種一種是上面所說的項目內(nèi)的復(fù)用,第二種就是新項目的復(fù)用,當(dāng)你開始一個新項目的時候其實已經(jīng)有很多返回是通用的了,那么你就可以直接使用或者是拷貝過來,很多重復(fù)的工作量就可以省去

2. 文檔自動生成

大家可以發(fā)現(xiàn)和index.php以及init.php并行的還有一個checkApiParams.php一直沒有用到,當(dāng)我們試著去訪問一下

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

它的機制是通過接口文件上的注釋生成的返回結(jié)果

/**
 * 默認(rèn)接口服務(wù)
 * @return string title 標(biāo)題
 * @return string content 內(nèi)容
 * @return string version 版本，格式：X.X.X
 * @return int time 當(dāng)前時間戳
 */

剖析一下@return string title 標(biāo)題 第一個是必要參數(shù)@return后面接著一個空格(千萬不能多空格否則會失效)返回類型在接著一個空格返回名稱

請求參數(shù)會按照接口文檔中的getRules生成一些限定條件會自動生成說明需要加上'desc' => 說明就能生成大家可以試著訪問一下user.getBaseInfo接口文檔就能看到請求參數(shù)是有說明的

使用自動生成文檔的好處在于會時時更新不必在開發(fā)過程中要取維護接口文檔而煩惱,還有一點就是容錯高因為是事實的所以不會出現(xiàn)請求參數(shù)接口和文檔不同步的情況所以很推薦使用,但是對于返回結(jié)果來說需要手工維護不過也比維護文檔來的方便,而且不用下載網(wǎng)上直接看,

其實大家看到/Public/demo/listAllApis.php里面這個相當(dāng)于一個導(dǎo)航訪問http://localhost/Public/demo/listAllApis.php可以看到以下結(jié)果

對于這個文件可以自定義成自己的文檔入口文件,可以自己劃分模塊然后把接口文檔的地址寫上去名稱和說明這樣也不需要手動在url里面去輸入接口名稱了

注:在這里有一個坑,如果要使用自動生成文檔的話需要關(guān)掉一些PHP緩存拓展,因為這些拓展在緩存的時候會去除掉注釋之后在緩存會導(dǎo)致返回結(jié)果無法生成,比如opcache.xcache這類的拓展都會導(dǎo)致此類問題

3. 總結(jié)

本小節(jié)主要講解了一下如何使用國際化使用的好處,以及運用官方工具生成及時文檔,在下一章節(jié)我們會講解激動人心的數(shù)據(jù)庫操作希望大家能持續(xù)關(guān)注!

注:筆者能力有限有說的不對的地方希望大家能夠指出,也希望多多交流!

官網(wǎng)QQ交流群:421032344 歡迎大家的加入!