HEP: Higress API Portal

[lexburner]

背景

#501

功能设计

Higress API Portal 包含服务来源、服务列表、API 产品、API 列表、域名管理、证书管理 6 个菜单，其中服务来源、服务列表、域名管理、证书管理等和 Higress 控制台交互一致。可以理解为将 Higress 的路由配置替换为了 API 产品和 API 列表。Higress 原有的监控面板和插件市场，在初版设计中不涉及，后续考虑优化。

原型设计

API产品

列表页

列表页的操作包含 API 管理和策略，对应的行为

• API 管理，跳转到 API 列表页，并按照产品进行列表页的过滤查询
• 策略，跳转到策略配置页面，同 Higress，未重复给出具体交互

查询过滤条件：API产品名称

创建页

名称：必填，校验规则：包含小写字母、数字和以及特殊字符(- .)，且不能以特殊字符开头和结尾，长度限制：63
BasePath：必填，默认值：/，校验规则：以 / 开头，长度限制：255
域名：必填，从域名管理中获取域名列表，支持下拉选择
目标服务：必填，从服务列表中获取服务列表，支持下拉选择

建议用户通过域名关联产品，允许用户将域名配置给多个产品，但多个产品的 BasePath 一定要有区分度，否则无法正常路由

编辑页

除名称外，其他均允许编辑
鉴于 Higress 的“传统”，暂不涉及详情页

API 列表

列表页

支持按照 API 名称和 API 产品名称进行检索

创建 API 页

创建 API 主要分成两个部分：API 定义和后端配置

API 定义

API 产品：必填，从 API 产品列表中下拉选择。
域名和 BasePath，继承 API 产品中的属性，在创建时回显供用户查看。
API 名称：必填，校验规则：包含小写字母、数字和以及特殊字符(- .)，且不能以特殊字符开头和结尾，长度限制：63
请求方法：方法配置值，可多选，不填则匹配所有的 HTTP 方法，枚举值：GET/POST/PUT/DELETE/OPTIONS/HEAD/PATCH/TRACE/CONNECT
请求路径：必填，校验规则：以 / 开头，长度限制：255
映射模式：必填，下拉选择，目前仅支持入参透传这种模式，后期考虑支持入参映射（过滤未知参数）、入参映射（透传未知参数）问号提示文案：“透传：将请求头、请求方法、请求体透传至后端服务”

后端配置

后端服务：必填，从服务列表中下拉获取，并关联后端服务的协议类型，进行回显
请求路径：必填，默认设置为 API 定义模块中的请求路径，校验规则相同，允许用户编辑重写为其他路径。

导入页

编辑页

除 API 产品和 API 名称外，其他均允许编辑

领域模型解释

Higress API Portal 可以看做是 Higress 现有形态的延伸，所以两者的绝大部分领域模型是相同的，可以将 Higress 现有的控制台当做是 API Portal 的运维平面，API Portal 会针对其使用场景提出一些新的领域模型，下面诠释这些领域模型的关联。
Higress API Portal 的 API 产品跟 Higress 的路由一样，都对应一个 Ingress 规则，所以可以将 API 产品理解为一个配置 BasePath 为前缀匹配的路由。

Higress API Portal 中的 API 在现有的 Higress 中没有与之对应的模型，所以需要新增一个 CRD 与之对应。API 目前仅支持透传模式，所以仅需新增 API 请求路径映射这一个新特性，便可达到上述交互的效果，考虑使用 Higress 的插件机制完成该功能，后续针对 API 会有很多新的功能，也考虑使用插件机制完成，以保持跟 Higress 运维平面的兼容性。

API 是 API 产品精细化管理的产品，如果按照路由原先的模型，当 API 产品创建完毕后，意味着所有的路径都会被开放出去，但期望是只有具体的 API 被创建，才能正常进行路由，所以需要对 API 产品创建的 Ingress 规则做一些限制，判断是否有与之对应的 API，否则应该提示路由不存在相关的异常。

服务来源、服务列表、域名管理、证书管理等沿用 Higress 目前的领域对象完成映射。

Higress 的能力一定大于 Higress API Portal，但并不意味着所有用户都需要使用 Higress 全量的能力，API Portal 的提出是希望区分两类用户人群，让 Higress API Portal 服务于偏研发侧的用户，让 Higress 服务于偏运维侧的用户，Higress 和 Higress API Portal 识别同一套领域模型，共用同一个控制面，他们的数据是互通的。

如果目前没有 Higress API Portal 的需求，可以继续使用 Higress 控制台，Higress API Portal 不会损害现有的使用体验。

工作项拆分

• 前端页面开发
• Higress Console 后端接口开发
• API Product 对应的 Ingress 规则设计，支持无 API 时不能路由，API 级别精细化路由
• API CRD 设计
• API 路径重写插件开发设计
• 支持 OAS 2.0/3.0 规范导入 API 产品