// hello.proto
syntax = "proto3";

package hello;

service Greeter {
  // 一元 RPC
  rpc SayHello (HelloRequest) returns (HelloResponse) {}

  // 服务端流式
  rpc StreamHello (HelloRequest) returns (stream HelloResponse) {}
}

message HelloRequest {
  string name = 1;
}

message HelloResponse {
  string message = 1;
}

一个 int32 字段，值为 150 的编码过程：

1. Tag = (field_number << 3) | wire_type
   field_number=1, wire_type=0 => 0x08

2. Value 150 的 Varint 编码：
   150 = 0b10010110
   分组：0100110 + 0000001
   加 MSB：1010110 00000001 => 0x96 0x01

3. 最终字节：[0x08, 0x96, 0x01]

Client                Server
  |--- Request --------->|
  |<--- Response ---------|
  |--- Trailers (status)-→|

// 服务端实现
func (s *server) SayHello(ctx context.Context, req *pb.HelloRequest) (*pb.HelloResponse, error) {
    // 业务逻辑
    return &pb.HelloResponse{Message: "Hello " + req.Name}, nil
}

// 客户端调用
conn, _ := grpc.Dial("localhost:50051", grpc.WithInsecure())
client := pb.NewGreeterClient(conn)
resp, err := client.SayHello(context.Background(), &pb.HelloRequest{Name: "World"})

// 服务端实现：每秒推送一次股票价格
func (s *stockServer) StreamPrices(req *pb.StockRequest, stream pb.Stock_StreamPricesServer) error {
    ticker := time.NewTicker(1 * time.Second)
    defer ticker.Stop()

    for {
        select {
        case <-ticker.C:
            price := fetchCurrentPrice(req.Symbol)
            if err := stream.Send(&pb.PriceResponse{Price: price}); err != nil {
                return err  // 客户端断开连接
            }
        case <-stream.Context().Done():
            return stream.Context().Err()  // 客户端主动取消
        }
    }
}

// 服务端：接收多个温度读数，返回平均值
func (s *monitorServer) UploadTemperatures(stream pb.Monitor_UploadTemperaturesServer) error {
    var sum, count float64

    for {
        reading, err := stream.Recv()
        if err == io.EOF {
            return stream.SendAndClose(&pb.AvgResponse{Average: sum / count})
        }
        if err != nil {
            return err
        }
        sum += reading.Temperature
        count++
    }
}

// 服务端：简单回声服务
func (s *chatServer) Chat(stream pb.Chat_ChatServer) error {
    // 独立处理接收
    go func() {
        for {
            msg, err := stream.Recv()
            if err != nil {
                return
            }
            // 处理消息...
        }
    }()

    // 独立处理发送
    for {
        select {
        case outMsg := <-broadcastChan:
            if err := stream.Send(outMsg); err != nil {
                return err
            }
        case <-stream.Context().Done():
            return stream.Context().Err()
        }
    }
}

// 设置绝对截止时间
ctx, cancel := context.WithDeadline(context.Background(), time.Now().Add(5*time.Second))
defer cancel()

resp, err := client.SayHello(ctx, &pb.HelloRequest{Name: "World"})

// 检查超时类型
if err != nil {
    if status.Code(err) == codes.DeadlineExceeded {
        log.Printf("请求超时，已取消")
    }
}

// 自定义 Unary 客户端拦截器
func metricsInterceptor(ctx context.Context, method string, req, reply interface{},
    cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {

    start := time.Now()
    err := invoker(ctx, method, req, reply, cc, opts...)
    duration := time.Since(start)

    // 上报指标
    metrics.RecordRPC(method, duration, err)

    logger.Infof("RPC %s completed in %v, err=%v", method, duration, err)
    return err
}

// 注册拦截器
conn, err := grpc.Dial(addr, grpc.WithUnaryInterceptor(metricsInterceptor))

// 使用 round_robin
conn, err := grpc.Dial(
    "dns:///my-service:50051",
    grpc.WithDefaultServiceConfig(`{"loadBalancingPolicy":"round_robin"}`),
    grpc.WithInsecure(),
)

// 推荐：单连接复用
conn, err := grpc.Dial(
    "server:50051",
    grpc.WithInitialWindowSize(65535),         // 流控窗口
    grpc.WithInitialConnWindowSize(1024*1024), // 连接窗口
    grpc.WithKeepaliveParams(keepalive.ClientParameters{
        Time:                30 * time.Second, // 每 30s ping 一次
        Timeout:             10 * time.Second, // ping 超时
        PermitWithoutStream: true,             // 空闲时也 ping
    }),
)

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

// 服务端返回业务错误
func (s *authServer) Login(ctx context.Context, req *pb.LoginRequest) (*pb.LoginResponse, error) {
    if req.Username == "" {
        return nil, status.Error(codes.InvalidArgument, "username cannot be empty")
    }

    user, err := s.db.FindUser(req.Username)
    if err != nil {
        // 包装底层错误
        return nil, status.Errorf(codes.NotFound, "user %s not found: %v", req.Username, err)
    }

    // 成功时也建议设置状态（通过 Trailer）
    return &pb.LoginResponse{Token: token}, nil
}

// 客户端判断错误
resp, err := client.Login(ctx, req)
if err != nil {
    if s, ok := status.FromError(err); ok {
        switch s.Code() {
        case codes.InvalidArgument:
            log.Printf("参数错误: %s", s.Message())
        case codes.NotFound:
            log.Printf("用户不存在")
        default:
            log.Printf("未知错误: %v", err)
        }
    }
}

// 使用 Prometheus 客户端
var (
    rpcDuration = prometheus.NewHistogramVec(
        prometheus.HistogramOpts{
            Name:    "grpc_client_duration_seconds",
            Buckets: prometheus.DefBuckets,
        },
        []string{"method", "status"},
    )
)

// 使用 OpenTelemetry 自动注入
import "go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"

conn, err := grpc.Dial(addr,
    grpc.WithUnaryInterceptor(otelgrpc.UnaryClientInterceptor()),
)

// 服务端加载证书
func loadTLSCreds() (credentials.TransportCredentials, error) {
    cert, err := tls.LoadX509KeyPair("server.crt", "server.key")
    if err != nil {
        return nil, err
    }

    caCert, _ := ioutil.ReadFile("ca.crt")
    certPool := x509.NewCertPool()
    certPool.AppendCertsFromPEM(caCert)

    tlsConfig := &tls.Config{
        Certificates: []tls.Certificate{cert},
        ClientAuth:   tls.RequireAndVerifyClientCert,
        ClientCAs:    certPool,
        MinVersion:   tls.VersionTLS12,
    }

    return credentials.NewTLS(tlsConfig), nil
}

// 启动服务
creds, _ := loadTLSCreds()
s := grpc.NewServer(grpc.Creds(creds))

# headless-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: grpc-server
spec:
  clusterIP: None  # Headless
  selector:
    app: grpc-server
  ports:
  - port: 50051

// 客户端使用 DNS resolver
resolver.SetDefaultScheme("dns")  // 启用 DNS 解析
conn, _ := grpc.Dial("dns:///grpc-server.default.svc.cluster.local:50051",
    grpc.WithDefaultServiceConfig(`{"loadBalancingPolicy":"round_robin"}`),
)

// 服务端优雅关闭
s := grpc.NewServer(grpc.UnaryInterceptor(logInterceptor))
pb.RegisterGreeterServer(s, &server{})

// 健康检查服务注册
healthcheck := health.NewServer()
healthpb.RegisterHealthServer(s, healthcheck)
healthcheck.SetServingStatus("", healthpb.HealthCheckResponse_SERVING)

go func() {
    if err := s.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
}()

// 监听退出信号
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit

// 开始优雅关闭
log.Println("shutting down gracefully...")
healthcheck.SetServingStatus("", healthpb.HealthCheckResponse_NOT_SERVING)
s.GracefulStop()  // 等待现有请求完成

# envoy.yaml
admin:
  access_log_path: /tmp/admin_access.log
  address:
    socket_address: { address: 0.0.0.0, port_value: 9901 }

static_resources:
  listeners:
  - name: listener_http
    address:
      socket_address: { address: 0.0.0.0, port_value: 8080 }
    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          http_filters:
          - name: envoy.filters.http.grpc_web
          - name: envoy.filters.http.router
          route_config:
            virtual_hosts:
            - name: backend
              domains: ["*"]
              routes:
              - match: { prefix: "/" }
                route: { cluster: grpc_backend }

  clusters:
  - name: grpc_backend
    type: STRICT_DNS
    typed_extension_protocol_options:
      envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
        "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
        explicit_http_config:
          http2_protocol_options: {}
    load_assignment:
      cluster_name: grpc_backend
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address: { address: 127.0.0.1, port_value: 50051 }

// 使用 protoc 生成 JS 代码
// protoc -I=. hello.proto --js_out=import_style=commonjs:. --grpc-web_out=import_style=commonjs,mode=grpcwebtext:.

import { GreeterClient } from './hello_grpc_web_pb';
import { HelloRequest } from './hello_pb';

const client = new GreeterClient('http://localhost:8080');
const request = new HelloRequest();
request.setName('World');

client.sayHello(request, {}, (err, response) => {
  if (err) {
    console.error('Error:', err);
  } else {
    console.log('Response:', response.getMessage());
  }
});

是否面向公网且消费者是浏览器?
 ├─ 是 → REST 或 GraphQL
 └─ 否 → 是否要求极致性能?
      ├─ 是 → gRPC
      └─ 否 → 是否需要强类型跨语言?
           ├─ 是 → gRPC
           └─ 否 → 简单 REST

import "google/api/annotations.proto";

service Greeter {
  rpc SayHello(HelloRequest) returns (HelloResponse) {
    option (google.api.http) = {
      post: "/v1/hello"
      body: "*"
    };
  }
}

curl -X POST http://localhost:8080/v1/hello   -H "Content-Type: application/json"   -d '{"name": "World"}'