vitepress-template

Appearance

bi-notify 消息通知服务 ​

**本文档引用的文件** - [[[[[main.go]]]]](../file/bi-notify/cmd/bi-notify/main.go) - [[[[[notification.go]]]]](../file/bi-notify/internal/biz/notification.go) - [[[[[channel_adapter.go]]]]](../file/bi-notify/internal/biz/channel-adapter.go) - [[[[[notification_router.go]]]]](../file/bi-notify/internal/biz/notification-router.go) - [[[[[template_engine.go]]]]](../file/bi-notify/internal/biz/template-engine.go) - [[[[[notification_worker.go]]]]](../file/bi-notify/internal/biz/notification-worker.go) - [[[[[notification_producer.go]]]]](../file/bi-notify/internal/biz/notification-producer.go) - [[[[[dingtalk_adapter.go]]]]](../file/bi-notify/internal/biz/dingtalk-adapter.go) - [[[[[feishu_adapter.go]]]]](../file/bi-notify/internal/biz/feishu-adapter.go) - [[[[[sms_adapter.go]]]]](../file/bi-notify/internal/biz/sms-adapter.go) - [[[[[email_adapter.go]]]]](../file/bi-notify/internal/biz/email-adapter.go) - [[[[[architecture-bi-notify.md]]]]](../file/bi-notify/docs/architecture-bi-notify.md) - [[[[[NOTIFICATION_API.md]]]]](../file/bi-notify/docs/notification-api.md) - [[[[[notification.proto]]]]](../file/bi-notify/api/notify/v1/notification.proto) - [[[[[go.mod]]]]](../file/bi-notify/go.mod)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

bi-notify 是统一的通知网关服务，负责全系统的多渠道消息分发与投递，支持钉钉、飞书、短信、邮件等渠道。系统采用事件驱动与Kafka消息队列实现异步解耦，具备幂等性、重试与死信处理能力，并提供模板引擎与动态内容渲染，满足不同业务域的通知需求。

项目结构 ​

  • 二进制入口与依赖注入：cmd/bi-notify
  • 业务域模型与适配器：internal/biz
  • API 定义与文档：api/notify/v1、docs
  • 配置与部署：configs、k8s、scripts

图表来源

章节来源

核心组件 ​

  • 事件模型与状态：定义通知事件类型、渠道、状态与记录结构，支持幂等键与Kafka位点信息。
  • 事件生产者：将通知事件发送至Kafka事件主题，保证有序性与可追踪性。
  • 事件路由器：根据路由规则与模板映射，将事件拆分为任务并发送至任务主题。
  • 渠道适配器：抽象各渠道发送接口，实现钉钉、飞书、短信、邮件的差异化适配。
  • 模板引擎：基于Go text/template语法，支持自定义函数与变量渲染。
  • 通知工作者：对外提供统一的事件分发入口，完成参数校验与事件派发。

章节来源

架构总览 ​

系统采用"事件驱动 + 多渠道适配"的架构，通过Kafka实现生产者与消费者的解耦。事件从业务服务进入，经由通知工作者与事件生产者写入事件主题；事件路由器订阅事件主题，依据路由规则与模板映射生成任务并写入任务主题；渠道适配器消费任务主题，调用第三方平台API完成发送，并记录发送状态与重试策略。

图表来源

章节来源

详细组件分析 ​

事件模型与状态 ​

  • 事件类型：note_create、note_finish 等。
  • 渠道枚举：dingtalk、feishu、sms、email。
  • 状态机：待发送、处理中、成功、失败、重试中、永久失败。
  • 记录结构：包含事件ID、任务ID、模板ID、渠道、接收者、重试次数、Kafka位点、第三方消息ID等，便于追踪与重放。

图表来源

章节来源

事件生产者与路由 ​

  • 事件生产者负责参数校验、事件ID与时间戳补全、Kafka消息键生成（biz:event_type）并发送至事件主题。
  • 事件路由器从事件主题消费，获取路由规则与模板映射，构建模板数据，按目标与渠道拆分任务，发送至任务主题。

图表来源

章节来源

渠道适配器与发送流程 ​

  • 渠道适配器接口统一Send方法，支持幂等性检查、状态记录、模板渲染与错误处理。
  • 钉钉/飞书：通过用户手机号获取用户ID，渲染模板后调用平台卡片/Markdown消息接口。
  • 短信：使用阿里云模板Code与变量参数，调用短信发送接口。
  • 邮件：支持阿里云模板或本地渲染HTML/纯文本。

图表来源

章节来源

模板引擎与动态渲染 ​

  • 支持Go text/template语法，内置upper、lower、add等函数。
  • 提供事件与任务两种渲染入口，自动合并事件元数据与任务元数据。
  • 支持模板语法验证与变量提取（预留）。

图表来源

章节来源

通知API与使用指南 ​

  • gRPC/HTTP接口：SendNotification、BatchSendNotification、GetNotificationStatus。
  • 请求参数：biz、event_type、sender、recipients、content、channels、options、extra。
  • 状态查询：通过event_id查询事件整体状态与各接收者结果。
  • 幂等性：使用request_id实现请求幂等。
  • 批量发送：提升吞吐，减少网络开销。

章节来源

依赖关系分析 ​

  • 入口依赖注入：main.go通过wire生成应用，启动Kratos服务并启动Kafka消费者管理器。
  • 业务依赖：通知工作者依赖事件生产者、仓库与用户服务；路由器依赖配置服务、Kafka生产者、模板引擎与适配器集合。
  • 渠道适配器：依赖配置服务、用户服务、仓库、Kafka生产者、模板引擎与平台客户端。

更新 依赖关系已调整，移除了对 bi-proto 模块的依赖，所有协议定义直接使用本地 proto 文件。

图表来源

章节来源

性能考虑 ​

  • 异步解耦：通过Kafka实现生产者与消费者的解耦，提升系统吞吐与可用性。
  • 分区键策略：事件生产者使用biz:event_type作为Kafka消息键，保证同一业务同一事件类型的有序处理。
  • 任务拆分：路由器按目标与渠道拆分任务，提升并发度与资源利用率。
  • 模板渲染：模板引擎采用Go text/template，避免复杂表达式，减少渲染开销。
  • 重试与死信：适配器内置重试与死信处理，降低失败影响并支持人工干预。
  • 监控与可观测性：结合日志、追踪与指标，定位性能瓶颈与异常路径。

故障排查指南 ​

  • 发送失败重试：检查适配器错误处理逻辑与最大重试次数，必要时查看死信主题。
  • 幂等性问题：确认事件ID与接收者渠道组合的幂等键是否正确。
  • 模板渲染异常：验证模板语法与变量是否匹配，关注模板引擎日志。
  • 平台配置缺失：确认平台配置状态与凭证是否正确。
  • Kafka消费停滞：检查消费者组、分区分配与位移提交情况。

章节来源

结论 ​

bi-notify通过事件驱动与Kafka解耦，实现了多渠道通知的统一网关。其清晰的领域模型、可扩展的适配器接口与模板引擎，使得系统既能快速适配新渠道，又能灵活应对不同业务域的通知需求。配合完善的重试与死信机制，系统在可靠性与可维护性方面具备良好基础。

附录 ​

通知API接口定义 ​

  • gRPC服务：NotificationApiService
    • SendNotification：发送通知
    • BatchSendNotification：批量发送
    • GetNotificationStatus：查询状态
  • HTTP路由：
    • POST /api/v1/notify/send
    • POST /api/v1/notify/batch-send
    • GET /api/v1/notify/status/

章节来源

通知渠道配置指南 ​

  • 钉钉：配置app_key、app_secret、agent_id。
  • 飞书：配置app_id、app_secret。
  • 短信（阿里云）：配置access_key_id、access_key_secret、sign_name、endpoint。
  • 邮件：支持阿里云模板或本地渲染（规划中）。

章节来源

消息路由与模板映射 ​

  • 路由规则：事件类型到渠道列表的映射，支持默认规则与目标指定渠道。
  • 模板映射：事件类型与渠道到模板ID的映射，支持事件内模板键覆盖。

章节来源

依赖关系更新说明 ​

更新 依赖关系已完全重构，移除了对 bi-proto 模块的外部依赖，所有协议定义均采用本地 proto 文件：

  • 移除了对 codeup.aliyun.com/6948c28bf7465fb3044334e2/bi/bi-proto 的依赖声明
  • 所有 gRPC 服务接口直接引用本地 api/notify/v1/*.proto 文件
  • 服务间通信完全基于本地协议定义，无需外部模块依赖
  • 减少了模块间的耦合度，提升了系统的独立性和可维护性

这种调整使得 bi-notify 服务更加轻量化，不再依赖外部的 bi-proto 模块，所有协议定义都集中在服务内部，便于独立部署和版本管理。