# Apichain中文文档
**Repository Path**: onlinetool/apichain-chinese-documentation
## Basic Information
- **Project Name**: Apichain中文文档
- **Description**: Apichain项目的中文文档存放目录
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-09
- **Last Updated**: 2025-09-09
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
ApiChain从迭代和项目的视角管理我们不同项目、不同迭代接口api。按照迭代生成接口文档，基于项目并结合ai帮助我们搜索想要的接口发送网络请求。
沉寂半年之久，现发布 **v1.2.3** 版本包含以下重大更新：
1. 新增团队版功能，成员可内网部署 **runner** 共享数据，内网浏览器访问迭代开发文档，可通过 **runner** 转发api调用。
2. AI 加持，配置好项目的编程语言和开放框架后，可用国内外各种大模型针对项目进行提问，理解你的需求搜索相关api。
另外，新增以下更新：
1. 项目公共请求参数配置
2. api参数枚举类型支持
3. 从浏览器抓包快速创建api
4. json字符串类型请求参数优化
一些旧功能做了维护：
1. 全局、项目、迭代、单测环境变量
2. 给迭代编写api自动化测试
3. 迭代自动化测试导入项目做项目回归测试
🔥🔥🔥如果你也认可Ta更“懂”你，不妨 [点击这里给个star](https://gitee.com/onlinetool/mypostman) 支持一下呗 (*￣︶￣)💋💋💋
## 软件下载
windows 平台：[ApiChain_v1.2.3_windows.zip](https://github.com/jiangliuer326442/ApiChain/releases)
linux 平台：[ApiChain_v1.2.3_linux.zip](https://github.com/jiangliuer326442/ApiChain/releases)
mac 平台：[ApiChain_v1.2.3_macos.zip](https://github.com/jiangliuer326442/ApiChain/releases)
mac如果遇到无法打开应用的情况，在终端执行命令`sudo spctl --master-disable` 后即可正常打开。软件通过 github的workflow 自动打包，故提供GitHub下载链接，你也可以参照该文档，下载源码后本地编译打包。
## 相关术语
- 开发环境
正常情况下，我们的开发环境包括本地local、dev、sit、uat 测试环境、pre 预发布环境、pro 线上环境 等。通常不同开发环境的数据是隔离的，开发环境是我们存放**环境变量**的容器。
- 项目
通常一个具体的业务会通过内部不同微服务相互调用并对外提供唯一入口，这些微服务称为项目，当然单机项目只有一个微服务也是支持的。
- 迭代
一个时间段内，业务上需要完成的功能目标称为一个迭代，比如实现一个语音房。涉及到给不同的项目，包括直播、im、礼物、游戏微服务等，开发接口。因此，迭代是一个周期内，不同项目的一个组合。
- 环境变量
环境变量是 针对特定开发环境提供的 key-value 格式的数据集，可以方便我们修改数据，让这些有一定共性的数据变得更加可复用。
环境变量分为：
- 全局环境变量：在特定环境中的所有项目都可见，比如用于测试的特定UID。
- 项目环境变量：只在特定项目可见的数据，比如接口的api地址（api_host）
- 迭代环境变量：针对当前开发特定功能的版本迭代才可使用的数据，比如临时申请的验证特定功能的高权限账号，迭代测试完成就要销毁，不便污染全局数据集。
- 单测环境变量：为了跑通特定环境的单测而使用的数据源，长期对这个单测流程有效。
- 单测
就是不依赖于用户界面，通过连续的，链式的网络请求 来实现特定功能，并可验证该功能确实实现的一套接口组合以及对接口返回信息的是否成功的判断。
比如 新建文件夹、创建文件、写入数据、删除文件、删除文件夹这个流程。通过获取文件列表判断新建的文件是否在该文件列表中来验证新增文件或者删除文件是否成功。
为了让单测变得可复用，不要每次执行单测都要修改数据，单测就要支持 **随机字符串** 这个特性，用随机字符串作为单测的初始数据。同时需要**能够取前面任何一个步骤的输入数据**，与当前步骤执行结果的输出数据进行比较，确认当前步骤是否执行正确
## 开始旅程
### 任意城市查询天气预报
#### 加入团队
出于安全考虑，数据存储在本地，您需要在您的内网本地部署一个runner，部署runner的教程参考这里。下面使用我们的测试runner进行演示流程。
第一次打开，会弹出客户端类型设置的弹窗，我们选择联网版，服务器地址填写测试地址：`https://runner.apichain.app`
点击检测按钮，会检测我们的服务器地址是否正确，检测通过后，可以选择创建团队和加入团队，这里我们创建了一个叫 `天气预报开发小组`的团队，点击创建按钮成功创建了第一个团队！
创建成功后，app自动重启。
#### 环境、微服务、环境变量
点击设置 -> 开发环境 -> 新增 来创建我们的开发环境
发送请求中的client代表这个环境的api请求，从我们自己的电脑发出，runner代表api请求从这个runner（代理）中发出。具体说明参考这个文档。
点击设置 -> 项目 -> 添加 来创建我们的项目
编程语言 java，开发框架 springboot 的配置，是为了方便我们通过ai就这个项目的问题进行提问。关于如何使用ai就项目问题进行提问，参考这里。
在项目菜单下可以看到我们刚刚新增的项目，在环境变量菜单下设置我们这个项目在这个环境中，接口访问的 host 信息，点击项目->天气预报->环境变量->选择环境（本地环境）->api_host->编辑，下面填写的地址为 `https://pay.apichain.app/` (注意，要求必须是以 `http:// ` 或者 `https://` 开头且以 /结尾的 url 地址)
#### 迭代
我们这个天气预报项目 研发第一个迭代开发了两个接口：**查询支持的城市列表** 和 **根据城市查询未来天气**，
先创建一个迭代，在这个迭代里生产我们的接口文档，编写测试用例，最后迭代完成，接口合并到项目中，上线！
点击 设置 -> 版本迭代 -> 新增
我们现在通常是一个月一个迭代，因此我的迭代名称就是 **天气预报 2406**，因为我这个迭代涉及的项目就一个天气预报项目，所以微服务只选了一个。通常情况下，你们一个迭代会涉及很多个项目，都把它们选出来吧，多选漏选也无所谓，可以在 设置 -> 版本迭代 找到你的版本迭代，进行修改的。迭代说明是一个 markdown 的文案，这会在你们迭代的文档顶部展现出来，你、前端、测试 所有想要看迭代接口文档的人都会看到～
-----
#### 接口测试
##### 公共请求参数
先配置我们这个项目的公共请求参数。公共请求参数会在这个项目的所有网络请求中自动添加的部分，可以设置路径变量、参数、头部、主体。
在项目->全局参数->头部->批量编辑 中粘贴以下内容，会自动帮我们填写好全部的header信息。点击保存按钮，可以看到上面的内容。
```
Content-Type: application/x-www-form-urlencoded
lang: zh
```
##### 城市列表
测试一下我写的查询支持城市列表接口是否正确：请求 -> 发送请求，选择项目（天气预报）-> 选择环境（本地环境）->请求方式（POST）->地址（test/weather-report/city-list）。点击发送请求按钮可以得到下图的响应，代表查询天气预报接口是可用的。同时，我们看到，返回的message是中文的，表明我们设置的公共header中的语言是生效的！
点击**发送请求**按钮上面的 **保存** 按钮，把刚刚自测验证通过的接口保存到这个迭代文档中。我们需要告诉其他人，这个接口是用来干什么的（查询城市列表），传的那些字段是什么含义（`公共语言配置`），返回的那些字段又是什么含义，这些在我们的迭代文档中都会有所体现。另外这个接口是属于哪个迭代的，如果这个迭代涉及的接口太多，我们还要通过文件夹（天气预报）在迭代这个池子中进行接口和接口的分类。勾选导出到文档便可以在自动生成的迭代文档中看到这个接口。
data 备注为`城市列表`，下面的ID参数类型为**数字**，备注为`城市ID`，name 参数类型为字符串，备注为`城市名称`。
点击保存就在我们这个迭代中新建了第一个接口 ——查询支持的城市列表！
##### 查询天气
验证第二个接口，根据城市名称查询天气，这次改成从迭代中发送网络请求，两者的区别是 从迭代发送网络请求，使用的环境变量可以包括迭代私有的环境变量，并且优先级高于项目环境变量和全局环境变量。迭代->天气预报2406->文档->发送请求，打开发送请求页面。选择项目（天气预报）->选择环境（本地环境）->请求方式（POST）->请求地址`test/weather-report/query-city-weather`。参数 `cityId` 填写 `1`，代表查询Ankara这座城市的天气。发送请求得到以下响应：
我们点击保存按钮把这个接口存入迭代的接口文档中吧！标题：查询城市天气，字段cityId 城市ID，必填，导出到文档。城市id 配置为选择器，表明用户只能选择一个城市进行接口调用，而不是随便写个ID。
选择器内填写 `Ankara:1`代表有一个ID为1，城市名称为Ankara的城市，调用接口传输的是1，展示的名称是Ankara，点击回车确认。效果如下：
在迭代的接口列表点击发送按钮，可以看到发送网络请求的效果如下：
#### 编写文档
下面看看我们的劳动成果，一份迭代的接口文档已经准备好了
在迭代导航下可以看到我们刚刚创建的迭代，点到文档菜单，可以看到这个迭代下面的接口列表，支持根据接口地址、接口说明、接口所属的项目（微服务），接口在迭代里的文件夹进行帅选；对接口列表的管理包括编辑、删除、设置排序值等。
点击右下角的导出按钮，可以把这个迭代的接口导出成html或者markdown文件，离线分享。也可以打开这个迭代的 会员->迭代文档按钮，复制文档链接在线分享。（文档链接地址取决于您运行runner所在的服务器网络）
用浏览器打开复制的迭代文档链接，效果如下：
#### 编写单测用例、执行测试
上面，我们在编写接口文档时，已经大概测试了单个接口是可用的。实际上，这些接口不是单独存在的，他们需要根据特定的使用场景，按一定的规则将这些接口的入参、返回值串联起来，通过一步步的断言验证在这个特定场景下，接口返回信息是正确无误的。
以我们的天气预报项目为例，上面验证了 **Ankara** 这个城市查询天气是没有问题的，然而我们的实际场景是：从支持的城市列表中任意拿出一个城市，都要求必须能够查询出这个城市的天气，只有这样才能确保我们的接口是真的可用。
新建一个单测用例：从迭代菜单找到**天气预报 2407**->单测，点击添加，单测名称我写的是 **任意城市查询天气**，文件夹为 根目录 ，点击确定。
在这个单测用例中，包含两个步骤：
1. 查询城市列表
2. 从城市列表的返回中，任意选择一个城市名作为入参，查询该城市的天气
为了保证这些步骤顺利执行下去，每个步骤必须添加一个断言，断言失败终止执行测试用例，并告知亲在哪里断言出错了，入参是什么、返回是什么，方便你进行排查修复 bug。
从单测列表中找到你新加的单测，接口选择 **天气预报** 项目 的 **查询支持的城市列表** 接口，其他使用默认值即可。
下面填写返回断言：这个接口的断言是要求 **接口返回正确的错误码**，也就是 status 必须是 1
最终生成下面的断言表达式，支持添加多个断言的，他们之间是且的关系。点击**添加步骤**按钮，添加我们第一个单元测试的第一个步骤。
我们可以试着运行一下测试用例，看一下效果，选择环境->本地环境，勾选需要执行的单测项目，支持多选，多个测试用例将依次执行，点击执行用例按钮依次执行选中的测试用例。
从图中可以看到，我们的执行结果是成功的，也可以看到，我们每个步骤、接口调用的入参、返回值，断言两边的计算结果，方便我们在遇到失败时进行排障。
-------
再接再厉，添加第二个步骤，拿刚刚成功的获取城市列表接口返回的 **任意一个城市**作为入参，调用查询天气预报接口，断言接口返回的城市就是我们入参提供的来自于城市列表接口返回的任意城市。
很显然，这里只查询 Ankara 这一座城市不满足测试的需求，我们要的是任何城市都可以查询。下面是高能区，仔细看图：
数据源是 上一步，查询城市列表的返回值，我们取他数组里任意一个元素的city值。ApiChain目前支持的数据源包括：
* header
我们发送给接口的 header内容中的key
* uri param
我们发送给接口 uri 路径中的key，uri路径 例如 /user/id_{id}.html，可以提取出 id
* body
post 方式发送给接口的主体数据
* param
get 方式发送给接口的参数
* responseContent
接口返回的主体报文，包装在返回的body中的
* responseHeader
接口返回的header
* responseCookie
接口返回的cookie，cookie原本就是在header中的，ApiChain从接口返回的header中提取出所有的cookie，封装在独立的responseCookie数据源中，方便执行单测。
`result.*random().city` 是参数数据源的具体路径，result 下面是一个数组，我们选数组下面的任意的一个元素，拿到这个元素后，我们使用他的 **city** 字段作为入参。（放心，在输入“.”号时会自动触发语法提示，输入这些不会太难，你体验一下就知道了～）
*random() 是针对数组类型，ApiChain提供的一个内置函数，取数组任意元素。除此之外，针对数组类型提供的内置函数包括：
* *first()
取数组第一个元素。使用场景例如，先调用插入数据接口，后调用数据列表接口，往往刚刚新增的数据在第一个位置，我们可以取该数据与刚刚插入的数据进行比对，断言插入数据是否成功
* *last()
取数组最后一个元素。使用场景例如，分页查询，前端每次给我上次返回给他的数组的最后一个元素的id，我根据这个id返回前端下一页的数据。
* *eval()
针对非数组类型的数据，提供一个万能的 *eval() 函数，这是一个需要自己写参数的函数，例如 `result.*random().city.*eval('"location_" + $$')` 拿到的数据就不是 类似于“上海” 这样的字符串了，而是 "location_上海"这样的字符串，eval 函数可以当做 js 代码执行参数里面的内容，$$ 是对当前处理的变量的一个引用，示例中是 “city”这个变量。
点击确定，入参已经填好了
下面添加返回断言，和上一步类似
可以看到，我们已经添加好了两个步骤，下面在 **本地环境** 下执行我们的用例。
------
#### 迭代单测用例和接口合流到项目、回归测试
目前我们的单测是在迭代中进行的，迭代上线后是要关闭的，这样就会再也找不到我们给迭代写的单侧了。当我们需要给项目做回归测试时，我们希望能够在项目中找到这个项目所有执行过的单测，让他依次再执行一遍，用来判断这个版本的开发有没有导致项目旧的功能的使用出现问题。
单测拓展按钮里有个 “导出到项目”按钮，点击后，会在项目维度，将这个单测复制一份，同时被复制的还有迭代环境变量被复制为 单测环境变量，迭代环境变量在这个迭代中生效，单测环境变量对这个单测生效。
代码上线，迭代已经结束，我们到 设置->版本迭代->迭代状态 入口关闭我们的迭代，操作会自动把我们这个迭代开发的所有接口合并到项目中。
此刻，可以在项目中执行天气预报的单测用例的，测试用例可以多选执行，进行回归测试。
### 用户注册登录鉴权
本教程在上一篇讲述基本使用的前提下，以企业常见的登录注册鉴权流程为例，确保项目上线回归测试用户登录注册这块功能不出问题。
#### 初始化
新增一个项目，具体内容见下图，不展开讲
新增迭代，具体内容见下图，不展开讲
配置项目调用接口的地址前缀为`https://pay.apichain.app/test/user/`
#### 用户注册
从迭代入口进入到发送网络请求页面，接口地址 **register** ，提交数据如下
- **userName** {{$randomString}}
- **password** {{$randomString}}
- **email** {{$randomEmail}}
- **age** {{$randomAge}}
本次我们使用了 ApiChain 支持的内置函数，所有支持的函数列表，输入 `{{$` 时能够看到，关于支持的内置函数的完整列表，参考这个链接。
从这个返回报文中，我们看到注册后，返回的header（responseHeader）中包含了一个用于登录鉴权的jwt，返回的主体意思是注册成功，也给了注册的用户信息。我们先把它保存到接口文档。
这些参数都是必填的，age 字段类型是数字，其他都是字符串，返回的header 中包含 jwt，我们用来登录的令牌。点击保存。
#### 根据昵称获取用户头像
接口地址 `avatar/`，路径变量如下：
```
nickname:Mustafa
```
点击发送请求，可以看到uri变成 avatar/{{nickname}}，实际上，这只是一个规范，你可以根据{{nickname}}实际的位置重新调整。接口返回是一张图片，可以将这个返回图片的接口保存到迭代文档中。
#### 获取登录用户信息
从迭代文档中找到刚刚新增的用户注册接口，点击发送按钮。
点击发送请求按钮（此刻你会发现随机不重复的好处了，继续注册不要做任何修改），点击复制按钮，复制返回的jwt，粘贴到记事本中，后面流程会用到。
接口地址 **get-login-user** ，参数 header 的 key 是 **Authorization**，value 是 **bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI5Iiwic3ViIjoiQXBpQ2hhaW5fOGIzNzM1YWEtOTg2Mi00MDViLTllOTUtNWI2YzI5ZWI5MmNlIiwiaWF0IjoxNzM3OTczMzk3LCJleHAiOjE3Mzc5NzY5OTd9.A0bZ69TZE-412nFz1NqxffRh2y06mEHxTEIBcLndqyg** ，也就是 `bearer ` 加上你刚刚复制保存下来的那个jwt。
点击发送请求按钮，可以看到能够根据这个认证令牌拿到用户信息，这个令牌有效期 30 分钟。点击保存按钮，迭代文档新增我们的第二个接口。
#### 通过 application/json 方式实现用户登录
这个demo的登录方式既支持 邮箱+密码登录，也支持 用户名+密码登录，可通过 application/json 方式提交数据。
邮箱+密码 登录方式提交的报文是
```json
{
"type": "by_email",
"email": "username@email.com",
"password": "password"
}
```
用户名+密码的登录方式提交的报文是
```json
{
"type": "by_uname",
"userName": "userName",
"password": "password"
}
```
请求地址 **login**，header中 content-type 选择为 `application/json`，在主体部分粘上请求的报文，就可以发送一个登录请求了。
这样，就完成了一个application/json的网络请求，点击保存按钮保存到迭代文档。
#### 通过 jsonString 方式实现用户登录
在实际开发过程中，我们经常会遇到表单某个字段参数是一个json格式的报文，在我们编写单测时，需要能够自动构造出这样的json格式的报文，为此，我们的demo的登录也支持了 通过jsonString的方式提交登录数据。
接口地址 `login-by-jsonstring`， 参数 str，类型 jsonString，示例如下：
```json
{
"type": "by_email",
"email": "username@email.com",
"password": "password"
}
```
把他保存到迭代文档，保存时参数类型选择 json字符串。
到此，用户注册登录鉴权涉及的所有接口都登记到迭代文档中了。
## 版本发布记录
v1.0.9:
1. 启动速度优化
2. 使用ssh key作为默认用户
3. 修复bug
4. 界面滚动条优化
v1.0.8:
1. 支持将本次迭代部分接口因功能不上线移动到另一个迭代中
2. 支持选择部分环境变量拷贝到另一个开发环境
3. 支持将部分项目导出到另一个用户电脑，实现项目接口的共享
4. 将原有收费功能价格调整为1元
v1.0.7:
1. 单测链支持引用前面步骤cookie作为入参
2. 网络请求和单测统计接口耗时
3. 支持将迭代的单测导出到项目用于项目回归测试
v1.0.6:
1. 修复历史记录无法使用迭代环境变量的问题
v1.0.5:
1. 完善发送网络请求和迭代单元测试相关功能，支持从迭代到项目的可复用单元测试
v0.0.5:
1. 增加VIP充值和mock服务器功能
v0.0.4
1. 迭代支持接口先行方式添加 api
2. header 支持 application/json，multipart/form-data 两种方式的 api
3. 迭代自动化测试支持手动和自动两种触发方式
4. 其他 bug 修复和界面调整
## 从源码编译
版本依赖：
- nodejs：v20.12.2
- electron：26.2.4
1. 安装 & 配置 yarn
```cmd
npm install -g yarn
yarn config set ELECTRON_MIRROR https://registry.npmmirror.com/-/binary/electron/
yarn config set ELECTRON_BUILDER_BINARIES_MIRROR https://registry.npmmirror.com/-/binary/electron-builder-binaries/
yarn config set registry https://registry.npmmirror.com/
```
2. 下载依赖包
```cmd
yarn
```
3. 生成可执行文件
```cmd
yarn package
```
##
## 与作者交互
您对软件有任何批评建议，可以加我微信沟通，二维码如下：
如果觉得帮到了你，可以不吝打赏一个鸡腿哦，打赏二维码如下：
