FlareSolverr

FlareSolverr-go

README.md generated by VSCode Copilot

基于 Go 的 FlareSolverr 客户端，封装了 request.get / request.post、会话管理（sessions.list/create/destroy）等常用命令，并提供便捷的返回结构体与辅助方法。

模块路径：github.com/Miuzarte/FlareSolverr-go

要求

• Go 1.25+
• 运行中的 FlareSolverr 服务端（默认示例使用 http://127.0.0.1:8191/v1）

安装

go get github.com/Miuzarte/FlareSolverr-go

快速开始

package main

import (
	"fmt"
	fs "github.com/Miuzarte/FlareSolverr-go"
)

func main() {
	client := fs.NewClient("http://127.0.0.1:8191/v1")

	// GET 简单示例
	resp, err := client.Get("https://example.com", nil)
	if err != nil {
		panic(err)
	}
	fmt.Println("Status:", resp.Solution.Status)
	fmt.Println("URL:", resp.Solution.URL)
	fmt.Println("UA:", resp.Solution.UserAgent)
	fmt.Println("Body length:", len(resp.Solution.Response))
}

用法示例

基础 GET

resp, err := client.Get("https://example.com", nil)

带参数：

params := map[string]any{
	fs.PARAM_MAX_TIMEOUT: 60000,             // 毫秒
	fs.PARAM_RETURN_SCREENSHOT: false,       // 返回截图 base64
	fs.PARAM_RETURN_ONLY_COOKIES: false,     // 仅返回 cookies
	fs.PARAM_WAIT_IN_SECONDS: 0,             // 等待页面稳定（动态内容）
}
resp, err := client.Get("https://example.com", params)

基础 POST

postData 为 application/x-www-form-urlencoded 的原始字符串：

params := map[string]any{
	fs.PARAM_MAX_TIMEOUT: 60000,
}
resp, err := client.Post("https://httpbin.org/post", "a=b&c=d", params)

代理与会话

params := map[string]any{
	fs.PARAM_PROXY: map[string]any{
		"url": "http://127.0.0.1:7890",
		"username":  "testuser",
		"password":  "testpass",
	},
}

// 预创建会话（可复用浏览器上下文）
_ = client.SessionsCreate("mysess", params)

// 会话内请求
params[fs.PARAM_SESSION] = "mysess"
resp, err := client.Get("https://example.com", params)

// 列出/销毁会话
list, _ := client.SessionsList()
_ = client.SessionsDestroy("mysess")

Cookies 转换为 net/http.Cookie

sol, _ := client.Get("https://example.com", nil)
httpCookies := resp.Solution.Cookies.ToHttpCookies() // []*http.Cookie

原始 Submit 接口

如需发送自定义命令或完全掌控参数，可直接使用 Submit：

resp, err := client.Submit(fs.CMD_REQUEST_GET, map[string]any{
	fs.PARAM_URL:             "https://example.com",
	fs.PARAM_MAX_TIMEOUT:     60000,
	fs.PARAM_RETURN_SCREENSHOT: true,
})
if err != nil {
	// 注意：当 FlareSolverr 返回非 ok 状态时，err 为 Response.Message，且可同时读取 resp 获取详细信息
	fmt.Println("request error:", err)
}
fmt.Println("status:", resp.Status)
fmt.Println("session:", resp.Session)

参数与常量

• 命令（Cmd）：

  • fs.CMD_REQUEST_GET
  • fs.CMD_REQUEST_POST
  • fs.CMD_SESSIONS_LIST
  • fs.CMD_SESSIONS_CREATE
  • fs.CMD_SESSIONS_DESTROY

• 参数键（Param，map[string]any 的 key）：

  • fs.PARAM_URL（string）
  • fs.PARAM_SESSION（string）
  • fs.PARAM_SESSION_TTL_MINUTES（int）
  • fs.PARAM_MAX_TIMEOUT（int，毫秒）
  • fs.PARAM_COOKIES（[]Cookie）
  • fs.PARAM_RETURN_ONLY_COOKIES（bool）
  • fs.PARAM_RETURN_SCREENSHOT（bool）
  • fs.PARAM_PROXY（map[string]any：包含 url、可选 username、password）
  • fs.PARAM_WAIT_IN_SECONDS（int）
  • fs.PARAM_POST_DATA（string）

返回类型

• Response：包含 Status、Message、Version、时间戳、Session/Sessions、Solution 等。
• Solution：页面 URL、HTTP Status、Cookies、UserAgent、Headers、Response（HTML 文本）、Screenshot（base64 PNG）。

错误处理约定：

• HTTP 层非 200 会返回 error（内容为 HTTP 状态）。
• FlareSolverr 返回 status != "ok" 时：同时返回 *Response 与 error（error 为 Response.Message）。

设计细节

• Request 时内部会克隆你传入的 params（使用 Go 1.20+ 的 maps.Clone），避免修改调用方 map。
• Submit 采用 JSON 序列化并通过 Content-Type: application/json POST 到服务端。

许可

遵循与上游相同的开源许可（见仓库 LICENSE）。