apijson 初探本文試著用 5W1H 方式切入，試圖快速建立自己對 apijson 的整體認知，所以這不是一趟快速入門的 demo 之旅，而是顯得比較務虛的探索式知識體系整合過程。持續更新中... 1、Why 前後端開發過程中各種痛點：開發流程繁瑣、周期長前端/客戶端與後端各種扯皮文檔 ...

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"
}