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

前言

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

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

附上:

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

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

1. 國(guó)際化

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

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

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

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

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

這句話是指向了/Language/zh_cn/common.php文件,打開(kāi)這個(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)),

大家是不是感覺(jué)突然之間發(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ù)是用來(lái)替換key里面用{name}括弧括起來(lái)的參數(shù)的傳遞一個(gè)數(shù)組key就和括弧里面的參數(shù)相同value就是你需要顯示的類(lèi)容

是不是感覺(jué)簡(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中寫(xiě)下的Login success1這樣就可以輕易的切換返回語(yǔ)言從而實(shí)現(xiàn)國(guó)際化

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

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

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

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

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

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

它的機(jī)制是通過(guò)接口文件上的注釋生成的返回結(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è)空格(千萬(wàn)不能多空格否則會(huì)失效)返回類(lèi)型在接著一個(gè)空格返回名稱(chēng)

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

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

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

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

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

3. 總結(jié)

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

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

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