Skip to content

Comments

refactor: 统一配置驱动 API 设计 (Unified API Design)#34

Merged
ceyewan merged 22 commits intomainfrom
refactor/unified-api
Jan 4, 2026
Merged

refactor: 统一配置驱动 API 设计 (Unified API Design)#34
ceyewan merged 22 commits intomainfrom
refactor/unified-api

Conversation

@ceyewan
Copy link
Owner

@ceyewan ceyewan commented Jan 4, 2026

概述

本 PR 完成了 Genesis 组件库的统一配置驱动 API 重构，实现了 Issue #32 的设计目标。

变更统计

  • 22 commits
  • 176 files changed
  • +8,926 / -9,440 lines

主要变更

1. 统一 API 设计

  • 所有核心组件统一为 New(cfg *Config, opts ...Option) 签名
  • Config.Driver 字段控制底层实现选择
  • Option 模式注入 Connector，保持显式依赖原则

2. 重构完成的组件

组件 变更
clog 精简 options 设计，移除过度配置
config 精简 API，移除冗余 Option 和便捷函数
connector 精简 API，修复配置不一致问题，添加 SASL 支持
auth 精简 API，添加测试和基准测试
idgen 新增 Allocator 接口，优化并发性能，添加基准测试
cache 统一 API，新增 Driver 字段，添加 Redis Trace 支持
dlock 统一 API，移除内置 metrics
mq 隐藏底层驱动实现，精简公开 API，添加消息头透传
ratelimit 统一 API，优化 gRPC 中间件
registry 新增 StreamManager，移除本地缓存
breaker 简化组件，移除 metrics 依赖，新增流式支持
idem 重命名包（idempotency），统一 API，新增 Memory 驱动
db 统一 API，添加 OpenTelemetry trace 支持

3. 新增功能

  • trace 包: OpenTelemetry Trace 支持
  • observability 示例: 统一的可观测性演示
  • idem 包: 新增 Consume 方法用于消息消费幂等
  • registry: StreamManager 支持每实例一条流
  • mq: 消息头透传支持

4. 移除内容

  • 组件内置 metrics 记录（简化职责）
  • 过时的文档文件（component-spec.md, issue-idgen-etcd.md, refactor-unified-api.md）
  • 冗余的 Option 和便捷函数

测试

  • 所有现有测试已通过
  • 新增集成测试和基准测试

文档

  • 更新 CLAUDE.md、README.md
  • 新增 docs/API.md 组件 API 参考
  • 新增 examples/observability 统一示例

破坏性变更

  1. idempotency → idem: 包名变更，import 路径需要更新
  2. API 签名: 部分组件的 New 函数签名变更
  3. 配置结构: ratelimit.Mode → Config.Driver
  4. metrics: 移除组件内置的 metrics 记录

🤖 Generated with Claude Code

ceyewan and others added 22 commits January 3, 2026 19:13
@ceyewan @claude
refactor(clog): 精简 options 设计，移除过度配置
b05d6b0 
- 删除 Required、WithExtractor、WithContextPrefix、WithNamespaceJoiner
- 简化 ContextField 结构体，只保留 Key 和 FieldName
- WithContextField 从 3 参数简化为 2 参数
- Context 字段提取不再自动添加前缀，直接使用 FieldName
- 新增 docs/API.md 统一 API 文档
- 更新 README.md，精简错误字段说明

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(config): 精简 API，移除冗余 Option 和便捷函数
33873d4 
- 删除 WithConfigName/Path/Paths/Type/EnvPrefix/Remote 等函数
  Config 结构体已公开，直接传参即可
- 删除 IsNotFound/IsInvalidInput 便捷函数
  用户直接用 errors.Is(err, config.ErrNotFound)
- 删除 WrapValidationError/WrapLoadError 便捷函数
  用户直接用 xerrors.Wrap/Wrapf
- 精简 errors.go，只保留 ErrNotFound 和 ErrValidationFailed
- 精简 README.md，从 367 行减少到 116 行
- 更新 docs/API.md，添加 config 组件文档

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
feat(observability): 添加 OpenTelemetry 链路追踪和可观测性统一示例
ca8c73e 
- 新增 trace 组件，提供基于 OpenTelemetry 的分布式追踪能力
  - 支持 Provider/Tracer 初始化与 Shutdown
  - 提供 Noop 实现用于测试/降级
  - 支持通过 HTTP/gRPC/MQ 上下文传递 TraceID

- metrics 组件精简重构
  - 移除冗余的 options.go，直接使用 Config 配置
  - 新增 NewDevDefaultConfig 便捷函数用于开发环境
  - 新增 EnableRuntime 开关支持 Go Runtime 指标

- clog 组件集成 Trace Context
  - 新增 WithTraceContext() 选项自动提取 OTel TraceID/SpanID
  - 日志自动关联链路追踪，支持 Grafana 跳转

- 新增 observability 统一示例
  - 整合 Logging/Metrics/Tracing 三大支柱
  - 提供 Docker Compose 一键启动 LGTM 栈
  - 演示 HTTP → gRPC → MQ 全链路 Trace 透传
  - 预置 Grafana 仪表盘配置

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(auth): 精简 API 并添加测试和基准测试
736f98e 
- 使用 clog.Discard() 和 metrics.Discard() 替代自定义空实现
- 移除 nilLogger 和 GetCounter/GetHistogram 方法
- 精简指标到 3 个 Counter：验证成功、验证失败、刷新次数
- 新增 metrics.go 导出指标名称常量
- 支持多源 Token 提取（Header -> Query -> Cookie），开箱即用
- 新增 24 个测试用例覆盖核心功能
- 新增 5 个基准测试，性能：Header 提取 ~46ns，Token 生成 ~1430ns

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(idgen): 优化 Allocator 并发性能并添加基准测试
b0542cc 
- Allocator (Redis/Etcd) 使用随机起点环形遍历替代线性遍历，减少多实例并发启动时的冲突
- Snowflake 使用 atomic.Uint64 + CAS 替代 sync.Mutex，提升高并发性能
- Sequencer 移除 Etcd 实现，专注 Redis 单一后端
- 添加 Sequencer 完整基准测试（单键/并行/多键/批量）

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(connector): 精简 API，修复配置不一致问题并添加 SASL 支持
41a6fb1 
- 移除 metrics 支持（连接层指标意义不大，应放在业务层）
- 修复 MySQL DSN 字段未生效问题（优先使用 cfg.DSN）
- 修复 MySQL ConnMaxLifetime 配置不一致（统一使用 ConnMaxLifetime）
- 修复 Redis MinIdleConns 默认值逻辑（从 < 0 改为 <= 0）
- 修复 WithLogger(nil) 可能 panic 问题（添加 applyDefaults）
- 统一校验错误使用 ErrConfig 替代 fmt.Errorf
- 未使用的配置项标注为 [预留]
- 添加 Kafka SASL/PLAIN 认证支持（connector 和 mq driver）
- 移除 KafkaConnector.Config() 方法
- 移除 DatabaseConnector 接口，统一使用 TypedConnector[*gorm.DB]

Closes #31

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(db): 适配 DatabaseConnector 接口移除
2cef9f2 
- 将 connector.DatabaseConnector 改为 connector.MySQLConnector
- 修复示例中 MaxLifetime 改为 ConnMaxLifetime

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(db): 统一配置驱动 API 并添加 OpenTelemetry trace 支持
9ea01de 
主要变更：
- API 重构：New(cfg, opts...) 替代 New(conn, cfg, opts...)
- 配置驱动：添加 Config.Driver 字段支持 mysql/sqlite 切换
- 添加 WithTracer() 选项，集成 otelgorm 插件自动记录数据库查询
- 移除 WithMeter() 选项（未使用）
- SQLite 也支持分片，保持与 MySQL 一致的语义
- 更新示例为 SQLite 版本，无需外部依赖即可运行

(Closes #31)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(mq): 隐藏底层驱动实现，精简公开 API
839da9f 
主要变更：
- Driver 接口改为私有 driver 接口，不再对外暴露
- 移除 NewClient() 函数，仅保留配置驱动的 New(cfg, opts...)
- 驱动构造函数改为私有：newNatsCoreDriver、newNatsJetStreamDriver、newRedisDriver
- 移除未实现的 Kafka 驱动代码
- 优化 Message 接口注释，明确各驱动 Ack/Nak 行为差异
- 完善 SubscribeChan 文档，说明手动 Ack 的使用场景
- 同步更新 testkit 和文档

设计原则：
- 用户仅需知道 Client 接口和 Config.Driver 配置
- 底层驱动切换完全通过配置驱动实现
- 遵循"不暴露实现"的 Genesis 组件设计规范

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(dlock): 统一配置驱动 API 并移除 metrics
0bb7319 
主要变更：
- API 重构：New(cfg, opts...) 替代 New(conn, cfg, opts...)
- 配置驱动：添加 Config.Driver 字段支持 redis/etcd 切换
- 隐藏底层驱动实现：driver 接口私有化
- 移除 metrics：删除未使用的 metrics 相关代码
- 合并示例：dlock-etcd 和 dlock-redis 合并为单一示例

设计原则：
- 用户仅需知道 Lock 接口和 Config.Driver 配置
- 底层驱动切换完全通过配置驱动实现
- 遵循"不暴露实现"的 Genesis 组件设计规范

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
feat(mq): 添加消息头透传支持并完善可观测性
7f24002 
- 新增 Headers 类型和 WithHeaders/WithHeader 选项，支持元数据透传
- NATS 驱动复用原生 Header，Redis 驱动通过 JSON 序列化存储
- Message 接口新增 Headers() 和 Context() 方法
- 修复 Context 透传问题，确保订阅上下文正确传递到 Handler
- 完善 metrics 收集：统一在 wrapHandler 中处理消费指标
- 添加 metrics 常量定义和默认值处理（metrics.Discard()）
- 新增 message_helpers.go 存放通用辅助函数

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(dlock): 移除 metrics 支持并精简文档
fc2bd1c 
- 移除 WithMeter 选项和 meter 字段（当前未实际使用）
- 更新 Redis/Etcd 驱动构造函数，移除 meter 参数
- 精简包注释：从 48 行减少到 18 行
- 精简 README：从 295 行减少到 129 行
- 移除所有 metrics 相关文档和示例

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(cache): 统一配置驱动 API 并添加 Redis Trace 支持
ce19623 
Cache 组件：
- New 改为配置驱动模式，通过 Driver 选择后端（redis/memory）
- 移除 Mode 和 RedisConnectorName 配置字段
- 移除 NewStandalone 构造函数，统一使用 New
- 新增 DriverRedis 和 DriverMemory 常量
- Config 新增 setDefaults 和 validate 方法
- WithRedisConnector 增加 nil 检查

Connector：
- RedisConfig 新增 EnableTracing 配置项
- 使用 redisotel.InstrumentTracing 实现 Redis Trace
- go.mod 新增 redisotel 依赖

文档：
- cache/README.md 精简并更新为新 API（420→107 行，-75%）
- connector/README.md 新增 Trace 使用文档
- docs/* 同步更新配置驱动 API 示例
- examples/cache/main.go 更新为新 API

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(registry): 移除本地缓存并简化配置
b3367bd 
- 移除 EnableCache、CacheExpiration、Schema 配置字段
- 移除本地缓存机制，GetService 每次从 etcd 查询
- gRPC resolver scheme 固定为 "etcd"
- Watch 使用 watchID 替代 serviceName 作为 key，支持同名服务多次监听
- GetConnection 增加 waitForReady，支持 deadline 上下文
- 优化 KeepAlive 关闭逻辑，区分正常关闭和异常断开
- 测试改用 testkit 获取 etcd 连接

文档：
- README.md 更新配置示例
- examples/* 使用 clog 替代 log，增加 Connect 调用

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
feat(registry): 添加 StreamManager 支持每实例一条流
676a9ae 
新增 StreamManager，自动管理每个服务实例的一条 gRPC 双向流：
- 启动时全量建立流，Watch 监听上下线自动增删
- 流断开后自动重建（先复用连接，失败后新建）
- 支持 EndpointPicker 轮询选择实例的多个 endpoint
- 提供 StreamHandler 生命周期回调（OnAdd/OnRemove/OnError）
- 支持获取当前流快照（Streams 方法）

新增：
- registry/stream_manager.go - StreamManager 实现
- examples/registry-stream/ - 使用示例
- docs: README.md 更新使用文档

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(registry): 移除内置 DialOption，要求用户显式传入
3fa06f1 
- GetConnection 不再提供默认的 WithTransportCredentials
- StreamManager 不再提供默认的 WithTransportCredentials
- 用户必须显式传入 grpc.WithTransportCredentials() 或其他凭证选项
- 更新 README 和示例代码，添加必要的 DialOption 参数

原因：用户可能需要自定义负载均衡策略（如 pick_first），
内置的 round_robin 和 insecure 凭证会限制灵活性。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(ratelimit): 统一配置驱动 API 并优化中间件
c0c874f 
核心变更：
- New 改为配置驱动，通过 Driver 选择后端（standalone/distributed）
- 移除 NewStandalone 和 NewDistributed 公开构造函数
- 新增 DriverStandalone 和 DriverDistributed 常量
- Config 中的 Mode 改为 Driver，配置项改为指针类型
- 新增 WithRedisConnector 选项，通过 Option 注入连接器

Limiter 接口：
- 新增 AllowN 方法支持批量令牌获取
- 新增 Close 方法用于资源释放

gRPC 拦截器：
- 新增 StreamServerInterceptor 和 StreamClientInterceptor
- 流式默认按每条消息限流（RecvMsg/SendMsg）
- 错误返回使用 status.Error(codes.ResourceExhausted, ...)
- 移除内置 KeyFunc，使用默认 fullMethod 作为 key

Gin 中间件：
- 统一为 GinMiddleware，使用 GinMiddlewareOptions 结构体配置
- KeyFunc 和 LimitFunc 合并到 Options 中

文档：
- README.md 更新为新 API 示例
- examples/ratelimit/main.go 更新为新 API 并添加更多示例
- docs/API.md 和 docs/refactor-unified-api.md 同步更新

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
refactor(breaker): 简化熔断器组件并移除指标依赖
8b67adc 
- 移除 StreamClientInterceptor 及相关代码，专注 Unary 调用
- 移除 metrics 依赖和 WithMeter 选项，简化组件职责
- 删除 keyfunc.go 中预设的 KeyFunc 选项，仅保留 WithKeyFunc
- 简化错误定义：ErrServiceNameEmpty 改为 ErrKeyEmpty，移除 ErrBreakerNotFound
- 更新 README 移除指标说明和监控告警示例
- 示例代码同步更新，移除 metrics 依赖

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan
feat(breaker): 实现流式熔断器支持
f83893d 
- 新增 StreamClientInterceptor 接口支持 gRPC 流式熔断
- 实现消息级熔断(BreakOnMessage)与建流级熔断(BreakOnCreate)分离配置
- 引入 executeWithoutFallback 机制防止流式消息被错误降级
- 支持自定义错误分类器(FailureClassifier)
- 完善单元测试覆盖边界场景
@ceyewan @claude
refactor(idem): 重命名包并统一配置驱动 API
2c809b7 
- 包名重命名: idempotency → idem（更简洁）
- 统一配置驱动: 新增 Config.Driver 字段支持扩展
- 简化选项: 移除 WaitTimeout 和 WithMeter
- 新增文件: config.go, errors.go, impl.go
- 删除文件: implementation.go, metrics.go
- 更新所有文档和示例中的包引用

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
feat(idem): 新增内存驱动和 Consume 方法
af71f46 
- 新增 DriverMemory 支持单机内存存储
- 新增 Consume 方法用于消息消费幂等处理
- 新增 memory.go 实现内存存储后端

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan @claude
docs: 清理已完成的文档和问题文档
988633b 
- 删除 refactor-unified-api.md（重构已完成）
- 删除 component-spec.md（规范已整合到 CLAUDE.md）
- 删除 issue-idgen-etcd.md（需求已合并到 idgen 组件）

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ceyewan ceyewan merged commit 4115c8e into main Jan 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ceyewan