尧图网页设计 
qBittorrent 如何编写调用 WebUI 的客户端并适配 API 变化【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent你遇到的任务是写一个脚本或程序通过 qBittorrent 的 WebAPI 完成添加种子、同步状态、控制会话等操作并且希望在 qBittorrent 升级后能快速发现并修复 WebAPI 的破坏性变化。完成这篇文章后你会有一条从「验证服务可达 → 建立认证 → 拉取数据 → 执行写操作 → 对照 changelog 适配变更」的连续路径。前提是你已经安装并启动了 qBittorrent 且开启了 WebUI默认端口 8080见 Preferences 默认值并知道 WebUI 的登录账号密码。WebAPI 的暴露方式与版本查询所有接口都挂在基础路径/api/v2/下webapplication.cpp 中API_PATH u/api/v2/_s请求形如http://主机:8080/api/v2/scope/action例如api/v2/torrents/info。两个版本接口要区分开app/version返回 qBittorrent 程序版本号appcontroller.cpp 中返回QBT_VERSIONapp/webapiVersion返回 WebAPI 自身的版本号当前仓库中该常量定义为2.16.2webapplication.h 中API_VERSION {2, 16, 2}。适配 API 变化时你真正需要比对的是后者。除auth/login被声明为公开接口webapplication.cpp 中declarePublicAPI(uauth/login...)外访问其他端点时如果没有有效会话会直接收到 403。所以客户端的第一步永远是先认证。认证方式一用户名密码登录并持有会话 CookieWebUI 自带的登录脚本就是 WebAPI 调用的参照实现以表单编码 POSTusername、password到auth/loginlogin.js。服务端校验通过后建立会话并在响应中下发一个 httpOnly 的会话 Cookie名称前缀为QBT_SID_webapplication.cpp。凭据无效时返回 401。用 curl 验证这条路径把USER、PASS替换为你的 WebUI 账号密码127.0.0.1:8080替换为实际地址端口# 登录成功时返回 200并把会话 Cookie 写入 cookies.txt curl -c cookies.txt \ -d usernameUSER -d passwordPASS \ http://127.0.0.1:8080/api/v2/auth/login # 后续请求携带 Cookie若凭据错误第一步会收到 401 curl -b cookies.txt http://127.0.0.1:8080/api/v2/app/version客户端需要长期保存并复用这个 Cookie会话在服务端有超时Cookie 过期后服务端会丢弃该会话webapplication.cpp 中cookieSessionInitialize对过期会话直接删除。另一个可选方式自 2.15.0 起WebAPI 凭据可以直接通过 HTTP Basic auth 提供curl 写作curl -u USER:PASS http://127.0.0.1:8080/api/v2/app/version无需先调用auth/login。注意 CSRF 保护默认开启非 API Key 的跨站请求会被拒绝为 401webapplication.cpp 中的isCrossSiteRequest检查。对 curl/脚本这类不带Origin/Referer头的客户端服务端按宽松策略放行但如果你要从浏览器页面跨站调用必须改用 API Key。认证方式二API Key推荐用于长期运行的客户端自 2.14.1 起新增了app/rotateAPIKey生成并轮换 API Key和app/deleteAPIKey删除现有 Key。先登录再调用app/rotateAPIKey# 需要已登录的 Cookie响应为 JSON{apiKey: 生成的 Key} curl -b cookies.txt -X POST http://127.0.0.1:8080/api/v2/app/rotateAPIKey之后的每个请求携带Authorization: Bearer头即可不再依赖 Cookie 会话# 将 apiKey 替换为上一步响应 JSON 中的 apiKey 字段值 curl -H Authorization: Bearer apiKey http://127.0.0.1:8080/api/v2/sync/maindataAPI Key 行为有两处与 Cookie 会话不同webapplication.cpp使用Bearer认证时跳过 CSRF 检查使用Bearer认证访问auth/*端点会返回 403——API Key 会话不需要也不允许再走登录/登出。如果服务端从未配置过 Keyapp/rotateAPIKey的调用仍会生效它生成并写入新 KeyKey 会保存到偏好项web_ui_api_keyappcontroller.cpp也可以在 WebUI 偏好界面查看/轮换。拉取数据sync/maindata 与 rid 增量机制状态同步主接口是sync/maindata它通过ridresponse id实现增量更新synccontroller.cpp# 首次调用不带 rid返回完整快照full_update 为 true及一个 rid curl -b cookies.txt http://127.0.0.1:8080/api/v2/sync/maindata # 之后把上一次响应中的 rid 作为查询参数传回只获取增量 curl -b cookies.txt http://127.0.0.1:8080/api/v2/sync/maindata?rid上次返回的rid响应包含full_update、rid以及torrents、categories、tags、trackers、server_state等字段键定义见 synccontroller.cpp。WebUI 自身客户端的写法可作参照请求带cache: no-store每次从响应中取出新的rid用于下一次轮询client.js 中syncMainData。你的客户端应实现同样的循环记录rid→ 轮询 → 更新本地状态 → 若full_update为 true 则整体重建。执行写操作先约定好状态码语义写操作集中在torrents/*、transfer/*、app/setPreferences等端点参数以表单字段或查询参数传递。以下状态码约定是客户端必须处理的都来自 WebAPI_Changelog.md场景行为版本torrents/add响应包含success_count、pending_count、failure_count、added_torrent_idspending_count非零时返回 202全部失败时返回 4092.14.0响应体无数据返回204 No Content部分端点过渡期仍返回 200 OK2.11.8端点不存在错误消息为Endpoint does not exist用于区别于普通的 4042.14.0auth/login凭据无效返回 4012.14.0torrents/editTracker成功时固定返回 2042.13.0客户端不要假设所有成功都是 200也不要把所有 204 当成失败。以torrents/add为例一个健壮的判断顺序是先读状态码202 表示部分待处理、409 表示全部失败再解析响应体中的计数字段。适配 API 变化版本号对照 changelog客户端在启动或每次部署后应先用认证后的会话请求app/webapiVersion把返回值与 WebAPI_Changelog.md 中你当前支持版本之后的条目逐一比对。以下是 changelog 中与「客户端兼容性」直接相关的破坏性变化每条均可在 changelog 中按 PR 号核对2.16.0search/downloadTorrent与rss/setFeedRefreshInterval改为仅接受 POSTtorrents/add新增seedMode(bool) 参数且不再接受skip_checking参数。如果你的客户端还在发skip_checking升级后该参数会被忽略应切换到seedMode。2.16.2新增rss/exportRules、rss/importRules仅 POST新增transfer/pauseSession、transfer/resumeSessionsync/maindata的server_state中新增session_state(bool) 字段——依赖server_state结构的代码要注意新字段的出现。2.14.0torrents/add引入上表所述的计数字段与 202/409 状态码不存在的端点开始返回Endpoint does not exist文案。2.13.0torrents/editTracker的参数origUrl更名为url旧参数名不再可用。2.15.0起可用 Basic auth 提供凭据对旧客户端是可选的新路径不是破坏项。排查方向可以由状态码反推401 优先检查凭据或跨站来源403 检查会话是否过期、是否在用 API Key 访问auth/*405 Method Not Allowed 通常意味着该端点已改为仅 POST对照 2.16.0/2.16.2 条目收到Endpoint does not exist则说明端点被移除或更名回 changelog 找对应版本的替换项。限制与边界公开端点只有auth/login其余全部依赖会话用 API Key 认证时auth/*端点被禁止403。会话 Cookie 有服务端超时客户端需要处理 Cookie 失效后重新登录的分支。各版本新增的参数如torrents/add的seedMode、sync/maindata的session_state只在对应版本起可用跨版本部署的客户端应以app/webapiVersion的返回值决定行为分支。【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 qBittorrent 如何编写调用 WebUI 的客户端并适配 API 变化？
qBittorrent 如何编写调用 WebUI 的客户端并适配 API 变化【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent你遇到的任务是写一个脚本或程序通过 qBittorrent 的 WebAPI 完成添加种子、同步状态、控制会话等操作并且希望在 qBittorrent 升级后能快速发现并修复 WebAPI 的破坏性变化。完成这篇文章后你会有一条从「验证服务可达 → 建立认证 → 拉取数据 → 执行写操作 → 对照 changelog 适配变更」的连续路径。前提是你已经安装并启动了 qBittorrent 且开启了 WebUI默认端口 8080见 Preferences 默认值并知道 WebUI 的登录账号密码。WebAPI 的暴露方式与版本查询所有接口都挂在基础路径/api/v2/下webapplication.cpp 中API_PATH u/api/v2/_s请求形如http://主机:8080/api/v2/scope/action例如api/v2/torrents/info。两个版本接口要区分开app/version返回 qBittorrent 程序版本号appcontroller.cpp 中返回QBT_VERSIONapp/webapiVersion返回 WebAPI 自身的版本号当前仓库中该常量定义为2.16.2webapplication.h 中API_VERSION {2, 16, 2}。适配 API 变化时你真正需要比对的是后者。除auth/login被声明为公开接口webapplication.cpp 中declarePublicAPI(uauth/login...)外访问其他端点时如果没有有效会话会直接收到 403。所以客户端的第一步永远是先认证。认证方式一用户名密码登录并持有会话 CookieWebUI 自带的登录脚本就是 WebAPI 调用的参照实现以表单编码 POSTusername、password到auth/loginlogin.js。服务端校验通过后建立会话并在响应中下发一个 httpOnly 的会话 Cookie名称前缀为QBT_SID_webapplication.cpp。凭据无效时返回 401。用 curl 验证这条路径把USER、PASS替换为你的 WebUI 账号密码127.0.0.1:8080替换为实际地址端口# 登录成功时返回 200并把会话 Cookie 写入 cookies.txt curl -c cookies.txt \ -d usernameUSER -d passwordPASS \ http://127.0.0.1:8080/api/v2/auth/login # 后续请求携带 Cookie若凭据错误第一步会收到 401 curl -b cookies.txt http://127.0.0.1:8080/api/v2/app/version客户端需要长期保存并复用这个 Cookie会话在服务端有超时Cookie 过期后服务端会丢弃该会话webapplication.cpp 中cookieSessionInitialize对过期会话直接删除。另一个可选方式自 2.15.0 起WebAPI 凭据可以直接通过 HTTP Basic auth 提供curl 写作curl -u USER:PASS http://127.0.0.1:8080/api/v2/app/version无需先调用auth/login。注意 CSRF 保护默认开启非 API Key 的跨站请求会被拒绝为 401webapplication.cpp 中的isCrossSiteRequest检查。对 curl/脚本这类不带Origin/Referer头的客户端服务端按宽松策略放行但如果你要从浏览器页面跨站调用必须改用 API Key。认证方式二API Key推荐用于长期运行的客户端自 2.14.1 起新增了app/rotateAPIKey生成并轮换 API Key和app/deleteAPIKey删除现有 Key。先登录再调用app/rotateAPIKey# 需要已登录的 Cookie响应为 JSON{apiKey: 生成的 Key} curl -b cookies.txt -X POST http://127.0.0.1:8080/api/v2/app/rotateAPIKey之后的每个请求携带Authorization: Bearer头即可不再依赖 Cookie 会话# 将 apiKey 替换为上一步响应 JSON 中的 apiKey 字段值 curl -H Authorization: Bearer apiKey http://127.0.0.1:8080/api/v2/sync/maindataAPI Key 行为有两处与 Cookie 会话不同webapplication.cpp使用Bearer认证时跳过 CSRF 检查使用Bearer认证访问auth/*端点会返回 403——API Key 会话不需要也不允许再走登录/登出。如果服务端从未配置过 Keyapp/rotateAPIKey的调用仍会生效它生成并写入新 KeyKey 会保存到偏好项web_ui_api_keyappcontroller.cpp也可以在 WebUI 偏好界面查看/轮换。拉取数据sync/maindata 与 rid 增量机制状态同步主接口是sync/maindata它通过ridresponse id实现增量更新synccontroller.cpp# 首次调用不带 rid返回完整快照full_update 为 true及一个 rid curl -b cookies.txt http://127.0.0.1:8080/api/v2/sync/maindata # 之后把上一次响应中的 rid 作为查询参数传回只获取增量 curl -b cookies.txt http://127.0.0.1:8080/api/v2/sync/maindata?rid上次返回的rid响应包含full_update、rid以及torrents、categories、tags、trackers、server_state等字段键定义见 synccontroller.cpp。WebUI 自身客户端的写法可作参照请求带cache: no-store每次从响应中取出新的rid用于下一次轮询client.js 中syncMainData。你的客户端应实现同样的循环记录rid→ 轮询 → 更新本地状态 → 若full_update为 true 则整体重建。执行写操作先约定好状态码语义写操作集中在torrents/*、transfer/*、app/setPreferences等端点参数以表单字段或查询参数传递。以下状态码约定是客户端必须处理的都来自 WebAPI_Changelog.md场景行为版本torrents/add响应包含success_count、pending_count、failure_count、added_torrent_idspending_count非零时返回 202全部失败时返回 4092.14.0响应体无数据返回204 No Content部分端点过渡期仍返回 200 OK2.11.8端点不存在错误消息为Endpoint does not exist用于区别于普通的 4042.14.0auth/login凭据无效返回 4012.14.0torrents/editTracker成功时固定返回 2042.13.0客户端不要假设所有成功都是 200也不要把所有 204 当成失败。以torrents/add为例一个健壮的判断顺序是先读状态码202 表示部分待处理、409 表示全部失败再解析响应体中的计数字段。适配 API 变化版本号对照 changelog客户端在启动或每次部署后应先用认证后的会话请求app/webapiVersion把返回值与 WebAPI_Changelog.md 中你当前支持版本之后的条目逐一比对。以下是 changelog 中与「客户端兼容性」直接相关的破坏性变化每条均可在 changelog 中按 PR 号核对2.16.0search/downloadTorrent与rss/setFeedRefreshInterval改为仅接受 POSTtorrents/add新增seedMode(bool) 参数且不再接受skip_checking参数。如果你的客户端还在发skip_checking升级后该参数会被忽略应切换到seedMode。2.16.2新增rss/exportRules、rss/importRules仅 POST新增transfer/pauseSession、transfer/resumeSessionsync/maindata的server_state中新增session_state(bool) 字段——依赖server_state结构的代码要注意新字段的出现。2.14.0torrents/add引入上表所述的计数字段与 202/409 状态码不存在的端点开始返回Endpoint does not exist文案。2.13.0torrents/editTracker的参数origUrl更名为url旧参数名不再可用。2.15.0起可用 Basic auth 提供凭据对旧客户端是可选的新路径不是破坏项。排查方向可以由状态码反推401 优先检查凭据或跨站来源403 检查会话是否过期、是否在用 API Key 访问auth/*405 Method Not Allowed 通常意味着该端点已改为仅 POST对照 2.16.0/2.16.2 条目收到Endpoint does not exist则说明端点被移除或更名回 changelog 找对应版本的替换项。限制与边界公开端点只有auth/login其余全部依赖会话用 API Key 认证时auth/*端点被禁止403。会话 Cookie 有服务端超时客户端需要处理 Cookie 失效后重新登录的分支。各版本新增的参数如torrents/add的seedMode、sync/maindata的session_state只在对应版本起可用跨版本部署的客户端应以app/webapiVersion的返回值决定行为分支。【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考