Java项目连接SeaweedFS HTTP API应直接调用REST接口，使用OkHttpClient（推荐）或JDK11+ HttpClient，通过/dir/lookup获取volume地址，POST multipart/form-data至/volumeId上传文件，解析返回fid用于下载，并动态管理volume server地址映射。
Java项目里怎么连上SeaweedFS的HTTP API
SeaweedFS本身不提供官方Java SDK，所谓“Java API集成”实际是调用它的REST接口。别被“API”二字误导——你不需要引入某个叫 seaweedfs-java 的神秘包，直接用 HttpClient 或 OkHttp 发请求就行。
常见错误是试图找“客户端jar包”，结果在Maven中央白搜半天。它压根没发布过标准Java SDK，所有文档里提到的“API”都指HTTP端点。
- 最简路径：用
java.net.http.HttpClient（JDK 11+）或OkHttpClient调/dir/lookup、/vol/<em>volumeId</em>这类地址 - 上传文件走
POST /<em>volumeId</em>，注意必须用multipart/form-data，且字段名固定为file - 返回的JSON里，
fid是关键——形如3,01637037，后续下载要拼成http://host:8080/3,01637037 - 别漏掉 volume server 的地址管理：SeaweedFS分 master + volume 两层，Java代码里得自己维护
volumeId → host:port映射，靠/dir/lookup?volumeId=3查
为什么用 OkHttpClient 比 HttpURLConnection 更稳
HttpURLConnection 在重试、连接池、超时控制上太原始，而SeaweedFS volume server可能临时不可达，或master返回的volume地址已失效。这时候裸用 HttpURLConnection 容易卡死或抛 SocketTimeoutException 不处理。
真实场景中，你大概率要支持断点续传、并发上传、自动重定向volume地址——这些 OkHttpClient 开箱即用，HttpURLConnection 得自己撸。
立即学习“Java免费学习笔记（深入）”；
- 务必配置
connectTimeout和readTimeout，SeaweedFS默认不设超时，Java客户端会卡住 - 启用
connectionPool，避免频繁建连拖慢吞吐 - 用
Interceptor统一处理 volume server 404 后的重查逻辑：捕获404 Not Found，再调一次/dir/lookup拿新地址 - 别信
setFollowRedirects(true)—— SeaweedFS 返回的是 302 + Location 头，但目标地址是另一个 volume server，JDK 默认不跨域重定向，得手动取头再发请求
上传大文件时 fid 生成和分块上传怎么配合
SeaweedFS本身不支持服务端分片，所谓“分块上传”是客户端行为：把大文件切片，每片单独 POST 到不同 volume，最后靠业务层拼 fid 或存元数据。这里没有魔法，只有取舍。
容易踩的坑是以为 fid 可以“合并”，其实不能——每个 POST 返回独立 fid，比如 3,01637037 和 5,01637038，它们之间无关联。你要么存多个 fid，要么用 SeaweedFS 的 ec.encode 接口做纠删码（但 Java 端得自己实现协议）。
- 小文件（fid，简单可靠
- 大文件（>100MB）：客户端分片（如每片 5MB），每片传完记录
fid+ offset，元数据存在本地DB或Redis - 别用
Content-Range头试图走“断点续传”协议——SeaweedFS HTTP API 不识别这个头，会当普通文件存 - 如果真要服务端分片，得换对象存储协议（如 S3 兼容层），启动 SeaweedFS 的
s3模式，走aws-sdk-java，不是直接调 HTTP API
测试环境里 localhost:8080 跑不通的三个典型原因
本地跑通不代表上线能用，尤其当你从 Docker 启动 SeaweedFS 时，Java 应用看到的 localhost 和容器里的 localhost 不是一回事。
错误现象常是 Connection refused 或 404，但日志里看不出哪层挂了。先盯住三件事：
- 检查 SeaweedFS master 是否加了
-ip=0.0.0.0（默认只绑127.0.0.1），否则外部Java进程连不上 - volume server 启动时是否用了
-publicUrl参数？比如-publicUrl=http://host.docker.internal:8080，否则/dir/lookup返回的地址仍是容器内不可达的localhost:8080 - Docker 网络模式：Java应用若也在容器里，别用
bridge网络直连localhost，改用host.docker.internal或自定义 network alias - Mac/Windows 上 Docker Desktop 的
host.docker.internal默认可用，Linux 需手动加--add-host=host.docker.internal:host-gateway
复杂点在于 volume server 地址是运行时动态分配的，Java 代码里不能写死；更麻烦的是，开发、测试、生产三套环境的网络拓扑不同，publicUrl 配置必须可外部注入，别硬编码进 properties 文件。
