apijson 初探

apijson 初探

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

持續更新中...

1、Why

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

  1. 開發流程繁瑣、週期長
  2. 前端/客戶端與後端各種扯皮
  3. 文檔過時-與接口不同步
  4. 後端拼裝數據費時費力且重複性勞動價值很低,全部交給前端拼裝又浪費流量帶寬
  5. 等等

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

後端。

怎麼解決?

後端實現一種萬能查詢,並能減少絕大部分重複的常規數據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 還是有重疊的部分的。

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

特性設計:

後端

  1. 提供萬能通用接口,大部分接口不用再寫(後端統一基於apiQL語言提供服務)
  2. 零碼CRUD(增刪改查)、跨庫連表、嵌套子查詢等(後端將DAO層開放給前端)
  3. 自動生成接口文檔,不用再編寫和維護(藉助於生態工具)
  4. 自動管理權限、校驗參數、防 SQL 注入(達到基本的安全要求)
  5. 開放 API,無需劃分版本,始終保持兼容(後端根本就沒有具體的API)

前端

  1. 前端不用再向後端開發同事催接口、求文檔(前端基於apiQL語言直接進行DAO)
  2. 前端能完全定製數據和結構,要啥有啥(前端自行按需拼裝)
  3. 前端調用接口看請求知結果,所求即所得(前端基於apiQL語言直接進行DAO)
  4. 前端可以一次性獲取任何數據、任何結構(前端自行按需拼裝)
  5. 前端能夠去除多餘數據,節省流量提高速度(前端自行按需拼裝)

接口工具

  1. 自動實時生成文檔,清晰可讀永遠最新
  2. 自動校驗與格式化,支持高亮和收展
  3. 自動生成各端各種語言代碼,一鍵下載
  4. 自動管理與測試各接口用例,一鍵共享
  5. 自動給 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"
}

DAO/實體服務

apijson 如官方所述作爲一款 ORM,其實質是將原來傳統開發模式中的三層架構中的數據持久化層直接開放給前端,即壓縮了領域層和表現層(很薄,僅做可選的權限校驗),幾乎是讓前端的視線直接穿透到數據持久化層來進行他們的對接開發工作。

前端開發需要建立一種新習慣 - 主動進行數據查詢和拼接,而非像以前那般,等待後端拼接好再給出來。

apiQL 中目前支持的 Query 語句

  1. 查詢數組
  2. 匹配選項範圍
  3. 匹配條件範圍
  4. 包含選項範圍
  5. 判斷是否存在
  6. 遠程調用函數
  7. 存儲過程
  8. 引用賦值
  9. 子查詢
  10. 模糊搜索
  11. 正則匹配
  12. 連續範圍
  13. 新建別名
  14. 增加 或 擴展
  15. 減少 或 去除
  16. 比較運算
  17. 邏輯運算
  18. 數組關鍵詞
  19. 對象關鍵詞
  20. 全局關鍵詞

DAO 方法

借鑑 Restful Api 中的 verbs 術語,實際請求時全用HTTP POST請求。

  1. GET: 普通獲取數據
  2. HEAD: 普通獲取數量
  3. GETS: 安全/私密獲取數據,用於獲取錢包等對安全性要求高的數據
  4. HEADS: 安全/私密獲取數量,用於獲取銀行卡數量等對安全性要求高的數據總數
  5. POST: 新增數據
  6. PUT: 修改數據,只修改所傳的字段
  7. DELETE: 刪除數據

實際使用時,最好在前端封裝一套對應的 QueryBuilder,得到更 OO-Style 的體驗,而不是記憶一堆“方言”詞彙, 如 apijson-builder

3、Who/When/Where

適用場景

非金融類場景;中小型前後端分離的項目,尤其是 初創項目、內部項目、低代碼/零代碼、小程序、BaaS、Serverless 等。

簡易Demo

APIJSON-ToDo-Demo 一個簡單的 todo 示例項目,精簡數據,簡化上手流程,帶自定義鑑權邏輯

管理類系統

apijson-examples APIJSON 的前端、業務後端、管理後端 Demo

4、How

按需依賴

  1. apijson-orm APIJSON ORM 庫,可通過 Maven, Gradle 等遠程依賴
  2. apijson-framework APIJSON 服務端框架,通過數據庫表配置角色權限、參數校驗等,簡化使用
  3. apijson-router APIJSON 的路由插件,可控地對公網暴露類 RESTful 簡單接口,內部轉成 APIJSON 格式請求來執行。
  4. apijson-column APIJSON 的字段插件,支持 字段名映射 和 !key 反選字段

Quick Start

TODO

Best Practices

文檔

  1. APIJSON 官方文檔 ,提供排版清晰、搜索方便的文檔內容展示,包括設計規範、圖文教程等
  2. APIJSON 英文文檔 ,提供排版清晰的文檔內容展示,包括詳細介紹、設計規範、使用方式等

視頻教程

APIJSON 後端教程(1):簡介
https://www.bilibili.com/video/BV1vL411W7yd

APIJSON 後端教程(2):數據庫
https://www.bilibili.com/video/BV1eB4y1N77s

APIJSON 後端教程(3):Demo
https://www.bilibili.com/video/BV1FX4y1c7ug

APIJSON 後端教程(4):Boot
https://www.bilibili.com/video/BV18h411z7FK

APIJSON 後端教程(5):Final
https://www.bilibili.com/video/BV1GM4y1N7XJ

APIJSON 後端教程(6):uliweb_apijson
https://www.bilibili.com/video/BV1yb4y1S79v/

APIJSON 後端教程(7):問題答疑
https://www.bilibili.com/video/BV1dQ4y1h7Df

FAQ

https://hanxu2018.github.io/APIJSON-DOC/md/QA/#q-a-常見問題

5、Other

生態

  1. APIAuto 敏捷開發最強大易用的 HTTP 接口工具,機器學習零代碼測試、生成代碼與靜態檢查、生成文檔與光標懸浮註釋
  2. UnitAuto 機器學習單元測試平臺,零代碼、全方位、自動化 測試 方法/函數 的正確性和可用性
  3. SQLAuto 智能零代碼自動化測試 SQL 語句執行結果的數據庫工具
發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章