调用外部程序

外部程序概述

定义和基本概念

外部程序是指存储在 “外部程序目录” 中的可执行代码文件。这些文件可以是：

Java 程序归档文件（JAR 包）

其它编程语言的源代码文件

可执行脚本文件

支持的文件类型

支持以下文件格式：

.jar - Java 归档文件

.php - PHP 脚本文件

.js - JavaScript 文件

.py - Python 脚本文件

.bsh - BeanShell 脚本

.go - Go 源代码文件

.sh - Shell 脚本

.rb - Ruby 脚本

.lua - Lua 脚本

.rs - Rust 源代码文件

.bat - Windows 批处理文件

.ps1 - PowerShell 脚本文件

请注意：外部程序在 “沙盒环境” 之外运行，具有访问和操作计算机上其他程序、文件及数据的权限。使用时请确保程序的安全性，谨防潜在风险。

外部程序目录配置

打开 Apifox 应用

点击页面右上角的 “设置”

在弹出的面板中选择 “外部程序” 选项

设置或查看外部程序目录位置

调用原理

调用流程

Apifox 调用外部程序的过程分为三个核心步骤：

命令拼接：根据用户提供的参数构建完整的命令字符串

命令执行：启动子进程运行构建的命令

结果返回：捕获并返回程序的标准输出

命令拼接规则

完整命令的构成：命令前缀 + 程序路径 + 参数列表

示例：

支持的编程语言对照表

语言	命令前缀	程序扩展名
Java	`java -jar`	`.jar`
Python	`python`	`.py`
PHP	`php`	`.php`
JavaScript	`node`	`.js`
BeanShell	`java bsh.Interpreter`	`.bsh`
Go	`go run`	`.go`
Shell	`sh`	`.sh`
Ruby	`ruby`	`.rb`
Lua	`lua`	`.lua`
Rust	`cargo run`	`.rs`
Windows批处理	`cmd /c`	`.bat`
PowerShell	`powershell`	`.ps1`

调用示例

在 Apifox 中调用外部程序可以使用 pm.executeAsync() 方法，其语法如下，可将其写在接口的 “前置/后置操作” 中：

其内各项参数表示如下：

filePath （string）: 外部程序路径。

args （string[]）: 传递给外部程序的参数，数组中每个字符串代表一个参数。

options （Object）: 其它选项设置。

Apifox 会通过 pm.executeAsync() 方法执行外部程序。该方法生成一个命令行，并在子进程中运行指定的外部程序，然后返回该程序的标准输出（stdout）。

举个例子，调用 pm.executeAsync('add.py', ['2', '3']) 实际执行的是命令 python add.py 2 3。

举个更具体的例子。

假设你有一个 Python 脚本，用于计算两个数字的和。现在，你想在 Apifox 中调用这个外部的 Python 脚本，就可以使用 pm.executeAsync() 方法，具体如下。

步骤 1：准备外部程序

首先，创建一个 Python 文件并将其放到 “外部程序目录” 的根目录下，例如 add.py，它从命令行参数获取输入并打印结果：

外部程序建议先进行单独测试，确保其可以独立运行并产生预期结果，然后再在 Apifox 中调用，例如使用命令行 python add.py 2 3 或 python3 add.py 2 3 运行这个文件，就会打印出结果。

步骤 2：在 Apifox 中调用

在 Apifox 中，可以在 “前置/后置操作” 中创建一个自定义脚本，并通过 pm.executeAsync() 方法调用外部程序，示例如下：

传递的参数除了常量/固定值以外，你还可以通过变量的方式进行传递，例如：

当你在 Apifox 中发送请求时，会执行这个 JavaScript 脚本，并通过生成的命令调用外部程序 add.py，以获取外部程序的输出结果，如下图所示：

外部程序应先独立测试，确保能按预期输出结果。

返回结果为字符串类型，可根据需要进行转换。

你可以将返回值存储到环境变量，便于后续使用：pm.environment.set('变量名', '变量值');

更具体的例子可参考这篇最佳实践《如何在 Apifox 中调用其他语言（Java、PHP、Python、Go 等）》

API 参考

pm.executeAsync

推荐使用的方法，支持异步调用，避免阻塞 UI 线程。

语法

参数说明

filePath (string): 外部程序的路径

args (string[]): 传递给程序的参数数组

options (Object): 可选配置项

command (string): 自定义命令前缀（如 python3）

cwd (string): 子进程工作目录（默认：外部程序目录）

env (Object): 子进程环境变量

windowsEncoding (string): Windows 系统的编码格式（默认："cp936"）

className (string): JAR 包类名

method (string): JAR 包方法名

paramTypes (string[]): 方法参数类型

示例

pm.execute (遗留方法)

不推荐，建议使用pm.executeAsync替代此方法，因为pm.execute会阻塞UI线程。

语法：

参数说明:

filePath string 外部程序路径

args string[] 参数。调用 jar 包中的指定方法时，会使用 JSON.stringify 进行转换。除此之外非 string 类型会进行隐式类型转换自动转换为 string 类型。

options Object

windowsEncoding string Windows 系统用使用的编码格式。非必填，默认为 "cp936"。

className string 指定 jar 包中调用的类名，例如 "cn.apifox.Utils"。非必填。

method string 指定 jar 包中调用的方法名，例如 "add"。非必填（className有值时为必填）。

paramTypes string[] 指定 jar 包中调用的方法参数类型，例如 ["int", "int"]。非必填，默认根据参数自动推断。

返回：string

从`pm.execute`迁移到`pm.executeAsync`

由于 pm.executeAsync 的返回值是 Promise 类型，这导致不可以直接将旧代码中的 execute 改为 executeAsync。但是可以使用 async/await 方式，在最小改动的前提下，迁移代码。

具体操作如下：

将 execute 改为 executeAsync

在方法调用前添加 await 关键字

修改前

修改后

程序执行

执行过程

执行外部程序时，系统会：

在控制台显示执行的命令

输出程序的标准输出(stdout)

输出程序的标准错误(stderr)

执行结果判定

pm.executeAsync: 通过程序退出码判断执行状态

pm.execute: 通过标准错误输出判断执行状态

调试方法

可将控制台显示的命令复制到终端中直接执行

利用标准错误输出进行调试信息输出

外部程序的输入输出处理

外部程序可以通过命令行参数获取到执行时从 Apifox 传递的参数。

参数传递

参数通过命令行方式传递，各语言获取方式示例：

JavaScript

Python

返回值处理

程序可通过 “标准输出” 返回结果：

错误处理

调试信息

Java JAR 包调用

特殊调用机制

此功能仅支持可直接反射调用的 JAR 包。不支持如 Spring Boot 等需要内部运行时进行反射调用的 JAR 包。

JAR 包调用有两种方式：

默认方式：调用 Main 类的 main 方法

指定方式：通过反射调用指定类的特定方法

方法调用规范

参数类型说明

支持的参数类型包括：

基本类型："int", "long", "boolean", "double", "float", "short"

包装类型："Integer", "Long", "Boolean", "Double", "Float", "Short"

字符串："String"

数组类型："int[]", "String[]", "Integer[]"等

如果不指定 paramTypes，系统会自动推断类型：

整数 → "int"

浮点数 → "double"

布尔值 → "boolean"

字符串 → "String"

数组根据第一个元素类型推断

代码示例

PHP 示例

脚本调用

外部程序 PHP 代码

JAR 包示例

点击下载 cn.apifox.utils.jar 示例包

脚本调用

外部程序 Java 代码

Python 示例

脚本调用

外部程序 Python 代码

常见问题与解决方案

项目配置文件问题

问题：Rust 或 Go 项目找不到配置文件

解决方案：

Python 版本问题

问题：MacOS 默认使用 Python3

解决方案：

命令查找问题

问题：系统提示找不到命令

解决方案：

安装相应的程序

确保程序路径已添加到系统 PATH

Java 环境配置参考安装文档

中文编码问题

问题：Windows 系统下中文显示乱码

解决方案：

Python 编码错误

问题：Windows 系统下 Python 出现编码相关错误

解决方案：

最佳实践建议

优先使用 pm.executeAsync 而不是 pm.execute

总是进行错误处理

使用 try-catch 捕获可能的异常

为跨平台兼容性考虑编码问题

谨慎处理用户输入，避免命令注入风险

外部程序概述#

定义和基本概念#

支持的文件类型#

外部程序目录配置#

调用原理#

调用流程#

命令拼接规则#

支持的编程语言对照表#

调用示例#

步骤 1：准备外部程序#

步骤 2：在 Apifox 中调用#

API 参考#

pm.executeAsync#

pm.execute (遗留方法)#

从pm.execute迁移到pm.executeAsync#

程序执行#

执行过程#

执行结果判定#

调试方法#

外部程序的输入输出处理#

参数传递#

返回值处理#

错误处理#

调试信息#

Java JAR 包调用#

特殊调用机制#

方法调用规范#

参数类型说明#

代码示例#

PHP 示例#

JAR 包示例#

Python 示例#

常见问题与解决方案#

项目配置文件问题#

Python 版本问题#

命令查找问题#

中文编码问题#

Python 编码错误#

最佳实践建议#

外部程序概述

定义和基本概念

支持的文件类型

外部程序目录配置

调用原理

调用流程

命令拼接规则

支持的编程语言对照表

调用示例

步骤 1：准备外部程序

步骤 2：在 Apifox 中调用

API 参考

pm.executeAsync

pm.execute (遗留方法)

从`pm.execute`迁移到`pm.executeAsync`

程序执行

执行过程

执行结果判定

调试方法

外部程序的输入输出处理

参数传递

返回值处理

错误处理

调试信息

Java JAR 包调用

特殊调用机制

方法调用规范

参数类型说明

代码示例

PHP 示例

JAR 包示例

Python 示例

常见问题与解决方案

项目配置文件问题

Python 版本问题

命令查找问题

中文编码问题

Python 编码错误

最佳实践建议