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

前言

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

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

附上:

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

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

1. 國(guó)際化

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

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

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

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

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

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

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

我們看看自帶的Demo例子里面有使用到第一個(gè),使用方法是這樣的

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

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

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

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

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

是不是感覺簡(jiǎn)單易用啊,那我們動(dòng)手實(shí)驗(yàn)一下我們把zh_cn/common.php加入一條對(duì)照

'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');會(huì)有什么結(jié)果呢

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

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

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

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

2. 文檔自動(dòng)生成

大家可以發(fā)現(xiàn)和index.php以及init.php并行的還有一個(gè)checkApiParams.php一直沒有用到,當(dāng)我們?cè)囍ピL問一下

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

它的機(jī)制是通過接口文件上的注釋生成的返回結(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)前時(shí)間戳
 */

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

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

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

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

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

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

3. 總結(jié)

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

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

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