前言
最近一段時間，要為一個手機(jī)終端APP程序從零開始設(shè)計一整套HTTP API，因?yàn)槊嫦虻挠脩艉芄潭ǎ粋€新的移動端APP。目前還是項(xiàng)目初期，自然要求一切快速、從簡，實(shí)用性為主。
下面將逐一論述我們是如何設(shè)計HTTP API，雖然相對大部分人而言，沒有什么新意，但對我來說很新鮮的。避免忘卻，趁著空閑盡快記錄下來。
技術(shù)堆棧的選擇
PHP嘛？團(tuán)隊內(nèi)也沒幾個人熟悉。
Java？好幾年沒有碰過了，那么復(fù)雜的解決方案，再加上團(tuán)隊內(nèi)也沒什么人會 ……
團(tuán)隊使用過Lua，基于OpenResty構(gòu)建過TCP、HTTP網(wǎng)關(guān)等，對Lua + Nginx組合非常熟悉，能夠快速的應(yīng)用在線上環(huán)境。再說Lua語法小巧、簡單，一個新手半天就可以基本熟悉，馬上開工。
看來，Nginx + Lua是目前最為適合我們的了。
HTTP API，需要充分利用HTTP具體操作語義，來應(yīng)對具體的業(yè)務(wù)操作方法。基于此，沒有閉門造車，我們選擇了 http://lor.sumory.com/ 這么一個小巧的框架，用于輔助HTTP API的開發(fā)開發(fā)。
嗯，OpenResty + Lua + Lor，就構(gòu)成了我們簡單技術(shù)堆棧。
HTTP API簡要設(shè)計
HTTP API路徑和語義
每一具體業(yè)務(wù)邏輯，直接在URL Path中體現(xiàn)出來。我們要的是簡單快速，數(shù)據(jù)結(jié)構(gòu)之間的連接關(guān)系，盡可能的去淡化。eg：
/resource/video/ID
比如用戶反饋這一模塊，將使用下面比較固定的路徑：
/user/feedback
GET，以用戶維度查詢反饋的歷史列表，可分頁
curl -X GET http://localhost/user/feedback?page=1
POST，提交一個反饋
curl -X POST http://localhost/user/feedback -d "content=hello"
DELETE，刪除一個或多個反饋，參數(shù)附加在URL路徑中。
curl -X DELETE http://localhost/user/feedback?id=1001
PUT，更新評論內(nèi)容
curl -X PUT http://localhost/user/feedback/1234 -d "content=hello2"
用戶屬性很多，用戶昵稱只是其中一個部分，因此更新昵稱這一行為，HTTP的 PATCH 方法可更精準(zhǔn)的描述部分?jǐn)?shù)據(jù)更新的業(yè)務(wù)需求：
/user/nickname
PATCH，更新用戶昵稱，昵稱是用戶屬性之一，可以使用更輕量級的 PATCH 語義
curl -X PATCH http://localhost/user/nickname -d "nickname=hello2"
嗯，同一類的資源URL雖然固定了，但HTTP Method呈現(xiàn)了不同的業(yè)務(wù)邏輯需求。
HTTP API的訪問授權(quán)
實(shí)際業(yè)務(wù)HTTP API的訪問是需要授權(quán)的。
傳統(tǒng)的Access Token解決方案，有session回話機(jī)制，一般需要結(jié)合Web瀏覽器，需要寫入到Cookie中，或生產(chǎn)一個JSessionID用于標(biāo)識等。這針對單純面向移動終端的HTTP API后端來講，并沒有義務(wù)去做這一的兼容，略顯冗余。
另外就是 OAUTH 認(rèn)證了，有整套的認(rèn)證方案并已工業(yè)化，很是成熟了，但對我們而言還是太重，不太適合輕量級的HTTP API，不太可能花費(fèi)太多的精力去做它的運(yùn)維工作。
最終選擇了輕量級的 Json Web Token，非常緊湊，開箱即用。
最佳做法是把JWT Token放在HTTP請求頭部中，不至于和其它參數(shù)混淆：
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2NyIsInV0eXBlIjoxfQ.LjkZYriurTqIpHSMvojNZZ60J0SZHpqN3TNQeEMSPO8" -X GET http://localhost/user/info
下面是一副瀏覽器段的一般認(rèn)證流程，這與HTTP API認(rèn)證大體一致：
JWT的Lua實(shí)現(xiàn)，推薦: https://github.com/SkyLothar/lua-resty-jwt.git，簡單夠用。
JWT和Lor的結(jié)合
jwt需要和業(yè)務(wù)進(jìn)行綁定，結(jié)合 lor 這個API開發(fā)框架提供的中間件機(jī)制，可在業(yè)務(wù)處理之前，在合適位置進(jìn)行權(quán)限攔截。
- 用戶需要請求進(jìn)行授權(quán)接口，比如登陸等
- 服務(wù)器端會把用戶標(biāo)識符，比如用戶id等，存入JWT的payload負(fù)荷中，然后生成Token字符串，發(fā)給客戶端
- 客戶端收到JWT生成的Token字符串，在后續(xù)的請求中需要附加在HTTP請求的Header中
- 完成認(rèn)證過程
不同于OAUTH，JWT協(xié)議的自包含特性，決定了后端可以將很多屬性信息存放在payload負(fù)荷中，其token生成之后后端可以不用存儲；下次客戶端發(fā)送請求時會發(fā)送給服務(wù)器端，后端獲取之后，直接驗(yàn)證即可，驗(yàn)證通過，可以直接讀取原先保存其中的所有屬性。
下面梳理一下Jwt認(rèn)證和Lor的結(jié)合。
- 全局?jǐn)r截，針對所有PATH，所有HTTP Method，這里處理JWT認(rèn)證，若認(rèn)證成功，會直接把用戶id注入到當(dāng)前業(yè)務(wù)處理上下文中，后面的業(yè)務(wù)可以直接讀取當(dāng)前用戶的id值
app:use(function(req, res, next)
local token = ngx.req.get_headers()["Authorization"]
-- 校驗(yàn)失敗，err為錯誤代碼，比如 400
local payload, err = verify_jwt(token)
if err then
res:status(err):send("bad access token reqeust")
return
end
-- 注入進(jìn)當(dāng)前上下文中，避免每次從token中獲取
req.params.uid = payload.uid
next()
end)
- 針對具體路徑進(jìn)行設(shè)定權(quán)限攔截，較粗粒度；比如 /user 只允許已登陸授權(quán)用戶訪問
app:use("/user", function(req, res, next)
if not req.params.uid then
-- 注意，這里沒有調(diào)用next()方法，請求到這里就截止了，不在匹配后面的路由
res:status(403):send("not allowed reqeust")
else
next() -- 滿足以上條件，那么繼續(xù)匹配下一個路由
end
end)
- 一種是較細(xì)粒度，具體到每一個API接口，因?yàn)殡m然URL一致，但不同的HTTP Method有時請求權(quán)限還是有區(qū)別的
local function check_token(req, res, next)
if not req.params.uid then
res:status(403):send("not allowed reqeust")
else
next()
end
end
local function check_master(req, res, next)
if not req.params.uid ~= master_uid then
res:status(403):send("not allowed reqeust")
else
next()
end
end
local lor = require("lor.index")
local app = lor()
-- 聲明一個group router
local user_router = lor:Router()
-- 假設(shè)查看是不需要用戶權(quán)限的
user_router:get("/feedback", function(req, res, next)
end)
user_router:put("/feedback", check_token, function(req, res, next)
end)
user_router:post("/feedback", check_token, function(req, res, next)
end)
-- 只有管理員才有權(quán)限刪除
user_router:delete("/feedback", check_master, function(req, res, next)
end)
-- 以middleware的形式將該group router加載進(jìn)來
app:use("/user", user_router())
......
app:run()
為什么沒有選擇GraphQL API ？
我們在上一個項(xiàng)目中對外提供了GraphQL API，其（在測試環(huán)境下）自身提供文檔輸出自托管機(jī)制，再結(jié)合方便的調(diào)試客戶端，確實(shí)讓后端開發(fā)和前端APP開發(fā)大大降低了頻繁交流的頻率，節(jié)省了若干流量，但前期還是需要較多的培訓(xùn)投入。
但在新項(xiàng)目中，一度想提供GraphQL API，遇到的問題如下：
- 全新的項(xiàng)目數(shù)據(jù)結(jié)構(gòu)屬性變動太頻繁
- 普遍求快，業(yè)務(wù)模型快速開發(fā)、調(diào)試
- 大家普遍對GraphQL API有些抵觸，使用JSON輸出格式的HTTP API是約定俗成的習(xí)慣選擇
毫無疑問，以最低成本快速構(gòu)建較為完整的APP功能，HTTP API + JSON格式是最為舒服的選擇。
雖然有些擔(dān)心服務(wù)器端的輸出，很多時候還是會浪費(fèi)掉一些流量，客戶端并不能夠有效的利用返回數(shù)據(jù)的所有字段屬性。但和進(jìn)度以及人們已經(jīng)習(xí)慣的HTTP API調(diào)用方式相比，又微乎其微了。
小結(jié)
當(dāng)前這一套HTTP API技術(shù)堆棧運(yùn)行的還不錯，希望能給有同樣需要的同學(xué)提供一點(diǎn)點(diǎn)的參考價值 :))
當(dāng)然沒有一成不變的架構(gòu)模型，隨著業(yè)務(wù)的逐漸發(fā)展，后面相信會有很多的變動。但這是以后的事情了，誰知道呢，后面有空再次記錄吧~