_Give it some time, everything will be okay. -- 《那些年我们疯狂的青春/青春洋溢色彩/This Youth is Crazy》_
## 4.3.1 模拟的业务场景
假设我们需要为“奔跑吧兄弟”综艺节目开发一套手机App的投票接口，以供用户在观看电视的同时，可以进行投票活动参与互动。
下面将以此模拟的业务场景，提供一个接口开发实战的过程。
## 4.3.2 源代码下载
[PhalApi-Demo-Vote](http://git.oschina.net/dogstar/PhalApi-Demo-Vote)
## 4.3.3 接口总列表
以下是我们根据业务需求整理出来的接口：
+ 1、用户可以通过微信、QQ、新浪微博等渠道进行第三方登录
+ 2、用户可以创建团队进行参赛，但队名不能重复
+ 3、用户可以对已参赛的团队进行投票，且每个用户每天投票最多不能超过3次，支持可配置
+ 4、获取已参赛团队的得票排行榜
## 4.3.4 主要涉及技术功能点
+ 1、使用User扩展类库实现第三方登录操作
+ 2、使用缓存存放用户每天投票的次数（为方便起见，使用文件缓存，不落地）
+ 3、对接口进行签名验证（为方便起见，固定sign签名）
+ 4、数据库的基本操作
+ 5、自动化脚本的使用
## 4.3.4 快速开发流程
（题外音：整个示例的开发，我个人在单元测试驱动开发下，只用了两个多小时，其中还包括对模板场景的业务构思、建表、编写单元测试代码等）。
###(1)创建项目和部署环境
把PhalApi最新的框架代码下载后，并将User扩展类库按文档说明配置后，将项目部署到了以下接口域名：
```
http://api.vote.phalapi.com
```
测试一下：
```javascript
http://api.vote.phalapi.com/vote/?sign=phalapi
//返回
{
"ret": 200,
"data": {
"title": "Hello World!",
"content": "PHPer您好，欢迎使用PhalApi！",
"version": "1.1.4",
"time": 1431796924
},
"msg": ""
}
```
Good! 下面是简明的开发过程。
###(2)单元测试驱动开发
在定好接口后：
```javascript
<?php
class Api_Act extends PhalApi_Api {
public function joinIn() {
}
public function showList() {
}
public function vote() {
}
}
```
便可使用脚本，快速生成单元测试的骨架代码：
```javascript
$ cd ./Vote/Tests/Api
$ phalapi_buildtests ../../Api/Act.php Api_Act ../test_env.php > Api_Act_Test.php
```
###(3)快速开发
开发过程此处略，但在单元测试驱动的引导下，很快就产出了以下高质量的代码：
```javascript
.
├── Api
│ ├── Act.php
│ └── Default.php
├── Common
│ └── SignFilter.php
├── Domain
│ ├── Team.php
│ └── Vote.php
├── Model
│ ├── Team.php
│ ├── UserVoteRecord.php
│ └── Vote.php
└── Tests
├── Api
│ ├── Api_Act_Test.php
│ └── Api_Default_Test.php
├── Domain
├── Model
├── phpunit.xml
└── test_env.php
```
###(4)单元测试全部通过了！
为了方便大家查看，已省略了部分的调试内容，但保留了测试过程中全部执行的SQL语句，如下：
```javascript
$ phpunit ./Api_Act_Test.php
PHPUnit 4.3.4 by Sebastian Bergmann.
[1 - 0.06911s]DELETE FROM phalapi_team WHERE (team_name = 'test team name');<br>
[2 - 0.06487s]SELECT expires_time FROM phalapi_user_session_1 WHERE (user_id = '1') AND (token = '193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731');<br>
[3 - 0.06553s]SELECT COUNT(id) FROM phalapi_team WHERE (team_name = 'test team name');<br>
[4 - 0.0653s]INSERT INTO phalapi_team (team_name) VALUES ('test team name');<br>
[5 - 0.0699s]SELECT expires_time FROM phalapi_user_session_1 WHERE (user_id = '1') AND (token = '193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731');<br>
[6 - 0.06555s]SELECT COUNT(id) FROM phalapi_team WHERE (team_name = 'test team name');<br>
[9 - 0.06778s]SELECT expires_time FROM phalapi_user_session_1 WHERE (user_id = '1') AND (token = '193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731');<br>
[10 - 0.06603s]SELECT COUNT(id) FROM phalapi_team WHERE (id = 3);<br>
[11 - 0.06825s]SELECT vote_num FROM phalapi_vote WHERE (team_id = 3) LIMIT 1;<br>
[12 - 0.07374s]UPDATE phalapi_vote SET team_id = 3, vote_num = 22 WHERE (team_id = 3);<br>
[13 - 0.07012s]SELECT expires_time FROM phalapi_user_session_1 WHERE (user_id = '1') AND (token = '193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731');<br>
[14 - 0.06682s]SELECT COUNT(id) FROM phalapi_team WHERE (id = 3);<br>
[15 - 0.07433s]SELECT vote_num FROM phalapi_vote WHERE (team_id = 3) LIMIT 1;<br>
[16 - 0.07283s]UPDATE phalapi_vote SET team_id = 3, vote_num = 23 WHERE (team_id = 3);<br>
[17 - 0.07307s]SELECT expires_time FROM phalapi_user_session_1 WHERE (user_id = '1') AND (token = '193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731');<br>
[18 - 0.07501s]SELECT COUNT(id) FROM phalapi_team WHERE (id = 3);<br>
[19 - 0.07135s]SELECT vote_num FROM phalapi_vote WHERE (team_id = 3) LIMIT 1;<br>
[20 - 0.07653s]UPDATE phalapi_vote SET team_id = 3, vote_num = 24 WHERE (team_id = 3);<br>
[21 - 0.07215s]SELECT expires_time FROM phalapi_user_session_1 WHERE (user_id = '1') AND (token = '193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731');<br>
[22 - 0.06722s]SELECT COUNT(id) FROM phalapi_team WHERE (id = 3);<br>
[23 - 0.06506s]SELECT expires_time FROM phalapi_user_session_1 WHERE (user_id = '1') AND (token = '193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731');<br>
[24 - 0.06732s]SELECT COUNT(id) FROM phalapi_team WHERE (id = 404);<br>
Time: 1.97 seconds, Memory: 7.00Mb
OK (4 tests, 42 assertions)
```
###(5)运行效果 - Part 1
在我们通过第三方登录后，我们就可以这样进行接口操作了。
首先，让我们添加两个参赛团队：
```javascript
//奔跑吧兄弟（蓝队）
http://api.vote.phalapi.com/vote/?sign=phalapi&service=Act.JoinIn&team_name=%E5%A5%94%E8%B7%91%E5%90%A7%E5%85%84%E5%BC%9F%EF%BC%88%E8%93%9D%E9%98%9F%EF%BC%89&token=193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731&user_id=1
//返回
{
"ret": 200,
"data": {
"code": 0,
"team_id": "5"
},
"msg": ""
}
//奔跑吧兄弟（红队）
http://api.vote.phalapi.com/vote/?sign=phalapi&service=Act.JoinIn&team_name=%E5%A5%94%E8%B7%91%E5%90%A7%E5%85%84%E5%BC%9F%EF%BC%88%E7%BA%A2%E9%98%9F%EF%BC%89&token=193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731&user_id=1
//返回
{
"ret": 200,
"data": {
"code": 0,
"team_id": "6"
},
"msg": ""
}
```
然后，让我们进行疯狂地投票：
```javascript
//第一次投票
http://api.vote.phalapi.com/vote/?sign=phalapi&service=Act.Vote&team_id=5&token=193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731&user_id=1
//返回
{"ret":200,"data":{"code":0,"vote_num":1},"msg":""}
//第二次投票
http://api.vote.phalapi.com/vote/?sign=phalapi&service=Act.Vote&team_id=5&token=193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731&user_id=1
//返回
{"ret":200,"data":{"code":0,"vote_num":2},"msg":""}
//第三次投票
http://api.vote.phalapi.com/vote/?sign=phalapi&service=Act.Vote&team_id=5&token=193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731&user_id=1
//返回
{"ret":200,"data":{"code":0,"vote_num":3},"msg":""}
//第四次投票
http://api.vote.phalapi.com/vote/?sign=phalapi&service=Act.Vote&team_id=5&token=193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731&user_id=1
//返回 - 注意此返回！
{"ret":200,"data":{"code":2,"vote_num":0},"msg":""}
```
最后，看一下排行榜：
```javascript
http://api.vote.phalapi.com/vote/?sign=phalapi&service=Act.ShowList&token=193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731&user_id=1
//返回
{
"ret": 200,
"data": {
"code": 0,
"teams": [
{
"id": 5,
"team_name": "奔跑吧兄弟（蓝队）",
"vote_num": 3
},
{
"id": 6,
"team_name": "奔跑吧兄弟（红队）",
"vote_num": 0
}
]
},
"msg": ""
}
```
至此，我们已经可以把接口交付给客户端同学使用啦！
当然，我们还需要稍微整理输出WIKI文档~~~
部分接口返回的结果可能与你实际看到的不一样，因为数据会在变化而且有单元测试的测试数据。
###(6)运行效果 - Part 2
接口服务，不仅仅需要提供正常的业务功能，还需要考虑到各种客户端使用的情况，包括非法的请求，或者不合的调用，比如防刷票。
这一部分，主要展示接口在各种异常情况下的响应能力。
####签名失败
```javascript
http://api.vote.phalapi.com/vote/?sign=XXX&service=Act.JoinIn&team_name=%E5%A5%94%E8%B7%91%E5%90%A7%E5%85%84%E5%BC%9F%EF%BC%88%E7%BA%A2%E9%98%9F%EF%BC%89&token=193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731&user_id=1
//返回
{
"ret": 400,
"data": [
],
"msg": "非法请求：wrong sign"
}
```
####无登录态
```javascript
http://api.vote.phalapi.com/vote/?sign=phalapi&service=Act.JoinIn&team_name=%E5%A5%94%E8%B7%91%E5%90%A7%E5%85%84%E5%BC%9F%EF%BC%88%E7%BA%A2%E9%98%9F%EF%BC%89&token=XXX&user_id=1
//返回
{
"ret": 401,
"data": [
],
"msg": "非法请求：user need to login again"
}
```
####重复参赛
```javascript
http://api.vote.phalapi.com/vote/?sign=phalapi&service=Act.JoinIn&team_name=%E5%A5%94%E8%B7%91%E5%90%A7%E5%85%84%E5%BC%9F%EF%BC%88%E7%BA%A2%E9%98%9F%EF%BC%89&token=193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731&user_id=1
//返回
{
"ret": 200,
"data": {
"code": 1,
"team_id": 0
},
"msg": ""
}
```
####当天投票次数已达最大
```javascript
//第四次投票后
http://api.vote.phalapi.com/vote/?sign=phalapi&service=Act.Vote&team_id=5&token=193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731&user_id=1
//返回 - 注意此返回！
{
"ret": 200,
"data": {
"code": 2,
"vote_num": 0
},
"msg": ""
}
```
####投票的团队不存在
```javascript
http://api.vote.phalapi.com/vote/?sign=phalapi&service=Act.Vote&team_id=404&token=193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731&user_id=1
//返回
{
"ret": 200,
"data": {
"code": 1,
"vote_num": 0
},
"msg": ""
}
```
在进行上面的非法请求后，我们可以同时关注后台的日志：
```javascript
$ tailf ./Runtime/log/201505/20150517.log
2015-05-17 01:35:32|DEBUG|user not login|{"userId":null,"token":null}
2015-05-17 01:36:01|DEBUG|user can not vote today|{"userId":1,"teamId":5}
2015-05-17 01:37:52|DEBUG|user can not vote today|{"userId":1,"teamId":5}
2015-05-17 01:45:25|DEBUG|user need to login again|{"expiresTime":0,"userId":"1","token":"XXX"}
2015-05-17 01:48:13|DEBUG|user can not vote today|{"userId":1,"teamId":5}
```
###(7)需要的数据库表
以下为关键的表，其他表，可以通过脚本自动生成，然后导入。
```javascript
-- ----------------------------
-- Table structure for `phalapi_team`
-- ----------------------------
DROP TABLE IF EXISTS `phalapi_team`;
CREATE TABLE `phalapi_team` (
`id` bigint(20) NOT NULL AUTO_INCREMENT,
`team_name` varchar(100) DEFAULT '' COMMENT '队名',
PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=18 DEFAULT CHARSET=utf8;
-- ----------------------------
-- Records of phalapi_team
-- ----------------------------
INSERT INTO `phalapi_team` VALUES ('3', 'egg team');
INSERT INTO `phalapi_team` VALUES ('5', '奔跑吧兄弟（蓝队）');
INSERT INTO `phalapi_team` VALUES ('6', '奔跑吧兄弟（红队）');
INSERT INTO `phalapi_team` VALUES ('17', 'test team name');
INSERT INTO `phalapi_user` VALUES ('1', 'wx_edebc877070133c65161d00799e00544', 'weixinName', '******', '4CHqOhe1Jxi3X9HmRfPOXygDnU267eCA', '1431790647', 'phpunit.png');
INSERT INTO `phalapi_user_login_weixin` VALUES ('1', 'wx_122348561111', 'ASDF', '130000000', '1');
INSERT INTO `phalapi_user_session_1` VALUES ('1', '1', '193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731', '', '1', '1431790647', '1934382647', null);
```
## 4.3.4 脚本的使用
###(1)创建项目脚本 - phalapi_buildapp
此脚本可用于快速创建项目，其使用如下：
```javascript
$ ./PhalApi/phalapi-buildapp
Usage: ./PhalApi/phalapi-buildapp <app>
```
此脚本会根据Demo示例，快速生成一个新的项目。
###(2)自动生成单元测试骨架脚本 - phalapi_buildtest
这是一个用来自动生成单元测试骨架的脚本，其使用如下：
```javascript
$ phalapi-buildtest
Usage:
php /usr/bin/phalapi-buildtest <file_path> <class_name> [bootstrap] [author = dogstar]
Demo:
php ./build_phpunit_test_tpl.php ./Demo.php Demo > Demo_Test.php
```
然后，我们就可以使用辅助的PhalApiTestRunner::go()进行单元测试：
```javascript
public function testShowList()
{
//Step 1. 构建请求URL
$url = 'service=Act.ShowList&sign=phalapi&user_id=1&token=193CE82D1F4588A9A168BDE6E6B83868B1464F523D16C05206F308E51EB91731';
//Step 2. 执行请求
$rs = PhalApiTestRunner::go($url);
//var_dump($rs);
//Step 3. 验证
$this->assertNotEmpty($rs);
$this->assertArrayHasKey('code', $rs);
$this->assertArrayHasKey('teams', $rs);
$this->assertEquals(0, $rs['code']);
$this->assertNotEmpty($rs['teams']);
foreach ($rs['teams'] as $team) {
$this->assertArrayHasKey('id', $team);
$this->assertArrayHasKey('team_name', $team);
$this->assertArrayHasKey('vote_num', $team);
$this->assertGreaterThanOrEqual(0, $team['vote_num']);
}
}
```
###(3)自动生成分表建表SQL语句 - phalapi_buildsqls
此脚本用于根据dbs.php配置和./Data/*.sql文件生成完整的建表语句，其使用如下：
```javascript
$ ./PhalApi/phalapi-buildsqls
Usage: ./PhalApi/phalapi-buildsqls <dbs.php> <table> [engine=InnoDB]
```
假设我们需要对vote进行分表，拆分成3个表，可以这样配置：
```javascript
//$ vim ./Config/dbs.php
'vote' => array(
'prefix' => 'phalapi_',
'key' => 'id',
'map' => array(
array('start' => 0, 'end' => 2, 'db' => 'db_vote'),
),
),
```
然后准备基本的建表语句：
```javascript
//$vim ./Data/vote.sql
`team_id` bigint(20) DEFAULT '0',
`vote_num` int(11) DEFAULT '0',
```
最后，执行生成脚本：
```javascript
$ phalapi-buildsqls ./Config/dbs.php vote
/**
* DB: phalapi_vote
*/
CREATE TABLE `phalapi_vote_0` (
`id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
`team_id` bigint(20) DEFAULT '0',
`vote_num` int(11) DEFAULT '0',
`ext_data` text COMMENT 'json data here',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
CREATE TABLE `phalapi_vote_1` (
`id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
`team_id` bigint(20) DEFAULT '0',
`vote_num` int(11) DEFAULT '0',
`ext_data` text COMMENT 'json data here',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
CREATE TABLE `phalapi_vote_2` (
`id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
`team_id` bigint(20) DEFAULT '0',
`vote_num` int(11) DEFAULT '0',
`ext_data` text COMMENT 'json data here',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
```
## 4.3.5 在线接口参数查看
可以通过以下链接，在线实时查看接口参数：
```javascript
//参赛接口
http://api.vote.phalapi.com/vote/checkApiParams.php?service=Act.JoinIn
//投票接口
http://api.vote.phalapi.com/vote/checkApiParams.php?service=Act.Vote
//排行榜接口
http://api.vote.phalapi.com/vote/checkApiParams.php?service=Act.ShowList
```
其中，投票接口的参数如下：
- 欢迎使用PhalApi！
- 接口，从简单开始！
- [1.1]-下载与安装
- [1.2]-创建一个自己的项目
- [1.3]-在线体验
- [1.4]-文档、帮助和官网
- [1.10]-对PhalApi框架的抉择
- [1.11]-快速入门(backup)
- [1.12]-参数规则：接口参数规则配置
- [1.13]-统一的接口请求方式：_sevice=XXX.XXX
- [1.14]-统一的返回格式和结构：ret-data-msg
- [1.15]-数据库操作：基于NotORM的使用及优化
- [1.16]-配置读取：内外网环境配置的完美切换
- [1.17]-日记纪录：简化版的日记接口
- [1.18]-快速函数：人性化的关怀
- [1.19]-DI服务速查：各资源服务一览表
- [1.20]-DB操作：数据库基本操作速查
- [1.21]-类的自动加载：遵循PEAR包的命名规范
- [1.22]-签名验证：自定义签名规则
- [1.23]-请求和响应：GET和POST两者皆可得及超越JSON格式返回
- [1.24]-缓存策略：更灵活地可配置化的多级缓存
- [1.25]-国际化翻译：为走向国际化提前做好翻译准备
- [1.26]-数据安全：数据对称加密方案
- [1.27]-精益开发：更富表现力的Model层和重量级数据获取的应对方案
- [1.28]-COOKIE：对COOKIE原生态的支持及记忆加密升级版
- [1.29]-开放与封闭：多入口和统一初始化
- [1.30]-保持的力量：接口开发最佳实践
- [1.31]-新型计划任务：以接口形式实现的计划任务
- [2.11]-核心思想：DI依赖注入-让资源更可控
- [2.12]-海量数据：可配置的分库分表
- [2.13]-接口调试：在线SQL语句查看与性能优化
- [2.14]-测试驱动开发：意图导向编程下的接口开发
- [2.15]-演进：新型计划任务续篇
- [2.16]-领域驱动设计：应对复杂领域业务的Domain层
- [2.17]-微服务：Api接口服务层
- [2.18]-定制化：资源服务的再实现
- [2.19]-扩展库：可重用的扩展类库
- [2.20]-约定编程：架构明显的编程风格
- [2.21]-服务器统一部署方案简明版：CentOs---Nginx---php-fpm---MySql-[--Memcached]
- [2.22]-更多工具：精益项目和团队建设
- [3.1]-扩展类库：微信开发
- [3.2]-扩展类库：代理模式下phprpc协议的轻松支持
- [3.3]-扩展类库：基于PHPMailer的邮件发送
- [3.4]-扩展类库：优酷开放平台接口调用
- [3.5]-扩展类库：七牛云存储接口调用
- [3.6]-扩展类库：新型计划任务
- [3.8]-扩展类库：用户、会话和第三方登录集成
- [3.9]-扩展类库：swoole支持下的长链接和异步任务实现
- [3.11]-扩展类库：基于FastRoute的快速路由
- [4.2]-开发实战2：模拟优酷开放平台接口项目开发
- [4.3]-开发实战3：一个简单的小型项目开发（奔跑吧兄弟投票活动）
- [5.1]-架构与思想：PhalApi核心设计和思想解读
- [5.2]-杂谈：扯一些PhalApi的前世和今生
- [5.3]-框架总结：术语表和PHP开发建议
- [5.4]-许可
- [5.5]-联系和加入我们
- [5.6]-更新日记
- [5.8]-致框架贡献者：加入PhalApi开源指南
- [6.1]-基于接口查询语言的SDK包
- [6.2]-SDK包（JAVA版）
- [6.3]-SDK包（PHP版）
- [6.4]-SDK包（Objective-C版）
- [6.5]-SDK包（javascript版）
- [6.6]-SDK包（Ruby版）
- [8.1]-PhalApi视频教程
- 附录1：接口文档参考模板