CQS实战：从线上事故看如何驯服查询路径上的隐藏副作用

1. 一次线上事故复盘：当查询悄悄改写了状态

1.1 事故现场与排查过程

两年前负责一个用户中心的改造项目，有一天线上告警群凌晨一点被炸开：一批用户在修改个人资料之后，数据库里只出现了大量 SELECT 语句，原以为会看到的 UPDATE 却迟迟没有出现。更诡异的是，这些 SELECT 全部指向同一个方法——getUserProfile()。负责值班的同事一检索调用链，发现该方法在返回用户资料之外，还顺手把当前登录状态和最近一次登录时间写进了 audit_login 表。

排查到这里，第一反应是“这不该发生”，因为从接口命名和调用方的理解来看，getUserProfile 就应该是个纯读取操作。跟踪真实执行路径后发现：代码深处用 ORM 的延迟写机制挂了审计拦截器，所有经过 UserProfileService 的查询，只要被判定为“用户身份相关”，就会在返回前触发一次隐式写入。于是出现了那个反直觉的现象——整个系统看起来没有任何写接口在运行，但审计表却在不断膨胀，连带导致对应的数据库行锁竞争，一批真实更新请求被阻塞。

1.2 根因：隐藏在“读取”背后的副作用

这个事故的本质，就是典型的 CQS（命令查询分离）违规。CQS 的第一条硬规矩是：一个方法要么是命令，修改系统状态；要么是查询，返回数据。二者不能兼得。getUserProfile 恰好踩中了最隐蔽的违规形态：它正常返回了用户资料，看起来行为完全正常，但在方法内部隐式修改了“最近登录时间”这个可观察状态。

为什么这类问题特别难排查？因为大多数团队的性能监控、日志检索、调用链追踪，都是以“方法名 + SQL 类型”为维度建立告警规则的。一个方法叫 getUserProfile，名字里没有半点写入暗示，监控系统自然不会把它和写操作关联起来。只有当副作用触发连锁故障——比如行锁竞争、缓存与数据库不一致、或者审计数据翻倍——你才会顺着 SQL 抽丝剥茧地找到源头。我后来统计了一下，从告警触发到定位根因花了将近两小时，其中大部分时间都浪费在排除“有没有隐藏定时任务”和“是不是 ORM 配置错乱”上。

1.3 为什么这类问题潜伏期特别长

CQS 违规的可怕之处在于它的潜伏期。一个“带副作用的查询”在低并发、小数据量阶段通常不会暴露问题，因为那个额外的写入往往量级很小，既不影响返回值，也不会立刻阻塞谁。但随着调用方增加、流量上涨，副作用会像滚雪球一样积累：审计表膨胀、锁竞争加剧、缓存命中率异常波动。更麻烦的是，它会通过并发场景引爆。比如在缓存失效的瞬间，大量请求同时进入 getUserProfile，触发多次隐式写锁，导致一部分读请求意外等待，最终表现成“系统变慢了”，而不是“某个报表不准了”。

从那次事故之后，我在团队代码评审里把 CQS 列成了第一道红线：新代码里如果出现“查询方法体内部出现任何非只读操作”，一律打回。不是为了教条，而是现实已经给了教训——驯服副作用，第一步就是别让它在查询路径里偷偷生长。

2. 命令与查询的分界线：到底怎么判才算清晰

2.1 从原始定义说起

CQS 这个概念最早是 Bertrand Meyer 在 Eiffel 语言里提出的，核心就一句话：方法要么改变状态（命令），要么返回数据（查询），不能同时做两件事。听起来简单，但真正执行起来，模糊地带比想象中多得多。

先说最清晰的形态。命令就是 createUser、updatePassword、submitOrder 这类方法，它们的特征是修改系统内部状态，通常返回值是 void 或只有一个成功/失败标识。查询就是 getUserById、findOrders、loadProfile 这类方法，它们的特征是只读数据并返回结果，不改变任何可观察状态。

但现实中的方法不会永远这么边界分明。最常见的灰色场景就是“写操作需要返回 ID”。比如 saveUser(User user)，数据库自动生成了主键 id，调用方很自然地希望方法把生成的 ID 返回出来。从字面意义上讲，这已经破坏了“命令不返回值”的教条。可完全不返回 ID，调用方还要再发一次查询才能拿到主键，性能上又实在浪费。

2.2 灰色地带：写操作返回 ID 到底可不可以

我处理这类问题的原则是：允许命令返回一个“结果对象”，但这个结果对象里只能包含与本次命令执行直接相关的标识信息，不允许返回领域数据。比如 saveUser 可以返回 SaveUserResult { userId }，用于告诉调用方这次创建的是哪个实体；但不应返回完整的 UserProfile 或把实体内全部字段都捞回来。

这么设计的原因有三层。第一，创建命令在绝大多数业务里天然就是“为了拿到新 ID 才存在的”，不返回 ID 等于让调用方多绕一圈，违背了方法设计的基本直觉。第二，把返回内容限定为“标识信息”，能避免命令和查询的职责进一步混淆——调用方如果真的需要完整实体，应当显式调用 getUserById，这一层调用关系对代码审查者和后续维护者都是透明的。第三，在面向对象领域里，如果使用聚合根或实体工厂，实体本身往往有能力生成业务 ID（比如 UUID、业务单号），此时命令方法可以完全做到不返回 ID，把生成 ID 的职责放在实体构造阶段。

所以真正的纪律不是“命令绝对不能有返回值”，而是“命令的返回值必须可控、可解释、不能悄悄附带状态变更信息”。

2.3 我总结的三问判定法

写代码时判断一个方法到底该算命令还是查询，我有一套一直沿用的三问判定法：

• 可观察状态是否改变：方法执行前后，对象本身、全局变量、数据库、文件系统、缓存、外部系统，有没有任何一项可能发生变化？如果答案是“会”，这个方法无论如何都逃不开命令的范畴。
• 多次调用的返回值是否稳定：在入参完全相同的前提下，连续调用几次，返回结果会不会因为内部状态不同而出现差异？如果会，说明这个方法并不“纯”，它隐式依赖了状态，或者隐式修改了状态。
• 调用顺序是否敏感：如果把两次调用的顺序交换，业务结果是否会不同？比如先调用 A 再调用 B 和先调用 B 再调用 A，行为或数据不一致，那 A 或 B 里至少有一个不是查询。

这套方法不追求学术上的绝对，而是为了快速在生产代码里做判断。只要三问中任何一问答出“是”，方法就必须被明确归类为命令，或者在命名、签名、代码注释里给后续维护者充分提示。

2.4 和“纯函数”的关系：别把两个概念混为一谈

纯函数的定义是“无副作用且输出仅由输入决定”，它比 CQS 的查询更严格。一个查询方法可能是纯函数，也可能只是“只读但不是纯”，比如读取系统时间、随机数、外部配置——这些不修改状态，却可能让返回值不稳定。

我在理解 CQS 时最重要的转化是：它解决的不是“如何写出数学意义上的纯函数”，而是“如何让读写责任在代码结构上可视化”。副作用不可怕，可怕的是它藏在一张“查询”面具后面。所以这篇文章的标题用了“驯服”这个词——我们不消灭所有副作用，只保证它乖乖待在命令那边，并让所有开发者一眼就能看出“这句代码在执行后到底有没有改变世界”。

3. 副作用的真实成本：不只是“改了状态”那么简单

3.1 内存副作用：改了实例变量或静态变量

副作用的第一张脸藏在内存里，主要表现是方法内部改了实例字段、静态变量、引用关系，甚至只是改变了一个布尔标志位。这类副作用最难发现，因为它不涉及数据库、不产生日志，连二进制对比都可能看不出差异。

举个例子，我之前接手过一个订单模块，里面有个 calculateTotal(order) 方法，看起来是纯计算，但它在方法末尾把计算结果赋值到了 order.lastCalculatedTotal 字段上。某个下游模块刚好依赖这个字段做二次校验，于是一模一样的订单，在不同流程里计算后会得到不同结果，原因是 calculateTotal 有没有被执行过。这就是典型的内存副作用引发的顺序依赖。

对付内存副作用的难度在于它可能藏得很深。我常用的排查手段是：代码评审时盯方法内部的赋值语句，如果一个“查询方法”里出现了 this.xxx = ... 或 static xxx = ...，哪怕看起来无害，都要打一个问号。如果方法有返回值，又同时写了实例状态，基本可以判定为 CQS 违规。

3.2 外部 I/O 副作用：数据库、缓存、日志、消息

第二张脸是外部 I/O。数据库写入、缓存写入、日志打印、消息队列发送、调用第三方接口，这些都属于外部副作用。它们在日志和监控里最容易被发现，但也最容易在不知不觉中被塞进查询路径。

日志是个很好的例子。几乎每个团队都曾有过“在查询方法里打一行 info 日志”的习惯。单看一行日志没有任何问题，但高流量场景下，日志本身就是 I/O，会造成文件锁竞争、磁盘占用和性能波动。更危险的是日志写入失败导致的业务异常——不少框架的同步日志组件在磁盘满或权限异常时会抛出异常，一个原本只读的查询方法瞬间就变成了故障源。

缓存的场景更微妙。很多开发者认为“查询时更新一下缓存命中计数”是无害的，但如果是分布式缓存，每一次计数更新都是一次跨网络写入。当查询量达到每秒上万次，这种“无害”的副作用就会成为瓶颈。我见过一个排行榜服务，因为每次读取都更新 Redis 中的点击统计，导致 Redis CPU 被打满，最终整个服务级联超时。

3.3 时间相关副作用：随机数、时间戳与调用计数

第三张脸是最容易被新手忽略的，我把它叫“时间相关副作用”。它不是修改了外部状态，而是让方法的行为依赖当前时间、随机数、调用次数等动态因素。表面看方法没有写任何东西，但由于它返回的值在不同时刻不同，调用方很容易做出错误假设。

一个典型例子是 getDiscount()。假设它根据当前时间的优惠活动配置计算折扣，返回值随时间变化，这本身可能没问题，但如果方法内部还悄悄记录了一份“计算次数计数”，并把计数作为下次计算折扣的权重，问题就来了：同一用户连续调用两次，返回的折扣率居然不同。从 CQS 的角度看，这个方法需要重新设计——折扣活动本身是配置，它应该通过查询获取；而“记录计算次数”是一个命令行为，应该显式抽出。

判断时间相关副作用的标准就一句话：同一个入参，在业务意义上等价的两次调用，是否必须得到完全相同的结果？如果“必须”但从代码里得不到保证，说明副作用已经混进去了，必须拆开。

4. 落地实操：把一个查询方法拆成“安全的读取”

4.1 命名和签名层面先做出强约束

CQS 真正落地靠的不是理论，而是编码规范。我实践中效果最好的第一条，就是从命名和签名上强制区分。命令方法用动词开头，比如 createUser、updatePassword、deleteOrder；查询方法用 get、find、load、list 这类明确表示读取的词开头。签名上也做约定：命令方法的返回值要么是 void，要么是一个明确的“结果信息”对象，里面不裹挟业务数据；查询方法不接收 Cmd 或 Command 类型的参数，避免调用者产生“这个方法会写东西”的误解。

有人会说这套约定太表面，命名可以骗人。但实际上，约定最大的价值不在于防止故意欺骗，而在于给代码评审提供一个“质疑入口”。当评审者看到一个方法叫 getUserProfile 但签名里返回了一个 UpdateResult，他就有理由追问“读操作为什么返回更新结果”。约束越清晰，异常就越显眼。

4.2 自动生成 ID 的拆法：一个可复制的案例

很多团队卡在“保存用户返回自增 ID”这一步。下面这段代码是典型违规：

csharp复制public long SaveUser(User user)
{
    // 写入数据库
    db.Insert(user);
    // 返回自增主键（副作用：写 + 读同时发生）
    return user.Id;
}

按 CQS 的严格定义，这个方法既改了状态又返回了数据。我的处理方式是先想办法让 ID 在命令之前就存在。现在主流数据库都支持 UUID 或应用层生成 ID，比如用雪花算法或 UUID 字符串，在调用命令前就把 ID 赋给实体，再传进 SaveUser，方法内部只负责落库，不返回任何值：

csharp复制public User CreateUser(CreateUserCommand command)
{
    var user = new User(command.UserId, command.Name);
    db.Insert(user);
    return user; // 注意：这里返回的是实体，但它由实体构造器内部生成 ID，不依赖数据库返回
}

如果项目确实只能用自增主键，我退而求其次的方案是把“生成 ID”的逻辑保留在命令内部，用领域事件发布出去，调用方订阅事件后自行处理 ID，而不是通过返回值拿。这套方案虽然绕，但能保证命令方法不返回业务数据。

4.3 事务边界到底该放在哪里

差的事务设计是“查询方法里包了一个事务”，因为事务本质上是对状态变更的保护和协调。正确的做法是事务只圈住命令方法，查询方法永远裸读，不加事务。如果查询需要保证一致性，你应该去考虑读副本、快照隔离或者合适的隔离级别，而不是给查询包一层可写事务。

事务的边界还得覆盖“命令内部的所有副作用”。比如创建订单时，既要写订单表，又要写库存表，还要发消息通知仓库，这些动作如果分别散在不同方法里，每个方法自己开一个事务，就容易出现部分成功部分失败的局面。我把事务收敛在命令方法这一层，让命令编排所有外部副作用，查询方法则完全不参与事务协调。这样排查问题时，只需要沿着命令方法的调用链清除副作用，查询路径永远是干净的。

4.4 查询方法的“可重入性”检查

查询还有一个容易被忽略的工程属性：可重入性。因为查询方法不应该修改状态，它应当可以安全地并发调用、重复调用，而不受上一次调用结果的影响。我在代码审查时经常做一个“双重调用测试”：把某个查询方法在同一个请求里连续调用两次，观察结果是否完全一致、性能是否出现明显变化。如果第一次调用和第二次调用之间存在“热数据”和“冷数据”的差异，或者第二次调用明显变快，往往说明方法内部偷偷改写了缓存或某个标志位，需要进一步检查。

实际上，可重入性是我认为 CQS 最有价值的工程收益。当一个查询方法完全可重入时，你可以放心地对它做缓存、做并发、做预取，不用担心状态互相干扰。这比“职责分离”这种抽象说法实用得多。

5. 反模式现场：五个常见违规例子及改法

5.1 GetOrCreate：可能是最常见的读改不分

GetOrCreateUser 这种方法是反模式重灾区。从调用方视角看，它是一个“获取用户”的查询；但实际上它内部会判断用户是否存在，不存在就插入一条记录。由于方法名叫 Get 开头，调用链追踪时很容易被当作只读操作分析，极其具有迷惑性。

改法不是把方法改名成 CreateOrGetUser 就行，而是要区分场景。如果调用方在业务上“必须保证用户存在”，那方法本质上就是一个幂等命令，返回值可以是用户 ID，但必须命名为 EnsureUserExists 或 CreateUserIfNotExists，并在注释里明确说明“可能触发写入”。如果业务语义是“用户应该存在，不存在说明数据有问题”，那就应该直接 GetUser，查不到就抛业务异常，而不是擅自插入数据。

5.2 查询方法里“顺便”写审计日志

前面事故案例里，getUserProfile 就是典型的“顺便”写日志。很多团队为了省事，会把“访问记录”“登录时间”“埋点统计”直接挂到查询方法里，因为这样调用方不用额外写一行代码。

我的建议是：审计行为必须独立成命令方法。你可以用一个 AuditService.Accessed(profileId) 方法，在调用链的入口处显式调用，或者通过 AOP 拦截器统一处理。这里的关键不是不能做审计，而是审计不能藏在“查询”方法的名字底下，否则排查问题时你会产生直接误判。AOP 拦截器虽然也需要在配置里显式声明，但至少它不属于查询方法的代码体。

5.3 返回“剩余库存”却把库存扣了

这个反模式常见于商品域。某个 GetRemainingStock(productId) 方法，发现库存不足 10 件时，会直接生成一条补货预警记录。问题在于，调用这个方法的入口很多：商品详情页、购物车校验、结算页，都会触发写操作。补货预警是业务事件，它应当由下单命令触发，而不是由查询库存的方法自身触发。

改法很简单：库存查询方法只返回库存数字，补货预警的逻辑收敛到订单确认或后台定时任务里。如果确实需要“查询的同时判断是否预警”，也应拆成两个步骤：先查询，再显式调用 RaiseLowStockAlertIfNeeded 命令。

5.4 缓存命中率统计：查询路径上的“隐蔽写”

任何一个没有经过 CQS 约束的查询方法，都很容易被后续需求者添加“统计代码”。比如在 GetProductInfo 里加一行 cacheClient.Incr("product_hit_" + id)，理由是“我们要统计商品详情页的缓存命中率”。这个方法在业务上依然是查询，但它已经产生了外部 I/O 副作用——每次读取都会触发一个 Redis 计数请求。当流量上来后，计数请求本身可能比业务查询还频繁。

我的处理方式是把可观测性副作用的“写入”也视为命令。同性能参数统计，用一种专门的异步采样写入，不要同步地塞在查询方法里阻塞主流程；要么就由监控组件在代理层完成，和业务代码彻底解耦。

5.5 队列里“消费即删除”的读操作

消息队列、Session、一次性 Token 这类结构天然带有“取出即变更”的语义，比如 queue.Dequeue() 或 token.Consume()。从命名上看，它们很像查询，但它们内部会把数据标记为已消费或者彻底删除，是实打实的命令。

处理这类情况，我遵循的原则是“命名里面必须写出消费动作”。普通队列取出一条消息但保留原件的操作用 Peek，取走且只允许一次的操作就用 Consume、Take、Dequeue 这类词，让调用者明确知道这个操作改变状态。接口文档和注释里也要标明可重入性——Peek 可以安全调用多次，Consume 绝对不行。

6. CQS 不是 CQRS：别再被名字误导

6.1 一个管方法，一个管架构

把 CQS 和 CQRS（Command Query Responsibility Segregation）混为一谈是我见过最多的问题，包括一些很资深的开发者也经常在技术方案里把两者当成一回事。实际上，CQS 是方法级别、类级别的一种职责约束，它解决的是“一个方法是否兼读兼写”的问题；CQRS 则是系统架构级别的读写分离，它把整个系统的模型拆成独立的命令模型和查询模型，两者甚至可以使用不同的数据库、不同的存储引擎、不同的部署单元。

我在后面谈“什么时候值得上 CQRS”时会说清楚，两者之间没有强制依赖。你可以是一个把 CQS 贯彻得很好的单体服务，却完全没有用 CQRS；你也可以实现一个不严格方法级约束的 CQRS 架构，命令和查询在服务层已经分得足够干净，方法内部有一点返回 ID 之类的不那么“纯”也无伤大雅。

6.2 从 CQS 进化到 CQRS 的触发信号

很多资深开发者建议“系统复杂了再上 CQRS”，但“复杂”这个词太模糊。我把可用的触发信号列出来，满足两条以上再考虑重构：

• 读流量和写流量的量级差异极大，同一份数据上，读的 QPS 是写的十倍以上，且峰值时段读写并发互相拖累。
• 领域建模过程中，查出来的数据形态和写入时需要的聚合形态严重不对等，比如写模型需要用户、订单、地址、支付状态合在一起反转，而查询需要比较扁平的 DTO。
• 系统需要支持复杂的统计报表，而这些报表无法通过已有查询接口以可接受延迟获得，必须为查询建立专门的投影表或物化视图。
• 多团队并行开发时，读写模型由不同团队负责，需要清晰的系统边界和独立的交付节奏。

但我不建议小项目直接上 CQRS，甚至不建议中等规模项目一上来就做完整的事件溯源式 CQRS。它的代价是最终一致性、重复查询模型、事件总线等一堆额外复杂度，如果没有明确的触发条件，几乎必然出现“投入产出严重倒挂”。

6.3 很多人“假装在实践 CQRS”

我在代码库里见过太多挂着 CQRS 之名、行单体 CRUD 之实的项目：写服务跑着 JPA/Hibernate，读服务也连着同一个数据库，两个模型之间除了包名不同，没有本质区别。这种情况下 CQRS 不但没有带来收益，反而让代码翻倍、定位链路变长、联调成本上升。

如果你真想践行 CQRS 思想，哪怕不引入事件溯源，至少要把读模型和写模型的表结构区分开。读模型可以做成对查询友好的宽表、物化视图，写模型保留规范化表结构；数据同步用异步消息或定时任务完成，允许读模型短时落后于写模型。这个状态下的“CQRS”才算有效降级版。而如果你连读模型表都不打算独立，那你其实还在 CQS 的范畴里，不要叫它 CQRS。

7. 我主动打破 CQS 的几个场景

7.1 幂等命令里的“返回已存数据”

即便是把 CQS 当成铁律的我，也会在幂等命令场景主动放松约束。比如分布式系统里常见的外卖平台“重复下单防重”：调用方可能因为网络重试发来同一个 OrderNo，此时命令如果发现订单已存在，直接返回已有订单信息和成功状态，不再二次创建。这看起来像查询，因为它在读数据并返回；但它本质上是幂等命令，因为它可能在某次调用中创建数据。

这种场景我不想硬拆成两步——先查订单、不存在再创建——因为并发下两步会引入竞态，重复创建的风险比违反纯字面的 CQS 更大。我的处理是：函数命名上明确写成 CreateOrderIfNotExists 或 EnsureOrderCreated，并在注释里标出幂等语义。职责上它仍是命令，返回值只是它附带交付的信息。

7.2 查询路径中的“必须”性能优化

极端性能场景下我也会打破 CQS，典型是高频热点数据的本地缓存更新。假设某个配置查询方法从本地内存缓存中读数据，缓存 miss 时才选择去数据库加载并写入本地缓存。这里“查询方法写缓存”确实产生了副作用，但如果不这么做，要么需要调用方预先执行一步“预加载”命令，要么每次读取都走远程，都不现实。

我的底线是：这种副作用仅限于基础设施层，不涉及业务逻辑状态，且必须通过合适的命名（比如 GetConfigWithCacheRefresh）向调用者显式暴露。同时它会尽可能保证方法返回值不受副作用影响，即使缓存写入失败，也要 catch 住异常、降级为正常查询，不让副作用反过来污染主逻辑。

7.3 领域事件发布：可以靠近命令，但别藏进查询

领域事件发布是另一个需要小心对待的灰色地带。在 DDD 建模里，事件发布往往发生在聚合根状态变更之后。一些团队为了减少事务管理的复杂度，会在查询方法里判断“如果这个聚合根刚刚被加载过，就发布一个事件”。这绝对是灾难级设计——事件发布应当是命令之后的结果，而不是某个查询在调用过程中触发的随机行为。

我在不变的权利范围内保留了两条宽松策略：第一，领域事件如果确实没法从命令里明确发出，可以把它放进仓库层提交后的回调里，但要确保它的事件源是某个写操作；第二，绝不把事件发布逻辑附着在“查询类”方法上。CQS 允许你在命令里做很多编排，但唯一不允许的就是让查询方法悄悄成为事件发源地。

7.4 一句话总结我的取舍标准

CQS 的价值从来不在于“守规矩”本身，而在于让系统里所有状态变更都看得见、找得到、可控可回滚。所以我打破它的标准也很简单：这个破坏是不是只是在“基础设施层”产生不影响业务结果的副效应？这个破坏有没有在命名和注释里被显式标记？如果两个答案都是“是”，那我愿意妥协；如果有一个答案是“否”，那这个副作用就应该回到命令那边去。

我在实际项目里越来越发现，团队的代码质量和 CQS 的执行程度不见得线性相关，但团队的“可调试性”几乎总是和 CQS 的执行质量成正比。当你能拍着胸脯说“所有查询方法都可以在任意线程、任意时机、无限次地安全调用”，排障时的脑内排除范围会瞬间缩小一大半。让命令做命令，让查询做查询，剩下的问题就是让每个副作用都被看见、被跟踪、被驯服。