309 lines
14 KiB
Markdown
309 lines
14 KiB
Markdown
|
---
|
|||
|
|
tags: [gRPC, Go, Dial, Connection, TransportCredentials, Keepalive, Retry]
|
|||
|
|
create time: 2026-05-11 15:30
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Client 连接与 Dial
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
gRPC client 的连接建立在 `grpc.Dial` 上，但 dial 只是起点——真正的连接管理、自动重连逻辑、负载均衡和地址解析都在背后的子系统里。理解这些机制能让你避免绝大多数生产环境下的连接问题，而不是把时间浪费在反复调试"为什么偶尔超时"上。
|
|||
|
|
|
|||
|
|
> [!question] 为什么一个 conn 就能代替连接池？
|
|||
|
|
> HTTP/1.1 时代我们需要手动维护 http.Client 的 Transport 来复用 TCP 连接。但 gRPC 的设计哲学不同——它把连接生命周期完全封装在 `grpc.ClientConn` 内部，你只需要调好 dial options 就够了。后续章节会详细拆解这个内部是怎么工作的。
|
|||
|
|
|
|||
|
|
## Basic Dial
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
import (
|
|||
|
|
"google.golang.org/grpc"
|
|||
|
|
"google.golang.org/grpc/credentials/insecure"
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
conn, err := grpc.Dial(
|
|||
|
|
"localhost:50051",
|
|||
|
|
grpc.WithTransportCredentials(insecure.NewCredentials()),
|
|||
|
|
)
|
|||
|
|
if err != nil {
|
|||
|
|
log.Fatalf("dial failed: %v", err)
|
|||
|
|
}
|
|||
|
|
defer conn.Close() // 必须调用，释放底层 goroutine 和文件描述符
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **target** 支持多种 scheme：`dns:///host:port`、`unix:///path`、`ip://...`。不指定 scheme 时默认走 DNS resolver。
|
|||
|
|
- `grpc.Dial()` 是 **non-blocking** 的——它立即返回 `conn` 对象，后台异步建立连接。此时不能立即发起 RPC，否则会排队等待连接就绪。
|
|||
|
|
- **必须**在进程退出前调用 `conn.Close()`，否则 goroutine 泄漏（每个 subchannel 都会启动 keepalive timer、reconnect goroutine）。
|
|||
|
|
- ❌ gRPC v1.35+ 已废弃 `grpc.WithInsecure()`，改用 `grpc.WithTransportCredentials(insecure.NewCredentials())`。
|
|||
|
|
|
|||
|
|
## Dial Options 分类表
|
|||
|
|
|
|||
|
|
gRPC 通过 Option pattern（函数式选项）配置客户端行为。按功能域分为以下类别：
|
|||
|
|
|
|||
|
|
| 类别 | Option | 用途 |
|
|||
|
|
|------|--------|------|
|
|||
|
|
| 传输安全 | `WithTransportCredentials()` | TLS / mTLS 配置 |
|
|||
|
|
| **重连策略** | `WithConnectTimeout()`, `WithBackoffConfig()` | 底层 reconnect backoff（**见下文**） |
|
|||
|
|
| 重试 | `WithDefaultServiceConfig()` | Service config JSON，含 retry policy |
|
|||
|
|
| 负载平衡 | `WithBalancerName()` ⚠️已废弃 | v1.60+ 固定使用 `pick_first`；需改 service config 中的 `loadBalancingConfig` |
|
|||
|
|
| 消息大小 | `WithMaxCallRecvMsgSize()` / `WithMaxSendMsgSize()` | 接收/发送上限（默认 recv 4MB） |
|
|||
|
|
| 保持活 | `WithKeepaliveParams()` / `WithKeepaliveAuthority()` | Keepalive 心跳 + 覆盖 authority |
|
|||
|
|
| 拦截器 | `WithChainUnaryInterceptor()` / `WithChainStreamInterceptor()` | 拦截器链 |
|
|||
|
|
| 统计/观测 | `WithStatsHandler()` | StatsHandler 接口，用于 metrics 和 tracing |
|
|||
|
|
| 元数据 | `WithUserAgent()` | 自定义 User-Agent header |
|
|||
|
|
| 通信类型 | `WithInitialWindowSize()` / `WithInitialConnWindowSize()` | 调整 gRPC 层 flow control 窗口 |
|
|||
|
|
|
|||
|
|
> [!warning] WithBalancerName 已废弃
|
|||
|
|
> gRPC v1.60.0 起移除了旧版 balancer API（`balancer.Register`）。负载均衡策略现在统一通过 service config JSON 的 `loadBalancingConfig` 字段配置——这也会在 "Default Service Config" 部分详述。
|
|||
|
|
|
|||
|
|
## Transport Credentials（证书配置）
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
import (
|
|||
|
|
"crypto/tls"
|
|||
|
|
"crypto/x509"
|
|||
|
|
"google.golang.org/grpc/credentials"
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// 生产环境：标准 TLS
|
|||
|
|
caBytes, _ := os.ReadFile("ca-cert.pem")
|
|||
|
|
caPool := x509.NewCertPool()
|
|||
|
|
caPool.AppendCertsFromPEM(caBytes)
|
|||
|
|
|
|||
|
|
cert, _ := tls.LoadX509KeyPair("client-cert.pem", "client-key.pem")
|
|||
|
|
|
|||
|
|
creds := credentials.NewTLS(&tls.Config{
|
|||
|
|
Certificates: []tls.Certificate{cert},
|
|||
|
|
RootCAs: caPool,
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
conn, err := grpc.Dial(addr, grpc.WithTransportCredentials(creds))
|
|||
|
|
|
|||
|
|
// 本地开发：insecure（仅本地！绝不能用于生产）
|
|||
|
|
// conn, _ := grpc.Dial(addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
mTLS 与普通 TLS 的区别：普通 TLS 只需验证服务端证书；mTLS 还要求客户端出示自己的证书。如果你的服务网格或零信任架构要求双向认证，就必须用 mTLS。
|
|||
|
|
|
|||
|
|
## Default Service Config（Retry Policy）
|
|||
|
|
|
|||
|
|
gRPC Go 内置的自动重试能力，通过 service config JSON 开启：
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
config := `{
|
|||
|
|
"retryPolicy": {
|
|||
|
|
"maxAttempts": 3,
|
|||
|
|
"initialBackoff": "0.1s",
|
|||
|
|
"maxBackoff": "1s",
|
|||
|
|
"backoffMultiplier": 2,
|
|||
|
|
"retryableStatusCodes": ["UNAVAILABLE", "DEADLINE_EXCEEDED"]
|
|||
|
|
}
|
|||
|
|
}`
|
|||
|
|
|
|||
|
|
conn, err := grpc.Dial(addr,
|
|||
|
|
grpc.WithDefaultServiceConfig(config),
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
retry policy 的核心机制：**指数退避**。第一次失败等 100ms，第二次 200ms，第三次 400ms，直到达到 maxBackoff 上限。
|
|||
|
|
|
|||
|
|
⚠️ 注意：service config 中同时可以设置 load balancing policy：
|
|||
|
|
```json
|
|||
|
|
{"loadBalancingPolicy":"round_robin","retryPolicy":{...}}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Keepalive Parameters
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
import "google.golang.org/grpc/keepalive"
|
|||
|
|
|
|||
|
|
ksp := keepalive.ClientParameters{
|
|||
|
|
Time: 10 * time.Second, // ping 间隔
|
|||
|
|
Timeout: 5 * time.Second, // 等待 pong 的超时
|
|||
|
|
PermitWithoutStream: true, // 空闲时也发 ping
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
conn, err := grpc.Dial(addr,
|
|||
|
|
grpc.WithKeepaliveParams(ksp),
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
为什么需要 keepalive：NAT 网关和云负载均衡器通常会在 30~60 秒无流量后主动切断 TCP 连接。如果不发送 keepalive ping，服务端认为连接已死，而客户端仍然以为活着，后续读写就会拿到 `i/o timeout` 这类难以排查的错误。
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
flowchart LR
|
|||
|
|
subgraph "Client"
|
|||
|
|
A["Keepalive Timer\nEvery 10s send ping"] --> B["HTTP/2 PING Frame"]
|
|||
|
|
end
|
|||
|
|
subgraph "Server"
|
|||
|
|
B --> C["Receive PING"]
|
|||
|
|
C --> D["Reply PONG"]
|
|||
|
|
D --> E["Return to step A"]
|
|||
|
|
end
|
|||
|
|
|
|||
|
|
F["NAT / LB\nNo traffic 30s close conn"] -.-> G["Connection alive"]
|
|||
|
|
|
|||
|
|
style A fill:#00D866,color:#fff
|
|||
|
|
style G fill:#EE5A24,color:#fff
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Backoff / Reconnect Policy
|
|||
|
|
|
|||
|
|
Keepalive 负责探测"连接是否还活着"，而 backoff 策略决定断连后**等多久重连**。这两者是协作关系：
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
// gRPC v1.60+ 推荐方式：手动指定 backoff config
|
|||
|
|
conn, err := grpc.Dial(addr,
|
|||
|
|
grpc.WithConnectTimeout(5*time.Second),
|
|||
|
|
grpc.WithBackoffConfig(backoff.BackoffConfig{
|
|||
|
|
MaxDelay: 1 * time.Minute, // 最大重连延迟（指数退避上限）
|
|||
|
|
BaseDelay: 1 * time.Second, // 初始 delay
|
|||
|
|
Multiplier: 1.6, // 每次翻倍乘数
|
|||
|
|
Jitter: 0.2, // 抖动范围 ±20%，防止 thundering herd
|
|||
|
|
}),
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
默认行为与可配参数的对比：
|
|||
|
|
|
|||
|
|
| 参数 | 默认值 | 说明 |
|
|||
|
|
|------|--------|------|
|
|||
|
|
| `BaseDelay` | 1s | 初次重连等待时间 |
|
|||
|
|
| `Multiplier` | 1.6 | 指数退避系数 |
|
|||
|
|
| `Jitter` | 0.2 | 随机抖动（防雪崩） |
|
|||
|
|
| `MaxDelay` | 120s | 重连间隔上限 |
|
|||
|
|
|
|||
|
|
当 keepalive 检测失败（ping timeout），subchannel 进入 TransientFailure 状态并触发 backoff。背压按如下序列递增：
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
flowchart LR
|
|||
|
|
A["Disconnected"] --> B["wait 1.0s"]
|
|||
|
|
B --> C["reconnect failure"]
|
|||
|
|
C --> D["wait 1.6s jitter"]
|
|||
|
|
D --> E["reconnect failure"]
|
|||
|
|
E --> F["wait 2.56s jitter"]
|
|||
|
|
F --> G["exponential growth"]
|
|||
|
|
G --> H["wait up to 120s jitter"]
|
|||
|
|
H --> I["retry until connected"]
|
|||
|
|
|
|||
|
|
style B fill:#FFD43B
|
|||
|
|
style G fill:#FF9F43
|
|||
|
|
style H fill:#EE5A24,color:#fff
|
|||
|
|
style I fill:#00D866,color:#fff
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
核心要点：
|
|||
|
|
- **不要设得太激进**——如果服务端确实挂了，频繁重连只会放大 traffic。120s 上限给了运维人员修复窗口。
|
|||
|
|
- **thundering herd 防护**：Jitter 让每个 client 的重连时间分散开来，避免大批量客户端在同一时刻同时重连压垮刚恢复的服务端。
|
|||
|
|
- `WithConnectTimeout` 控制的是握手阶段的超时（TCP + TLS handshake），和 reconnection backoff 是两个独立的超时维度。
|
|||
|
|
|
|||
|
|
## Address Resolution（地址解析）
|
|||
|
|
|
|||
|
|
gRPC 通过 resolver 机制将目标字符串翻译为真实地址列表——这使得客户端不需要硬编码 IP，天然支持动态扩缩容和 Service Discovery。
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
flowchart LR
|
|||
|
|
subgraph Target["target dns:///my-service.default.svc:50051"]
|
|||
|
|
Resolver["Resolver\nDNS / etcd / Static"]
|
|||
|
|
end
|
|||
|
|
|
|||
|
|
Resolver -->|"Address List"| Picker["Picker\nSelect subchannel for request"]
|
|||
|
|
|
|||
|
|
subgraph Conn["grpc.ClientConn"]
|
|||
|
|
Picker --> SC1["SubChannel 1\n10.0.0.1:50051"]
|
|||
|
|
Picker --> SC2["SubChannel 2\n10.0.0.2:50051"]
|
|||
|
|
Picker --> SC3["SubChannel 3\n10.0.0.3:50051"]
|
|||
|
|
end
|
|||
|
|
|
|||
|
|
style Resolver fill:#00B6BC,color:#fff
|
|||
|
|
style Picker fill:#FFD43B
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**核心组件：**
|
|||
|
|
|
|||
|
|
| 角色 | 职责 |
|
|||
|
|
|------|------|
|
|||
|
|
| **Resolver** | 把 target 字符串解析为 `address.Address` 列表，并 watch 更新 |
|
|||
|
|
| **Balancer (Picker)** | 从子连接中选一个来发请求（pick_first / round_robin） |
|
|||
|
|
| **SubChannel** | 封装单个后端连接的传输层，含 keepalive、reconnect 逻辑 |
|
|||
|
|
|
|||
|
|
**内置 Resolver 类型：**
|
|||
|
|
|
|||
|
|
- **DNS resolver**：`dns:///my-service.default.svc.cluster.local:50051`，自动解析 A/AAAA/TXT 记录并 watch 变化。当 DNS 返回多个 A 记录时，gRPC 会创建子连接并使用 picker 做负载均衡。
|
|||
|
|
- **Static resolver**：传入裸 `IP:port`（如 `10.0.0.1:50051`），不会自动重连，适合单元测试或固定 IP 场景。
|
|||
|
|
- **Discovery 插件**：etcd、Consul、Nacos 等有第三方 resolver 实现。
|
|||
|
|
|
|||
|
|
> [!tip] 为什么需要 TXT 记录？
|
|||
|
|
> gRPC DNS resolver 同时读取 A 记录（后端地址）和 TXT 记录（service config）。你可以在 DNS TXT 中声明 retry policy 和 load balancing config，这样服务端就能统一管理配置而不需要改客户端代码。
|
|||
|
|
|
|||
|
|
## Client Lifecycle（连接生命周期）
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
stateDiagram-v2
|
|||
|
|
[*] --> Idle: grpc.Dial() returns immediately
|
|||
|
|
Idle --> Connecting: first call or reconnect
|
|||
|
|
Connecting --> Ready: TCP + HTTP/2 handshake OK
|
|||
|
|
Connecting --> TransientFailure: dial failed
|
|||
|
|
|
|||
|
|
state "Connecting" as C {
|
|||
|
|
[*] --> TCPConnect
|
|||
|
|
TCPConnect --> TLSHandshake: secure mode
|
|||
|
|
TLSHandshake --> PrefaceSent
|
|||
|
|
TCPConnect --> PrefaceSent: insecure mode
|
|||
|
|
PrefaceSent --> Ready: SETTINGS ACK received
|
|||
|
|
PrefaceSent --> ErrorTimeout: timeout
|
|||
|
|
ErrorTimeout --> TransientFailure
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
Ready --> Busy: Create RPC Stream
|
|||
|
|
Busy --> Ready: Stream completed
|
|||
|
|
Busy --> Closing: context cancellation
|
|||
|
|
|
|||
|
|
TransientFailure --> Reconnecting: backoff expires
|
|||
|
|
Reconnecting --> Ready: reconnect success
|
|||
|
|
Reconnecting --> TransientFailure: reconnect fail
|
|||
|
|
|
|||
|
|
Closing --> [*]: conn.Close() graceful shutdown
|
|||
|
|
TransientFailure --> [*]: fatal error (e.g., invalid addr)
|
|||
|
|
|
|||
|
|
note right of TransientFailure
|
|||
|
|
DNS resolved but all
|
|||
|
|
backends unreachable
|
|||
|
|
end note
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
gRPC client 的生命周期分为以下状态：
|
|||
|
|
|
|||
|
|
1. **Idle** —— `grpc.Dial()` 立即返回，后台不自动发起连接。直到第一次 RPC 调用或某个 subchannel 需要重建时才触发连接。
|
|||
|
|
2. **Connecting** —— 正在建立 TCP → TLS（如启用安全模式）→ HTTP/2 Preface 握手。这个阶段发来的 call 会被排队，由 `WaitForReady` 控制超时行为。
|
|||
|
|
3. **Ready** —— 连接就绪，可以正常收发 RPC。picker 从可用的 subchannels 中选择一个来发送请求。
|
|||
|
|
4. **TransientFailure** —— 所有后端都不可达时进入此状态。此时新 call 直接失败（除非设了 `WaitForReady`），但 gRPC 会在 backoff 到期后自动尝试重连。
|
|||
|
|
5. **Closing** —— `conn.Close()` 被调用，启动优雅关闭流程：等待在跑的 stream 完成，然后终止所有子连接。
|
|||
|
|
|
|||
|
|
> [!question] Dial 到底是同步还是异步？
|
|||
|
|
> 答案很微妙：`grpc.Dial()` 本身是同步的——它马上返回 `*grpc.ClientConn`。但连接的**建立过程是异步的**。这意味着你在 dial 返回后立刻发第一个 call 时，如果连接还没 ready，这个 call 会阻塞在排队中等待连接就绪。你可以用 `conn.WaitForStateChange()` 或者 StatsHandler 来主动监听状态变化。
|
|||
|
|
|
|||
|
|
## 生产最佳实践
|
|||
|
|
|
|||
|
|
- **永远在进程启动时建立一次连接，复用 `conn` 对象**——gRPC 内部是连接池，重新 dial 会创建新的子连接并浪费资源。
|
|||
|
|
- **永远不要因某个 call 失败就重新 Dial**——gRPC 自带 transport-layer 重连逻辑（reconnect policy），比任何手动重试都可靠。
|
|||
|
|
- **跨机房部署时必须配置 keepalive**，否则几乎必然遇到半死连接（NAT/LB 已断连但客户端不知情）。
|
|||
|
|
- **使用 `grpc.StatsHandler` 监控连接状态变化**，将子连接数、transient failure 次数等指标接入 Prometheus/Grafana。
|
|||
|
|
- **生产环境禁用 insecure credentials，务必使用 TLS**——这看起来是废话，但在 CI/CD 环境中我们见过太多忘记改的测试配置流入生产。
|
|||
|
|
|
|||
|
|
> [!tip] 预热连接（Connection Warm-up）
|
|||
|
|
> DNS resolver 解析后不会立刻建立连接，直到第一次 RPC 调用才触发握手。如果需要降低首次调用的尾延迟，可以在进程启动后立即发一个健康检查 call：
|
|||
|
|
> ```go
|
|||
|
|
> // 利用 WaitForReady 避免首次调用的排队超时
|
|||
|
|
> healthConn, _ := grpc.Dial(addr, opts...)
|
|||
|
|
> defer healthConn.Close()
|
|||
|
|
> healthClient := health.NewClient(healthConn)
|
|||
|
|
> healthClient.Check(context.Background(), &healthpb.HealthCheckRequest{Service: "my.Service"})
|
|||
|
|
> ```
|
|||
|
|
|
|||
|
|
## 关联笔记
|
|||
|
|
|
|||
|
|
- [[../2. gRPC 核心篇/07-HTTP2 传输原理]] — HTTP/2 frame、stream multiplexing 和 flow control 原理
|
|||
|
|
- [[12-Call Options 与 Context]] — call-level options、retry policy 匹配规则、context 取消传播
|
|||
|
|
- [[../3. 服务端实现/10-健康检查与反射]] — health check API，与 warm-up 技巧配合使用
|
|||
|
|
- [[../6. 工程实践篇/20-性能优化与压测]] — 连接池复用、compression、gRPC-bench 压测手法
|