gRPC Server Streaming 的正确函数签名是 func (s Server) ListItems(req ListRequest, stream Service_ListItemsServer) error，其中请求参数在前、stream 参数在后，无独立 context 参数，且必须返回 error 类型。
gRPC Server Streaming 的函数签名怎么写
Go 里实现服务端流式响应，核心是把返回类型从 *Response 改成 stream，且必须是服务端可写的流——也就是 StreamingServer 类型的参数。不是你 return 一个切片，而是通过传入的 stream 对象反复调用 Send()。
常见错误：写成 func (s *Server) ListItems(ctx context.Context, req *ListRequest) (*ListResponse, error)，这是一元 RPC，根本不会触发流式行为。
- 正确签名长这样：
func (s *Server) ListItems(req *ListRequest, stream Service_ListItemsServer) error -
Service_ListItemsServer是 protoc-gen-go 自动生成的接口，含Send(*ListItem)和Context()等方法 - 注意参数顺序：请求消息在前，stream 在后；没有 context 单独参数——
stream.Context()就是你要的上下文 - 函数必须返回
error，不能是void或其他类型，gRPC 框架靠它判断流是否正常结束
Send() 调用时机和阻塞风险
Send() 不是异步投递，它是同步写入底层 HTTP/2 流的，如果客户端消费慢、网络卡住或主动断连，Send() 会阻塞，甚至永久 hang 住你的 goroutine。
典型现象：服务端协程卡死，CPU 低但连接数持续上涨，netstat 显示大量 ESTABLISHED + CLOSE_WAIT。
立即学习“go语言免费学习笔记（深入）”；
- 务必在每次
Send()后检查err，尤其关注io.EOF和status.Error（如codes.Canceled） - 别假设客户端一定在线——加超时控制：
ctx, cancel := context.WithTimeout(stream.Context(), 30*time.Second)，并在循环中用select { case - 避免在
Send()前做重计算或 DB 查询，否则阻塞会拖累整个流；提前准备好数据，或用带缓冲的 channel 解耦生产与发送
客户端如何正确读取 ServerStream
客户端拿到的 Service_ClientListItemsClient 接口，关键方法是 Recv()，它每次返回一个 *ListItem 和 error。很多人误以为能像 channel 一样 range，其实不能——必须显式循环调用 Recv()，直到 error 非 nil。
常见错误：用 for item := range client 编译不过；或只调一次 Recv() 就退出，漏掉后续消息。
- 标准读法：
for { item, err := client.Recv(); if err != nil { break }; handle(item) } -
err == io.EOF表示服务端正常关闭流；err != nil && err != io.EOF才是异常中断（如网络断开、服务崩溃） - 别在
Recv()外层套context.WithTimeout——它自带超时逻辑，用client.Context().Done()更准确 - 如果需要并发处理多个流，每个
Recv()循环应独立 goroutine，但注意流本身不支持并发Recv()
流式 RPC 的错误传播和状态码陷阱
Server Streaming 中，服务端可以在任意时刻调用 return err 结束流，但这个 err 不会立刻发给客户端——gRPC 会等所有已发出的 message 全部 flush 完，再发 status frame。这就导致「错误延迟可见」。
更隐蔽的问题：如果你在 Send() 失败后直接 return，gRPC 可能收不到你想要的 status code，反而回一个 UNKNOWN 或 INTERNAL。
- 想发自定义错误码，必须用
status.Errorf(codes.XXX, "msg")构造 error，不能用fmt.Errorf -
Send()返回io.EOF通常意味着客户端已断开，此时应立即 return，不要再尝试 Send 或 return 其他 error - 流未关闭前，客户端调用
CloseSend()是非法操作（一元 RPC 才有），gRPC 会报rpc error: code = Unimplemented - 调试时抓包看 HTTP/2 frames 会发现：message data frame 和 trailers frame（含 status）是分开发的，中间可能有几百毫秒间隔
流式不是“多发几个 response”那么简单——它的生命周期、错误边界、背压机制都和一元 RPC 本质不同。最容易被忽略的是：服务端 Send 阻塞时，你既没做超时，也没检查 ctx.Done()，结果整条连接就挂在那儿了。
