草庐IT

apijson 初探

x3d 2023-03-28 原文

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 还是有重叠的部分的。 当然，一般国产的都是精品，APIJSON 也不会例外，APIJSON 在功能、安全、性能、易用性、Java 版生态(继承 JSON 的相关生态) 等方面都会比 GraphQL 更实用易用。

因此，可以考虑为这种 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 语句执行结果的数据库工具
初探apijsonliAPIJSONhttps架构设计

有关apijson 初探的更多相关文章

  1. 只能写作文？那必须安排一条龙服务[ChatGPT的应用场景初探] - 2

    0.引言在日常学习和工作中，我们经常需要进行写作，而写作不仅需要语言技巧和文学知识，还需要丰富的素材和思维的深度。随着人工智能技术的发展，ChatGPT等工具已经能够帮助我们解决这一问题。本文将介绍ChatGPT的应用场景以及如何使用它来进行写作。1.话题和题干成年人的心动有多珍贵心动是珍贵的瞬间，它推动我们追求梦想，给我们带来无限的希望。请描述一下你或他人在心动的鼓舞下所做出的努力，并论述心动对成年人生活的重要性。例如，当你爱上一个人的时候，你会有怎样的心动感受；当你为了实现梦想而奋斗时，心动会给你带来怎样的支持。题目自拟，字数800。2.写作思路描写男女邂逅的事情有可能落入俗套。所以，我们

  2. 【嵌入式Bluetooth应用开发笔记】第三篇：初探BLUE ALSA应用开发 - 2

    概述BlueALSA（BluetoothAudioALSA）是一种将蓝牙音频设备连接到ALSA音频系统的桥接程序。它提供了一个蓝牙音频设备的ALSA插件，允许使用ALSAAPI直接从蓝牙音频设备读取和写入音频数据，从而使得蓝牙音频设备能够以与其他ALSA兼容设备相同的方式工作。BlueALSA的主要功能如下：ALSA插件：提供一个ALSA插件，可以将蓝牙音频设备映射到ALSA设备节点上，使其可以像其他ALSA设备一样被应用程序使用。音频格式转换：支持将蓝牙音频设备的音频格式转换为ALSA支持的格式，以便在ALSA系统中进行处理和播放。延迟控制：提供了延迟控制机制，以便在数据传输过程中进行延迟控

  3. 【必知必会的MySQL知识】①初探MySQL - 2

    目录前言MySQL是什么？MySQL版本表的概念表中的列和数据类型行主键什么是SQL实践操作小结前言周所周知MySQL已成为全世界最受欢迎的数据库之一。无论你用的何种编程语言在开发系统，数据库基本上都是必不可少的。无论是小型项目开发如我们开发一个个人博客系统，还是构建那些声名显赫的网站如某宝、某讯等，MySQL都有着稳定、可靠、快速等优点。可以胜任数据存储的业务需求。我们今天就来一探MySQL，走入MySQL。MySQL是什么？数据库是以某种有组织的方式保存数据的容器，我们可以将其理解为一个文件柜。我们常见的容器有Oracle、DB2、SQLServer、Postgresql、mongodb等

  4. 技术分享 | Airsim初探-用游戏引擎做仿真 - 2

    谈到无人机/无人车仿真，首先想到的大概就是gazebo，但现在都快进入元宇宙时代了（手动狗头），还再继续使用gazebo这种上个时代的产品就显得不够hack，是时候了解和学习下新事物--Airsim了。Airsim是由微软开源的无人机/无人车仿真工具，其本质是UE4（虚幻引擎）的一个插件，所以Airsim可以在任何UE4的3D场景地图中运行，可以充分利用epic商城提供的免费、付费地图。在我探索Airsim的几周来，发现Airsim的优点在于：1、PX4支持，并且支持其他多种飞行模式。2、Python支持完善，官方提供大量pythondemo，可以快速进行算法可行性验证。3、开箱即用，几乎内置

  5. 初探交换机虚拟化技术m-lag - 2

    说到虚拟化，大家最先联想到的几个名词应该是虚拟机，服务器。今天要介绍的虚拟化，是路由与交换技术里面的虚拟化技术。在网络上，将多个网络设备虚拟化成一个整体的逻辑设备的技术，就称为虚拟化技术。通过交换机虚拟化技术，既可以在逻辑上集成多台物理连接的交换机，实现拓宽虚拟交换机带宽、提升转发效率的目的，也可以在逻辑上将一台物理交换机虚拟为多台虚拟交换机，实现业务隔离、提升可靠性的目的。虚拟化有横向虚拟化和纵向虚拟化，其中横行虚拟化技术常用的有堆叠、m-lag，vrrp。今天我们主要了解下m-lag技术。了解m-lag之前，我们先了解下以往数据中心常用的横向虚拟化技术-堆叠。从上图我们可以看到堆叠就是将两

  6. 基于FFmpeg的Java视频Mp4转GIF初探 - 2

    背景    在一些业务场景中，会有如下的一些要求：比如有用户需要将Mp4视频转为Gif动图。当然有一些小伙伴说可以使用系统截图，然后使用之前提到过的技术：GIF图像动态生成-JAVA后台生成。需要处理的素材比较少，就一两个视频，确实可以通过这种方式来处理。试想一下，如果需要处理上百个，做处理的小伙伴是不是就抓狂了，这完全是实打实的工作量。那有没有直接从Mp4转成gif动态图的技术呢？运营的小伙伴就能按时下班了。    经过一番查询，找到一些思路，Mp4视频的组成也是一帧一帧的图像组成的。如果有什么技术可以去动态获取这些数据，通过动态截取每一帧，最后再合成图片。不久解决了吗？FFmpeg变进入技

  7. Web3.0初探：一个基于区块链技术、用户主导、去中心化的网络生态 - 2

    Web3.0初探一个基于区块链技术用户主导、去中心化的网络生态Web3.0：致力打造一个基于区块链技术、用户主导、去中心化的网络生态。在Web3.0中，用户为满足自身需求进行交互操作，并在交互中利用区块链技术，从而实现价值的创造、分配与流通。这样的整个用户交互、价值流通的过程就形成了Web3.0生态。相比Web2.0的平台中心化特征，Web3.0致力于实现用户所有、用户共建的“去中心化”网络生态。 Web3.0生态主要组成要素及特点：1）用户身份：传统中心化身份容易产生安全和隐私风险，web3构建了一个去中心化的身份标识，以DID作为web3的用户身份表现形式；2）组织形式：web3的核心观点

  8. 【JavaWeb从入门到实战】MySQL筑基&初探SQL - 2

    🔥一个人走得远了，就会忘记自己为了什么而出发，希望你可以不忘初心，不要随波逐流，一直走下去🎶🦋欢迎关注🖱点赞👍收藏🌟留言🐾🦄本文由程序喵正在路上原创，CSDN首发！💖系列专栏：JavaWeb从入门到实战🌠首发时间：2022年8月18日✅如果觉得博主的文章还不错的话，希望小伙伴们三连支持一下哦阅读指南一、JavaWeb介绍二、数据库相关概念三、MySQL数据库MySQL安装MySQL配置MySQL登录、退出MySQL卸载MySQL数据模型四、SQL概述SQL简介SQL通用语法SQL分类五、DDL--数据定义语言DDL--操作数据库DDL--操作表六、navicatnavicat概述navicat

  9. 夜莺初探三·Categraf采集器 - 2

    夜莺初探三·Categraf采集器前言github仓库文档中对Categraf有很详细的介绍，简单重复一下就是:支持多种数据格式的remote_write；All-in-one的设计理念，指标采集只需要一个agent完成，也计划支持日志和调用链路的数据采集；Go编写，依赖少，容易分发和安装；内置一些监控大盘和告警规则，用户可以直接导入使用；开源项目并由快猫研发团队持续迭代。特殊目录结构说明input采集插件基本都位于input目录下，并且有些采集器提供了通用的大盘（alters-xxx.json）和告警(dashbord.json)配置可以导入n9e直接使用（例如监控仪表盘中更多操作的批量导入

  10. 新知实验室_初探腾讯云音视频 - 2

    本文目标：了解TRTC的基本概念初步运行demo调用API完成进入视频房间完成多人进入同一房间一、腾讯TRTC可能有些同学并不知道RTC的相关概念，这里先简单说一下。WebRTC(webReal-TimeCommunication)是指网站实时音视频通话技术。这项技术允许网络应用或者网络站点，在不借助任何中间媒介和第三方工具的情况下，建立浏览器之间点对点（Peer-to-Peer）的连接，实现视频流和音频流或者其他任意数据的传输，感兴趣的小伙伴可以自行搜索了解下。TRTC(TencentReal-TimeCommunication)是腾讯业务中的一项，也是WebRTC的一种实现。TRTC主要提

随机推荐