Istio通用库架构深度剖析：基础设施与工具链的完整实现

graph TB
    subgraph "Istio pkg 通用库架构"
        subgraph "控制器运行时层"
            krt[KRT Framework<br/>声明式控制器运行时]
            multicluster[Multi-cluster<br/>多集群管理]
            controllers[Controllers<br/>Kubernetes控制器]
        end
        
        subgraph "Kubernetes集成层"
            kube_client[Kube Client<br/>K8s客户端封装]
            kclient[KClient<br/>类型化客户端]
            inject[Inject<br/>Sidecar注入]
            crd[CRD<br/>自定义资源]
        end
        
        subgraph "配置管理层"
            config[Config<br/>配置模型]
            schema[Schema<br/>配置模式]
            validation[Validation<br/>配置验证]
            mesh[Mesh Config<br/>网格配置]
        end
        
        subgraph "监控观测层"
            monitoring[Monitoring<br/>指标监控]
            log[Log<br/>日志系统]
            ctrlz[ControlZ<br/>内省调试]
            tracing[Tracing<br/>链路追踪]
        end
        
        subgraph "基础工具层"
            bootstrap[Bootstrap<br/>引导配置]
            security[Security<br/>安全工具]
            util[Util<br/>通用工具]
            queue[Queue<br/>队列管理]
        end
        
        subgraph "网络通信层"
            xds[XDS<br/>配置分发协议]
            grpc[gRPC<br/>通信框架]
            http[HTTP<br/>RESTful API]
            keepalive[Keepalive<br/>连接保活]
        end
    end
    
    %% 依赖关系
    krt --> kube_client
    multicluster --> kclient
    controllers --> kube_client
    
    inject --> config
    inject --> validation
    crd --> schema
    
    monitoring --> log
    ctrlz --> monitoring
    tracing --> log
    
    krt -.->|监控| monitoring
    controllers -.->|配置| config
    multicluster -.->|安全| security
    
    style krt fill:#e1f5fe
    style monitoring fill:#f3e5f5
    style config fill:#e8f5e8
    style ctrlz fill:#fff3e0

// pkg/kube/krt/core.go
// Collection是KRT的核心资源类型，表示对象的集合
// 类似于Informer，但不绑定到Kubernetes
type Collection[T any] interface {
    // GetKey根据键返回对象，如果存在的话。否则返回nil
    GetKey(k string) *T

    // List返回集合中的所有对象
    // 列表的顺序未定义
    List() []T

    // EventStream为集合提供事件处理能力，允许客户端订阅变化
    // 并在添加、修改或删除对象时接收通知
    EventStream[T]

    // Metadata返回与此集合关联的元数据
    // 这可以用于存储和检索任意的键值对
    // 为集合提供额外的上下文或配置
    Metadata() Metadata
}

// EventStream提供底层集合与其客户端之间的链接
// EventStream不会为重触发操作发布事件
// 其中T类型的结果对象等于集合中的现有对象
type EventStream[T any] interface {
    // Subscribe注册一个处理器以接收事件通知
    Subscribe(handler func(obj T, event Event)) Syncer
    
    // AddHandler添加一个类型化的事件处理器
    AddHandler(handler Handler[T]) Syncer
    
    // RegisterBatch批量注册处理器，提高性能
    RegisterBatch(handler func(events []Event[T]), runExistingState bool) Syncer
}

// 从Kubernetes Informer包装成Collection
func WrapClient[T controllers.ComparableObject](c kclient.Client[T], opts ...CollectionOption) Collection[T] {
    return &clientCollection[T]{
        client: c,
        opts:   applyCollectionOptions(opts...),
    }
}

// 创建新的Informer Collection
func NewInformer[T controllers.ComparableObject](c kclient.Untyped, gvr schema.GroupVersionResource, 
    opts ...CollectionOption) Collection[T] {
    client := kclient.NewFiltered[T](c, kclient.Filter{
        ObjectFilter: opts.objectFilter,
    })
    
    return WrapClient(client, opts...)
}

// pkg/kube/krt/static.go
type StaticCollection[T any] struct {
    mu    sync.RWMutex
    items map[string]T
    opts  collectionOptions
    
    // 事件处理器列表
    handlers []Handler[T]
}

// 创建静态配置的Collection
func NewStatic[T any](items []T, opts ...CollectionOption) *StaticCollection[T] {
    res := &StaticCollection[T]{
        items: make(map[string]T),
        opts:  applyCollectionOptions(opts...),
    }
    
    // 填充初始项目
    for _, item := range items {
        key := GetKey(item)
        res.items[key] = item
    }
    
    return res
}

// 更新静态Collection的内容
func (sc *StaticCollection[T]) UpdateObject(obj T) {
    sc.mu.Lock()
    defer sc.mu.Unlock()
    
    key := GetKey(obj)
    old, exists := sc.items[key]
    sc.items[key] = obj
    
    // 发送适当的事件
    event := EventAdd
    if exists {
        if Equal(old, obj) {
            return // 对象未变化，不发送事件
        }
        event = EventUpdate
    }
    
    sc.triggerHandlers(obj, event)
}

// 一对一映射转换
func NewCollection[I, O any](c Collection[I], 
    f func(ctx HandlerContext, i I) *O, 
    opts ...CollectionOption) Collection[O] {
    
    return newDerivedCollection[I, O](c, func(ctx HandlerContext, i I) []O {
        if res := f(ctx, i); res != nil {
            return []O{*res}
        }
        return nil
    }, opts...)
}

// 一对多映射转换
func NewManyCollection[I, O any](c Collection[I], 
    f func(ctx HandlerContext, i I) []O, 
    opts ...CollectionOption) Collection[O] {
    
    return newDerivedCollection[I, O](c, f, opts...)
}

// 单例Collection - 全局状态管理
func NewSingleton[O any](f func(ctx HandlerContext) *O, 
    opts ...CollectionOption) Collection[O] {
    
    // 创建一个虚拟的输入Collection来触发计算
    trigger := NewRecomputeTrigger()
    return NewCollection(trigger, func(ctx HandlerContext, _ RecomputeTrigger) *O {
        return f(ctx)
    }, opts...)
}

// HandlerContext提供对其他Collection的访问能力
type HandlerContext interface {
    // Fetch从另一个Collection获取数据
    // 如果Fetch操作的结果改变，Collection将自动重新计算
    Fetch[T any](c Collection[T]) []T
    
    // FetchKey从Collection获取特定的对象
    FetchKey[T any](c Collection[T], key string) *T
    
    // Logger返回结构化的日志记录器
    Logger() *istiolog.Scope
}

// 实际的HandlerContext实现
type handlerContext struct {
    dependencies []Collection[any]  // 依赖的Collection列表
    augmentations []Augmentation   // 增强器列表
    logger       *istiolog.Scope   // 日志记录器
}

func (h *handlerContext) Fetch[T any](c Collection[T]) []T {
    // 记录依赖关系
    h.dependencies = append(h.dependencies, collectionAsAny(c))
    
    // 返回当前数据
    return c.List()
}

// 示例：依赖管理的实际应用
func createServiceDependentCollection() Collection[EnhancedService] {
    return NewCollection(Services, func(ctx HandlerContext, svc *v1.Service) *EnhancedService {
        // 获取相关的Endpoints
        endpoints := ctx.FetchKey(Endpoints, types.NamespacedName{
            Namespace: svc.Namespace,
            Name:      svc.Name,
        }.String())
        
        // 获取相关的Pods
        allPods := ctx.Fetch(Pods)
        relatedPods := slices.FilterMatch(allPods, func(pod *v1.Pod) bool {
            return pod.Namespace == svc.Namespace && 
                   matchesSelector(pod.Labels, svc.Spec.Selector)
        })
        
        return &EnhancedService{
            Service:   svc,
            Endpoints: endpoints,
            Pods:      relatedPods,
        }
    })
    // 当Services、Endpoints或Pods发生变化时，这个Collection会自动更新
}

// pkg/kube/krt/index.go
type Index[K comparable, O any] interface {
    // Lookup根据键查找对象
    Lookup(k K) []O
    
    // AsCollection将索引转换为Collection
    AsCollection(opts ...CollectionOption) Collection[IndexObject[K, O]]
    
    objectHasKey(obj O, k K) bool
    extractKeys(o O) []K
    id() collectionUID
}

// 创建命名空间索引的便利函数
func NewNamespaceIndex[O Namespacer](c Collection[O]) Index[string, O] {
    return NewIndex(c, cache.NamespaceIndex, func(o O) []string {
        return []string{o.GetNamespace()}
    })
}

// 通用索引创建
func NewIndex[K comparable, O any](
    c Collection[O],
    name string,
    extract func(o O) []K,
    opts ...CollectionOption,
) Index[K, O] {
    
    idx := &index[K, O]{
        name:         name,
        extract:      extract,
        parent:       c,
        objects:      make(map[string]O),
        byIndex:      make(map[K]sets.String),
    }
    
    // 设置事件处理器来维护索引
    c.AddHandler(func(obj O, event Event) {
        switch event {
        case EventAdd:
            idx.handleAdd(obj)
        case EventUpdate:
            idx.handleUpdate(obj)
        case EventDelete:
            idx.handleDelete(obj)
        }
    })
    
    return idx
}

// 使用示例：按标签索引Pods
func createPodByAppIndex() Index[string, *v1.Pod] {
    return NewIndex(Pods, "app", func(pod *v1.Pod) []string {
        if app := pod.Labels["app"]; app != "" {
            return []string{app}
        }
        return nil
    })
}

// pkg/monitoring/monitoring.go
var (
    // 获取全局的Meter实例
    meter = func() api.Meter {
        return otel.GetMeterProvider().Meter("istio")
    }

    monitoringLogger = log.RegisterScope("monitoring", "metrics monitoring")
)

// 注册Prometheus导出器
func RegisterPrometheusExporter(reg prometheus.Registerer, gatherer prometheus.Gatherer) (http.Handler, error) {
    if reg == nil {
        reg = prometheus.DefaultRegisterer
    }
    if gatherer == nil {
        gatherer = prometheus.DefaultGatherer
    }
    
    // 配置Prometheus导出器选项
    promOpts := []otelprom.Option{
        otelprom.WithoutScopeInfo(),      // 不包含scope信息
        otelprom.WithoutTargetInfo(),     // 不包含target信息
        otelprom.WithoutUnits(),          // 不包含单位信息
        otelprom.WithRegisterer(reg),     // 使用指定的注册器
        otelprom.WithoutCounterSuffixes(), // 不添加counter后缀
    }

    prom, err := otelprom.New(promOpts...)
    if err != nil {
        return nil, err
    }

    // 创建MeterProvider
    opts := []metric.Option{metric.WithReader(prom)}
    opts = append(opts, knownMetrics.toHistogramViews()...)
    mp := metric.NewMeterProvider(opts...)
    otel.SetMeterProvider(mp)
    
    // 返回HTTP处理器
    handler := promhttp.HandlerFor(gatherer, promhttp.HandlerOpts{})
    return handler, nil
}

// Metric接口定义了所有指标类型的通用行为
type Metric interface {
    // Increment记录值为1。对于Sum类型，相当于当前值+1
    // 对于Gauge类型，相当于设置值为1
    // 对于Distribution类型，相当于观察值1
    Increment()

    // Decrement记录值为-1
    Decrement()

    // Name返回指标的名称
    Name() string

    // Record记录提供的值
    Record(value float64)

    // RecordInt记录整数值
    RecordInt(value int64)

    // With创建带有指定标签值的新Metric实例
    With(labelValues ...LabelValue) Metric
}

// 具体的指标类型实现
type counter struct {
    baseMetric
    c api.Int64Counter
}

func (f *counter) Increment() {
    f.RecordInt(1)
}

func (f *counter) RecordInt(value int64) {
    f.c.Add(context.Background(), value, api.WithAttributes(f.attrs...))
}

type gauge struct {
    baseMetric
    // Gauge使用回调函数实现
    // 当Prometheus抓取时，会调用这个函数获取当前值
    setValue func(v float64)
    getValue func() float64
}

func (f *gauge) Record(value float64) {
    f.setValue(value)
}

// 直方图类型用于记录数值分布
type histogram struct {
    baseMetric
    h api.Float64Histogram
}

func (f *histogram) Record(value float64) {
    f.h.Record(context.Background(), value, api.WithAttributes(f.attrs...))
}

// 指标构建器模式
type MetricBuilder struct {
    name        string
    unit        Unit
    description string
}

func NewSum(name, description string) MetricBuilder {
    return MetricBuilder{
        name:        name,
        description: description,
        unit:        None,
    }
}

func NewGauge(name, description string) MetricBuilder {
    return MetricBuilder{
        name:        name, 
        description: description,
        unit:        None,
    }
}

func NewHistogram(name, description string) MetricBuilder {
    return MetricBuilder{
        name:        name,
        description: description,
        unit:        None,
    }
}

// 使用标签创建指标
func (m MetricBuilder) With(labels ...Label) Metric {
    switch m.metricType {
    case metricTypeCounter:
        return newCounter(m, labels)
    case metricTypeGauge:
        return newGauge(m, labels)
    case metricTypeHistogram:
        return newHistogram(m, labels)
    default:
        panic("unknown metric type")
    }
}

// 实际使用示例
var (
    // 请求总数计数器
    requestTotal = NewSum(
        "requests_total",
        "The total number of requests",
    ).With(
        ResponseCodeLabel.Value("200"), 
        MethodLabel.Value("GET"),
    )
    
    // 响应时间直方图
    responseTime = NewHistogram(
        "response_duration_milliseconds",
        "Response time in milliseconds",
    ).With(
        ServiceLabel.Value("pilot"),
    )
    
    // 当前连接数量表
    currentConnections = NewGauge(
        "current_connections",
        "Current number of connections",
    )
)

// pkg/ctrlz/ctrlz.go
// ControlZ是Istio的内省工具。当组件集成ControlZ时，
// 它们自动获得一个IP端口，允许操作员可视化和控制进程的各个方面，
// 包括控制日志级别、查看命令行选项、内存使用等
// 该端口还实现了REST API，允许访问和控制相同的状态

// 核心主题列表 - 代表UI的不同部分
var coreTopics = []fw.Topic{
    topics.ScopeTopic(),      // 日志作用域管理
    topics.MemTopic(),        // 内存使用情况  
    topics.EnvTopic(),        // 环境变量
    topics.ProcTopic(),       // 进程信息
    topics.ArgsTopic(),       // 命令行参数
    topics.VersionTopic(),    // 版本信息
    topics.SignalsTopic(),    // 信号处理
}

// Server表示正在运行的ControlZ实例
type Server struct {
    listener   net.Listener      // 网络监听器
    shutdown   sync.WaitGroup    // 优雅关闭同步
    httpServer http.Server       // HTTP服务器
}

// 运行ControlZ服务器
func Run(o *Options, customTopics []fw.Topic) (*Server, error) {
    if o == nil {
        o = DefaultOptions()
    }

    // 合并核心主题和自定义主题
    topics := append(coreTopics, customTopics...)
    
    // 创建路由器
    router := mux.NewRouter()
    
    // 注册主题路由
    for _, topic := range topics {
        registerTopic(router, topic)
    }
    
    // 注册静态资源
    registerStatic(router)
    
    // 注册pprof端点（性能分析）
    registerPprof(router)
    
    // 启动HTTP服务器
    server := &http.Server{
        Handler: router,
        Addr:    o.Address,
    }
    
    return &Server{
        httpServer: *server,
    }, nil
}

// pkg/ctrlz/fw/topic.go
// Topic接口定义了ControlZ主题的行为
type Topic interface {
    // Title返回主题的标题
    Title() string
    
    // Prefix返回URL前缀
    Prefix() string
    
    // Activate激活主题，返回HTML模板数据
    Activate(context Context) string
    
    // GetRequest处理GET请求
    GetRequest(context Context) (string, error)
    
    // PostRequest处理POST请求  
    PostRequest(context Context) (string, error)
}

// 上下文接口提供请求处理所需的信息
type Context interface {
    // Request返回HTTP请求对象
    Request() *http.Request
    
    // ResponseWriter返回HTTP响应写入器
    ResponseWriter() http.ResponseWriter
    
    // Vars返回路径变量
    Vars() map[string]string
    
    // Query返回查询参数
    Query() url.Values
}

// 内存主题实现示例
type memTopic struct{}

func (m memTopic) Title() string {
    return "Memory Usage"
}

func (m memTopic) Prefix() string {
    return "mem"
}

func (m memTopic) Activate(context Context) string {
    // 收集内存统计信息
    var memStats runtime.MemStats
    runtime.ReadMemStats(&memStats)
    
    data := struct {
        Alloc        uint64
        TotalAlloc   uint64
        Sys          uint64
        Lookups      uint64
        Mallocs      uint64
        Frees        uint64
        HeapAlloc    uint64
        HeapSys      uint64
        HeapIdle     uint64
        HeapInuse    uint64
        HeapReleased uint64
        HeapObjects  uint64
        StackInuse   uint64
        StackSys     uint64
        MSpanInuse   uint64
        MSpanSys     uint64
        MCacheInuse  uint64
        MCacheSys    uint64
        GCSys        uint64
        NextGC       uint64
        LastGC       time.Time
        PauseTotalNs uint64
        NumGC        uint32
        NumForcedGC  uint32
    }{
        Alloc:        memStats.Alloc,
        TotalAlloc:   memStats.TotalAlloc,
        Sys:          memStats.Sys,
        // ... 更多字段
    }
    
    return renderTemplate("memory.html", data)
}

// 日志作用域主题 - 允许动态调整日志级别
type scopeTopic struct{}

func (s scopeTopic) PostRequest(context Context) (string, error) {
    request := context.Request()
    
    // 解析POST参数
    if err := request.ParseForm(); err != nil {
        return "", err
    }
    
    scopeName := request.FormValue("scope")
    levelStr := request.FormValue("level")
    
    // 查找日志作用域
    scope := log.FindScope(scopeName)
    if scope == nil {
        return "", fmt.Errorf("unknown scope: %s", scopeName)
    }
    
    // 解析日志级别
    level, err := log.StringToLevel(levelStr)
    if err != nil {
        return "", err
    }
    
    // 设置新的日志级别
    scope.SetOutputLevel(level)
    
    return fmt.Sprintf("Set %s to %v", scopeName, level), nil
}

// pkg/config/config.go
// Config是Istio配置的统一表示
type Config struct {
    // Meta包含所有配置的通用元数据
    Meta Meta
    
    // Spec是配置的规范，类型由Meta.Schema确定
    Spec proto.Message
    
    // Status是配置的状态信息
    Status proto.Message
}

// Meta包含配置元数据
type Meta struct {
    // GroupVersionKind标识配置的类型
    GroupVersionKind schema.GroupVersionKind
    
    // Name是配置对象的名称
    Name string
    
    // Namespace是配置对象的命名空间
    Namespace string
    
    // Domain是集群域名后缀
    Domain string
    
    // Labels是标签映射
    Labels map[string]string
    
    // Annotations是注释映射
    Annotations map[string]string
    
    // ResourceVersion用于乐观并发控制
    ResourceVersion string
    
    // CreationTimestamp是创建时间戳
    CreationTimestamp time.Time
    
    // UID是唯一标识符
    UID string
}

// Key返回配置的唯一键
func (m Meta) Key() string {
    return KeyFunc(m.GroupVersionKind.Kind, m.Name, m.Namespace)
}

// KeyFunc生成配置键的标准函数
func KeyFunc(typ, name, namespace string) string {
    return fmt.Sprintf("%s/%s/%s", typ, namespace, name)
}

// pkg/config/schema/collection/collections.go
// Resource描述配置资源的模式
type Resource struct {
    // Group是API组
    Group string
    
    // Version是API版本
    Version string
    
    // Kind是资源类型
    Kind string
    
    // Plural是复数形式的名称
    Plural string
    
    // ClusterScoped表示是否为集群级资源
    ClusterScoped bool
    
    // Proto是protobuf消息类型
    Proto proto.Message
    
    // ProtoPackage是proto包名
    ProtoPackage string
    
    // ValidateProto是验证函数
    ValidateProto validation.ValidateFunc
}

// Schema表示配置模式集合
type Schema struct {
    resources []Resource
    byKind    map[string]Resource
}

// 创建新的Schema
func NewSchemasBuilder() *Builder {
    return &Builder{
        resources: make([]Resource, 0),
    }
}

func (b *Builder) Add(r Resource) *Builder {
    b.resources = append(b.resources, r)
    return b
}

func (b *Builder) Build() Schema {
    byKind := make(map[string]Resource)
    for _, r := range b.resources {
        byKind[r.Kind] = r
    }
    
    return Schema{
        resources: b.resources,
        byKind:    byKind,
    }
}

// Istio核心配置资源定义
var (
    VirtualService = Resource{
        Group:         "networking.istio.io",
        Version:       "v1beta1",
        Kind:          "VirtualService",
        Plural:        "virtualservices",
        ClusterScoped: false,
        Proto:         &networking.VirtualService{},
        ValidateProto: validation.ValidateVirtualService,
    }
    
    DestinationRule = Resource{
        Group:         "networking.istio.io",
        Version:       "v1beta1", 
        Kind:          "DestinationRule",
        Plural:        "destinationrules",
        ClusterScoped: false,
        Proto:         &networking.DestinationRule{},
        ValidateProto: validation.ValidateDestinationRule,
    }
    
    Gateway = Resource{
        Group:         "networking.istio.io",
        Version:       "v1beta1",
        Kind:          "Gateway", 
        Plural:        "gateways",
        ClusterScoped: false,
        Proto:         &networking.Gateway{},
        ValidateProto: validation.ValidateGateway,
    }
)

// 构建完整的Pilot配置模式
func PilotSchema() Schema {
    return NewSchemasBuilder().
        Add(VirtualService).
        Add(DestinationRule).
        Add(Gateway).
        Add(ServiceEntry).
        Add(Sidecar).
        Add(WorkloadEntry).
        Add(WorkloadGroup).
        Add(PeerAuthentication).
        Add(RequestAuthentication).
        Add(AuthorizationPolicy).
        Add(Telemetry).
        Add(ProxyConfig).
        Build()
}

// pkg/config/validation/validation.go
// ValidateFunc定义验证函数类型
type ValidateFunc func(config proto.Message) error

// Warning表示验证警告
type Warning struct {
    Message string
}

// Error表示验证错误
type Error struct {
    Field   string
    Message string
}

// ValidationResult包含验证结果
type ValidationResult struct {
    Errors   []Error
    Warnings []Warning
}

func (v ValidationResult) IsValid() bool {
    return len(v.Errors) == 0
}

// VirtualService验证实现示例
func ValidateVirtualService(cfg proto.Message) error {
    vs, ok := cfg.(*networking.VirtualService)
    if !ok {
        return fmt.Errorf("expected VirtualService, got %T", cfg)
    }
    
    var result ValidationResult
    
    // 验证主机名
    if len(vs.Hosts) == 0 {
        result.Errors = append(result.Errors, Error{
            Field:   "hosts",
            Message: "hosts field is required",
        })
    }
    
    for i, host := range vs.Hosts {
        if err := ValidateHost(host); err != nil {
            result.Errors = append(result.Errors, Error{
                Field:   fmt.Sprintf("hosts[%d]", i),
                Message: err.Error(),
            })
        }
    }
    
    // 验证HTTP路由规则
    for i, route := range vs.Http {
        if err := validateHTTPRoute(route); err != nil {
            result.Errors = append(result.Errors, Error{
                Field:   fmt.Sprintf("http[%d]", i),
                Message: err.Error(),
            })
        }
    }
    
    if !result.IsValid() {
        return fmt.Errorf("validation failed: %v", result.Errors)
    }
    
    return nil
}

// 主机名验证
func ValidateHost(host string) error {
    if len(host) == 0 {
        return fmt.Errorf("host cannot be empty")
    }
    
    // 检查通配符主机名
    if strings.HasPrefix(host, "*") {
        if len(host) == 1 || host[1] != '.' {
            return fmt.Errorf("wildcard host %s is not valid", host)
        }
    }
    
    // 检查FQDN格式
    if !isValidDNSName(host) {
        return fmt.Errorf("host %s is not a valid DNS name", host)
    }
    
    return nil
}

// pkg/log/config.go
// Options包含日志系统的配置选项
type Options struct {
    // OutputPaths是日志输出路径列表
    OutputPaths []string
    
    // ErrorOutputPaths是错误日志输出路径列表  
    ErrorOutputPaths []string
    
    // RotateOutputPath是日志轮转输出路径
    RotateOutputPath string
    
    // RotationMaxSize是单个日志文件的最大大小（MB）
    RotationMaxSize int
    
    // RotationMaxAge是日志文件保留的最大天数
    RotationMaxAge int
    
    // RotationMaxBackups是保留的旧日志文件最大数量
    RotationMaxBackups int
    
    // JSONEncoding控制是否使用JSON格式编码
    JSONEncoding bool
    
    // LogGrpc启用gRPC日志记录
    LogGrpc bool
    
    // Level设置日志级别
    Level string
    
    // StackTraceLevel设置堆栈跟踪的最小级别
    StackTraceLevel string
}

// Scope表示日志作用域，提供分层的日志控制
type Scope struct {
    // name是作用域的名称
    name string
    
    // nameToEmit是实际发出的名称（可能被截断）
    nameToEmit string
    
    // description是作用域的描述
    description string
    
    // callerSkip是调用栈跳过的层数
    callerSkip int
    
    // logger是底层的zap.Logger
    logger *zap.SugaredLogger
    
    // level是当前的日志级别（原子操作）
    level *zap.AtomicLevel
}

// RegisterScope注册一个新的日志作用域
func RegisterScope(name, description string, callerSkip ...int) *Scope {
    skip := 0
    if len(callerSkip) > 0 {
        skip = callerSkip[0]
    }
    
    s := &Scope{
        name:        name,
        nameToEmit:  name,
        description: description,
        callerSkip:  skip,
        level:       zap.NewAtomicLevel(),
    }
    
    // 注册到全局作用域映射
    registerScope(s)
    
    return s
}

// 日志方法实现
func (s *Scope) Info(msg string) {
    s.logger.Info(msg)
}

func (s *Scope) Infof(template string, args ...interface{}) {
    s.logger.Infof(template, args...)
}

func (s *Scope) Infow(msg string, keysAndValues ...interface{}) {
    s.logger.Infow(msg, keysAndValues...)
}

func (s *Scope) Error(msg string) {
    s.logger.Error(msg)
}

func (s *Scope) Errorf(template string, args ...interface{}) {
    s.logger.Errorf(template, args...)
}

func (s *Scope) Errorw(msg string, keysAndValues ...interface{}) {
    s.logger.Errorw(msg, keysAndValues...)
}

// WithLabels创建带有结构化标签的新作用域
func (s *Scope) WithLabels(keysAndValues ...interface{}) *Scope {
    newLogger := s.logger.With(keysAndValues...)
    return &Scope{
        name:       s.name,
        nameToEmit: s.nameToEmit,
        logger:     newLogger,
        level:      s.level,
    }
}