必须显式设置http.Client的Timeout字段,否则可能无限hang住;Kratos.NewHTTPClient()不自动设超时,需传入自定义client,如&http.Client{Timeout: 5 * time.Second}。

直接用 http.Client 就行,但必须显式设 Timeout,否则大概率 hang 住。
为什么不能用 http.DefaultClient
它没设 Timeout,底层 net.Conn 可能永远等不到响应。Kratos 的 kratos.NewHTTPClient() 默认也不带超时——它只是封装了 transport,不改 client 本身的超时行为。你看到服务日志里某次请求卡住十几秒甚至几分钟,八成是这里漏了。
- 必须新建
&http.Client{Timeout: 5 * time.Second}这类实例 - 传给
kratos.NewHTTPClient(kratos.WithHTTPClient(client)) - 别在中间件或 service 层复用未设超时的 client
kratos.NewHTTPClient() 和自己 new http.Client 的区别
kratos.NewHTTPClient() 主要干三件事:注入 transport(比如加 TLS、代理)、挂载中间件(如重试、指标)、统一日志打点。但它不碰 Timeout 字段。你自己 new 的 http.Client 才真正控制连接、读、写超时。
- 连接超时 →
Transport.DialContext控制 - 读超时 →
Client.Timeout或context.WithTimeout控制(推荐后者,更灵活) - 写超时 → 同样靠
Client.Timeout,但实际场景少 - 如果用了
kratos.NewHTTPClient()却没传自定义client,它内部用的是http.DefaultClient,等于白封装
调用第三方 API 时怎么传 context 超时
别只依赖 Client.Timeout。有些第三方接口响应慢但合法(比如 Webhook 回调),你可能想单独放宽某次请求的 timeout,这时得在调用时用 context.WithTimeout 包一层。
- 错误写法:
resp, err := client.Get("https://api.example.com/data")—— 没 context,超时不可控 - 正确写法:
ctx, cancel := context.WithTimeout(r.Context(), 8*time.Second); defer cancel(); resp, err := client.Get(ctx, "https://api.example.com/data") - Kratos 的
http.Client封装支持Get(ctx, url)等带 ctx 的方法,优先用这个 - 注意:
r.Context()是 handler 里的*http.Request上下文,不是kratos.Context;别混用
常见报错和对应解法
context deadline exceeded:超时触发,检查 Client.Timeout 和调用时的 context.WithTimeout 是否合理;connection refused:目标服务没起来或网络不通,和 Kratos 无关;tls: handshake timeout:TLS 握手卡住,通常要调大 Transport.TLSHandshakeTimeout,而不是 Client.Timeout。
- 第三方域名解析失败?加
Transport.DialContext里手动指定 DNS 解析器,或确认服务所在环境 DNS 配置正常 - 返回 401/403 却没进错误处理?检查是否把
resp.StatusCode >= 200 && resp.StatusCode 当作成功条件,http.Client不会自动报错 - Body 没读完就 return?会导致连接无法复用,用
io.ReadAll(resp.Body); defer resp.Body.Close()
最常被忽略的一点:超时配置不在 server 端,而在 outbound client 实例上。哪怕你把 http.Server.ReadTimeout 设成 1 秒,对调第三方接口毫无影响。
大量免费API接口:立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游,为数据API应用能力赋能!











