iT邦幫忙

2019 iT 邦幫忙鐵人賽

DAY 4
1

經過了這幾天一大堆的文字說明,想必您已經昏昏欲睡、有點不知所云了,是時候該上點乾貨了,否則台下的看官都要跑光了。

前一篇文章我已經坦承,我就是前端小白一名,所以要上乾貨,當然是跟後端有關了。在今天的文章中,我先略過一大堆的前言、理論、想法等等會讓人睡著的文字,直接用 Postman 來展示,在不增加一行 Server 端的 javascript 程式(沒錯,您猜對了,後端我是用 Node.js 實作) 的情況下,僅透過修改 SQL 的 store procedure 的內容,就能立刻新增、修改多支 API,而且可以立刻對外發佈使用。

在此要事先說明,因為這是一個快速的效果展示,所以相關程式並不嚴謹,目的只是讓您能先有個概念,否則聽我自吹自擂了半天,硬是搞不清楚我在說啥,那就冤枉了。
而在後續的章節會陸續加入諸如 token 驗證機制等的安全性議題,請持續關注本系列文即可。

上實際範例吧,我先寫了一支 test_getUserData 的 store procedure,程式內容如下

create proc test_getUserData
(
  @userid varchar(100)
)
as
begin
  select * from sys_users where userid = @userid
end

將程式寫入資料庫中
https://ithelp.ithome.com.tw/upload/images/20181012/201114216zuJU9WkKE.jpg

然後開啟 PostMan,輸入如下的參數內容,就得到該 user 的相關資料
https://ithelp.ithome.com.tw/upload/images/20181012/20111421st9zpmm6w7.jpg

一般而言,用 select * from xxx 是個不好的習慣,所以讓我們改一下 Store Procedure,只取 4個欄位,更新程式後,再執行一次 API,您會發現,Response 的資料內容已經不一樣了

alter proc test_getUserData
(
  @userid varchar(100)
)
as
begin
  select userid,username,email,token from sys_users where userid = @userid
end

https://ithelp.ithome.com.tw/upload/images/20181012/20111421jeJ5hgOAXE.jpg

在這個過程中,我們完全沒有更改任何一行 server 端的程式。

這只是一個非常簡單的範例,可是這樣的解決方案,可以讓您或是貴公司,很輕易的透過撰寫 Store Procedure 就完成數十隻甚至成百上千支的 API,這在很大的程度上大幅提升後端的開發效率。當然,如果你所在的組織已經有寫了一堆的 store procedure,那恭喜您,接下來要考慮的只是要開放哪些 API 而已。

Store Procedure 是一個已經存在超過 20 年以上的技術,我從早期在 MS-SQL 2005 上寫的程式,到目前的最新版本都能執行。即使是在 Opensource 赫赫有名,使用者滿坑滿谷的 MySQL,也從 5.0 版以後完整支援 Store Procedure。更令人欣賞的是 SQL 語法自從 ANSI 92 後就有一個國際標準,讓我們在跨不同資料庫時,雖不能直接 Copy 使用,但是總是有跡可循,是可以修改部分語法後移植到其他資料庫。

更多的優缺點,會在稍後有專章說明,本文主要的目的是在展示,透過一支通用的 Server 端程式,配合使用 Store Procedure 就能提供一個快速開發 API 的有效方法。您也許會有疑問,這個所謂的通用 Server 端程式,只能用在 Node.js 嗎? Of Course Not! 事實上我的通用 Server 端的第一個版本,是用 ASP.NET 寫成的,所以如果您想用 PHP、RoR、Python 等等現有的 Server 程式語言,都沒有問題,只要該工具能連接資料庫即可。

如果您不熟悉 Postman 的操作,可以上網 Google 一下就有很多的教學文,或是參考下文
http://kainors.github.io/2017/03/19/api-testing-with-postman/

實際上在使用 API 時,雖然可以使用 GET 或 POST,不過除非有特殊的原因,一般都是建議使用 POST 方法。

如果要提供 API 讓前端呼叫,一般而言我們會先提供一份 API 的使用說明文檔,主要的內容應該會有下列部分
Request
Response-ok
Response-error

https://ithelp.ithome.com.tw/upload/images/20181012/20111421FgRugk6ytH.jpg

寫文檔對工程師而言,都是一件苦差事,如果您不清楚該如何撰寫 API 的使用文檔,我個人會推薦您使用 APIDoc 這一套工具來產生相關的文檔。(沒錯,您又發現了,我就是喜歡能夠偷懶的工具)
關於 APIDoc 的使用,簡單的說就是只要您依照固定的格式寫程式的註解,APIDoc 就會幫您產生超讚的 html 格式的 API 使用文檔規格書,
您可以參考下面這幾篇教學文
http://hinylover.space/2016/03/31/create-online-document-use-apidoc/
http://apidoc.tools/
https://ifun01.com/8NKB7FA.html

以上就後端開發 API 提供一個不同的做法,這個方法的形成也是因為專業分工的思維下的產物。或是換個角度想,您認為 API 應該由誰來撰寫最合適? 誰最了解系統? 我的看法是系統分析師(System Analysis) 應該是最熟悉的。甚至在寫規格書時,如果有適當的工具,規格書的內容會有很大的改變。傳統用 Word 撰寫數以千頁的規格文檔,在實務上是非常沒有效率的,對工程師也是最沒有幫助的,因為就算工程師啃完厚厚的規格書,然後呢? 然後就要一行一行寫程式。如果改為 SA 是交付已經完成的雛型程式,加上已經寫好的相關 API 程式,在這個基礎上,您認為開發的效率還會一樣嗎?

今天就談到這,感謝您的支持,謝謝收看。


上一篇
Day3:全端開發架構說明(一)
下一篇
Day5:環境安裝(Database 篇) - DataBase.NET 的快速導覽
系列文
以資料庫為開發核心,利用通用 API 玩轉後端資料存取的概念與實作15

尚未有邦友留言

立即登入留言