WireMock IPv6代理问题分析与解决方案

2025-06-01 11:38:37作者：薛曦旖Francesca

WireMock是每位API开发者与测试者的得力助手，一个广受赞誉的开源工具，每月超过500万次下载，证明了其在构建稳定测试与开发环境方面的不可或缺。自2011年由Tom Akehurst以Java起家，如今WireMock已跨越多种编程语言和技术栈，无论是作为库集成于项目，还是作为独立服务器运行，都能游刃有余。它支持代码编写、REST API配置、JSON文件定义乃至通过代理记录HTTP流量来创建模拟API，满足各类复杂需求。具备精细的请求匹配规则与基于Handlebars的动态响应生成能力，加之广泛的扩展点与API，让WireMock成为易于融入任何工作流程的强大工具。无论单元测试、独立运行或是容器部署，WireMock都让你的API模拟变得简单高效，赋能软件开发的每一个环节。加入Wiremock社区，共同探索更多可能！

项目地址：https://gitcode.com/gh_mirrors/wir/wiremock

WireMock作为一款流行的API模拟工具，其代理功能在实际开发测试中扮演着重要角色。近期社区发现了一个影响IPv6环境下代理功能的典型问题，本文将深入分析问题成因并提供完整解决方案。

问题现象

当WireMock配置为代理模式时，如果目标主机仅支持IPv6协议或网络环境强制使用IPv6时，会出现"Network is unreachable (connect failed)"的错误。这个问题自WireMock 3.2.0之后的版本开始出现，表现为无法正确解析和访问仅支持IPv6的目标服务。

技术背景

现代网络环境中，IPv6的普及率正在逐步提升。许多云服务和企业内网已经开始部署纯IPv6环境或双栈环境。WireMock作为中间代理时，需要正确处理DNS解析结果中的IPv6记录。

根本原因

问题源于WireMock核心代码中对DNS解析结果的强制过滤机制。在默认配置下（未显式设置allow-proxy-targets或deny-proxy-targets参数时），系统会主动过滤掉所有IPv6地址记录，导致：

双栈环境中优先尝试不可达的IPv4地址
纯IPv6环境中直接无法获取有效地址

解决方案

方案一：版本回退（临时方案）

对于急需解决问题的场景，可以暂时回退到WireMock 3.2.0版本，该版本尚未引入IPv6过滤机制。

方案二：自定义HttpClientFactory（推荐方案）

对于Java集成场景，可以通过实现自定义的HttpClientFactory来绕过IPv6限制：

public class IPv6EnabledHttpClientFactory implements HttpClientFactory {
    @Override
    public HttpClient buildHttpClient(
        ProxySettings proxySettings,
        TlsSettings tlsSettings,
        int maxConnections,
        long connectionTimeout,
        long readTimeout,
        boolean useSystemProperties) {
        
        // 使用系统默认DNS解析器（包含IPv6支持）
        DnsResolver dnsResolver = SystemDefaultDnsResolver.INSTANCE;
        
        // 构建HttpClient实例
        CloseableHttpClient httpClient = HttpClients.custom()
            .setDnsResolver(dnsResolver)
            // 其他配置参数
            .build();
            
        return new HttpClient4(httpClient);
    }
}