KMS 核心概念

KMS 是在线 online 服务，不需要对产出代码进行二次人工开发。所有的功能配置都是通过在线配置完成。相比于传统手工开发后台管理系统有几个重要底层概念：

声明式 json
API First
SandboxFunction

以及几个特殊的核心概念：

表单
视图
API Porxy
Data API
Webhook

声明式 json

在实现机制上，KMS 所有的操作都是围绕 json 完成，包括表单的渲染、网络请求的配置，以及所有功能的定义。声明式 json 配置可以方便地将状态存到数据库中，方便后续查看和继续修改，也方便多端复用。

基于这个概念，你在 KMS 所看到的功能，基本上都可以导入和导出，大部分导入导出都是 json 明文，部分功能防止手工修改导致格式错乱，进行了简单的二次编码以降低人为可读性。

API First

在前后端的交互设计中，一切都是 API，即网络调用（https:// 或者 http://），这样后端的所有实现细节就可以完美屏蔽，KMS 前端不仅仅可以使用 KMS 的后端 API，也可以使用其他任意可访问系统的 API，从这些 API 中读取数据，发送数据操作指令。不仅如此，KMS 内部多个子系统之间也是通过 API 通讯。

同时为了保护实际的 API，KMS 提供 API 代理（即 API Proxy）功能来保护 API 并提供简化的调用方式。

此外，API 通讯数据格式默认是 application/json 格式，在某些场景下只接受 application/json 格式。

SandboxFunction

基于声明式 json 的设定，所有 KMS 能支持的功能在实质上都是预设好的，它并不能支持自己不识别的功能（比如你给表单 json 添加了一个人类可读可知的配置，或者不小心修改了属性大小写），从这个角度看，KMS 功能是非常有限的。

为了弥补这个缺陷，KMS 设计了类似宏的概念：SandboxFunction，即将 JavaScript 代码片段在一个动态的代码沙盒中执行以提高动态性。通常提供这个代码片段的属性，被称之为 code选项，通过提供代码片段，可以极大提高 KMS 的业务灵活性，这在数据展示和处理中极为重要。

也正是因为如此，如果要使用 KMS 的高级功能，了解一些 JavaScript 的知识是必要的。

表单

表单就是一个 html 中原生支持的 form 表单，用来向服务器提交数据只用。KMS 内置了许多表单组件，可以通过拖拽完成组件创建和布局，每个组件又有各自的配置选项，其中必备项是：字段名，即表单组件抛出的数据在表单中的字段，而整个表单抛出的数据，就是由各个表单组件抛出的数据的汇总。

一个表单一共有两份对应的 json：表单配置 和 表单数据。

表单配置 json 决定了表单如何显示，而表单数据 json 决定了表单能有什么用途。

表单配置 json 用来描述表单包含哪些组件，怎么布局，以及组件的配置都是什么值；比如一个空表单的表单配置是这样的：

json

{
  "meta": {
    "type": "form",
    "submitBtn": "确认",
    "labelWidth": 90,
    "layout": "horizontal",
    "labelAlign": "right",
    "gutter": [
      0,
      0
    ],
    "requests": [],
    "colon": true,
    "id": "kfmGzrjI"
  },
  "children": []
}

上述这个表单配置会抛出一个表单数据：

json

{}

是的，它没有任何字段，因为表单没有任何组件，它默认只能抛出一个空对象。

包含了一个输入框的表单配置，点击查看

json

{
  "meta": {
    "type": "form",
    "submitBtn": "确认",
    "labelWidth": 90,
    "layout": "horizontal",
    "labelAlign": "right",
    "gutter": [
      0,
      0
    ],
    "requests": [],
    "colon": true,
    "id": "kfmGzrjI",
    "itemCounter": 2
  },
  "children": [
    {
      "meta": {
        "type": "item",
        "tag": "cus-input",
        "span": 18,
        "vmodel": "value",
        "key": "id",
        "defaultValue": "",
        "required": true,
        "label": "编号",
        "tip": "",
        "v-if": true,
        "v-show": true,
        "width": 100,
        "widthUnit": "%",
        "$id": "input",
        "id": "ngEJrl6JU85dQnpe"
      },
      "attrs": {
        "maxlength": -1,
        "placeholder": "请输入ID编号",
        "allowClear": true,
        "readOnly": false,
        "disabled": false,
        "onChange": [],
        "trim": true,
        "showCount": false
      },
      "slots": {
        "prefix": "",
        "suffix": "",
        "addonBefore": "",
        "addonAfter": ""
      },
      "rules": []
    }
  ]
}

此表单配置可以生成以下格式的表单数据：

json

{
    "id": ""
}

小技巧

通常你不需要面对这个 json，它是由 KMS 生成并使用的；表单配置是可以导出导入的，你可以将一个项目已经配置好的表单，通过导出导入从而简单复制到其他项目中去。

表单的配套按钮

每一个表单都会配套一个 “提交” 按钮（默认情况下按钮的文字是：确认），点击后将表单数据递交给 API 存储或进行下一步检查和处理；而表单的 “取消” 按钮是可选的，通常并不太需要它。

表单根据使用场景，划分为三个类型：

专用表单：作为独立 json 数据的编辑容器，并由 KMS 提供数据访问服务，并且在菜单中只能使用一次
模板表单：作为独立 json 数据的编辑容器，并由 KMS 提供数据访问服务，并且在菜单中可以多次使用
内嵌表单：作为视图中内嵌使用，通常用于编辑视图表格的数据，不限制使用次数

视图

视图是一个只能用来看（展示数据）的图（页面）。视图并不具备抛出数据的能力，对比表单，视图有以下几个特点：

不支持数据抛出
没有“默认交互” （即提交/重置）
支持复杂数据展示
支持复杂交互

从功能定义上来看，视图更接近一个完整的 web 页面，甚至有一个视图组件就是：表单容器。

一个视图只有一份 json：视图配置。它类似这个样子，跟表单配置非常相似：

json

{
  "meta": {
    "type": "view",
    "labelWidth": 90,
    "labelAlign": "right",
    "gutter": [
      0,
      0
    ],
    "requests": [],
    "colon": true,
    "id": "kprKrKK2"
  },
  "children": [
    {
      "meta": {
        "type": "item",
        "tag": "text-tip",
        "span": 24,
        "v-if": true,
        "v-show": true,
        "label": "",
        "$id": "textTip",
        "id": "5Qy6RocQu9hHW0yd"
      },
      "attrs": {
        "tip": "请输入提示内容，以 ! 或者 i 开头试试。",
        "showClose": true,
        "showBorder": true,
        "interval": 0
      }
    }
  ]
}

视图中的表单

视图中的表单容器，是一个单层无嵌套简单表单，功能上与独立的表单做了区分以降低复杂度和理解成本。通常表单容器是作为其他数据组件的搜索功能存在的。当然如果需要渲染复杂表单，可以使用表单容器渲染一个内嵌表单，以降低表单维护难度。

小技巧

通常你不需要面对这个 json，它是由 KMS 生成并使用的；视图配置是可以导出导入的，你可以将一个项目已经配置好的视图，通过导出导入从而简单复制到其他项目中去。

API Proxy

这是由 API First 衍生出来的功能，是对业务 API 接口的代理。为什么要做 API 代理呢？原因如下：

提高业务 API 接口安全度。通常对于浏览器访问的 API 接口，都必须有一个可访问的域名作为基本配置，而有些管理接口是不需要且不能部署到公网，但 KMS 在公网部署。使用 KMS 的后端服务代理后，请求可以从 KMS 后端发出，从而避免实际业务 API 接口暴露到公网，提高安全度；
便于调试和修改。在 KMS 表单和视图中，需要配置 url 地址，使用 KMS 的代理地址后，实际的业务 API 地址可以统一单独配置，从而可以方便进行本地调试或者 API 直连等，而不用修改表单和视图；
复用 KMS 角色和权限管理。KMS 实现了一套灵活的基于角色的权限控制模块，大到功能模块，小到按钮点击，都可以在界面上方便配置和管理，使用 API Proxy 后，业务接口就可以免于在权限管理方面的开发，直接复用 KMS 权限即可，API 接口可以专注于业务内容开发；

API Proxy 的初始请求由 KMS 在浏览器中触发，到达 KMS 后端后，经过 KMS 后端对请求增加签名数据，然后将请求转给实际业务 API 处理，并将业务 API 处理的结果返回给 KMS 前端代码，并最终在浏览器中做出响应。

了解更多 API Proxy 的说明

Data API

KMS 有一个配套的数据 API 访问服务，即由 KMS 表单产生的 json 数据，可以存在这个 Data API 服务中，并有一个独立的域名提供数据访问服务。Data API 是独立运行和提供服务的。

比如 web 组的专题活动的 KMS 地址为：https://activity.kms.seayoo.com

对应的 Data API 地址为：https://activity.dsi.seayoo.com

Data API 服务主要是为了应对没有独立后端支持的一些场景而设计的，Data API 跟 KMS 主程序之间通过一组约定的 API 进行数据同步。如果需要，您完全可以重写一个 Data API 服务并挂接到 KMS 上，虽然这种重写似乎没有太多收益。

因为 Data API 的访问并不限制于浏览器，原则上可以由任何地方发出请求，所以 Data API 也可以从服务端调用以获取一些配置数据，如果这些配置数据同时被浏览器端使用到，那运营人员只需要配置一份数据即可。

了解更多 Data API 的说明

Webhook

KMS 由于可以提供数据服务，所以在数据变更的时候就需要通知关注数据变化的应用。这种通知机制基于 PubSub 模式，并通过 HTTP 请求调用的方式执行，这个功能称为Ｗebhook。

Webhook 允许登记一个 url 地址，指定某一个或某些表单菜单对应的数据发生变化后，应该收到来自 KMS 的通知，告知什么数据发生了什么变化。

了解更多 Webhook 的说明

KMS 核心概念 ​

声明式 json ​

API First ​

SandboxFunction ​

表单 ​

视图 ​

API Proxy ​

Data API ​

Webhook ​

KMS 核心概念

声明式 json

API First

SandboxFunction

表单

视图

API Proxy

Data API

Webhook