文档说明

作者：痴者工良

作者博客地址：

https://www.whuanle.cn

https://www.cnblogs.com/whuanle

教程地址：

https://docs.whuanle.cn/zh/maomi_mq

导读

Maomi.MQ 是一个面向 RabbitMQ 的消息通讯框架，目标不是把消息队列“藏起来”，而是在保留 RabbitMQ 核心能力的前提下，尽量降低发布、消费、路由绑定、重试处理和异常恢复的接入复杂度。

在常见业务系统里，消息队列通常要同时面对这些问题：

• 发布端代码重复，业务代码和消息投递逻辑耦合严重；
• 消费端配置分散，交换器、路由键、队列、死信、并发控制容易遗漏；
• 出错后的重试、补偿、死信转移、幂等处理经常需要重复造轮子；
• 做链路追踪、事务消息、跨框架集成时，接入成本明显升高。

Maomi.MQ.RabbitMQ 针对这些场景，提供了统一的发布与消费抽象，并围绕“可靠投递、易于扩展、方便排障”三个目标做了较多工程化封装。你既可以把它当作 RabbitMQ 的高层开发组件来使用，也可以把它当作一套消息系统设计范例来阅读。

核心能力

• 简化消息发布与消费模型，降低 RabbitMQ 接入样板代码；
• 统一消费者配置，集中管理队列、交换器、路由、死信和并发参数；
• 支持普通消费者、事件总线编排、动态消费者和动态订阅；
• 支持 Qos 并发控制、失败重试、死信转移等可靠性机制；
• 支持可观测性接入，便于对消息流转过程做追踪与诊断；
• 支持本地事务消息模式，使用 Outbox + Inbox Barrier 提升最终一致性；
• 支持多种序列化方案，兼顾性能、体积和跨语言兼容；
• 支持与 MediatR、FastEndpoints 等应用层框架协作。

目录

• 快速开始

  安装依赖、理解基础概念，并跑通第一个可工作的示例。

• 消息发布者

  介绍消息发布模型、消息体定义和发布端常见用法。

• 消费者

  介绍消费者抽象以及队列、死信、Qos 等核心配置项。

  • 普通消费者模式

    介绍最常用的消费者实现方式与注册方式。

  • 基于事件

    介绍事件总线编排、补偿和业务流程组织思路。

  • 自定义消费者和动态订阅

    介绍如何在运行时动态绑定消费者和订阅关系。

• 配置

  介绍框架配置项、调试方式和常见配置策略。

• Qos 并发和顺序

  介绍并发控制、顺序消费以及不同消费负载下的配置建议。

• 重试

  介绍失败重试策略、默认行为以及自定义重试实现方式。

• 死信队列

  介绍死信消息转移、失败消息兜底和异常处理链路。

• 可观测性

  介绍如何把消息发布和消费过程接入 OpenTelemetry 体系。

• 本地事务消息（Outbox + Inbox Barrier）完整指南

  介绍“写库 + 发 MQ”场景下的最终一致性设计与工程实践。

• 序列化与反序列化

  介绍多种序列化器的选型建议、性能差异和接入方式。

• 支持 MediatR / FastEndpoints

  介绍如何把 Maomi.MQ 与常见应用层框架组合使用。

希望本系列教程不仅能帮助你更快地使用 Maomi.MQ，也能帮助你建立对消息系统可靠性、可观测性和一致性设计的整体认识。