PHP stream_socket_client 超时后如何区分 DNS 和连接失败

PHP 服务调用上游时，日志里只出现“超时”并不够用：域名解析失败、目标端口拒绝连接、网络路径丢包，都可能在同一条业务日志里被压成一个模糊结论。更稳妥的做法是把排查拆成两层：先独立确认主机名能否得到 A/AAAA 记录，再让 stream_socket_client() 只负责报告 TCP 连接结果。

为什么同一条“超时”日志不能直接下结论

stream_socket_client() 接收 tcp://host:port 地址，成功返回流资源，失败返回 false，并通过引用参数写入系统级错误码和错误信息。它的 $timeout 只作用于建立连接的 connect() 阶段，不能替代后续读写的超时控制。

因此，主机名还没有解析成功时，问题属于名称解析层；已经得到 IP 但端口没有服务监听时，通常是连接被拒绝；数据包没有在限定时间内完成握手，则更接近 TCP 连接超时。只有把层次拆开，日志才有可操作性。

先让 DNS 结果单独可见

不要把“连接失败”直接等同于“域名解析失败”。先抽出地址中的主机名；如果调用方本来就传入 IP，可以跳过 DNS 检查。下面的辅助函数只负责产生诊断事实，不负责重试，也不把空数组和 false 混为一谈。

 'ip-literal', 'addresses' => [$host]];
    }

    // 只查询 A 与 AAAA，保留 IPv4/IPv6 两类连接入口。
    $records = @dns_get_record($host, DNS_A | DNS_AAAA);
    if ($records === false) {
        // false 表示查询失败，和“查询成功但没有目标记录”不同。
        return ['state' => 'dns-query-failed', 'addresses' => []];
    }

    $addresses = [];
    foreach ($records as $record) {
        // A 使用 ip 字段，AAAA 使用 ipv6 字段。
        $value = $record['ip'] ?? $record['ipv6'] ?? null;
        if (is_string($value) && $value !== '') {
            $addresses[] = $value;
        }
    }

    return [
        'state' => $addresses ? 'dns-resolved' : 'dns-no-address',
        'addresses' => array_values(array_unique($addresses)),
    ];
}
?>

这里的 dns-query-failed 只说明 DNS 查询没有成功，不等同于某个固定的网络错误；而 dns-no-address 说明查询完成但没有收集到 A/AAAA。生产日志应同时记录原始主机名和解析状态，便于比较不同容器或不同 DNS 配置的差异。

再用 stream_socket_client 判定 TCP 连接

DNS 通过后再尝试连接，失败时保留三个字段：返回值、系统错误码和错误文本。连接成功则尽快进入业务协议处理，并在不用时关闭资源；连接函数的 $timeout 不能覆盖后续读取。

 'connected', 'elapsed_ms' => $elapsedMs, 'stream' => $stream];
    }

    // errno=0 且返回 false，说明错误发生在系统 connect() 之前。
    $state = $errno === 0 ? 'pre-connect-failure' : 'tcp-failure';
    $message = strtolower($errstr);
    if (str_contains($message, 'refused')) {
        $state = 'connection-refused';
    } elseif (str_contains($message, 'timed out') || str_contains($message, 'timeout')) {
        $state = 'connection-timeout';
    }

    return [
        'state' => $state,
        'errno' => $errno,
        'error' => $errstr,
        'elapsed_ms' => $elapsedMs,
    ];
}
?>

“refused”和“timeout”只是便于人读的辅助分类，不能替代原始字段：不同操作系统、语言环境和网络库可能返回不同文本。真正的复查记录至少应包含 address、解析状态、errno、errstr、耗时和部署节点。若目标是 IPv6 字面量，地址要写成 tcp://[::1]:80 这样的方括号形式。

把修复动作和复查证据分开

解析失败时先查 DNS 配置、搜索域和主机名拼写；解析成功但被拒绝时，检查目标服务监听地址、端口映射和防火墙；连接超时则看路由、安全组和网络策略。不要通过无限加大 timeout 来掩盖拒绝或错误主机名。

修复后用同一地址、同一运行节点重新记录结果。只有从 dns-query-failed 或 dns-no-address 变为 dns-resolved，再从连接失败变为 connected，才能说明两层都恢复。若已建立连接但读数据仍卡住，应转查 stream_set_timeout() 与上游协议响应，而不是继续修改连接超时。

常见问题

只检查 $errno 能区分 DNS 和 TCP 吗？

不建议。先做独立 DNS 检查更可靠；$errno 是系统级连接回执，适合与原始错误文本和阶段状态一起记录。

连接超时参数能限制读取响应的时间吗？

不能。它只针对建立连接；连接成功后要用 stream_set_timeout() 设置读写超时。

为什么不直接用错误文本做枚举？

错误文本会受平台和语言环境影响。文本可以帮助值班人员快速判断，但日志和告警应保留原始 errno、errstr 与阶段字段。