MongoDB Change Streams 实战：避开副本集监听的四大陷阱
说到用 MongoDB Change Streams 监听数据变更，很多开发者都踩过坑。你可能会想，这不就是个监听数据库变化的API吗？但真用起来，尤其是在副本集环境下，从连接建立到事件恢复，处处都是细节。下面这几个关键问题，几乎每个生产部署都会遇到。
Change Streams 不能跨副本集所有节点监听，仅支持在 primary 节点上基于 oplog 创建；需通过含 replicaSet 参数的连接字符串连接，并确保权限（如 clusterMonitor）与配置匹配，配合 resumeAfter 持久化 token 实现断线续传。
Change Streams 能否跨副本集所有节点监听？
答案很明确：不能。这里有个常见的误解，以为 Change Streams 能提供一个“集群级别”的统一事件总线。实际上，它的本质是基于单个 mongod 实例（通常就是主节点）的 oplog 构建的一个聚合管道。这意味着，所谓“全集群范围”的监听，并不是由 MongoDB 本身提供的，而是需要应用层自己动脑筋——要么协调多个流向不同节点的流，要么确保所有消费请求都最终路由到 primary 节点上。
如何确保 Change Stream 始终连接到 primary？
客户端驱动虽然号称能自动重连，但前提是你的“入场券”得给对。最关键的就是连接字符串。如果里面缺少了完整的副本集配置和那个至关重要的 replicaSet 参数，连接就会默默降级为单机模式。这时候调用 watch()，等着你的很可能就是 CommandNotSupportedOnView 或 FailedToSatisfyReadPreference 这类报错。
- 正确的连接字符串应该长这样：
mongodb://node1:27017,node2:27017,node3:27017/?replicaSet=rs0&readPreference=primary - 切忌图省事，只写一个节点的
host:port进行单点连接，这会让你彻底失去自动故障转移的能力。 - 另外，当使用
startAfter或resumeAfter参数进行断点续传时，提供的 token 必须源自同一个副本集的 oplog 上下文。试图跨节点恢复监听，CursorNotFound错误就会找上门。
监听整个数据库或所有集合是否可行？
到了 MongoDB 6.0，答案是肯定的，支持数据库级甚至集群级的监听。但别高兴太早，有两个硬性前提必须满足：第一，连接必须指向 primary 节点；第二，执行操作的用户得有相应的“通行证”。集群级监听需要 clusterMonitor 角色，数据库级则需要类似 dbOwner 的权限。很多“连接成功却收不到事件”的灵异事件，根源就是权限没给够，导致 Unauthorized 或者直接静默失败。
- 监听整个集群的所有变更（集群级）：
db.watch([], { fullDocument: "updateLookup" })—— 注意，第一个参数是空数组[]，而不是空对象{}，这里很容易写错。 - 监听特定数据库的所有变更（数据库级）：
db.getSiblingDB("mydb").watch() - 最后提个醒，别在
admin数据库上尝试watch()，这个系统库不支持 Change Streams。
Resumability 和网络中断后如何不丢事件？
Change Streams 的“可恢复性”并非开箱即用。这是个需要警惕的认知差：如果网络闪断后，你没有显式地保存并传递恢复令牌（resumeToken），那么重连后流会从最新的时间点开始，中间错过的变更就永久丢失了。MongoDB 服务器不会替你保存客户端的消费状态，这件事完全得靠应用自己来管。
- 最佳实践是，每处理一个变更事件，就立刻提取并持久化事件中的
change._id（它就是resumeToken）。存到本地文件，或者像 Redis 这样的轻量级存储里都行。 - 应用重启或重连后，使用
resumeAfter: sa vedToken来初始化流。相比而言，startAtOperationTime选项依赖服务器间时钟严格同步，实际生产环境中更容易出现偏差，不推荐作为首选。 - 还需要注意，
resumeToken是有“保质期”的。一旦底层的 oplog 被轮转截断，旧的 token 就会失效，并引发ResumeInProgress错误。到了这一步，通常的策略要么是降级为全量数据同步，要么就得忍痛跳过一段数据。
话说回来，在实际部署中，最容易掉进去的坑，往往是权限模型和连接模式之间的耦合问题。表面上看连接是成功了，可一调用 watch()，返回的要么是空流，要么是报错。这时候，十有八九是用户角色权限没配置完整，或者，就是连接字符串里漏掉了那个不起眼却至关重要的 replicaSet 参数。
