// ✅ 好的设计
syntax = "proto3";

package example.v1;

import "google/protobuf/timestamp.proto";
import "google/protobuf/field_mask.proto";

// 使用版本化包名
service UserService {
  // 清晰的动词 + 名词
  rpc GetUser(GetUserRequest) returns (User);
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
  rpc CreateUser(CreateUserRequest) returns (User);
  rpc UpdateUser(UpdateUserRequest) returns (User);
  rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty);
}

message User {
  // 资源名称（Google AIP 风格）
  string name = 1;  // "users/123"
  
  // 输出字段用 readonly 标记
  int64 id = 2;
  string display_name = 3;
  string email = 4;
  
  // 时间戳使用 google.protobuf 类型
  google.protobuf.Timestamp create_time = 5;
  google.protobuf.Timestamp update_time = 6;
  
  // 状态使用枚举
  UserState state = 7;
  
  // 避免使用 bool flag，使用枚举
  // ❌ bool is_active = 8;
  // ✅ UserState state = 7;
}

enum UserState {
  USER_STATE_UNSPECIFIED = 0;  // 必须有默认值
  USER_STATE_ACTIVE = 1;
  USER_STATE_INACTIVE = 2;
  USER_STATE_DELETED = 3;
}

message GetUserRequest {
  // 使用资源名称
  string name = 1;  // "users/123"
}

message ListUsersRequest {
  int32 page_size = 1;
  string page_token = 2;
  string filter = 3;
  
  // 排序
  string order_by = 4;
}

message ListUsersResponse {
  repeated User users = 1;
  string next_page_token = 2;
  int32 total_size = 3;
}

message UpdateUserRequest {
  User user = 1;
  google.protobuf.FieldMask update_mask = 2;
}

// 方式 1：包名版本（推荐）
package example.v1;    // 稳定版
package example.v2;    // 新版本
package example.v1beta1;  // 测试版

// 方式 2：路径版本
// proto/example/v1/user.proto
// proto/example/v2/user.proto

// 向后兼容规则：
// ✅ 新增字段（使用新的编号）
// ✅ 新增方法
// ✅ 新增枚举值
// ❌ 删除字段（使用 reserved 保留编号）
// ❌ 修改字段类型
// ❌ 修改字段编号
// ❌ 重命名字段

// 正确处理废弃字段
message User {
  int64 id = 1;
  string name = 2;
  
  // 废弃但不删除的字段
  reserved 3;  // 保留旧编号
  reserved "old_name";  // 保留旧名称
  
  string display_name = 4;  // 新字段
}

// 服务端同时支持 v1 和 v2
package main

import (
	"google.golang.org/grpc"
)

func main() {
	server := grpc.NewServer()

	// 注册 v1 服务
	pbv1.RegisterUserServiceServer(server, &v1UserServer{})
	
	// 注册 v2 服务
	pbv2.RegisterUserServiceServer(server, &v2UserServer{})

	// v2 服务内部调用 v1 服务实现
}

// v2 服务适配层
type v2UserServer struct {
	v1 *v1UserServer
}

func (s *v2UserServer) GetUser(ctx context.Context, req *pbv2.GetUserRequest) (*pbv2.User, error) {
	// 转换请求
	v1Req := &pbv1.GetUserRequest{Id: req.Id}
	
	// 调用 v1
	v1User, err := s.v1.GetUser(ctx, v1Req)
	if err != nil {
		return nil, err
	}
	
	// 转换响应
	return &pbv2.User{
		Id:          v1User.Id,
		DisplayName: v1User.Name,  // 字段重命名
		Email:       v1User.Email,
	}, nil
}

// 定义领域错误详情
syntax = "proto3";

package example.v1;

import "google/rpc/error_details.proto";

// 自定义错误详情
message QuotaError {
  string resource = 1;
  int64 limit = 2;
  int64 current = 3;
  int64 retry_after_seconds = 4;
}

message ValidationError {
  repeated FieldViolation violations = 1;
  
  message FieldViolation {
    string field = 1;
    string description = 2;
    string reason = 3;
  }
}

// 服务端：返回结构化错误
package main

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

func (s *server) CreateUser(ctx context.Context, req *pb.CreateUserRequest) (*pb.User, error) {
	// 参数校验错误
	if req.Name == "" {
		st := status.New(codes.InvalidArgument, "参数校验失败")
		ds, _ := st.WithDetails(&errdetails.BadRequest{
			FieldViolations: []*errdetails.BadRequest_FieldViolation{
				{
					Field:       "name",
					Description: "用户名不能为空",
				},
			},
		})
		return nil, ds.Err()
	}

	// 限流错误
	if !s.rateLimiter.Allow() {
		st := status.New(codes.ResourceExhausted, "请求过于频繁")
		ds, _ := st.WithDetails(&errdetails.RetryInfo{
			RetryDelay: durationpb.New(5 * time.Second),
		})
		return nil, ds.Err()
	}

	// 业务错误
	if exists, _ := s.userExists(req.Email); exists {
		st := status.New(codes.AlreadyExists, "用户已存在")
		ds, _ := st.WithDetails(&errdetails.ResourceInfo{
			ResourceType: "user",
			ResourceName: req.Email,
			Description:  "该邮箱已被注册",
		})
		return nil, ds.Err()
	}

	// 正常处理...
	return &pb.User{}, nil
}

// 客户端：解析结构化错误
func handleGRPCError(err error) {
	if err == nil {
		return
	}

	st, ok := status.FromError(err)
	if !ok {
		log.Printf("非 gRPC 错误: %v", err)
		return
	}

	log.Printf("gRPC 错误 [%s]: %s", st.Code(), st.Message())

	// 解析详细信息
	for _, detail := range st.Details() {
		switch d := detail.(type) {
		case *errdetails.BadRequest:
			for _, v := range d.FieldViolations {
				log.Printf("  字段错误: %s - %s", v.Field, v.Description)
			}
		case *errdetails.RetryInfo:
			log.Printf("  建议重试间隔: %v", d.RetryDelay.AsDuration())
		case *errdetails.ResourceInfo:
			log.Printf("  资源: %s/%s - %s", d.ResourceType, d.ResourceName, d.Description)
		}
	}
}

# Nginx HTTP/2 配置
server {
    listen 443 ssl http2;
    
    # 启用 HTTP/2
    http2_max_concurrent_streams 256;
    http2_recv_buffer_size 256k;
    http2_idle_timeout 180s;
    
    # SSL 优化
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    ssl_session_tickets on;
    
    # HPACK 配置
    http2_max_field_size 8k;
    http2_max_header_size 16k;
}

// gRPC 服务器调优
server := grpc.NewServer(
    // 消息大小限制
    grpc.MaxRecvMsgSize(16 * 1024 * 1024),  // 16MB
    grpc.MaxSendMsgSize(16 * 1024 * 1024),  // 16MB
    
    // 并发流限制
    grpc.MaxConcurrentStreams(1000),
    
    // 连接参数
    grpc.KeepaliveParams(keepalive.ServerParameters{
        MaxConnectionIdle:     15 * time.Minute,
        MaxConnectionAge:      30 * time.Minute,
        MaxConnectionAgeGrace: 5 * time.Second,
        Time:                  5 * time.Second,
        Timeout:               1 * time.Second,
    }),
    grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
        MinTime:             5 * time.Second,
        PermitWithoutStream: true,
    }),
    
    // 拦截器链
    grpc.ChainUnaryInterceptor(
        recoveryInterceptor,
        loggingInterceptor,
        authInterceptor,
        rateLimitInterceptor,
    ),
)

// gRPC 客户端调优
conn, err := grpc.Dial(target,
    grpc.WithTransportCredentials(insecure.NewCredentials()),
    
    // 连接参数
    grpc.WithKeepaliveParams(keepalive.ClientParameters{
        Time:                10 * time.Second,
        Timeout:             3 * time.Second,
        PermitWithoutStream: true,
    }),
    
    // 负载均衡
    grpc.WithDefaultServiceConfig(`{
        "loadBalancingConfig": [{"round_robin":{}}],
        "methodConfig": [{
            "name": [{"service": "example.UserService"}],
            "timeout": "10s",
            "retryPolicy": {
                "maxAttempts": 3,
                "initialBackoff": "0.1s",
                "maxBackoff": "1s",
                "backoffMultiplier": 2.0,
                "retryableStatusCodes": ["UNAVAILABLE", "DEADLINE_EXCEEDED"]
            }
        }]
    }`),
    
    // 连接池（通过多个连接）
    // grpc.WithBalancerName 用于旧版本
)

// 1. 使用 MarshalVT（更快的序列化库）
// go get github.com/planetscale/vtprotobuf
import "github.com/planetscale/vtprotobuf/codec/grpc"

server := grpc.NewServer(
    grpc.ForceServerCodecV2(grpc.NewCodecV2(grpc.CodecOptions{
        MarshalV2: func(msg any) (data []byte, err error) {
            if vtmsg, ok := msg.(vtproto.Message); ok {
                return vtmsg.MarshalVT()
            }
            return proto.Marshal(msg.(proto.Message))
        },
    })),
)

// 2. 避免不必要的拷贝
resp, err := client.GetUser(ctx, req)
// ❌ 不好：拷贝字段
userCopy := &pb.User{
    Id:   resp.User.Id,
    Name: resp.User.Name,
}
// ✅ 好：直接使用指针
userRef := resp.User

// 3. 使用 sync.Pool 复用大对象
var bufferPool = sync.Pool{
    New: func() interface{} {
        return make([]byte, 0, 4096)
    },
}

// 高并发场景的连接池
package main

import (
	"sync"
	"sync/atomic"
	
	"google.golang.org/grpc"
)

type Pool struct {
	conns []*grpc.ClientConn
	size  int
	idx   uint64
	mu    sync.RWMutex
}

func NewPool(target string, size int, opts ...grpc.DialOption) (*Pool, error) {
	p := &Pool{
		conns: make([]*grpc.ClientConn, size),
		size:  size,
	}

	for i := 0; i < size; i++ {
		conn, err := grpc.Dial(target, opts...)
		if err != nil {
			// 关闭已创建的连接
			for j := 0; j < i; j++ {
				p.conns[j].Close()
			}
			return nil, err
		}
		p.conns[i] = conn
	}

	return p, nil
}

func (p *Pool) Get() *grpc.ClientConn {
	idx := atomic.AddUint64(&p.idx, 1)
	return p.conns[idx%uint64(p.size)]
}

func (p *Pool) Close() {
	for _, conn := range p.conns {
		conn.Close()
	}
}

// 使用示例
func main() {
	pool, err := NewPool(
		"localhost:50051",
		4, // 4 个连接
		grpc.WithTransportCredentials(insecure.NewCredentials()),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer pool.Close()

	// 轮询获取连接
	for i := 0; i < 100; i++ {
		conn := pool.Get()
		client := pb.NewUserServiceClient(conn)
		// 并发调用
		go client.GetUser(context.Background(), &pb.GetUserRequest{Id: 1})
	}
}

import (
	grpc_prometheus "github.com/grpc-ecosystem/go-grpc-prometheus"
	"github.com/prometheus/client_golang/prometheus"
	"github.com/prometheus/client_golang/prometheus/promhttp"
)

func setupMetrics(server *grpc.Server) {
	// 注册 Prometheus 指标
	grpc_prometheus.Register(server)

	// 自定义直方图桶
	grpcMetrics := grpc_prometheus.NewServerMetrics(
		grpc_prometheus.WithServerHandlingTimeHistogram(
			grpc_prometheus.WithHistogramBuckets(
				[]float64{0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10},
			),
		),
	)

	// 初始化收集器
	grpcMetrics.InitializeMetrics(server)

	// 暴露指标端点
	http.Handle("/metrics", promhttp.Handler())
	go http.ListenAndServe(":9090", nil)
}

// 常用的 gRPC 指标
/*
grpc_server_handled_total          - 处理的请求总数（按状态码分组）
grpc_server_handling_seconds       - 请求处理延迟分布
grpc_server_started_total          - 开始处理的请求总数
grpc_server_msg_received_total     - 接收的消息总数
grpc_server_msg_sent_total         - 发送的消息总数
grpc_client_handled_total          - 客户端请求总数
grpc_client_handling_seconds       - 客户端请求延迟
*/

import (
	"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
	"go.opentelemetry.io/otel/sdk/trace"
)

func setupTracing() func() {
	// 创建 OTLP exporter
	exporter, err := otlptracegrpc.New(context.Background(),
		otlptracegrpc.WithEndpoint("jaeger:4317"),
		otlptracegrpc.WithInsecure(),
	)
	if err != nil {
		log.Fatal(err)
	}

	tp := trace.NewTracerProvider(
		trace.WithBatcher(exporter),
		trace.WithResource(resource.NewWithAttributes(
			semconv.SchemaURL,
			semconv.ServiceNameKey.String("user-service"),
		)),
	)
	otel.SetTracerProvider(tp)

	return func() { tp.Shutdown(context.Background()) }
}

// gRPC 服务端追踪
server := grpc.NewServer(
    grpc.StatsHandler(otelgrpc.NewServerHandler()),
)

// gRPC 客户端追踪
conn, err := grpc.Dial(target,
    grpc.WithStatsHandler(otelgrpc.NewClientHandler()),
)

// 生产环境 TLS 配置
creds, err := credentials.NewServerTLSFromFile("cert.pem", "key.pem")
if err != nil {
    log.Fatal(err)
}

server := grpc.NewServer(
    grpc.Creds(creds),
    // 强制 TLS 1.2+
    grpc.Creds(credentials.NewTLS(&tls.Config{
        MinVersion: tls.VersionTLS12,
        CipherSuites: []uint16{
            tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
            tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
            tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
            tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
        },
    })),
)

// 加载 CA 证书
certPool := x509.NewCertPool()
ca, _ := os.ReadFile("ca.pem")
certPool.AppendCertsFromPEM(ca)

// 加载服务端证书
serverCert, _ := tls.LoadX509KeyPair("server.pem", "server.key")

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

server := grpc.NewServer(
    grpc.Creds(credentials.NewTLS(tlsConfig)),
)

package main

import (
	"context"
	"net"
	"testing"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
	"google.golang.org/grpc/test/bufconn"
)

const bufSize = 1024 * 1024

var lis *bufconn.Listener

func init() {
	lis = bufconn.Listen(bufSize)
	server := grpc.NewServer()
	pb.RegisterUserServiceServer(server, &userServer{})
	go server.Serve(lis)
}

func bufDialer(context.Context, string) (net.Conn, error) {
	return lis.Dial()
}

func TestGetUser(t *testing.T) {
	conn, err := grpc.DialContext(context.Background(), "bufnet",
		grpc.WithContextDialer(bufDialer),
		grpc.WithTransportCredentials(insecure.NewCredentials()),
	)
	if err != nil {
		t.Fatal(err)
	}
	defer conn.Close()

	client := pb.NewUserServiceClient(conn)

	// 测试正常获取
	resp, err := client.GetUser(context.Background(), &pb.GetUserRequest{Id: 1})
	if err != nil {
		t.Fatalf("GetUser 失败: %v", err)
	}
	if resp.User.Name != "Alice" {
		t.Errorf("期望 'Alice'，实际 '%s'", resp.User.Name)
	}

	// 测试不存在的用户
	_, err = client.GetUser(context.Background(), &pb.GetUserRequest{Id: 999})
	if err == nil {
		t.Error("期望错误，实际为 nil")
	}
	st, ok := status.FromError(err)
	if !ok || st.Code() != codes.NotFound {
		t.Errorf("期望 NotFound 错误，实际: %v", err)
	}
}

// 使用 grpcurl 进行集成测试
func TestIntegration(t *testing.T) {
	if testing.Short() {
		t.Skip("跳过集成测试")
	}

	// 启动服务器
	server := startTestServer(t)
	defer server.Stop()

	// 使用 grpcurl 测试
	conn, _ := grpc.Dial("localhost:50051",
		grpc.WithTransportCredentials(insecure.NewCredentials()))
	defer conn.Close()

	// 描述服务
	desc := grpcurl.DescriptorSourceFromServer(context.Background(), conn)

	// 调用方法
	handler := &grpcurl.DefaultEventHandler{
		Out: os.Stdout,
	}
	err := grpcurl.InvokeRPC(context.Background(), desc, conn,
		"example.UserService/GetUser",
		[]string{},
		handler,
		`{"id": 1}`,
	)
	if err != nil {
		t.Fatalf("RPC 调用失败: %v", err)
	}
}

# 常用调试命令

# 检查服务是否支持 HTTP/2
openssl s_client -connect localhost:443 -alpn h2

# 测试 gRPC 服务
grpcurl -plaintext localhost:50051 list
grpcurl -plaintext localhost:50051 describe example.UserService
grpcurl -plaintext -d '{"id": 1}' localhost:50051 example.UserService/GetUser

# 查看 HTTP/2 帧
nghttp -v https://localhost:443

# 检查连接状态
ss -tlnp | grep 50051
netstat -an | grep 50051