極速輸出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協作雲上，可以線上編輯和協作你的介面文件。你可以建立一個或多個介面專案。
維護好後，可以看到類似這樣的介面文件訪問主頁和效果。
訪問連結：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
值得注意的是，在PHP開發的專案中，對於composer包，有2點注意事項。第1：composer包不應納入git程式碼倉庫管理；第2：每次釋出，除非有必要，否則不釋出vendor目錄，避免釋出過慢。其他語言也類似，最好實現增量的釋出，並且把第三方依賴的包和原始碼在程式碼倉庫中排除掉。
線上釋出
一鍵釋出，已經很方便了，但還不夠友好。畢竟，它還要要求使用的人要登入伺服器或跳板機，還要會懂得執行命令。
那有沒有更簡便的釋出方式呢？
答案：還是有的！
可以在內部開發一個釋出系統的介面，讓有許可權的人，可以選擇需要釋出的專案，進行線上釋出。這樣就非常完美了。例如我們的釋出系統1。0。
介面開發，唯快不破
API介面，從設計到上線，已經分享了極速開發過程中用到的工具和思想。關鍵詞：自動生成程式碼、一鍵測試、使用合適的工具。
