HTTP Client、Socket 与数据库元数据
查找 HTTP Client、Socket 和数据库元数据入口及适用边界。
浏览全部手册
本页目录
文档来源与 Markdown 原文
权威正文:ineed-core/docs/guides/clients-and-metadata.md。网站按工作区快照同步,原文中的历史日期和验证范围保留。
开始编码前核对同版本源码;跨仓文件引用可在源码定位目录查找。
下载 Markdown 原文 ↓本页是外围能力接入入口。HTTP 三种实现于 2026-09-23 增加共同回环网络验证;Socket 和数据库元数据仍需区分各协议、厂商的验证范围。
HTTP Client
共享请求/响应来自 ineed-core-httpclient;阻塞实现有 JDK 与 OkHttp,响应式使用独立 reactive 契约及 WebClient 实现。按应用运行时选择实现,不为了复用阻塞客户端在响应式链中阻塞等待。
BlockingHttpClientExecutor以 execute(HttpClientRequest) 返回 HttpClientResponse,声明 IO 与中断异常。请求配置从HttpClientRequest核对。
接入时明确执行器、超时、响应体限制、错误处理、重试及幂等。重试外部写请求前先确认业务允许重复;不能把客户端超时直接解释为对端没有执行。
JDK 执行器的 timeout 覆盖等待响应与完整响应体接收;缺省或非正值使用 30 秒。接收时逐块检查 maxResponseBytes,超限抛出 HttpResponseTooLargeException;超时抛出 HttpTimeoutException,中断继续向调用方抛出 InterruptedException,同时取消交换与响应体订阅。回环 HTTP 验证见 JdkBlockingHttpClientExecutorTest,包含立即返回头但慢传正文、持续小块传输、大小边界与中断。
三种 HTTP 实现的共同约定
JDK、OkHttp、WebClient 使用同一份 HTTP 契约测试。以下适用于框架提供的默认执行器;应用自行注入拦截器、代理或自定义连接器后应重新验证。
- 字符串请求与响应正文使用 UTF-8;不会推断 JSON 或自动补
Content-Type。发送 JSON 时显式传入Content-Type: application/json; charset=utf-8。声明其他 charset 不会自动改变正文编码。 - 最终请求缺少
Accept-Encoding时补identity,避免不同客户端自动协商、解压的差异;显式请求头按大小写不敏感识别并保留。压缩数据和二进制下载不属于当前字符串正文契约。 - URL 是已构造的最终 URI,百分号编码保留,不按 URI 模板再次展开。GET、DELETE、HEAD 不发送正文。
- 不自动跟随重定向;3xx、4xx、5xx 均返回状态、响应头和正文,调用方判断业务成功与否。网络失败才走异常路径。
- 缺省或非正超时为 30 秒,超时覆盖完整响应。三种实现均以
HttpTimeoutException表达期限超时;WebClient 通过 Publisher 发出错误。OkHttp 的有效精度为毫秒,正的亚毫秒值按 1 毫秒执行,绝不能变成无限等待。 maxResponseBytes按字节计算,非正值或未设置表示不设业务上限;超限以HttpResponseTooLargeException失败并释放接收资源。WebClient 聚合缓冲还有 Java 单数组的int容量限制,不能用此接口下载超大文件。- WebClient 在订阅后启动,取消向下游交换传播。JDK 线程中断抛出
InterruptedException;OkHttp 的底层中断仍可能是InterruptedIOException,不能把所有中断误报为超时。
兼容提醒:此前依赖 OkHttp 自动添加 JSON 类型、WebClient 自动添加文本类型或 OkHttp 默认 gzip 的调用方,现在需要显式配置请求头。执行证据及未覆盖环境见实现对齐记录。
Socket 接入
SocketAccessExecutor声明 supports(SocketAccessMode) 和 start(SocketAccessEndpoint, SocketAccessMessageHandler),启动返回 session。实际支持模式以所选执行器为准,不能因为枚举含某模式就认为每个实现都支持。
应用负责明确连接生命周期、消息处理、取消/关闭、重连与资源释放。参考SocketAccessSession;响应式实现位于 reactive 聚合。
数据库元数据
RdbMetadataUtil提供数据库、表、列等读取入口。DataSource 重载内部获取并关闭连接;传入 Connection 时按调用方连接生命周期管理。
读取 SQLException 通过 RdbMetadataException.readFailed 转换,不应将失败伪装成空表列表。元数据为空和读取失败要分别处理,具体支持的 schema/catalog 行为需要针对目标数据库验证。
验证与维护
客户端至少覆盖成功、超时、异常、取消/关闭和资源释放;元数据至少覆盖有效结构、无结果与连接/读取失败。新增适配器时更新模块清单和运行时矩阵,不要把“已加入 POM”标记为“全部能力已验证”。
仍有疑问?按反馈清单整理复现信息 →