首先,这里分享的是【极速】,不是【快速】,这意味着【极速】会比【快速】更高一个级别。基本一个开拓就可以掩护几个接口项目、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协作云上,可以在线编辑和协作你的接口文档。你可以创建一个或多个接口项目。
掩护好后,可以看到类似这样的接口文档访问主页和效果。
访问链接:https://www.yesdev.cn/apidocs-home-13.html
这是第一步,比较传统和手工的做法。但接下来,是故事开始的地方。你也可以跳过此环节。
一键天生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官网(https://www.phalapi.net/)的先容,只须要一行命令就可以安装PhalApi 2.x 最新版本。
1、composer安装PhalApi 2.x
$ composer create-project phalapi/phalapi
2、利用HTTP访问接口
http://localhost/phalapi/public/
3、查看在线接口文档
http://localhost/phalapi/public/docs.php
本地安装支配后,再把前面的接口代码包解压放到src目录,就可以直策应用了。
温馨提示:下一步,YesDev将会支持直接导出API接口源代码,当前还在开拓中。
自动天生接口文档无论是不是利用PHP还是Java或其他措辞开拓API接口,还是利用其他和编程措辞无关的办法编写掩护API接口文档,最主要的一点便是,只管即便避免再次人工额外掩护接口,该当利用工具根据接口源代码实时、自动天生。
这时须要用到编程开拓措辞的高等语法,例如PHP的反射,Java的表明等。
在PhalApi开源接口框架中,当API接口代码写好后,是可以实时自动天生对应的API接口文档,并且支持在线测试接口。
这部分内容不再赘述,详情可参考:《PhalApi 2.x 开拓文档 - 1.12 接口文档》 http://docs.phalapi.net/#/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接口,从设计到上线,已经分享了极速开拓过程中用到的工具和思想。关键词:自动天生代码、一键测试、利用得当的工具。