gRPC在Go中默认基于HTTP/2实现长连接，无需额外开启；需重点配置服务端keepalive、客户端复用ClientConn及PermitWithoutStream开关，并正确使用--go_out和--go-grpc_out双参数生成代码。
gRPC 在 Go 中默认就是长连接，不需要额外“开启”或“配置”长连接——它基于 HTTP/2，连接复用是协议原生行为。真正需要你动手干预的，是避免连接意外中断、控制连接生命周期、以及防止服务端因空闲超时断连。
protoc 生成代码时必须指定 --go-grpc_out 而非 --grpc_out
很多初学者复制旧教程命令，写成 protoc --grpc_out=. service.proto，结果报错：unrecognized option '--grpc_out' 或生成的代码里没有 RegisterXXXServer 函数。这是因为老版本插件已废弃，新版本（2021 年后）严格区分：
-
--go_out=.：只生成数据结构（*.pb.go），不含服务桩 -
--go-grpc_out=.：生成服务接口和注册函数（*_grpc.pb.go） - 两个参数必须**同时使用**，缺一不可
- 确保
protoc-gen-go-grpc在 PATH 中，且版本与google.golang.org/grpc兼容（推荐 v1.60+）
服务端空闲超时导致连接被重置
常见现象：客户端连续发请求正常，但隔 5–10 分钟不调用后，下一次调用直接报 rpc error: code = Unavailable desc = transport is closing。这不是 gRPC 本身问题，而是底层 HTTP/2 连接被服务端或中间代理（如 Nginx、Envoy）主动关闭了。
- Go gRPC 服务端默认无 keepalive 配置，不发 ping 帧，连接空闲即失效
- 解决方法是在
grpc.NewServer时传入 keepalive 选项：
import "google.golang.org/grpc/keepalive"
<p>s := grpc.NewServer(
grpc.KeepaliveParams(keepalive.ServerParameters{
MaxConnectionIdle: 30 <em> time.Minute, // 连接空闲多久后关闭
MaxConnectionAge: 45 </em> time.Minute, // 连接最大存活时间
Time: 10 <em> time.Second, // ping 间隔
Timeout: 3 </em> time.Second, // ping 响应超时
}),
)
- 注意：
MaxConnectionIdle和Time是关键；若设为 0 表示禁用，但不推荐，可能引发连接泄漏 - 如果用了反向代理，还需同步配置其 keepalive 参数（例如 Nginx 的
keepalive_timeout）
客户端连接复用失败：每次调用都新建 TCP 连接
表现是 netstat -an | grep :50051 显示大量 TIME_WAIT 状态连接，QPS 上不去。根本原因在于客户端未复用 *grpc.ClientConn 实例。
立即学习“go语言免费学习笔记（深入）”；
- 错误写法：每个请求都
grpc.Dial(...)→defer conn.Close()→ 连接无法复用 - 正确做法：全局复用一个
*grpc.ClientConn，并在整个应用生命周期内保持打开 - 务必设置连接选项，否则默认不健康检查、不重试：
conn, err := grpc.Dial("localhost:50051",
grpc.WithTransportCredentials(insecure.NewCredentials()),
grpc.WithBlock(), // 同步阻塞等待连接就绪（开发期可选）
grpc.WithKeepaliveParams(keepalive.ClientParameters{
Time: 10 * time.Second,
Timeout: 3 * time.Second,
PermitWithoutStream: true, // 即使没活跃流也发 keepalive
}),
)
if err != nil {
log.Fatal(err)
}
defer conn.Close() // 注意：这里 defer 不应在每次请求时执行！
-
PermitWithoutStream是关键开关，不设它，空闲时 keepalive 帧不会发送 - 生产环境建议配合
grpc.WithResolvers或服务发现做连接管理
proto 中 optional 字段在 Go 生成代码后行为易混淆
proto3 默认字段都是“可选”，但 Go 生成的 struct 字段仍是值类型（如 int32、string），无法区分“未设置”和“设为零值”。加 optional 关键字（proto3.12+）后，字段会变成指针类型，但需注意兼容性陷阱：
- 仅当
syntax = "proto3"且 protoc ≥ v3.21 才支持optional - 生成后字段变为
*string、*int32，判空需用req.Name != nil && *req.Name != "" - 如果服务端接收的是旧版 client（未加
optional），而 proto 文件新增了optional，会导致编译失败或运行时 panic - 更稳妥的做法：对真正需要区分“未传”和“传了空字符串”的字段，显式定义 wrapper 类型（如
google.protobuf.StringValue）
长连接不是“开了就完事”的开关，它是 HTTP/2 协议能力 + 客户端连接池管理 + 服务端保活策略 + 中间件协同的结果。最容易被忽略的是客户端连接复用时机和 keepalive 的 PermitWithoutStream 开关——这两处一错，长连接就退化成短连接。
