约 12 分钟7 张卡

gRPC-Go

gRPC-Go 是 gRPC 的 Go 实现，通过生成的客户端和服务端接口承载远程调用。写起来像调用一个 Go 方法，实际仍然经过连接建立、编码、网络传输和远端执行；返回错误时，不能只按本地函数失败来理解业务结果。

本文使用 Go 1.22.12、gRPC-Go v1.65.0 与 Protocol Buffers Go v1.35.1，重点是调用生命周期和资源边界。协议分层、四种调用形式与最终状态见 gRPC。

1. 面试核心

先记住这几条，再读正文

生成代码负责消息类型和调用接口，不自动实现业务规则。服务端仍要校验输入、检查权限并处理失败。卡 · 接口契约与生成代码
ClientConn 是可复用的逻辑通信入口，不等于一条永远不变的 TCP 连接。NewClient 创建成功不证明远端可达；调用错误仍需逐次处理。卡 · ClientConn 生命周期
deadline 限制一次调用的等待预算，取消需要处理器及下游配合。它不是强制终止任意 goroutine，也不自动回滚已完成的副作用。卡 · 总预算与取消
状态码表达失败类别，不证明操作执行了几次或是否已经提交。重试还需要幂等、次数、退避与总预算约束。卡 · 状态码与重试
一元与流式调用使用不同拦截器。链中顺序影响观察和处理范围，共享状态仍要满足并发安全要求。卡 · 拦截器与 metadata
创建流成功不代表整个流成功。要读取到正常 EOF 或最终错误，并通过取消等方式释放提前结束的流。卡 · 最终状态与资源释放
GracefulStop 会等待在途 RPC，长流可能使等待持续下去。关闭流程需要明确排空预算和强制结束策略。卡 · 服务排空

2. 接口契约与生成代码

卡 · 生成的 gRPC 代码负责什么，业务代码还要做什么？

下面的服务包含一个一元查询和一个服务端流式列表。消息字段编号参与编码兼容，不因调整 Go 字段顺序随意复用：

catalog.proto
syntax = "proto3";
package catalog.v1;
option go_package = "example.com/grpcdemo/catalogpb";

service Catalog {
  rpc Get(GetRequest) returns (Item);
  rpc List(ListRequest) returns (stream Item);
}
message GetRequest { int64 id = 1; }
message ListRequest { int32 limit = 1; }
message Item {
  int64 id = 1;
  string name = 2;
}

假设 Go 模块名为 example.com/grpcdemo，使用 protoc 和已安装的 protoc-gen-go、protoc-gen-go-grpc 生成代码：

protoc -I . --go_out=. --go_opt=module=example.com/grpcdemo \
  --go-grpc_out=. --go-grpc_opt=module=example.com/grpcdemo catalog.proto

本文使用 protoc-gen-go v1.35.1 和 protoc-gen-go-grpc v1.4.0。前者生成消息与序列化相关代码，后者生成 CatalogClient、CatalogServer、注册方法和流接口。生成物放入 catalogpb 包，业务实现放在自己的包中，不手工修改生成文件。

proto3 的普通标量字段有默认值。这里请求中的 id 缺省时为零，是否接受由业务决定；如果必须区分“未提供”和“明确提供零”，应在契约中表达字段存在性，而不能只检查生成结构体里的零值。

3. 服务端实现

卡 · 生成的 gRPC 代码负责什么，业务代码还要做什么？

下面只保留参数校验、状态码和逐条发送，用固定数据说明调用行为：

server.go
package catalog

import (
    "context"
    "fmt"

    pb "example.com/grpcdemo/catalogpb"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

type Server struct {
    pb.UnimplementedCatalogServer
}

func (Server) Get(ctx context.Context, req *pb.GetRequest) (*pb.Item, error) {
    if err := ctx.Err(); err != nil {
        return nil, status.FromContextError(err).Err()
    }
    if req.GetId() <= 0 {
        return nil, status.Error(codes.InvalidArgument, "id must be positive")
    }
    if req.GetId() > 3 {
        return nil, status.Error(codes.NotFound, "item not found")
    }
    return &pb.Item{Id: req.GetId(), Name: fmt.Sprintf("item-%d", req.GetId())}, nil
}

func (Server) List(req *pb.ListRequest, stream pb.Catalog_ListServer) error {
    if req.GetLimit() < 1 || req.GetLimit() > 3 {
        return status.Error(codes.InvalidArgument, "limit must be between 1 and 3")
    }
    for id := int64(1); id <= int64(req.GetLimit()); id++ {
        if err := stream.Context().Err(); err != nil {
            return status.FromContextError(err).Err()
        }
        if err := stream.Send(&pb.Item{Id: id, Name: fmt.Sprintf("item-%d", id)}); err != nil {
            return err
        }
    }
    return nil
}

服务通过 pb.RegisterCatalogServer(grpcServer, Server{}) 注册到 grpc.Server。Get 的正常请求返回一条记录，非法参数与缺失记录分别返回 InvalidArgument 和 NotFound；List 逐条发送，返回 nil 表示处理器正常结束。

嵌入 UnimplementedCatalogServer 提供生成接口的默认未实现行为，但不会替新 RPC 完成业务。gRPC-Go 会并发调用处理器；这个示例没有可变共享状态，换成 map、计数器或连接依赖后，应另外保证并发安全。

处理器里调用数据库或下游 RPC 时，继续传入当前 context。不要无条件换成 Background，否则上游取消和剩余 deadline 就无法沿这条调用链继续传递。

4. 客户端与 deadline

卡 · NewClient 成功是否证明服务可用，ClientConn 应该怎样复用？卡 · 客户端 deadline 到期后，服务端一定停止且没有副作用吗？

4.1 ClientConn 生命周期

ClientConn 管理目标解析、连接与调用等状态。可以在多个 goroutine 中复用同一个 ClientConn 和生成的客户端，应用退出时再关闭，不必每次 RPC 都新建和销毁。

client.go
package catalog

import (
    "context"
    "time"

    pb "example.com/grpcdemo/catalogpb"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
)

func NewClient(target string, creds credentials.TransportCredentials) (*grpc.ClientConn, pb.CatalogClient, error) {
    conn, err := grpc.NewClient(target, grpc.WithTransportCredentials(creds))
    if err != nil {
        return nil, nil, err
    }
    return conn, pb.NewCatalogClient(conn), nil
}

func GetItem(parent context.Context, client pb.CatalogClient, id int64) (*pb.Item, error) {
    ctx, cancel := context.WithTimeout(parent, 500*time.Millisecond)
    defer cancel()
    return client.Get(ctx, &pb.GetRequest{Id: id})
}

调用方持有返回的 conn，并在不再需要时调用 conn.Close()。传输凭据由调用方提供；TLS 配置需要校验服务端身份和信任根，本机明文实验使用 insecure 凭据时也应限定在实验环境。

本文版本的 grpc.NewClient 不执行网络 I/O。因此，即使端口没有服务，构造也可能成功，真正的连接或调用错误在 RPC 时出现。ClientConn 还可能管理重连与多个底层连接，不能把一次成功连接当作后续调用可用性的保证。

4.2 总预算与取消

GetItem 给当前调用设置最多 500 毫秒预算。如果 parent 更早到期，子 context 不能把期限延长到父级之后。超时预算要覆盖建立可用连接、排队、远端处理和返回等等待，不只是业务函数中某一段计算。

没有 deadline 的调用可能等待很久；WaitForReady(true) 还可以让调用在连接处于暂时失败状态时继续等待可用性，因此更需要有限 deadline。它不是无限重试业务的授权，也不保证服务最终恢复。

客户端超时后，服务端 context 会获得取消信号，但处理器要检查信号并让下游协作退出。忽略 context 的计算或阻塞动作可能继续存在；取消前已经提交的数据库修改也不会由 gRPC 回滚，见 gRPC 的取消不等于回滚。

5. 状态码与重试

卡 · 收到 Unavailable 或 DeadlineExceeded 就能直接重试吗？

状态码帮助调用方区分失败类别。Go 中使用 status.Code(err) 读取，不通过匹配错误消息文本来决定行为：

状态	常见语义	不能直接推出的结论
InvalidArgument	请求参数不满足要求	反复发送相同请求就能成功
NotFound	请求的对象不存在	底层服务整体不可用
DeadlineExceeded	当前调用超过时间预算	远端没有执行或没有提交
Canceled	调用被取消	远端所有后台动作已经结束
Unavailable	当前服务或传输暂时不可用	操作一定没有产生副作用，可以任意重试
Internal	服务内部出现问题	可以把内部 SQL、堆栈或凭据直接交给客户端

普通 Go error 若没有映射为明确 gRPC 状态，客户端可能看到 Unknown。服务端应按 API 语义转换内部错误，保留诊断信息在受控日志中；不能把每种下游错误都原样透传成上层接口的同一种含义。

重试需要同时回答：操作是否幂等，是否有稳定的请求标识，最多尝试几次，退避怎样进行，总 deadline 还剩多少。客户端没有收到成功响应时，远端仍可能已经提交，因此“重试后只执行一次”需要业务协议保证。

库的透明重试和服务配置重试各有条件，不能把没有手写循环理解成“绝不会有重试”，也不能把自动重试理解成任意方法都获得恰好一次执行。具体重试策略应与服务端的幂等和结果确认方式共同设计。

6. 拦截器与 metadata

卡 · Unary 拦截器能覆盖所有 RPC 吗，链的顺序有什么影响？

拦截器在调用进入处理器或离开客户端时组织公共逻辑，例如观测、身份验证和错误转换。一元调用与流式调用分别配置 Unary 和 Stream 拦截器，不能只安装 Unary 就认为覆盖了所有 RPC。

interceptor.go
package catalog

import (
    "context"
    "time"

    "google.golang.org/grpc"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

func TimingUnary(observe func(string, codes.Code, time.Duration)) grpc.UnaryServerInterceptor {
    return func(ctx context.Context, req any, info *grpc.UnaryServerInfo,
        handler grpc.UnaryHandler) (any, error) {
        start := time.Now()
        response, err := handler(ctx, req)
        observe(info.FullMethod, status.Code(err), time.Since(start))
        return response, err
    }
}

observe 由调用方提供，必须能够安全地被多个 RPC 并发调用。它观察的是这个拦截器包住的处理过程，不等于客户端测到的完整网络耗时，也不覆盖流式方法或处理器 panic 的恢复。

grpc.ChainUnaryInterceptor(A, B) 让 A 包住 B，再进入处理器。入口通常按 A、B 的顺序执行，返回时反向展开；某层直接返回错误，可以阻止后续层和处理器执行。鉴权放在哪一层、日志能否观察拒绝结果，都取决于实际顺序。

metadata 是随 RPC 传递的附加信息。客户端可以通过 metadata.AppendToOutgoingContext 发送指定字段，服务端通过 metadata.FromIncomingContext 读取。context 中任意 Value 不会自动序列化到网络另一端。

metadata 本身也不是可信身份。令牌、租户和追踪字段需要各自的校验与传递规则；不要把收到的所有 metadata 不加选择地转发给任何下游。流的 metadata、最终 trailer 和状态也有自己的可用时机。

7. 流与关闭流程

卡 · 为什么创建流成功和 CloseSend 都不等于调用最终成功？卡 · GracefulStop 为什么也需要关闭预算？

7.1 最终状态与资源释放

客户端需要持续读取服务端流，直到正常结束或遇到错误：

stream.go
package catalog

import (
    "context"
    "io"
    "time"

    pb "example.com/grpcdemo/catalogpb"
)

func ListItems(parent context.Context, client pb.CatalogClient, limit int32) ([]*pb.Item, error) {
    ctx, cancel := context.WithTimeout(parent, time.Second)
    defer cancel()
    stream, err := client.List(ctx, &pb.ListRequest{Limit: limit})
    if err != nil {
        return nil, err
    }
    items := make([]*pb.Item, 0)
    for {
        item, err := stream.Recv()
        if err == io.EOF {
            return items, nil
        }
        if err != nil {
            return nil, err
        }
        items = append(items, item)
    }
}