国际化高可用和自动生成文档

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 string $msg 待翻译的内容
 * @param 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 string title 标题
 * @return 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 欢迎大家的加入!