Go 微服务开发完全指南 2026：gRPC + Protobuf + Gin + OpenTelemetry 链路追踪

1
package main
2

3
import (
4
  "context"
5
  "net/http"
6
  "time"
7

8
  "github.com/gin-gonic/gin"
9
  "google.golang.org/grpc"
10
  "google.golang.org/grpc/credentials/insecure"
11
  "go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
12
  "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
13

14
  pb "rust-axum-service/proto/user/v1"
15
)
16

17
type GatewayHandler struct {
18
  userClient pb.UserServiceClient
19
}
20

21
func main() {
22
  // 1. 建立长连接复用的 gRPC 客户端
23
  conn, err := grpc.NewClient(
24
    "localhost:50051",
25
    grpc.WithTransportCredentials(insecure.NewCredentials()),
26
    grpc.WithStatsHandler(otelgrpc.NewClientHandler()), // 透传 TraceContext
27
  )
28
  if err != nil {
29
    panic(err)
30
  }
31
  defer conn.Close()
32

33
  handler := &GatewayHandler{
34
    userClient: pb.NewUserServiceClient(conn),
35
  }
36

37
  // 2. 初始化 Gin 网关
38
  r := gin.Default()
39
  r.Use(otelgin.Middleware("api-gateway")) // HTTP 链路追踪中间件
40

41
  r.GET("/api/v1/users/:id", handler.GetUserHandler)
42
  r.POST("/api/v1/users", handler.CreateUserHandler)
43

44
  r.Run(":8080")
45
}
46

47
func (h *GatewayHandler) GetUserHandler(c *gin.Context) {
48
  userId := c.Param("id")
49

50
  // 必须带上 Context 超时控制，防止慢查询拖垮 Goroutine
51
  ctx, cancel := context.WithTimeout(c.Request.Context(), 2*time.Second)
52
  defer cancel()
53

54
  resp, err := h.userClient.GetUser(ctx, &pb.GetUserRequest{UserId: userId})
55
  if err != nil {
56
    c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
57
    return
58
  }
59

60
  c.JSON(http.StatusOK, gin.H{
61
    "code": 200,
62
    "data": resp.GetUser(),
63
  })
64
}
65

66
func (h *GatewayHandler) CreateUserHandler(c *gin.Context) {
67
  var body struct {
68
    Username string `json:"username" binding:"required"`
69
    Email    string `json:"email" binding:"required,email"`
70
  }
71

72
  if err := c.ShouldBindJSON(&body); err != nil {
73
    c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
74
    return
75
  }
76

77
  ctx, cancel := context.WithTimeout(c.Request.Context(), 2*time.Second)
78
  defer cancel()
79

80
  resp, err := h.userClient.CreateUser(ctx, &pb.CreateUserRequest{
81
    Username: body.Username,
82
    Email:    body.Email,
83
  })
84
  if err != nil {
85
    c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
86
    return
87
  }
88

89
  c.JSON(http.StatusCreated, gin.H{
90
    "code": 201,
91
    "data": resp.GetUser(),
92
  })
93
}

1
package telemetry
2

3
import (
4
  "context"
5
  "go.opentelemetry.io/otel"
6
  "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
7
  "go.opentelemetry.io/otel/sdk/resource"
8
  sdktrace "go.opentelemetry.io/otel/sdk/trace"
9
  semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
10
  "google.golang.org/grpc"
11
  "google.golang.org/grpc/credentials/insecure"
12
)
13

14
// InitTracer 初始化全局 TracerProvider 并导出到 Jaeger / OTel Collector
15
func InitTracer(ctx context.Context, serviceName string, collectorAddr string) (*sdktrace.TracerProvider, error) {
16
  exporter, err := otlptracegrpc.New(ctx,
17
    otlptracegrpc.WithInsecure(),
18
    otlptracegrpc.WithEndpoint(collectorAddr),
19
  )
20
  if err != nil {
21
    return nil, err
22
  }
23

24
  res, err := resource.New(ctx,
25
    resource.WithAttributes(
26
      semconv.ServiceNameKey.String(serviceName),
27
    ),
28
  )
29
  if err != nil {
30
    return nil, err
31
  }
32

33
  tp := sdktrace.NewTracerProvider(
34
    sdktrace.WithBatcher(exporter),
35
    sdktrace.WithResource(res),
36
  )
37
  otel.SetTracerProvider(tp)
38
  return tp, nil
39
}