代理 API

Important

由于 v3.3.1,每个开发代理 API 请求都需要 Authorization: Bearer <token> 标头;请求没有有效的令牌返回 401 Unauthorized。

开发代理附带一个 Web API,可用于以编程方式与代理交互。 API 在 代理设置中指定的 IP 地址和端口上可用。

开发代理为每个正在运行的实例生成唯一令牌,并将其存储在仅可供启动实例的用户访问的文件中。 使用 devproxy status 或 devproxy api token. 获取令牌。 CI设置环境变量时,请使用devproxy api token,因为开发代理省略状态和启动输出中的令牌。

若要使用已知令牌而不是生成的令牌,例如,当另一个工具启动开发代理并调用其 API 时,请在启动开发代理之前设置 DEV_PROXY_API_TOKEN 环境变量,或使用此选项传递它 --env 。 该值长度必须至少为 32 个字符,不计算尾随=填充,并且只能包含 ASCII 字母、数字和字符-、.、、_+~、和/(可选)后跟=填充。 开发代理会剪裁周围的空格。 如果值无效,则开发代理不会启动并退出并显示错误。 开发代理仍存储令牌,因此 devproxy status, devproxy api token并保持 devproxy stop 正常运行。

在标头中包含 Authorization 令牌:

Authorization: Bearer <token>

没有有效令牌返回 401 Unauthorized的请求。 浏览器请求还必须来自设置中列出的 apiAllowedOrigins 源。 其他源返回 403 Forbidden。

Operations

以下列表显示了可用的 API 操作。

GET /proxy

返回一个实例, ProxyInfo 其中包含有关当前正在运行的开发代理实例的信息。

示例:获取有关当前正在运行的开发代理实例的信息

请求:

GET http://localhost:8897/proxy
Authorization: Bearer <token>

响应:

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

POST /proxy

控制当前正在运行的开发代理实例。 若要从脚本或 CI 管道启动和停止录制,请参阅 脚本和 CI 中的记录。

示例:开始录制

请求:

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": true
}

响应:

200 OK

{
  "recording": true,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

示例:停止录制

请求:

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": false
}

响应:

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

停止录制和生成报告

停止录制不仅仅是停止捕获请求。 在开发代理录制时发送 {"recording": false} 时,Dev Proxy 会按照配置文件中列出的顺序将记录的请求传递给所有已启用的插件。 这与运行开发代理的 控制台中的按下 相同。 在此步骤中:

  • 报告插件 分析记录的请求并生成报告。
  • 记者 将报告转换为文件。 每个记者为每个报告写入一个文件,例如ExecutionSummaryPlugin_MarkdownReporter.md,命名<plugin>_<reporter>.<extension>。 <plugin> 是生成报表的插件实例的名称,是 <reporter> 报告实例的名称。 如果已存在具有该名称的文件,则记者会追加时间戳, ExecutionSummaryPlugin_MarkdownReporter_20261105114500.md例如。
  • 生成器插件,例如 OpenApiSpecGeneratorPlugin,编写它们生成的文件。

开发代理将这些文件写入其当前工作目录,这是从中启动开发代理的目录。

所有插件完成处理记录的请求后,API 都会做出响应。 根据所使用的插件(例如,调用语言模型的插件)可能需要一段时间,因此请确保 HTTP 客户端不会太早超时。 响应到达时,报表文件将写入磁盘。

开发代理还会记录处理记录的请求的进度:

日志消息 Meaning
DONE 所有插件都已完成处理记录的请求。
No requests to process 插件未找到要分析的任何记录请求。
An error occurred in a plugin 插件失败。 当所有插件完成后,开发代理将继续执行下一个插件和日志 DONE 。

如果发送 {"recording": false}时开发代理未录制,则开发代理不会处理任何请求,不写入任何文件,也不会记录 DONE。

Tip

如果在录制时停止开发代理, POST /proxy/stopproxy 开发代理也会在退出之前处理录制的请求。 但是,该 API 会立即响应,因此需要等待开发代理进程退出,知道报表已准备就绪。 若要确切了解报表何时准备就绪,请首先停止录制,等待响应,然后停止开发代理。

有关启动开发代理的完整脚本,控制通过 API 录制,并等待开发代理完成,请参阅 在 CI/CD 方案中使用开发代理。

POST /proxy/jwtToken

生成 JSON Web 令牌(JWT)。

请求:

POST http://localhost:8897/proxy/jwtToken
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Dev Proxy",
  "audiences": [
    "https://myserver.com"
  ],
  "issuer": "dev-proxy",
  "roles": [
    "admin"
  ],
  "scopes": [
    "Post.Read",
    "Post.Write"
  ],
  "claims": {
    "claim1": "value",
    "claim2": "value"
  },
  "validFor": 60
}

注意

已注册的声明(例如,、iss、subaud、exp、nbf、iat)jti会自动添加到令牌中。 如果在请求中指定这些声明中的任何一个,API 将忽略你提供的值。

响应:

200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IkRldiBQcm94eSIsInN1YiI6IkRldiBQcm94eSIsImp0aSI6IjkyZjM5YzciLCJzY3AiOlsiUG9zdC5SZWFkIiwiUG9zdC5Xcml0ZSJdLCJyb2xlcyI6ImFkbWluIiwiY2xhaW0xIjoidmFsdWUiLCJjbGFpbTIiOiJ2YWx1ZSIsImF1ZCI6Imh0dHBzOi8vbXlzZXJ2ZXIuY29tIiwibmJmIjoxNzI3MTk4MjgyLCJleHAiOjE3MjcyMDE4ODIsImlhdCI6MTcyNzE5ODI4MiwiaXNzIjoiZGV2LXByb3h5In0.E_Gj9E58OrAh9uHgc-TW8DYfq8YHFrhaUTpKA4yXEIg"
}

GET /proxy/logs

返回开发代理日志输出。 等效于 logs 命令。 仅当开发代理在分离模式下运行时,此终结点才可用。 否则,API 返回 404 Not Found。

查询参数 描述 默认
lines 要从日志末尾返回的行数 50
follow 当 true,将新的日志行作为服务器发送的事件流式传输 false
since 仅返回自指定日期和时间以来记录的行。 使用持续时间(例如、、、)或 ISO 8601 日期和时间(例如,2026-01-24T14:00:00或2026-01-24T14:00:00Z)。 1d1h5m30s 如果时间戳不包括时区偏移量,则开发代理使用本地时区。 n/a

参数 since 按日志行的完整日期和时间筛选日志行,同时返回日志行和流式传输日志行时。 开发代理按启动时间筛选每个请求,因此即使以后完成,也不会返回在指定时间之前启动的请求。

默认情况下,API 以纯文本形式返回日志行。 若要获取日志条目的 JSON 数组,请将 Accept 标头设置为 application/json。 若要将日志行作为服务器发送的事件流式传输,请将Accept标头text/event-stream设置为或设置为 truefollow 。

请求:

GET http://localhost:8897/proxy/logs?lines=10
Authorization: Bearer <token>

响应:

200 OK
content-type: text/plain

[last 10 lines of the Dev Proxy log]

POST /proxy/mockrequest

引发模拟请求。 等效于在运行开发代理的控制台中按 w 。 模拟请求完成后,API 将做出响应。

请求:

POST http://localhost:8897/proxy/mockrequest
Authorization: Bearer <token>

响应:

204 No Content

GET /proxy/rootCertificate?format=crt

下载开发代理用于解密 HTTPS 请求的 PEM(隐私增强邮件)格式的根证书的公钥。 如果要在 Docker 容器中运行开发代理时信任主机上的根证书,此 API 非常有用。

目前,唯一支持的格式是 crt。 如果指定任何其他格式或根本不指定格式,API 将返回 400 错误请求错误。

请求:

GET http://localhost:8897/proxy/rootCertificate?format=crt
Authorization: Bearer <token>

响应:

content-type: application/x-x509-ca-cert

-----BEGIN CERTIFICATE-----
[base64 encoded certificate]
-----END CERTIFICATE-----

POST /proxy/stopproxy

正常关闭开发代理。 如果开发代理正在录制,它会 停止录制并生成报告 ,然后再退出。 在开发代理完成关闭之前,API 会立即响应。

请求:

POST http://localhost:8897/proxy/stopproxy
Authorization: Bearer <token>

响应:

202 Accepted

开发代理在开始关闭后立即返回 202 Accepted 。 响应并不意味着开发代理已退出。 在关闭期间,开发代理:

  1. 停止接受新的代理请求。 如果开发代理注册为系统代理,它将还原以前的系统代理设置。 开发代理最多等待 5 秒才能关闭打开的连接,然后关闭所有剩余的连接。
  2. 停止录制(如果录制已打开),并在录制的请求上运行报告插件,与停止录制时一样。 插件完成后,开发代理将写入报表和日志 DONE。
  3. 删除其实例信息,因此devproxy statusdevproxy stop不再列出它。
  4. 退出代码 0。

在关闭时,开发代理不会从受信任的证书存储中删除其根证书。 若要删除证书,请使用 证书删除。

关闭通常需要几秒钟时间。 报告插件处理大型录制时可能需要更长的时间。 关闭后,API 不再可访问,因此不要轮询 API 以检查开发代理是否已退出。 请改用以下选项之一:

  • 等待输出到退出的进程 ID (PID)。devproxy --detach
  • 在返回退出代码1之前运行devproxy status --pid <pid>,这意味着实例不再运行。 有关详细信息,请参阅 状态。
  • 如果正在录制,请检查开发代理日志 DONE 中是否有消息,开发代理会在报告插件完成后记录该消息。 有关示例,请参阅 在 CI/CD 方案中使用开发代理。

例如,等待分离的开发代理实例在 Linux 或 macOS 上退出:

# DEVPROXY_PID is the PID that devproxy --detach printed
# TOKEN is the API token from devproxy api token
curl -X POST http://localhost:8897/proxy/stopproxy -H "Authorization: Bearer $TOKEN"

while ./devproxy/devproxy status --pid $DEVPROXY_PID > /dev/null 2>&1; do
  sleep 1
done

避免强制终止开发代理进程,例如,使用 kill -9。 以这种方式结束此过程时,开发代理不会刷新录制或还原系统代理设置。 若要从命令行停止开发代理,请使用 stop,这会调用此 API,等待最多 10 秒,让开发代理退出。

模型

ProxyInfo

有关当前正在运行的开发代理实例的信息。

properties 类型 描述
recording boolean 代理当前是否正在记录请求
configFile string 开发代理正在使用的配置文件的路径(只读)

JwtOptions

用于生成 JWT 令牌的选项。

properties 类型 描述
name string 要为其创建令牌的用户的名称
audiences string[] 要为其创建令牌的受众
issuer string 令牌的颁发者
roles string[] 要添加到令牌的角色声明
scopes string[] 要添加到令牌的范围声明
claims KeyValuePair 要添加到令牌的声明
validFor number 令牌有效的持续时间(以分钟为单位)
signingKey string 用于对令牌进行签名的密钥。 长度必须至少为 32 个字符。 如果未指定,请使用随机生成的密钥。

JwtInfo

有关 JWT 令牌的信息。

properties 类型 描述
token string JWT 令牌

另请参阅