security(http): 同步出站请求 host 白名单守卫（JDK 17 / Jackson 2 适配）+ 移除孤儿 README.zh_CN.md

Author: loong10k

README.zh_CN.md

@@ -314,6 +314,9 @@ private void copyHttpConfig(HermesHttpClientConfig src) {
     }
 
     private static void copyHttpConfig(HermesHttpClientConfig src, HermesHttpClientConfig target) {
+        // 把测试用的 host 白名单旁路标志也复制过来——门面内部快照在 copy 期间
+        // 会经 setter 重新校验 URL，漏掉此标志会让 MockWebServer 测试抛 IAE。
+        target.markUnsafeBaseUrlOverriddenForTest(src.isUnsafeBaseUrlOverriddenForTest());
         target.setMode(src.getMode());
         target.setEnabled(src.isEnabled());
         target.setStartupCheckEnabled(src.isStartupCheckEnabled());

src/main/java/io/github/easy4j/hermes/HermesClient.java

@@ -12,6 +12,19 @@
 @Data
 public class HermesClientConfig {
 
+    /**
+     * <p>仅供测试代码使用——将内部 {@link HermesHttpClientConfig} 的
+     * unsafe bypass 标志一并打开，使 {@link HermesClient} 复制配置时也能放行
+     * localhost / MockWebServer 地址。生产代码不应调用此方法。</p>
+     *
+     * @return 当前配置（链式）
+     * @since 1.0.0
+     */
+    public HermesClientConfig markUnsafeBaseUrlOverriddenForTest() {
+        this.http.markUnsafeBaseUrlOverriddenForTest(true);
+        return this;
+    }
+
     /** 客户端所有通信通道共享的调试配置。 */
     private final HermesDebugConfig debug = new HermesDebugConfig();
 

src/main/java/io/github/easy4j/hermes/HermesClientConfig.java

@@ -57,6 +57,13 @@ public HermesHttpClientConfig(HermesDebugConfig debug) {
      */
     private String baseUrl = HermesApiConstants.DEFAULT_SERVER_URL;
 
+    /**
+     * 仅供测试代码使用——调用 {@link #markUnsafeBaseUrlOverriddenForTest(boolean)}
+     * 打开后，{@link #setBaseUrl(String)} 跳过 {@link io.github.easy4j.hermes.util.EndpointGuard}
+     * 的 host 白名单校验。生产代码不应设置此字段。
+     */
+    private boolean unsafeBaseUrlOverriddenForTest;
+
     /**
      * Bearer 鉴权密钥；为空时不发送 Authorization 请求头。
      */
@@ -173,6 +180,35 @@ public HermesHttpClientConfig(HermesDebugConfig debug) {
      * @return 配置的 API key；未配置时返回空字符串
      * @since 1.0.0
      */
+
+    /**
+     * <p>设置基础 URL 并强制 host 白名单校验：仅接受 {@code http} / {@code https}，
+     * 拒绝 localhost、环回、私有与保留地址。测试可经
+     * {@link #markUnsafeBaseUrlOverriddenForTest(boolean)} 放行。</p>
+     *
+     * @param baseUrl 服务基础 URL
+     * @return 当前配置（链式）
+     * @since 1.0.0
+     */
+    public HermesHttpClientConfig setBaseUrl(String baseUrl) {
+        if (!this.unsafeBaseUrlOverriddenForTest) {
+            this.baseUrl = io.github.easy4j.hermes.util.EndpointGuard.require(baseUrl);
+        } else {
+            this.baseUrl = baseUrl;
+        }
+        return this;
+    }
+
+    /**
+     * <p>仅供测试代码使用——绕开 host 白名单。</p>
+     *
+     * @param value true 跳过下一次 setter 调用的 host 校验
+     * @since 1.0.0
+     */
+    public void markUnsafeBaseUrlOverriddenForTest(boolean value) {
+        this.unsafeBaseUrlOverriddenForTest = value;
+    }
+
     public String resolveApiKey() {
         return Objects.toString(apiKey, "");
     }