Godot HTTP API 客户端：登录、鉴权、重试和错误码边界

HTTP 接口不该散在每个按钮里

Godot 项目接后端时，很多功能一开始都很直接：登录页发一个 HTTPRequest，商城页发一个购买请求，排行榜页发一个刷新请求。每个页面自己创建节点、拼 URL、处理 JSON。原型能跑，但弱网、鉴权过期、错误码、重复点击、请求取消、日志追踪一来，代码会立刻分裂。

HTTP API 客户端应该是一层基础设施。它负责 base URL、鉴权 token、请求 id、超时、重试、错误码映射、日志和回调生命周期。业务系统只表达“我要登录”“我要刷新背包”“我要领取奖励”，不关心底层是 HTTPRequest 还是 HTTPClient。

flowchart TD
    A[业务请求] --> B[ApiClient]
    B --> C[请求构建/签名]
    C --> D[RequestQueue]
    D --> E[HTTPRequest/HTTPClient]
    E --> F{响应结果}
    F -->|成功| G[解码为领域结果]
    F -->|鉴权过期| H[刷新 Token/重新登录]
    F -->|可重试错误| I[退避重试]
    F -->|业务错误| J[错误码映射]
    G --> K[模型更新/UI反馈]

HTTPRequest 方便，但要统一封装

Godot 的 HTTPRequest 节点很好用，发起请求和接收信号都很直观。问题是它是节点，有生命周期。页面关闭时，节点可能被释放；请求回来时，回调可能访问失效 UI。统一 ApiClient 可以持有请求节点池或独立 HTTPClient，把响应交给模型或 Promise 风格对象，而不是直接回调页面节点。

封装还可以统一 headers、超时和 JSON 解析。不要让每个页面自己写 JSON.parse_string，也不要让每个功能自己判断状态码。HTTP 200 也可能包含业务错误，HTTP 401 也可能需要刷新 token。规则集中，行为才一致。

如果项目有大量并发请求，可以考虑用 HTTPClient 或自己管理请求节点池。简单项目用若干 HTTPRequest 节点也够。关键不是 API 选择，而是业务层不要直接依赖具体节点。

鉴权要有状态机

登录后通常会得到 access token、refresh token、过期时间、账号信息。ApiClient 发送请求前检查 token 状态，必要时刷新。刷新过程中，其他需要鉴权的请求应该排队等待，而不是同时发十个刷新请求。

鉴权过期要区分：access token 过期可刷新，refresh token 过期需要回登录，账号被踢要清理本地状态，服务器维护要进入维护页。UI 不应该自己猜这些状态。ApiClient 或 SessionService 给出明确会话状态。

刷新 token 失败时，要取消或标记队列里的请求。玩家正在领取奖励，如果会话过期，按钮应恢复并提示重新登录，而不是一直转圈。

重试不是所有请求都重试

查询配置、刷新列表、拉排行榜可以自动重试。购买、领取、改名、消耗道具这类事务请求不能盲目重试，除非后端提供幂等 request id。ApiClient 应支持请求策略：是否重试、重试次数、退避时间、是否需要幂等 id。

弱网下，指数退避比固定间隔更友好。第一次失败很快重试，后续逐渐拉长。重试期间 UI 要知道请求仍在进行，必要时允许玩家取消显示。取消显示不一定取消服务端请求，这个边界要讲清楚。

迟到响应也要处理。请求超时后 UI 已经恢复，响应又回来了。ApiClient 要检查请求状态，避免把旧结果应用到新页面。事务请求则要通过 request id 对账。

错误码映射要面向玩家和开发

后端错误码不能直接显示给玩家。客户端需要错误码表：业务含义、玩家文案、是否可重试、是否需要刷新模型、是否需要重新登录、日志等级。比如背包满、活动结束、等级不足、服务器维护，都有不同处理。

错误码表最好是配置或集中代码，不要每个页面 switch 一遍。这样后端新增错误码时，客户端能统一补。未知错误码也要有兜底文案，并把原始码写入日志。

开发调试需要更多信息。测试包可以显示 request id、接口名、HTTP 状态、业务码、耗时。正式包只显示玩家文案，但日志保留可追踪信息。

请求结果先更新模型，再刷新 UI

HTTP 成功返回后，不要直接在页面里改 Label。比如领取奖励成功，应该更新背包模型、活动模型和奖励展示队列。页面监听模型变化刷新。这样同一个接口结果能影响多个 UI，页面关闭后也不会丢状态。

如果接口返回的是局部数据，要明确是否替换模型、合并模型还是触发重新拉取。背包增量、任务进度、商城库存都有不同策略。ApiClient 只负责传输，领域服务负责解释结果。

小结

Godot HTTP API 客户端要把网络细节从页面里收回来。统一请求构建、鉴权状态、重试策略、错误码映射、日志和回调生命周期，业务再通过模型刷新 UI。这样弱网和会话过期不会把每个按钮都变成独立问题，后端接口增长时客户端也能保持一致。
我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。

我会为 ApiClient 做一个网络调试页，列出最近请求、耗时、错误码、重试次数和鉴权状态。接口问题最怕只看到 UI 失败，有这张表后，测试能直接判断是网络、会话还是业务错误。