# 网络与 HTTP

> 没有高层 HTTP 客户端 —— 在绘制线程之外使用 java.net/OkHttp，用 Jackson 处理 JSON。

Source: https://crossfly.dev/zh/docs/data-and-services/networking-http — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 网络与 HTTP

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

## 强制性规则
**在绘制线程之外发起请求**，并**用 `Component.onUI(...)` 回来**操作 UI（见
[后台工作](/docs/data-and-services/background-work)）。

## 下载字节 —— `Utils.getRemoteFile(url)`
用于下载某个 URL 内容的快捷方式：
```java
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`）：
```java
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](/docs/platforms)）。

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

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

## 另见
- [后台工作](/docs/data-and-services/background-work) · [状态管理](/docs/data-and-services/state-management)