gRPC 与 Protocol Buffers

syntax = "proto3";

package order.v1;

option go_package = "github.com/yourorg/order/v1;orderv1";

// 订单服务定义
service OrderService {
  // 创建订单
  rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
  // 查询订单
  rpc GetOrder(GetOrderRequest) returns (Order);
  // 订单列表(服务端流式)
  rpc ListOrders(ListOrdersRequest) returns (stream Order);
}

// 请求消息
message CreateOrderRequest {
  string user_id = 1;
  repeated OrderItem items = 2;
  string shipping_address = 3;
}

message OrderItem {
  string product_id = 1;
  int32 quantity = 2;
  int64 price_cents = 3;  // 价格用分表示,避免浮点精度问题
}

// 响应消息
message CreateOrderResponse {
  string order_id = 1;
  OrderStatus status = 2;
}

message Order {
  string order_id = 1;
  string user_id = 2;
  repeated OrderItem items = 3;
  OrderStatus status = 4;
  google.protobuf.Timestamp created_at = 5;
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_PAID = 2;
  ORDER_STATUS_SHIPPED = 3;
  ORDER_STATUS_COMPLETED = 4;
  ORDER_STATUS_CANCELLED = 5;
}

type orderServer struct {
    orderv1.UnimplementedOrderServiceServer
    store map[string]*orderv1.Order
}

func (s *orderServer) CreateOrder(
    ctx context.Context,
    req *orderv1.CreateOrderRequest,
) (*orderv1.CreateOrderResponse, error) {
    // 参数校验
    if req.UserId == "" {
        return nil, status.Error(codes.InvalidArgument, "user_id is required")
    }
    if len(req.Items) == 0 {
        return nil, status.Error(codes.InvalidArgument, "at least one item required")
    }

    // 业务逻辑
    order := &orderv1.Order{
        OrderId: uuid.New().String(),
        UserId:  req.UserId,
        Items:   req.Items,
        Status:  orderv1.OrderStatus_ORDER_STATUS_PENDING,
    }
    s.store[order.OrderId] = order

    return &orderv1.CreateOrderResponse{
        OrderId: order.OrderId,
        Status:  order.Status,
    }, nil
}

func main() {
    lis, _ := net.Listen("tcp", ":50051")
    srv := grpc.NewServer()
    orderv1.RegisterOrderServiceServer(srv, &orderServer{
        store: make(map[string]*orderv1.Order),
    })
    srv.Serve(lis)
}

func main() {
    conn, _ := grpc.Dial("localhost:50051", grpc.WithInsecure())
    defer conn.Close()

    client := orderv1.NewOrderServiceClient(conn)

    resp, err := client.CreateOrder(context.Background(),
        &orderv1.CreateOrderRequest{
            UserId: "user-001",
            Items: []*orderv1.OrderItem{
                {ProductId: "prod-1", Quantity: 2, PriceCents: 9900},
            },
            ShippingAddress: "北京市海淀区",
        },
    )
    if err != nil {
        st, _ := status.FromError(err)
        log.Fatalf("RPC failed: code=%s msg=%s", st.Code(), st.Message())
    }
    fmt.Printf("Order created: %s\n", resp.OrderId)
}

import (
    "google.golang.org/grpc/status"
    "google.golang.org/grpc/codes"
    errdetails "google.golang.org/genproto/googleapis/rpc/errdetails"
)

// 服务端:返回带字段级错误详情
st := status.New(codes.InvalidArgument, "invalid request")
st, _ = st.WithDetails(&errdetails.BadRequest{
    FieldViolations: []*errdetails.BadRequest_FieldViolation{
        {Field: "email", Description: "must be valid email format"},
        {Field: "age", Description: "must be positive"},
    },
})
return nil, st.Err()

// 客户端:解析错误详情
st, _ := status.FromError(err)
for _, detail := range st.Details() {
    if br, ok := detail.(*errdetails.BadRequest); ok {
        for _, v := range br.FieldViolations {
            fmt.Printf("field %s: %s\n", v.Field, v.Description)
        }
    }
}

func loggingInterceptor(
    ctx context.Context,
    req interface{},
    info *grpc.UnaryServerInfo,
    handler grpc.UnaryHandler,
) (interface{}, error) {
    start := time.Now()

    // 调用实际处理器
    resp, err := handler(ctx, req)

    // 记录日志
    duration := time.Since(start)
    code := status.Code(err)
    log.Printf("method=%s duration=%v code=%s", info.FullMethod, duration, code)

    return resp, err
}

// 注册
srv := grpc.NewServer(
    grpc.UnaryInterceptor(loggingInterceptor),
)

srv := grpc.NewServer(
    grpc.ChainUnaryInterceptor(
        recoveryInterceptor,   // 最外层:panic 恢复
        loggingInterceptor,    // 日志
        authInterceptor,       // 认证
        rateLimitInterceptor,  // 限流
    ),
)

// 客户端:发送 metadata
md := metadata.Pairs(
    "authorization", "Bearer "+token,
    "x-request-id", uuid.New().String(),
)
ctx := metadata.NewOutgoingContext(ctx, md)
resp, err := client.GetOrder(ctx, req)

// 服务端:读取 metadata
md, ok := metadata.FromIncomingContext(ctx)
if !ok {
    return nil, status.Error(codes.Unauthenticated, "missing metadata")
}
tokens := md.Get("authorization")
if len(tokens) == 0 {
    return nil, status.Error(codes.Unauthenticated, "missing token")
}

// 客户端设置 3 秒超时
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()

resp, err := client.CreateOrder(ctx, req)
if status.Code(err) == codes.DeadlineExceeded {
    // 超时处理
}

// v1 版本
package order.v1;
service OrderService { ... }

// v2 版本(破坏性变更)
package order.v2;
service OrderService { ... }

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order) {
    option (google.api.http) = {
      get: "/v1/orders/{order_id}"
    };
  }
}

message User { int32 age = 1; }

User{}          // 没设置 age
User{age: 0}    // 显式把 age 设成 0
// ↑ 两者序列化后的字节完全相同,接收方拿到的 age 都是 0

enum OrderStatus {
  PENDING = 0;    // ✗ 把有效状态放在了 0
  PAID = 1;
  SHIPPED = 2;
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;   // ✓ 0 = 未设置,不是有效状态
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_PAID = 2;
  ORDER_STATUS_SHIPPED = 3;
}

// 接收方可以主动校验并拒绝
if order.status == ORDER_STATUS_UNSPECIFIED {
    return error("status is required")
}

import "google/protobuf/field_mask.proto";

message UpdateUserRequest {
  User user = 1;
  google.protobuf.FieldMask update_mask = 2;   // 要更新的字段路径
}

// 调用:明确只动 nickname 和 bio
UpdateUserRequest{
  user: User{nickname: "新名字", bio: ""},
  update_mask: { paths: ["nickname", "bio"] }
}

message ListPostsRequest {
  int32 page_size = 1;
  string page_token = 2;   // 上次返回的 next_page_token,首次为空
}
message ListPostsResponse {
  repeated Post posts = 1;
  string next_page_token = 2;
}

conn, _ := grpc.Dial(target,
    grpc.WithKeepaliveParams(keepalive.ClientParameters{
        Time:                10 * time.Second, // 10s 无活动则发 ping
        Timeout:             3 * time.Second,  // ping 3s 无响应则断开
        PermitWithoutStream: true,             // 无活跃流时也保持心跳
    }),
)