应定义Receiver和Dispatcher接口解耦消息接入与分发：Receiver负责Start/Stop及将各类源消息标准化为Message结构体，Dispatcher按Topic动态注册处理器并保证幂等、异步、语义明确（如HTTP用202、Kafka延迟提交offset），Message.ID须由接收器统一生成以保障幂等性。
如何设计一个支持多种消息源的通用接收器接口
Go 里没有“通用消息总线”这种现成抽象，得自己定义干净、可扩展的接口。核心是把「消息来源」和「分发逻辑」解耦，避免每加一种协议（HTTP、gRPC、Kafka）就重写路由逻辑。
推荐用 Receiver 接口统一接收入口，用 Dispatcher 接口封装分发行为，两者通过 Message 结构体桥接：
type Message struct {
ID string
Topic string
Payload []byte
Metadata map[string]string
Timestamp time.Time
}
type Receiver interface {
Start(ctx context.Context) error
Stop() error
}
type Dispatcher interface {
Dispatch(ctx context.Context, msg *Message) error
}
这样 HTTP 接收器只管解析 POST /webhook 请求并转成 Message，Kafka 消费者也只负责拉取 record → 构造 Message，后续都交给同一个 Dispatcher 实现。
为什么不能直接在 Handler 里做业务逻辑分发
常见错误是把 http.HandlerFunc 或 kafka.ConsumerGroupHandler 当作分发起点，在里面硬编码 if topic == "order.created" { handleOrderCreated(...) } —— 这会导致：
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 测试困难：无法 mock 接收层单独测分发逻辑
- 横向扩展受限：想加 RabbitMQ 支持就得改所有 Handler
- 中间件难插拔：日志、验签、限流等横切关注点分散在各处
正确做法是让接收器只做三件事：解码 → 标准化 → 丢给 Dispatcher。比如 HTTP 接收器应统一提取 X-Topic header 或 path segment 作为 Message.Topic，不关心下游怎么处理。
Dispatcher 如何支持按 Topic 动态注册处理器
硬编码 switch topic 不可维护，用 map + sync.RWMutex 实现运行时注册更灵活：
type TopicDispatcher struct {
handlers map[string]func(context.Context, *Message) error
mu sync.RWMutex
}
func (d *TopicDispatcher) Register(topic string, h func(context.Context, *Message) error) {
d.mu.Lock()
defer d.mu.Unlock()
d.handlers[topic] = h
}
func (d *TopicDispatcher) Dispatch(ctx context.Context, msg *Message) error {
d.mu.RLock()
h, ok := d.handlers[msg.Topic]
d.mu.RUnlock()
if !ok {
return fmt.Errorf("no handler registered for topic %q", msg.Topic)
}
return h(ctx, msg)
}
注意点：
- 注册必须在
Start()之前完成，否则可能漏消息 - 不要在
Register里传入闭包捕获外部变量，容易引发 goroutine 泄漏 - 如果需要优先级或 fallback 处理，可额外加
defaultHandler字段
如何避免消息丢失和重复分发
通用 API 往往暴露给不可信外部系统，必须明确语义边界：
- HTTP 接收器默认用
202 Accepted响应，表示“已收到，但不保证处理成功”，避免调用方重试导致重复 - Kafka 接收器应在
Dispatcher.Dispatch()成功后才提交 offset，失败则返回 error 让 consumer 重试 - 所有
Dispatcher实现必须是幂等的 —— 同一Message.ID被多次传入，结果一致 - 不要在
Dispatcher里做耗时操作（如写 DB），应投递到内部 channel 或 worker pool 异步处理
最常被忽略的是：Message 结构体里的 ID 字段必须由接收器生成或透传，不能依赖下游生成 —— 否则不同接收器产生的 ID 规则不一致，幂等逻辑就失效了。
