apijson 初探

本文試著用 5W1H 方式切入，試圖快速建立自己對 apijson 的整體認知，所以這不是一趟快速入門的 demo 之旅，而是顯得比較務虛的探索式知識體系整合過程。

持續更新中...

1、Why

前後端開發過程中各種痛點：

開發流程繁瑣、週期長
前端/使用者端與後端各種扯皮
檔案過時-與介面不同步
後端拼裝資料費時費力且重複性勞動價值很低，全部交給前端拼裝又浪費流量頻寬
等等

誰應該負責徹底解決這個問題？

後端。

怎麼解決？

後端實現一種萬能查詢，並能減少絕大部分重複的常規資料CRUD功能及資料拼裝等開發過程，定義一套統一的規範讓前端來學習掌握，以後後端除了維護好這個 DSL 的執行時，就只需要做好資料實體的定義及許可權維護可以了。

這裡的前端，不一定只是 Web 前端開發，而是包含了更廣義的 Client 端開發的大前端開發人員，比如安卓使用者端開發人員、甚至包含部分在平臺上做小應用的後端開發人員。

前端是時候 Get 一門新技能了。

2、What

官方：

APIJSON 是一種專為 API 而生的 JSON 網路傳輸協定以及基於這套協定實現的 ORM 庫。

據個人理解，它定義了一整套 DSL 作為 API Client 的查詢語言（Query Language）的規範(Specification)，同時也是的一款對應的後端具體實現(Implementation for the Spec at server side)。

是的，這會讓人想起 GraphQL，如果做一些對比工作的話，會發現他們在 Spec 還是有重疊的部分的。當然，一般國產的都是精品，APIJSON 也不會例外，APIJSON 在功能、安全、效能、易用性、Java 版生態(繼承 JSON 的相關生態) 等方面都會比 GraphQL 更實用易用。

因此，可以考慮為這種 QL 取個名字，比如 ApijsonQL、或者短一點 apiQL。我選 apiQL。

特性設計：

後端

提供萬能通用介面，大部分介面不用再寫（後端統一基於apiQL語言提供服務）
零碼CRUD(增刪改查)、跨庫連表、巢狀子查詢等（後端將DAO層開放給前端）
自動生成介面檔案，不用再編寫和維護（藉助於生態工具）
自動管理許可權、校驗引數、防 SQL 注入（達到基本的安全要求）
開放 API，無需劃分版本，始終保持相容（後端根本就沒有具體的API）

前端

前端不用再向後端開發同事催介面、求檔案（前端基於apiQL語言直接進行DAO）
前端能完全客製化資料和結構，要啥有啥（前端自行按需拼裝）
前端呼叫介面看請求知結果，所求即所得（前端基於apiQL語言直接進行DAO）
前端可以一次性獲取任何資料、任何結構（前端自行按需拼裝）
前端能夠去除多餘資料，節省流量提高速度（前端自行按需拼裝）

介面工具

自動實時生成檔案，清晰可讀永遠最新
自動校驗與格式化，支援高亮和收展
自動生成各端各種語言程式碼，一鍵下載
自動管理與測試各介面用例，一鍵共用
自動給 JSON 加註釋和檔案，一鍵切換

DSL Specification

Client 應用使用 apiQL 查詢語言來請求支援 apiQL 的服務。

apiQL 是基於 JSON 資料格式定義的一種 DSL，對於 Cleint 開發人員來說，語法學習成本極低。剩下的，主要是熟悉領域特定的部分。

範例報文

請求：

{
   "[]":{
     "page":0,
     "count":3,
     "Moment":{},
     "User":{
       "id@":"/Moment/userId"
     },
     "Comment[]":{
       "count":3,
       "Comment":{
         "momentId@":"[]/Moment/id"
       }
     }
   }
}

響應：

{
   "[]":[
     {
       "Moment":{
         "id":235,
         "content":"xxx",
         ...
       },
       "User":{
         ...
       },
       "Comment[]":[
         ...
       ]
     },
     {
       "Moment":{
         "id":301,
         "content":"xxx",
         ...
       },
       "User":{
         ...
       },
       ...
     },
     ...
   ],
   "code":200,
   "msg":"success"
}