一个真正的强者，不是摆平了多少人，而是他能帮助到多少人。  --开源中国源创会分享广州站 @海洋之心-悟空  

1.11.1 模拟开发：获取开源中国用户信息接口

首次使用此接口开发框架时，可以先查看此开发示例。

假设，我们需要为开源中国打造一个平放平台，其中有一个接口是可以根据用户ID来获取用户的基本信息。

本文，就以模拟获取开源中国用户信息接口开发（即：从数据库获取用户的基本信息并以JSON格式返回给客户端）为例，简明的接口开发中的流程，以及 用到的基本功能和操作，主要包括有：统一入口文件、参数规则配置、接口层/领域层/模型持久层、日记纪录、数据库操作、配置读取、国际化翻译等。

以给大家一个感观的认识。

最终接口的调用与返回结果如下：

//接口请求格式http://dev.phalapi.com/demo/?service=User.GetBaseInfo&userId=帐号ID//返回结果格式{    "ret": 200,    "data": {                   "code": 0,    //状态码，0表示正常获取，1表示用户不存在        "msg": "",        "info": {      //用户信息            "id": "1",    //用户ID            "name": "dogstar",   //帐号            "from": "oschina"   //来源        }    },    "msg": ""}

1.11.2 开发流程

(1) 统一入口文件

为了更好保护我们的项目代码，建议将接口的访问路径设置在：./PhalApi/Pubic目录，并且各套接口（如按版本分：v1/v2/v3等 等；按不同终端分：ios/android/pc等）各自独立入口。所以本示例中将./PhalApi/Pubic/demo/index.php下。

参数入口文件的写法，我们可以快速得到基本的入口文件如下：

// $ vim ./Public/demo/index.php 
    loader->addDirs('Demo');/** ---------------- 响应接口请求 ---------------- **/$server = new PhalApi();$rs = $server->response();$rs->output();

此外，我们还需要一个公共的初始化文件：

//$ vim ./Public/init.php 
    loader = $loader;//配置DI()->config = new PhalApi_Config_File(API_ROOT . '/Config');//参数请求DI()->request = new PhalApi_Request();//日记纪录DI()->logger = new PhalApi_Logger_File(API_ROOT . '/Runtime',    PhalApi_Logger::LOG_LEVEL_DEBUG | PhalApi_Logger::LOG_LEVEL_INFO | PhalApi_Logger::LOG_LEVEL_ERROR);//数据操作 - 基于NotORMDI()->notorm = function() {    return new PhalApi_DB_NotORM(DI()->config->get('dbs'), false);};

(2)TDD测试驱动开发

遵循最佳实践，我们在编写代码前先编写单元测试。但同时为了减少编写测试代码的痛苦，我们可以先定义接口函数签名，再通过脚本自动生成测试代码骨架来提高我们的开发效率。

//$vim ./Demo/Api/User.php
    

通过脚本生成测试骨架：

$ mkdir -p ./Demo/Tests/Api/$ cd ./Demo/Tests/Api$ php ../../../PhalApi/build_phpunit_test_tpl.php ../../Api/User.php Api_User ./../test_env.php

然后，根据/Public/demo/index.php入口文件，也搭建一个测试环境的入口文件：

vim ./Demo/Tests/test_env.php

修正一下Api_Examples_User_Test.php里，测试环境test_env.php的包含路径：

//手动调用test_env.php的路径require_once dirname(__FILE__) . '/../test_env.php';

并且，修改测试，以符合我们通过userId=1获取基本信息（名字为dogstar，来源为oschina）：

//$vim ./Demo/Tests/Api/Api_User_Test.php    /**     * @group testGetBaseInfo     */    public function testGetBaseInfo()    {        $str = 'service=User.GetBaseInfo&userId=1';        parse_str($str, $params);        DI()->request = new PhalApi_Request($params);        $api = new Api_User();         //自己进行初始化        $api->init();        $rs = $api->getBaseInfo();        $this->assertNotEmpty($rs);        $this->assertArrayHasKey('code', $rs);        $this->assertArrayHasKey('msg', $rs);        $this->assertArrayHasKey('info', $rs);        $this->assertEquals(0, $rs['code']);        $this->assertEquals('dogstar', $rs['info']['name']);        $this->assertEquals('oschina', $rs['info']['from']);    }

此时，单元测试是预期失败的：

$ phpunit ./Api_User_Test.php PHPUnit 4.3.4 by Sebastian Bergmann.FTime: 3 ms, Memory: 5.25MbThere was 1 failure:1) PhpUnderControl_ApiUser_Test::testGetBaseInfoFailed asserting that a NULL is not empty.FAILURES!Tests: 1, Assertions: 1, Failures: 1.

(3)Api接口层

此接口层，主要是负责响应客户端的请求，调用需要的领域层进行必要的服务功能提供。

配置参数规则

为了获取到用户ID，我们可以在getRules()函数里面定义参数规则，以便框架自动帮我们过滤获取需要的参数。

温馨提示：

接口层的全部类成员函数都应以小写开头。

但对外，函数首字母不区分大小写，因为框架会将请求的函数强制转换成小写再执行。

原因在于：

1、我们坚持驼峰法的代码风格；

2、对外界我们可以统一使用大写来提供服务名称，如：User.Login，这样更显专业。

//$vim ./Demo/Api/User.php
     array(                'userId' => array('name' => 'userId', 'type' => 'int', 'min' => 1, 'require' => true),            ),        );    }    //...

如上，我们就定义了getBaseInfo接口中的userId参数，名字也为userId，整型，最小值为1，必须。

接口实现

//$vim ./Demo/Api/User.php    public function getBaseInfo()    {        $rs = array('code' => 0, 'msg' => '', 'info' => array());        $domain = new Domain_User();        $info = $domain->getBaseInfo($this->userId);        if (empty($info)) {            DI()->logger->debug('user not found', $this->userId);            $rs['code'] = 1;            $rs['msg'] = T('user not exists');            return $rs;        }        $rs['info'] = $info;        return $rs;    }

(4)Domain领域层

领域层主要是关注复杂业务的处理，以及缓存的处理、耗时操作后台异步处理等，并调用Model持久层获取需要的数据。因此，是Api与Model层之间的桥梁。

在此示例中，我们只需要简单地调用Model层获取用户的信息即可，再加强一下用户ID的合法性判断。

//$ vim ./Demo/Domain/User.php 
    getByUserId($userId);        return $rs;    }}

(5)Model持久层

此一层主要关注数据从持久存储的获取，特别是针对数据库的操作，但不排除其他媒介，如文件、缓存等。

首先，先准备一下我们需要的表和数据：

CREATE TABLE `phalapi_test`.`tbl_user` (  `id` INT NOT NULL,  `name` VARCHAR(45) NULL,  `from` VARCHAR(45) NULL,  PRIMARY KEY (`id`));INSERT INTO `phalapi_test`.`tbl_user` (`id`, `name`, `from`) VALUES ('1', 'dogstar', 'oschina');

然后，编写需要的Model代码，即利用NotORm实现对数据的操作：

//$ vim ./Demo/Model/User.php 
    notorm->user->select('*')->where('id = ?', $userId)->fetch();    }}

(6)单元测试通过啦！

在完成上面简单的开发后，我们即可以实现接口的开发，运行一下刚才的单元测试，完美通过！

$ phpunit ./Api_User_Test.php PHPUnit 4.3.4 by Sebastian Bergmann.SELECT * FROM tbl_user WHERE (id = ?); -- 1.SELECT * FROM tbl_user WHERE (id = ?); -- 1
    Time: 34 ms, Memory: 6.50MbOK (2 tests, 7 assertions)

在单元测试的保证下，我们便可以放心大胆地将我们的代码发布到外网，提供给更多的开发者，和终端用户使用。

(7)数据库配置

因为是单元测试，所以我们配置搭建了新的一个测试环境，特别对于数据库的配置，如下：

//$ vim ./Config/dbs.php
     array(        'db_demo' => array(            'host'      => '192.168.0.104',         //数据库域名            'name'      => 'phalapi_test',          //数据库名字            'user'      => 'root',                  //数据库用户名            'password'  => '123456',                //数据库密码            'port'      => '3306',                  //数据库端口        ),    ),    /**     * 自定义路由表     */    'tables' => array(        '__default__' => array(            'prefix' => 'tbl_',            'key' => 'id',            'map' => array(                array('db' => 'db_demo'),            ),        ),    ),);

温馨提示：

为了方便在单元测试时进行调试，和查看日记，对于全部查询、执行的SQL语句都会显示出来，全部的日记改用控制台输出。

(8)最终接口调用

接口调用的链接，这时已经相当明了了，即：域名 + 路径（/demo） + 参数（可从单元测试那直接获取）

如本示例的是：

http://dev.phalapi.com/demo/?service=User.GetBaseInfo&userId=1

返回的结果是：

{    "ret": 200,    "data": {        "code": 0,        "msg": "",        "info": {            "id": "1",            "name": "dogstar",            "from": "oschina"        }    },    "msg": ""}

截图效果：

 

温馨提示：

如果提示日记写入失败，请确保./Runtime目录具有写入权限，即0777。

1.11.3 更多简明的使用

(1)日记纪录

当我们访问一个不存在的用户时，将会触发日记纪录：

DI()->logger->debug('user not found', $this->userId);

如访问：

http://dev.phalapi.com/demo/?service=User.GetBaseInfo&userId=2

然后，可以在Runtime下看到按天分目录的日记：

$ tailf ./Runtime/log/201501/20150128.log 2015-01-28 00:37:34|DEBUG|user not found|2

温馨提示：

外网环境上，请把Runtime目录软链到磁盘空间很大的路径。

(2)国际化翻译

当需要翻译时，可以使用人性化的函数T()，如：

$rs['msg'] = T('user not exists');

对应地需要补充翻译的内容：

//$ vim ./Language/zh_cn/common.php     'user not exists' => '用户不存在',

还是以上面的用户不存在为例，看下运行的截图效果：

(3)配置读取

配置的读取，使用方便，直接通过以下方式便可以获取，以点号分割：

DI()->config->get('dbs')

第一段，必须为文件名，后面的为用点号相连的数组下标，不限级。

(4)[酷！]接口参数在线查询

为了方便客户端实时查看最新的接口参数，这里提供了一个快速的在线工具：

http://dev.phalapi.com/demo/checkApiParams.php?service=User.GetBaseInfo

用浏览器打开后，即可以看到最新的接口参数说明， 不需要后台接口开发人员编写文档维护，直接从代码中生成参数报表：

1.11.4 Demo相关代码文件

从上面可以得到，此示例相关的代码如下：

Demo$ tree.├── Api│   ├── Default.php│   └── User.php├── Domain│   └── User.php├── Model│   └── User.php└── Tests    ├── Api    │   ├── Api_Default_Test.php    │   └── Api_User_Test.php    └── test_env.php