极速输出API接口

API接口开发，是当前软件开发项目中重要部分。掌握API接口的极速开发技巧、工具和思想，能让你设计、开发和维护接口项目更加得心应手，让本来“看不见”、“摸不着”的API接口开发更加有趣、有成就感。

首先，这里分享的是 【极速】 ，不是【快速】，这意味着【极速】会比【快速】更高一个级别。基本一个开发就可以维护几个接口项目、600+款API接口，事实上我就是这样进行日常开发和维护的。

其次，开宗明义，本次分享的 【输出 Api 接口】 ，涵盖API接口设计、接口文档、接口开发、接口黑盒测试、接口白盒测试、接口发布、接口正向工程。

下面，就来分享下极速输出API的开发体验。重点内容有：

• 在线设计接口文档
• 一键生成API源代码
• 自动生成接口文档
• 一键运行API接口
• 即刻搭建开放平台和提供OpenAPI
• 一键生成数据库Model类源代码
• 自动生成测试代码
• 一键测试
• 100%测试通过率
• 一键发布到分布式集群服务器
• 在线发布

内容上，承上启下，有连续性，但实际应用时，可以按需部分应用。

图片来源网络

技术栈和用到的工具

犹如物理定律和公式一样，成立的前提要有前置假设条件。

为了能达到极速开发API接口的效果，假设你已经：

1、有一定的编程经验或接口项目开发经验

2、已经有数据库、内部API接口或待开发的项目

3、当需要把内部API接口开放部分接口时，更为匹配

将使用到的技术栈是（如果你已熟悉或掌握，效果更佳）：

1、PHP开发语言

2、MySQL数据库或其他数据库

3、Linux和命令行终端的基本使用

将会用到的框架或工具：

1、PhalApi开源接口框架

2、YesDev协作云的接口文档管理

3、PHPUnit单元测试

4、搭建开放平台的接口大师（可选）

真实的接口项目成例

以下是已经上线的接口项目，分别是：

1、果创云，API接口数量 500+款

2、接口大师，API接口数量 208款

3、YesDev协作云，API接口数量 333+款

以上3个接口项目的API接口，累计约有 1000+款API接口（实际上，数量远不止这些接口，还有很多隐藏接口）。都是我和我的团队一起开发和维护的，从接口设计、开发、测试和上线，都应用这一套的极速开发模型，目前运行稳定，每日都被调用成千上万次。

关键理念和思想

谋定而动。

恰到其分、优秀的系统架构，需要符合SOLID原则、既满意高度的抽象又不失具体的实现；令人尖叫的产品，需要结合最小试错成本、MVP产品和敏捷开发，直击用户痛点。

要想实现API接口的极速输出和开发，就需要重点在效率和质量上“狠花”心思。只有把接口开发、维护的时间和精力减到最低最低，我们才能真正体验到极速开发的快感；只有把接口质量追求到极致，才能真正领悟到成千上万次API接口调用和高并发背后的稳定、安详和99.999%的SLA服务水平。

关键的理念和思想有：

1、 编程境界： 无代码优于生成代码；生成代码优先编写代码；尽量不要人工写代码。

2、 自动化原则： 尽可能进行自动化，把一切重复手工操作的实现自动化，并交由计算机来运行，只有这样，在效率提升上才能进行质的飞跃。

3、 CI持续集成 ：再小的项目，再小的团队也要搭建自己接口项目的持续集成体系，从开发和发布，一气呵成。

4、 用代码证明代码： 不依靠人的主观判断或臆想，而是通过白盒测试用单元测试证明每一条规则、每一个场景、每一行代码。

5、 充分发挥 编程语言 的优势： 每一种编程语言都有它的优势和专长，例如PHP的动态和解析性，可以在这基础上进行很多有创意的创作，减少代码维护的成本。

在线设计接口文档

在YesDev协作云上，可以在线编辑和协作你的接口文档。你可以创建一个或多个接口项目。

维护好后，可以看到类似这样的接口文档访问主页和效果。

访问链接：

这是第一步，比较传统和手工的做法。但接下来，是故事开始的地方。你也可以跳过此环节。

一键生成API源代码

当有了接口文档，我们下一步，可以做什么呢？

一方面，有了接口文档，我们就可以和前端开发者或外部的合作方，进行接口对接，让对方可以先参考和根据接口文档进行开发，避免阻塞对方的开发进度。

另一方面，很重要的是。当前，我们的传统做法都是先写API接口，写补充或生成接口文档。那么，有没一种可能，如果有一份接口文档，可以得到API接口吗？如果能做到这一点，无疑能：1）极大降低API接口开发的技术难度；2）帮助有专业技能的开发者极大提升开发接口的效率，节省时间。

例如，基于前面的接口文档元数据，我编写了一个根据接口文档自动生成API接口PHP源代码的解析引擎，最终简化为 脚本 命令的使用。

编写好脚本后，运行的效果是：

 [apps@izwz96prwhiplqswy76kvvz yesinew_www]$ ./bin/apidocs/build_my_apis.php 13Start to build my api 会员注册 into product ...Start to build my api  Hello Wolrd示例接口 into product ...Finished![apps@izwz96prwhiplqswy76kvvz yesinew_www]$ tree ./runtime/cache/         _install.lock  log/           Project13/     README.md      task/          weChatLogin/   [apps@izwz96prwhiplqswy76kvvz yesinew_www]$ tree ./runtime/Project13./runtime/Project13├── demos│   ├── N0.C0.A3.json│   └── N17.C0.A5.json├── N0│   └── C0.php└── N17    └── C0.php3 directories, 4 files  

简单解释一下，上面执行了 ./bin/apidocs/build_my_apis.php 脚本，并传递了参数 13（对应上面的接口项目ID），随后开始根据接口文档元数据生成对应的API接口源代码。这里使用的格式是基于PhalApi开源接口框架进行设计和生成的。

所以，以上面的“会员注册”为例，生成的PHP接口代码，类似如下：

 <?phpnamespace N17\Api;use PhalApi\Exception\BadRequestException;use N17\Common\Api;/** * 默认分类 */class C0 extends Api {    /**     * 会员注册     * @desc 会员注册     */    public function A5() {        $ PARAMS  = get_object_vars($this);        $api_version = "v1.0";        $module_url = "/user";        $api_service_url = "/regiser";        $api_service_request_type = "GET";        $url = $module_url . $api_service_url;        $funRs = $this->requestProxy($url, $PARAMS, $api_service_request_type);        return $funRs;   }}  

可以看到上面生成的API接口代码中，实现了对内部API接口的中转和调用。

生成API源代码后，就可打包放到PhalApi开源接口框架，运行和使用。

试想一下，如果瞬间可以生成和输出100个或几百个API接口，开发效率是何等的高效和方便。最后，你只需要做的，只是在接口基类完成一些业务上的通用处理即可。

一键运行API接口

有了上面生成的API接口源代码后，就需要把API接口运行起来，这时，就需要用到PhalApi开源接口框架了。

根据PhalApi官网（）的介绍，只需要一行命令就可以安装PhalApi 2.x 最新版本。

1、composer安装PhalApi 2.x

$ composer create-project phalapi/phalapi

2、使用HTTP访问接口

3、查看在线接口文档

本地安装部署后，再把前面的接口代码包解压放到src目录，就可以直接使用了。

自动生成接口文档

无论是不是使用PHP还是 Java 或其他语言开发API接口，还是使用其他和编程语言无关的方式编写维护API接口文档，最重要的一点就是，尽量避免再次人工额外维护接口，应该使用工具根据接口源代码实时、自动生成。

这时需要用到编程开发语言的高级语法，例如PHP的反射，Java的注解等。

在PhalApi开源接口框架中，当API接口代码写好后，是可以实时自动生成对应的API接口文档，并且支持在线测试接口。

这部分内容不再赘述，详情可参考：《PhalApi 2.x 开发文档 – 1.12 接口文档》 #/v2.0/api-docs

至此，我们有了可以直接访问和使用的API接口。

即刻搭建开放平台和提供OpenAPI

如果我们还需要把API接口开放给外部调用，有什么极速的解决方案？

答案是：有的。

这时，可以使用接口大师。接口大师是PhalApi开源框架的专业版，除了可以快速开发API接口，还可以即刻开放API接口，对API接口进行管理。

通过接口大师，把接口源代码放进来后，或者把API接口放进来后，后面的接口文档、接口权限、接口管理、接口授权、接口流量统计、接口付费套餐，都会自动出来，直接可以使用。

接口大师包含了给开发者使用的开放平台、给内部管理员使用的管理后台、OpenAPI、以及详细的开发文档。以下是接口大师安装后运行的首页：

开发者，在开发平台可以申请应用以及查看已获取的接口权限。

在管理后台，管理员可以根据业务配置和分配接口权限，以及对接口进行全面的管理。

如果说，从头开发搭建一个开放平台，需要30天；那么用了接口大师，可能1天或几天就能实现同样的效果。这也是善于使用工具和不重复造轮子的好处。

至此，就拥有了把API接口开放的能力。

一键生成数据库Model类源代码

在PHP，有3种方式，可以提升开发的效率。

第一种是，使用PHP的魔术方法，通过避免编写类似重复的代码，如setter/getter来提升开发效率，但这要求必须存在对应的PHP魔术方法，并且会对性能有一定损耗。

例如这个例子，需要对 DTO 对象实现重复的setter方法，分别设置了姓名、年龄。

 <?phpclass Student {    protected $name;    protected $age;        public function setName($name) {        $this->name = $name;    }        public function setAge($age) {        $this->age = $age;    }}  

如果改用PHP的魔术方法，可以这样快速实现。只需要编写一个__set()魔术方法就可以了，不管有多少个属性。

 <?phpclass Student {    protected $name;    protected $age;        public function __set($name, $value) {        $this->$name = $value;    }    }  

第二种是，通过变量，动态执行，这也是PHP的一大优势（但很可能也会被滥用）。就是编写一段通用的代码，或者直接使用PHP的动态变量、动态方法、动态类，根据参数来执行。例如上面的，改为：

 <?phpclass Student {}$obj = new Student();$key = 'name';$obj->$key = 'dogstar'  

第三种，就是自动生成代码。例如，我们已经有一个数据库，数据库中有几十或上百张表。这时，新的项目中，根据 MVC 模式，需要给每一个表都编写一个Model类的话，光是编写最基本的代码，都要花很多时间。这时，可以编写一个脚本，或使用现在的工具，直接批量生成代码。

例如，在PhalApi开源框架的官方文档上，介绍的 一键生成DataModel源代码。使用脚本./bin/phalapi_build_data_model.php迅速一键生成全部的DataModel源代码。 这将能极大提升开发的效率。

有多少张表，就会有多少份对应的类文件。类文件存在时不会覆盖原有文件。类似效果如下：

查看新生成的文件：./src/app/Model/Curd.php，有以下代码：

 <?phpnamespace App\Model;class Curd extends Base {    public function getTableName($id) {        return 'curd';    }}  

需要注意的是，自动生成的代码，不要再人工修改和维护，避免重新生成时会覆盖。如果需要定制，可以在基类、钩子函数、或事件来执行、回调或加载。

自动生成测试代码

接下来，再来探讨【质量】方面的话题。有了效率，还要有质量。也许有人会觉得质量和效率，犹如熊掌和鱼不可兼得。但实际上，我觉得是可以的，并且这两不是互斥的，而是相辅相成、互相促进的。

通过白盒的单元测试，可以非常有信心和有保障对质量作出承诺。

但前提是：

1、你要有单元测试的概念和意识

2、你要有一套单元测试的套件

3、你要随时运行这套测试用例

在国内，或者说在我身边所经历过的开发者、团队和企业，都极少有单元测试的意识，觉得这是浪费时间的事情，或者觉得这是测试人员应该做的事情。但我想说的是，不管怎样，作为开发，都应尽最大努力减少Bug的出现，而单元测试是最具有可行性、性价比最高的一种方式。

在开始进行单元测试之前，你应该要对PHPUnit和XUnit的家族有一定的了解。随后，我们可以继续使用脚本和工具，为已经写好的PHP代码自动生成对应的单元测试骨架，不需要自己手工重复编写。当然，更推荐的方式是，在编写代码之前，采用和遵循 TDD 的做法，先写测试用例。

例如，PhalApi开源框架提供的phalapi-buildtest命令，使用phalapi-buildtest命令生成对应的单元测试骨架代码，其使用说明如下：

生成的骨架代码类似如下：

 <?php/** * PhpUnderControl_App\Api\Site_Test * * 针对 ./src/app/Api/Site.php App\Api\Site 类的PHPUnit单元测试 * * @author: dogstar 20170725 */class PhpUnderControl_AppApiSite_Test extends \PHPUnit_Framework_TestCase{    public $appApiSite;     protected  function setUp(){        parent::setUp();        $this->appApiSite = new App\Api\Site();    }    ... ...  

phalapi-buildtest命令脚本虽然是PhalApi开源框架提供，但你也可以把它移植到你的项目、你的框架，只需要简单调整就能满足和适用。你还可以根据自己项目的测试的需要，加以调整和升级。重要是这种思想，哪怕使用的不是PHP开发语言，也可以从中获得极速开发的启发。

下面是YesDev单元测试代码的一小部分，YesDev项目整体上有上百的测试文件，这些都是人工创建的吗？不，都是使用脚本一键生成的。还可以在脚本的基础上再写一个脚本，就可以循环批量生成全部的测试文件了。

一键测试，用代码证明代码

不管是在职场的日常工作中，还是敏捷开发过程中的协作，抑或是个人开发时，快速和及时反馈都是很有帮助的。

一个庞大的系统，如果每个基本的元件、接口和组件，都已充分测试，那么它的质量和稳定性不言自明。

自动化单元测试，能够在几秒钟或1分钟内，针对你刚才编写的代码作出反馈，它会告诉你你的代码是否有问题、是否有语法问题、是否执行出错、是否不符合业务逻辑规则、是否存在回归测试中其他场景忽略的问题，这难道不是一件很有意义的事件呢？通过一个个这样的测试，构建成一个完整、全面、自动化的单元测试体系，进而对产品的稳定性和用户体验、公司品牌做出积极的帮助。

再具体一点，在做PaaS产品时，API接口是开发者用户频繁使用、调用和项目赖以生存的基础。如果任何一个底层的接口或逻辑出现问题，那么影响的就不仅仅是一个开发者、一个基于PaaS平台开发的产品，而是这个终端产品背后的全部用户。试想一下，假设 微信小程序 的登录接口突然无法登录了，会有多少微信小程序将受有影响。

在果创云后端云PaaS开发平台上，为了保障每一个接口的正确性、安全性和稳定性，我们为其编写了维护了恰到好处的自动化测试体系。接口开发后，执行一下；发布前，执行一下；紧急修复故障时，执行一下。每次执行，都能在几秒或1分钟内，对整套系统的500+款API接口进行回归测试。

以下，是果创云PaaS平台，一键执行单元测试的结果。

 [apps@izwz909znunwv0kmnmdpdkz tests]$ phpunit 我们正在帮助上万名技术开发人员取得成功！PHPUnit 6.2.4 by Sebastian Bergmann and contributors................................................................  63 / 429 ( 14%)............................................................... 126 / 429 ( 29%)............................................................... 189 / 429 ( 44%)............................................................... 252 / 429 ( 58%)............................................................... 315 / 429 ( 73%).......................................................*.*....... 378 / 429 ( 88%)...................................................             429 / 429 (100%)Time: 49.35 seconds, Memory: 30.00MBOK (429 tests, 1158 assertions)  

从上面的结果看到，运行花了49.35秒，不到1分钟。总共执行了429个测试，1158个断言。不管谁写的代码，只要有Bug，就难逃这道“法网”。

除此之外，我们还把自动化单元测试集成到了发布系统，不管是谁发布，都会自动执行上面的单元测试。如果有任何一个测试失败了，都将会停止发布，直接修复再重新发布。以下是发布系统的发布进度和提示。

100%测试通过率

单元测试，实际也是一种思想，一个工具；和脚本一样，应用得当，你的开发和维护工作，都将会非常愉悦、轻松和有成就感。

从编写了单元测试那一刻起，你和你的团队，就应该一起精心维护它。时刻使用它，并且让它保证100%的测试通过率。

除了上面分享的PaaS项目的单元测试，在开发SaaS产品时，单元测试的重要性也不容忽视。在SaaS，用户只需要注册一个账号，就可以开箱即用，不需要本地安装，不需要系统维护，不需要有技术人员，能过很低的成本就能体验和使用富有创意的产品功能。在YesDev项目协作云这款SaaS产品中，为了让项目经理和开发团队使用的每个功能，都顺畅、信息正确和恰到好处，我们也编写和维护了单元测试。

以下是YesDev的一键测试的运行效果。总共有370 tests, 585 assertions。不同的是，在每次进行测试之前，我们都会先添加一些测试数据，方便为后续的具体业务场景提供对应的测试数据。

再举一个产品项目的单元测试的案例。接口大师，是一套开发、开放和管理API接口的源代码和解决方案，在客户购买后我们会提供整套的 源代码 。这个项目的性质，就有点像以前 微软 卖光碟软件，一旦软件售出，有问题反馈，再修复再更新给客户就会非常繁杂。为此，100%通过的自动单元测试也为我们的软件输出和客户使用提供了非常有力的保障。并且针对软件销售和使用的场景不同，在每次进行自动化测试前，我们都会把数据库全部清掉，再把注册、登录和关键的底层逻辑再重新执行一遍。PaaS和SaaS的发布都好控制，因为运行的代码和运行环境都在自己的手上和控制范围内，但是光碟式的软件一旦售出，它运行的环境就离我们十万八千里了。同样是发布这一概念，但因软件产品开发的性质和商业的模式不同，有着不同的诠释。

因此，对于接口大师的发布，我们只是把需要提供给客户的源代码、文件和运行程序、以及相关文档打包成压缩包就可以了，并且使用版本号进行标识。

在接口大师3.8版本中，执行的单元测试效果如下，不管用例多少，始终100%通过率。

和此类似的项目还有很多，例如在PhalApi开源项目、曾经在唯品会开发PC官网系统时、曾经在MobVista维护开发者后台时，都有我编写、维护、运行和推广单元测试的身影。

一键发布到分布式集群服务器

有了极速输出的API接口源代码，也有了一套自动化且一键测试100%通过测试用例，最后一公里，我们还需要实现一键发布到服务器。可能你的服务器只有一台，可能有几台，可能是分布式。

不管怎样，记住，不要手动重复进行发布的工作。应当，编写一个脚本，或简化成一个按钮，只需要按一下，或点一下，就能实现快速的发布和上线。

我一直使用的发布工具，很简单，都是我自己编写的。在PHP的项目中，我觉得是非常方便、简单和有效的。就是使用 shell 命令，ssh，tar， rsync ，scp等，编写一个发布脚本，结合git代码管理，进行最新代码拉取、打包、传输、批量解压、备份和发布。

发布时，可以选择需要发布什么内容，以及发布到哪里。

分享下YesDev的发布脚本，你可以参考以下脚本，修改编写你自己的发布脚本。

 #!/bin/bash## 发布代码到各服务器## @author dogstar 20180123DIR="$( cd "$( dirname "$0"  )" && pwd  )"is_pre=$(echo $DIR | grep "preview")if [[ "$is_pre" == "" ]]then    echo "Please run in preview mode!"    exit 1fiif [ $# -lt 1 ]; then    echo "Usage: $0 <src|lite|full>"    echo ""    echo " - $0 src         # release ONLY src except demos (最快，只发src目录)"    echo " - $0 lite        # release src, public, config, etc. NOT with vendor (正常，排除vendor)"    echo " - $0 full        # release src with vendor (最慢，全量发布，包括vendor)"    echo ""    exit 1fiSUCCESS='\033[1;32m'FAILURE='\033[1;35m'RES='\033[0m'# 根路径设置为预发布API_ROOT_PRE="/path/to/preview/www.yesdev.cn"API_ROOT="/path/to/projects/www.yesdev.cn"IPS=("127.0.0.1")release_what=$1release_where=$2echo "start to release to product ..."echo ""# Step 0. 备份备份cp $API_ROOT_PRE/release/bak/yesdev.tar.gz $API_ROOT_PRE/release/bak/yesdev.tar.gz.bak# Step 1. 备份cp $API_ROOT_PRE/release/yesdev.tar.gz $API_ROOT_PRE/release/bak/yesdev.tar.gzcd $API_ROOT_PREsrc_and_vendor="./src"if [ "$release_what" == "full" ]; then    src_and_vendor="./src ./vendor --exclude *.svn --exclude=*.git "fi# Step 2. 打包tar -czf ./release/yesdev.tar.gz \    ./config/di.php  \    ./config/app.php \    ./bin \    ./data \    ./plugins \    ./language \    ./composer.json \    $src_and_vendorif [ "$release_what" == "src" ]; then    tar -czf ./release/yesdev.tar.gz ./srcfi# Step 3. 分发scp -P$port $API_ROOT_PRE/release/yesdev.tar.gz www@$ip:$API_ROOT# Step 4. 解压# 云端集群解压$API_ROOT_PRE/release/run_on_product.sh "tar -xzf $API_ROOT/yesdev.tar.gz -C $API_ROOT"echo -e "${SUCCESS}OK! ${RES}"echo ""  

值得注意的是，在PHP开发的项目中，对于composer包，有2点注意事项。第1：composer包不应纳入git代码仓库管理；第2：每次发布，除非有必要，否则不发布vendor目录，避免发布过慢。其他语言也类似，最好实现增量的发布，并且把第三方依赖的包和源代码在代码仓库中排除掉。

在线发布

一键发布，已经很方便了，但还不够友好。毕竟，它还要要求使用的人要登录服务器或跳板机，还要会懂得执行命令。

那有没有更简便的发布方式呢？

答案：还是有的！

可以在内部开发一个发布系统的界面，让有权限的人，可以选择需要发布的项目，进行在线发布。这样就非常完美了。例如我们的发布系统1.0。

接口开发，唯快不破

API接口，从设计到上线，已经分享了极速开发过程中用到的工具和思想。关键词：自动生成代码、一键测试、使用合适的工具。