五、可用性和可观测性

// Dubbo-go 的 Filter 接口（概念示例）
// 请求和响应分别走两个方向，形成完整的调用链
type Filter interface {
    // Invoke 处理请求（正向调用）
    Invoke(invoker Invoker, invocation Invocation) Result
    // OnResponse 处理响应（反向回调）
    OnResponse(result Result, invoker Invoker, invocation Invocation) Result
}

package ratelimit

import (
	"sync"
	"time"
)

// ============================================================
// 令牌桶（Token Bucket）限流算法实现
// ============================================================

// TokenBucket 令牌桶限流器
type TokenBucket struct {
	mu         sync.Mutex    // 互斥锁，保证并发安全
	rate       float64       // 令牌生成速率（个/秒）
	capacity   float64       // 桶的容量（最大令牌数）
	tokens     float64       // 当前桶中的令牌数
	lastRefill time.Time     // 上次补充令牌的时间
}

// NewTokenBucket 创建一个令牌桶限流器
// 参数 rate 是令牌生成速率（每秒生成多少个令牌）
// 参数 capacity 是桶的容量（最多存放多少个令牌）
func NewTokenBucket(rate, capacity float64) *TokenBucket {
	return &TokenBucket{
		rate:       rate,           // 例如 10.0 表示每秒生成 10 个令牌
		capacity:   capacity,       // 例如 100.0 表示桶最多放 100 个令牌
		tokens:     capacity,       // 初始化时桶是满的
		lastRefill: time.Now(),     // 记录创建时间
	}
}

// Allow 尝试获取一个令牌
// 返回 true 表示获取成功（请求被允许），false 表示获取失败（请求被拒绝）
func (tb *TokenBucket) Allow() bool {
	tb.mu.Lock()
	defer tb.mu.Unlock()

	// 第一步：计算自上次补充以来经过的时间，补充令牌
	now := time.Now()
	elapsed := now.Sub(tb.lastRefill).Seconds() // 经过的秒数
	tb.lastRefill = now

	// 按速率补充令牌，但不超过桶的容量
	// 例如 rate=10，elapsed=0.5秒，则补充 10*0.5=5 个令牌
	tb.tokens += tb.rate * elapsed
	if tb.tokens > tb.capacity {
		tb.tokens = tb.capacity // 令牌数不能超过桶容量
	}

	// 第二步：尝试消费一个令牌
	if tb.tokens >= 1 {
		tb.tokens-- // 消费一个令牌
		return true
	}

	// 令牌不足，拒绝请求
	return false
}

package ratelimit

import (
	"sync"
	"time"
)

// ============================================================
// 漏桶（Leaky Bucket）限流算法实现
// ============================================================

// LeakyBucket 漏桶限流器
type LeakyBucket struct {
	mu         sync.Mutex
	rate       float64       // 漏水速率（请求/秒）
	capacity   float64       // 桶容量（队列长度上限）
	water      float64       // 当前桶中的水量（排队请求数）
	lastLeak   time.Time     // 上次漏水时间
}

// NewLeakyBucket 创建一个漏桶限流器
// 参数 rate 是处理速率（每秒处理多少请求）
// 参数 capacity 是桶容量（最多排队多少请求）
func NewLeakyBucket(rate, capacity float64) *LeakyBucket {
	return &LeakyBucket{
		rate:     rate,       // 例如 10.0 表示每秒处理 10 个请求
		capacity: capacity,   // 例如 100.0 表示最多排队 100 个请求
		water:    0,          // 初始水量为 0
		lastLeak: time.Now(),
	}
}

// Allow 尝试将请求加入队列
// 返回 true 表示请求被接受（排队等待处理），false 表示队列已满（拒绝）
func (lb *LeakyBucket) Allow() bool {
	lb.mu.Lock()
	defer lb.mu.Unlock()

	// 第一步：先漏水（处理排队请求）
	now := time.Now()
	elapsed := now.Sub(lb.lastLeak).Seconds()
	lb.lastLeak = now

	// 按速率漏水，水量不能小于 0
	// 例如 rate=10，elapsed=0.5秒，则漏掉 10*0.5=5 个请求
	lb.water -= lb.rate * elapsed
	if lb.water < 0 {
		lb.water = 0
	}

	// 第二步：尝试加入新请求（加水）
	if lb.water < lb.capacity {
		lb.water++ // 加入队列
		return true
	}

	// 队列已满，拒绝请求
	return false
}

package ratelimit

import (
	"sync"
	"time"
)

// ============================================================
// 固定窗口（Fixed Window）限流算法实现
// ============================================================

// FixedWindow 固定窗口限流器
type FixedWindow struct {
	mu        sync.Mutex
	limit     int           // 每个窗口允许的最大请求数
	window    time.Duration // 窗口大小（如 1 分钟）
	count     int           // 当前窗口内的请求计数
	windowStart time.Time   // 当前窗口的起始时间
}

// NewFixedWindow 创建一个固定窗口限流器
// 参数 limit 是每个窗口允许的最大请求数
// 参数 window 是窗口大小（如 time.Minute 表示 1 分钟）
func NewFixedWindow(limit int, window time.Duration) *FixedWindow {
	return &FixedWindow{
		limit:       limit,          // 例如 100 表示每分钟最多 100 个请求
		window:      window,         // 例如 time.Minute
		windowStart: time.Now(),     // 窗口从当前时间开始
	}
}

// Allow 尝试通过限流
func (fw *FixedWindow) Allow() bool {
	fw.mu.Lock()
	defer fw.mu.Unlock()

	now := time.Now()

	// 第一步：检查是否需要切换到新窗口
	if now.Sub(fw.windowStart) >= fw.window {
		// 窗口已过期，开启新窗口
		fw.windowStart = now
		fw.count = 0
	}

	// 第二步：检查当前窗口的请求计数
	if fw.count < fw.limit {
		fw.count++ // 计数加一
		return true
	}

	// 超过限制，拒绝请求
	return false
}

package ratelimit

import (
	"sync"
	"time"
)

// ============================================================
// 滑动窗口（Sliding Window）限流算法实现
// 使用滑动日志方式实现
// ============================================================

// SlidingWindow 滑动窗口限流器
type SlidingWindow struct {
	mu        sync.Mutex
	limit     int           // 窗口内允许的最大请求数
	window    time.Duration // 窗口大小（如 1 分钟）
	timestamps []time.Time  // 记录每个请求的时间戳
}

// NewSlidingWindow 创建一个滑动窗口限流器
// 参数 limit 是窗口内允许的最大请求数
// 参数 window 是窗口大小（如 time.Minute）
func NewSlidingWindow(limit int, window time.Duration) *SlidingWindow {
	return &SlidingWindow{
		limit:      limit,
		window:     window,
		timestamps: make([]time.Time, 0, limit),
	}
}

// Allow 尝试通过限流
func (sw *SlidingWindow) Allow() bool {
	sw.mu.Lock()
	defer sw.mu.Unlock()

	now := time.Now()
	// 窗口起始时间 = 当前时间 - 窗口大小
	windowStart := now.Add(-sw.window)

	// 第一步：清理过期的请求记录（在窗口之外的）
	// 从前往后找，把所有早于窗口起始时间的记录删除
	idx := 0
	for idx < len(sw.timestamps) && sw.timestamps[idx].Before(windowStart) {
		idx++
	}
	sw.timestamps = sw.timestamps[idx:]

	// 第二步：检查窗口内的请求数量
	if len(sw.timestamps) < sw.limit {
		// 未超过限制，记录当前请求的时间戳
		sw.timestamps = append(sw.timestamps, now)
		return true
	}

	// 超过限制，拒绝请求
	return false
}

package circuitbreaker

import (
	"errors"
	"sync"
	"time"
)

// ============================================================
// 熔断器（Circuit Breaker）实现
// ============================================================

// State 熔断器状态
type State int

const (
	StateClosed   State = iota // 关闭状态：正常处理请求
	StateOpen                  // 打开状态：拒绝所有请求
	StateHalfOpen              // 半开状态：放行少量试探请求
)

// CircuitBreaker 熔断器
type CircuitBreaker struct {
	mu sync.Mutex

	state          State         // 当前状态
	failureThreshold int         // 失败阈值（连续失败多少次触发熔断）
	failureCount     int         // 当前失败计数
	successThreshold int         // 半开状态下成功多少次恢复
	successCount     int         // 半开状态下成功计数
	cooldown         time.Duration // 熔断冷却时间
	lastFailureTime  time.Time   // 上次失败时间
}

// NewCircuitBreaker 创建一个熔断器
// 参数 failureThreshold 是连续失败多少次触发熔断
// 参数 successThreshold 是半开状态下成功多少次恢复到 Closed
// 参数 cooldown 是熔断后的冷却时间
func NewCircuitBreaker(failureThreshold, successThreshold int, cooldown time.Duration) *CircuitBreaker {
	return &CircuitBreaker{
		state:            StateClosed,    // 初始状态为关闭
		failureThreshold: failureThreshold, // 例如 5 次
		successThreshold: successThreshold, // 例如 3 次
		cooldown:         cooldown,        // 例如 30 秒
	}
}

// Allow 检查是否允许请求通过
// 返回 nil 表示允许，返回 error 表示被熔断
func (cb *CircuitBreaker) Allow() error {
	cb.mu.Lock()
	defer cb.mu.Unlock()

	now := time.Now()

	switch cb.state {
	case StateClosed:
		// 关闭状态：允许所有请求
		return nil

	case StateOpen:
		// 打开状态：检查冷却时间是否已过
		if now.Sub(cb.lastFailureTime) >= cb.cooldown {
			// 冷却时间已过，切换到半开状态
			cb.state = StateHalfOpen
			cb.successCount = 0
			return nil
		}
		// 冷却时间未过，拒绝请求
		return errors.New("circuit breaker is open")

	case StateHalfOpen:
		// 半开状态：允许少量请求通过
		return nil
	}

	return nil
}

// OnSuccess 记录请求成功
func (cb *CircuitBreaker) OnSuccess() {
	cb.mu.Lock()
	defer cb.mu.Unlock()

	switch cb.state {
	case StateClosed:
		// 关闭状态下成功，重置失败计数
		cb.failureCount = 0

	case StateHalfOpen:
		// 半开状态下成功，增加成功计数
		cb.successCount++
		if cb.successCount >= cb.successThreshold {
			// 达到成功阈值，恢复到关闭状态
			cb.state = StateClosed
			cb.failureCount = 0
			cb.successCount = 0
		}
	}
}

// OnFailure 记录请求失败
func (cb *CircuitBreaker) OnFailure() {
	cb.mu.Lock()
	defer cb.mu.Unlock()

	cb.lastFailureTime = time.Now()

	switch cb.state {
	case StateClosed:
		// 关闭状态下失败，增加失败计数
		cb.failureCount++
		if cb.failureCount >= cb.failureThreshold {
			// 达到失败阈值，切换到打开状态
			cb.state = StateOpen
		}

	case StateHalfOpen:
		// 半开状态下失败，重新切换到打开状态
		cb.state = StateOpen
		cb.failureCount = 0
		cb.successCount = 0
	}
}

package interceptor

import (
	"context"
	"sync"

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

// ============================================================
// gRPC 服务端限流拦截器
// 使用令牌桶算法对每个方法进行限流
// ============================================================

// RateLimitInterceptor 限流拦截器
// 对每个 gRPC 方法维护一个独立的令牌桶
type RateLimitInterceptor struct {
	mu       sync.Mutex
	limiters map[string]*TokenBucket // 方法名 -> 令牌桶
	rate     float64                  // 令牌生成速率
	capacity float64                  // 桶容量
}

// NewRateLimitInterceptor 创建限流拦截器
// 参数 rate 是每秒允许的请求数
// 参数 capacity 是令牌桶容量（允许的突发请求数）
func NewRateLimitInterceptor(rate, capacity float64) *RateLimitInterceptor {
	return &RateLimitInterceptor{
		limiters: make(map[string]*TokenBucket),
		rate:     rate,
		capacity: capacity,
	}
}

// getLimiter 获取或创建某个方法的令牌桶
// 不同的方法可以使用不同的令牌桶，互不影响
func (r *RateLimitInterceptor) getLimiter(method string) *TokenBucket {
	r.mu.Lock()
	defer r.mu.Unlock()

	if limiter, ok := r.limiters[method]; ok {
		return limiter
	}

	// 为新方法创建令牌桶
	limiter := NewTokenBucket(r.rate, r.capacity)
	r.limiters[method] = limiter
	return limiter
}

// ServerInterceptor 返回 gRPC 服务端拦截器
// 在每个请求处理前检查是否超过限流阈值
func (r *RateLimitInterceptor) ServerInterceptor() grpc.UnaryServerInterceptor {
	return func(
		ctx context.Context,       // 请求上下文
		req interface{},           // 请求参数
		info *grpc.UnaryServerInfo, // 服务端调用信息，包含方法名
		handler grpc.UnaryHandler,  // 实际的业务处理函数
	) (interface{}, error) {
		// 第一步：获取该方法的令牌桶
		limiter := r.getLimiter(info.FullMethod)

		// 第二步：检查是否允许通过
		if !limiter.Allow() {
			// 超过限流，返回 ResourceExhausted 错误
			// gRPC 标准状态码中，ResourceExhausted 表示资源不足
			return nil, status.Errorf(codes.ResourceExhausted,
				"rate limit exceeded for method %s", info.FullMethod)
		}

		// 第三步：调用实际业务逻辑
		return handler(ctx, req)
	}
}

package interceptor

import (
	"context"

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

// ============================================================
// gRPC 客户端熔断拦截器
// ============================================================

// CircuitBreakerInterceptor 熔断拦截器
type CircuitBreakerInterceptor struct {
	breaker *CircuitBreaker
}

// NewCircuitBreakerInterceptor 创建熔断拦截器
func NewCircuitBreakerInterceptor(breaker *CircuitBreaker) *CircuitBreakerInterceptor {
	return &CircuitBreakerInterceptor{breaker: breaker}
}

// ClientInterceptor 返回 gRPC 客户端拦截器
// 在每次调用前检查熔断状态，调用后记录成功/失败
func (c *CircuitBreakerInterceptor) ClientInterceptor() grpc.UnaryClientInterceptor {
	return func(
		ctx context.Context,         // 请求上下文
		method string,               // 方法名
		req, reply interface{},      // 请求和响应
		cc *grpc.ClientConn,         // 客户端连接
		invoker grpc.UnaryInvoker,   // 实际调用函数
		opts ...grpc.CallOption,     // 调用选项
	) error {
		// 第一步：检查熔断器是否允许请求通过
		if err := c.breaker.Allow(); err != nil {
			// 熔断器打开，直接返回错误
			return status.Error(codes.Unavailable, "circuit breaker is open")
		}

		// 第二步：发起实际调用
		err := invoker(ctx, method, req, reply, cc, opts...)

		// 第三步：根据调用结果更新熔断器状态
		if err != nil {
			c.breaker.OnFailure() // 调用失败，记录失败
		} else {
			c.breaker.OnSuccess() // 调用成功，记录成功
		}

		return err
	}
}

package degradation

import (
	"context"

	"google.golang.org/grpc"
)

// ============================================================
// 降级拦截器实现
// 当服务不可用时，走简易路径返回默认值
// ============================================================

// degradeKey 用于在 context 中标记降级请求
type degradeKey struct{}

// WithDegrade 在 context 中设置降级标记
// 被标记的请求会走快路径（简易逻辑）
func WithDegrade(ctx context.Context) context.Context {
	return context.WithValue(ctx, degradeKey{}, true)
}

// IsDegrade 检查是否为降级请求
func IsDegrade(ctx context.Context) bool {
	v, ok := ctx.Value(degradeKey{}).(bool)
	return ok && v
}

// DegradeInterceptor 降级拦截器
// 参数 fallback 是降级时执行的简易逻辑
// 当原始调用失败时，执行 fallback 返回默认值
func DegradeInterceptor(fallback func(ctx context.Context, method string, req interface{}) (interface{}, error)) grpc.UnaryClientInterceptor {
	return func(
		ctx context.Context,
		method string,
		req, reply interface{},
		cc *grpc.ClientConn,
		invoker grpc.UnaryInvoker,
		opts ...grpc.CallOption,
	) error {
		// 第一步：检查是否已经被标记为降级请求
		if IsDegrade(ctx) {
			// 已经是降级请求，直接走快路径
			result, err := fallback(ctx, method, req)
			if err != nil {
				return err
			}
			// 将 fallback 的结果复制到 reply
			// 实际实现中需要使用反射或 protobuf 的 Merge 方法
			return nil
		}

		// 第二步：正常调用
		err := invoker(ctx, method, req, reply, cc, opts...)
		if err != nil {
			// 第三步：调用失败，走降级逻辑
			result, ferr := fallback(ctx, method, req)
			if ferr == nil && result != nil {
				// 降级成功，返回默认值
				_ = result // 实际实现中需要将 result 复制到 reply
				return nil
			}
			// 降级也失败了，返回原始错误
			return err
		}

		return nil
	}
}

package ratelimit

import (
	"context"
	"fmt"
	"time"

	"github.com/redis/go-redis/v9"
)

// ============================================================
// 基于 Redis 的集群限流实现（固定窗口）
// ============================================================

// RedisFixedWindow 基于 Redis 的固定窗口集群限流器
type RedisFixedWindow struct {
	client *redis.Client // Redis 客户端
	limit  int           // 每个窗口允许的最大请求数
	window time.Duration // 窗口大小
}

// NewRedisFixedWindow 创建 Redis 集群限流器
func NewRedisFixedWindow(client *redis.Client, limit int, window time.Duration) *RedisFixedWindow {
	return &RedisFixedWindow{
		client: client,
		limit:  limit,  // 例如 1000 表示每分钟整个集群最多 1000 个请求
		window: window, // 例如 time.Minute
	}
}

// Allow 尝试通过限流
// 使用 Redis 的 INCR 命令原子递增计数器
func (r *RedisFixedWindow) Allow(ctx context.Context, key string) (bool, error) {
	// 第一步：计算当前窗口的 Redis key
	// 使用时间戳取整来确保同一窗口内的 key 相同
	// 例如窗口为 1 分钟，则 00:01:30 和 00:01:59 的 key 相同
	now := time.Now()
	windowStart := now.Truncate(r.window) // 截断到窗口边界
	redisKey := fmt.Sprintf("ratelimit:%s:%d", key, windowStart.Unix())

	// 第二步：使用 Lua 脚本原子操作
	// INCR 和 EXPIRE 必须在同一个原子操作中执行
	// 否则可能出现 INCR 成功但 EXPIRE 失败导致 key 永不过期
	script := `
		local count = redis.call('INCR', KEYS[1])
		if count == 1 then
			redis.call('EXPIRE', KEYS[1], ARGV[1])
		end
		return count
	`

	// 窗口过期时间（秒）
	ttl := int64(r.window.Seconds())

	// 执行 Lua 脚本
	result, err := r.client.Eval(ctx, script, []string{redisKey}, ttl).Int()
	if err != nil {
		return false, err
	}

	// 第三步：判断是否超过限制
	return result <= r.limit, nil
}

package ratelimit

import (
	"context"
	"fmt"
	"time"

	"github.com/redis/go-redis/v9"
)

// ============================================================
// 基于 Redis 的集群限流实现（滑动窗口）
// 使用 Sorted Set（有序集合）实现
// ============================================================

// RedisSlidingWindow 基于 Redis 的滑动窗口集群限流器
type RedisSlidingWindow struct {
	client *redis.Client // Redis 客户端
	limit  int           // 窗口内允许的最大请求数
	window time.Duration // 窗口大小
}

// NewRedisSlidingWindow 创建 Redis 滑动窗口集群限流器
func NewRedisSlidingWindow(client *redis.Client, limit int, window time.Duration) *RedisSlidingWindow {
	return &RedisSlidingWindow{
		client: client,
		limit:  limit,
		window: window,
	}
}

// Allow 尝试通过限流
// 使用 Redis 的 Sorted Set 记录请求时间戳
func (r *RedisSlidingWindow) Allow(ctx context.Context, key string) (bool, error) {
	now := time.Now()
	windowStart := now.Add(-r.window) // 窗口起始时间

	// Redis key
	redisKey := fmt.Sprintf("sliding_window:%s", key)

	// 使用 Lua 脚本保证原子性
	// 步骤：
	// 1. 移除窗口外的旧记录
	// 2. 检查当前窗口内的请求数
	// 3. 如果未超限，添加当前请求的时间戳
	script := `
		-- 第一步：移除窗口外的旧记录
		redis.call('ZREMRANGEBYSCORE', KEYS[1], 0, ARGV[1])

		-- 第二步：获取当前窗口内的请求数
		local count = redis.call('ZCARD', KEYS[1])

		-- 第三步：判断是否超过限制
		if count < tonumber(ARGV[3]) then
			-- 未超限，添加当前请求
			redis.call('ZADD', KEYS[1], ARGV[2], ARGV[2])
			-- 设置 key 的过期时间，防止内存浪费
			redis.call('EXPIRE', KEYS[1], ARGV[4])
			return 1
		else
			return 0
		end
	`

	// 参数说明：
	// ARGV[1] = 窗口起始时间（用于移除旧记录）
	// ARGV[2] = 当前时间戳（作为 score 和 member）
	// ARGV[3] = 限制数量
	// ARGV[4] = 过期时间（秒）
	result, err := r.client.Eval(ctx, script,
		[]string{redisKey},
		windowStart.UnixNano(),
		now.UnixNano(),
		r.limit,
		int64(r.window.Seconds()),
	).Int()
	if err != nil {
		return false, err
	}

	return result == 1, nil
}

package metrics

import (
	"context"
	"time"

	"google.golang.org/grpc"
)

// ============================================================
// gRPC Metrics 拦截器
// 记录请求的响应时间和调用结果
// ============================================================

// MetricsInterceptor Metrics 拦截器
type MetricsInterceptor struct {
	// 实际项目中，这里会接入 Prometheus 等监控系统
	// 我们这里简化演示，用 map 存储统计数据
}

// NewMetricsInterceptor 创建 Metrics 拦截器
func NewMetricsInterceptor() *MetricsInterceptor {
	return &MetricsInterceptor{}
}

// ServerInterceptor 返回服务端 Metrics 拦截器
// 在请求处理前后记录指标数据
func (m *MetricsInterceptor) ServerInterceptor() grpc.UnaryServerInterceptor {
	return func(
		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)

		// 第四步：记录指标
		// 实际项目中，这些数据会发送到 Prometheus 等监控系统
		// 这里简化演示
		m.recordMetrics(info.FullMethod, duration, err)

		return resp, err
	}
}

// recordMetrics 记录指标数据
// method: 方法名，如 "/user.UserService/GetUser"
// duration: 响应时间
// err: 调用错误（nil 表示成功）
func (m *MetricsInterceptor) recordMetrics(method string, duration time.Duration, err error) {
	// 在实际项目中，这些数据会被 Prometheus 采集
	// 例如：
	// - grpc_request_total{method="GetUser", status="success"} ++
	// - grpc_request_duration_seconds{method="GetUser"} observe(duration)
	
	// 这里简化输出
	status := "success"
	if err != nil {
		status = "error"
	}
	
	// 实际实现中，不要在拦截器里打印日志（影响性能）
	// 这里仅作演示
	_ = method
	_ = duration
	_ = status
}

package tracing

import (
	"context"
	"time"

	"google.golang.org/grpc"
	"google.golang.org/grpc/metadata"
)

// ============================================================
// gRPC Tracing 拦截器
// 将请求在多个服务间的调用串联起来
// ============================================================

// 链路追踪的 metadata key
const (
	TraceIDKey      = "x-trace-id"
	SpanIDKey       = "x-span-id"
	ParentSpanIDKey = "x-parent-span-id"
)

// generateID 生成唯一 ID（简化版，实际使用 UUID 或类似方案）
func generateID() string {
	return time.Now().Format("20060102150405.000000")
}

// ServerTracingInterceptor 服务端链路追踪拦截器
// 从 gRPC metadata 中提取 TraceID，创建新的 SpanID
func ServerTracingInterceptor() grpc.UnaryServerInterceptor {
	return func(
		ctx context.Context,
		req interface{},
		info *grpc.UnaryServerInfo,
		handler grpc.UnaryHandler,
	) (interface{}, error) {
		// 第一步：从 metadata 中提取链路信息（Extract）
		// 客户端在发起请求时会将 TraceID 放入 metadata
		md, ok := metadata.FromIncomingContext(ctx)
		
		var traceID string
		var parentSpanID string
		
		if ok {
			// 提取 TraceID
			if values := md.Get(TraceIDKey); len(values) > 0 {
				traceID = values[0]
			}
			// 提取父 SpanID
			if values := md.Get(SpanIDKey); len(values) > 0 {
				parentSpanID = values[0]
			}
		}
		
		// 如果没有 TraceID，说明是链路起点，生成新的
		if traceID == "" {
			traceID = generateID()
		}
		
		// 第二步：生成当前节点的 SpanID
		spanID := generateID()
		
		// 第三步：记录 Span 信息
		// 实际项目中，这些信息会发送到 Jaeger、Zipkin 等 tracing 系统
		start := time.Now()
		
		// 将链路信息存入 context，供后续使用
		ctx = context.WithValue(ctx, "traceID", traceID)
		ctx = context.WithValue(ctx, "spanID", spanID)
		
		// 第四步：调用业务逻辑
		resp, err := handler(ctx, req)
		
		// 第五步：记录 Span 的结束信息
		duration := time.Since(start)
		// 实际项目中，会将 span 信息上报到 tracing 系统：
		// span.SetTag("method", info.FullMethod)
		// span.SetTag("duration", duration)
		// span.SetTag("error", err != nil)
		// span.Finish()
		_ = duration
		_ = err
		
		return resp, err
	}
}

// ClientTracingInterceptor 客户端链路追踪拦截器
// 将 TraceID 注入到 gRPC metadata 中（Inject）
func ClientTracingInterceptor() grpc.UnaryClientInterceptor {
	return func(
		ctx context.Context,
		method string,
		req, reply interface{},
		cc *grpc.ClientConn,
		invoker grpc.UnaryInvoker,
		opts ...grpc.CallOption,
	) error {
		// 第一步：从 context 中获取链路信息
		traceID, _ := ctx.Value("traceID").(string)
		if traceID == "" {
			// 如果没有 TraceID，生成新的
			traceID = generateID()
		}
		
		// 生成当前调用的 SpanID
		spanID := generateID()
		
		// 第二步：将链路信息注入到 metadata 中（Inject）
		md := metadata.Pairs(
			TraceIDKey, traceID,      // 传递 TraceID
			SpanIDKey, spanID,        // 当前的 SpanID 成为下游的 ParentSpanID
		)
		
		// 将 metadata 附加到 context
		ctx = metadata.AppendToOutgoingContext(ctx, 
			TraceIDKey, traceID,
			SpanIDKey, spanID,
		)
		
		// 第三步：发起调用
		return invoker(ctx, method, req, reply, cc, opts...)
	}
}

package logging

import (
	"context"
	"log"
	"time"

	"google.golang.org/grpc"
)

// ============================================================
// gRPC Logging 拦截器
// 记录请求和响应的详细信息
// ============================================================

// LoggingInterceptor 日志拦截器
type LoggingInterceptor struct {
	logger *log.Logger // 日志记录器
}

// NewLoggingInterceptor 创建日志拦截器
func NewLoggingInterceptor(logger *log.Logger) *LoggingInterceptor {
	return &LoggingInterceptor{logger: logger}
}

// ServerInterceptor 返回服务端日志拦截器
func (l *LoggingInterceptor) ServerInterceptor() grpc.UnaryServerInterceptor {
	return func(
		ctx context.Context,
		req interface{},
		info *grpc.UnaryServerInfo,
		handler grpc.UnaryHandler,
	) (interface{}, error) {
		start := time.Now()

		// 记录请求信息
		// 注意：记录请求参数要考虑两个问题：
		// 1. 请求可能很大（占用日志存储空间）
		// 2. 请求可能包含敏感数据（如住址、手机号码等）
		l.logger.Printf("[REQ] method=%s req=%v", info.FullMethod, req)

		// 调用业务逻辑
		resp, err := handler(ctx, req)

		// 记录响应信息
		duration := time.Since(start)
		if err != nil {
			l.logger.Printf("[ERR] method=%s duration=%s err=%v", 
				info.FullMethod, duration, err)
		} else {
			l.logger.Printf("[RSP] method=%s duration=%s", 
				info.FullMethod, duration)
		}

		return resp, err
	}
}