低调好用的API接口管理工具 - APIEagle

为啥不用现成的 APIFox

各位小伙伴，我是全栈开发小卷。很久没更新文章了，这期我们来聊一聊API接口文档管理工具什么是适合自己的，以及咱们自研的 APIEagle。提到 API 接口工具，很多人想到 PostMan、APIFox 等等工具，的确 APIFox 是一个集文档管理、接口调试、自动化测试于一体的 API 接口管理行业解决方案，但在实际企业使用中，或许我们仅仅是用它来维护接口的定义和版本管理，并不会完全把接口管理托管给该平台。那么对于基本的这些能力，在实际使用中 APIFox 在使用的便利性和人性化方面，个人认为还有更多可以迭代和优化的功能，比如说数据模型如何在接口的编辑场景中更好的维护。

随着 AI 迅速普及到各行业的软件产品赋能和研发、维护等方面，维护公司产品的程序员或个人开发者也从只会埋头敲代码转向了更具产品思维和软件设计的IT角色，而编码只需要交给 AI 代码生成工具，比如大名鼎鼎的 Cursor AI。基于这样的背景，小卷开始依赖 AI 工具来自研 API 接口管理工具。思路是先自研基础的表单引擎，并依据接口管理的页面构建场景来不断完善底层的表单引擎，同时基于表单引擎的字段配置、监听、联动等核心机制，对页面配置层实现更灵活的交互行为。通过这样的方式让表单引擎渲染的核心机制与页面配置、布局和交互的扩展能力交相辉映，通过良好协作构建出有高度定制需求的接口管理工具。

前后端技术栈与自研工具

下面我将介绍下自研的 API 接口管理工具所开发迭代的一版基本功能的初步实现。在介绍功能演示之前先介绍下研发采用的相关技术：

• 该工具整体使用的 Vue 3 + Spring Boot 4 的技术栈

• 前端采用 Node 24.18.0，基于 Vite 8 的工程脚手架

  • 整合了 Typescript 6、Eslint 10、Oxlint、Prettier等基础开发依赖
  • 功能依赖包含了：vue 3.5.32、ant-design-vue 4.2.6、vue-router、Tailwindcss 4.3.0、axios、pinia等等。
  • 自主研发基于 Vue 3 响应式特性的表单引擎 juan-form 1.0 版本
    前端的接口管理页面不是直接就研发，而是先自研了基于 Vue 3 响应式特性的表单引擎 juan-form 1.0 版本，该版本已经实现了表单引擎应该具备基础与核心能力：声明式字段配置、注册自定义控件类型、支持内层 Group、可编辑 List等实现模型嵌套、字段显隐、联动、依赖监听、表达式缓存、跨层状态同步、表单插件、字段插件、html 嵌套布局等等。这对 API 接口管理页面的复杂功能的构建提供了很厚的底层支持，未来还将进一步研发基于 json-schema 的 2.0 版本，以用于低代码表单和页面的页面级配置与所见即所得的渲染效果。
  • 自主研发企业级表达式构建器 juan-expr-builder 1.0
  • 一款借助 AI 研发的基于 Vue 3的响应式表达式构建器，可以与表单引擎集成，通过预先的字段、字典等配置，业务人员只需要在页面上通过点选和右键操作很方便的构建出图形化展示的复杂的表达式，当内容过长时支持自动换行，支持 juel、spel 等后端常用表达式引擎。通过图形化的操作方式，这样就避免了业务人员对于后台表达式技术的学习成本。这里咱们的表达式主要用在对接口数据模型的字段联合校验上，后续会演示相关功能。

• 后端采用 Java 25，基于 maven 构建的 Spring Boot 4.1.0 脚手架

  • 整合了 webmvc、jdbc、mybatis等基础的起始依赖，用于后台各层的代码构建
  • 采用江湖失传已久的 TDD（测试驱动开发）的模式，这里通过 AI 来研发并用大量的基于内存数据库 h2 的单元测试、集成测试来覆盖接口管理工具的各种操作场景，为越来越复杂的功能迭代保驾护航。曾经的敏捷开发最佳实践之一的 TDD 一直被诟病拖慢了软件开发生命周期，而在 AI 时代，TDD 终于焕发了第二春。
  • 后台的数据层同时采用数据库 h2+ 缓存 caffeine的组合，这是 TDD 小步快跑的快速开发迭代的最佳拍档，等功能测试稳定准备部署上线时可以再切换到 MySQL + redis 的组合。

基础功能演示

下面将详细的给大家介绍下 APIEagle 目前实现的功能以及亟待完善的一些地方。

创建初始版本

目前的布局暂时没有做路由首屏的固化，比较好的做法是参考 APIFox 的接口维护页面的布局设计，它这里不会跳路由，首页只加载一次，布局框架的各部分单独加载，这种方案咱们后续会引入对齐下；另外这里 API 是分模块的，不同模块下有不同的 API 接口和 Model（我这里叫 DTO）的维护，这就和微服务按各模块维护接口对齐了，而对于聚合查询的模块，DTO 是可以跨模块来引用的。这里咱们初始版本先做的简单，布局上没有聚合，分散在各个路由页面，且暂时没有做到模块维度，后续的产品迭代会补齐这块。

接口管理工具首先要考虑版本管理，因为实际软件开发的生命周期很长，不管是前后端交互还是第三方接口对接，都是一个长期维护的过程，接口版本管理就非常有必要。对应到咱们这里的实现，第一次创建的版本会全量的写入数据，而后续维护的变更将增量式的写入版本数据，这里我们先实现为显式的记录版本，后续也可以改为隐式的，比如保存会自动将版本对应到当前日期和递增的版本序号，而对用户来说是无感知的。

现在咱们来新增 API 接口文档，先手动创建初始版本，点「新增初始版本」，这里我们简单做一个校园跑腿App的接口文档吧。

编辑完，点「创建」，进入 API 列表页

在右上角可以进入「数据模型」维护界面，也可以进入「文档视图」，这里我们点「新增接口」，比如我们创建一个用户注册 API，在弹框中编辑信息：

下一步将进入接口编辑详情页，这也是咱们这个应用初版实现的最复杂的页面，看似简单朴素，实际暗藏乾坤，后续会给大伙儿演示各种编辑特性。

首先看请求配置信息，这里不需要额外的参数，直接看请求体类型，下拉框中选择「JSON对象」类型，因为还没有数据模型，在当前页面支持同步数据模型接口，而不必再跳转到单独的路由页面去维护数据模型，非常省事。

点「新增 DTO」，在弹框中输入信息来创建 DTO，这里支持从已维护的数据模型继承，此处不涉及，点「创建」

会看到联动出如下信息，默认的第一行字段配置是无法删除，咱们可以基于它右键「字段名」来创建同级字段。

这里支持「编辑 DTO」，比如改变继承关系，对应的继承路径见改行最后的「路径」，因为这里不存在继承关系，所以继承路径没体现出来。勾选「批量模式」则可以对下面的字段列表进行批量的删除、复制、移动等操作，这里的场景不涉及，暂且略过。咱们要做的就是编辑字段列表，对于必填项，点击勾选，则「校验规则」列会自动出现一条必填校验项，需要新建一条，只需右键当前字段名，选择「向上新增」或「向下新增」，注意：这一版并没有维护字段的顺序，只保证了要创建的字段所在的对象的结构层次不乱，后续会补齐排序功能。

其他的属性，在移动到字段行上在「操作」列会浮现一个编辑图标，点开可以编辑其他属性，比如这里的别名可以覆盖驼峰命名（与后台字段对应）转换后的下划线的json字段的命名，这里咱们补充下字段说明。

姑且咱们对 UserRegisterDTO 先定义这些字段，在后续版本再完善：

返回类型也先选择字符串来返回，注意这一版其实我们简化了返回的 json 数据模型，只是返回一个统一的 json 结构体中的 data 域这块的类型，后续版本会进一步补齐响应内容类型和数据结构的完整性。

点最下面的「保存」后，回到 API 列表页，再点右上角的「保存」

这样一个初始版本的接口文档就创建成功了，再回到版本首页

增加校验版本

下一步，咱们对创建的初始版本做一些接口校验工作的改进，这里咱们对创建的注册接口先增加数据模型的关联性校验：要求用户名和手机号不都为空，注意这里配置的校验要同步到后台代码的处理，为此这里应该是一个 DTO 中字段联动的后台表达式。而这对于咱们的接口管理工具来说，可以很方便的让业务人员分分钟搞定，看下面的操作吧！ 先进入最新版去编辑，注意只有最新版可以编辑，其他是历史版本，仅用于查看历史快照，等后续再次推送版本后，这里就能看到历史版本了。

进入「数据模型」，这里把数据模型的维护工作放到了它自己的编辑页，本来也可以把一些常用的设置放到 API 接口编辑页，操作上就不需要调页面了，尤其是我们没有做页框架首页的情况，姑且先跳过去吧

再进入当前版本的数据模型列表，对 UserRegisterDTO 点「编辑」

然后进入数据模型编辑页，该页面比 API 接口编辑页开发要早，字段列表并没有采用类似可编辑表格的形式来展示，而是采用横线展示、纵向展开编辑的方式，后续可以把编辑风格再统一下

这里我们关注的是 DTO 上字段的联合校验，点开校验框

下拉内部的校验类型下拉框，注意：这里的校验类型是按照要校验的目标和数据类型来加载的，对于对象类型而言这里的选项如下：

这里我们选「表达式」，然后会联动出表达式校验类型的对应的配置项，这里我们先填写「消息」栏

然后点击表达式控件的右侧编辑按钮，调出表达式构建器

这是一个非常灵活的企业级表达式构建器组件，关于它更多的操作配置场景，后续会详细给大家介绍。现在就来配置下这个规则，看详细操作：

配置企业表达式

从中间开路，选择「且」

此时会有校验信息，别担心，这里要求两边是逻辑表达式，咱们做一个变形即可

对左边操作数（字段框）右键选择「一元表达式」，让其变成一个子表达式结构

同理，对右操作数（值输入框）也右键变为一元表达式

ok，现在表达式整体结构出来了

下一步仅需选择字段即可

表达式配置完成，这里的条件就是满足校验失败的情况，预览以及渲染出来的表达式一目了然

当然对于这种逻辑我们还提供了一种更简单的一元表达式配置方式，这里我们要还原下之前的结构也很简单，在 hover 到目标表达式上（会有蓝色背景），在操作符或者空白区域右键，弹出设置

选择最下面的「一元表达式」，则选择部分（也就是这里的整体表达式）被切换为一元表达式

整体右键，勾选「字段多选」

则现在可以多选字段来组合逻辑

最终表达式其实是一样的，只是操作更简单

点「确定」关闭表达式构建器，校验下拉框也点「确定」以完成校验类型配置项的绑定

既然对象用表达式构建器实现了字段联合校验，那么对应字段单独的必填校验就可以取消了，直接反选复选框，校验规则中的那一项自动会被移除

都改完后，当前页点「保存」，再回到当前版本首页，点右上角「保存」，填写增量版本

注意这里我们先实现为手动推新版本，后续也可做成隐式的按照小版本号递增规则自动生成新版本。总之这种增量式写入的机制，有助于后续做版本差异对比。

推了新版本后看到历史版本只能查看，点历史版本的「查看」

能看到初版 1.0.1 的历史快照信息，这里请求和响应的外层通用结构后续再对齐一版

再看 1.0.2 版本的文档视图，看到变化的部分

数据模型的灵活编辑

首先咱们要明白：数据模型是为接口的请求体和响应体服务的，也就是说，不建议对它进行单独维护，这也是相对于 APIFox，我们做的一个创新------在接口的编辑视图中按需来使用和直接就地编辑数据模型，这也符合编程界的一个原则，就是数据的定义尽量靠近它被使用的地方，可以有效的减少数据模型维护的工作量。

这里我们就以校园跑腿应用的 API 接口文档为例，来新增一个跑腿员应聘个人信息填报这个接口，一起来看下对于请求的数据模型相对比较复杂的情况下如何更好的维护。

数据模型的继承

新增一个接口

创建请求体的数据模型

这里咱们的数据模型支持继承，如果有些属性我们希望很多模型可以共用，可以将它们抽取到父模型中，继承链路和 java 中类的继承一样。这里演示下创建一个数据模型时同时为其创建父模型

再新增一个父模型

在这里我们可以继续往上再继承一个基类

咱们再创建一个用户的基类

点创建后，回到了上一层弹框，此时父类带过来了，并且旁边还多了一个编辑，方便对继承的基类再做修改

这里我们直接点创建，ok，现在回到了最外层的弹框了，继承链路创建的模型都带回来了，点创建

现在我们维护的模型创建出来了，看到绑定的上层基类的字段也继承过来了，光标停在了自身要创建的字段上

内层数据模型与内联对象

继续编辑信息这里我们在字段中需要引用一个模型，顺带创建下

按照这样的操作，我们又完善了下内层模型的信息

接着咱们再完善一个紧急联系人列表的信息，注意，在最外层字段上右键，创建同级字段

注意创建的类型为一个数组，元素为内联对象，因为这里通过内联对象就不用抽取成可复用的模型了，内联对象只属于当前的模型独有

继续编辑，保存新的版本后，再回到最新的编辑

字段列表层级参考线与标注

注意这里，你应该发现咱们的数据模型的创建其实都是在当前页面，在需要的地方弹框来创建的，而不是用一个单独的页面去维护的，这就非常方便了。

另外咱们这里对字段列表中它所继承的模型以及内部的模型和内联对象都做了很贴心的层级参考线，位于字段名列的左侧，同时在光标移动到字段行上，所在的区域的模型还有浮动的标注展示。这里我们规定了：蓝色用于本模型和内层模型，紫色用于继承的模型，绿色用于内联对象，光标在字段行上移动时，它所在的区域也会实时的变化，这里会对当前区域继承的字段（除了自身的）的字段名显示为以 ^ 开头。

字段校验

很多人会诟病 APIFox 的模型在接口中应用的时候捆绑式和独立编辑的设计，咱们的设计不存在解绑的概念，而是如果不想内层的模型被复用了，直接切换类型从模型到内联对象即可，而要维护模型的字段，在需要的接口中直接维护即可，不需要再去单独的模型页维护。

这里拿字段校验为例，我们这里操作很简单

功能演示配套视频资源

复杂的字段列表的编辑演示

后续将进一步开发迭代新功能并修复缺陷，未完待更新~