# API管理系统中转接口使用说明
> 该功能为V1.5版本新增，文档先出 程序后面更新 ，请等待新版本更新使用，以下为配置教程
# API管理系统操作手册
## 一、概述
本系统用于管理API接口，支持添加、编辑、删除API，并可配置转发、计费、参数说明等功能。本文档将详细介绍各配置项的含义，特别是转发配置中的成功判断类型，帮助管理员快速上手。
---
## 二、添加/编辑API
点击“添加API”或“编辑”按钮，将弹出表单窗口，包含三个标签页：**接口信息**、**参数内容**、**计费模式**。
### 2.1 接口信息
#### 基础信息
| 字段 | 说明 |
|------|------|
| 选择分类 | 选择API所属的分类（需先添加分类） |
| API名称 | 接口的名称，如“IP查询” |
| API关键词 | 用于搜索的关键词，多个用英文逗号隔开 |
| API简介 | 简要描述接口功能 |
| 接口地址 | 完整的调用地址（例如：`https://api.example.com/endpoint`） |
| 接口目录名 | 用于生成调用URL的标识，例如 `ip`，调用时可通过 `apis.php?api=ip` 访问 |
| 返回格式 | 接口返回的数据格式：json、text、img、audio/mp3、video/mp4 |
| 请求方式 | 客户端调用该接口时使用的HTTP方法（GET/POST/PUT/DELETE/PATCH） |
| 成功返回示例 | 填写一个成功的返回示例，便于测试和文档生成 |
| 接口权重 | 数字越大，在列表中的排名越靠前 |
| 接口实名可用 | 无需实名 / 需要实名（控制是否要求用户实名认证） |
| 公告开关 | 开启后可在下方填写公告内容，用户调用时会显示 |
| 公告内容 | 公告文本，支持HTML |
#### 转发配置
> 当需要将当前接口的请求转发到第三方接口时，配置此部分。所有转发配置项会统一保存在数据库的 `forward_config` JSON字段中。
| 字段 | 说明 |
|------|------|
| 接口地址 | 第三方目标接口的完整URL |
| 请求方式 | 转发给第三方接口时使用的HTTP方法（GET/POST） |
| 秘钥值 | 对方接口需要的秘钥/令牌（如 `api_secret`） |
| 秘钥参数名 | 发送秘钥时使用的参数名，例如 `apikey`、`token` |
| 传递位置 | 秘钥的放置位置：**请求头 (Header)** 或 **请求参数 (Query)** |
| 成功类型 | 判断本次转发是否成功的规则类型（详见下文） |
| 判断规则 | 与成功类型配合使用的规则内容 |
### 2.2 成功判断类型详解
在转发请求后，系统需要根据目标接口的返回内容判断是否成功。您可以根据返回的格式选择不同的判断方式。
| 类型 | 说明 | 规则格式 | 示例 |
|------|------|----------|------|
| **JSON字段匹配** | 当返回为JSON时，检查指定字段的值是否等于期望值 | `字段路径=期望值` | `code=0`
`data.status=success` |
| **JSON路径匹配** | 使用JSONPath表达式定位值并比较 | `$.路径=期望值` | `$.data[0].id=100` |
| **文本包含关键词** | 返回为纯文本时，判断是否包含指定关键词 | `关键词` | `success`
`操作成功` |
| **文本正则匹配** | 使用正则表达式匹配返回文本 | `正则表达式` | `/成功/`
`/^OK$/` |
| **HTTP状态码等于** | 检查HTTP状态码是否等于指定值 | `状态码` | `200`
`404` |
| **HTTP状态码范围** | 检查状态码是否在指定范围内 | `起始-结束` | `200-299`
`400-499` |
| **响应头包含** | 检查响应头中是否存在指定键值对 | `头字段=值` | `Content-Type=application/json`
`X-Status=success` |
**注意事项：**
- JSON路径匹配目前支持简单的点号和数组索引语法（如 `$.store.book[0].title`），如需复杂表达式可等待后续扩展。
- 文本正则匹配时，规则中不要包含定界符（如 `/`），系统会自动添加 `#` 作为定界符。
- 响应头字段名不区分大小写。
### 2.3 参数内容
#### 请求参数说明
用于定义接口需要的输入参数，方便生成文档和前端校验。表格包含：
- **参数名称**：字段名
- **是否必填**：是/否
- **参数类型**：string、int、Array、float、bool
- **参数说明**：描述
- **操作**：删除行
**固定行**：第一行默认为 `apikey`，必填，类型string，说明“你开通的apikey”，可删除。
#### 返回参数说明
定义接口成功返回的数据字段，用于文档展示。表格包含：
- **参数名称**：字段名（支持点号嵌套，如 `data.user.id`）
- **参数类型**：同上
- **参数说明**：描述
- **操作**：删除行
**便捷工具**：点击“从JSON生成”可将成功返回示例的JSON自动解析并填充表格。
### 2.4 计费模式
| 选项 | 说明 |
|------|------|
| 按量计费 | 每次调用扣除固定点数（在“接口价格”中设置） |
| 包月计费 | 提供套餐，用户购买后可在有效期内无限次调用 |
| 会员组 | 仅限指定会员组免费使用 |
- **接口价格**：按量计费时，每次调用消耗的点数。
- **包月套餐**：格式 `金额-天数`，一行一个，例如：`9.9-30` 表示30天9.9元。
- **会员可用**：选择允许免费使用的会员组（需先配置会员组）。
---
## 三、常见问题
### 3.1 为什么我的转发请求返回了301？
目标接口可能发生了URL变更，请在cURL配置中启用自动跟随重定向（代码中已默认启用）。若仍不行，请检查目标接口是否强制HTTPS。
### 3.2 如何调试转发是否成功？
可临时在代码中加入日志记录，输出 `$response` 和 `$http_code`。也可以使用浏览器开发者工具观察网络请求。
### 3.3 成功判断规则未生效？
- 检查规则格式是否正确，特别是JSON字段匹配时字段路径是否存在。
- 检查返回内容是否为有效JSON（可用在线工具验证）。
- 若使用文本正则，注意正则表达式是否包含特殊字符，建议先用在线正则测试。
---
本手册将持续更新，如有疑问请联系技术支持。