接口约定

基础 URL

本文统一使用：

{baseUrl} = http://主机:端口/<安全入口>

实际接口为 {baseUrl}/api/...。OpenAPI 中的 safeEntry 是占位变量，默认值不对应真实实例。

请求格式

• 鉴权头：openToken。
• 常见内容类型：application/json。
• 文件上传、下载、备份和导入接口可能使用 multipart 或二进制响应。
• WebSocket 接口由前端先生成连接 URL，或直接位于 /api/.../ws、/connect/...、/attach/...。
• 字段名大小写并不统一，需保持前端或 GET 返回对象中的原样。

响应包络

常见成功结构：

{
  "ret": 0,
  "data": {}
}

其他端点可能返回 list、info、Modules 等顶层字段；下载接口则直接返回文件。不要假设所有接口都严格遵循同一 schema。

ret: 0 只是最常见的成功约定，不是全局不变量。Lucky 3.0.0 已实测存在成功写接口返回非零 ret 的情况；这类例外必须按具体 METHOD + path 写入运行时目录的 success_response_markers，并精确记录 ret + msg 组合，客户端才会接受。未在目录中明确验证的非零 ret 仍按业务错误处理。

客户端至少应同时检查：

1. HTTP 状态码；
2. 响应 Content-Type；
3. JSON 中的 ret，以及该端点是否有运行时验证过的精确成功响应标记；
4. 可选的 msg 错误说明。

Lucky 历史接口可能以 HTTP 200 返回业务错误，所以仅调用 raise_for_status() 不足以判断成功。

方法语义

大体约定如下：

• GET：查询列表、状态、日志和配置；
• POST：创建、触发、导入或执行动作；
• PUT：更新、排序、启用/禁用或整体保存；
• DELETE：删除或清理。

但不能把所有 GET 当成无副作用。已经观察到或历史存在的例外包括重启程序、唤醒/关机、立即执行任务、手动同步和启用开关。因此自动化客户端应对路径建立显式只读白名单。

更新配置的安全模式

闭源后端对缺失字段是“保留旧值”还是“写入零值”没有统一保证。推荐流程：

1. GET 当前配置；
2. 深拷贝完整对象；
3. 只修改目标字段；
4. 发送完整对象；
5. 再次 GET 验证；
6. 保留脱敏前后差异和回滚数据。

不要直接根据旧版本示例构造一个字段不全的 PUT 请求。

限流

Lucky 3.0.0 本机状态接口实测返回：

RateLimit-Limit: 20
RateLimit-Remaining: <动态值>
RateLimit-Reset: 1
X-Rate-Limit-Duration: 1

可将其理解为当前实例约 20 请求/秒的窗口，但不同接口、版本和配置可能不同。建议普通状态轮询不高于每 2 秒一次，收到 429 时按 RateLimit-Reset 或指数退避重试。

并发和幂等性

没有证据表明写接口支持 ETag、If-Match 或幂等键。避免并行写同一配置；创建、导入、触发任务和容器操作在超时后不要盲目重试，先查询当前状态。

版本漂移

Lucky 后续版本并无继续开源计划，前端与后端接口可随版本变化。客户端应在启动时读取 /api/info，对未验证版本拒绝写操作，并保留版本到端点快照的映射。

仓库内客户端的具体错误、重试和写确认行为见安全 API 客户端与 CLI。