网络与 HTTP

又是一个坦诚的页面：框架不提供高层 HTTP 客户端（没有向应用暴露符合人体工学的 Http.get()）。你使用 java.net 或某个库（OkHttp 已在 classpath 中，被地图内部使用）。

强制性规则

在绘制线程之外发起请求，并用 Component.onUI(...) 回来操作 UI（见后台工作）。

下载字节 —— `Utils.getRemoteFile(url)`

用于下载某个 URL 内容的快捷方式：

new Thread(() -> {
   byte[] dados = Utils.getRemoteFile("https://api.exemplo.com/dados");  // 出错或在 WebGL 中时为 null
   if (dados == null) { Component.onUI(() -> Hint.show("Falha na rede", 2000)); return; }
   String corpo = new String(dados);
   Component.onUI(() -> mostrar(corpo));
}).start();

⚠️ getRemoteFile 在 HTTP 错误、异常以及在 WebGL/TeaVM 中都会返回 null —— 请始终检查。

用 Jackson（不是 Gson）处理 JSON

项目的默认选择是 Jackson（com.fasterxml.jackson.databind.ObjectMapper）：

ObjectMapper mapper = new ObjectMapper();
new Thread(() -> {
   try {
      byte[] json = Utils.getRemoteFile("https://api.exemplo.com/clientes");
      if (json == null) return;
      List<Cliente> clientes = mapper.readValue(json, new TypeReference<List<Cliente>>(){});
      Component.onUI(() -> lista.setItems(clientes));
   } catch (Exception e) { Debug.log("parse: " + e); }
}).start();

用 `java.net` 进行 GET/POST

当你需要更多控制（headers、POST）时，直接使用 HttpURLConnection/OkHttp —— 始终在后台线程中，结果用 onUI(...) 返回。

⚠️ 在 WebGL/TeaVM 中的限制

在 Web 目标上，HTTP 调用有限制（CORS、没有直接 socket），且 getRemoteFile 返回 null。请处理这种情况，或在 Web 上禁用该功能（见 platforms）。

最佳实践

绝不在绘制线程上进行网络操作 —— UI 会冻结。
用 Jackson，不用 Gson（与项目其余部分保持一致）。
对每个响应都检查 null/异常；通过 Hint/Alert 向用户显示错误。

常见错误

寻找 Http.get()/现成客户端 —— 不存在；请用 java.net/OkHttp。
忽略 getRemoteFile 在 WebGL 中为 null。
直接在网络线程上解析/操作 UI（没有 onUI）。

另见

后台工作 · 状态管理