MiscAPI
约 604 字大约 2 分钟
2026-03-21
杂项工具 API — 下载、HTTP 请求、代理检查
源码位置:ncatbot/api/misc.py
访问方式:api.misc(与 api.qq / api.github 平级)
概述
MiscAPI 提供与平台无关的 HTTP/下载/代理工具。所有带 proxy 参数的方法遵循统一的代理解析逻辑:
- 显式传入
proxy参数时使用传入值 - 省略时自动读取主配置
http_proxy - 配置也为空时直连
# 插件中使用
path = await self.api.misc.download_to_file(url, "./downloads")
data = await self.api.misc.download_to_bytes(url)
ok = await self.api.misc.is_proxy_valid()⚠️ 网络提醒:从 GitHub 下载资源时(包括通过
Attachment.download()/as_bytes()隐式下载 Release Assets),国内网络可能无法直连。建议开发者在config.yaml中配置http_proxy,或在下载前自行对 GitHub URL 添加镜像前缀(如ghfast.top)以避免网络阻塞。参见 配置文档 中的http_proxy字段。
构造
class MiscAPI:
def __init__(self, config: Config) -> None: ...MiscAPI 在框架启动时由 BotClient._setup_api() 自动创建并注册,无需手动构造。
方法
get_proxy
返回当前主配置中的 http_proxy,无配置时返回 None。
def get_proxy(self) -> str | Nonedownload_to_file
下载 URL 到目录,返回文件路径。
async def download_to_file(
self,
url: str,
dest_dir: str | Path,
*,
filename: str | None = None,
proxy: str | None = None,
) -> Path| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url | str | — | 下载地址 |
dest_dir | str | Path | — | 目标目录(不存在时自动创建) |
filename | str | None | None | 文件名,省略则从 URL 推断 |
proxy | str | None | None | 代理地址,省略则使用主配置 http_proxy |
download_to_bytes
下载 URL 到内存,返回原始字节。
async def download_to_bytes(
self,
url: str,
*,
proxy: str | None = None,
) -> bytes| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url | str | — | 下载地址 |
proxy | str | None | None | 代理地址 |
http_get
异步 GET 请求,返回响应体字节。
async def http_get(
self,
url: str,
*,
headers: dict | None = None,
proxy: str | None = None,
timeout: float = 10.0,
) -> bytes| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url | str | — | 请求地址 |
headers | dict | None | None | 额外请求头 |
proxy | str | None | None | 代理地址 |
timeout | float | 10.0 | 超时秒数 |
is_proxy_valid
检查代理是否可用。
async def is_proxy_valid(self, proxy: str | None = None) -> bool| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
proxy | str | None | None | 要检查的代理地址。省略则检查主配置 http_proxy。配置也为空时直接返回 False |
配置
在 config.yaml 中设置标准 HTTP/SOCKS5 代理:
# 标准 HTTP/SOCKS5 代理(用于 Attachment 下载、MiscAPI 请求等)
http_proxy: "http://127.0.0.1:7890"也可通过环境变量 HTTP_PROXY 设置。
返回:API 参考首页
版权所有
版权归属:huan-yp
