ERP 后端 / 系统学习与工程实践

从代码出发,
建立后端全景。

写给前端基础扎实、正在走向 Java ERP 后端的你。先理解机制,再辨认项目里的取舍;从正确性、性能、安全,一直走到故障恢复。

7学习模块
78编号章节
27.2万汉字正文及配套说明
源码事实、教学方案与实验结果分开呈现。原 Markdown 全部保留;本地源码链接仅作为证据提示,不随线上阅读站公开。
学习阶段 01

Java与工程基础

从语言、建模与规范建立后端思维

原始文档 · backend-foundations-course/README.md

Java ERP 后端基础:从前端经验到可验证的工程能力

面向前端基础扎实、准备承担 Java ERP 后端开发的读者。本课程先解决语言、模型、权限与评审能力,再衔接已有数据库和 Spring 课程。每章包含机制解释、真实源码定位、教学设计、故障推演和练习答案。

完整目录

章节 学完应能交付的东西
00 全目录技术栈证据与课程能力地图 区分 POM 声明、源码路径、运行证据的技术地图
01 Java语言集合泛型异常资源管理与前端迁移 有类型边界、异常语义和资源所有权的 Java 方法
02 Java工程分层领域建模金额时间编码规范 可测试的领域规则、金额和时间契约
03 数据库访问安全权限注入凭据与迁移规范 授权数据流、参数化 SQL、迁移和凭据生命周期方案
04 项目反例与安全编码评审 逐条包含证据、成立条件、改进与验证的风险评审
审阅与知识缺口 旧课已覆盖、薄弱处、新增范围及验证边界
第二轮查缺补漏与学习路线 按实际开发故障补课,区分已验证与待验证
图解导读 用六张图识别调用链、事务、消息与任务恢复边界
外部输入、文件与网络安全深化 URL、文件上传、直传签名与回调的授权和资源限制

与其他课程配合

先按 00—04 顺序阅读,再按问题进入专题:

统一彩色阅读站收录这些模块,原始Markdown保留。先掌握编号章节的基础,再结合深化篇复查自己的开发方案。

证据与实验约定

整理日期:2026-11-11。源码链接使用相对路径和 #L行号,行号对应当前工作区快照。12 个顶级业务 Maven 项目的根 POM 都已读取结构化声明;Java/XML 只抽样阅读,不是全面代码审计。构建插件版本、BOM 管理版本、实际运行版本分开表述。

正文代码除明确标为“源码摘录”外,均为独立教学片段;省略的领域类型不会被伪装成完整可部署工程。Java 语法以 Java 8 为基线,历史依赖用于解释现有工程,不构成新项目版本推荐。未启动业务应用、未连接业务服务、未运行业务构建或集成测试,未读取业务秘密配置文件。所有容量和故障时间线都是注明条件的推演。

学习验收以解释能力为准:说出规则为何成立,构造会失败的输入,写出实际可观察的断言,指出测试仍不能证明的范围。不要把“代码有注解”“构建成功”或“没有报错”当作最终证据。

原始文档 · backend-foundations-course/00-全目录技术栈证据与课程能力地图.md

00 全目录技术栈证据与课程能力地图

前端转后端最容易低估的变化,是一个动作不再以组件卸载或请求结束为终点。浏览器看到超时,数据库可能已经提交;页面禁用了按钮,另一个客户端仍能提交;服务对象可能在进程中存活数天,被许多请求并发使用。学习后端因此不能只背注解。你需要建立一张图:业务事实由谁保存,规则在哪一层保证,失败在哪里暴露,资源由谁释放。

本章的“全目录”限定为 /Users/try/work/admin 当前直接子目录中的后端业务 Maven 项目,共12个。教材目录和实验 POM 不计入业务项目。下面的表来自真实根 POM 结构化阅读,排除了注释节点;没有读取连接秘密配置,没有下载私有依赖,没有启动项目。普查 POM 与全面代码审计是两种工作,本课程只完成前者及少量源码抽样。

1. 先建立证据等级

把结论分成四层,会比记住一串版本号更实用。第一层是声明:POM 写了 Java 1.8、某依赖或某插件。第二层是实现:具体工厂创建了哪个对象、Mapper 拼出了什么 SQL。第三层是解析与装配:最终依赖树选了什么版本、哪些 Bean 和过滤器真的注册。第四层是运行:部署实例加载了什么、请求走了哪条路径、耗时花在哪里。本轮主要提供前两层。

例如一个 Maven 属性名叫 spring.boot.maven.plugin.version,它说明构建插件使用的版本;不能直接写成所有 Spring Boot 运行依赖都是该版本。dependencyManagement 管理依赖选择,不表示其中每个库都进入最终应用。父 POM 继承与 BOM 的 type=pom, scope=import 也不同:一个导入项即使名字包含 parent,仍不能按 XML 的父节点理解。官方机制见Maven依赖管理。

2. 12个顶级项目的声明证据

所有项目的根 POM 均声明 Java 1.8。表内“插件属性”只表示声明的构建线索;“模块”列是帮助定位的结构摘要,不是已验证部署进程清单。

顶级项目 根POM证据 结构与可确认声明
erp-admin Java属性〔本地文件〕、Boot BOM〔本地文件〕、模块〔本地文件〕 Boot BOM 2.7.3;ruoyi-admin/framework/system/biz/quartz/generator/common/modules
erp-aftersale 模块〔本地文件〕、属性〔本地文件〕、导入项〔本地文件〕 web/task/down-task、service/component/dal等;Boot插件属性2.3.3.RELEASE;私有BOM
erp-dts 属性〔本地文件〕、导入项〔本地文件〕、模块〔本地文件〕 web/facade/facade-impl及分层模块;Boot插件属性2.3.3.RELEASE;ONS声明〔本地文件〕
erp-index 模块〔本地文件〕、属性〔本地文件〕、导入项〔本地文件〕 含core与task;Boot插件属性2.3.3.RELEASE;Nacos声明〔本地文件〕
erp-item 模块〔本地文件〕、属性〔本地文件〕、导入项〔本地文件〕 web/facade-impl/task/down-task与领域分层;Boot插件属性2.3.3.RELEASE
erp-logistics-service 父项〔本地文件〕、模块〔本地文件〕、Java属性〔本地文件〕 Boot parent 2.2.1.RELEASE;common/service/web/dao/api/integration
erp-message-push 属性〔本地文件〕、模块〔本地文件〕、导入项〔本地文件〕 web/facade/facade-impl及分层模块;Boot插件属性2.3.3.RELEASE
erp-report 模块〔本地文件〕、属性〔本地文件〕、导入项〔本地文件〕 含task和facade-impl;Boot插件属性2.3.3.RELEASE
erp-report-pro 模块〔本地文件〕、属性〔本地文件〕、导入项〔本地文件〕 Boot插件属性2.3.3.RELEASE;明确有PostgreSQL驱动声明〔本地文件〕
erp-scm Java属性〔本地文件〕、模块〔本地文件〕、导入项〔本地文件〕 client/adapter/app/domain/infrastructure/start;Dubbo starter声明〔本地文件〕
erp-sdk 模块〔本地文件〕、属性〔本地文件〕、导入项〔本地文件〕 erp-item-transform;Boot插件属性2.3.3.RELEASE不证明SDK是独立Web服务
kdzs-erp-rds 模块〔本地文件〕、Java属性〔本地文件〕、Boot BOM〔本地文件〕 Boot BOM 2.2.1.RELEASE;consumer/ons/task/task-slave/dubbo等入口模块

表中私有导入项大多为 dz-starter-parent:kdzs-erp-1.0.0-SNAPSHOT,SDK导入版本为 1.0.4-SNAPSHOT。本轮不解析它们的内容,也就不能替它们承诺最终 Spring、MyBatis、数据库驱动或日志实现版本。SNAPSHOT还提醒我们:源码文本相同不必然意味着不同时间构建出的依赖字节完全相同。

在明确可见的声明中,erp-admin 有Dubbo 2.6.2〔本地文件〕、Elasticsearch客户端7.1.0〔本地文件〕、MyBatis-Plus 3.5.5〔本地文件〕;rds有ONS客户端〔本地文件〕。这解释为什么教材要覆盖 RPC、搜索与消息,但仍不能证明对应服务当前在线,更不能由客户端版本倒推出数据库或搜索集群版本。

3. 从依赖表走到一条真实路径

以后台用户查询为例,SysUserServiceImpl第73行〔本地文件〕的方法有 @DataScope,内部调用 Mapper。DataScopeAspect第58行〔本地文件〕先清除原参数中的范围片段,再按登录身份生成范围;Mapper第99行〔本地文件〕消费这个片段。下面是根据这三处代码整理的条件时序,不是抓到的线上调用日志:

调用经过Spring代理
  → DataScope切面清理旧范围
  → 根据当前身份和角色生成范围
  → Service调用Mapper
  → Mapper把值参数绑定,把可信范围片段加入SQL
  → 数据库返回范围内的数据

这个时序同时需要语言、框架和数据库知识。你要理解方法调用与对象类型,理解代理何时工作,还要理解绑定值和拼接语法的区别。若只会写注解,就可能在新增无注解入口时遗漏授权;若只会 SQL,就可能误以为范围条件总会自动存在。03、04章会继续分析已存在的另一条方法形态,但不会把未追完的外部可达性说成已证实越权。

另一例是MyBatisConfig第126行〔本地文件〕直接创建 SqlSessionFactoryBean。它告诉我们应该检查实际工厂与插件链,而不是因为 POM 声明 Plus,就宣布所有 Plus 拦截器生效。课程选择源码作为入口,目的正是让你能提出下一步需要什么证据。

4. 把学习目标变成能力地图

能力层 需要回答的问题 本课程与后续入口
语言与资源 对象由谁共享?失败后谁关闭资源? 01章
业务模型 哪些状态允许转换?金额在哪一步舍入? 02章
数据安全 身份谁决定?动态SQL谁可以生成? 03章
评审与反证 风险何时成立?什么测试能推翻假设? 04章
数据库与框架 约束、事务、索引、代理如何协作? 数据库、Spring
跨进程正确性 超时、重复、乱序和提交未知如何处理? 分布式
资源与恢复 排队何时失控?发布失败如何恢复? 高并发、运维

学习顺序可以围绕同一个库存预占用例。先用普通 Java 表达数量必须为正、库存不能负;再用数据库条件更新解决两个请求同时扣减;用 Spring组织事务;接入消息后讨论重复投递;流量变大后限制待处理任务;最后练习中断发布与恢复。这样每个新知识都解决已有设计中的一个具体缺口,不会变成彼此孤立的名词。

前端经验仍有价值。你熟悉的组件输入契约可迁移到命令 DTO,状态机可迁移到订单生命周期,取消请求可帮助理解超时预算。但不能直接照搬假设:前端类型校验不能约束恶意客户端,单页面状态不能协调多个进程,Promise失败也不能证明远端副作用没有发生。

阅读新项目时,可以先选择一个很小的用例,例如修改某条商品备注,而不是从公共工具包顺序读到最后。画出入口、授权、用例、存储和响应五个节点,然后给每个节点标注输入可信度、可能失败和资源占用。若同一用例还可从任务或RPC进入,应另画入口但复用核心规则。这会暴露规则到底属于业务层,还是只写在某个HTTP方法里。等这条链可以解释清楚,再扩展到事务和异步,你得到的是可以不断验证的地图。

还要记录依赖方向与运行方向的区别。源码中应用服务可能依赖领域接口,运行时却调用基础设施实现;这不矛盾,前者讨论编译耦合,后者讨论对象协作。Maven模块也不等于独立部署单元,一个启动模块可能把多个模块一起打包。反过来,同一领域模块可能被Web、任务和RPC入口共享,所以修改公共类型需要考虑多个消费者。没有打包和部署证据时,把一个模块直接数成一个微服务,会让容量、发布顺序和故障范围的推断全部偏离实际。

5. 故障推演:依赖存在为什么仍然失败

假设新同事看到 Plus 依赖,就移除手写 SQL 中的租户条件,理由是“插件会加”。若实际工厂未安装租户插件,请求仍执行合法 SQL,却扩大结果范围。这类失败可能没有异常、平均延迟也正常,只有资源隔离断言能暴露。正确调查顺序是先检查最终 SQL 与参数来源,再确认工厂和拦截器,不应先猜数据库坏了。

另一种失败是构建显示成功便认为测试通过。erp-item第82行〔本地文件〕声明 maven.test.skip=true,rds第29行〔本地文件〕声明 skipTests=true。它们是需要核验的跳过线索,真实命令还可能覆盖属性。评审时应查看测试报告中的执行数、失败数、跳过数及命令,而不是只截最后一行绿色输出。本轮没有执行这些构建。

性能也要保持同样的证据纪律。某段日志间隔很长只给出调查区间,不能直接证明 Redis、类扫描或某个初始化方法是阻塞点。只有在同一运行中将时间线、线程栈和外部调用关联起来,才能逐渐收窄因果。这种方法能防止把合理猜测写成错误优化方案。

6. 练习与参考答案

练习一: erp-sdk 有 Boot 插件属性,能否断言它监听 HTTP?答案:不能。还需应用入口、打包方式、运行配置和进程证据;当前根 POM 只证明声明与模块。能正确说出未知,比猜一个端口更有价值。

练习二: 根据表格,哪些 Boot 版本可直接在根声明中确定?答案:admin的BOM为2.7.3,logistics的parent为2.2.1.RELEASE,rds的BOM为2.2.1.RELEASE。其余所列2.3.3.RELEASE多为插件属性,不能混称运行时统一版本;就连明确BOM的项目,局部覆盖和部署结果仍需另查。

练习三: 为库存预占写三项验收而不是三种工具名。答案:并发后库存不负;同请求重复到达只产生一次业务扣减;租户甲不能读取或修改租户乙库存。分别用受控并发、重放和跨租户负例验证,再记录失败时数据与响应。测试机制可复用旧课,不能把未执行方案称为已通过。

练习四: 什么才算完成技术地图?答案:每个结论都能指出证据位置和等级,每个未知都能说明下一项验证。若只能列出 Spring、Redis、Dubbo 而不能说明边界,地图尚未完成。

官方参考与继续阅读

Maven POM参考用于核对父项、模块和构建语义;Maven依赖机制用于解释BOM与传递依赖;MyBatis映射文档用于核对参数处理。项目名单和行号来自当前源码,官方文档不能替代部署验证。

原始文档 · backend-foundations-course/01-Java语言集合泛型异常资源管理与前端迁移.md

01 Java语言、集合、泛型、异常、资源管理与前端迁移

Java 与 TypeScript 都能写类、接口、泛型和异步流程,但代码外形相似并不代表运行机制相同。Java 泛型大部分也经过擦除,却有 JVM 的类、字节码和运行时类型检查;Java 服务中的普通方法可能在多个线程上同时执行。学习时先建立对象、类型、失败与资源四个概念,再去看 Spring,能避免把语言问题误诊为框架问题。本章片段按 Java 8 编写,除注明的源码摘录外均为教学设计。

1. 值、引用和类型:从表单对象到长期存活的服务

Java 总是按值传参。基本类型复制数值,对象变量复制引用值。方法里修改对象字段,调用方能观察到;给参数变量重新赋值,不会让调用方变量自动指向新对象。final List<Order> 只禁止引用改指向,不禁止列表增删,也不禁止 Order 改字段。这与 JavaScript 的 const 有相似处,但后端共享服务里的可变字段还会被多个请求同时访问。

long 与 Long 也不是随意互换:前者不能表达缺少值,后者可以为 null;自动拆箱会在 null 处抛异常。外部订单号未提供不能默认零,零也不能自动解释成“查询全部”。比较包装对象用 Objects.equals 或明确拆箱,不用 == 判断业务相等,否则某些缓存范围内的样本可能碰巧通过,换一个数字就失败。字符串业务比较同理。

Java 的继承和接口以声明关系为主,不像 TypeScript 常用的结构兼容。两个类都有 getId(),并不自动实现同一个接口。接口要表达调用方需要的协议,而不是为了让所有对象长得一样。例如 PriceSource 应承诺“按币种返回报价或明确失败”,而不是暴露供应商 SDK 的全部方法。

后端对象的寿命需要显式判断。DTO通常属于一次请求;无状态 Service可被共享;连接和流拥有短期借用周期。把“当前租户”放进单例字段,会让请求甲刚设置的值被请求乙覆盖。即便方法内每一行都合法,跨请求组合仍错误。这个问题来自共享状态,不是加一个 Java 类型注解就能解决。

2. 集合不仅存数据,还定义相等、顺序和成本

List 表达有序序列并允许重复;Set 表达去重;Map 表达键到值的关联。选择依据是业务语义。例如订单明细不能随意按 SKU 去重,因为同 SKU 的不同成交价或促销批次可能是不同明细。批量查库存可以先按租户和 SKU 归并数量,但归并规则必须先被业务批准。

ArrayList 的按下标访问很直接,连续内存中的引用也适合遍历;在开头反复插入则需要搬动元素。HashMap 在哈希分布合理时适合平均常数级查找,但它不承诺业务排序;需要稳定输出可使用明确排序或 LinkedHashMap 的插入顺序。不要依赖一次运行中恰好稳定的遍历顺序生成签名或幂等摘要。Map官方契约还要求特别注意可变键。

一个对象作为 HashMap 键后,如果参与 equals/hashCode 的字段改变,查找会按新哈希寻找,却可能找不到原来存放位置。ERP常见键应包含租户和业务ID,并保持不可变。仅覆盖 equals、不覆盖一致的 hashCode,也会破坏哈希集合的相等契约。BigDecimal 作为键还涉及 scale,下一章会解释为何数值相等不总等于对象相等。

// 教学片段:合并同一用例中已确认可归并的SKU数量,输入已完成权限校验。
static Map<Long, Integer> mergeQuantities(List<Line> lines) {
    Map<Long, Integer> result = new LinkedHashMap<>();
    for (Line line : lines) {
        if (line == null || line.skuId() == null || line.quantity() <= 0) {
            throw new IllegalArgumentException("invalid line");
        }
        result.merge(line.skuId(), line.quantity(), Math::addExact);
    }
    return Collections.unmodifiableMap(result);
}

这里的 Line 是教学输入接口,提供 Long skuId() 与 int quantity()。addExact 让整数溢出失败,避免超大批次变成负数量。只读包装防止调用者增删映射,但不是通用的深度不可变:若 value 是可变对象,仍须防御性复制。当前值是 Integer,所以没有这个可变值问题。这个区分比笼统说“用了不可变集合就线程安全”更准确。

3. 泛型让错误提前,但不能替代边界校验

真实项目LocalCache第25行〔本地文件〕定义 LocalCache<K,V>,第117行〔本地文件〕接受 Supplier<V>。这使缓存键、返回值和加载器之间形成编译期约束。Supplier<V>可理解为延迟提供一个值的函数,但它本身没有保证只调用一次、自动重试或线程安全。

List<Refund> 不能当作 List<Object> 传入,否则接收方就可能向退款列表加入普通 Object。只读取元素的工具可用 ? extends T,接受写入的目标可用 ? super T。例如:

static <T> void appendAll(List<? extends T> source,
                          List<? super T> target) {
    for (T value : source) {
        target.add(value);
    }
}

通配符解释的是允许哪些操作,不是把列表变成只读对象。使用 raw type,例如裸 List,会把类型问题推迟到强制转换处。泛型擦除也意味着不能用 instanceof List<Order> 验证 JSON 内容,通常需要明确反序列化类型信息并逐字段校验。前端传来的字符串ID、金额、枚举必须经过协议解析;类型正确以后,还要做业务和权限判断。通配符使用规则见Oracle泛型指南。

4. Lambda、Stream和并发之间没有自动等号

Lambda 是函数行为的表达方式,Stream 是处理数据的流水线,普通 stream 不会因为写法简洁就自动异步。map 内查询数据库,仍可能每个元素执行一次 SQL;collect(toList()) 仍会保留全部输出。Java Stream 与数据库流式游标没有必然联系。

把它改成 parallelStream 也不是可靠提速方案。任务可能使用公共线程池,阻塞I/O占住线程,共享容器写入还会产生竞态。先减少重复查询、分批获取数据,再衡量是否有必要使用受控并发。函数式写法最适合表达无副作用的映射和归约,例如计算已验证明细的金额;带事务、外部调用和重试的步骤通常需要更明确的生命周期。

回看 LocalCache:源码先 getIfPresent,未命中后 supplier.get(),最后 put。每一步可独立正确,但两线程可以同时未命中并重复加载。这是“单个操作安全不推出组合协议安全”的语言级案例,不能靠把 Supplier 换成 Lambda 修复。并发回源的条件和测试见04章。

5. 异常是失败协议,不只是红色日志

受检异常要求调用方捕获或声明,RuntimeException没有同样编译要求;这不代表前者一定能恢复、后者一定是程序错误。分类应围绕用例:参数错误可以要求用户修改,冲突可以重新读取状态,依赖故障可能稍后重试,提交结果未知必须先查状态。不要把所有异常吞掉并返回空集合,否则“没有数据”和“没有查成功”无法区分。

在应用边界可以把底层异常转为业务异常,但要保留 cause 供内部诊断,对外使用稳定错误码和安全文案。真实GlobalExceptionHandler第91行〔本地文件〕直接把运行时异常 message 写入响应。如果 message 带内部细节,才形成相应泄漏风险;这不意味着每个异常消息都敏感。需要同时设计内部排查与外部契约。

中断尤其不能被当成普通可忽略错误。Threads.sleep第23行〔本地文件〕捕获 InterruptedException 后直接返回。Thread.sleep抛出该异常时会清除中断标记,因此依赖标记退出的外层循环可能继续工作。若当前层能声明异常,就继续抛出;若接口不能抛,可恢复标记并结束本层工作:

try {
    Thread.sleep(backoffMillis);
} catch (InterruptedException e) {
    Thread.currentThread().interrupt();
    return; // 教学前提:这里是本次任务的退出点
}

仅恢复标记但继续下一轮重试仍不够,调用协议必须真的停止。官方语义见Thread API。

6. GC回收内存,不替你归还连接和关闭文件

连接池、文件句柄、网络流都可能在对象变得不可达之前已造成资源压力。try-with-resources 的目的,是将资源关闭绑定到词法作用域;支持 AutoCloseable 的对象按声明逆序关闭,主异常保留,关闭异常可作为 suppressed exception附加。Oracle资源管理教程解释了这一机制。

// 教学片段:只读取调用方指定的独立练习文件。
static long countLines(Path file) throws IOException {
    long count = 0;
    try (BufferedReader reader = Files.newBufferedReader(
            file, StandardCharsets.UTF_8)) {
        while (reader.readLine() != null) {
            count++;
        }
    }
    return count;
}

这个方法拥有reader,所以负责关闭。若参数是调用方传来的流,所有权应在契约中写清,不能擅自关掉仍被上游使用的输出流。数据库也一样:池化 Connection.close常是归还连接;在 Spring事务内应让框架的集成方式管理资源,不能为追求形式上的try而提前关闭共享事务连接。

真实HttpUtils第214行〔本地文件〕打开输入流,关闭出现在成功路径末尾。若读取中抛异常,控制流会越过这些关闭语句。这是局部异常路径的资源风险证据;具体连接是否由实现最终回收仍需运行观察,不能把“可能泄漏”量化成未经测量的耗尽时间。

7. 故障推演与练习答案

设导入任务连续读文件,每遇到坏行就 catch后继续,输入流只在正常返回时关闭。坏文件比例升高后,失败任务留下更多句柄;后续正常文件也可能打不开。故障最终表现为“正常请求失败”,根因却是早先异常路径没有释放资源。改进应同时改变失败语义和关闭结构,测试不能只覆盖好文件。

练习一: final List 能否保证请求间不串数据?答案:不能。引用不变不代表内容不变,也不提供跨线程可见性和操作原子性。请求数据应保持局部,跨线程共享时需不可变快照或明确同步协议。

练习二: 给上面的归并函数传两个接近整数上限的数量,预期什么?答案:Math.addExact 抛ArithmeticException,由入口转成有界输入错误,不能得到负库存申请。还需先限制行数和单行数量,避免只在最后才发现攻击性输入。

练习三: 读取与关闭同时失败,应该只留下哪个异常?答案:try-with-resources保留读取主异常,并把关闭异常放入suppressed列表。测试用自定义AutoCloseable在close中抛异常,断言主cause和suppressed;不要依赖真实磁盘损坏来触发。

练习四: 中断后sleep工具直接返回是否算任务已取消?答案:只证明等待结束。外层可能继续执行SQL或重试;应受控安排线程进入等待、发出中断,并断言任务结束且没有后续副作用。以上是测试设计,本轮未运行业务任务。

继续学习可阅读Spring并发与上下文和数据库工具链。它们建立在本章的对象所有权与失败协议之上。

原始文档 · backend-foundations-course/02-Java工程分层领域建模金额时间编码规范.md

02 Java工程分层、领域建模、金额、时间与编码规范

页面按用户此刻需要的信息组织对象,后端按长期有效的业务事实和规则组织模型。订单详情页把商品、收款、物流一起显示,并不意味着它们应该共用一个可任意修改的大对象。本章用库存与核销价贯穿分层设计:先讲什么必须正确,再讲哪个类负责它,最后把金额、时间和编码写成可测试契约。代码是Java 8教学片段,不是对业务仓库的修改。

1. 分层的价值是限制变化传播

Controller负责把HTTP输入转换为用例,应用服务负责协调授权、事务和外部步骤,领域对象表达规则,持久层负责存取和条件更新,integration处理外部平台差异。如果某平台把“取消”改成另一个状态码,最好只改变适配层;如果库存不变量改变,应进入领域规则和存储约束,不应散落在多个Controller。

这不是强制所有项目使用同样的包名。erp-item根POM第16行〔本地文件〕列出service、component、dal等模块;erp-scm第35行〔本地文件〕列出adapter、app、domain、infrastructure等另一种结构。模块名称只能提示设计意图,实际依赖和责任仍需读源码,不能凭目录宣称全项目符合某种架构。

一个具体入口是ScmSkuGateway第12行〔本地文件〕。它位于domain模块,定义批量插入、按参与方和平台查SKU、设置核销价等接口。第30行的参数同时包含供应商、分销商、店铺、平台、SKU与价格,这提示模型中存在多种身份,不能把所有Long都叫userId。这个接口证据不证明全部实现都隔离良好;它只是讨论“领域需要什么能力”的真实起点。

2. DTO、实体和值对象分别保护什么

请求DTO描述允许客户端表达的意图,例如“对某SKU预占三件”;持久DO对应表列;响应DTO描述允许公开的视图。它们结构接近时也不宜直接互用。数据库实体可能有审核人、删除标记、租户与内部状态,若全部变成请求可写字段,客户端就获得了修改内部规则的入口。

实体有持续身份,例如订单改备注后仍是同一订单;值对象由值决定含义,例如明确币种和数额的Money。订单金额不能是脱离币种的裸数,SKU身份也可能需要平台和店铺共同确定。构造时验证值对象,可以让后续业务代码在更强的前提下运行,但不能替代“当前操作者是否有权修改”的授权检查。

应用服务适合接收语义完整的命令:ReserveCommand携带sku、quantity、幂等键,可信租户与操作者由认证上下文提供。创建命令时拒绝非法格式;执行用例时检查状态和权限;写入时再由数据库条件保证并发下不变量。这个顺序将不同问题分开处理,而不是用一个万能validate方法隐藏全部规则。

// 教学接口:数据库实现必须把检查与扣减放进同一个原子更新。
interface StockRepository {
    int reserve(long tenantId, long skuId, int quantity, long version);
}

// 教学用例片段:未展示幂等记录和事务装配。
void reserve(TrustedActor actor, ReserveCommand command) {
    if (command.quantity() <= 0) {
        throw new IllegalArgumentException("quantity must be positive");
    }
    policy.requireCanReserve(actor, command.skuId());
    int changed = stocks.reserve(actor.tenantId(), command.skuId(),
                                 command.quantity(), command.version());
    if (changed != 1) {
        throw new StockConflictException();
    }
}

TrustedActor、ReserveCommand、policy和stocks是教学协作对象。这里刻意把“影响一行”作为协议:如果返回零,可能版本冲突、库存不足或资源不可见,不能默认成功。若要向用户区分原因,可以在授权范围内重新读取,但重读只是诊断,不再充当首次写入的并发保证。

3. 金额正确性取决于整条数据流

Java BigDecimal以十进制数值和scale表达金额,能进行明确舍入,但不能修复输入前已经发生的精度损失。new BigDecimal(0.1)接收的是已经表示成二进制浮点的值;从协议中的十进制字符串构造,才能保留约定的十进制输入。最终还要匹配数据库DECIMAL范围与API输出格式。BigDecimal API是这些行为的官方依据。

真实Arith.add第28行〔本地文件〕接受double,用Double.toString构造BigDecimal,算完再返回double。它可改善某些常见浮点运算的展示效果,但不能提供端到端金额精确契约。如果调用者已经把超大金额或小数算坏了,内部转成字符串不会重建原始输入。因此不能仅根据“精确运算”的注释就决定把它用于记账。

// 教学规则:本练习仅处理两位小数的同币种金额。
static BigDecimal parseAmount(String text) {
    if (text == null || !text.matches("[0-9]{1,12}(\\.[0-9]{1,2})?")) {
        throw new IllegalArgumentException("invalid amount");
    }
    return new BigDecimal(text).setScale(2, RoundingMode.UNNECESSARY);
}

static BigDecimal lineTotal(BigDecimal unitPrice, int quantity) {
    if (quantity <= 0) throw new IllegalArgumentException("invalid quantity");
    return unitPrice.multiply(BigDecimal.valueOf(quantity));
}

这个练习故意拒绝指数记法、负数和多余小数,并不宣称所有币种都只有两位。退款可使用不同命令表达方向,避免同一接口既以负金额又以退款标记表达相同意图。格式规则必须在产品契约中写明,不能靠前端输入控件代替后端验证。

比较金额时还要区分数值相等和对象相等:BigDecimal的equals考虑scale,1.0与1.00的compareTo为零,但equals不同。若Money用于集合键,应先按币种约定归一化scale,再保持equals/hashCode一致,不能只修改equals。金额序列化也应明确字符串或数值协议,不让浏览器无意参与精确账务计算。

4. 舍入与分摊是业务规则,不能留给工具类猜

三行商品各优惠0.005元,逐行按两位四舍五入得到0.01,总计0.03;先汇总0.015再舍入得到0.02。两种结果都能遵守某种计算规则,但不能同时当作同一张单据的口径。应规定在哪一级舍入、税额和优惠谁先计算、头明细如何对账。

将1元平均分给三行,可以先按最小货币单位计算100分,得到33、33、34分,并用稳定的明细顺序分配余数。若分配顺序依赖HashMap遍历,同样输入可能把余数落到不同商品,退款时便无法复现。需要保留原始金额、算法版本和分配结果,退款原则上引用原交易快照,而非用今天的商品价格重算。

另一处源码Arith.div第81行〔本地文件〕先判断被除数为零便返回零,再执行除法。因此输入0/0会走零返回。这是当前方法能直接推导的行为;是否业务上出现该输入并造成错误没有验证。核销率的分母为零应定义为“不可计算”或特定规则,而不是让一个工具类悄悄决定成零。

5. 时间先分语义,再选择Java类型

发生在时间线上的事件可用Instant;账期、生日或营业日用LocalDate;没有时区的墙上时间可用LocalDateTime,但它不能独自代表全球唯一时刻。ZoneId描述区域规则,Offset只描述某次偏移。跨境ERP不能把“当前服务器默认时区”当成所有商家的业务时区。LocalDate官方说明明确它不携带时区。

真实DateUtils.toDate第185行〔本地文件〕用 ZoneId.systemDefault() 转换LocalDateTime。这是隐式依赖运行环境的证据。如果机器默认时区改变,同一输入可能变成不同Instant;当前部署是否统一时区,本轮没有检查。可改进的设计是由用例显式传入业务ZoneId,并把当前时钟作为Clock注入,让测试不依赖运行当天。

// 教学片段:业务自然日对应的半开时间区间。
ZoneId businessZone = ZoneId.of("Asia/Shanghai");
LocalDate day = LocalDate.of(2026, 11, 11);
Instant from = day.atStartOfDay(businessZone).toInstant();
Instant until = day.plusDays(1).atStartOfDay(businessZone).toInstant();
// SQL契约:created_at >= from AND created_at < until

用下一个自然日的起点,而不是直接加固定24小时,可适应某些时区的夏令时切换。半开区间避免依赖数据库毫秒或微秒精度去猜当天最后一刻。存储选DATETIME还是TIMESTAMP、驱动怎样转换,要继续查数据库课程;光改Java类型不足以消除跨层时差。

6. 编码规范应该减少歧义

方法名写用例,如reserve、confirm、cancel;参数名携带单位与身份,如amountFen、timeoutMillis、supplierUserId。不要让一个price有时为元、有时为分。Long ID传浏览器应按契约用字符串,避免超过安全整数范围后被改写;外部SKU编码即使全是数字,也可能含前导零,不应随意转数值。

字符编码要在字节边界显式指定UTF-8,而不是先默认解码再尝试“乱码修复”。字符数量、UTF-16长度和UTF-8字节长度不是同一限制;数据库字段限制、请求大小与签名字节应分别验证。签名场景还需明确字段顺序、空值和Unicode规范化策略,不能由两端各自猜测。

空值也要建模。PATCH中未传字段表示不修改,传null可能表示清空,传空字符串可能是有效值或非法输入。一个普通可空字段无法同时无歧义表达三种状态,应使用存在标记、专门命令或明确JSON解析策略。未知枚举值应拒绝或进入明确兼容路径,不能自动变成“已审核”。

7. 故障推演与练习答案

设两个请求都先读取库存5,各自预占4,再用普通覆盖写入1。两个请求都成功,账上只少4,实际承诺8。这是读后写竞态,即使领域方法检查了quantity合法也无法解决。存储实现需在同一原子更新中加入租户、版本和 available >= quantity,并检查影响行数;事务范围还须包含对应业务流水。对象规则与数据库规则是互补保护。

练习一: 为什么Controller里有校验仍需要Money构造校验?答案:RPC、批处理和测试可能绕过Controller;值对象保护所有使用入口。但它不负责识别操作者,授权仍由可信上下文和用例完成。

练习二: 1元分三行,退款第二行能否按现在剩余两行重新均分?答案:通常不能。应使用原交易分配快照,第二行退款33分,避免重新分摊造成历史总额漂移;具体余数归属应写进规则。

练习三: 给同一个LocalDateTime分别按UTC和Asia/Shanghai转Instant,预期什么?答案:二者相差八小时。这证明墙上时间需要时区,不证明项目目前保存错了。测试应固定输入和区域,不改全局默认时区影响其他并发测试。

练习四: 如何测试本章用例又不启动整个ERP?答案:用内存替代Repository,分别返回1、0或抛异常,断言用例成功、冲突和失败语义;再由独立目标数据库测试验证条件SQL真正原子。前者不能替代后者。本轮提供方案,未执行业务测试。

官方参考还包括JDK Clock与JDK字符集。继续阅读关系建模、库存并发和依赖注入设计。

原始文档 · backend-foundations-course/03-数据库访问安全权限注入凭据与迁移规范.md

03 数据库访问安全、权限、注入、凭据与迁移规范

数据库安全不只是SQL中有没有引号,也不只是用户有没有登录。一个合法用户可以提交别人的订单ID,一个正确绑定参数的查询可以遗漏租户,一个只读接口可以一次扫描太多数据把资源耗尽。要建立可靠边界,需要把身份来源、查询语义、账户权限、秘密生命周期和发布迁移连在一起。本章不读取真实秘密配置,不连接业务服务;代码与账号名称都是教学设计。

1. 从不可信请求走到可信查询

浏览器输入都属于待验证数据,包括前端隐藏的tenantId、不可编辑的金额和禁用按钮旁边的状态。客户端可能被修改,请求也可以绕过页面直接构造。服务器应先验证认证材料,再建立可信主体,然后判断这个主体能否对指定资源执行动作。认证回答“是谁”,授权回答“能做什么、对哪一份数据做”。

多租户ERP还要区分租户、店铺、供应商和操作员。它们可能有授权关系,但不是同一个ID的不同名字。请求允许选择店铺时,应检查店铺属于当前主体的授权范围,而不是把店铺参数原样当作路由依据。高权限的后台操作也应成为显式用例,不能靠传一个空tenantId就进入全量模式。OWASP建议默认拒绝并在每次访问时验证权限,见授权指南。

请求中的订单ID和筛选条件(不可信)
  → 认证取得主体(可信来源)
  → 验证动作权限和店铺/租户关系
  → 生成范围明确的查询对象
  → Mapper绑定值并保留范围条件
  → 返回经过字段裁剪的响应

缓存和异步不能跳过这条边界。缓存键缺少租户可能混数据;即使键包含租户,角色可见字段不同也不宜共用完整响应。导出任务执行完成不表示任意拿到jobId的人都能下载,下载时还需检查当前主体与文件所属任务的关系。

2. 真实权限链:成立的前提必须写出来

SysUserServiceImpl第73行〔本地文件〕给 selectUserList 标了 @DataScope。DataScopeAspect第58行〔本地文件〕在进入目标方法前先clear再生成范围。第153行〔本地文件〕要求首参数是BaseEntity,才能将生成片段写入params;Mapper第99行〔本地文件〕使用它。

这条链不是“看到${}就一定有注入”。当前代码存在清理输入片段的防护,而且范围取自服务器上下文。评审要核对调用是否经过代理、参数类型是否满足、别名是否匹配、登录上下文是否存在,以及所有入口是否都遵守同一约定。任何一个环节绕开,后续层都可能收不到预期限制。

同文件第79行〔本地文件〕还有无同样注解的 selectUserListWithout,调用同一Mapper。这证明有不同入口形态,不证明低权限用户已能走到它。应继续追踪调用者、上游授权和参数来源,再决定其是否为受控管理能力。本轮未追完可达性,因此只把它列为条件风险。

更易维护的设计,是尽量用类型化范围对象表示可见部门、用户或租户,由固定SQL消费;有意绕过范围的操作使用专门方法和独立权限,而不是复用一个可装任意SQL片段的公共Map。缺少授权上下文时默认失败,不能自动解释成全量访问。

3. 参数绑定保护值,不保护SQL结构

MyBatis的 #{name} 生成绑定参数,${name}进行文本替换。值如订单号、金额和状态应绑定;表名、列名、排序方向属于语法,不能指望用问号占位得到同样效果。正确方法是从外部枚举映射到服务器固定片段。官方区别见MyBatis映射文档。

<!-- 教学Mapper:tenantId必须从可信上下文取得。 -->
<select id="findOrders" resultType="course.OrderView">
  SELECT order_id, status, amount
  FROM course_order
  WHERE tenant_id = #{tenantId}
    AND status = #{status}
  <choose>
    <when test="sort == 'CREATED_DESC'">
      ORDER BY created_at DESC, order_id DESC
    </when>
    <otherwise>
      ORDER BY order_id ASC
    </otherwise>
  </choose>
  LIMIT #{limit}
</select>

入口应拒绝未知sort或明确采用默认值,并限制limit。不要将orderBy整段字符串交给Mapper。若搜索要匹配字面量百分号和下划线,还要按方言处理LIKE转义:绑定可以防止它们变成SQL语法,却不会取消它们在LIKE中的通配符含义。安全与搜索语义是两项独立要求。

批量操作同样要限制空集合和大集合。空ID集合不能导致条件分支消失后更新整表;应在应用层直接拒绝或返回明确空结果。分批处理时每批仍带相同授权范围,不能为了“优化SQL长度”把租户条件移除。批量写入还须声明部分成功策略,不能把异常都降为跳过后返回整批成功。

4. 读和写都需要资源授权与并发条件

只在查询接口检查权限还不够,更新可能直接使用客户端ID。下面的教学更新把租户、身份、旧状态和版本一起放在写入条件里:

UPDATE course_order
SET status = 'CONFIRMED', version = version + 1
WHERE tenant_id = #{tenantId}
  AND order_id = #{orderId}
  AND status = 'DRAFT'
  AND version = #{expectedVersion};

参数都绑定后,调用方仍要检查影响行数等于1。返回零可能表示资源不在范围、状态已变化或版本过期,不能无条件返回“审核成功”。为避免枚举资源,外部可用统一不可访问或冲突响应,内部记录安全的错误分类;产品若需精确区分,应在已授权范围内进行补充查询。

数据库账号的权限是另一层。普通应用账号不应同时拥有任意DDL与账户管理能力;迁移账号只在受控变更阶段使用;只读报表账号限制可访问对象。账号最小权限无法替代行级租户授权,但能限制应用错误或入侵后的影响范围。不要因为数据库通常部署在内网,就假设应用请求天然可信。

5. 凭据管理是一条生命周期

教材只写 COURSE_DB_USER、COURSE_DB_PASSWORD 等变量名,不给出真实值,也不通过尝试登录验证它们。真实秘密应由受控注入或秘密管理服务提供,并明确读取主体、有效期、审计与轮换机制。环境变量只是传递方式之一,不会自动防止进程转储、调试输出或日志泄漏。官方实践见OWASP秘密管理。

轮换流程需要考虑池化连接:发布新凭据后,旧连接可能继续使用原身份直到关闭。合理方案是先提供新身份并验证权限范围,再分批更新客户端,观察连接重建和错误率,确认旧身份不再需要后撤销。若是已泄漏凭据,撤销的紧迫性更高,应采用相应应急流程,不能为了无损切换无限期保留旧凭据。

发现凭据出现在代码或日志时,删除文本不等于撤销秘密;旧提交、构建产物、缓存和接收方可能仍持有副本。处理记录应描述类别、位置和处置状态,而不是复制完整值进入工单。测试可以使用明显虚构的敏感标记,断言日志、异常响应和导出文件中没有它,避免为了测试泄漏防护而真的传播秘密。

6. 异常、日志和网络也会扩大数据边界

真实GlobalExceptionHandler第102行〔本地文件〕将异常message作为错误响应。若上游异常包含SQL、内部地址或隐私,便可能进入浏览器。改进应把公开错误码与内部cause分开,并用traceId关联。内部日志也不是无限可信的保险箱,应限制字段、长度、保留时间和访问人群。

HttpUtils.sendSSLPost第198行〔本地文件〕记录拼接后的请求串,第224行〔本地文件〕记录返回内容。这是记录形态证据,不说明实际请求必定含秘密。若被用于敏感平台调用,应改为服务标识、耗时、结果类别和脱敏样本。请求失败时尤其不要自动打印完整参数。

同方法的TLS检查问题在04章展开。此处的要点是:参数绑定不会保护传输身份,HTTPS字样也不会保证客户端认真验证对方证书。安全必须沿整条数据路径逐层检查,不能由某一层的正确性推出其他层也正确。

7. 迁移要兼容运行中的旧代码

数据库变更不是提交一份DDL就结束。新旧应用可能同时运行,回填可能中断,数据量会放大锁和I/O成本。以增加核销金额精度为例,先扩展兼容列或结构,部署可兼容读取的版本,再按主键有界回填并保存水位,核对总额、空值与范围,最后切换写入和移除旧路径。双写若不在同一事务,还需要失败修复与对账,不能把双写当作天然一致。

变更计划应写明版本前置条件、影响对象、预计锁行为、备份恢复点、失败停止条件与数据修复路径。回滚应用不会自动恢复已改变的数据口径。MySQL许多DDL会隐式提交,不能用一个外层事务假装全部DDL可回滚;具体操作以MySQL隐式提交说明和目标版本为准。本轮没有确认业务数据库服务端版本。

不要把大规模回填放到每个实例启动方法中。多副本同时启动会重复扫描并竞争资源,而且无法清楚恢复水位。迁移任务需要独立身份、受控批次、可观察进度和重复执行语义;吞吐提高之前先证明不会漏、不重写新数据、不跨租户。

8. 故障推演、练习与答案

假设团队增加一个导出任务,直接调用无范围注解的方法,以为后台任务没有用户就应该全量查询。任务随后把文件存到可猜ID下。这个组合同时绕开查询范围和下载授权,即使SQL全部参数化仍不安全。修复要从任务的可信发起身份开始,持久化授权依据或按协议重验,执行时应用范围,下载时检查归属;只给文件名加随机串不能替代授权。

练习一: SQL已全部使用#{},还可能越权吗?答案:可能。绑定防止数据改变语法,不保证数据属于当前租户。测试用租户甲身份请求租户乙ID,分别覆盖读、改、删、导出和下载,断言结果与副作用。

练习二: 如何验证${params.dataScope}不是客户端注入入口?答案:先追参数绑定来源、clear路径、代理和首参数类型,再通过真实入口提交伪造范围,观察最终BoundSql与授权结果。仅调用切面私有逻辑的单元测试不能证明所有入口可达路径都受保护。

练习三: 新密码发布后能马上撤销旧账号吗?答案:取决于实例切换与连接重建状态;常规轮换应验证兼容窗口并确认旧身份退出,泄漏应急则按更紧迫的撤销策略执行。不能仅看配置发布成功就认为全部旧连接已消失。

练习四: 迁移回填完成90%后进程退出怎么办?答案:从已确认水位继续,重复批次不损坏新数据,完成后按业务总量和金额对账;水位与提交的先后必须定义。这里只给出方案,没有执行DDL或业务故障注入。

继续阅读数据库迁移与恢复、Spring多租户安全及运维课程。

原始文档 · backend-foundations-course/04-项目反例与安全编码评审.md

04 项目反例与安全编码评审

安全评审的产物应让别人能够复查和验证,而不是一句“这里不安全”。本章选取当前源码中的12种风险形态,统一交代已观察行为、成立条件、改进方向和测试判据。它们涵盖权限、数据、传输和资源,不等同12个已确认可利用漏洞。未追完所有调用者,未启动业务应用,未验证线上配置、流量和部署事故。下面的测试均为设计与预期,不是本轮执行结果。

1. 任意异常消息直接进入响应

证据: GlobalExceptionHandler第91行〔本地文件〕捕获RuntimeException并返回 AjaxResult.error(e.getMessage()),第102行的通用Exception路径也类似。

条件与机制: 当下游异常携带SQL、内部路径或敏感业务字段,且请求能够触发该异常时,内部信息会跨越公开响应边界。若消息本来就是固定公开文案,则不构成同等泄漏,不能把每次异常都称为泄密。

改进与测试: 未知异常统一安全错误码和traceId,受控业务异常单独映射。用虚构标记构造异常,断言响应不含标记、内部记录可关联原因,并检查真实HTTP状态与业务码;只检查JSON有error字段不够。

2. 数据范围依赖切面,但存在不同入口形态

证据: SysUserServiceImpl第73行〔本地文件〕有DataScope注解,第79行〔本地文件〕的selectUserListWithout没有同样注解,二者调用同一Mapper。Mapper第99行〔本地文件〕消费文本范围。

条件与机制: 当无注解入口对低权限调用者可达、上游未独立授权且参数缺少可信范围时,查询可能扩大。正常注解路径还存在清理防护〔本地文件〕,不能忽略它而直接宣布注入漏洞。

改进与测试: 将绕过能力命名和权限独立化,普通查询接受不可伪造的类型化范围。分别经真实代理入口、后台入口和直接Mapper入口测试甲乙两组身份;未完成调用者追踪前保留“可达性未验证”。

3. 时间列上执行函数扩大查询成本

证据: SysUserMapper第89行〔本地文件〕对create_time使用date_format再比较,格式还是两位年份。

条件与机制: 在需要利用普通时间列索引、大量候选行且无适配表达式索引等条件下,函数形式可能妨碍有效范围访问。两位年还会在跨世纪数据中改变排序含义。没有实际计划和数据分布,不能声称该查询当前一定慢。

改进与测试: 应用先计算明确时区的起止边界,SQL使用原列半开范围。用同一数据集核对结果相等、跨日和跨世纪边界,再在目标数据库检查执行计划、扫描行数与耗时;不能只用小表的毫秒结果论证性能。

4. 无界队列让最大线程数难以发挥作用

证据: ScmDistributorItemThreadConfig第28行〔本地文件〕创建未指定容量的LinkedBlockingQueue,第33行设置core=5、max=10。

条件与机制: 持续提交速度超过处理速度时,任务在近似无界队列中积累。核心线程忙后优先入队,队列一直接收,通常不会因普通负载增长而扩展到max;排队对象还保留请求上下文和参数。是否实际积压需运行指标证明。

改进与测试: 设计有界队列、拒绝反馈和下游并发预算。用闩锁占住工作线程,再精确提交超过容量的任务,断言拒绝和队列上界;所有等待设超时并finally释放。详见ThreadPoolExecutor官方语义。

5. 缓存的查、算、写不是同一个原子操作

证据: LocalCache第117行〔本地文件〕依次getIfPresent、supplier.get和put。

条件与机制: 同键并发未命中且supplier昂贵时,会重复回源;若加载器有副作用,重复的不只是查询成本。底层缓存线程安全并不把这三步自动合成一次加载。没有并发调用不代表此风险永远不存在,但也不能宣称已发生击穿。

改进与测试: 采用适合当前版本的原子加载API,加载器保持无副作用,区分本机合并与多实例协调。通过闩锁让两个调用同时未命中,记录加载次数;改造后断言单机同键合并,但仍要验证异常和空值策略。Caffeine维护者文档说明加载方式。

6. 中断被吞后取消协议失效

证据: Threads第23行〔本地文件〕捕获InterruptedException直接返回,没有恢复中断标志。

条件与机制: 若外层循环用中断标志判断退出,sleep抛异常清除标志后,这个工具会让循环失去取消信号。若调用者本身立即退出,则影响较小,必须结合调用者判断。不能把shutdownNow理解成强制杀死任何任务。

改进与测试: 可抛则传播,否则恢复标志并由任务边界结束工作。测试控制线程进入等待,发出interrupt,断言后续副作用计数为零、线程在期限内退出。Thread API给出中断语义。

7. 金额工具的double入口和出口损失契约

证据: Arith.add第28行〔本地文件〕接受double,内部构造BigDecimal,再doubleValue返回。

条件与机制: 用于要求十进制精确的账务且输入或输出超出double精确表达能力时,内部BigDecimal不能恢复上游已丢失的数字。普通近似统计可能允许这种误差,因此问题在于适用范围与业务契约,而非所有double一律禁止。

改进与测试: 金额全链路使用受限十进制字符串、BigDecimal和匹配DECIMAL,规定币种与scale。测试包含大数、最小单位、分摊与JSON往返;不能只用0.1加0.2的单例证明全部资金正确。

8. 零分子提前返回掩盖零分母

证据: Arith.div第81行〔本地文件〕在第90行检查分子为零,直接返回零,除法在第94行发生。

条件与机制: 输入0/0时会走提前返回;若它表示“没有样本的核销率”,零值可能被误读为已测得0%。这是可从局部控制流推导的行为,但未证明业务真的传入过这个组合。

改进与测试: 优先检查分母并由领域定义不可计算语义,必要时用带状态的结果代替裸数。覆盖0/0、0/非零、非零/0、负分母和非法scale;断言异常或明确状态,不仅断言程序没有崩溃。

9. 默认时区让相同输入依赖机器环境

证据: DateUtils第185行〔本地文件〕将LocalDateTime按systemDefault转换成Instant,第194行对LocalDate也使用默认区域。

条件与机制: 当输入代表固定业务区域,而机器默认时区不一致或改变,同一日历时间会产生不同瞬间。若系统严格统一并契约明确,风险受控,但这需要部署证据,本轮未验证。

改进与测试: 显式传入业务ZoneId,Clock作为依赖;测试UTC、Asia/Shanghai和存在夏令时的区域,验证自然日半开边界。避免并行测试修改全局默认时区,造成别的测试偶发失败。

10. HTTPS连接绕过证书与主机名校验

证据: HttpUtils第199行〔本地文件〕安装自定义TrustManager,第255行〔本地文件〕的checkServerTrusted为空,第269行〔本地文件〕的verify恒为true。

条件与机制: 若该方法实际用于敏感外部通信,且攻击者能介入相应网络路径,客户端无法依靠这些校验确认对端身份。代码明确绕过检查,但使用范围和攻击可达性没有验证;HTTPS加密与对端可信不是同一个保证。

改进与测试: 使用标准证书链和主机名验证,内部CA通过受控信任库分发。只在隔离测试端点验证过期证书、不受信任证书和错误主机名均拒绝;不能连接业务端点试错。机制见JSSE参考。

11. 流关闭只出现在成功路径

证据: HttpUtils第214行〔本地文件〕获取流并读内容,disconnect与close在第225—226行,异常分支不经过这两句。

条件与机制: 读取或处理时抛异常会跳过显式关闭。重复失败可能累积资源压力,具体回收行为取决于连接实现,不能据此计算确定的泄漏速率。

改进与测试: 将流交给try-with-resources,连接清理放适当finally;同时保证失败不会被伪装成完整响应。用可在第N次读取抛异常的假流,断言close恰被调用,避免为了复现而依赖不稳定外网。

12. 完整请求参数和响应进入日志

证据: HttpUtils第198行〔本地文件〕记录完整拼接请求串,第224行〔本地文件〕记录返回内容,异常路径也拼接param。

条件与机制: 当参数或响应含凭据、个人信息或巨大列表时,日志同时成为泄漏面和额外I/O成本。这里没有读取或复制任何实际请求值,也没有证明日志系统中已有秘密。

改进与测试: 用字段白名单、长度上限和脱敏策略,保留服务名、结果类别、耗时与traceId。以虚构敏感标记和超长响应测试日志,断言标记不出现且记录量受限;禁止用真实凭据作测试样本。

13. 将单点风险组合成故障时序

下面是教学假设:某批处理同时使用第4种队列、第6种等待工具和第11种I/O路径。我们没有证明真实调用链把它们组合在一起。组合推演的价值在于练习寻找放大关系:

外部依赖变慢 → 工作线程长时间占用 → 待处理任务持续入队
管理员取消任务 → 等待工具丢失中断 → 工作继续
读取反复异常 → 部分路径跳过关闭 → 可用资源继续下降
最终:更多正常请求也开始排队或失败

修复顺序应结合暴露范围与可验证性。先阻止无界接单并明确取消,保护资源;再定位失败路径和对端原因。只把最大线程数调大可能加重下游压力。恢复验收要观察队列最老任务年龄、活跃资源、失败类别与有效吞吐,不能只看接口平均耗时下降。

14. 评审练习与参考答案

练习一: 哪些结论可以由局部源码直接确定?答案:空的证书检查、恒true主机校验、0/0提前返回、无容量参数队列等实现形态。哪些用户可调用、是否已泄漏、是否已OOM仍需另外证据。把两者混写会使评审失去可信度。

练习二: 如何让缓存并发测试稳定?答案:用闩锁控制两线程在读到缺失后再放行加载,等待有期限并finally清理;不要靠sleep猜交错。原实现的测试应观察重复加载可能发生,改进实现断言约定的合并行为。

练习三: TLS修好后,能否宣布这个HTTP工具安全?答案:不能。还需处理超时、资源、响应大小、日志、失败语义和目标地址来源。本章没有审计完整SSRF路径,不能把没有列出的问题当作已经安全。

练习四: 为第2项写一句合格结论。答案:“存在无DataScope注解但访问同一Mapper的方法;若低权限入口可达且无上游授权,数据范围可能扩大,需追踪调用者并以跨主体负例验证。”这比“用户列表存在严重越权”更符合当前证据。

评审记录应同时包含源码版本或日期、相对路径与行号、触发前提、预期不变量、改进副作用和未覆盖范围。完整性不能靠风险数量证明;本章12项只是可复查的训练集。继续阅读Spring故障验收、高并发课程及运维课程。

原始文档 · backend-foundations-course/图解导读.md

图解导读:把调用、资源和故障边界画清楚

这六张图用于辅助阅读,不代替具体实现。它们是结合项目模式提炼的教学图,不是对线上部署拓扑的测绘。图中简化项均在图注或下文说明。手机可以在图内横向滑动,统一阅读站还支持放大;SVG矢量图与正文均离线可用。

1. 请求、授权与本地事务

图解 · 可横向查看
请求调用链:身份、代理与数据库边界从客户端经授权和Controller进入事务代理,再到Mapper和数据库。远端资源不属于此本地事务。 请求调用链:身份、代理与数据库边界客户端输入DTO / 不可信租户参数认证与资源授权身份 → 租户 → 资源范围Controller参数绑定 / 校验 / 契约事务代理 → Service从代理进入才有该增强Mapper / JDBC参数绑定 + 租户谓词同一事务数据库资源条件更新 / 唯一键 / 提交外部调用事务边界:仅覆盖同一管理器实际参与的资源Redis、远端RPC、对象存储,不因写在同一个方法就一起回滚。HTTP不是唯一入口:RPC、消息、定时任务也必须落实授权与业务规则。
请求调用链与本地事务资源边界

看图时回答三件事:租户身份来自哪里,调用是否真的进入代理,实际SQL是否使用事务管理器绑定的连接。Controller上的校验不覆盖所有RPC与任务入口;SQL参数绑定也不自动提供租户授权。项目启动和数据范围切面是具体阅读入口,见源码风险评审。

2. 自调用不等于“一定没有事务”

图解 · 可横向查看
事务代理:外部进入与this自调用是两条不同路径时间从上到下;虚线箭头表示返回。this.inner()不重新进入代理;但可能仍处于外层已经开启的事务内。;没有外层事务时,自调用不会仅凭内部@Transactional注解创建新事务。 事务代理:外部进入与this自调用是两条不同路径调用者Spring代理目标Service数据库外部调用方法开始或加入事务调用目标方法this.inner()执行同线程SQL结果 / 异常返回按规则提交回滚返回调用者this.inner()不重新进入代理;但可能仍处于外层已经开启的事务内。没有外层事务时,自调用不会仅凭内部@Transactional注解创建新事务。
事务代理与自调用:内部方法不重新经过代理,但可能仍在外层事务内

最容易学错的是把“self调用不触发内部增强”简化成“内部方法执行时肯定没有事务”。如果外部入口已经通过代理开启事务,同线程SQL仍可能加入外层资源;只是内部注解要求的REQUIRES_NEW、隔离或回滚规则没有通过这次自调用单独生效。反过来,无外层事务时,注解也不会凭空开启它。继续读Spring事务。

3. 线程池不是先用满max再排队

图解 · 可横向查看
线程池决策:core → 队列 → max → 拒绝worker不足core时创建,否则先尝试队列,队列拒绝后再尝试扩容,最后执行拒绝策略。 线程池决策:core → 队列 → max → 拒绝收到任务execute / submitworker 少于 core?不是先扩到 max创建 worker 执行接收失败仍需处理队列接受成功?有界容量 / 已关闭状态排队等待等待时间与对象内存有成本还能创建 worker?少于 max 且创建成功扩容执行不是数据库自动扩容拒绝处理显式失败 / 持久待调度是否是否是否无界队列通常先持续排队;静默丢弃可能让submit返回的Future永不完成。这是接收决策简图,关闭状态竞争与创建失败还需参考JDK实现。
执行器接收决策与拒绝边界

用SCM的core5/max10与无界队列沿箭头走一次,就能看出正常负载为何可能一直排队而不扩到10。再用Index的有界队列与DiscardPolicy推演:排队失败和扩容失败之后,调用者得到什么?静默丢弃不是可靠接单。高并发执行器章节还讨论取消发生在任务开始之前时,finally为什么不够。

4. Outbox和Inbox保护不同的提交边界

图解 · 可横向查看
Outbox / Inbox:两次本地提交,不是一笔全局事务时间从上到下;虚线箭头表示返回。发送后、标记SENT前崩溃会重发;消费提交后、ACK前崩溃会重投。;消费者靠同一事务内的去重记录和业务变化收敛;Broker确认含义依产品契约核验。 Outbox / Inbox:两次本地提交,不是一笔全局事务业务服务订单数据库投递器Broker消费者业务+Outbox写入事务提交成功读取待发事件发送固定eventId收到发送确认投递,可重复Inbox+业务提交提交后ACK发送后、标记SENT前崩溃会重发;消费提交后、ACK前崩溃会重投。消费者靠同一事务内的去重记录和业务变化收敛;Broker确认含义依产品契约核验。
Outbox与Inbox跨服务提交时序

图中有两笔本地业务事务:订单侧的业务+Outbox,消费侧的Inbox+业务效果。投递器在收到确认后仍需更新发送状态,图为控制密度省略了这个数据库箭头;恰恰是确认后、标记前的崩溃让重复发送成为正常情况。ACK并不等于所有业务都完成,只有消费者的提交协议才决定承诺。详见幂等与Outbox。

5. 锁过期后旧线程仍可能继续运行

图解 · 可横向查看
租约到期不等于旧执行者停止:写入端还要校验token时间从上到下;虚线箭头表示返回。前提:授权方提供单调token,资源端原子比较并拒绝旧写入。;普通Redis锁或任意对象存储不自动具备此能力;外部文件可用隔离键+受控发布。 租约到期不等于旧执行者停止:写入端还要校验token旧 worker租约授权方新 worker受保护资源取得 token=7暂停 / 长GC到期后取得8带8写入,接受恢复后带7写入拒绝旧token前提:授权方提供单调token,资源端原子比较并拒绝旧写入。普通Redis锁或任意对象存储不自动具备此能力;外部文件可用隔离键+受控发布。
租约与fencing:旧worker恢复后的写入必须由资源端拒绝

图中token由授权方保证单调,资源端原子比较。若项目实际只是一个Redis锁,没有这样的资源侧检查,就不能把图上的拒绝能力当作现成事实。对对象存储这类不能直接比较token的资源,可以使用不可变隔离对象键和数据库控制最终发布,但必须处理孤儿对象。租约课程解释适用条件。

6. 导出恢复不是把任务重新跑一次

图解 · 可横向查看
可靠导出:任务、文件和数据库之间的恢复边界持久任务抢占后分批上传并短事务记录进度,故障后退避重抢,全部完成才发布成功。 可靠导出:任务、文件和数据库之间的恢复边界PENDING任务已持久化RUNNINGowner+epoch+租约分块上传不可变对象+校验和短事务记账块记录+连续checkpoint继续下一块检查租约 / 取消 / 预算RETRY_WAIT过期回收 / 有限重试SUCCEEDED发布完整manifest抢占确认上传还有数据下一批全部核验完成故障/过期退避后重抢上传后、记账前崩溃:允许孤儿对象,不能提前推进checkpoint。本图省略永久失败与取消终态;只有连续完成前缀可被安全跳过。
可靠导出的持久状态、分块上传和checkpoint恢复

上传成功不等于数据库进度提交成功;有多个并行块时,完成最大的块也不意味着之前的块都已完成。必须推进连续完成前缀。图中重试需要重新获取owner与epoch,而不是旧worker继续写;永久失败、取消与最大尝试次数在正文设计中另外处理。可靠导出实战给出完整边界。

读图练习与答案

  1. RPC调用位于事务方法内,失败是否能回滚远端?不能,本地事务只管理参与的本地资源。
  2. outbox重复发送是否证明方案失败?不是,重复投递是预期窗口,业务效果须通过稳定ID与原子去重收敛。
  3. worker拿到锁后暂停到租约过期,恢复后自动停止吗?不会,需要协作停止与资源侧旧token拒绝等保护。
  4. 图中一条箭头能证明部署生效吗?不能,图表达机制或方案;运行路径仍需代码、配置和测试证据。
原始文档 · backend-foundations-course/外部输入文件与网络安全深化.md

外部输入、文件与网络安全深化

前几轮课程已经覆盖SQL注入、租户条件、日志脱敏与TLS校验。这次把一个容易被遗漏的边界补齐:当服务器替用户读取URL、处理附件、接收第三方回调时,输入不仅能改变查询结果,还可能改变服务器访问的网络、消耗的内存、写入的文件和触发的业务动作。本章只读源码并提供防御设计,不执行攻击或访问任何业务服务。

1. 一个URL不是普通字符串参数

项目HttpUtils.sendGet〔本地文件〕拼接参数后创建URL与URLConnection,逐行读取响应到StringBuilder。该方法局部没有显示业务目的地址白名单、显式连接/读取超时和响应总量限制。这里只能确认工具方法的形态;若调用者永远传固定可信地址且外部网络有隔离,风险与任意用户控制URL的场景完全不同,不能跳过调用者直接认定可利用SSRF。

应该沿参数来源追踪:URL来自固定配置、受控平台枚举,还是请求/数据库中的用户内容?数据库中保存的字符串不天然可信。若用户可以登记图片URL、回调地址或远程文档,应用就承担了代理访问责任,需要定义允许访问的目的地和网络范围。

对固定平台集成,优先让前端提交平台ID,由后端映射到固定客户端与固定端点,而不是接受任意URL。对确实需要开放URL的功能,应通过统一出站策略、受控解析和网络隔离处理,避免几十个调用点各写一个不完整正则。

2. URL校验与实际连接必须一致

只判断字符串包含某域名不可靠;应解析scheme、规范化host、有效port、userinfo和必要path,再按批准的策略判断。还要处理重定向、IPv6、多DNS结果和重新解析。如果校验一次DNS结果后,HTTP客户端连接时重新解析到另一地址,校验与使用就脱节。

这是TOCTOU问题:检查发生的时刻和使用发生的时刻不同。可采用能把连接绑定到已验证地址且保持正确TLS主机验证的客户端/受控代理,并在网络层拒绝不允许的出站路径。不要通过关闭证书校验来“解决绑定IP后的HTTPS报错”。重定向可以禁用,或每一跳重新执行同等策略;允许首个地址不代表信任它返回的任意Location。

这里不提供几行自制URL过滤器,原因不是省略实现,而是它会错误暗示完整防护。应对项目实际HTTP客户端版本、代理配置和解析行为做集成验证。对外部URL的防御原则可核对OWASP SSRF指南。

3. 超时之外,还要限制读取与解压成本

连接快、持续不断返回少量字节的响应,可能长时间不触发普通读取超时。响应压缩前很小、解压后巨大,也可能造成内存压力。因此除了连接/读取超时,还要有总deadline、解码后体积、重定向次数、并发、失败重试和下载存储配额。

HttpUtils按行累积StringBuilder的形态说明“使用流API”不等于“有界流式处理”。如果最终把全文放进内存,仍然受总内容大小影响。大文件应边读边写受控临时存储、累计字节并及时取消,避免把文件再转成Base64造成额外内存膨胀。限额应在解析之前尽量生效,应用层检查不能撤销网关或multipart解析已经消耗的资源。

接收远程文件任务
 → 校验身份、任务配额和目的地
 → 有界连接与读取
 → 隔离临时存储(累计解码后大小)
 → 内容验证 / 扫描 / 格式处理
 → 原子发布业务引用
 → 失败清理与可重试状态

这是设计时序,不是当前HttpUtils已有实现。响应体不能无条件写完整日志,尤其URL查询参数可能带token或签名。

4. 两条上传路径不能假定有同样的校验

FileUploadUtils.upload〔本地文件〕检查原始文件名长度,再调用assertAllowed并生成保存名称。这个工具提供部分边界,但要继续看允许扩展集合、文件大小、目标目录来源和最终下载方式,不能仅因调用了assertAllowed就认定附件安全。

另一个OssFileController〔本地文件〕有不同路径:读取后缀,类型检查调用被注释,获得InputStream后上传;关闭流位于成功路径,catch忽略异常。这是可确认的局部代码形态。该入口是否另有过滤器、SDK是否负责部分资源回收、部署如何授权,需要继续验证。

应避免“一个上传工具安全,所以所有上传都安全”的推断。按所有入口建立表:入口权限、体积限制、类型限制、对象键、资源所有权、审计、下载鉴权与失败清理。直传签名入口也属于上传入口,不能漏掉。

5. 文件类型、路径和浏览器执行是三个问题

后缀和Content-Type都来自不可信元数据,文件签名与格式解析增加证据但不能保证不存在恶意内容。根据业务只接受必要格式,解析器使用受支持版本并限制资源;压缩包还要限制展开体积、文件数、嵌套深度和目标路径,防止小包变成巨大工作量。

保存位置应由服务端生成并绑定租户/用途,原始名字作为经过处理的展示字段,不直接拼进磁盘路径。路径规范化后检查仍处于允许根目录,并考虑符号链接及创建竞争;字符串startsWith不是完整文件系统安全证明。对象存储不是本地目录,但同样存在前缀权限与覆盖其他对象的问题。

上传文件即使不会在服务器执行,也可能在浏览器同源打开时形成主动内容风险。需区分附件下载与受支持的预览格式,合理设置Content-Type、Content-Disposition和禁止嗅探等响应策略;隔离附件域、短期访问凭证和下载时重新授权都是独立控制。相关原则见OWASP文件上传指南。

6. 直传策略与完成回调

getUploadPolicy〔本地文件〕创建带有效期、对象键前缀和大小范围的策略。要检查前缀中的module和用户身份是如何限制的,以及大小上限与业务用途是否匹配。策略签名只说明持有人能执行其授权动作,不自动说明上传结果已获业务批准。

“前端告诉我上传成功”不能直接创建可信附件记录。服务端应根据预创建的上传任务、期望对象键和必要的存储元数据校验完成,再关联业务单据。若使用回调,校验回调真实性和绑定关系;重复通知通过事件键或状态迁移幂等处理。

签名URL、上传策略与短期凭证即使不是长期账号密码,也应限制传播与日志记录;一旦泄漏,在有效期内仍可能被使用。撤销、过期清理与孤儿文件治理不能完全依赖用户关闭页面。

7. Webhook签名验证不是幂等

签名验证证明消息来自持有密钥的一方且内容符合签名,不证明它没被重放。应根据对方协议验证原始字节、时间窗口、签名版本和密钥轮换,再以稳定业务事件ID实现幂等。重新序列化JSON可能改变字节顺序或空白,使验签失败;不能为了兼容而跳过验签。

先通过验证,再可靠保存事件,最后按承诺返回确认。若接口在业务未完成时就快速返回成功,应明确已有持久队列/Inbox接管,而不是仅提交内存线程池。重放保护与业务重复去重是不同层:时间窗内仍可收到合法重试,同一事件的跨进程副作用仍需唯一约束和事务。

本项目具体外部平台回调契约需逐个平台核对;这一段是通用设计补充,不声称存在一个统一的生产Webhook实现。参照OWASP Webhook安全指南时也应保持这一边界。

8. 验收用例与答案

用例 期望验证 不充分的替代
固定目的地返回重定向 每跳遵守策略或拒绝跳转 只检查第一个URL
持续慢速返回大内容 总deadline与体积上限触发 只有单次read超时
MIME与实际格式不符 按业务格式验证并拒绝 信任浏览器accept属性
上传途中异常 流/临时文件有明确释放责任 只在成功路径close
同一完成通知重复 一次业务关联且可查询结果 仅校验签名
租户A猜到B的对象键 下载仍按身份与归属拒绝 对象键足够随机

练习:文件名字安全、签名也合法,为什么仍可能耗尽资源?名字与签名解决身份/语法边界,不约束文件解析复杂度、解压体积和并发;资源预算必须单独执行。

练习:catch返回默认对象是否比抛异常稳定?只有协议把失败状态明确暴露并收敛才稳定。吞掉错误可能让调用方误以为成功,掩盖资源泄漏或留下无法重试的状态。

本章没有执行网络探测、上传或真实服务测试。重点是把输入可信度、资源限额、权限与失败恢复放进同一条调用链分析,而不是列一串安全名词。

原始文档 · backend-foundations-course/审阅与知识缺口.md

旧课程审阅与知识缺口

审阅时间:2026-11-11。本报告服务于补课设计,不给旧教材或整个业务系统下“已全面验证”的结论。

一、实际看了什么

完整读取了数据库 README、Spring README,枚举了数据库 00—27 共 28 章、Spring 00—19 共 20 章的文件和标题层级。进一步重点抽样阅读数据库 01 的关系建模与类型、25 的 MyBatis 装配与 CRUD、27 的 JDBC/连接池/工具链,以及 Spring 01 的依赖方向、08 的校验与多租户安全、16 的测试与发布;读取两课验证记录和 Spring 源码索引。标题普查覆盖全部章节,正文抽样没有覆盖全部段落,不能把“目录已有主题”写成“已经审查其全部论证”。

旧课验证记录称数据库有独立关系计算、Redis 与语法检查,Spring 有 11 项机制测试及阅读版复核。这些是已有文档记录,本轮没有重新执行,因此不将其转记为本轮测试通过。尤其 H2、SQLite、内存模型的边界已经写得比较清楚,应保留,而不是为了课程显得完整就改成“真实业务集成通过”。

项目层面枚举并解析了 12 份顶级根 POM 的模块、Java 属性、父项、依赖管理和部分依赖声明,名单见00章。未下载私有 BOM、未执行有效 POM 或依赖树解析,未据此推断部署版本。源码抽样集中于 erp-admin 的权限切面、用户查询、异常处理、缓存、算术、时间、线程和 HTTP 工具,以及 erp-scm 的 Gateway 接口和线程池。04章给出逐项可回查证据。

已读取适用协作约定;本次写入范围仅为本目录和两份未编号补充阅读。没有修改业务代码、已有课程正文、旧 README 或验证器。没有读取业务 application 配置、Maven settings 或连接服务;教材不记录真实凭据和业务服务地址。

二、已覆盖的能力应继续复用

数据库课程已形成从关系模型到存储、事务、拓扑和工具链的路线。01章不是单纯列类型:它解释一行的业务粒度、唯一键与普通索引的区别,讨论历史成交价和商品现价,能支撑新课的领域模型练习。25章明确区分原生 MyBatis 与 Plus 装配,27章明确连接借用、驱动、池和事务集成边界,这些内容不需要再抄成一套新的数据库入门。

Spring课程已有对象装配、代理生效、异常响应和多租户访问的说明。08章已经指出认证、动作权限与资源权限不同,也涉及字符串 ID、金额、时区、文件与日志;16章讨论不同测试层级及滚动发布兼容。新增课程不能声称旧课“完全没有安全”“没有金额时间”,准确说法是:这些知识分散在框架或数据库场景中,尚不足以替代一套语言与工程基础训练。

两套旧课程共同强调证据边界和故障时序。这种方法值得延续。比如在代码中看见回源分三步,可以推导并发重复加载,但是否已击穿生产数据库还需要流量、调用路径和运行指标。学习者应掌握这种克制,而不是学会把每个反例都包装为线上漏洞。

三、薄弱处与本轮新增的对应关系

能力 旧课观察 本轮补充
全目录技术地图 多章有局部版本和源码入口,缺统一的顶级项目普查表 00章列出12项目、证据等级和能力地图
Java语言 并发和框架示例假设读者已理解 Java 对象与类型 01章解释引用、集合、泛型、异常和关闭资源
领域工程 已有 DI、表模型和服务编排,语言到业务不变量的桥梁较分散 02章从用例、值对象和条件更新组织模型
金额与时间 已提示 DECIMAL、BigDecimal、时区与 ID 精度 02章补齐舍入时机、分摊余数、跨日边界和序列化契约
数据访问安全 已有租户条件、参数绑定、日志警示 03章把可信身份、权限旁路、凭据轮换和迁移串成协议
可重复评审 有多个风险实例,但新读者不易形成统一表达 04章给出至少8种独立风险形态及测试判据

“薄弱”是针对前端转后端的前置知识需求,不等于旧课写错。比如数据库课程讲 DECIMAL 已经足够支撑存储选择;但读者仍可能把 Java double 先算完再转 BigDecimal,误以为就恢复了原始金额。这个缺口要靠跨层数据流解释,而不是再背一次数据类型表。

凭据部分同样需要从“不能写明文”推进到生命周期:谁能读取、什么时候失效、旧连接如何退出、审计记录保留什么、泄漏后为什么删文件并不撤销凭据。本轮用虚构变量和通用流程说明,不通过搜集真实秘密来证明风险。

四、还没有覆盖、不能假装覆盖的部分

本轮没有完成 Java 字节码、类加载器、JIT、GC 算法或全部 JMM 的系统教材;这些内容应在 JVM 与高并发专题中继续展开。没有设计完整身份平台、密钥服务、零信任网络和全部合规流程。分布式事务、消息投递语义、限流容量与发布恢复分别交给分布式、高并发和运维专题。

安全评审也没有追完全部 Controller、RPC、MQ、任务和私有依赖。04章中的权限旁路代表需要继续追踪的路径,不能据此声称任意用户已经可利用。TLS 校验绕过是局部方法中的明确行为,但调用可达性、网络条件和实际使用范围没有验证。风险列表是一组有证据的教学入口,不是渗透测试报告。

本轮未修改旧文对“后续课程尚未交付”的历史描述。新目录的链接是本轮协作入口,真实完成状态应由主代理合并验收后确认,避免并行任务互相改写结论。

五、建议的验收方式

让读者交三份材料:第一份是包含证据等级的依赖与调用链图;第二份是不启动 Spring 的金额、日期、集合和状态规则测试;第三份是对一个接口的授权数据流和失败矩阵。评分重点不是代码行数,而是能否解释“可信值从哪里来”“规则在哪一层最终生效”“请求超时后是否可能已经成功”。

文档交付检查应验证五章齐全、每章汉字数、代码围栏、目录链接和源码行号范围;人工复核引用是否真正支持相邻结论。字数只能避免过薄,不能证明教学深度。源码行号合法也不能证明推导正确。新的测试方案没有执行时必须写“预期”,不得写成测试结果。

参考口径:Maven依赖管理、MyBatis映射与参数、OWASP授权指南。这些材料解释机制,项目事实仍由本地源码链接承担。

六、本轮交付检查

新增五章、课程README、审阅报告与两份补充阅读,共9份Markdown。静态检查覆盖146个本地链接,其中87处带源码行号;链接存在、引用行号在文件范围内,代码围栏成对。五章均超过2500汉字,按汉字字符计数,不把英文路径和代码长度用来充数。分布式、高并发与运维README在本轮检查时已存在,只核验链接存在,不代表审阅其内容。

对新增文本进行了有限的私钥标记、明显长凭据赋值、业务JDBC地址与常见业务域名模式检查,未命中;这不是完整秘密审计。官方材料已按Java 8、Maven、MyBatis、OWASP和相关维护者文档核对。没有运行Maven、业务测试、数据库实验或网络故障注入,正文测试判据仍是待执行方案。HTML交由主代理生成,本轮没有新增或修改阅读器。

原始文档 · backend-foundations-course/第二轮查缺补漏与学习路线.md

第二轮查缺补漏:把知识变成能检查的开发边界

这一轮没有重新铺开一遍技术名词,而是检查此前课程中容易“读懂概念,写错代码”的地方。主要缺口是把正常流程讲清楚以后,没有把输入为空、事务嵌套、确认早于完成、线程取消、配置切换等分支串到具体调用点。补课应沿着一条业务链推演:谁接收责任、谁持有资源、哪里真正提交、失败以后谁接手。

本轮采用重点抽查,不是对整个工作区每一行代码的完整安全或性能审计。项目反例始终分为源码事实、触发条件、改进设计与验证边界;不根据局部catch、注解或方法名直接宣判线上必然故障。下面给出建议阅读顺序。

1. 先解决“改错数据”的问题

读数据库开发陷阱深化。优先掌握空Example导致条件消失、空IN产生错误、CASE批次身份混用、OR条件范围、一对多分页粒度、BATCH刷新与提交、影响行数口径、唯一键与逻辑删除。

练习不止是背诵“禁止全表更新”。拿一条实际Mapper,把输入分为null、空集合、单值、重复键、混身份五组,预测BoundSql以及目标键集合。再区分“SQL能生成”“插件允许执行”“数据库实际修改”“事务最终提交”四种证据。完成的产物应是输入表、生成SQL形状、预期键集合与尚未验证的环境条件。

2. 再解决“以为事务生效”的问题

读Spring开发陷阱深化,配合事务代理图。自调用没有重新进入代理,不等于一定没有外层事务;catch异常不等于清除了rollback-only;REQUIRES_NEW需要独立资源预算;提交后回调也不自动等于可靠消息。

练习:在订单服务画出两条调用路径,一条外部通过代理,一条this调用。分别标注事务管理器、连接资源、传播行为、异常穿过哪个代理、何时释放连接。之后才讨论该加哪个注解。对多数据源尤其要区分“路由上下文改变”和“已经绑定的连接改变”。

3. 把“接收成功”拆成多层承诺

读分布式开发陷阱深化。本轮继续追踪真实消息入口、内存去重对象相等性、入队返回值和后台异常,补上ACK之后责任是否还存在的问题。把消息放入内存队列、数据库提交、浏览器看到通知,不是同一种成功。

练习:列出一条事件从接收到最终业务变化的每一次责任交接,在每条交接线后假设进程立即退出。若答案是“它应该会重试”,继续写出谁保存了待办、用什么键找到、重试会不会重复扣库存。没有可定位记录的重试承诺不能作为验收结论。

4. 把“任务结束”与“资源归还”分开

读高并发开发陷阱深化。重点是拒绝、未运行就取消、运行中取消和真实IO退出的区别。Future进入终态不意味着底层计算停止,更不意味着连接、许可、文件句柄都已经可以重用。

练习:为一个最多N个运行任务的系统画状态机,定义什么时候扣许可、谁负责归还、排队取消怎么收尾。以N=1构造“调用者已超时但旧任务仍运行”的路径;如果第二个任务仍能立刻拿到运行许可,检查是否提前释放。Python模型用于检验协议思想,JDK取消/中断还需单独验证。

5. 最后补齐外部输入和运维闭环

读外部输入、文件与网络安全深化与运维开发陷阱深化。安全并不只发生在SQL拼接:服务器访问外部URL、解析文件、签发上传策略、接收回调都需要权限、资源预算与失败恢复。排障则要验证日志代表哪层成功、配置是否实际生效,以及发布回滚后数据和任务是否还能被旧代码理解。

练习:给导入/导出任务写一页验收方案,包含可信身份、允许输入、最大工作量、取消状态、孤儿文件、重试身份、错误日志字段和人工恢复。不能用“异步执行”“有重试”“有日志”作为验收项;应写可观察结果,例如“同事件重复投递时业务计数只增加一次,重试账本仍能说明每次失败”。

6. 六张图怎样配合正文

图解导读提供请求边界、事务代理、线程池接纳、Outbox/Inbox、租约fencing和可靠导出六张离线矢量图,也已嵌回对应章节。手机可以在图内横向查看,点击放大后看全尺寸图。图是教学模型,不是从生产部署自动生成的拓扑。

先看箭头说明责任如何转移,再看正文的例外条件。图无法承载完整配置和所有失败分支,因此每张图都说明省略内容;尤其不要把普通Redis租约等同于资源端已实施fencing,也不要把Outbox画成跨数据库与Broker的一笔原子事务。

7. 检查记录与剩余深挖方向

后续需要针对目标环境继续深入的内容包括:真实MySQL执行计划与锁等待、实际MQ客户端故障注入、带生产相似数据分布的容量验证、多数据源插件装配,以及部署后的备份恢复和升级兼容测试。这些不是靠继续增加概述文字就能“验证完成”的知识点;本轮补充的是可执行的观察方法与验收条件。

学习阶段 02

数据库与数据访问

关系模型、SQL、索引、锁与多种存储

原始文档 · database-course/README.md

ERP数据库系统课程:从基础语法到正确性、性能与运维

新增开发陷阱深化:空条件、CASE批次、权限OR范围、一对多分页、BATCH提交、影响行数与逻辑删除唯一键,附真实XML形状及H2隔离实验。

面向前端转后端开发者,基于/Users/try/work/admin当前ERP源码编写。这里是独立数据库模块,共28章,按能力递进组织;旧erp-backend-handbook保留作后端全景参考,本课程不用依赖旧教材即可学习。源码是案例,教学DDL与实例是独立练习,两者明确区分。

推荐打开本地阅读版:浏览器可直接打开,不需要付费Markdown阅读器,不上传文件。左侧筛选章节,⌘F/Ctrl+F搜索全部正文,支持系统深浅色和打印。原始Markdown仍可单独阅读;源码链接需和旁边项目目录一起保留,浏览器对本地源码的打开方式因系统而异。

学习顺序

先读00;不理解Java数据访问路径时提前读24。按01—09完成单库建模、SQL、索引和事务,再读10—13与21学习复制、分片、同步和恢复。14—17是Redis完整专题,18—20是MongoDB专题,25—27深入应用工具链。最后做22综合项目与23答辩。

每章都有机制、例子、失败边界与练习。不要以“看过”为完成,至少交出一份可重复实验记录:版本、结构、数据、执行顺序、预期、实际、差异解释。涉及版本或环境未核实的能力,不能默认为业务系统线上已启用。

第一部分:关系模型、SQL与性能

章 内容 学完需要能做什么
00 课程地图 数据模型、访问语言、并发、拓扑与工具链 用五层模型定位问题
01 关系建模与类型 主外键、关联表、范式、金额时间、NULL与约束 设计不会串租户、不会丢历史事实的表
02 SQL基础 CRUD、表达式、过滤、分组、排序与更新 从基础语法写完整查询
03 高级SQL JOIN、EXISTS、CTE、递归、窗口、游标 解释金额放大并正确改写
04 索引 B+树、回表、覆盖、联合、选择性、维护 从访问路径推导索引取舍
05 查询优化 EXPLAIN、真实行数、连接算法、规模实验 提交有正确性和成本证据的优化报告

第二部分:存储、事务与锁

章 内容 学完需要能做什么
06 存储与日志 页、buffer pool、redo、undo、binlog、恢复 解释提交、刷盘与崩溃边界
07 MVCC Read View、RC/RR、快照/当前读、写偏斜 预测两会话的可见结果
08 锁与死锁 记录/gap/next-key、MDL、死锁、库存 观察等待链并设计完整重试
09 应用事务 代理、传播、回滚、多数据源、批处理 保证Java边界与数据库事务一致

第三部分:数据拓扑与运维

章 内容 学完需要能做什么
10 主从与读写分离 复制链、GTID、延迟、切换、写后读 选择明确的读一致性策略
11 分库分表 路由、全局唯一、跨片查询与迁移 解释分片带来的新增代价
12 CDC 快照与增量、位点、重放、幂等、对账 避免丢事件与旧版本覆盖
13 PostgreSQL 聚合口径、PG语法、VACUUM、索引与计划 区分报表错误和性能瓶颈
21 运维与恢复 备份、PITR、在线DDL、迁移、故障排查 给出可演练的RPO/RTO与迁移方案

第四部分:Redis与MongoDB

章 内容 学完需要能做什么
14 Redis命令 String/Hash/List/Set/ZSet及扩展结构 按操作选择数据结构
15 Redis性能 编码、内存、过期淘汰、大键热点 定位慢命令和内存增长
16 缓存一致性 回填竞态、多级缓存、击穿、雪崩 定义陈旧预算与恢复协议
17 Redis可靠性 MULTI、Lua、锁、RDB/AOF、复制/集群 区分原子执行、持久化与分布式保证
18 MongoDB入门 BSON、文档边界、CRUD、数组、校验 避免ObjectId/null/数组语义错误
19 MongoDB进阶 管道、lookup、facet、索引、explain 写正确聚合并量出扫描成本
20 MongoDB集群 session、事务、关注、复制、分片 解释确认、可见性与重试边界

第五部分:ORM、工具链与综合实战

章 内容 学完需要能做什么
24 数据访问选型 ORM、SQL Mapper、Repository、真实调用链 知道每层自动做了什么
25 MyBatis与Plus XML、动态SQL、映射、Wrapper、分页与插件 从API追踪最终SQL及影响行数
26 Spring Data MongoDB Repository、Template、映射、聚合与事务 正确生成BSON并处理并发更新
27 数据库工具链 JDBC、Druid、超时、类型、流式批写、测试迁移 定位SQL之外的数据库访问问题
22 综合项目 库存预占、流水、幂等、缓存与任务投影 交付能证明不变量的数据库子系统
23 实验答辩 27组深度问题与答案骨架 用数据、时序和计划解释取舍

实验入口与验证

在课程根目录可执行python3 validate.py检查章节与本地链接,python3 labs/mysql/verify_relational.py验证有限关系结果,python3 labs/redis/verify.py运行独立Redis实验。SQL检查使用SQLite,不能替代MySQL实验。

更新本地阅读版

阅读HTML无需安装任何依赖。修改Markdown后,才需要Python Markdown包重新构建:

python3 -m venv .reader-venv
.reader-venv/bin/pip install -r requirements-reader.txt
.reader-venv/bin/python build_reader.py

流程图若以Mermaid源码存在,离线阅读版保留源码而不依赖外部渲染服务。SQL、Java和命令块按原样显示。浏览器打印可保存PDF,但长篇打印排版不等同经过出版级分页审校的PDF制品。

后续模块的衔接

数据库是第一模块。后续分布式模块将从本地提交边界延伸到RPC/MQ、事件、Outbox、Saga、幂等、顺序和故障恢复;高并发模块再从数据库容量延伸到流量模型、线程池、排队、隔离、限流、背压和压测。这些后续模块尚未在本目录交付,不用标题或待办冒充已完成正文。

原始文档 · database-course/00-课程地图与数据库思维.md

00 课程地图与数据库思维:从会调用接口到能证明数据正确

这是一套独立的数据库课程,不要求先通读旧的后端手册。课程围绕当前目录中的ERP项目展开,但练习使用独立教学数据。一次学习的最小单位是:理解一个模型,运行一个正常例子,再构造一个反例,最后解释结果与恢复方法。完成阅读是起点,能重复实验、解释执行计划、排查锁等待和证明业务不变量才是验收。

1. 你实际需要掌握的五层知识

前端常把接口看成输入JSON、输出JSON的函数。数据库把问题延伸到了请求之外:上次失败留下了什么,两个请求同时修改会怎样,服务器重启后什么仍然存在,另一个副本什么时候能看见结果。这些问题分成五层,不能只学SQL后跳过其余四层。

层次 核心问题 典型错误 对应阅读
业务模型 一行或一个文档代表什么事实 用商品现价重算历史订单 01、18、22
访问语言 怎么精确取出和修改目标集合 两张明细表JOIN后金额翻倍 02、03、14、19
执行机制 数据库做了多少工作 看见用了索引就认为已优化 04—06、15
并发与故障 谁能同时改、提交后保留什么 缓存锁过期后两个执行者都写库 07—12、17、20
应用与运维 SQL怎样生成、连接怎样管理、数据怎样恢复 线程池扩容把数据库压垮 09、21、24—27

“数据库、Redis、MongoDB、主从”不在同一个分类维度。MySQL、PostgreSQL、MongoDB、Redis是数据库产品;关系、文档、键值是数据模型;主从复制与分片是数据放置和传播方式;ORM、SQL Mapper、JDBC是应用访问方式。同一个MongoDB集群可以既有分片又有副本集,每个分片由自己的副本集提供复制。把这些词放在正确层次,才能讨论组合方案。

2. 全书贯穿的ERP问题

用一个具体订单贯穿全书:租户1的店铺收到订单,包含两个SKU,支付后预占库存,之后可能部分发货、部分退款,用户还要按天查看利润。这个业务至少包含订单事实、库存余额、库存流水、支付退款、查询报表五类状态。为避免初学时混淆,先采用以下教学规则,再逐步扩展。

订单明细记录成交时的单价、数量和币种。SKU保存当前商品信息,但不能覆盖成交快照。库存保存实物量与预占量,可用量定义为实物量减预占量。退款成功改变资金事实,退货入库改变库存事实,二者不能用一个布尔值表达。报表是事实的投影,允许按明确水位稍晚生成,但必须能够重算和对账。

假设SKU A实物10件,预占3件,则可用7件。新订单要6件,条件更新应在数据库内确认可用量足够,再把预占改成9件。并发订单再要2件时必须失败。若两个请求都先读7,再分别在Java里计算剩余数量,读到的条件不代表写入时仍然成立。这就是为什么前端里常见的“读状态—算新值—写回”到数据库并发场景必须重新设计。

订单成功的含义也必须具体:是本地订单已经提交,还是库存也已预占,还是外部平台也已确认?本模块集中解释本地数据库提交、跨存储可见性和恢复。后续分布式模块再系统展开RPC/MQ编排,不把数据库事务误写成能覆盖一切外部副作用的工具。

3. 四种存储各自怎样思考

MySQL:把关系和约束放在中心

关系表保存结构化事实,SQL描述集合操作,唯一键、外键、检查约束和事务共同维护局部正确性。不是所有系统都在线上使用物理外键;不用外键也必须回答引用完整性由谁验证、删除怎样处理、历史孤儿如何检测。应用校验可以提供友好错误,数据库约束负责抵挡竞争条件,两者不是重复建设。

MySQL通常适合订单、库存、结算等需要明确约束的核心数据。适合不代表任意SQL都会快。索引按照业务访问路径设计,事务按照业务原子性范围设计;二者相互影响,因为访问路径也影响锁定范围。不要只背“加索引提升查询”,还要衡量每次写入新增多少索引维护、页分裂和日志工作。

PostgreSQL:同样是关系库,机制和语法并不完全相同

SQL知识可迁移,隔离、版本回收、索引实现与执行计划不能机械照搬。课程结合利润报表讲聚合粒度、时间窗口、类型和VACUUM等问题。项目引入PostgreSQL协议驱动,只能证明客户端技术选择,不能凭此断言服务端必然是标准PostgreSQL、Hologres或某种列存产品。

MongoDB:围绕一起读取、一起更新的文档建模

订单可以嵌入有限的商品明细,让一次读得到完整订单。但不能无限嵌入所有历史操作日志;数组增长会让单文档尺寸、更新和索引成本失控。引用方式能减少重复,却需要额外读取或聚合。文档数据库不是“不需要设计结构”,而是把部分关系设计转成了文档边界和嵌套路径设计。

本目录实际有Spring Data MongoDB的Repository与MongoTemplate。课程据此讲任务、项目、用户、标签和历史集合的真实读取方式,再扩展到ERP教学模型。不能用一个JSON文件能成功存入来证明所有查询都合理;读路径、更新竞争、数组索引、唯一性和副本读语义一样要分析。

Redis:按操作语义选择数据结构

如果需要访问一个计数,不必存整个JSON后读出改写;计数命令能直接表达原子增量。如果需要排序积分,Sorted Set通常比应用下载整个集合再排序更合适。如果需要消息的待确认与重领,Streams与Pub/Sub的语义不同,不能只因都有“消息”就互换。

Redis里的值也需要数据契约:谁是权威来源,过期多久,缺失时如何重建,重复执行会怎样。数据库记录存在而缓存缺失通常可重建;如果不可替代的业务事实只放在易丢失缓存里,就不能再把它按“丢了也没关系”的缓存处理。持久化、复制和访问延迟是不同问题。

4. 统一看懂一次读和一次写

一次典型关系数据库读取经过:HTTP参数校验、可信租户上下文、Service业务条件、Mapper SQL生成、JDBC参数绑定、连接池借连接、数据库执行、ResultSet类型转换、DTO组装、JSON序列化。某个字段错了,先定位在哪个边界发生转换,而不是立即怀疑数据库。

例如Java long能保存的整数可能超出JavaScript安全整数范围;数据库中的分转成BigDecimal元后,又可能在JSON消费者里进入浮点计算。金额正确性是跨层契约,不能只靠选DECIMAL。时间也一样,时间戳、服务器时区、数据库会话时区和用户业务日不是同一个概念。

一次写入还要跟踪:唯一性判定、事务开始、锁等待、修改、提交、结果返回。客户端超时发生在提交后时,用户没看到成功,但数据可能已生效。重试前用同一业务幂等键查询或重放,不能生成新键当成新操作。连接异常也不能直接等同回滚,需要区分失败发生在提交前、提交中还是确认后。

因此阅读每段源码时都写六个字段:输入身份、查询谓词、约束、事务资源、提交点、失败恢复点。用这些字段读代码,比只记类名更有迁移价值。ORM节省重复映射,不负责替你定义正确的业务事务。

5. 阅读顺序和可验证里程碑

阶段 阅读 必须交出的成果
关系与语言 01—03 自己建模订单、标签,写出正确JOIN和窗口查询
性能 04—06 对同一查询给出数据分布、索引候选、实际计划与写成本
正确性 07—09 两会话复现并解释快照、阻塞、死锁和重试
数据拓扑 10—13、21 画读写路由与复制链,验证延迟读和恢复边界
Redis 14—17 按类型运行命令,复现旧缓存回填与锁过期
MongoDB 18—20 创建文档、聚合、索引,解释副本读与事务结果
应用工具链 24—27 从接口追踪到SQL或Mongo命令,并识别框架自动行为
综合验证 22—23 完成跨数据库选型、故障矩阵和答辩

工具链章节可以提前读:如果你还不知道Mapper怎么被调用,先读24、25,再回到SQL;如果对Mongo语法已有疑惑,先读18再读26。编号表示教材组织,不要求以一次线性阅读代替反复练习。

6. 每次实验记录什么

至少记录数据库服务端版本、客户端版本、表结构或文档结构、数据规模与分布、相关索引、隔离或一致性级别、执行顺序、原始结果和结论。如果涉及两个会话,用A/B明确每条语句由谁执行,不能只写“一边查询一边修改”。如果结论依赖锁等待,要保留等待期间的观察结果,而不只看最终值。

小数据验证语义,大数据验证成本;两者不能互相代替。四行数据能证明JOIN重复计算,但不能证明百万订单下最佳连接算法。百万行平均分布也不能代表一个大租户占80%流量的热点。实验先验证答案,再改变规模、选择性和并发,每次尽量只改一个因素。

错误也是结果。唯一键冲突、死锁受害者、乐观锁影响零行、Mongo重复键、Redis错误类型,都应映射为明确的业务处理。把所有异常都转换成“系统繁忙请重试”会掩盖不能重试的输入错误,也可能放大已经成功的操作。

本教材引用本地源码作为可检查证据,官方文档用于机制与版本核对。静态阅读不能确定线上物理索引、集群拓扑或动态配置。实验是否实际运行应看交付验证记录,不能把示例中写出的预期结果当成作者已经实测。

7. 起步练习与答案

练习一: 订单明细需要保存sku_id和成交价,为什么还要保存商品名快照?

答案: 当前商品资料可能改名、删除或拆分。订单详情与售后凭证应反映成交事实;是否保留哪些快照字段由审计与业务需求决定。引用当前SKU可用于导航和库存身份,不能替代历史快照。冗余并非自动违反良好建模,它在这里表达不同时点的事实。

练习二: Redis读写都很快,能否把订单余额也改成缓存后定时落库?

答案: 先说明丢失、重放和故障切换后的业务代价。若缓存已响应成功而落库前失败,谁保存被确认的事实?需要可靠日志、幂等重放、对账和明确的持久化保证,已经不是普通缓存替换。不能仅用平均延迟做决定。

练习三: 同一事务里读到了自己的更新,另一个副本没读到,矛盾吗?

答案: 不矛盾。本地事务可见性与副本应用进度是不同边界。先确认两次查询是否使用同一连接、同一数据库节点、同一事务或会话,再谈隔离级别。主库事务提交不自动让异步副本同步完成。

练习四: 一条SQL十毫秒,接口两秒,该先加什么索引?

答案: 不能先猜索引。拆解连接等待、SQL执行次数、结果传输、映射、RPC和排队。N+1可能执行了上百条十毫秒SQL;连接等待也可能占大多数时间。性能优化针对实际瓶颈,而不是只优化最容易看到的那一条语句。

原始文档 · database-course/01-关系建模与数据类型.md

01 关系建模与数据类型:把页面对象变成可验证的业务事实

本章面向会写表单、列表和接口调用,正在转向 ERP 后端的开发者。学习目标不是背会几种字段类型,而是能解释:一行代表什么,两个相同值是否代表同一件事,错误数据应该在哪一层被拒绝。先完成独立实验初始化,再把本章中的查询粘到自己的教学库。完整结构在 schema.sql〔本地文件〕,固定样本在 seed.sql〔本地文件〕。本专题只讲建模与查询,不展开事务和锁。

证据边界:项目事实来自当前工作区的标签 DDL 和 Mapper;lab_ 表是重新设计的教学模型,所有业务样本统一为 tenant_id=1。本章的结果是根据种子数据推导的预期,不是假装运行过的日志。未连接业务数据库,未核实线上版本、实际表结构或脚本部署状态。实验以 MySQL 8.4、InnoDB 为目标,不能从旧项目用了某种语法就推断其数据库版本。

1. 先说清楚“一行是什么”,再想字段叫什么

订单详情页常有一个对象,里面嵌着客户、明细数组、商品标签和收款记录。前端把它们组合在一起,是因为这些信息要同时展示。数据库拆开保存,是因为它们有不同的身份和生命周期:客户改名不等于订单重建;给商品增加标签不等于多了一条订单明细;同一张订单收两次钱,也不意味着订单出现两份。

因此建模的第一步是写自然语言定义。lab_sale 一行是一张订单,lab_sale_line 一行是订单中的一个行号,lab_payment 一行是一笔收款尝试,lab_item_tag 一行是某货品拥有某标签这一关系。特别注意收款尝试和成功收款的区别:待处理记录可以存在,但不能直接计入实收金额。表名无法替你完成业务口径定义。

关系基数会直接影响查询。一个订单有多条明细,属于一对多;一件货品能有多个标签,一个标签也能属于多个货品,属于多对多。多对多必须有一个承载关系的地方。把标签写成 "1,2",只能得到一个字符串,无法直接用外键校验每个标签,删除标签也变成字符串编辑。把它放进 JSON 数组虽然改善结构表达,却仍没有自动得到关系唯一性与引用完整性。JSON 适合某些弹性扩展属性,不应因为前端接收数组,就取代稳定的关联模型。

本实验的身份链是:客户到订单,订单到明细,明细到货品;货品经关联表到标签;订单另有收款记录。以后看一条复杂 SQL,先在纸上写出这条链,并给每个箭头标出“一”或“多”。第三章会证明,只要两个“多”在订单层直接相遇,金额就有被乘倍的可能。

2. 主键、唯一键和普通索引的承诺不同

主键承担行身份。教学表用 (tenant_id,sale_id) 标识订单,用 (tenant_id,sale_id,line_no) 标识明细。这里的行号只要求在同一订单中唯一,它不需要在全库唯一。不要把页面数组下标直接当行号:用户拖动排序时,展示位置可以变化,业务身份却不应因此改变。

业务唯一键描述另一类承诺。订单的 (tenant_id,sale_no) 不允许重复,即使两次导入生成了不同的 sale_id,同一业务订单号仍只能对应一张单。主键阻止身份重复,业务唯一键阻止业务事实重复,两者常常同时需要。普通索引只提供查找路径,不会自动拒绝重复;把 UNIQUE KEY 改成 KEY 看似只差一个单词,却改变了数据规则。

-- 在初始化后的教学库运行;预期唯一键冲突,不应成功插入。
INSERT INTO lab_tag (tenant_id,tag_id,tag_name,sort,enabled)
VALUES (1,99,'热卖',99,1);

-- 先看现有事实,不需要用应用猜测重复原因。
SELECT tag_id,tag_name FROM lab_tag
WHERE tenant_id=1 AND tag_name='热卖';
-- 预期:1 / 热卖。

为何前端校验和后端“先查再插”不能替代唯一键?设想时间线:请求甲查询标签名不存在,请求乙也查询不存在,甲保存,乙再保存。两边各自的判断在当时都可能成立,但最终要求是全体数据中只能有一个名称。唯一约束把这个要求放到存储边界。遇到冲突时,应用仍需区分“同一请求重复提交”和“两个不同意图用了相同名字”,不能一律返回新增成功。

唯一约束还受字符串比较规则影响。本实验显式选用 utf8mb4_0900_ai_ci;名称与编码是否区分大小写、重音,必须与产品规则一致。不要把比较规则当成无关紧要的默认配置。对于必须逐字节区分的外部编号,可以另行选择二进制字符串或适当的二进制排序规则,再用真实编号样本核对预期。

3. 用完整 DDL 表达多对多,而不是只画一条线

下面的建表语句已经包含在初始化脚本,阅读时不用重复执行。逐行理解比记住“建关联表”更重要。

CREATE TABLE lab_item_tag (
  tenant_id BIGINT NOT NULL,
  item_id BIGINT NOT NULL,
  tag_id BIGINT NOT NULL,
  PRIMARY KEY (tenant_id,item_id,tag_id),
  KEY idx_lab_tag_item (tenant_id,tag_id,item_id),
  CONSTRAINT fk_lab_it_item FOREIGN KEY (tenant_id,item_id)
    REFERENCES lab_item (tenant_id,item_id),
  CONSTRAINT fk_lab_it_tag FOREIGN KEY (tenant_id,tag_id)
    REFERENCES lab_tag (tenant_id,tag_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

主键防止重复绑定:同一货品同一标签只能出现一次。反方向索引支持“这个标签下有哪些货品”。两组外键要求货品和标签都确实存在,而且属于关系行指定的租户。外键的父键使用显式主键,避免依赖非标准的非唯一引用行为。MySQL 的列类型匹配、引用键要求与引用动作应按官方外键说明核对。

SELECT item_id,tag_id FROM lab_item_tag
WHERE tenant_id=1 ORDER BY item_id,tag_id;
-- 预期:(101,1)、(101,2)、(102,1)、(103,3)。

-- 预期外键失败:不存在教学货品999。
INSERT INTO lab_item_tag (tenant_id,item_id,tag_id) VALUES (1,999,1);

外键并不会自动帮 SELECT 加上租户条件,也不会证明当前登录者有权读取租户数据。它保护引用完整性,应用鉴权负责访问资格,SQL 负责正确关联。教学模型把租户放进键,是为了把边界显式化;实际项目的 user_id 是否等同租户,需要结合认证与路由实现判断,不能擅自重命名概念。

还要看删除语义。本实验没有声明级联删除,因此不能直接删掉仍被关系表引用的标签。产品可以选择先解除绑定、禁止删除或只停用标签,这些是不同业务行为。为了让一次 DELETE 顺利执行就关闭外键检查,会把“关系该如何处理”变成无人负责的遗留问题。

4. 类型不是存储长度表,而是数据契约

BIGINT 用于标识,不意味着前端可以安全地把任意 ID 放进 JavaScript Number。接口若可能传递超过安全整数范围的值,应以十进制字符串传递身份,前端无需对 ID 做四则运算。INT 适合本实验的整数件数,但称重商品需要额外设计数量单位、精度与换算规则,不能把公斤随意截断为整数。

金额采用 DECIMAL(12,2),含义是最多十二位十进制数字,其中两位在小数点后,不是十二位整数再加两位小数。它给定点数提供精确表达能力,但不会自动决定优惠怎么分摊、税额在哪一步舍入、不同币种能否相加。FLOAT 与 DOUBLE 适合允许近似误差的计算,不能因为数值显示有两位小数就认为其存储是精确金额。官方 DECIMAL 说明明确区分精确数与近似数。

SELECT sale_id,line_no,quantity,unit_price,
       quantity*unit_price AS line_amount
FROM lab_sale_line WHERE tenant_id=1 AND sale_id=1001
ORDER BY line_no;
-- 1号行:2 × 30.00 = 60.00;2号行:1 × 60.00 = 60.00。

字符串要区分身份、枚举和描述。sku_code 是业务编码,item_name 是可修改描述;订单状态是受控集合,而不是任意说明文字。本实验使用字符串状态加 CHECK,便于读者直接看懂。使用整数状态码也可以,但必须维护映射与合法值约束。TINYINT 本身不是“只能零或一”,因此标签启用列还要配合 CHECK(enabled IN (0,1))。

时间也有语义。下单时间与付款时间是两件事,付款前未知不应填当前时间。实验使用 DATETIME(6),并约定写入 UTC 的日历时间;DATETIME 自身不携带时区,设置会话时区不会替你自动转换任意 DATETIME 字面量。TIMESTAMP 有会话时区转换行为,范围也与 DATETIME 不同,选型请看官方日期时间类型。报表按北京时间自然日统计时,应先求出对应的 UTC 起止边界,再查询,不能把存储时间的日期部分直接当业务日。

5. NULL 表示缺少值,默认值表示你作出的决定

种子中笔记本成本为 NULL,收纳袋成本为 0。这两个值有意不同:前者尚未录入成本,后者是已知成本为零。若把它们统一显示为零,利润报表会把未知情况当成百分之百利润。前端表单的空字符串、未传字段、显式 NULL 与数值零也不应在后端入口无差别合并。

SELECT item_id,cost_price,current_price-cost_price AS margin
FROM lab_item WHERE tenant_id=1 AND item_id IN (103,104)
ORDER BY item_id;
-- 103 / NULL / NULL;104 / 0.00 / 30.00。

NULL 参与普通比较得到未知,cost_price=NULL 不是空值判断,必须写 IS NULL。CHECK 的语义也需要留意:检查表达式为 FALSE 才违例,为 UNKNOWN 可以通过,所以只写 CHECK(quantity>0) 不能代替 NOT NULL。本实验的数量既非空又大于零,分别约束“有没有”和“值是否合法”。依据见官方 CHECK 约束。

DEFAULT 只在适用的省略列等场景提供默认值,不应被理解成“任何非法输入都自动修好”。标签启用状态默认一,是教学上定义的新标签规则;付款时间没有这个默认值,因为“没有付款时间”不能推导出“现在刚付款”。可空唯一索引还允许多个 NULL,本实验收款外部编号可空,意味着尚未取得外部编号的多笔尝试可同时存在;一旦有编号,同租户下就不能重复。这不是幂等身份设计的完整替代方案。

6. 规范化与快照:什么时候重复是合理的

商品当前价和历史成交价看起来都叫价格,但对应不同时间的事实。种子里钢笔当前价为 35,订单 1001 成交价为 30。用明细快照计算是 2×30+1×60=120;若重新 JOIN 商品当前价计算,则变成 2×35+1×60=130。这种差额不是浮点误差,而是查询换了业务事实。

规范化关注依赖关系:商品名称依赖货品身份,标签名称依赖标签身份,不应在每条关联记录上复制一遍。快照则保留某时刻的事实:成交单价依赖订单明细身份,不能在商品涨价时跟着修改。把所有重复都消除,会破坏历史;把所有页面字段都复制,也会制造大量更新异常。判断依据是字段由谁决定、何时确定、以后是否应随源对象变化。

订单头总额是另一种冗余。它便于展示,但必须能与明细核对。外键只能保证明细引用了存在的订单,CHECK 也不能替你跨多行求和证明头明细一致。实验提供 Q15 对账查询〔本地文件〕,同时检查缺明细与金额不符。不能把缺明细的 NULL 汇总简单转成零后就宣称订单正常,否则零元异常订单会被隐藏。

7. 回到项目:证据是什么,推导到哪里停止

已读取的标签 DDL〔本地文件〕包含 item_tag 与 item_tag_relation。前者以 id 为主键,以 (user_id,tag_name) 为唯一键;后者以 id 为主键,并有 (user_id,sys_item_id,tag_id) 唯一键和 (user_id,tag_id,sys_item_id) 普通索引。脚本注释说明按 user_id 分库,这是仓库文本事实,不是线上路由验证结论。该脚本没有声明外键,也没有本实验的 CHECK。

关系 Mapper〔本地文件〕中的 batchInsert 使用 insert ignore,selectByUserIdAndSysItemIds 以用户和货品集合查关系。由此可以推导,唯一键是阻止重复绑定的重要存储条件;但不能仅凭 IGNORE 就断言业务接口满足全部幂等要求。IGNORE 可能把某些错误降为警告,调用方还需处理影响行数和输入异常。

标签 Mapper〔本地文件〕有 insertSelective、updateByPrimaryKeySelective 等不同写入形式。“选择性更新”通常只拼接非空字段,意味着 Java 的 NULL 可能表示“不更新”,未必表示“把数据库列清空”。这是 API 语义与 SQL 语义交界处必须确认的事。本章没有审计所有调用方,因此不把这一观察写成已证实的线上缺陷。

8. 练习与答案

练习一:给货品 101 再绑定一次标签 1,什么约束应拒绝?如果删掉唯一性,只保留反方向索引,会怎样?答案:PRIMARY KEY(tenant_id,item_id,tag_id) 拒绝重复,普通索引不会拒绝。重复关系可能让标签列表重复,并使后续 JOIN 多出行。实验先查询确认已有绑定,再单独执行预期失败的 INSERT;不要把失败示例混进一键初始化脚本。

练习二:为什么明细不能只保存当前货品 ID,不保存成交价?答案:货品当前价会变,历史订单金额应保持当时的价格口径。样本已提供反证:订单 1001 由 120 被误算为 130。你可以只用 SELECT 分别计算两种金额,无需修改商品价格就能观察差异。

练习三:能否把未知成本统一设零来让 SUM 不返回 NULL?答案:不能在存储层这样偷换含义。应分别统计已知成本的金额与未知成本的记录数,报告完整性,再由业务定义是否允许出具利润。仅显示合计数会让使用者误以为覆盖了全部商品。

练习四:外键已经有租户列,JOIN 是否可以省掉租户列?答案:不可以。外键控制写入关系是否合法,JOIN 决定哪些行参与组合;两者承担不同职责。即便当前样本只有租户一,也要写出完整关联条件,不能用样本碰巧不冲突证明省略是正确的。

完成标准是能为每张表说出粒度、身份、唯一性、引用边界和空值含义,并能解释每个约束阻止哪一种具体错误。下一章把这些承诺带入完整 SQL,观察一个条件放错位置如何改变结果。

原始文档 · database-course/02-SQL基础到完整查询.md

02 SQL 基础到完整查询:从逐行条件走到可对账的结果

本章沿用第一章的七张教学表。你会从一次 SELECT 开始,逐步补齐条件、表达式、分组、排序和分页,再学习可控的增删改。目标是看到一条 SQL 就能说明输入是什么、每一步改变了哪些行、最后一行代表什么。所有示例的租户都是 tenant_id=1,初始化入口为实验 README,查询编号对应 queries.sql〔本地文件〕。

事实与教学边界:代码引用来自本地标签 DDL 和 Mapper。下面的订单、金额和故障过程均为教学构造,表中结果是固定种子推导,不是业务执行日志。本次未连接 MySQL 或业务服务;涉及语法的目标版本为 MySQL 8.4,参考官方 SELECT 语法。实际项目的数据库版本和动态 SQL 最终形态仍需在隔离环境核实。

1. SELECT 不是把表搬到 JavaScript 再过滤

前端习惯先拿到数组,再用 filter、map、sort。SQL 则声明需要什么结果,由数据库决定如何读取。不要为了接近前端思路而查询全部订单,再在 Java 中筛掉不需要的行;这会把数据传输、内存占用和租户过滤责任转移到更脆弱的位置。不过用数组流水线帮助理解逻辑步骤是有价值的,前提是不把逻辑步骤当成物理执行顺序。

SELECT sale_id,sale_no,total_amount
FROM lab_sale
WHERE tenant_id=1
ORDER BY sale_id;

该查询投影三列,返回四行:1001 的金额 120,1002 的金额 120,1003 的金额 50,1004 的金额 30。SELECT * 适合临时查看小样本,却不适合作为稳定接口的默认契约;表增加字段可能扩大传输,也可能暴露本来无需展示的内容。显式列名还让后续覆盖索引分析有明确对象。

表别名负责区分来源,列别名负责命名输出。s.total_amount AS amount 不会修改表中列名,只改变本次结果的名称。没有 ORDER BY 时结果没有可靠顺序,即使你连续执行几次恰好按主键返回,也不能把偶然观察当作分页协议。

2. 先掌握完整结构,再逐步装入业务条件

下面是本章使用的完整查询骨架。方括号表示可选语法,不是可以原样执行的 SQL;复杂的 UNION、窗口函数在第三章继续展开。

[WITH 临时结果名 AS (查询), ...]
SELECT [DISTINCT] 表达式 [AS 别名], ...
FROM 表名 [AS 别名]
[JOIN 另一张表 ON 关联条件]
[WHERE 逐行条件]
[GROUP BY 分组表达式, ...]
[HAVING 分组条件]
[ORDER BY 排序表达式 [ASC|DESC], ...]
[LIMIT 返回条数 [OFFSET 跳过条数]];

逻辑理解可以按“建立来源与关联、逐行筛选、形成分组、筛选分组、计算展示结果、去重、排序、截取”展开。优化器可能把条件提前、改变连接顺序,这不影响你先验证逻辑语义。窗口函数通常在分组和 HAVING 之后处理结果,不能凭它在 SELECT 中出现,就认为 WHERE 能直接引用它的别名。

第一步只找已付订单:

SELECT sale_id,total_amount FROM lab_sale
WHERE tenant_id=1 AND status='PAID'
ORDER BY sale_id;
-- 1001/120.00,1002/120.00。

第二步加时间边界:

SELECT sale_id,total_amount FROM lab_sale
WHERE tenant_id=1 AND status='PAID'
  AND ordered_at>='2026-01-01'
  AND ordered_at<'2026-02-01'
ORDER BY sale_id;

采用左闭右开区间,既包括一月一日零点,又排除二月一日零点。BETWEEN 包含两个端点,如果结束值写一月三十一日零点,会漏掉这一天剩余时间;若写成 23:59:59,又会遗漏微秒精度的尾部。半开区间还方便相邻月份首尾拼接而不重叠。

3. 布尔表达式必须像接口权限一样仔细审查

AND 与 OR 的优先级不同,下面的条件会让第二条分支脱离租户约束:

-- 错误模板:OR后面的NEW分支不受tenant_id条件限制。
SELECT sale_id FROM lab_sale
WHERE tenant_id=1 AND status='PAID' OR status='NEW';

-- 正确表达:先决定租户,再决定允许哪些状态。
SELECT sale_id FROM lab_sale
WHERE tenant_id=1 AND (status='PAID' OR status='NEW')
ORDER BY sale_id;
-- 本实验预期:1001、1002、1003。

当前只有一个租户,所以错误写法可能得到同样结果。这恰好说明测试样本通过不等于逻辑安全。审查时应展开括号,把每一条 OR 分支看成一条独立路径,确认租户、状态、日期等共同限制没有漏到某个分支之外。

IN ('PAID','NEW') 是等值候选集合的简写,NOT IN 则必须检查空值,第三章给出反例。LIKE 'SO-%' 表示前缀匹配,百分号匹配任意长度,单个下划线匹配一个字符。如果用户输入本来包含百分号或下划线,应用必须按约定转义或明确提供通配符搜索,否则“按字面搜索”会变成扩大匹配。= 是等值判断,不能与 LIKE 的模式语义混为一谈。

比较类型也属于条件正确性。把编码 '00123' 当数字 123 比较,可能失去前导零语义;把字符串列与数值参数混比还可能引入隐式转换。JDBC 绑定参数时应使用与列契约相符的类型,不能只靠数据库“能自动转”就认为输入可靠。

4. NULL 的三值逻辑会悄悄删除结果行

SQL 条件不只有真和假,还可能是未知。WHERE 只保留结果为真的行。样本中订单 1003、1004 的 paid_at 是 NULL,执行 paid_at=NULL 不会找出它们,因为普通等号无法证明一个未知值等于另一个未知值。正确语法是 IS NULL;反向判断是 IS NOT NULL。MySQL 的 <=> 是空值安全等号,可用于确实需要把两个 NULL 视为相等的比较,但不能替代业务上的空值定义。官方 NULL 说明给出了这种比较语义。

SELECT COUNT(*) AS all_rows,COUNT(paid_at) AS known_paid_times,
       SUM(CASE WHEN paid_at IS NULL THEN 1 ELSE 0 END) AS missing_paid_times
FROM lab_sale WHERE tenant_id=1;
-- Q01预期:4 / 2 / 2。

COUNT(*) 数结果行,COUNT(列) 数该列非空值,不是去重数。COUNT(DISTINCT customer_id) 才数非空的不同客户编号;样本为二,因为匿名客户 NULL 不参与该计数。若产品想把匿名客群也算成一类,要明确表达这个新口径,不能让一个默认统计函数代替需求决定。

SUM、AVG 忽略 NULL 输入,且没有可聚合值时通常返回 NULL。忽略并不意味着未知值变成零:三个成本中有一个未知,平均值分母可能只剩两个。COALESCE(value,0) 是显式业务选择,适合“没有成功收款则实收零”,不适合“不知道成本则成本零”。为了让页面好看而统一填零,会把数据缺失藏起来。

5. 从逐行计算到分组:先问统计单位

逐行表达式不改变行数。例如把每条明细的 quantity*unit_price 命名为行金额,仍是一条明细一行。GROUP BY 则把多行收拢为一组一行。按客户统计时,输出的每一行已不再是订单,不能随意携带某张订单号。这个粒度变化,是分组查询最重要的思维转折。

SELECT customer_id,COUNT(*) AS sale_count,
       SUM(total_amount) AS paid_total,
       AVG(total_amount) AS average_amount
FROM lab_sale
WHERE tenant_id=1 AND status='PAID'
  AND ordered_at>='2026-01-01' AND ordered_at<'2026-02-01'
GROUP BY customer_id
HAVING SUM(total_amount)>=200
ORDER BY paid_total DESC,customer_id ASC
LIMIT 10 OFFSET 0;
-- Q03预期:501 / 2 / 240.00 / 120.00。

逐步推导:四张订单先按租户、状态、日期筛成两张;两张订单属于同一客户,所以变成一组;组内订单数为二,总额为二百四十,平均额为一百二十;HAVING 保留总额不少于二百的组;最后排序截取。这份解释应能独立于执行计划成立,因为它在描述结果为何正确。

WHERE 不能写 SUM(total_amount)>=200,因为逐行筛选时还没有组内总额;HAVING 可以。反过来,把本应在 WHERE 中表达的日期筛选藏进 HAVING,既容易混淆语义,也可能扩大中间数据。按状态条件统计多个指标时可用条件聚合:

SELECT COUNT(*) AS total_count,
       SUM(CASE WHEN status='PAID' THEN 1 ELSE 0 END) AS paid_count,
       SUM(CASE WHEN status='PAID' THEN total_amount ELSE 0 END) AS paid_amount
FROM lab_sale WHERE tenant_id=1;
-- 4 / 2 / 240.00。

这种写法同一次输入扫描产生多个口径,但每个 CASE 仍需有明确的状态规则。订单状态为已付和收款表实收相等,是本实验的样本事实,不是所有 ERP 都必须满足的恒等式;退款、补款和确认延迟都会要求重新定义指标。

6. 分组错账:语法通过并不代表业务正确

反例一是按客户分组,却同时选择订单号:

-- 预期在ONLY_FULL_GROUP_BY模式被拒绝。
SELECT customer_id,sale_no,SUM(total_amount)
FROM lab_sale WHERE tenant_id=1
GROUP BY customer_id;

客户 501 有两张订单,数据库不能知道应该显示 SO-001 还是 SO-002。关闭 ONLY_FULL_GROUP_BY 只是允许选择不确定值,并不会把“客户最后一张订单”的需求自动补上。使用 MAX(sale_no) 则改成了字典序最大订单号,也不等于按下单时间最新。应在第三章用窗口函数或明确的关联条件取整行。

MySQL 允许有可证明函数依赖的非分组列,所以规则并不是“SELECT 中所有列必须无条件写进 GROUP BY”。例如一个非空唯一键可以确定同行其他属性。教学时先要求每个输出字段都有清晰来源,再理解函数依赖的例外,比机械增加分组列更安全。官方 GROUP BY 说明解释了拒绝规则与依赖判断。

反例二是用金额去重。两张已付订单恰好都为 120,SUM(total_amount) 为 240,SUM(DISTINCT total_amount) 却为 120。DISTINCT 删除相同的值,不理解业务身份。即使它恰好修正了某个 JOIN 引起的重复,也会错误合并真实存在的同金额订单。第三章会在多表关联里把这个错误完整展开。

反例三是把所有订单金额相加称为收入。全表合计是 320,已付订单合计是 240。取消订单的 30 和未付款订单的 50 可以作为订单录入金额存在,却不应该混入本实验的已付口径。数据库算术正确,但字段名称和报表标题错了,同样属于错账。

7. 排序与分页:必须把并列情况写进协议

SELECT sale_id,ordered_at FROM lab_sale WHERE tenant_id=1
ORDER BY ordered_at DESC,sale_id DESC LIMIT 2 OFFSET 0;
-- 第一页:1004、1003。

1002 与 1003 的下单时间相同,所以只按时间排序不能保证它们的相对位置。追加唯一的 sale_id 后,排序形成稳定的全序。分页需要这样的决胜字段,窗口排名、导出续传也一样。不能用“日常大多不会同一微秒创建”来省略正确性条件。

偏移分页写法简单,适合浅页和需要跳页的界面,但较深页通常仍要处理被跳过的记录。如果两次分页之间数据改变,OFFSET 还可能重复或遗漏。游标分页用上一页的最后一组排序值继续:

SELECT sale_id,ordered_at FROM lab_sale
WHERE tenant_id=1 AND (
  ordered_at<'2026-01-02 09:00:00' OR
  (ordered_at='2026-01-02 09:00:00' AND sale_id<1003)
)
ORDER BY ordered_at DESC,sale_id DESC LIMIT 2;
-- Q16预期:1002、1001。

如果只写 ordered_at<上一页时间,1002 就会被漏掉。游标需要保存完整排序键及筛选条件;前端换了状态条件之后不能沿用旧游标。游标也不是历史快照,后续修改排序字段仍会影响遍历,稳定导出需要另定业务截点,此处不展开并发控制。

8. 增删改要给出前置条件、影响范围和结果核对

只在教学库单独运行下面一组语句,执行完成后恢复原始种子状态。它演示完整列清单、显式条件与核对查询,而不是提供业务批量改数脚本。

INSERT INTO lab_tag (tenant_id,tag_id,tag_name,sort,enabled)
VALUES (1,90,'教学临时标签',90,1);

SELECT tag_id,sort FROM lab_tag WHERE tenant_id=1 AND tag_id=90;
UPDATE lab_tag SET sort=91
WHERE tenant_id=1 AND tag_id=90 AND sort=90;
SELECT tag_id,sort FROM lab_tag WHERE tenant_id=1 AND tag_id=90;
-- 预期由90变91;影响行数还受客户端“匹配行/改变行”设置影响。

DELETE FROM lab_tag WHERE tenant_id=1 AND tag_id=90;
SELECT COUNT(*) FROM lab_tag WHERE tenant_id=1 AND tag_id=90;
-- 预期0。

UPDATE 表 SET 列=表达式 WHERE 条件 与 DELETE FROM 表 WHERE 条件 的 WHERE 不是可有可无的装饰。删掉租户和身份条件会把操作范围扩大到整个表。写修改语句前先写同条件 SELECT,可以检查意图;但不能把这一步宣传成任何时刻都保证不变化的安全机制。

普通 INSERT 遇到唯一冲突报错;INSERT IGNORE 可能将某些错误降为警告;ON DUPLICATE KEY UPDATE 遇到主键或唯一键冲突转为更新。它们是不同业务选择,不能为了“接口不报错”互相替换。项目标签 Mapper 的 batchInsert 结合 IGNORE 和冲突更新,并使用 VALUES(column);该用法在 MySQL 8.4 文档中已标记弃用,迁移应核查服务器版本及行别名语法,本文不修改项目代码。官方冲突更新说明。

9. 把 SQL 读回 Mapper,找出动态部分

标签 Mapper〔本地文件〕的 selectByExample 先选择基础列,再按 Example 拼接条件,最后通过 ${orderByClause} 拼接排序。${} 是文本替换,不能接收任意用户排序字符串;排序字段与方向应从服务端白名单映射。#{} 用于值绑定,但表名、列名、ASC/DESC 不能简单当作普通值参数替换。这里观察到的是 Mapper 的拼接方式,未检查调用链是否已经做好白名单,因此不是线上漏洞结论。

关系 Mapper〔本地文件〕通过 foreach 生成 IN 列表。输入空集合时,业务必须明确返回空结果、忽略筛选或拒绝请求,不能让模板生成不完整 SQL;大集合还应考虑 SQL 长度与参数规模。查标签关系只返回关系行,不会自动带上标签名称和启用状态,需要调用层或 JOIN 明确补齐。

对照标签 DDL〔本地文件〕,tag_name 非空且同用户唯一,enable_status 是有效状态字段。生成查询时要决定“停用标签是否保留历史关联”。只会按字段名拼 WHERE,而没有这个语义决定,就可能把历史记录过滤掉或让停用标签继续出现在选择器。

10. 练习与答案

练习一:统计租户一的订单总数、已付数量和未填付款时间数量,应该有几行结果?答案:没有 GROUP BY 时聚合为一行,依次为四、二、二。若误加 GROUP BY status,结果就变成每状态一行,接口结构与分母也改变了。

练习二:查询一月二日订单,为什么不用 BETWEEN '2026-01-02' AND '2026-01-03'?答案:BETWEEN 会包含三日零点,正确范围为大于等于二日、小于三日。样本当前没有三日零点订单,所以两种结果可能相同;仍应按边界语义判定,而不是只比较眼前输出。

练习三:客户汇总里添加 sale_no 后报错,同事建议关闭完整分组模式,如何处理?答案:先澄清订单号到底代表什么。如果要最新订单,应使用第三章排名后取一行再与汇总关联;如果只是客户金额报表,则删去订单号。关闭检查无法补全业务定义。

练习四:第二页少了订单 1002,检查什么?答案:先检查排序是否有唯一决胜键,再检查游标是否同时带上时间和 ID、比较方向是否与降序一致。样本两笔同时间订单就是专门为此设置的反例。不要先怀疑数据库丢数据。

练习五:如何证明结果没有串租户?答案:审查每个 OR 分支、每个 JOIN 条件与子查询的租户作用域,并确认参数来源受服务端身份约束。单租户样本只能验证本题预期,不能充当完整权限测试。学会明确测试能证明什么,和学会写 SELECT 同样重要。

原始文档 · database-course/03-JOIN子查询CTE与窗口函数.md

03 JOIN、子查询、CTE与窗口函数

本章使用labs/mysql/schema.sql〔本地文件〕、种子〔本地文件〕与查询集〔本地文件〕。基线MySQL8.4;CTE与窗口在MySQL5.7不可直接使用。先读02章的NULL与分组语义,再运行Q04—Q16、Q19。以下数字由固定种子推导,是否实际运行看验证记录。

1. 连接不是把两个数组按位置拼起来

JOIN为每个左行寻找所有满足ON条件的右行。若左行匹配三个右行,产生三行;若另一张子表又匹配两个,可能产生六行。SQL不会自动知道“这是同一个订单,所以金额只算一次”。写查询前在纸上写目标粒度:一行订单、一行客户还是一行商品。

INNER JOIN只保留匹配;LEFT JOIN保留左行,无匹配时右侧补NULL;CROSS JOIN生成组合,可用于日期×店铺骨架,也可能因遗漏条件造成爆炸。MySQL没有直接的FULL OUTER JOIN语法,可用左连接与另一方向的未匹配集合UNION ALL实现。不能简单把两个完整LEFT JOIN拼起来,那会重复匹配部分。

所有实验表使用tenant_id组成身份。sale_id=1001只是租户内的订单,关联必须比较tenant_id和sale_id。数据库约束保障允许写入的关系,ON决定这次查询实际组合哪些行。已有外键不意味着JOIN可以省略租户。

2. 订单1001的错误报表逐行拆解

1001有钢笔2×30、水杯1×60两行商品;收款70、50两笔。直接关联订单、明细、收款得到:钢笔/70、钢笔/50、水杯/70、水杯/50。SUM商品得240,SUM收款也得240,正确值各为120。

SELECT s.sale_id, l.line_no, p.payment_id,
       l.quantity*l.unit_price AS line_amount, p.amount
FROM lab_sale s
JOIN lab_sale_line l
  ON l.tenant_id=s.tenant_id AND l.sale_id=s.sale_id
JOIN lab_payment p
  ON p.tenant_id=s.tenant_id AND p.sale_id=s.sale_id
WHERE s.tenant_id=1 AND s.sale_id=1001 AND p.status='SUCCESS'
ORDER BY l.line_no,p.payment_id;

调试聚合时先删除SUM和GROUP BY,展示事实身份,是发现重复的有效方法。SUM(DISTINCT amount)不能修复:订单1001和1002总额都为120,Q07显示真实总额240,而DISTINCT只剩120。去重必须按业务事实身份进行,不能按金额值。

Q06先将明细和成功收款分别GROUP BY tenant_id,sale_id,再连接订单;中间结果每订单最多一行,因而不会相乘。1001和1002商品额/收款均120,未付款1003为50/0,取消1004排除。使用INNER JOIN商品聚合意味着无明细订单不会展示;Q15单独检查缺明细或头明细金额不符,不能把异常静默丢弃。

优化时先筛目标订单,再聚合相关子表,避免每次小页面都汇总全历史。Q14演示先选“含热卖商品的已付订单”,再汇总其所有明细。若把tag过滤放在商品汇总内部,会只统计热卖商品金额,结果口径已改变。

3. ON与WHERE是不同的边界

Q04把status='PAID'写在ON中,返回客户501两单240,502零单,503零单。移到WHERE后,502的取消订单不满足,503补空行也不满足,两者消失。COUNT(s.sale_id)统计匹配订单;COUNT(*)会把补空行也算作一单。

COALESCE适用于业务已定义的“没有付款就是付款合计零”;未知成本不应同样改零。NULL比较还有三值逻辑:NOT IN集合里有NULL时,不能证明某值与全部未知值都不同。Q11错误写法无结果,NOT EXISTS返回从未下单客户503。

SELECT c.customer_id
FROM lab_customer c
WHERE c.tenant_id=1 AND NOT EXISTS (
  SELECT 1 FROM lab_sale s
  WHERE s.tenant_id=c.tenant_id AND s.customer_id=c.customer_id
);

相关子查询的写法不代表执行时必然完整执行N次。优化器可能将EXISTS转换为半连接;是否发生要看计划。SELECT 1只是表示不需要子查询投影,不是性能秘诀。

4. 标签查询体现“任意、全部、没有”的集合差异

任意拥有标签1或2:对商品使用EXISTS,Q08返回101、102。全部拥有标签1和2:过滤关联表到目标集合,按商品分组并要求COUNT DISTINCT=2,Q09只返回101。输入[1,1,2]先去重,不能使用原始数组长度3。

没有任何标签是104;没有有效标签则103和104,因为103绑定的是禁用标签。不存在关系与关系指向失效主数据不是同一条件。空筛选集合也需要产品定义:任意空集合通常无结果,满足全部空条件可能代表不过滤;不要生成IN ()。

源码对应标签关联Mapper〔本地文件〕与DDL〔本地文件〕。思考双向访问为何使用两个不同顺序的索引,然后到04章验证。复杂SQL的第一步是定义集合语义,之后才是索引。

5. CTE让粒度可读,但不承诺缓存

WITH为查询命名中间结果,能分离目标订单、商品聚合与收款聚合。它不是创建永久表,也不保证只计算一次或一定比子查询快。MySQL可按规则合并或物化,物化涉及中间存储和索引成本。相同逻辑要用实际计划比较,不能按语法长短判断性能。

递归CTE由锚点与递归分支组成。Q19生成1月1—3日再LEFT JOIN日汇总,输出120、120、0。没有日期骨架时,根本没有订单的日期不会出现,COALESCE也无行可补。

WITH RECURSIVE dates(d) AS (
  SELECT CAST('2026-01-01' AS DATE)
  UNION ALL
  SELECT d + INTERVAL 1 DAY FROM dates WHERE d<'2026-01-03'
)
SELECT d FROM dates ORDER BY d;

递归必须有终止条件并控制层数。层级组织、BOM可以保存路径防循环;仅限制递归次数只能防无限运行,不能证明数据无环。锚点列的类型与长度要能容纳递归扩展结果,长路径可显式CAST。大型日期报表常用持久日期维表更便于节假日和会计周期管理。

6. 窗口函数保留明细并观察邻居

GROUP BY将多行压为一行,窗口函数保留输入行,给每行附加分组统计或顺序。Q12按ordered_at,sale_id逐行累计得到120、240、290、320。这里统计全部订单,含未付与取消;如果产品要实收累计,必须先调整输入集合而不是只修改列名。

SELECT sale_id, customer_id, total_amount,
       ROW_NUMBER() OVER (
         PARTITION BY tenant_id,customer_id
         ORDER BY ordered_at DESC,sale_id DESC
       ) AS sequence_no,
       LAG(total_amount) OVER (
         PARTITION BY tenant_id,customer_id ORDER BY ordered_at,sale_id
       ) AS previous_amount
FROM lab_sale WHERE tenant_id=1 AND customer_id IS NOT NULL;

ROW_NUMBER给唯一序号;RANK同值同名次且跳号;DENSE_RANK同值同名次不跳号。若订单按金额120、120、50排序,三者分别1/2/3、1/1/3、1/1/2。若给RANK排序又加入唯一ID,同金额就不再并列。用哪一种取决于“最多两条”还是“前两档金额”。

同层WHERE不能直接过滤刚计算的窗口别名,Q13使用外层查询筛rn=1。将过滤提前可能改变排名范围:“全站前十中本店的订单”不同于“本店前十”。窗口默认frame也可能按同值RANGE一起累计,逐行累计应显式ROWS,并定义稳定排序。LAST_VALUE尤其容易只返回当前frame最后值;要取整个分区末尾,显式指定到UNBOUNDED FOLLOWING。

7. 游标分页与查询一致性

Q16降序页面的最后位置是时间1月2日9点、ID1003;续页条件是时间更小,或同时间ID更小,得到1002、1001。只用时间小于会漏1002。复合行比较可以更短,但NULL、方向混排和优化器范围提取需要逐项验证,不能为简洁改变语义。

项目广告Mapper〔本地文件〕有多列游标和NULL分支。阅读时先抄ORDER BY,再逐段对照续页条件;唯一尾键和过滤条件必须一致。游标应绑定租户、筛选和排序版本,防止跨查询误用。

游标不自动提供快照。翻页间排序字段修改仍可能遗漏或重复,长时间导出需要业务水位、不可变排序键或一致性快照策略。保持一天的数据库事务虽然能保住某些快照,也可能阻碍版本回收、占连接和拖累存储。

8. 综合练习

  1. 找“至少有一笔成功收款,但收款少于商品额”的订单。先分别聚合,再筛成功收款大于零且小于商品额;种子无结果。单独把1001的一笔成功付款改为PENDING后应出现1001,实验后ROLLBACK。
  2. 每个客户按订单金额排名,保留并列第一。使用RANK按金额降序,不能加入订单ID破坏并列;501应得到1001与1002。最终展示可在外层再按ID排序。
  3. 对所有客户展示2026-01-01至03每日已付额。客户CROSS JOIN日期骨架,然后LEFT JOIN按客户日期聚合结果。预期3客户×3天9行,未匹配额零。
  4. 为什么Q14不能用JOIN标签后直接SUM明细?同一个商品可能有多个目标标签,标签关系再次复制明细。用EXISTS筛选订单或先对目标关系去重,再保持约定粒度。

官方机制:JOIN、CTE、窗口函数。语法支持、物化策略和计划都要按实际服务端版本复核。

原始文档 · database-course/04-索引原理与设计.md

04 索引原理与设计

本章沿用MySQL实验。索引不是某列旁边的“加速开关”,而是一份额外维护的有序访问结构。理解其排序、记录内容、扫描范围和维护成本,才能从SQL推导候选索引。先验证语义再验证成本,不能以错误结果更快为优化成功。

1. B+树为什么适合数据库

磁盘和内存之间以页读取数据,比起逐条随机查找,在一页中保存许多键能减少树高。内部页导航,叶子页承载记录或定位信息;叶子顺序便于范围扫描。树高少不代表请求永远只需固定几次IO:缓存命中、回表数量、锁等待、页分裂和扫描长度都影响耗时。

InnoDB以聚簇索引组织表,通常主键叶子就是完整行。二级索引叶子包含二级键和主键值,找到它后可能还要按主键查行,这叫回表。若查询字段全部可从索引取得,可能使用覆盖扫描,减少访问宽行。MVCC可见性等实现条件仍可能需要查聚簇记录,因此覆盖不是任何场景绝不访问表的保证。

主键过宽会放大二级索引,因为多个二级索引都要携带主键。随机主键可能增加分散写入和页分裂;递增主键改善局部性,也可能在高并发出现右端热点。选择ID不能只说UUID不好或自增最好,还需考虑分布式生成、枚举暴露、写入模式和存储成本。

2. 联合索引是按元组排序

索引(tenant_id,status,ordered_at,sale_id)先排租户,租户相同时排状态,再排时间,再排ID。想象电话簿按城市、姓、名排序:给定城市和姓可以找到紧凑范围;只给名一般不能直接定位一个连续小段。

EXPLAIN SELECT sale_id FROM lab_sale
WHERE tenant_id=1 AND status='PAID'
  AND ordered_at>='2026-01-01' AND ordered_at<'2026-02-01'
ORDER BY ordered_at,sale_id;

等值前缀tenant_id/status固定后,时间范围缩小扫描,时间与ID的顺序也可能直接服务ORDER BY。若不限制status却想按时间全局排序,同一租户下不同状态各有自己的时间段,不能简单按该索引顺序得到全局时间顺序,所以实验另有(tenant_id,ordered_at,sale_id)。

所谓“范围后索引失效”过于粗糙。后续列也许不能继续缩小连续扫描边界,但仍能用于索引条件下推、覆盖或过滤。key_len提示参与定位的键长度,不等于整个索引剩余列毫无作用。前导列缺失时优化器也可能全索引扫描或在满足条件的版本使用skip scan;这并不推翻前导列对高效定位的重要性。

3. 用项目标签关系推导两个索引

项目DDL〔本地文件〕定义主键id、唯一键(user_id,sys_item_id,tag_id)和普通键(user_id,tag_id,sys_item_id)。第一份保证不重复绑定,也支持给定用户与商品查标签;第二份支持给定用户与标签查商品。两份列集合相同,排序不同,访问能力不同。

若查询只返回sys_item_id,反方向索引可能覆盖;若还要商品标题、价格,需关联商品表或回到其他数据。索引应围绕实际输出和筛选,不应为追求覆盖把很长标题、JSON或不断变动字段全部塞进去,写入代价可能得不偿失。

实验的lab_item_tag使用复合主键,而项目使用独立id主键;这是教学结构差异。实验结构不能直接拿来替换生产表,尤其要考虑其他外键、分片、历史重复和ORM主键假设。

4. 选择性、基数与数据倾斜

基数是不同值的数量,选择性关注条件命中多少比例。状态只有三个值不意味着索引永远无用:若某个错误状态只占十万分之一,过滤它可能很有效;在联合索引中等值状态还能帮助时间扫描与排序。反过来,唯一手机号选择性高,但报表根本不按手机号查询,索引就帮不上忙。

大租户占80%行、小租户只有几十行时,同一SQL模板的最佳计划可能不同。统计信息是估计,不是精确知道每组参数。表变化后需要观察估计与实际偏差,再考虑ANALYZE TABLE或适用直方图。不能把强制索引当常态修复,否则数据分布变化后可能锁死在旧选择。

单列统计还可能低估列相关性,例如国家与城市、租户与店铺。加入联合索引有时既改善访问路径,也提供不同统计信息,但仍要用代表性参数检查,而不是只跑一组测试。

5. 让谓词可定位

SELECT sale_id FROM lab_sale
WHERE tenant_id=1 AND ordered_at>='2026-01-02'
  AND ordered_at<'2026-01-03';

这比在列上套DATE更直接表达时间范围。函数索引或生成列可能支持特定表达式,但不是任何函数都可用,且会增加维护。时间区间用半开形式避免漏掉微秒尾部;业务时区先转换成正确的起止时刻,不能把UTC自然日与北京时间自然日混为一谈。

类型也影响谓词。字符串编号与数字比较可能引入隐式转换、改变结果语义或索引使用;不同字符集和排序规则的JOIN也需要留意转换。参数用与列匹配的类型绑定,不能看起来都是“123”就视为等价。

前缀LIKE如abc%在合适排序规则和计划下可形成范围;%abc%通常不能利用普通B+树做同样的前缀定位。全文索引是另一套检索语义,不等价于任意子串搜索。中文分词、停用词、最短词长和相关性均需单独设计。

6. 索引维护与唯一性细节

每次INSERT可能写聚簇页和多个二级页,产生日志并消耗缓存;UPDATE若修改索引列也需维护相应结构。过多索引使写放大、备份和恢复时间增长,优化读取不能忽略ERP批量导入成本。

唯一键保护数据库层竞争,但允许NULL的唯一键在MySQL中可容纳多个NULL。实验付款external_ref可空,因此未获得外部交易号的多条记录可以共存;如果业务要求每条都有稳定去重身份,应另外定义非空业务键。字符排序规则还决定大小写、重音是否被视为相等,事件token常需要明确区分大小写。

前缀索引只保存字符串前若干字符,节省空间,但不能保证覆盖完整列,唯一前缀还会把前缀相同但完整值不同的数据拒绝。选择前缀长度应比较不同长度下的区分度和查询需求,不是统一取几十个字符。

7. 冗余索引、不可见索引与上线

(a,b)通常能服务部分只用a的访问,但单列(a)更窄,仍可能有不同成本;如果一个是唯一、另一不是,也不能随意互换。判断冗余要结合约束语义、查询使用、排序和维护成本。

MySQL8支持不可见索引用于观察优化器不使用它后的影响,但索引仍被维护,不代表已降低写成本;唯一性也不会因不可见消失。修改前记录关键查询计划、业务指标和回退方法,再受控观察。加索引可能遇到元数据锁和资源消耗,所谓在线不等于零阻塞零IO。

索引发布方案要回答:操作算法是否支持,长事务是否阻塞,临时盘够不够,副本延迟是否可控,失败后如何处理,业务超时门槛是什么。第21章展开迁移与恢复。

8. 实验与答案

运行Q17比较只查sale_id和同时查total_amount。解释为何前者可能覆盖、后者需要额外字段;小表可能选择全表扫描,不强迫出现某个key。扩充数据后再测量,保留两种计划。

运行Q18比较DATE包列和范围条件。若两者耗时几乎一样,先检查是否数据太少、全部在缓存,不能据此断言可定位谓词没有价值。若建立表达式索引,重新解释实验的前提已经变化。

设计“租户、状态、时间范围,按时间和ID倒序”的索引。参考候选是实验现有四列索引;若主要查询不含状态,还需另一个时间入口。不要同时创建所有排列组合,应根据查询频率、写负载与服务目标取舍。

官方资料:多列索引、聚簇与二级索引、索引条件下推、不可见索引。

原始文档 · database-course/05-执行计划与SQL优化实战.md

05 执行计划与SQL优化实战

优化流程是“定义正确结果—建立基线—定位工作量—提出一个假设—改变一个因素—比较结果与资源”。本章不提供虚构的线上提速数字,所有耗时由学习者在隔离实例测量。MySQL实验基线8.4;EXPLAIN ANALYZE从8.0.18开始支持,不能对旧服务器直接使用。

1. 三种EXPLAIN读法

传统表格适合快速看访问类型、索引、估计扫描与Extra;JSON包含更详细的计划信息;TREE显示迭代器关系,适合理解连接与排序。EXPLAIN ANALYZE执行语句并显示实际计时、行数与循环次数,不是纯静态检查。对生产大查询不能把它当无成本按钮。官方EXPLAIN

EXPLAIN FORMAT=TRADITIONAL
SELECT sale_id,total_amount FROM lab_sale
WHERE tenant_id=1 AND status='PAID'
ORDER BY ordered_at DESC,sale_id DESC LIMIT 20;

EXPLAIN ANALYZE FORMAT=TREE
SELECT sale_id,total_amount FROM lab_sale
WHERE tenant_id=1 AND status='PAID'
ORDER BY ordered_at DESC,sale_id DESC LIMIT 20;

不要用一张访问类型排行榜代替判断。ALL可能是几行维表最合理的扫描;ref也可能对每个外层行重复取出数千行。Using filesort表示额外排序路径,不保证落磁盘;Using temporary也不自动证明性能不可接受。关注实际输入规模、排序内存、落盘和返回行数。

2. 估计、实际与循环次数

传统rows是估计,不是执行后精确计数,filtered也是估计过滤比例。TREE中的actual rows和loops需要一起看:每轮平均10行、循环10万次,意味着累计输出量大,而不是只处理10行。嵌套节点时间可能包含子节点,不能把所有节点时间直接相加当总耗时。

可以先画手工预算:外层目标订单1000张,每张查平均3条明细,合理输入约3000条;若计划实际访问几十万条,找出在哪个条件没有提前约束。若数据库只返回20行,应用仍卡两秒,继续量连接等待、SQL次数和映射,不把接口总时长全算给这一条SQL。

估计错了不一定只靠更新统计解决。可能查询条件需要隐式转换、JOIN少了租户、统计无法描述相关性,也可能参数分布极端。保留错误计划、完整参数类型与数据分布,分别测试小租户、大租户、窄时间窗和宽时间窗。

3. 连接算法与驱动集合

嵌套循环对外层每行访问内层。如果内层有合适索引且外层很小,通常有效;如果外层巨大,重复探测成本会升高。Hash join在版本与查询形态支持时可服务等值连接,需要构建/探测并可能受内存与溢写影响。SQL把哪张表写在前面不保证优化器选择它先执行。

先把外层集合缩小常有帮助,但前提是语义等价。例如“筛选含热卖商品的订单,再统计订单全部明细”不能改成“只统计热卖明细”。Q14已经为这类优化提供语义基线。调整连接顺序或hint之前,先排除JOIN乘倍与缺失过滤这种根本错误。

4. 一个完整的优化工单

需求:展示租户最近已付订单20条,返回订单ID、客户名、金额与成功收款额。第一版把订单、商品、付款全部连接再分组并排序。问题有两个:商品/付款乘倍影响正确性,全历史聚合影响成本。

先用目标订单CTE或派生表按时间与ID取20个订单身份,再仅聚合这20个订单的成功收款,客户一对一连接。若过滤条件还依赖付款合计,则不能先LIMIT20后过滤,因为可能丢掉后续符合条件的订单;这时目标集合与排序必须重新设计。

改写完成用同一批种子核对零付款、多付款、同额订单、无客户、同时间订单。结果一致后增加规模,记录扫描、循环、排序、回表和总时长。最后测试写入负担,不能只展示加上宽覆盖索引后读快了,而忽略导入时长和磁盘增长。

5. 可重复的规模数据

在独立MySQL教学库创建性能表,避免扩容语义实验的四张订单。下面生成十万行,不使用递归深度设置。它是合成数据,不模拟所有真实分布。

CREATE TABLE lab_perf_digit (digit INT PRIMARY KEY);
INSERT INTO lab_perf_digit VALUES (0),(1),(2),(3),(4),(5),(6),(7),(8),(9);
CREATE TABLE lab_perf_sale (
  id BIGINT PRIMARY KEY,
  tenant_id BIGINT NOT NULL,
  status VARCHAR(12) NOT NULL,
  ordered_at DATETIME NOT NULL,
  amount DECIMAL(12,2) NOT NULL,
  payload VARCHAR(200) NOT NULL
) ENGINE=InnoDB;
INSERT INTO lab_perf_sale
SELECT sequence_no+1, IF(sequence_no<80000,1,2+MOD(sequence_no,100)),
       IF(MOD(sequence_no,10)=0,'NEW','PAID'),
       TIMESTAMPADD(SECOND,sequence_no,'2026-01-01 00:00:00'),
       100.00, REPEAT('x',180)
FROM (
  SELECT d0.digit+10*d1.digit+100*d2.digit+
         1000*d3.digit+10000*d4.digit AS sequence_no
  FROM lab_perf_digit d0 CROSS JOIN lab_perf_digit d1
  CROSS JOIN lab_perf_digit d2 CROSS JOIN lab_perf_digit d3
  CROSS JOIN lab_perf_digit d4
) numbers;

先无二级索引测固定查询,再添加(tenant_id,status,ordered_at,id)测同一查询。区分小租户与tenant1,返回窄列与payload,LIMIT20与COUNT全部。不要在共享实例清空缓存制造冷启动;冷热只在自己拥有的实验环境控制。记录多轮分布,单次十毫秒差异可能只是噪声。

6. COUNT、分页和宽结果

列表常执行两条SQL:数据页和总数。数据页只取20行,COUNT却扫描整个筛选集合,因此用户认为“查20条很慢”其实慢在统计。是否需要精确总数由产品决定,可以取消、缓存、延迟或限制范围,但不能在未说明时返回近似值冒充精确值。

OFFSET深分页会跳过候选结果;延迟关联能减小中间宽度但不消除偏移扫描。游标降低定位成本,代价是需要上一页位置、稳定排序及一致性策略。大导出不要把所有行加载List后再写文件,应分批拉取、流式输出,注意驱动取数设置和连接占用时间。

SELECT *既增加网络和反序列化,也可能破坏覆盖查询,且使表新增字段意外进入响应。只取业务需要列;但也不能为了一个字段每行再发查询,形成N+1。可通过批量IN、JOIN或分两次批量加载映射解决,注意IN长度和结果顺序。

7. 写性能和锁等待必须进入排查

慢UPDATE可能在等行锁而非扫描慢;慢ALTER可能等元数据锁;慢请求可能等连接。先分离等待与执行。长期未提交事务会扩大锁持有和版本保留,索引再好也不能让互斥写同时完成。

批量写减小网络往返,但批次越大,锁、日志、回滚成本越高。按业务原子性决定一个事务覆盖多少行,再调批次,不能把“每1000条提交”当通用正确答案。必须全有或全无的订单明细不应随意切事务,独立商品导入则可以分批记录进度和失败。

项目库存CASE增量Mapper〔本地文件〕应检查参数数量、WHERE范围和每批SKU数。广告游标〔本地文件〕应检查复合排序与NULL。源码说明查询意图,不能替代线上DDL和实际计划。

8. 交付标准与练习

优化报告写出正确性用例、版本、表/索引、数据规模分布、原SQL、新SQL、代表参数、前后计划、延迟分布、写成本和回退方式。若只有平均值下降而p99上升,要解释排队或长尾,不宣布全局优化。

练习一:索引后耗时没变,为什么?可能命中量仍很大、瓶颈是锁或连接、小表无差异、计划没选新索引、回表太多。用分层指标逐个证伪,不直接再加索引。

练习二:每租户前10订单改成全表LIMIT10后再按租户筛选,为什么错误?LIMIT改变候选集合,不可跨越影响排名范围的过滤。正确做法根据业务用窗口分区或每租户查询并明确成本。

练习三:慢SQL日志没有异常,但接口很慢?慢阈值以内的百次N+1、连接池等待、网络传输和应用CPU都可能遗漏。用SQL计数、调用链和连接指标补足,日志不是全部延迟。

官方参考:实际计划解读、统计更新、Hash Join。

原始文档 · database-course/06-InnoDB存储日志与崩溃恢复.md

06 InnoDB 存储、日志与崩溃恢复:一次库存扣减怎样活过重启

前端开发者通常把保存理解为“请求成功,数据已经写入文件”。转到 ERP 后端,需要把这句话拆开:SQL执行成功、事务提交成功、客户端收到成功、数据页落盘、日志持久化、下游收到事件,是不同的时刻。一笔采购入库或库存预占同时碰到这些边界,若只知道“数据库有事务”,就无法解释为什么接口超时后订单已经存在,也无法判断重试会不会重复扣库存。

本章以 tenant_id=1, sku_id=101 的库存从10减到7为主线。先执行事务实验室的独立初始化,再做L1和L10;不需要运行任何业务项目。事实指官方文档或当前源码能直接支持的行为;推导指在明确前提下对本例结果的推演;教学指人为缩小的模型和代码;未执行指本次没有启动数据库、读取真实页、运行故障注入或验证生产配置。下文所有输出均为教学预期。

6.1 从一行数据走到一页数据

教学表的主键是 (tenant_id,sku_id)。对于 InnoDB,主键不只是一个防重复约束,它还决定聚簇索引的组织方式。聚簇索引叶子记录存放行数据;二级索引记录包含用于定位聚簇记录的主键。因而一个很宽的主键不仅影响主索引,还会进入二级索引,影响缓存容纳的记录数和写入成本。没有显式主键时也不是“没有组织方式”,引擎会按规则选用其他合适的唯一键或生成内部行标识。见官方聚簇与二级索引说明。

页是磁盘与内存管理的重要单位。默认 InnoDB 页大小通常为16KiB,但必须以 @@innodb_page_size 为准,不能把默认值当成所有实例的事实。一个页容纳多条记录和管理信息;B+树上层页帮助缩小查找范围,叶子页承载按索引键组织的记录。因此一次主键查询不是“把整张表搬到Java数组再过滤”,也不是“每行固定占据一个磁盘文件”。数据库在页层面管理缓存、分裂、合并与刷写,行级业务动作会带来页级存储动作。见官方索引物理结构。

USE lab_transactions;
SELECT @@innodb_page_size;
SHOW CREATE TABLE lab_stock;
EXPLAIN SELECT available FROM lab_stock
WHERE tenant_id=1 AND sku_id=101;

预期 SHOW CREATE TABLE 含复合主键和 InnoDB,引擎可通过完整主键定位目标。EXPLAIN 是访问路径证据,不是物理磁盘读取次数证据;页是否已在缓存、一次访问是否发生I/O,不能由 type=const 或 key=PRIMARY 单独证明。本实验只有两条库存记录,更不能用其耗时估算千万行库存表的性能。

可以把 Buffer Pool 理解为数据库掌握的页缓存:读某条记录时,需要的页可能已经在内存;更新时,内存页内容改变,页成为脏页。这里“脏”仅指它与持久存储中的对应页不同,并不表示事务未提交、数据错误或有人读到了脏数据。一个页可以包含多个事务修改过的不同记录,单个事务也可以跨很多页。因此“提交这个事务”不等于“立即把它碰过的每个整页都同步写完”。

由此推导一个重要结论:事务已经提交时,数据页仍可能是脏页;事务尚未提交时,其修改涉及的页也可能因缓存管理被刷写。这两种情况都要求引擎在页文件之外保存足够的恢复信息。否则第一种会丢已提交结果,第二种会把未完成工作误当成成功。redo和undo正是为这些不同问题服务的,而不是两个名字不同的SQL备份文件。

6.2 把一条 UPDATE 分解成能解释故障的过程

先快速重置,然后在A执行以下教学事务,停在提交之前:

START TRANSACTION;
UPDATE lab_stock
SET available=available-3, version=version+1
WHERE tenant_id=1 AND sku_id=101 AND available>=3;
SELECT ROW_COUNT(); -- 预期1
INSERT INTO lab_reservation VALUES (1,'C06-reserve',101,3);
SELECT available, version FROM lab_stock
WHERE tenant_id=1 AND sku_id=101; -- A预期7,1
-- 暂不COMMIT,切换到另一个会话观察。

A需要找到并锁定可更新记录,检查条件,保存支持回滚与旧版本访问的信息,再改变相关内存结构并生成日志。这里写成线性叙事是帮助理解,不宣称每一项内部调用都独立运行、严格按文字顺序完成;真实实现还涉及页闩锁、mini-transaction及日志缓冲等机制。业务事务的行锁保护事务间冲突,短时间的页闩锁保护内部数据结构,并不是同一个锁。

B的普通查询在本实验中仍看到库存10和零条预占流水,A则看到自己的7和流水。A执行 ROLLBACK 后,库存回到10,流水不存在。若A执行 COMMIT,B在新的可见性条件下能看到7和流水。这展示了逻辑可见性,尚未检验断电行为。把“另一个连接已经查得到”当成所有故障下都持久,是把隔离性与持久性混在了一起。

反例是先在自动提交模式扣库存,再插流水。第一条语句提交后,第二条因重复键报错,此时调用 ROLLBACK 无法跨越事务边界撤回已经完成的扣减。引擎只能兑现应用实际建立的事务,而不能猜出两个HTTP接口原本想构成同一业务。实验室L1提供了这个反例的步骤和重置方法。

6.3 redo:恢复页状态,不是重放所有业务请求

redo记录引擎用于恢复数据页变化的信息。可以教学性地把它看成“哪些页上的哪些结构发生了变化”,但不应把它说成永远等于简单的“页号、字节偏移、旧值、新值”四元组;实际日志类型由实现决定。恢复时也不是把原SQL再次提交给优化器,让订单再下单一遍。redo属于存储引擎恢复机制。见官方redo说明。

Write-Ahead Logging的关键是:相关脏页持久化之前,能够恢复这些变化的日志必须先满足相应持久化要求。由此数据库可以顺序写日志,同时在之后批量或异步刷新随机分布的数据页。性能收益不是“日志不用落盘”,而是把请求提交所依赖的同步工作和大量页写入解耦,并能把部分同步成本在多个事务之间摊销。

教学上可给日志位置起名:当前生成到L120,已经持久化到L110,检查点推进到L80。这些是假设刻度,不是实际字节或本机观测。L80之前已具备相应页持久化保障,恢复不必无止境扫描全部历史。若不断产生新日志,而最老的必要脏页迟迟不能刷新,检查点难以推进,可重用日志空间变少,前台事务会受到压力。扩大redo容量可能缓冲高峰,但不能治好持续超过磁盘能力的写入,也不能替代定位长事务和慢I/O。

这里最容易记错的是“redo只记录已提交事务”。修改发生时就会产生日志,未提交事务的日志也可能随缓冲刷出。否则一个未提交事务碰过的页若先落盘,引擎会失去恢复其内部一致性的依据。恢复可能先根据redo把页重建到可以识别的状态,再根据事务状态处理未完成工作;这也是下一节undo不能被省掉的原因。

6.4 undo:既让失败撤回,也让旧快照继续读

undo不是供运维人员任意回到去年某一天的历史库。它保存引擎撤销修改、构造旧版本所需的信息。更新一行时,当前聚簇记录关联修改事务和回滚信息;旧快照看不见当前版本时,可以沿历史信息构造可见版本。删除也通常先标记,再在没有读者需要时由后台清理。更细的可见性判断留到第07章。见官方多版本机制。

在本例中,10改为7之后,A回滚需要恢复10;B若持有更早的RR快照,即使A提交,B仍可能需要看到10。两者共享对旧信息的需求,却对应不同的生命周期:回滚关心未完成事务,快照关心仍活跃的读者。因此“事务一提交,undo立刻全部删除”是错误的。反过来,“只读事务从不写数据,所以长时间开着没有代价”也错误,它可能使旧版本不能被及时清理。

设导出任务A持续持有早上的快照,库存服务B每秒更新相同SKU。B的每笔事务很短,但A迟迟不结束,旧版本仍可能需要保留。这时增加连接池不会改善版本保留压力,还可能允许更多长读者进入。教学推导的排查方向是读事务年龄、历史版本清理进展、导出分页是否持续保持同一事务,而不是先认定数据库文件增长就是“内存泄漏”。

回滚也需要做工作。一个写了很多页的大事务中途失败,不会因为客户端断开就瞬间消失;撤销过程可能继续消耗资源和持有相关锁。KILL某个请求与“立刻释放所有资源”不是同义词。更合理的导入设计要在开始之前明确原子性单元,避免把几十万行、远程调用和文件解析全塞入一个难以撤销的事务。

6.5 binlog:服务器的变化历史与内部两阶段提交

binlog属于MySQL服务器层,服务于复制及基于备份的时间点恢复等用途。ROW格式记录行变化事件,STATEMENT格式记录语句,不能把“binlog就是SQL文本”作为普遍定义。binlog也不是redo:拥有binlog不代表可以在没有基础备份的情况下恢复任意已丢失的数据页,拥有redo也不意味着拥有可供无限期追溯的业务变更历史。见官方二进制日志说明。

为什么扣减要同时关心两份日志?假设引擎已经永久确认库存7,binlog却没有这笔事务,复制或后续恢复可能缺这笔扣减;反过来,binlog保留了事务,而引擎最终否认它,下游与本机也会分歧。教学模型因此把启用binlog时的提交分成“引擎prepare、持久化可用于决策的binlog、引擎commit”三个逻辑阶段。它描述一致性决策依赖,不是说每条事务必定单独执行三次fsync,也不等同于应用主动执行分布式XA。

精确实现涉及组提交队列、flush/sync/commit阶段和恢复时的事务标识匹配,可沿MySQL 8.4.0官方源码 binlog.cc 中 MYSQL_BIN_LOG::ordered_commit、process_commit_stage_queue 等符号继续阅读。面试中用三个框解释依赖即可,工程决策不能拿这个简图代替目标版本源码和持久化配置。

在“单实例InnoDB、启用binlog、日志持久化可靠”的教学前提下,可按下面时序理解崩溃。这里的“binlog有事务”指恢复流程认可的完整事务及提交标记,不是文件里恰好找到某个字符串。

崩溃位置 可用于恢复的状态 教学预期及原因
事务更新后,尚无可确认提交的决策 可能已有数据页或redo变化 未完成事务不能冒充成功,需撤销
引擎已prepare,尚无持久化完整binlog事务 待决事务,无提交依据 恢复时通常回滚该内部事务
引擎已prepare,完整binlog提交决策已持久化 引擎提交标记可能尚未完成 按已持久化决策完成提交
引擎已提交,应答尚未送达客户端 数据库认为成功 客户端结果不确定,不能直接再次扣减

表格不覆盖外部XA、非事务表、关闭binlog、日志被人为删除或存储介质撒谎等情形。最值得后端记住的是最后一行:数据库可以一致地恢复,客户端仍无法仅凭断线判断成功与否。这正是请求号唯一约束和幂等查询存在的理由,而不是“数据库事务不可靠”。

6.6 提交刷盘参数应当怎样读

innodb_flush_log_at_trx_commit=1意味着提交遵循写出并刷新redo的策略;2通常是每次提交写到操作系统缓存,再周期性刷新;0把写出和刷新更多交给周期任务。周期不是严格的每一秒契约。sync_binlog=1要求binlog在相应提交同步边界刷新;组提交可以让多个事务共享一次同步。硬件、操作系统和存储对刷新请求的兑现仍是前提。见redo刷盘参数与binlog同步参数。

SELECT @@innodb_flush_log_at_trx_commit AS redo_policy,
       @@sync_binlog AS binlog_policy,
       @@log_bin AS binlog_enabled,
       @@binlog_format AS binlog_format;

这些查询用于专用实验实例,不是让读者连接业务环境取配置。仅看参数值也不能证明底层磁盘在故障时保持写入。教学上可以区分进程崩溃和宿主断电:进程消失后操作系统缓存可能还在,而断电可能连缓存一起丢失。因此“我kill了mysqld十次都没丢”不能证明较弱刷盘策略同样能抵抗断电。

ERP的库存、付款关联和出库记录往往需要清晰的已确认提交边界。若为性能降低持久化要求,需要由业务明确接受什么故障下丢哪些已确认操作,并设计对账恢复,而不是把某个参数当万能优化。更应先测量提交延迟、事务数量、单批大小及底层I/O,判断是否真的在同步日志上受限。

6.7 页只写了一半,为什么还需要doublewrite

redo解决“哪些变化要恢复”,但物理页写入本身还可能中断。假设一个页由多次底层写操作完成,掉电后页的部分内容来自新版本,部分来自旧版本,就可能连页的内部结构都不完整。doublewrite机制为恢复这类不完整页写入提供保护;它不是事务的第二份binlog,也不是让每条SQL执行两次。具体是否使用、存放方式及优化随版本和存储能力变化。见官方doublewrite说明。

可以把三者分工串起来理解:先要有可用的页基础,再根据redo恢复应有的变化,再结合事务状态与undo处理不应保留的工作。这里仍是教学顺序,并非完整内部启动算法。不要把删除redo、关闭doublewrite、强制恢复选项拼成“重启慢的一键修复”;那会绕过引擎赖以证明数据正确性的条件。

6.8 真正复现一次进程崩溃,并限制结论范围

事务实验室L10使用专用容器:A提交101扣3和流水,B修改102及另一条流水却不提交;确认A已收到成功后,让该容器内的mysqld进程突停,再启动同一个容器。预期101为7,102为10,只保留A的流水。初始化、执行顺序、重连、重置及资源清理均在L10。

这个实验有两个可以验收的命题:一个已确认事务在指定配置与本次故障下仍存在;一个未完成事务在恢复后未变成可见提交。它不能证明物理页具体哪一毫秒刷盘,也不能强行验证prepare与binlog同步之间的每一个极短窗口。精确注入内部提交阶段需要专门的调试构建和受控测试钩子,不能用普通SQL加随机sleep冒充。

恢复期间服务也未必马上可用。redo应用和其他恢复工作存在不同阶段,未完成事务回滚可能继续进行。官方InnoDB恢复说明提供了恢复步骤和限制。对业务而言,健康检查成功、所有回滚结束、所有缓存和下游追平也不是同一时刻,应用恢复策略应按自己真正依赖的条件设计。

6.9 回到项目源码:日志知识怎样帮助读业务代码

源码事实:StockComponentImpl.doTransitStockWithStorageUpdate〔本地文件〕先做数据准备,在第1427行的TransactionTemplate〔本地文件〕内编排数据库写入。SysSkuStorageStockMapper.xml的batchUpdateStorageStock〔本地文件〕包含库存增量表达式,而不是全部由Java计算新绝对值后覆盖。

推导:这种把准备与写入分开的结构有利于缩短持锁窗口;但准备阶段读到的值能否安全用于后续写入,仍要看更新条件和并发协议。TransactionTemplate只标明应用希望的事务范围,不能从这几行代码推出真实数据源、分片后的原子性、日志刷盘参数或线上MySQL版本。源码字段是 user_id 等,本章 tenant_id=1 是统一教学模型,不声称项目已有同名字段。

阅读任务:沿方法进入Mapper,标出一次操作可能触及的表,找出哪些字段增量更新、哪些字段覆盖,最后回答“如果提交应答丢失,调用者依据什么识别原请求”。这是把存储知识用于业务,而不是要求业务开发每天手工解析redo文件。

6.10 练习与答案

练习一:事务提交成功时,库存所在数据页一定已经落盘吗?如果没有,重启如何得到7?

答案:不一定。提交持久性可依赖已满足要求的日志,数据页之后刷新;重启通过恢复机制重建已提交结果。必须同时说明日志策略和可靠存储前提,不能只回答“有redo所以永远不丢”。

练习二:L1执行回滚后库存仍是10,是否说明此前没有写入任何磁盘?

答案:不能。redo、undo及某些页可能已经产生持久写入;逻辑回滚不等于物理世界从未发生写入。引擎保证的是事务语义,而不是失败请求零I/O。

练习三:A提交后保留了undo,是数据库忘记清理吗?

答案:也可能是旧读视图仍需要历史版本。先观察事务和清理进展,不能只凭文件未缩小判定泄漏;内部可重用空间与文件缩小也是不同概念。

练习四:客户端超时,重新生成请求号再扣3是否安全?

答案:不安全,原事务可能已经提交。保留原幂等键,按原业务内容查询或重放;若发现同键不同参数应拒绝,不能把唯一键冲突随意当成同一请求成功。

练习五:把十万条导入放进一个事务,可以省提交次数,是否必定更快?

答案:提交次数可能下降,但日志量、锁持有、回滚成本、内存和复制延迟可能上升。先定义允许整批原子还是分块成功,再用对应吞吐、延迟和失败恢复指标比较,不能仅以SQL条数作判断。

本章的验证边界是源码链接与文本静态检查、官方依据核对;数据库实验、页解析、故障恢复和性能数字均未在本次执行。

原始文档 · database-course/07-事务MVCC与隔离级别.md

07 事务、MVCC与隔离级别

本章基线MySQL8.4/InnoDB,对应事务实验L1—L3、L9。语句顺序、重置与观察脚本以实验室为准。本章解释为什么得到这些结果。事务不是Java方法上的标记,而是数据库对一组操作定义的提交、回滚与并发可见性边界。

1. ACID四个字母各保护什么

原子性要求本地事务内的修改一起提交或撤回;一致性要求在应用正确使用约束和算法的前提下维护不变量;隔离性限制并发事务互相观察与干扰的方式;持久性描述提交效果在相应故障模型下保留。数据库不会自己知道“库存预占应该等于所有订单剩余预占之和”,应用必须把规则落实成事务和约束。

一次事务只能控制实际参与的资源。使用同一个DataSource事务管理器不意味着另一个独立数据库、Redis和HTTP调用也加入。数据库回滚不撤回已发出的短信,不删除已上传文件,不自动恢复另一个服务的状态。这些边界是后续分布式课程的起点。

自动提交开启时,每条独立DML一般自成事务。显式START TRANSACTION延长到COMMIT/ROLLBACK。DDL可能隐式提交,不能在业务事务中执行ALTER后以为ROLLBACK会撤销表结构。保存点允许局部回退,但不是开启独立子事务,外层回滚仍撤销全部未提交结果。

2. 四种隔离级别先从现象理解

READ UNCOMMITTED允许某些未提交可见,极少适合核心交易;READ COMMITTED让普通一致性读观察每条语句开始时的已提交快照;REPEATABLE READ通常复用第一次一致性读建立的快照;SERIALIZABLE提供更强隔离,也带来等待、冲突和吞吐代价。具体锁行为必须按产品解释,PostgreSQL的同名级别不等于InnoDB的实现。

脏读是读到最终可能回滚的数据;不可重复读是同一行在两次读取间出现他人已提交修改;幻读关注同一条件的行集合变化;丢失更新是一个写覆盖另一个写;写偏斜是多个事务各自依据旧集合更新不同记录,联合违反约束。这些不是一个简单从低到高的“所有问题都被RR解决”的列表。

SET SESSION TRANSACTION ISOLATION LEVEL REPEATABLE READ;
START TRANSACTION;
SELECT available FROM lab_stock WHERE tenant_id=1 AND sku_id=101;

实验初值10。A先读10;B更新到7并提交;A普通SELECT仍读10;A提交后新事务读7。换成RC,A第二条普通SELECT应读7。必须先让B提交,再做A读取,否则无法区分隔离机制与未提交不可见。

3. Read View不是复制整张表

MVCC通过版本链与可见性判断重建读取者应看到的版本。读视图记录相关事务可见性边界;引擎根据版本的修改事务身份,判断它是否在快照之前提交、当时是否仍活跃,再必要时沿undo构造旧版本。它不是开事务时复制整个库,也不是每次SELECT都从备份文件读取。

RR通常在首次一致性读建立快照,单独START TRANSACTION不等于立即冻结视图。实验L3先开启A而不读,B提交变更后A首次读,应按首次读时点理解。WITH CONSISTENT SNAPSHOT在适用级别能改变建立时点,不能把它当所有隔离级别都相同的魔法开关。

事务能看到自己的修改。假设A的快照中某行旧值10,B已提交新值7,A执行UPDATE available=available-1操作的是当前可写版本,结果可能为6,而不是按旧快照写9。A随后看到自己的6。把旧快照读到的字段与自己新写入组合起来,可能得到其他任何时刻都没有出现的组合。

官方依据:一致性非锁定读、隔离级别。这些机制说明为什么观察不同读法时必须注明语句类型。

4. 快照读与锁定读不能混同

普通SELECT通常使用一致性非锁定读;SELECT FOR UPDATE/FOR SHARE属于锁定读取,关注当前可锁定数据并获取相应锁。UPDATE/DELETE也按写入的规则访问当前记录,而不是简单在事务最早快照上做离线修改。

因此“RR杜绝幻读”需要拆开说:重复快照读可以继续观察旧集合;适当锁定范围的next-key机制可阻止竞争插入;混合普通快照读和当前读则可能观察到不同集合。业务判断要选择同一套可论证的访问协议,不能第一步读旧集合、第二步按当前集合修改却假设完全一致。

只读报表通常希望一个一致快照,但长事务会阻碍旧版本回收,增加undo与存储压力。逐页独立事务减轻长期资源占用,却不再保证所有页来自同一时点。可用不可变事件水位、快照表或业务截止时间平衡,必须写清报表对“截至时间”的定义。

5. 丢失更新与单条条件更新

错误算法:A/B都读available=10,分别想减3、减4,在Java计算后写绝对值7、6。最终可能是6,丢掉减3。RR并不自动理解“6其实来自过时的10”。可以用原子算术更新、版本条件或锁定读取来表达竞争约束。

UPDATE lab_stock
SET available=available-4, version=version+1
WHERE tenant_id=1 AND sku_id=101 AND available>=4;
SELECT ROW_COUNT();

影响1行表示当前条件满足并执行,0行需要区分记录不存在或库存不足。输入数量必须在应用和必要约束中保证为正,负数不能变成反向充值。该语句防止单行超卖,但不防同一事件被重复扣减;事件唯一键与效果写入仍要在同一事务里。

6. 写偏斜:事务正确提交仍可能破坏集合规则

教学规则至少一人值班。A/B都从快照读到两人在岗,A把自己设下班,B把自己设下班,两者修改不同记录,可能都提交,最终无人值班。每行合法、每个事务原子,都不等于集合不变量成立。

解决思路是把竞争聚合到同一可锁定资源,例如排班组的协调行;在统一锁协议下读取并更新,或使用适当的SERIALIZABLE与重试。不能只给每个人的version加乐观锁,因为两者仍修改不同记录。库存跨仓总可用量、资金多账户限额也会出现类似问题。

实验L9提供完整时序。要求先预测提交结果,再讨论哪种资源能代表“这个排班组不能全离岗”。由此理解领域聚合边界和数据库锁范围之间的联系。

7. 异常、提交不确定与重试

收到数据库约束错误不一定意味着连接已回到干净状态;死锁与锁等待超时的回滚范围也可能不同。应用应显式结束失败事务,再决定是否可重试。重试使用新事务与同一个业务身份,不能在已经rollback-only的上下文继续执行。

COMMIT发送后连接断开,结果可能已提交,也可能没提交。客户端没收到确认不是未执行证明。用唯一业务事件和结果查询解决重试的不确定性,不能盲目换新事件ID。日志也应区分“提交结果未知”和“明确回滚”,否则人工补偿可能重复处理。

8. 练习与答案

  1. START TRANSACTION之后B提交,A第一次SELECT读什么?在普通RR一致性读条件下,快照通常建立于首次读,因此应包含B在此之前已提交的变化;实验必须排除先前隐藏查询。
  2. RR普通读保持10,FOR UPDATE读7,是否数据库坏了?没有,读取协议不同。业务要求当前值就用明确锁定/条件更新方案,不以旧快照作为可写性保证。
  3. 乐观锁更新影响零行应直接去掉version重试吗?不应。应重读并重新验证业务意图,或返回冲突,去条件会恢复覆盖风险。
  4. 长报表用一个事务能否无限读?机制允许不代表成本合理。观察事务年龄、版本回收、连接占用和复制影响,设计水位或快照策略。

完成本章后,继续08章把可见性判断与具体锁对象联系起来。

原始文档 · database-course/08-锁死锁与库存并发实战.md

08 锁、死锁与库存并发实战

本章配套事务实验L4—L8,基线MySQL8.4/InnoDB。锁结论必须同时给表结构、索引、隔离级别、谓词与执行时序;不能只看WHERE文本就精确画出所有锁。下述范围解释用于建立直觉,实际以锁诊断记录和实验为准。

1. 锁与latch分别解决什么

事务锁协调业务数据并发,可能持续到事务结束;引擎内部latch保护内存结构的短临界区,生命周期和诊断不同。表级意向锁表达事务准备持有哪些行级锁,帮助协调表级锁请求,并不是先锁住整表后所有人都无法访问。

共享锁S允许兼容读取,排他锁X保护写入。记录锁对应索引记录;gap lock保护索引记录之间的间隙,主要用于限制插入;next-key是记录与其前间隙的组合。gap锁之间并非普通互斥写锁那样简单,不能把“两个事务持有间隙锁”直接解释成它们必然相互阻塞。

另有元数据锁MDL保护表定义与正在使用它的语句/事务。ALTER等待可能是旧事务持有MDL,和业务行锁不是一回事。AUTO_INCREMENT相关锁与配置也有独立机制,不应把所有等待都归于行锁。

2. 唯一键命中、不存在与范围扫描

对完整唯一键的现存行做等值锁定,通常只需记录锁;缺失键的锁定查询可能保护其所在间隙,阻止别人插入该值。复合唯一键只指定部分列并不是完整唯一查找,范围仍可能较大。

实验lab_range的主键为tenant_id,slot_no,有10、20、30。A在RR事务锁定不存在的15,B插15会等待;A回滚释放后B继续,再由B回滚恢复。B若插其他值也可能受相同间隙保护,说明锁不是仅对一个不存在的抽象数字生效。

范围slot_no>=10 AND slot_no<20的边界锁可能涉及扫描停止位置,不能凭开区间文字断言20附近绝不受影响。执行计划、唯一性和引擎优化都会影响具体记录。实验L5要求观察实际对象和插入等待,避免只背固定区间图。

RC通常减少普通搜索/扫描所需gap锁,但外键和重复键检查仍存在例外。改级别不是“所有锁变少而业务含义不变”,它同时改变读可见性,必须回到不变量分析。

3. 两会话死锁不是普通等待

用两行库存101和102,初值均10。A先锁101,B先锁102;A再改102等待B;B再改101构成环。启用死锁检测时数据库选择受害者回滚,另一个才能继续。不要假设固定A或B必然被选中。

START TRANSACTION;
UPDATE lab_stock SET available=available-1
WHERE tenant_id=1 AND sku_id=101;

上面只是A第一步。完整交错和B步骤见实验L6。执行阻塞语句后必须换另一个终端,不是在同一连接粘贴“下一步”。观察后双方都ROLLBACK,再重置初值,避免上一个实验留下锁污染结果。

统一按SKU排序能减少反向获取,但不能证明全部业务路径遵守同一顺序,也不能消除二级索引、外键和间隙造成的环。死锁处理是正常并发协议的一部分:识别可重试错误、回滚整个尝试、有限次数退避、保留业务幂等身份。

4. 看等待链而不只看慢语句

MySQL8可用performance_schema.data_locks与data_lock_waits观察请求/持有关系,结合事务、线程与语句信息定位阻塞者。SHOW ENGINE INNODB STATUS提供最近死锁线索,但不保证包含全部历史。查询这些诊断表需要相应权限,也不应把真实业务参数直接传播到公共文档。

SELECT ENGINE_TRANSACTION_ID,OBJECT_SCHEMA,OBJECT_NAME,
       INDEX_NAME,LOCK_TYPE,LOCK_MODE,LOCK_STATUS,LOCK_DATA
FROM performance_schema.data_locks
WHERE OBJECT_SCHEMA='lab_transactions';

SELECT REQUESTING_ENGINE_TRANSACTION_ID,
       BLOCKING_ENGINE_TRANSACTION_ID
FROM performance_schema.data_lock_waits;

锁等待超时常见1205,死锁常见1213。错误码有助分类,但驱动可能包装异常;事务是否整体回滚取决于错误及配置。不能收到1205后继续提交此前其他写入,却向用户宣称整笔操作失败。应用层最容易论证的策略通常是结束失败事务后完整重试。

5. 防超卖与防重复是两件事

条件UPDATE防当前库存不足;唯一事件表防同一意图重复;一个本地事务让余额与事件效果一起生效。仅有锁只能串行,不会判断第二次相同请求是不是第一次的重复。仅有唯一键但写余额在另一个事务,也可能记录已做过而实际没扣,或反过来。

悲观锁适合需要读取多列后做复杂判定,但锁内不应等待外部RPC,否则把网络尾延迟变成数据库锁持有时间。版本乐观锁适合冲突可接受且能重新计算的更新;热点严重时反复重读重试可能比串行等待更浪费。原子条件更新适合单行可表达的不变量。

跨SKU全有或全无用同一资源事务,按稳定顺序写;如果中间件路由到多个物理库,必须重新确认事务类型,不能因Java处于同一方法就假设已原子提交。跨库主题见11章。

6. 真实库存代码逐层看

StockComponentImpl第1339行〔本地文件〕存在根据客户端和开关决定是否走Redis锁的分支。锁按名称排序,用MultiLock等待30秒、指定300秒租期。源码可证明参数,不能由此推出任何工作时长都小于租期或线上始终启用。

第1391行附近〔本地文件〕先查询旧SKU、已有分仓库存并构造DTO,之后在TransactionTemplate回调中更新分仓与总库存。前置读取不因后面开启事务自动纳入同一快照,是否安全还要看增量SQL、条件、外部锁和其他写路径。

Mapper第405行〔本地文件〕使用CASE构建批量增量。数据库算术可避免一类绝对值覆盖,却不自动保证不重复、不负数和所有租户条件完备。阅读时逐个字段检查WHERE与CASE,没有源码证据的能力保留待验证。

7. SKIP LOCKED与任务领取

FOR UPDATE SKIP LOCKED可跳过被锁记录,适合多个worker领取独立队列项。它故意返回不完整的即时集合,不适合需要完整金额汇总的报表。NOWAIT则在无法立即获取锁时失败,适合快速冲突反馈,但应用必须处理这种失败。

任务领取建议在短事务内锁定候选、写owner/lease/state并提交,长业务处理在外面执行;完成更新必须校验owner和attempt,防旧worker覆盖新领取者。任务租约与数据库行锁不是同一概念:提交后行锁释放,但业务租约继续由字段约束。

不要在处理十分钟文件期间一直持有FOR UPDATE事务。那既占连接与锁,又不能保证进程在外部上传成功后一定完成数据库状态更新。需要任务状态机和恢复扫描,而不是把事务无限延长。

8. 练习与答案

一:UPDATE匹配一行为什么锁很多?先看索引和实际扫描,谓词匹配数量不等于访问数量;还需考虑二级索引与外键。提供计划与data_locks证据。

二:给所有操作加synchronized能否防超卖?它只协调同一JVM中遵守同一对象锁的线程,多实例、任务、其他服务写库仍竞争。数据库最终约束不能省。

三:Redis锁还没到期,数据库一定没有死锁?不一定,不同资源键或未遵循该锁的写路径仍可能形成数据库锁环,两种锁的范围和生命周期不同。

四:死锁后只重试最后一条UPDATE为什么危险?受害事务此前的写可能已经回滚,最后一条成功也无法恢复整个业务原子性。需要重新执行完整事务意图并处理外部副作用。

参考:InnoDB锁、不同语句的锁、死锁处理。

原始文档 · database-course/09-SpringMyBatis数据库工程.md

09 Spring、MyBatis与数据库事务工程

SQL在客户端执行正确,还必须保证进入Java服务后用正确资源、正确边界执行。本章讲事务代理、资源绑定、传播与测试。Mapper API、动态SQL、Plus插件详见25章;驱动和连接池详见27章,避免把框架功能误认为数据库保证。

1. 一次事务怎样绑定到连接

以Spring JDBC事务管理器管理一个关系DataSource为例:代理拦截方法,事务管理器获取或复用连接、设置事务属性,将资源绑定到当前执行上下文,Mapper通过集成层参与同一事务,方法正常结束后提交,符合回滚规则的异常导致回滚。关键是实际使用同一被管理资源,而非两个变量碰巧都叫dataSource。

Spring的命令式事务通常与当前线程关联。把Mapper调用丢到线程池,不会自动继承父线程事务;异步线程可能自行提交。若父事务随后失败,子线程已提交结果不会随之撤回。要么在单线程事务中完成原子操作,要么明确拆成异步工作与持久化事件。

连接池返回的是可复用连接,不应业务代码持有为全局对象。事务结束归还连接,池应恢复相应状态;自行修改autoCommit、isolation、readOnly或会话变量时尤其要验证恢复路径,避免下一位使用者继承旧设置。

2. 代理边界与自调用

@Service
public class StockApplicationService {
    private final StockMapper stockMapper;

    public StockApplicationService(StockMapper stockMapper) {
        this.stockMapper = stockMapper;
    }

    @Transactional(rollbackFor = Exception.class)
    public void reserve(long tenantId, long skuId, long quantity) {
        if (quantity <= 0) {
            throw new IllegalArgumentException("quantity must be positive");
        }
        int changed = stockMapper.reserve(tenantId, skuId, quantity);
        if (changed != 1) {
            throw new IllegalStateException("stock unavailable");
        }
    }
}

这是教学片段,StockMapper需要对应带条件的SQL和配置。只有通过已装配代理调用,该注解才按代理模式生效。同一个对象内部this.reserve(...)通常绕过代理。private方法、final方法和接口/类代理还有版本与代理类型边界,不能把注解贴上去就认为事务已启动。

建议将业务事务入口放在清晰的可代理Service方法,通过注入的另一个Bean调用;需要精确编排也可用TransactionTemplate。不要为绕开问题到处获取自己代理而失去可读边界。项目库存TransactionTemplate〔本地文件〕就是显式边界的阅读入口。

3. 回滚规则与异常吞掉

常见默认规则对RuntimeException和Error回滚,受检异常未必默认回滚,具体按配置。rollbackFor=Exception.class扩大范围,但不是所有异常都应重试。业务校验失败、权限失败与数据库死锁需要不同处理。

如果方法捕获数据库异常后返回正常值,代理可能看不到异常;内层事务也可能已标记rollback-only,最终提交抛UnexpectedRollbackException。不能以“catch了所以没事”推断事务可提交。确定要失败就传播正确异常或明确设置回滚状态,并避免继续发出外部成功通知。

MyBatis影响行数为零通常不是异常:条件不满足、版本冲突、记录不存在都可能返回0。应用必须判断,否则一条未生效的更新仍可能被包装成成功。UPDATE语句返回“匹配”或“改变”行数还受驱动配置和SQL是否实际改变值影响,API契约应避免把任意0都当同一业务原因。

4. 传播行为不是名词表

REQUIRED有事务则加入、没有则创建。A调用B的REQUIRED,通常共享同一资源事务,B失败可能影响A整体。REQUIRES_NEW暂停外层并使用独立事务;内层提交不随外层回滚,适合明确需要独立持久化的记录,却可能产生“业务回滚但日志成功”的预期结果。

REQUIRES_NEW还可能需要第二条连接。大量线程各占外层连接后同时申请内层连接,会把连接池耗尽。扩大池不一定解决数据库容量问题;更重要是审查独立事务是否必要、外层是否占锁和内层是否等待外层资源。

NESTED在支持的本地管理器上可基于保存点,不是独立物理提交。SUPPORTS不强制开启,MANDATORY要求已有,NOT_SUPPORTED暂停,NEVER拒绝已有。是否支持取决于管理器和资源类型,不能把关系型保存点语义直接套到MongoDB管理器。

5. 多数据源、路由与只读提示

路由必须在实际获取连接之前确定。事务已绑定主库连接后,临时改ThreadLocal路由不一定让下一个Mapper换库。嵌套路由需要恢复此前值,不能简单finally全部remove导致外层上下文丢失。

项目副本切面〔本地文件〕与HintInterceptor〔本地文件〕展示路由入口。应结合切面顺序、事务开始和中间件实现验证,不只看注解名。

@Transactional(readOnly=true)可向框架或驱动传递优化/只读意图,不能自动代表所有数据库权限层拒绝写入,也不能自动保证副本路由。读写分离后的写后读一致性由10章的策略处理,数据库隔离级别不会消除复制延迟。

6. 批处理、flush与提交

MyBatis批执行可能先积累参数,到flush才真正发送或检查部分错误。方法调用返回不等于全部已成功,flush也不等于commit。一个事务中多次flush仍可整体回滚,前提是同一事务资源和引擎支持。

批次数量平衡内存、网络、锁持有和回滚成本。不能仅凭导入十万行需求就开一个超长事务,也不能把必须原子的订单拆成多个独立提交。幂等导入可以每批提交、保存水位与失败行,重跑依靠唯一键或版本条件,而不是依靠Java集合在内存记住已做过。

动态SQL空集合尤其危险:某些拼接路径若省略IN条件,可能变成全租户更新。空列表应在Service明确返回或拒绝,SQL也应有安全边界。检查最终BoundSql与绑定参数,不只检查XML长得合理。

7. 事务测试必须穿过真实边界

单元测试可验证参数和金额算法,无法证明Spring代理、数据库锁和驱动事务正确。集成测试应从实际Bean代理入口调用,使用隔离数据库,故意在第二步抛异常,核对第一步也被回滚。测试自身若始终包着一个外层事务,可能掩盖被测方法没有正确开启事务。

两线程测试必须使用两个独立连接;每个线程的准备、提交和屏障明确。不要用随机sleep当所有并发测试的同步方式。要复现死锁,可以按步骤使用屏障协调第一把锁已拿到,再开始第二步。

最低验证集:正常提交、第二写失败整体回滚、受检异常回滚规则、自调用差异、REQUIRES_NEW独立提交、版本冲突、死锁重试、提交确认未知、路由上下文清理。当前教材没有启动ERP应用,实验室提供测试契约而非伪造JUnit通过记录。

8. 练习与答案

一:方法标@Transactional却部分成功?检查是否经过代理、异常是否被吞、是否跨线程/数据源、存储引擎是否支持事务,以及是否存在独立REQUIRES_NEW。不要先猜数据库故障。

二:为何锁内RPC不合理?远端延迟无法由本地数据库控制,会延长连接和锁占用;远端成功本地回滚仍需补偿。事务内保存意图,提交后按可靠协议执行是常见改造方向。

三:事务后删缓存失败要回滚数据库吗?提交已经完成,不能再普通ROLLBACK撤销。需要重试失效、版本策略或补偿机制,接口应区分业务提交与辅助传播失败。

官方依据:Spring 5.3事务、MyBatis-Spring事务。实际项目跨多个Spring年代,先解析有效版本再选择API。

原始文档 · database-course/10-MySQL主从复制与读写分离.md

10 MySQL 主从复制与读写分离:提交成功之后,谁能读到它

本章面向从前端转向 ERP 后端的读者。页面提交订单返回成功,再请求详情却得到“订单不存在”,可能不是缓存代码写错,而是写请求与读请求落到了不同数据库。理解这个问题,需要沿着事务提交、日志传送、日志重放和查询快照四个阶段追踪数据,不能用“数据库会自动同步”一句话带过。

证据与实验边界。 本章“源码事实”仅指当前工作区中可见的代码;“推导”指由代码和机制得到的风险分析,不代表线上已经发生;“教学实验”使用 MySQL 8.0.36、独立容器和 tenant_id=1,不是项目生产版本声明。本文编写时未连接业务数据库,也未执行主库切换。命令中的预期结果是教学推演,实际验收必须保存自己的输出。MySQL 8.0.22 起采用 START REPLICA 等新术语,8.0.23 起可用 CHANGE REPLICATION SOURCE TO;不要把这些命令直接复制到较老版本。MySQL GTID 配置说明

10.1 先区分三个看起来相近的系统

主从复制解决同一份数据库内容如何复制到另一台实例。读写分离决定请求发往哪个副本。分库分表决定一条业务记录属于哪个逻辑分片。三个问题可以同时存在,但没有一个自动包含另外两个。一个租户先被路由到分片三,再在分片三内部选择主库或从库,是两个连续决策。CDC 又是另一条链路:它可能把订单事件转换成报表行,而不是保存业务表的完整镜像。

源码事实:report-pro 的 ShardingDataSourceConfig〔本地文件〕 创建 Sharding 数据源,把多个命名数据源放入目标映射,默认数据源仍为 Sharding 数据源。DynamicDataSource〔本地文件〕 通过 ThreadLocal 返回查找键;DataSourceAspect.around〔本地文件〕 根据用户配置与注解前缀选择数据源,并在 finally 清理。

这些事实只能证明应用存在数据源路由,不能证明某个名称是 MySQL 从库、自动故障转移已部署,或事务中的读取始终走主库。ShardingSphere 4.1.0 的读写分离文档描述了事务内请求走主库等行为,但本项目还封装了路由组件,依赖的最终运行版本和代理层策略需另外核实。教材不把新版本 YAML 参数套到旧项目中。ShardingSphere 4.1.0 读写分离

10.2 一次提交与两种“已经到了”

设主库 S 接收租户 1 的订单 1001。InnoDB 提交涉及 redo 与 binlog 的协调,具体持久化保证还受 innodb_flush_log_at_trx_commit、sync_binlog 和存储设备行为影响。普通异步复制下,客户端收到提交成功,不必等待任何从库执行这笔事务。从库的接收线程把事件写入 relay log,应用线程再执行事件;收到日志和提交数据是两个时刻。

时刻 主库 S 从库 R 用户所见
t0 订单金额 100.00 金额 100.00 原详情
t1 更新 120.00 并提交事务 g 尚未收到 g 保存接口成功
t2 金额 120.00 已收 g,尚未应用 查询 R 仍为 100.00
t3 金额 120.00 g 执行并提交 新快照可读 120.00

这不是主库事务“不一致”,而是用户跨实例读取时没有得到“读己之写”的保证。更隐蔽的反例是:R 已经执行 g,但请求复用了一个在 t0 建立的 REPEATABLE READ 一致性快照,仍然看到旧值。等日志追平解决的是副本进度,不能把既有快照变成新快照。

半同步也不要解释成“所有从库都能立刻读”。它等待的是配置规定的副本接收确认,不等价于所有副本执行完成;超时退化、确认数量、等待点和持久化设置都会影响故障语义。本章实验使用普通异步复制,不借半同步名称承诺 RPO 为零。MySQL 半同步复制

10.3 独立初始化:先构造一组可丢弃副本

以下命令由读者在装有 Docker 的实验机执行。它们创建无端口映射的内部网络,空口令仅用于这组不接业务网络的教学容器;不读取仓库配置。容器名存在时先检查是否为自己的旧实验,不要删除不明容器。两个实例必须有不同 server_id 和各自独立数据目录,不能复制包含相同 auto.cnf 的目录直接启动。

docker network create --internal lab10-net
docker run -d --name lab10-source --network lab10-net \
  -e MYSQL_ALLOW_EMPTY_PASSWORD=yes mysql:8.0.36 \
  --server-id=101 --log-bin=lab-bin --binlog-format=ROW \
  --gtid-mode=ON --enforce-gtid-consistency=ON \
  --log-replica-updates=ON --sync-binlog=1 \
  --innodb-flush-log-at-trx-commit=1
docker run -d --name lab10-replica --network lab10-net \
  -e MYSQL_ALLOW_EMPTY_PASSWORD=yes mysql:8.0.36 \
  --server-id=102 --log-bin=lab-bin --binlog-format=ROW \
  --gtid-mode=ON --enforce-gtid-consistency=ON \
  --log-replica-updates=ON --relay-log=lab-relay

分别执行 docker exec lab10-source mysqladmin -uroot ping 与副本对应命令,成功后继续。不要用固定等待五秒代替就绪检查。进入 S:docker exec -it lab10-source mysql -uroot,执行:

CREATE USER 'lab_repl'@'%' IDENTIFIED BY '';
GRANT REPLICATION SLAVE ON *.* TO 'lab_repl'@'%';
CREATE DATABASE lab10;
CREATE TABLE lab10.lab_order (
  tenant_id BIGINT NOT NULL,
  order_id BIGINT NOT NULL,
  amount DECIMAL(12,2) NOT NULL,
  version BIGINT NOT NULL,
  PRIMARY KEY (tenant_id, order_id)
) ENGINE=InnoDB;
INSERT INTO lab10.lab_order VALUES (1,1001,100.00,1);
SELECT @@server_uuid, @@GLOBAL.gtid_executed;

进入 R:docker exec -it lab10-replica mysql -uroot,执行:

CHANGE REPLICATION SOURCE TO
  SOURCE_HOST='lab10-source', SOURCE_PORT=3306,
  SOURCE_USER='lab_repl', SOURCE_PASSWORD='',
  SOURCE_AUTO_POSITION=1;
START REPLICA;
SET GLOBAL read_only=ON;
SET GLOBAL super_read_only=ON;
SHOW REPLICA STATUS\G
SELECT * FROM lab10.lab_order WHERE tenant_id=1;

首次查询可能早于表创建事件到达,应先检查复制线程,再等待源端记录的 GTID 集合。预期最终出现 (1,1001,100.00,1)。真实新副本通常还需要一致性全量备份作为基线,本实验源端数据从空库开始且日志保留完整,才能直接从头复制。GTID 自动定位找不到已经被源端清理的必需日志时会报错,不会凭空补出历史数据。GTID 自动定位

10.4 人工制造延迟,并用事务屏障解释读一致性

在 R 执行 STOP REPLICA SQL_THREAD;,保留接收线程工作。在 S 执行下面事务;随后复制查询得到的整段 GTID 字符串,记为 TOKEN。

START TRANSACTION;
UPDATE lab10.lab_order
SET amount=120.00, version=version+1
WHERE tenant_id=1 AND order_id=1001;
COMMIT;
SELECT @@GLOBAL.gtid_executed;

在 R 的自动提交会话中查询,预期仍为 100.00。接着执行以下语句,将 TOKEN 替换为刚才得到的字符串;不要把单词 TOKEN 原样执行。

SELECT WAIT_FOR_EXECUTED_GTID_SET('TOKEN', 1);
-- 预期返回 1:超时;不是成功
START REPLICA SQL_THREAD;
SELECT WAIT_FOR_EXECUTED_GTID_SET('TOKEN', 10);
-- 预期返回 0:所需 GTID 已执行
SELECT amount,version FROM lab10.lab_order
WHERE tenant_id=1 AND order_id=1001;
-- 新快照预期 120.00 / 2

本实验获取的是提交之后的全局已执行集合,它包含本次事务,但也可能包含其他会话的事务,因此是保守屏障,可能多等。应用若要精确传递本次提交的 GTID,需要核实连接器对 session tracking 的支持和连接复用行为,不能把某个未验证的 Java 方法当现成接口。WAIT_FOR_EXECUTED_GTID_SET 返回 0 表示满足、1 表示超时,其余失败应按错误处理。MySQL GTID 函数

教学读策略可以写成下面伪代码。它强调物理连接与快照的顺序,不是本项目已有实现。

选择副本 R,借出并固定物理连接 c,确认没有遗留事务
在 c 上以自动提交执行 wait(token, 预算内超时)
若返回 0:在同一 c 上建立新读事务并查询
若超时/复制异常:归还 c,按剩余预算选择主库或返回明确的稍后重试
把节点、等待耗时和路由原因写入不含凭据的诊断记录

反例是屏障在 R1 执行成功,真正查询又由连接池分配到 R2;另一个反例是等待前已打开旧快照。固定五秒粘主策略能够降低常见延迟读问题,但五秒不是复制上限。财务确认、扣库存后的核验等路径应按正确性要求选主库或屏障,历史列表才适合接受有界或明确标注的陈旧度。回主请求还要限流,否则副本故障会把全部查询压力压到主库。

10.5 GTID 的集合语义与主库故障

GTID 通常以“源服务器 UUID:事务序号”标识事务。它帮助识别哪些事务已执行、避免重复应用,并让更换复制源时无需手算文件位置;它既不是行内容校验和,也不是选主协议。下面 A、B、C 都是教学 UUID,序号来自不同 UUID 时不能直接比较大小。GTID 格式与存储

SET @s='aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:1-100';
SET @r='aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:1-98';
SELECT GTID_SUBTRACT(@s,@r);  -- A:99-100,实际输出完整 UUID
SELECT GTID_SUBSET(@s,@r);    -- 0,R 不包含 S 全部事务
SELECT GTID_SUBTRACT(@r,@s);  -- 空串,没有此集合意义下的额外事务

假设 S 已向用户确认第 100 笔提交,R1 执行到 98,R2 执行到 99。此时 S 不可达,把 R2 提升为主库只是选择了已知较新的候选,不能证明第 100 笔没有提交。只有恢复旧主日志、找到其他持久副本或依赖事先设计并验证过的提交协议,才能进一步缩小损失范围。应把“最后确认点未知”写入事故记录,而不是因为从库延迟显示零就宣称无损切换。

更棘手的是 R1 的集合包含 A:1-100,R2 包含 A:1-99 与 B:1。R2 的事务总数也是 100,却不包含 R1 的全部事务;B:1 可能是误写产生的 errant transaction。应双向做集合差并核对来源,不能用字符串最长、最大序号或 GTID 数量选主。集合相等也不能替代数据校验:复制过滤、手工修复、跳过错误等操作可能让业务内容分叉。

10.6 可操作的切换演练与失败判据

先做计划切换,理解每一个停顿的目的。在上述双容器中停止实验写入,在 S 执行 SET GLOBAL super_read_only=ON; 并确认没有尚未结束的写事务;记录最终源端 GTID 集合。在 R 等待该集合成功,再检查接收和应用错误、复制过滤、必要业务记录。此时暂停 R 的复制,确认旧主仍被隔离,然后才在 R 关闭 super_read_only 和 read_only,把实验客户端写入口指向 R。旧主恢复为副本前,应保持不可写,核对是否存在独有事务,必要时从新主重建。MySQL 使用 GTID 故障转移

这里的隔离称为 fencing:旧主即使网络恢复也不得继续接受旧连接写入。生产中通常需要编排器、网络或存储隔离、代理与租约协作,设置一个变量不是完整的分布式隔离方案。先放开新主再隔离旧主,会产生双主写入;只改 DNS、不处理连接池长连接,会让部分请求仍写旧主。切换后还必须检查 CDC 是否继续读取正确日志源、租户路由是否指向新位置、失败请求是否按幂等键重试。

再做故障演练:回到重新初始化的实验,在 R 暂停应用后向 S 写入版本 3,再停止 S 容器。记录 R 的已执行集合与已接收集合,检查 relay log 中是否已有该事务;有日志就先尝试应用,没有日志就必须报告可能丢失的提交。不要直接执行清空复制元数据或伪造空 GTID 的命令来“消除报错”,那些操作会破坏诊断证据。实验以明确写出候选包含哪些事务、缺少哪些事务、如何隔离旧主作为通过条件,不以“新主能登录”为通过条件。

10.7 监控为什么不能只看一个延迟数字

SHOW REPLICA STATUS 中要结合 Replica_IO_Running、Replica_SQL_Running、错误字段、接收与执行的 GTID 集合分析。Seconds_Behind_Source 依赖复制运行状态和时间信息,可能为零或 NULL,不能单独证明副本满足某次读取。性能库还可查看并行 worker 的错误,避免协调线程表面存活但某个 worker 停止的误判。MySQL SHOW REPLICA STATUS

教学上可以每秒在源端更新租户 1 的心跳行,记录业务提交时间和序号;副本读取序号差与时间差,并同步观察 backlog。跨机器时间差受时钟偏差影响,所以序号与 GTID 屏障更适合验证特定写入。还要分开记录“应用提交到副本可读”和“应用提交到报表可读”,后者还包含 DTS 处理、队列和报表写入时间,主从延迟正常并不能证明报表新鲜。

10.8 练习与参考答案

练习一: 写接口成功后 R1 返回不存在,重试却查到。列出两种不同原因,并给出可以区分它们的证据。

答案: 一是复制尚未应用,检查写事务对应 GTID 是否包含在 R1 的执行集合;二是应用使用旧事务快照,检查同一连接的新自动提交查询是否能看到记录。还要记录物理节点,排除重试换到了其他副本。只记录 SQL 文本不能区分这些原因。

练习二: R1 为 A:1-40,R2 为 A:1-39,B:1,是否可把 R2 当成最新副本?

答案: 不可。两者互不包含,R2 缺少 A:40,并存在来源不同的 B:1。必须查明 B:1 的内容和产生原因,确认候选的完整性及旧主最后确认点,不能把事务数量相同当成集合相同。

练习三: 等待 GTID 返回 0 后仍读到旧金额,应如何修改教学伪代码?

答案: 固定同一物理副本连接,在等待前结束旧事务,在等待成功后建立新快照;确认表未被复制过滤且查询未命中旧缓存。若路由重新借连接,屏障证明不再适用于真正查询的实例。

练习四: 完成暂停应用、等待超时、恢复应用和计划切换实验,交付什么才算验证?

答案: 交付两个节点身份、写前写后版本、源端 token、两次等待返回值、复制错误为空的检查、隔离旧主记录及切换后单写入口的证据。本文没有代执行这些实验,不能把上述预期结果写进自己的“实测”栏。实验结束只删除自己创建的 lab10-source、lab10-replica 和 lab10-net,保留实验记录。

原始文档 · database-course/11-分库分表路由与数据迁移.md

11 分库分表路由与数据迁移:一条订单到底住在哪里

前端习惯把订单 ID 当成请求定位符:知道 ID,就能打开详情。分片系统需要更多信息。订单号 1001 可能位于某个租户的某张物理表,路由还可能在迁移期间改变。后端必须回答“去哪个库、哪张表、使用哪个版本的路由”,然后才有机会讨论索引是否命中。查不到数据时,先排除查错位置,往往比继续给 SQL 加索引更有效。

边界声明。 本章源码事实来自当前工作区,不声明线上路由配置和依赖版本。教学实验选用 MySQL 8.0.36,在一个独立实例里用两张 lab_ 表模拟两个分片,所有数据属于 tenant_id=1。同实例事务实验不证明真实跨实例事务原子性;源库和目标库之间的复制、CDC、配置发布属于操作步骤,本文未执行业务迁移。官方机制与教学设计分别标识,不能把设计当作项目已有功能。

11.1 从项目入口还原路由,而不是从表名猜算法

源码事实:TableShardingRuleConfig.tableShardingRule〔本地文件〕 先检查方法参数中的 RouterInfo 或相关集合;未直接得到路由时,再取 ActionContextHolder 中的用户。READ_CONFIG 分支读取用户配置中的表号,以用户 ID 取模结果作为默认值;MODE 分支按用户 ID 取模;两者的库号都从用户配置读取。这说明显式路由参数可能影响通常的用户上下文路径,排查时不能只盯住取模表达式。

继续读 DataBaseUtil〔本地文件〕:初始化时会写入各表的取模结果,getFkId 和 getTable 再从配置读取库表号;该类也提供 JVM 缓存相关方法。注意“存在缓存方法”不等于“本章这个调用点使用了缓存”,前面的规则直接调用的就是 getFkId 与 getTable。迁移时应沿实际调用链检查缓存,不能凭工具类里有缓存就断言所有路由缓存两小时。

另一个入口是 TableShardingUtil.calculateTableShardingNumber〔本地文件〕,其中若干售后逻辑表配置了取模张数。它只能说明这个工具覆盖的表,不代表全项目都按相同数量分表。DataSourceAspect〔本地文件〕 则负责动态数据源键,属于另一层路由。写一个正确的 Mapper,需要同时知道这些层是否参与当前调用。

由此得到一个排查推导:同一 SQL 在命令行查得到、接口查不到,可能是上下文用户、显式 RouterInfo、表规则或数据库前缀不同。应记录逻辑表、租户、路由版本、目标库表与 SQL 模板,不记录连接口令。项目字段常为 user_id,教材统一用 tenant_id=1 表达隔离维度;这不是认定所有项目用户 ID 都可不经业务分析等价为租户 ID。

11.2 分片键不是普通筛选条件

假设教学规则是 order_id % 2。1001 在表 1,1002 在表 0。查询带着分片键,路由器可以缩小目标;只带创建时间,可能需要访问所有分片后归并。真实系统若以租户决定分片,那么仅有订单 ID 并不足够定位,接口需要租户上下文或额外目录。路由条件同时影响资源开销和隔离,不能为了减少参数而随意省掉。

主键唯一也有作用域。两个独立实例各自 AUTO_INCREMENT 都能产生 1001,本地唯一约束不会互相通知。可以使用全局生成 ID,或将 (tenant_id, order_id) 作为业务身份;但如果同一租户也分布在多个分片,还必须确保业务唯一性协议覆盖所有可能目标。不要以为主键字段名一样就自然全局唯一。

反例是把分片数从 2 改为 4,然后直接发布。1001 的取模仍为 1,看起来没问题;1003 的结果却从 1 变成 3,旧记录仍在旧表 1,新查询去了表 3。单个租户或订单冒烟通过不能证明全量路由兼容。扩容实际改变了记录到物理位置的函数,必须迁数据或引入版本化映射。

跨分片分页也不是把每个分片的第十页拼起来。全局 ORDER BY created_at DESC, order_id DESC 的前 20 条可能全部来自一个分片。正确归并要取得足够候选,再按同一稳定全序排序;深 OFFSET 会放大扫描与传输。按最后一条 (created_at, order_id) 做游标分页有助于减少深分页成本,但更新排序字段和快照变化仍需产品语义约束。跨分片 JOIN 与全局聚合的执行范围同样必须测量。ShardingSphere 路由引擎

11.3 独立初始化:用路由目录观察迁移状态

在自己创建的 MySQL 实验实例执行以下 SQL,不依赖第十章的库。重复实验时可以换一个数据库名;不要在未知库中先执行清空语句。

CREATE DATABASE lab11;
USE lab11;
CREATE TABLE lab_route (
  tenant_id BIGINT PRIMARY KEY,
  active_shard VARCHAR(16) NOT NULL,
  route_epoch BIGINT NOT NULL,
  phase VARCHAR(16) NOT NULL
) ENGINE=InnoDB;
CREATE TABLE lab_order_old (
  tenant_id BIGINT NOT NULL,
  order_id BIGINT NOT NULL,
  amount DECIMAL(12,2) NOT NULL,
  row_version BIGINT NOT NULL,
  deleted TINYINT NOT NULL DEFAULT 0,
  PRIMARY KEY(tenant_id,order_id)
) ENGINE=InnoDB;
CREATE TABLE lab_order_new LIKE lab_order_old;
INSERT INTO lab_route VALUES(1,'old',1,'NORMAL');
INSERT INTO lab_order_old VALUES
 (1,1001,100.00,1,0),(1,1002,60.00,1,0),(1,1003,20.00,1,0);
SELECT tenant_id,COUNT(*) AS n,SUM(amount) AS total
FROM lab_order_old WHERE tenant_id=1 AND deleted=0 GROUP BY tenant_id;
-- 预期 tenant_id=1,n=3,total=180.00

route_epoch 是本章提出的教学字段,项目现有用户配置并未因此自动具备版本屏障。它的意义是让应用携带的旧路由能够被识别,而不是用一个更新时间猜测路由是否新鲜。迁移状态也不是装饰:NORMAL 可正常写,COPYING 仍写旧位置并捕获增量,FENCED 禁止新写入,CUTOVER 使用新位置,观察期内保留旧数据与变更证据。

先将目录改为 COPYING,再复制本实验静态全量:

UPDATE lab_route SET phase='COPYING' WHERE tenant_id=1 AND route_epoch=1;
INSERT INTO lab_order_new SELECT * FROM lab_order_old WHERE tenant_id=1;
UPDATE lab_order_old SET amount=120.00,row_version=2
WHERE tenant_id=1 AND order_id=1001;
UPDATE lab_order_old SET deleted=1,row_version=2
WHERE tenant_id=1 AND order_id=1003;
SELECT 'old' AS place,COUNT(*) AS n,SUM(amount) AS total
FROM lab_order_old WHERE tenant_id=1 AND deleted=0
UNION ALL
SELECT 'new',COUNT(*),SUM(amount)
FROM lab_order_new WHERE tenant_id=1 AND deleted=0;
-- 旧位置 2 行/180.00;新位置 3 行/180.00

这组刻意构造的数据说明,只核对金额和会漏掉差异。行数也不够:把两笔订单金额分别加十减十,数量和金额和都不变,但明细已经错误。分层校验应先比较行数与总额,再按稳定主键分段比较字段和版本,最后核查删除标记及关键业务不变量。

11.4 全量与增量之间必须有交接点

真实迁移不能把一张持续变化的表分页读完就称为一致快照。第一页读取后可能发生删除,后面页可能看到更晚版本;基于 OFFSET 的扫描还可能因插入删除跳行。可选择一致性快照配合精确日志起点,或经过验证的 CDC 快照算法。必须有一个可解释的水位 P0:目标全量代表 P0 的状态,随后应用 P0 之后的变化。若全量扫描并非单一快照,就需要窗口、去重与版本控制来合并变化,不能假造一个全局时刻。

本实验用明确的两个版本 2 事件模拟增量。下面只更新已存在的目标行,完整通用迁移还必须覆盖新增行、删除、主键变化以及 schema 变化。

UPDATE lab_order_new n JOIN lab_order_old o
  ON n.tenant_id=o.tenant_id AND n.order_id=o.order_id
SET n.amount=o.amount,n.row_version=o.row_version,n.deleted=o.deleted
WHERE o.tenant_id=1 AND o.row_version>n.row_version;
SELECT o.order_id,o.row_version AS old_v,n.row_version AS new_v,
       o.amount AS old_amount,n.amount AS new_amount,
       o.deleted AS old_deleted,n.deleted AS new_deleted
FROM lab_order_old o JOIN lab_order_new n
  ON n.tenant_id=o.tenant_id AND n.order_id=o.order_id
WHERE o.tenant_id=1
ORDER BY o.order_id;

预期 1001 为 120.00/版本 2,1002 为 60.00/版本 1,1003 为删除标记 1/版本 2,两侧一致。保留 tombstone 可以阻止迟到的版本 1 把已删除订单复活。若源没有可比较的行版本,应建立源日志分区和偏移量的比较规则;不同源库的 binlog 序号不能当成一条全局数轴。

最后一次追平之前冻结租户 1 的新写入,等待旧位置正在执行的事务结束,记录最终水位 P1,确认目标已应用到 P1,然后再改目录。教学 SQL 如下:

UPDATE lab_route SET phase='FENCED'
WHERE tenant_id=1 AND route_epoch=1 AND phase='COPYING';
-- 操作门禁:旧写入已排空,增量到 P1,校验通过,再执行下一句。
UPDATE lab_route SET active_shard='new',route_epoch=2,phase='CUTOVER'
WHERE tenant_id=1 AND route_epoch=1 AND phase='FENCED';
SELECT ROW_COUNT(); -- 必须为 1,否则检查并发迁移或状态错误

仅更新目录并不能拦住已经拿到旧路由的请求。应用写入协议要能校验 epoch,或者通过统一写入口、租约、旧分片写保护等方式形成 fencing。下面本地实验利用同一数据库事务演示旧 epoch 拒绝写入,不把它当跨库实现:

START TRANSACTION;
SELECT route_epoch,phase FROM lab_route WHERE tenant_id=1 FOR UPDATE;
UPDATE lab_order_old o JOIN lab_route r ON r.tenant_id=o.tenant_id
SET o.amount=999.00
WHERE o.tenant_id=1 AND o.order_id=1001
  AND r.route_epoch=1 AND r.active_shard='old' AND r.phase='NORMAL';
SELECT ROW_COUNT(); -- 切换后应为 0,业务必须将它视为拒绝而非成功
ROLLBACK;

跨实例时本地行锁不能同时锁住目录服务和另一个数据库。实现者要单独设计租约撤销、路由分发确认和写入口排空,或者选择有明确边界的短暂停写。把这个问题藏在“更新缓存”四个字里,会留下双写窗口。

11.5 双写不是迁移正确性的证明

常见教学反例:先写旧库成功,再写新库超时,接口返回失败;用户重试导致旧库写两次,新库可能一次或两次。更危险的是第二次写其实成功,只是响应丢失。两个普通 JDBC 事务不能靠 try/catch 自动组成跨库原子事务。若选双写,至少要有幂等键、可重放事件、明确的权威源和持续校验;否则全量加 CDC 加短暂停写往往更容易证明边界。

回滚也有阶段。切换前可以丢弃未承接新流量的目标副本并重建。切换后若新位置已收到订单 1004,直接把路由改回旧位置会让 1004 消失。此时必须先反向同步或合并新写入,再冻结新入口、验证反向水位、切回并隔离新位置。是否支持回滚,应在迁移方案中用具体状态描述,不能只写“有问题回滚”。

故障时刻 旧位置 新位置 合理处理
全量中断 仍权威且持续变化 部分数据 保持旧路由,恢复或重建全量
增量落后 仍权威 缺 P1 后的事件 暂缓切换,查 backlog 与错误
目录切换后旧请求到达 应被拒绝 新权威 验证 fencing,禁止继续双主写
新位置已有新增后申请回切 缺少新订单 含新订单 先反向追平,不能直接改目录

11.6 在线 DDL 与 expand/contract:迁移的不只是行

订单金额从 amount 演进为 amount_cents 时,直接重命名字段会同时破坏旧应用、旧 Mapper、CDC 字段映射和报表任务。expand/contract 把一次破坏性变化分为兼容阶段:先扩展 schema,部署能同时处理新旧字段的代码,再回填历史值,验证后切换读取,最后收缩旧字段。每一步都应有回退边界。

在初始化后的实验表执行:

SET SESSION lock_wait_timeout=3;
ALTER TABLE lab_order_old ADD COLUMN amount_cents BIGINT NULL,
  ALGORITHM=INSTANT;
ALTER TABLE lab_order_new ADD COLUMN amount_cents BIGINT NULL,
  ALGORITHM=INSTANT;

这类简单 InnoDB 尾部加列在选定版本可尝试 INSTANT,但实际表的行格式、索引、列数和版本限制可能使它失败。显式指定算法的价值是“不满足条件就失败”,避免无意退化为昂贵操作。INPLACE 也不等于不重建表,INSTANT 更不等于不需要元数据锁。MySQL 在线 DDL 操作与限制

先把所有写入者升级为同一事务内维护 amount 与 amount_cents,包括定时任务、补偿脚本和 CDC 写入者,再按主键区间回填。下面是一个小批次而非全表长事务:

UPDATE lab_order_old
SET amount_cents=CAST(ROUND(amount*100) AS SIGNED)
WHERE tenant_id=1 AND order_id BETWEEN 1001 AND 1002
  AND amount_cents IS NULL;
UPDATE lab_order_old
SET amount_cents=CAST(ROUND(amount*100) AS SIGNED)
WHERE tenant_id=1 AND order_id=1003 AND amount_cents IS NULL;
SELECT order_id FROM lab_order_old
WHERE tenant_id=1 AND
 (amount_cents IS NULL OR amount_cents<>CAST(ROUND(amount*100) AS SIGNED));
-- 预期没有差异行;目标表要独立完成对应回填与检查

回填脚本按 NULL 过滤可以重入,但不是完整并发保证:如果仍有旧程序只改 amount,新字段会立刻过时。正确顺序必须先保证所有写入兼容,再回填和校验,灰度切新读,并观察旧字段使用率降到零。删除旧字段是最后一步,必须覆盖应用回滚窗口、历史任务、DTS schema 识别与报表消费契约。金额转换还需明确币种、精度、溢出和舍入规则,不能把所有币种都偷偷假定为两位小数。

可操作的锁实验:会话 A 开事务查询实验表并保持不提交;会话 B 设置三秒 lock_wait_timeout 后执行加列。观察 B 可能因等待元数据锁超时,然后 A 提交,再重试 B。在线 DDL 执行期间仍存在需要排他元数据锁的阶段,排队的 DDL 还可能影响后续请求。因此上线不仅看“支持 LOCK=NONE”,还应观察长事务、锁队列、复制延迟、磁盘空间和回填速率。MySQL 在线 DDL 限制

11.7 练习与参考答案

练习一: 只检查租户 1 的订单 1001 后,把 %2 改成 %4,为什么验收不充分?

答案: 1001 在两个规则下都落到 1,无法覆盖位置改变的输入。至少加入 1003 等余数变化记录,遍历路由边界,并确认旧数据实际搬迁位置。应检查所有分片、历史数据和回退映射,不是只测试新建订单。

练习二: 实验中旧库和新库金额和都是 180.00,为什么仍不能切换?

答案: 旧库 1001 增加了 20,1003 被删除,金额变化抵消;新库仍有旧版本和多余行。应比较数量、主键集合、删除标记、版本及金额明细,在相同水位下得到差异为空,才有业务内容一致的证据。

练习三: 新库已收订单 1004,产品要求立即回旧库,如何说明所需步骤?

答案: 先停止或隔离新写入,记录新位置最终水位,反向同步 1004 等变化,校验旧位置追平,再变更 epoch 与入口;清理旧连接和缓存后恢复写入。若无反向通道,就不能承诺无损快速回滚,应选择修复新位置或受控停机合并。

练习四: ALGORITHM=INSTANT 超时是否证明 MySQL 不支持该算法?

答案: 不一定。算法不支持和等待元数据锁超时是不同错误,应保存错误码、锁等待与长事务证据。释放实验会话 A 后重试可区分锁问题。不能为了“赶快成功”直接删去算法限制,让未知规模的表悄悄走 COPY。

本章验收材料应包含路由前后快照、差异查询、旧 epoch 写入拒绝记录、全量与增量交接水位以及回滚阶段说明。本文只提供独立 SQL 和操作路径,没有替项目实现版本路由、运行迁移或修改任何业务代码。

原始文档 · database-course/12-CDC同步一致性与数据修复.md

12 CDC 同步一致性与数据修复:消息消费成功,不等于报表正确

用户在订单页看到 120 元,报表页仍显示 100 元,第一反应往往是“刷新缓存”。但 ERP 的报表可能经历源事务、binlog、DTS 订阅、业务转换、目标表写入、聚合查询等多个阶段。缓存只是可能的一层。后端工程师需要能指出差异发生在哪个阶段、可以等待还是必须修复,以及重放会不会把正确数据再次改错。

证据与执行边界。 本章以当前 erp-dts 源码说明真实调用结构,以 PostgreSQL 16 语法编写独立教学接收端,统一 tenant_id=1。选择 PostgreSQL 仅为清楚演示 UPSERT 与事务,不表示项目 DTS 使用本章表结构,也不表示 report-pro 必然连接标准 PostgreSQL。业务服务未连接,线上消费位点未读取或修改;实验预期结果与源码风险推导不冒充线上事故事实。

12.1 CDC 保存变化,业务需要解释变化

CDC 是 Change Data Capture,即捕获数据变化。以行日志为例,源表一笔更新会产生关于某行变更的事件,订阅端再把事件转换成目标模型。数据库复制通常努力保持源库结构与数据的副本,而报表 CDC 可能展开一对多明细、丢弃不关心的列、计算币种金额或只保留部分时间范围。因此报表正确性不仅是“日志没丢”,还包括转换规则是否符合统计口径。

源码事实:DTSListenerConfiguration〔本地文件〕 构造订阅消费入口并启动消费者;AbsCustomGroupRecordListener.consume〔本地文件〕 根据监听器的 predicate 分发记录,各监听器异常被捕获,无匹配监听器时会提交记录。该层表示“谁接收事件”,还没有证明业务落库已完成。

再读 AbstractConsumerListener〔本地文件〕:consume 可先入队并按条件批量排出;extracted 转模型,模型为空时提交,否则根据 consumeWhetherCommit 返回值提交。commit 最终调用记录的 commit("")。这里的 commit 是订阅确认,不是目标数据库 JDBC 事务的 COMMIT,两者即使名字相同,也没有自动组成一个原子操作。

阿里云 SDK 文档要求先消费数据再调用提交;未确认记录可能再次出现,所以重复处理应作为正常故障路径设计,而非仅在“消息系统不稳定”时才考虑。DTS SDK 消费说明 DTS 常见问题

12.2 把源码中的异常边界翻译成故障时序

RdsTradeDtsSyncConsumerListener.executeAction〔本地文件〕 中,交易写入、物流预警更新、运单关系更新等部分调用各有捕获异常后记录日志的代码;订单 batchSave 位于其中的主流程,方法末尾返回 true。它还包含币种转换与删除时间范围过滤,说明消费成功不只取决于 SQL 是否执行,也取决于转换与筛选语义。

风险推导是:某个被捕获的分支失败,但后续主流程成功并返回 true,外层可能推进确认,从而出现某张派生表暂时或长期缺数。这不是断言线上没有其他补偿机制;要证实实际故障,还需查运行配置、补偿任务、事务传播以及该记录的真实流转。教材保留这个边界,避免把局部阅读升级为未经证实的线上结论。

故障点 目标数据库 订阅确认 重启后需要的行为
写入前崩溃 没有新数据 未确认 重放并正常写入
数据提交后崩溃 数据已生效 未确认 重放但不能重复计数
先确认再写入,随后崩溃 没有新数据 已确认 可能永久遗漏,需外部修复
一个目标成功、另一个失败后确认 部分生效 已确认 不能仅等自动重试,需要补偿证据

“至少一次”与“恰好一次业务效果”不是同一层概念。一个可重放的消费者可以接受重复投递,并通过事件身份、版本检查及本地事务,使同一事件只产生一次业务效果。但目标数据库、远程 API 和消息确认若不在同一事务域,就不能简单宣称端到端 exactly once。远程副作用通常还要 outbox、幂等接口或独立状态机配合。

12.3 独立初始化:一个可解释的教学接收端

在标准 PostgreSQL 的独立数据库中执行以下内容。读者可先用 createdb lab12 建库,再用 psql -X -v ON_ERROR_STOP=1 -d lab12 进入;连接参数必须指向自己的实验实例。表在专用 lab12 schema 下,重复实验请新建空数据库,不依赖其他章节。

CREATE SCHEMA lab12;
SET search_path=lab12,public;
CREATE TABLE lab_event_inbox (
  tenant_id bigint NOT NULL,
  event_id text NOT NULL,
  source_partition text NOT NULL,
  source_offset bigint NOT NULL,
  payload_hash text NOT NULL,
  PRIMARY KEY(tenant_id,event_id)
);
CREATE TABLE lab_order_projection (
  tenant_id bigint NOT NULL,
  order_id bigint NOT NULL,
  amount numeric(12,2) NOT NULL,
  source_version bigint NOT NULL,
  is_deleted boolean NOT NULL,
  PRIMARY KEY(tenant_id,order_id)
);
CREATE TABLE lab_source_snapshot (
  tenant_id bigint NOT NULL,
  order_id bigint NOT NULL,
  amount numeric(12,2) NOT NULL,
  source_version bigint NOT NULL,
  is_deleted boolean NOT NULL,
  PRIMARY KEY(tenant_id,order_id)
);

事件 ID 应是稳定身份,例如源实例身份、日志文件/事务与行序号的组合,或订阅系统文档保证稳定的事件标识。同一事务可能修改多行,仅用 GTID 去重整条行事件会误丢该事务其他行。本实验用 E1、E2 等手工 ID,并把 row version 设为可比较的单订单版本;它不是声称 DTS 自动提供这个字段。

创建教学处理函数,把去重和目标行写入放在同一个 PostgreSQL 事务中。它还检查“相同 ID、不同内容”这种数据契约错误,避免用 ON CONFLICT 把冲突偷偷吞掉。

CREATE FUNCTION lab12.lab_apply(
  p_event text,p_offset bigint,p_order bigint,p_version bigint,
  p_amount numeric,p_deleted boolean
) RETURNS text LANGUAGE plpgsql AS $$
DECLARE
  v_rows integer;
  v_hash text;
  v_old_hash text;
BEGIN
  v_hash := md5(jsonb_build_array('p0',p_offset,p_order,p_version,
                                p_amount,p_deleted)::text);
  INSERT INTO lab12.lab_event_inbox
    (tenant_id,event_id,source_partition,source_offset,payload_hash)
  VALUES(1,p_event,'p0',p_offset,v_hash)
  ON CONFLICT(tenant_id,event_id) DO NOTHING;
  GET DIAGNOSTICS v_rows=ROW_COUNT;
  IF v_rows=0 THEN
    SELECT payload_hash INTO v_old_hash FROM lab12.lab_event_inbox
    WHERE tenant_id=1 AND event_id=p_event;
    IF v_old_hash IS DISTINCT FROM v_hash THEN
      RAISE EXCEPTION 'same event id with different payload';
    END IF;
    RETURN 'duplicate';
  END IF;
  INSERT INTO lab12.lab_order_projection AS dst
    (tenant_id,order_id,amount,source_version,is_deleted)
  VALUES(1,p_order,p_amount,p_version,p_deleted)
  ON CONFLICT(tenant_id,order_id) DO UPDATE
  SET amount=EXCLUDED.amount, source_version=EXCLUDED.source_version,
      is_deleted=EXCLUDED.is_deleted
  WHERE EXCLUDED.source_version>dst.source_version;
  GET DIAGNOSTICS v_rows=ROW_COUNT;
  RETURN CASE WHEN v_rows=1 THEN 'applied' ELSE 'stale' END;
END;
$$;

UPSERT 的条件检查作用于发生冲突的行,并参与事务并发控制;本实验用它阻止旧版本覆盖新版本。PostgreSQL INSERT/ON CONFLICT MD5 在这里仅是教学内容指纹,不是对抗恶意碰撞的安全校验。生产事件身份、规范化序列化、同版本冲突处理和留存期限都要另行定义;同一业务版本若能合法对应不同内容,本模型就不成立,必须先修正版本契约。

12.4 重复、乱序与删除复活:逐条观察结果

依次执行,注意两个版本不是按数字顺序到达:

SELECT lab12.lab_apply('E1',1,1001,1,100.00,false); -- applied
SELECT lab12.lab_apply('E1',1,1001,1,100.00,false); -- duplicate
SELECT lab12.lab_apply('E3',3,1001,3,120.00,false); -- applied
SELECT lab12.lab_apply('E2',2,1001,2,110.00,false); -- stale
SELECT * FROM lab12.lab_order_projection WHERE tenant_id=1;
-- 一行:1001 / 120.00 / 版本3 / 未删除
SELECT lab12.lab_apply('E4',4,1001,4,120.00,true);  -- applied
SELECT lab12.lab_apply('E2-replay',2,1001,2,110.00,false); -- stale
SELECT COUNT(*) FROM lab12.lab_order_projection
WHERE tenant_id=1 AND NOT is_deleted;
-- 0,迟到更新没有复活订单

如果在删除时物理删除目标行及版本信息,迟到 E2 将看不到冲突行,便能重新插入订单。tombstone 让“这个订单已在版本 4 删除”的事实继续参与排序。墓碑不能永远不清理,但清理前必须证明所有可能重放窗口、备份恢复窗口与迟到事件都不会再带来更老版本,或把删除水位保存在独立结构里。

再模拟数据库提交前崩溃,用回滚代替杀进程:

BEGIN;
SELECT lab12.lab_apply('E5',5,1002,1,50.00,false);
ROLLBACK;
SELECT COUNT(*) FROM lab12.lab_event_inbox WHERE tenant_id=1 AND event_id='E5';
-- 0,去重记录与业务投影一起回滚
SELECT lab12.lab_apply('E5',5,1002,1,50.00,false); -- applied
SELECT lab12.lab_apply('E5',5,1002,1,50.00,false); -- duplicate

最后两次调用模拟“提交后、确认前崩溃”引发的重放。在单条自动提交函数调用成功后,消费者才可以尝试确认订阅;若确认失败,允许重放,函数返回 duplicate。反例是先把 event_id 写入 Redis,再写数据库:进程在两步之间崩溃,重试被 Redis 去重挡掉,业务数据反而永远缺失。

12.5 业务统计为什么不能对每个事件直接加金额

如果 E1 表示金额 100,E3 表示改成 120,把两次 after image 都加进日报会得到 220,而订单当前实付只有 120。重复投递再加一次,错误还会放大。一个稳健教学方案是先建立一订单一行的最新事实表,再从事实表聚合;需要实时增量聚合时,在同一事务内读取受版本保护的旧值,计算新旧差额,并同步更新聚合表。

删除也要撤销旧贡献,状态从未支付改已支付要增加贡献,退款跨日还要明确究竟修订原成交日还是记录退款发生日。跨币种统计若缺汇率,不能悄悄把原币金额放进人民币总额。源码中的币种转换分支正提示我们:对账应保存币种、汇率日期、转换规则版本和异常状态,而不是只比较一列 payment。

多表 JOIN 还有短暂撕裂窗口:订单事件先到,明细后到,报表会看到无明细的主单;如果把空明细当成真实零金额,就把传输过程误当业务状态。可按源事务边界成组应用、等待业务完成标识、采用水位封账,或明确报表处于暂定状态。选择哪种方式取决于消费者是否保留源事务信息、目标是否支持所需事务及延迟预算,不能凭“用了 CDC”就保证多表一致。

12.6 水位不是 max(offset):并行确认的洞

假设分区 p0 中偏移 10 处理很慢,11 与 12 已完成。如果只保存最大完成偏移 12,重启从 13 开始,就跳过了 10。安全的确认前沿应是“从上次确认点开始,已经连续完成的最大位置”,而不是所有 worker 完成值中的最大值。若系统有多个分区,水位是每分区一项的向量,不能取所有分区偏移的最大值假装全局完成。

这种规则需要和 SDK 的实际确认语义核对,项目代码中的 record.commit 不足以单独推断底层批次、分区或持久化行为。操作演练可用纸面序列:初始连续点 9,完成 11 后仍为 9,完成 12 后仍为 9,完成 10 才推进为 12;若 10 放入死信队列,则必须明确是阻塞分区、业务隔离后推进,还是接受不完整水位,不能无声略过。

监控至少分开记录源提交时间、订阅接收时间、目标提交时间、连续确认位置和业务完整水位。应用 now() 不是源提交时间,乱序到达时也不是版本号。报表页面显示“更新于 10:03”之前,应说明这是某个请求完成时间,还是所有相关分区至少已处理到的业务水位。

12.7 数据修复必须比正常消费更谨慎

先制造一个可审计差异。以下快照是教学上已确认到同一业务水位的源状态,不是真实远程查询;其中 1001 已删除,1002 应为 50 元,1003 缺失在目标。

INSERT INTO lab12.lab_source_snapshot VALUES
 (1,1001,120.00,4,true),(1,1002,50.00,1,false),(1,1003,30.00,1,false);
UPDATE lab12.lab_order_projection SET amount=5.00
WHERE tenant_id=1 AND order_id=1002;
SELECT COALESCE(s.order_id,t.order_id) AS order_id,
 s.amount AS source_amount,t.amount AS target_amount,
 s.source_version AS source_v,t.source_version AS target_v
FROM lab12.lab_source_snapshot s
FULL JOIN lab12.lab_order_projection t USING(tenant_id,order_id)
WHERE COALESCE(s.tenant_id,t.tenant_id)=1
 AND (s.order_id IS NULL OR t.order_id IS NULL OR
      (s.amount,s.source_version,s.is_deleted)
      IS DISTINCT FROM (t.amount,t.source_version,t.is_deleted))
ORDER BY order_id;
-- 差异:1002 的 50/5;1003 的 30/NULL

正常消费者拒绝相同版本覆盖,故不能指望重放 E5 就修正 1002:收件箱会返回 duplicate;即使换事件 ID,版本相等也会返回 stale。修复需要显式授权的特殊路径。本实验在本地事务中暂停目标写入,按已核定快照修复,并用 RETURNING 留下结果:

BEGIN;
LOCK TABLE lab12.lab_order_projection IN SHARE ROW EXCLUSIVE MODE;
INSERT INTO lab12.lab_order_projection AS t
SELECT * FROM lab12.lab_source_snapshot WHERE tenant_id=1
ON CONFLICT(tenant_id,order_id) DO UPDATE
SET amount=EXCLUDED.amount,source_version=EXCLUDED.source_version,
    is_deleted=EXCLUDED.is_deleted
WHERE t.source_version<=EXCLUDED.source_version
RETURNING tenant_id,order_id,amount,source_version,is_deleted;
COMMIT;
-- 再执行上面的差异查询,预期零行;有效金额合计为 80.00

这不是可以直接用于生产的整表锁方案。生产修复要按租户和主键区间限流,记录修复单号、源水位、旧值、新值、执行者和校验结果;并发更新时以版本条件拒绝覆盖更高版本。相同版本修复只有在源快照确为权威且转换规则一致时才成立。目标多余行需要单独审查:源快照可能过滤了历史数据,不能看到源缺行就直接删除目标。涉及外部接口副作用时,还要独立补偿,SQL 对账只覆盖数据库状态。

修复与重放期间保留原始事件及 schema 版本很重要。若列从元改为分而事件没有版本,重放旧消息可能把 100 元解释成 100 分。采用第十一章的 expand/contract,先让消费者同时识别旧新结构,回填并验证,然后再收缩字段。源日志保留期必须覆盖最大停机、重放、调查与修复窗口,否则位点落后到日志已清理时只能重新建立可信全量基线。

12.8 练习与参考答案

练习一: 数据已写入但确认失败,消费者该把这次写入撤销吗?

答案: 不应因为确认失败就盲目撤销已提交业务效果。保留提交结果,允许再次投递,通过与投影同事务的去重记录返回 duplicate;若撤销后确认其实成功,反而会丢数据。目标提交和确认之间的不确定性通过可重放设计处理。

练习二: 对已删除订单直接删除目标行,为何可能复活?

答案: 旧版本晚到时不再有目标行可比较,UPSERT 走插入分支。保留删除版本或独立删除水位能挡住旧更新;清理墓碑须覆盖日志保留、重放与恢复窗口。

练习三: 运行修复实验,为什么重新发送 E5 不会把 5 元修成 50 元?

答案: E5 已存在于收件箱,普通重放被去重;换 ID 也不能通过严格大于的版本条件。修复必须有同版本覆盖的审计路径与权威源证明,不能随意把版本加一伪造业务变化。

练习四: 分区 p0 完成 101、103、104,102 失败,应确认到哪里?

答案: 若此前连续点为 100,最多确认到 101。先处理 102 的缺口,不能直接写 104。其他分区可以按自身连续水位前进,但报表全量完成状态必须结合所有相关分区。

读者验收时应保留 applied/duplicate/stale 输出、事务回滚后的收件箱数量、删除后有效行数、修复前后差异和有效金额合计。本文教学接收端不对项目作业务代码修改,也不授权调整真实 DTS 位点。

原始文档 · database-course/13-PostgreSQL与报表数据库.md

13 PostgreSQL与报表数据库

本目录report-pro DAL依赖〔本地文件〕声明PostgreSQL驱动,利润Mapper〔本地文件〕使用FILTER和复合DISTINCT等语法。这证明存在PostgreSQL协议路径和相关SQL,不能证明线上必然是原生PostgreSQL或某个兼容分析产品。本章独立示例以PostgreSQL16为基线,兼容产品要另查支持范围。

1. 关系概念可以迁移,具体机制要重学

表、约束、JOIN、聚合、事务等思想相通,但MySQL反引号、ON DUPLICATE KEY、日期函数不能直接复制。PostgreSQL用双引号引用区分大小写标识符,常规未引用名称折叠为小写。UPSERT通常用ON CONFLICT,序列或identity的取号不是无空洞票据系统,事务回滚不应期待号码连续。

NUMERIC适合精确十进制金额,浮点适合允许误差的测量。timestamptz表达时刻并按会话时区显示,不保存原始输入时区名称;timestamp without time zone表达不带时区的墙上时间。必须定义业务日所属时区,不能因为显示了北京时间就认为存储的是北京时间字符串。

JSONB提供结构化检索,但不替代关系约束;对频繁过滤字段可以设计表达式索引或拆到普通列。数组和复合类型能简化某些数据表达,也增加跨语言映射需求。SQL更强不等于所有业务结构都该塞到JSON。

2. 一个独立的利润实验

在自己的空教学库执行以下脚本;金额单位为元,收入与成本均按付款日统计,退款在此简化成行上数值。这个口径仅用于演示,不等于项目财务规则。

CREATE TABLE lab_pg_sale (
  tenant_id bigint NOT NULL,
  line_id bigint NOT NULL,
  order_id bigint NOT NULL,
  paid_at timestamptz NOT NULL,
  amount numeric(14,2) NOT NULL,
  cost numeric(14,2),
  refund numeric(14,2) NOT NULL DEFAULT 0,
  PRIMARY KEY (tenant_id,line_id)
);
INSERT INTO lab_pg_sale VALUES
 (1,1,101,'2026-01-01 01:00:00+00',60,30,10),
 (1,2,101,'2026-01-01 01:00:00+00',40,20,0),
 (1,3,102,'2026-01-02 01:00:00+00',50,NULL,0);

SELECT (paid_at AT TIME ZONE 'Asia/Shanghai')::date AS business_day,
       count(DISTINCT order_id) AS orders,
       sum(amount) AS sales,
       sum(refund) AS refunds,
       sum(cost) AS known_cost,
       count(*) FILTER (WHERE cost IS NULL) AS missing_cost_rows
FROM lab_pg_sale WHERE tenant_id=1
GROUP BY (paid_at AT TIME ZONE 'Asia/Shanghai')::date
ORDER BY business_day;

预期1月1日订单1、销售100、退款10、已知成本50、未知0;1月2日订单1、销售50、退款0、已知成本NULL、未知1。第二天利润不能简单报50,因为成本未知。COALESCE方便展示,不应该掩盖质量缺口。

3. 报表的粒度与时间口径

原始行可能是订单明细,不是主订单。COUNT(*)是行数,COUNT DISTINCT order_id是订单数;跨平台订单ID可能冲突,需要同时纳入platform。项目Mapper的count(distinct (platform,order_id)) FILTER(...)说明它显式考虑了子单身份与空值过滤,不能随意改为一个字符串ID计数。

销售额、商品成本、退款可能发生在不同时间。按付款时间看成交利润和按退款发生时间看当日资金变化是不同报表,不能拿它们直接对账。维度要记录店铺、租户、币种、业务时区与口径版本,汇总字段名称应明确毛额、折扣、运费和退款是否已包含。

过滤时间仍推荐半开区间>=start AND <end。为利用原始时间索引,可先将本地业务日起止转换为两个绝对时刻,再比较paid_at;在WHERE给每行套时区函数可能改变索引利用。分组表达式可以用业务日,但过滤与分组不能使用不一致时区。

4. 条件聚合、DISTINCT ON与UPSERT

FILTER让不同聚合拥有不同输入集合,例如sum(amount) FILTER(WHERE...);它不是WHERE的替代,主WHERE先限制共同输入。DISTINCT ON可取每组一行,但ORDER BY要与分组键和稳定尾键协调,否则“最新一条”没有确定含义。

SELECT DISTINCT ON (tenant_id,order_id)
       tenant_id,order_id,line_id,paid_at
FROM lab_pg_sale
ORDER BY tenant_id,order_id,paid_at DESC,line_id DESC;

这里取的是每订单按时间与行号排序的代表行,不是汇总订单金额。ORM若只映射该行却当成完整订单,会丢失其他明细。

ON CONFLICT可以依赖指定唯一约束处理重复写入,RETURNING取得实际写入结果。幂等同步还要比较源版本,防较旧事件覆盖新状态。仅仅“重复时UPDATE全部字段”不解决乱序。

5. MVCC、VACUUM与长事务

PostgreSQL更新产生新tuple版本,旧版本在没有读者需要后才能回收。普通VACUUM主要让空间可重用、更新相关可见性状态,不必把文件缩回操作系统;VACUUM FULL重写表,锁与额外空间成本更高,不能当每小时定时清理。

autovacuum不是可随意关闭的后台噪声,负责空间与事务ID相关维护。长事务、闲置事务和复制槽保留可能阻碍回收或保留WAL,磁盘增长要定位阻塞者与水位。只有加磁盘而不处理保留原因,问题可能继续增长。官方VACUUM说明

PostgreSQL的READ COMMITTED与REPEATABLE READ机制也要单独理解,SERIALIZABLE可能检测依赖并报序列化失败,需要完整事务重试。不要把MySQL的next-key锁口诀直接搬来解释PG所有幻读行为。

6. 索引种类与实际计划

B-tree适合常规等值/范围/排序;GIN常用于JSONB、数组等多值检索;GiST支持特定搜索类型;BRIN利用块范围摘要,适合与物理顺序相关的大表列,但不能当B-tree精确定位的替代。部分索引只维护满足谓词的行,查询必须能被证明符合该谓词。

CREATE INDEX lab_pg_sale_time
ON lab_pg_sale (tenant_id,paid_at) INCLUDE (amount,refund);

EXPLAIN (ANALYZE,BUFFERS)
SELECT sum(amount-refund)
FROM lab_pg_sale
WHERE tenant_id=1 AND paid_at>='2026-01-01 00:00:00+00'
  AND paid_at<'2026-01-03 00:00:00+00';

INCLUDE列是覆盖数据,不增加同样的排序导航能力。Index Only Scan还依赖可见性映射,不能看到列都在索引里就断言不会访问heap。BUFFERS的hit/read信息帮助理解缓存访问;多个节点统计可能包含子节点,不能直接求和。官方计划解读

7. 报表刷新与可见性

先DELETE旧数据再INSERT新数据,如果不在同一事务或原子切换协议里,读者可能看到空白或半成品。若在长事务里整批重算,又可能造成锁、WAL和存储压力。可生成新批次、核对行数金额后原子切换读版本,再回收旧批次。

项目报表服务〔本地文件〕有相关删除与插入调用,应继续追调用者和事务管理器,不能只凭方法片段认定线上无事务。学习时要求画出结果对外可见的切换点。

物化视图保存结果,也要刷新;普通视图主要是查询定义,不会凭空把每次聚合变成预计算。增量维护需要定义源变化、去重、撤销与重算口径。报表水位属于用户可理解的信息,应展示“截至何时”,而不只显示一个看似精确的数字。

8. 练习与答案

一:某天成本未知,把NULL改零利润为何失真?零表示已知无成本,NULL表示不知道;应同时报告质量计数或阻止发布完整利润。

二:增加GIN为什么没加速普通租户时间查询?索引类型要匹配操作符与访问路径,JSON检索索引不能代替租户/时间B-tree。

三:DELETE大量历史数据后磁盘没缩小是否失败?逻辑删除、VACUUM可重用空间和文件缩小是不同阶段。观察死tuple与可重用空间,再决定是否需要受控重写,不盲目VACUUM FULL。

四:报表读到0是没有销售还是重算窗口?必须结合批次状态、水位、刷新事务与质量标记区分。业务结果正确性不能只靠SQL语法通过。

原始文档 · database-course/14-Redis基础命令与数据建模.md

14 Redis 基础命令与数据建模

从页面状态走向共享数据库

前端开发者容易把 Redis 理解为远程的 Map<string, object>。这个比喻只解释了按键读取,解释不了服务器重启、多个请求竞争、过期、消息确认以及一次操作超时后的未知结果。ERP 后端中的 Redis 应先按职责分类:商品摘要是可重建的缓存;任务进度是短期状态;打印去重标记参与并发控制;唯一一份导入结果则已经承担数据保存职责。职责不同,允许丢失的程度不同,不能因为类名包含 Cache 就认为内容丢失没有影响。

本章的目标是从访问方式推导结构,而不是记住九个类型名称。先学会按键取一个值,再理解对象字段、集合成员、排序、消息与近似统计,最后把这些选择放回项目调用中。数据统一属于 tenant_id=1;Redis 没有 SQL 表,本专题用 lab_ 前缀表示教学数据集,键形如 lab_order:tenant:1:1001。这些键不是项目现有约定,也不代表真实订单。

事实边界:项目事实只来自本地源码;命令语义依据文末附近链接的 Redis 官方文档。教学边界:订单、仓库坐标、时序都是合成样本。推导边界:从方法实现指出的风险不等于已发生线上事故。未执行边界:未连接业务 Redis,也没有确认其服务端版本。本专题命令基线为 Redis 7.2,实验实测版本及检查项见独立实验说明。不要把本机版本推定为部署版本。

1. 键本身就是数据模型的一部分

设计键时,先写出查询函数:loadOrder(tenantId, orderId, viewVersion)。所有影响结果的维度都必须反映在键或者权限校验中。只写 order:1001,意味着你暗中假设订单号全局唯一;加上租户,才把隔离条件表达出来。若摘要格式升级,追加 v2 可以隔离新旧序列化格式,但旧键仍需要自然过期或清理。

不要把手机号、令牌、完整查询 JSON 塞进键名;键可能出现在监控和诊断输出里。也不要把 Cluster 的 {tenant:1} 标签不加思考地放到所有键中:它会让这个租户的所有数据集中到同一槽。只有确实需要同槽原子操作的少量键才共享标签,第 17 章会继续讨论。

进入实验控制台后逐行输入:

SET lab_order:tenant:1:1001 '{"tenant_id":1,"status":"NEW","version":1}' EX 300
GET lab_order:tenant:1:1001
TYPE lab_order:tenant:1:1001
TTL lab_order:tenant:1:1001
EXISTS lab_order:tenant:1:1001

依次得到 OK、原始 JSON 字符串、string、介于 0 与 300 的剩余秒数和 1。JSON 的 status 对 Redis 仍是普通字节;GET 不会验证其中的租户,也不会反序列化。TTL=-1 表示存在但没有到期时间,TTL=-2 表示不存在,不能都解释为“过期了”。PTTL 用毫秒计时。DEL 返回实际删除的键数,UNLINK 先从键空间移除,再异步回收适合后台释放的内存。

过期是状态的一部分:普通 SET 覆盖值会去掉旧 TTL;需要保持时用 KEEPTTL,需要建立新生命周期时显式带 EX 或 PX。修改 Hash 字段通常保留整个键现有 TTL。不要把 SET、EXPIRE 两条独立命令当成不可分割的一步:客户端可能在中间退出,留下永久键。SET 官方定义、EXPIRE 官方定义给出了这些覆盖与保留规则。

2. String:快照、计数与条件写入

String 可以保存 JSON、文本、二进制,也可以保存可解析的整数。计数器应让服务器执行增量,而不是先 GET、在 Java 里加一、再 SET。两个请求都读到 9,各自写回 10,就会漏掉一次业务操作。

SET lab_counter:tenant:1:print 9
INCR lab_counter:tenant:1:print
INCRBY lab_counter:tenant:1:print 5
DECRBY lab_counter:tenant:1:print 2
MGET lab_counter:tenant:1:print lab_missing:tenant:1
SET lab_guard:tenant:1:1001 token-a NX PX 5000
SET lab_guard:tenant:1:1001 token-b NX PX 5000

计数结果依次是 10、15、13;MGET 按请求顺序返回 13、nil;短时间连续执行的第一次条件写返回 OK,第二次返回 nil。NX 是仅不存在时写,XX 是仅存在时写。返回 nil 表示条件未满足,不是网络失败。整数增量也会遇到非数字和溢出错误;金额以整数分保存通常比 INCRBYFLOAT 更容易建立精确规则,但仍需限定最大值和单位。

反例是用计数器直接充当永久业务流水号:即使增量本身原子,主从切换仍可能丢失最近增量,过期会使编号重置,网络超时后的重试会再增一次。数据库唯一约束、请求幂等标识与流水号规则是另一层要求。一次 Redis 原子命令不会自动给 HTTP 请求赋予“恰好一次”语义。

3. Hash:按字段访问的对象

一个导入任务的总数、成功数、状态适合放在 Hash;大体积失败明细则不应随每次进度查询返回。先创建,再局部修改,再读取需要的字段:

HSET lab_job:tenant:1:9001 total 10 done 0 state RUNNING
HINCRBY lab_job:tenant:1:9001 done 3
HMGET lab_job:tenant:1:9001 done total state
HSET lab_job:tenant:1:9001 state PAUSED
HGETALL lab_job:tenant:1:9001
HLEN lab_job:tenant:1:9001
HDEL lab_job:tenant:1:9001 state

第一次 HSET 返回新建字段数 3;HINCRBY 返回 3;HMGET 返回 3、10、RUNNING;覆盖 state 的 HSET 返回 0,这不表示失败,只表示没有增加新字段。HGETALL 展示三组字段值,但不应依赖返回顺序;HLEN 是 3,HDEL 是 1。Hash 的字段值也都是字节序列,没有 SQL 的列类型约束。

如果先把 done 更新为 10,下一条命令才把 state 改成 FINISHED,别的请求可以在中间读到 done=10,state=RUNNING。固定值更新可在一个 HSET 中写多个字段;涉及“读取后判断再改写”的逻辑需要第 17 章的 Lua 或 WATCH。Redis 7.2 基线下 TTL 施加于整个 Hash;不要用较新版本的字段过期功能解释旧部署。把所有订单放进一个无限增长的 Hash 也会使生命周期、迁移和批量读成本绑在一起。

4. List、Set 与 Sorted Set:顺序、唯一与排序是三件事

List 保留元素的重复和位置。教学上可用它演示待处理队列,但最简单的弹出操作不保存处理确认:消费者弹出后崩溃,元素已经离开队列。

RPUSH lab_queue:tenant:1 A B C
LRANGE lab_queue:tenant:1 0 -1
LPOP lab_queue:tenant:1
LMOVE lab_queue:tenant:1 lab_processing:tenant:1 LEFT RIGHT
LRANGE lab_processing:tenant:1 0 -1
LREM lab_processing:tenant:1 1 B

结果为长度 3、列表 [A,B,C]、A、B、[B]、删除数 1。LMOVE 把领取与转移合成一个命令,避免“弹出成功但尚未登记处理中”的空窗。它仍不提供自动超时重投,且重复业务值可能使确认不明确,真实任务需要唯一任务 ID。阻塞版本 BLPOP、BLMOVE 会等待元素,不要占用承担普通请求的唯一连接。

Set 用来回答“是否已经出现”,不保证顺序:

SADD lab_selected:tenant:1 1001 1002 1002
SISMEMBER lab_selected:tenant:1 1002
SCARD lab_selected:tenant:1
SADD lab_allowed:tenant:1 1002 1003
SINTER lab_selected:tenant:1 lab_allowed:tenant:1
SREM lab_selected:tenant:1 1001

依次返回 2、1、2、2、[1002]、1。SADD 的返回值是新成员数量,不是输入数量;交集可用于临时筛选,但不能替代最终数据库中的权限检查。SMEMBERS 一次返回全体,大集合应考虑 SSCAN 并理解它不是一致性快照。

Sorted Set 给唯一成员附加一个浮点 score,适合截止时间索引或排名。成员唯一、分数可重复,不能把“同分”误解为会覆盖。

ZADD lab_due:tenant:1 100 1001 100 1002 200 1003
ZRANGE lab_due:tenant:1 0 -1 WITHSCORES
ZRANGE lab_due:tenant:1 -inf 100 BYSCORE
ZINCRBY lab_due:tenant:1 50 1001
ZSCORE lab_due:tenant:1 1001
ZPOPMIN lab_due:tenant:1 1

最初按 (1001,100),(1002,100),(1003,200) 排列;范围查询得到 1001、1002;增量后 1001 的分数为 150;ZPOPMIN 领取的是 1002、100。相同分数按成员字节字典序排序,字符串 10 与 2 不按数值大小排序。范围读取后再 ZREM 不是原子领取;ZPOPMIN 虽原子,却不负责“是否已经到期”,需要原子条件判断。IEEE 754 双精度 score 还意味着不能把任意 64 位流水号无损当分数。

5. Bitmap 与 HyperLogLog:用空间换取什么

Bitmap 是 String 上的位操作,不是独立的键类型。它适合编号空间稠密的布尔状态,例如某个周期内第几个小仓库完成盘点。位偏移从 0 开始,偏移大并不意味着只占一个 bit 的内存。

SETBIT lab_check:tenant:1:day1 0 1
SETBIT lab_check:tenant:1:day1 2 1
GETBIT lab_check:tenant:1:day1 1
BITCOUNT lab_check:tenant:1:day1
SETBIT lab_check:tenant:1:day2 2 1
BITOP AND lab_check:tenant:1:both lab_check:tenant:1:day1 lab_check:tenant:1:day2
BITCOUNT lab_check:tenant:1:both

前两个 SETBIT 返回旧值 0;未设置的位是 0;day1 有两位为 1;BITOP 返回结果字节长度 1,最后 BITCOUNT 为 1。把超大雪花 ID 直接作为位偏移,是典型建模错误:空间与最大偏移相关。先做稳定、稠密的编号映射,或改用 Set。官方 Bitmap 说明说明其底层是字符串与位运算。

HyperLogLog 解决另一类问题:只需要估算访问过某页面的不同用户数,不需要列出用户,也不需要判断某个人是否已处理。

PFADD lab_uv:tenant:1:day1 u1 u2 u2
PFADD lab_uv:tenant:1:day2 u2 u3
PFCOUNT lab_uv:tenant:1:day1
PFMERGE lab_uv:tenant:1:all lab_uv:tenant:1:day1 lab_uv:tenant:1:day2
PFCOUNT lab_uv:tenant:1:all

本小样本通常得到 1、1、2、OK、3;PFADD 返回的是内部估计结构是否改变,不是新增了几个用户。较大样本存在统计误差;官方给出的标准误差约为 0.81%,密集表示使用约 12 KB,并非所有小 HLL 都立即占满这个数。官方 HLL 说明。用它防重复退款会失败,因为没有成员查询和精确去重证明。

6. GEO:空间索引不等于路线规划

GEOADD lab_warehouse:tenant:1 121.4737 31.2304 wh-a 121.4837 31.2304 wh-b
GEOPOS lab_warehouse:tenant:1 wh-a
GEODIST lab_warehouse:tenant:1 wh-a wh-b km
GEOSEARCH lab_warehouse:tenant:1 FROMMEMBER wh-a BYRADIUS 2 km ASC WITHDIST
ZREM lab_warehouse:tenant:1 wh-b

GEOADD 返回 2,经度在前、纬度在后。GEOPOS 返回量化后接近输入的坐标;距离约 0.95 km,具体末位不应作为业务断言;半径查询先返回距离接近零的 wh-a,再返回 wh-b。它使用地理距离近似,不理解道路、交通、仓库配送范围和可用库存。因此 ERP 的“推荐发货仓”必须在空间候选集上继续过滤,而不能直接把最近仓当成最优仓。GEO 基于 Sorted Set,删除成员用 ZREM;不要随便 ZADD 人工分数破坏地理编码。GEOSEARCH 官方语法标明该命令从 6.2 提供。

7. Stream:把追加日志与消费状态分开

Stream 适合观察“任务产生了哪些事件、哪些还没有确认”。消息体包含字段值,ID 有顺序;消费者组额外维护待确认列表 PEL。先使用固定 ID,让结果容易复核;实际生产一般让 XADD 的 * 自动生成 ID。

XADD lab_events:tenant:1 1-0 order_id 1001 event CREATED
XADD lab_events:tenant:1 2-0 order_id 1001 event PAID
XRANGE lab_events:tenant:1 - + COUNT 10
XGROUP CREATE lab_events:tenant:1 lab_workers 0
XREADGROUP GROUP lab_workers worker-a COUNT 1 STREAMS lab_events:tenant:1 >
XPENDING lab_events:tenant:1 lab_workers
XACK lab_events:tenant:1 lab_workers 1-0
XLEN lab_events:tenant:1

两个 XADD 返回各自 ID,XRANGE 返回两条完整消息。组从 0 开始能领取历史消息;若用 $ 建组则从创建时尾部之后开始。worker-a 先领到 1-0,XPENDING 数量为 1,ACK 返回 1,XLEN 仍为 2:确认消费不等于删除日志。普通 XREAD COUNT 10 STREAMS key 0 没有组状态;两个独立读者可以各自读到相同消息。

继续让 worker-a 领取 2-0 后“停机”,另一个消费者可以用 XAUTOCLAIM lab_events:tenant:1 lab_workers worker-b 60000 0-0 COUNT 10 接管空闲至少 60 秒的待确认项。它返回下次扫描游标、领取的消息,以及 7.0 起提供的已删除消息 ID 信息;不要把返回数组写死成两个元素。XAUTOCLAIM 官方说明。实验为了立即复现使用阈值 0,只适合教学,真实阈值须大于正常处理时间。

关键故障时序是:worker-a 提交数据库入库成功 → 在 XACK 前崩溃 → worker-b 接管 → 再次尝试入库。解决位置在数据库事务:用事件 ID 的唯一约束记录已处理,重放发现冲突后直接确认。相反,先 ACK 再入库,崩溃后可能永久漏处理。XTRIM ... MAXLEN ~ N 的近似裁剪可以控制内存,但不以所有消费者是否完成为前提,必须同时观测最老未确认项、组滞后与留存时间。Stream 官方说明是命令关系的依据。

Pub/Sub 则没有这个历史补读契约。SUBSCRIBE lab_notice:tenant:1 订阅后,另一个连接执行 PUBLISH lab_notice:tenant:1 refreshed,返回当前接收订阅的数量;订阅断开期间的消息不会为它保留。它适合即时通知提示,不应单独承担必须送达的业务事件。官方 Pub/Sub 交付语义明确其至多一次性质。

8. 回到源码:名称、参数与实际命令必须对齐

本地RedisCacheServiceImpl.java〔本地文件〕中,setIfPresent 实际委托给 setIfAbsent;这是可直接看到的调用事实。结合 NX/XX 语义可以推导:调用者如果依赖方法名,存在条件反转风险;但私有依赖的全部行为和线上调用影响没有在这里验证。该类的 multiHMSet 接收 timeout、unit,方法体只调用 putAll,未使用过期参数。审查这类封装时,要查“究竟发出了什么操作”,不能把参数存在当成 TTL 已设置的证据。

本地售后 RedisLuaScript.java〔本地文件〕的注释描述 zSet,脚本实际使用 SISMEMBER、SADD、SREM,属于 Set。这里应按实际命令理解“成员是否正在处理”,而不是杜撰按分数排序的逻辑。RedisSseMessageRouteRegister.java〔本地文件〕使用 Redisson RTopic 注册、移除监听器,没有 Stream 消费者组流程。这些都是适合建立“Java 抽象—Redis 操作—交付语义”对应关系的具体入口。

9. 练习与答案

练习一:一个任务有 10 万条错误明细,页面每秒只读 done、total、state。应该存一整个 JSON,还是一个 Hash?答案:小摘要适合 Hash 或独立小 JSON,明细另存支持分页的持久层。关键是拆分访问粒度;仅把巨型 JSON 改成巨型 Hash 并持续 HGETALL,仍没有解决传输问题。

练习二:SADD 输入三个值只返回 2,HSET 更新成功却返回 0,是否要重试?答案:不应仅凭数字小就判失败。前者表示两个新成员,后者表示没有新增字段。盲目重试计数型操作还可能产生额外副作用。

练习三:要求准确判断订单是否已退款,用 HLL 是否更省内存?答案:即使省内存也不满足问题。HLL 只估算基数,不能查询成员;永久幂等事实应由数据库唯一约束或相应持久化协议保存,短期 Set 只能作为辅助。

练习四:Stream 消息已经 ACK,为什么 XRANGE 仍可看到?答案:ACK 改的是消费组 PEL,不是日志本体。删除或裁剪有独立命令。若把 ACK 与数据删除混为一谈,就无法正确估计存储和重放能力。

练习五:给所有键统一添加 {tenant:1} 是否更安全?答案:它不是权限隔离机制,只影响槽分配。统一标签可能形成单槽容量和吞吐热点;仅对需要同槽事务的业务聚合采用小粒度标签,并另行实施访问控制。

原始文档 · database-course/15-Redis内部结构内存与性能.md

15 Redis 内部结构、内存与性能

为什么学过命令还需要理解内部表示

第 14 章解决的是“能不能表示这份数据”。本章解决“这种表示在数据长大后会付出什么代价”。前端开发中,一个列表在 30 行时很流畅,增长到十万行就需要分页或虚拟滚动;Redis 同样如此。命令返回正确只证明功能成立,不证明内存、延迟和故障恢复可接受。数据库工程尤其要防止把小样本的顺畅误认为大规模下的成本不变。

本章分开使用三个词:类型是客户端能执行哪些命令;编码是服务器怎样组织该类型的数据;容量是实例与操作系统最终承担的内存。Hash 是类型,listpack 或 hashtable 是某一版本可能采用的编码,RSS 是进程驻留内存。它们不是同一层概念,不能用一个 TYPE 结果解释全部性能。

事实边界:内部实现以 Redis 7.2 官方源码和配置为参考,本机验证版本见实验 README;编码阈值与字节数不是跨版本承诺。教学边界:容量数字与延迟预算是推演样本,所有键均归属 tenant_id=1。未执行边界:没有采集业务实例内存、流量、慢日志,也没有对业务服务压测。下文的“可能”是需要用证据验证的原因,不是对现有系统的事故诊断。

1. 从一个 GET 看到四种成本

一次请求从页面进入后端,后端先借连接,序列化键,通过网络发送,Redis 排队执行,再把字节返回,应用反序列化并组装响应。可以把耗时写成:

接口中缓存访问耗时
= 借连接等待 + 请求编码 + 网络往返
  + 服务端排队 + 命令执行 + 响应传输 + 对象解析

这个分解解释了为什么“Redis 慢日志没有慢命令”不等于接口正常。若服务器执行 GET 只用了很少时间,但返回 8 MB JSON,客户端仍可能在传输和反序列化阶段耗费大量时间;若连接池满了,请求甚至还没到服务器。复杂度中的 O(1) 主要描述定位工作量,不意味着返回任意体积的数据都等价。

传统 Redis 命令执行路径主要串行处理数据操作,同时还存在持久化、后台释放、I/O 等工作线程或进程。不要把它概括成“整个 Redis 只有一个线程”,也不要因为某版本支持 I/O 线程就认为一个耗时 Lua 可以被自动拆成多核并行任务。对于业务建模,最重要的是一个耗时操作可能延迟同一实例上的其他请求。官方延迟诊断文档按网络、命令、fork、交换和磁盘等来源拆解问题。

2. 类型不变,编码可以变化

进入独立实验控制台,先创建三个 String:

SET lab_encoding:tenant:1:number 42
SET lab_encoding:tenant:1:short hello
SET lab_encoding:tenant:1:long abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789
OBJECT ENCODING lab_encoding:tenant:1:number
OBJECT ENCODING lab_encoding:tenant:1:short
OBJECT ENCODING lab_encoding:tenant:1:long
TYPE lab_encoding:tenant:1:number

在默认 Redis 7.2 实现中,典型结果分别是 int、embstr、raw、string。int 直接表示可编码整数;embstr 将小字符串相关对象布局紧凑安排;raw 使用分开的字符串表示。Redis 7.2 源码中的短字符串边界为 44 字节,但它是实现细节,不是业务接口保证。中文 UTF-8 字符通常占多个字节,不能把“44 字节”写成“44 个汉字”。Redis 7.2 object.c是此处源码事实的依据。

即使值后来变短,也不要假定所有类型都会自动回到最紧凑编码。编码转换可能取决于创建路径、修改方式、数量和元素长度。工程上应该读取 OBJECT ENCODING 并用真实数据测量,而不是给 Java 对象字段贴一个“肯定占多少字节”的标签。

Hash 的小集合可用 listpack,把字段和值紧凑排列,减少大量指针和独立分配的开销。这样更省内存,却需要在紧凑容器内查找和搬移数据。超过数量或长度阈值后,可能转为哈希表。教学观察可以从两个字段开始,再加入长字段值:

HSET lab_encoding:tenant:1:hash a 1 b 2
OBJECT ENCODING lab_encoding:tenant:1:hash
HSET lab_encoding:tenant:1:hash description abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefgh
OBJECT ENCODING lab_encoding:tenant:1:hash

默认 7.2 配置下预期由 listpack 转为 hashtable,因为最后一个值超过 64 字节。这个变化不是错误,也不是数据变成了另一种类型。脚本会打印实际编码;只有版本与阈值一致时才对这个具体结果做比较。默认参考可查Redis 7.2 redis.conf:Hash 的条目阈值为 512、单项长度阈值为 64,ZSet 为 128 与 64;这些不是调优建议,修改阈值会改变空间与查找成本。

List 在该基线下使用 quicklist,将多个紧凑块串联;Set 可能使用 intset、listpack 或 hashtable,7.2 的小字符串 Set 不能一概讲成哈希表;ZSet 小集合可用 listpack,较大集合通常使用跳表结合字典来兼顾排序与按成员查找;Stream 使用基数树和紧凑节点组织消息。教材需要认识这些结构承担什么任务,却不需要把每个指针偏移背下来。官方内存优化说明列出了紧凑表示与阈值的版本区别。

3. 从数据字节到实例内存预算

假设一条订单摘要的序列化值是 600 字节,键是 45 字节,有一百万条。(600+45)×100万≈645 MB 只是键值载荷估算,没算字典、对象、过期信息、分配器碎片、复制积压、连接缓冲,也没算持久化时额外驻留的页面。把 maxmemory 设成物理内存大小,往往正是忽略了这些费用。

在实验中从具体对象开始测量:

STRLEN lab_encoding:tenant:1:short
MEMORY USAGE lab_encoding:tenant:1:short
MEMORY USAGE lab_encoding:tenant:1:hash
INFO memory
MEMORY STATS

STRLEN 返回 5;MEMORY USAGE 通常显著大于 5,但教材不写死一个数字,因为 libc/jemalloc、位数、版本和对象编码都会影响结果。集合型对象的 MEMORY USAGE 默认使用采样,精细评估可以选择 SAMPLES,但在大对象上全量测量也会增加开销。独立脚本输出的数字是本次进程观测,不是生产容量承诺。

阅读 INFO memory 时,先看 used_memory 与 used_memory_rss 的量级,再看 dataset、overhead 与分配器相关指标。used_memory 更接近 Redis 跟踪的分配量,RSS 是操作系统眼中的驻留内存;二者差额不全是业务数据。小实例刚启动时固定开销占比高,碎片比率可能看起来夸张。只凭一个比例大于某阈值就重启,容易把诊断变成随机操作。应该同时记录绝对字节差、近期删除、写入增长和系统内存压力。

一个更有用的教学预算是:先取真实键样本按类型测量分位数,再乘预计数量,加入复制与客户端缓冲预算,最后预留 fork 写时复制和操作系统空间。预算还要有增长速度:今天剩余 2 GB,如果每小时增加 500 MB,问题并不遥远。缓存设置 TTL 也不表示容量自动有界,因为新增速度可能持续超过过期速度。

4. 过期与淘汰是两种删除原因

TTL 表示键何时在逻辑上失效;内存淘汰是达到容量限制后,为后续操作腾出空间的策略。键还剩 200 秒 TTL,仍可能因为淘汰而消失;没有 TTL 的键,也可能在 allkeys 策略下被淘汰。读路径必须把缓存 miss 当成正常分支,而不是不可思议的异常。

Redis 会在访问时检查过期,也会主动处理过期键。到达过期时间不等于某个业务回调在准确毫秒触发,过期通知也不能替代可靠调度。若订单到期关闭必须留下持久记录,应从数据库或可靠任务机制驱动;缓存键的消失只能做提示信号。

选择淘汰策略前,先问实例中是否混放了不可随意丢失的状态。allkeys-lru/lfu 从所有键中选候选;volatile 系列只针对设置过期的键;noeviction 在超限时拒绝需要新增内存的相关写入,而不是把所有读写都一律关闭。LRU/LFU 是近似策略,不是维护一张绝对精确的访问排名表。volatile 策略没有可淘汰候选时,仍可能产生内存不足错误。官方淘汰文档给出了候选集合和行为区别。

实验用一个小数据量说明边界:先取当前 used_memory,再把 maxmemory 临时设置为略大于它,选择 noeviction,写入一个明显大于余量的 String。预期收到 OOM,而已有小键仍可读。随后恢复 maxmemory=0,并确认前一次失败没有制造一个完整新值。脚本仅在它自己启动的进程里进行这一步,不能把这段 CONFIG SET 操作复制到业务实例。

反例是把锁键和可丢弃的商品缓存混放在 allkeys-lru 实例中,然后把锁 TTL 视为最短持有期限。内存淘汰可以让锁提前消失,另一个请求便获得它。解决方向不是猜一个更大 TTL,而是明确状态的可靠性需求、隔离资源,并在数据库中保留最终正确性约束。

5. 大键与热点键要分别定位

大键描述体积或元素数,热点键描述访问频率。一个 20 MB JSON 可能每小时才读一次;一个 20 字节库存标记可能每秒被读十万次。两者都可能造成压力,但处理方式不同:大键需要拆分、分页、控制序列化大小;热点需要降低重复读取、分散只读流量、限制回源或改变聚合方式。

对大 Hash 使用 HGETALL,会同时增加服务端遍历、输出缓冲、网络传输和客户端对象分配。改为 HMGET 只取三个字段,通常比增加线程池更直接。List 深分页 LRANGE、全量 SMEMBERS、范围过宽的 GEOSEARCH、长 Lua 循环,也应按实际工作量审查,而不是看命令是否“常用”。

删除大键时,DEL 可能承担较多同步释放成本;UNLINK 把键先移除,将适合异步释放的工作交给后台,但释放仍消耗 CPU 和时间,后台队列也可能积压。不能把 UNLINK 理解为“数据没有清理成本”。如果一直创建再异步删除巨型对象,最终仍要为内存和后台工作买单。

使用 SCAN 分批发现键,比在繁忙路径上 KEYS 更合适,但有三个限制:COUNT 是工作量提示,不是精确页大小;一次可能返回空集合而游标非零;完整遍历可能返回重复元素,也不是某一时刻的一致快照。只有游标回到 0 才结束;后续动作应能承受重复处理。SCAN 官方契约对此有明确约束。

SCAN 0 MATCH lab_*:tenant:1* COUNT 20
# 将返回的游标原样代入下一次 SCAN;不要自行递增页码。
HSCAN lab_encoding:tenant:1:hash 0 COUNT 20

不能在业务请求里循环扫描整个实例,再把所有键累计成一个 Java Set,然后称之为“分页优化”。服务端阻塞时间可能变短,客户端总内存和接口总耗时却仍随键数增长。真正的治理通常需要后台批次、断点、限速和逐批处理。

6. Pipeline 优化往返,不提供事务隔离

假设每次网络往返为 1 ms,要读一千个小键,串行发送的纯等待就可能接近一秒。Pipeline 一次发送一批请求,减少逐条等待;它没有改变每条命令的基本工作量,也没有把这一批变成不可插入的事务。官方 Pipeline 文档解释了往返与服务端回复缓冲的关系。

教学上可以先拿 100 个小键做批次,不要直接把百万命令塞进一个 pipeline。批次越大,客户端与服务器需要保存的请求/响应越多,出错后待核对的操作也越多。网络在中途断开,不能确定全部未完成;重试 INCR 和重试 SET 固定快照的副作用不同。批处理接口必须暴露逐项错误,不能只返回一个“批量成功”。

MULTI/EXEC、Lua、pipeline 解决的是不同问题:前两者可以组织服务器上的不交错操作,Lua 还能依据读值分支;pipeline 主要减少网络等待。跨 Cluster 槽位的一批命令可能由客户端拆成多个连接,它更不可能自然获得一个全局原子边界。第 17 章会用失败结果说明为什么这些概念不能互换。

7. 用故障时序组织性能证据

考虑一个教学事件:10:00 所有商品摘要同时过期;10:00:01 数据库连接等待升高;10:00:03 Redis 的 GET 很快但 miss 飙升;10:00:05 接口 P99 变长。此时扩 Redis 的 CPU 不一定有效,因为主要成本已经转移到数据库回源。相反,如果 miss 稳定而慢日志出现长 Lua,热点锁竞争和命令执行队列才更值得检查。

排查顺序应围绕证据,而不是先贴“Redis 单线程瓶颈”的标签。先把接口耗时拆为连接等待、Redis、数据库和解析;再看单位时间的命令数、命中与未命中增量、过期与淘汰增量;然后关联大响应、慢命令、fork、磁盘和系统内存。INFO 的计数通常是累计值,应该取两个时刻的差,不能拿重启以来的总 miss 直接代表过去一分钟。

INFO stats
INFO commandstats
INFO memory
INFO persistence
SLOWLOG LEN
SLOWLOG GET 5
LATENCY LATEST

SLOWLOG 的执行耗时不包括完整的网络通信,空慢日志不能排除网络和客户端阻塞。SLOWLOG 官方说明是这个界限的依据。LATENCY 事件是否出现还取决于监控配置;没有事件不应被写成“零延迟”。诊断命令本身也要控制频率,日志中的参数可能包含业务数据,教材只展示合成 lab_ 键。

8. 项目源码中的具体阅读路线

RedisCacheServiceImpl.java〔本地文件〕同时提供 keys 和 scanTargetKeys。前者直接调用 template.keys;后者以 COUNT 100 迭代并把所有结果加入 HashSet。事实是服务端获取方式不同、客户端最终都可能拿到全集;推导是调用方若在高频接口调用,仍可能承担随结果规模增长的成本;未知是实际键数量和调用频率,本章不把潜在风险写成生产结论。

LocalCache.java〔本地文件〕在构建 Caffeine 时传入 maximumSize 并调用 expireAfterWrite。它的配置限制的是条目数量,而不是序列化字节数;当 value 大小差异很大时,同样一万条可能对应很不一样的堆内存。这不是 Redis 内部实现,但说明从远程缓存挪到本地缓存并不会消灭容量问题,只是把成本转移到了每个 JVM。

继续观察该类的 get:先 getIfPresent,再 supplier.get,再 put。源码中这段逻辑不是一个显式的“按键合并加载”调用。因此不能仅因用了 Caffeine 就宣称缓存未命中只会加载一次。并发效果需要看外层是否额外保护,或用受控并发实验确认;本章只基于当前方法体指出审查方向,不修改项目实现。

9. 练习与答案

练习一:MEMORY USAGE 显示一个 hello 占用远超 5 字节,是否说明泄漏?答案:不是。值载荷之外还有键、对象、字典和分配开销。泄漏判断需要看对象生命周期与持续增长,不是比较单个值长度。

练习二:TTL 还有 80 秒的键突然 miss,列出两个解释。答案:可能被其他请求删除或覆盖,也可能因淘汰消失;若发生重启/切换,还要检查恢复与复制窗口。TTL 不是保证存在的租约。

练习三:SCAN 返回空数组但游标是 72,能结束吗?答案:不能。继续用 72 扫描,直到返回 0。COUNT 与 MATCH 不保证每次都有结果,更不保证恰好 COUNT 个结果。

练习四:接口慢、慢日志空,下一步是否增加 Redis 线程?答案:先检查借连接、网络、返回字节数、应用解析和回源耗时。没有证据前调线程可能无关,还可能放大下游压力。

练习五:一万个独立小键改成一个 Hash,一定更好吗?答案:紧凑编码可能省内存,但会合并 TTL、槽位、迁移与淘汰粒度;若访问经常全量读取,还会制造大键。应按访问模式、数量增长和生命周期共同选择,不能只比较一个内存样本。

练习六:Pipeline 中发送了十次 INCR,连接超时后全部重试安全吗?答案:不安全,服务器可能已执行其中一些或全部。需要业务请求 ID 与去重规则,或者改为可安全重放的状态更新;pipeline 没有提供自动回滚。

原始文档 · database-course/16-缓存一致性与热点治理.md

16 缓存一致性与热点治理

先定义哪些事实允许暂时过时

前端状态管理也会遇到旧数据:一个标签页提交修改,另一个标签页仍显示旧值。ERP 后端把这个问题放大了:多个 JVM、本地缓存、共享 Redis、主从数据库、异步任务都可能持有不同时间的副本。所谓缓存一致性,不是选一个更新顺序就一劳永逸,而是明确权威来源、允许陈旧多久、哪些操作必须再次核验,以及失败后如何发现和修复。

本章用 tenant_id=1 的商品 1001 举例,数据库中有 name、price_cent、version 三列;教学缓存键为 lab_product:tenant:1:1001。商品列表允许短期展示旧名称,真正提交销售单时必须从数据库或权威价格规则验证金额;可售库存是否足够,也不能依赖页面刚读到的缓存值。这种区分直接决定一致性投入放在哪里。

项目事实仅指下文链接中的本地方法体;教学假设包括价格、版本、并发时序和流量;推导指在这些假设下能构造出的故障结果。没有连接任何业务服务,没有确认项目使用了本章的 outbox、版本下界或热点方案。独立实验用进程内字典模拟数据库的已提交状态,并用真实隔离 Redis 验证回填顺序;它不模拟 MySQL 隔离级别、网络分区或事务日志。

1. Cache-aside 的第一版及其边界

最常见读路径是“先读缓存,未命中再查数据库,再填缓存”。先写不涉及框架的伪代码,看清状态转换:

load(tenant_id=1, product_id=1001):
    value = redis.get("lab_product:tenant:1:1001")
    if value exists:
        return decode(value)
    row = database.select(tenant_id=1, product_id=1001)
    if row exists:
        redis.set(key, encode(row), ttl=60s)
    return row

它减少重复读库,但既没有合并同时到来的 miss,也没有证明回填的 row 仍是最新数据。还要决定 Redis 出错时怎样处理:对于可重建展示缓存,可以在有限回源预算内降级;对于保存唯一任务结果的状态,不能直接把错误解释成“不存在”。nil 和网络异常必须分开,前者是合法缓存状态,后者是结果未知或服务不可用。

一个可讨论的写路径是:数据库事务提交成功后,删除缓存;删除失败则记录并重试。它避免在数据库尚未提交时发布新缓存值,但不等于完全消除陈旧读。读路径对缓存中的数据仍没有事务快照保证,所以必须继续画出交错时序。

2. 三个常见更新顺序的反例

先删缓存再改数据库,有一个直观窗口:缓存空了,读请求查到的仍是旧库值。把时间列出来:

时刻 写请求 W 读请求 R 数据库/缓存
t0 准备把价格 100 改成 120 DB=100,cache=100
t1 DEL 缓存 DB=100,cache=空
t2 尚未提交 miss 后读库得到 100 DB=100
t3 提交 120 DB=120
t4 回填 100 DB=120,cache=100

TTL 最终会让旧副本消失,但错误已经持续到过期或下一次修复。反例不依赖罕见的硬件故障,只需要两个普通请求在正确的时间交错。

先更新数据库再更新缓存,也会遇到“旧写覆盖新写”:W1 提交 version=2 后暂停;W2 提交 version=3 并填缓存 3;W1 恢复后填缓存 2。数据库没有回退,缓存却回退了。单条 SET 的原子性只能保证值不被写一半,不能保证写入顺序符合数据库版本顺序。

先提交数据库再删缓存通常更易控制,因为失效操作可幂等重试,但仍有旧加载回填问题:R 在提交前已经取出 version=1;W 提交 version=2 并 DEL;R 最后才把 version=1 写进去。此时 DEL 的确成功了,却删不到未来才出现的旧值。理解这个反例,才不会把“缓存删除成功率 100%”等同于一致性证明。

R: 读库得到 v1 --------暂停-------------------- SET cache=v1
W:                 提交 v2 ---- DEL cache
最终:DB=v2,cache=v1

实验脚本按这个顺序逐步调用,不依赖线程碰巧调度到这个窗口,最后断言数据库是 v2、缓存是 v1。这是一个确定性的反例,不是对线上发生频率的测量。

3. 为什么删除要放到提交以后

假设 Java 方法有 @Transactional,在返回前调用 DEL。方法内部业务 SQL 执行成功,不代表事务已经提交;代理可能在方法返回之后才执行真正提交。另一个读请求在 DEL 与提交之间回源,就可能再读旧值。因此审查时要找实际事务边界,而不是只看方法里“SQL 写在 DEL 前面”。

提交后回调可以把删除时间挪到正确位置,但它没有跨越两个系统的原子提交能力:数据库已经提交,进程尚未执行回调就崩溃,Redis 仍保留旧值。即使回调执行,网络也可能使删除结果未知。正确的下一步是为失效动作建立可观测、可重试的记录,而不是给回调外面再套一次 try/catch 就宣称可靠。

以下是教学数据库表,只解释协议,本专题自动实验不会连接 MySQL。表名独立,租户统一为 1,语法面向 MySQL 8.0 的普通事务表能力;更完整的跨系统协议放在后续分布式专题。

CREATE TABLE lab_cache_invalidation (
  event_id BIGINT PRIMARY KEY,
  tenant_id BIGINT NOT NULL,
  aggregate_id BIGINT NOT NULL,
  version BIGINT NOT NULL,
  state VARCHAR(16) NOT NULL,
  UNIQUE KEY uk_lab_version (tenant_id, aggregate_id, version)
) ENGINE=InnoDB;

-- 与商品更新放在同一个数据库事务中;这里不引用业务表。
INSERT INTO lab_cache_invalidation
  (event_id, tenant_id, aggregate_id, version, state)
VALUES (90001, 1, 1001, 2, 'PENDING');

后台读取 PENDING 事件,删除对应缓存,成功后标记完成。删除后、标记前崩溃会再次删除,但 DEL 本身可重复执行。真正实现还要考虑批量领取、超时重试、错误告警、记录保留与事件延迟;本章不把这个片段包装成完整生产组件。数据库原子事务只覆盖同一事务内的表更新,其基础边界可核对MySQL 事务语句官方说明。

这种补偿最终可以删除被旧请求回填的值,但它并不保证任何瞬间都读到最新。失效延迟、重试间隔、缓存 TTL 共同决定错误暴露窗口,必须测量“最老待处理事件年龄”,而不是只看任务是否还活着。

4. 版本比较能做什么,不能做什么

给缓存对象增加 version,可以拒绝 v2 覆盖已经存在的 v3。比较与写入必须在服务器原子完成,否则两个回填请求又会在 GET 与 SET 之间交错。Lua 可把“读版本、判断、写值和 TTL”组合为短操作。

但只比较现存缓存版本有漏洞:W 提交 v3 并删空缓存;旧 R 带着 v2 来,发现缓存空了,于是判断“可以写入”。删除同时抹去了拒绝旧版本所需的证据。解决这类问题需要一个独立的版本下界或失效标记,且它自身也有生命周期和故障边界。

教学脚本使用两个同槽键:lab_cache:{tenant:1:product:1001} 存值,lab_floor:{tenant:1:product:1001} 存已观察到的最小可接受版本。提交事件在一个 Lua 内提高 floor 并删除低于该版本的缓存;已达到该版本或更高版本的缓存保留。回填 Lua 比较候选版本、floor 与现有版本,只有不回退才允许写入。具体实现见cache_publish.lua〔本地文件〕与invalidate.lua〔本地文件〕。

初始:DB=v1,floor=1,cache=v1
R 暂存 v1
W 提交 v2,失效脚本将 floor 提升到 2 并 DEL
R 发布 v1 → 返回 0,被拒绝
新读者发布 v2 → 返回 1
迟到的 v1 失效事件 → 不降低 floor,也不删除 v2

此实验假定版本是小范围正整数、floor 在演示期间不丢失。现实里 floor 被淘汰、重启后丢失、主从切换回退、提交事件尚未送达,都可能重新打开窗口。Java Long 的全范围也不能直接用 Lua 双精度数字比较。若要推广方案,需要定义版本格式、状态持久性和最大加载时长;教学脚本显式限制版本范围,不声称它是完整一致性组件。

“延迟双删”也是补偿思路:先按约定更新,过一段时间再删一次,试图覆盖较慢旧读的回填。它依赖对加载时间的假设;若旧请求比第二次删除更慢,反例仍成立。固定 sleep 不是数学保证,延迟任务本身还可能丢失。可把它作为降低风险的措施,但必须说明仍依赖 TTL、补偿和关键动作校验。

5. 两级缓存把一致性问题复制到每个实例

本地缓存 L1 可以减轻 Redis 热点,但每个 JVM 都有自己的副本。更新 Redis 不会自动修改其他进程的对象。常见策略是 L1 设置较短 TTL,同时收到失效通知后删除;即使通知漏失,TTL 最终收敛。若用 Pub/Sub 发通知,订阅断开期间没有离线补读,所以它只能加快失效,不能独自证明可靠到达。Redis Pub/Sub 官方交付语义是此处边界的依据。

还有一个更隐蔽的交错:实例 A 开始加载旧值 → 收到失效通知并清空 L1 → 加载结束,把旧值重新放回 L1。处理时可给每个键维护 generation:开始加载记录 g0;失效把 generation 加一;完成时只有 generation 仍为 g0 才发布。比较与发布也要在本地同一受保护区域完成。否则检查通过以后、put 以前又收到失效,仍会复现问题。

generation 只保护本进程已经观察到的失效,不知道尚未送达的消息,也不修复来自滞后数据库副本的旧数据。因此设计两级缓存时要同时决定数据加载来源、L1/L2 TTL、通知可靠性和强一致操作绕行路径,不能把“再加一层本地缓存”当成没有副作用的性能优化。

6. 穿透、击穿、雪崩要对应不同流量形状

穿透通常是大量不存在的查询:每次都 miss,每次查库也没有。先做合法性与租户权限校验,再考虑短期负缓存。负缓存必须有明确占位结构,例如 {"kind":"ABSENT","version":0},不能让空字符串、空列表、网络错误和不存在混为一种状态。新对象创建后要失效负缓存,否则“刚创建却查询不到”会持续到它过期。

Bloom Filter 可以减少明显不存在的请求,但有误判,不能把“可能存在”当成确实存在。构建延迟、过滤器重建和新增对象同步也需要考虑;本章不假设 Redis 基线已经装了任何 Bloom 模块。教学重点是先把负缓存和参数校验做对,而不是遇到穿透就直接引入新组件。

击穿是单个热点键过期时,许多请求同时回源。可在一个 JVM 内合并同键加载,让一位加载者工作,其他请求等待其结果;多 JVM 仍会各自有一位加载者。若数据库只能承受更少并发,可增加跨实例的短重建许可,但等待者必须有超时和降级边界,不能无限循环抢锁。许可失败不等于对象不存在,更不等于允许所有等待者立即放弃限制直接查库。

雪崩则是大量键同时过期,或者缓存整体不可用使大量流量回源。TTL 加随机抖动能分散计划到期,不能解决整个 Redis 断开的情况。此时需要回源并发上限、数据库保护、按业务优先级限流和有限的旧值降级。把缓存异常统一 catch 后无条件查库,功能上“还能返回”,容量上却可能把小故障扩成全站故障。

教学容量推导:某接口每秒 5000 次,平时命中 99%,数据库约承担 50 次;缓存不可用后若全部回源,负载升至 5000 次,是 100 倍。这个推导不是项目真实 QPS,但足以说明为什么回源预算要独立于 Redis 健康状态。即使短时间把超时加长,排队仍会继续占用连接与线程,并不会产生额外处理能力。

7. 热点治理要明确返回的是新值还是旧值

热点只读配置可以使用 L1、本地请求合并、提前刷新和短 TTL。逻辑过期模式则把业务截止时间放进 value:Redis 中保留旧值,过期后允许一位刷新者重建,其他请求在可接受窗口内继续读旧值。这个方案降低 miss 风暴,但要把 stale_until 写成产品可接受的上限;刷新持续失败超过上限,应拒绝或进入更明确的降级,而不是永远返回昨天的数据。

{"tenant_id":1,"version":2,"price_cent":12000,
 "fresh_until_ms":2000,"stale_until_ms":5000}

这里的数字只是虚拟时钟。t=1500 可正常返回;t=2500 可返回旧值并触发受限刷新;t=6000 不再允许以“短期陈旧”为由返回。真实环境还要处理时钟来源和刷新任务失败。对价格确认、权限撤销、可售库存等关键动作,直接在权威事务中验证通常比无限增加缓存协议更清晰。

热点写不能简单复制键来扩容,因为多个副本的计数、限额或扣减需要再合并。把总计数拆成多个桶后,读总数需要聚合,阈值判断不再是单键原子操作。数据库相关专题在此只给出权衡:读热点可以用副本减少压力;参与约束的写热点必须先保留正确性边界,再讨论扩展。

8. 把监控指标放到正确的因果链上

命中率高不代表正确:返回一份永远不变的旧配置可能有极高命中率。应同时观察结果版本、缓存年龄、负缓存命中、回源并发、加载时间、失效事件延迟、重试次数、等待者超时和 stale 返回比例。高风险操作还要统计数据库条件检查失败与幂等冲突,才能看出展示副本与权威状态之间的差异。

单次缓存失效失败不应只留一句日志后消失;至少有可聚合计数、重试状态和最老失败年龄。反过来,也不要为每个 miss 打完整请求与 value 日志,大流量时既制造额外开销,也可能泄露业务信息。教材实验仅记录 lab_ 键、版本与断言结果。

9. 逐段阅读项目,而不是替项目补全不存在的保证

AbstractCacheImpl.java〔本地文件〕的 expireKeys 和 expireKey 在 catch(Throwable ignored) 中忽略删除异常。事实:这个方法体没有重试或告警。推导:若调用者也没有补偿,删除失败可能让旧数据留到其他失效条件出现。未知:实际调用者、TTL 与外部任务是否已提供兜底;不能仅据基类判定整个项目没有修复机制。

LocalCache.java〔本地文件〕使用 expireAfterWrite,旁边中文注释却描述成“上次访问”。阅读时应以 API 调用为依据:写入后到期与访问后续期会产生不同的热点存活时间。该类 get 是先查询、再执行 supplier、再 put,可沿这三个点画出本章的旧加载回填窗口。它提供 invalidate,不意味着每个实例都收到同一个失效事件。

RedisSseMessageRouteRegister.java〔本地文件〕把 RTopic 消息交给回调,并在需要时使用 RateLimiter。它适合学习“订阅通知和本地处理”的连接位置;仅凭注册监听器不能推导可靠重放,也不能推导它承担了本章缓存失效协议。避免把某个相似工具类当成已经实现完整架构的证据。

10. 练习与答案

练习一:数据库提交后删除缓存成功,还能读到旧值吗?答案:能。提交前已取出旧值的读请求可以在删除之后回填。画出 R 读旧值、W 提交、W 删除、R 回填四步即可,不需要假设 DEL 失败。

练习二:把版本放进缓存并拒绝小版本,为什么还不完整?答案:缓存被删空时,旧请求没有可比较的版本。需要独立版本下界或其他受保护发布协议,并说明下界丢失、过期和事件延迟时的行为。

练习三:Redis 超时后统一查库,为什么可能比直接报错更危险?答案:缓存承担的高频流量全部落到数据库,引发连接耗尽与排队扩散。应给回源设置并发预算,并按业务风险选择拒绝、旧值或降级响应。

练习四:新建商品在一分钟内查不到,日志显示命中负缓存,怎么解释?答案:创建前的“不存在”被保存了。创建提交后需要失效对应负缓存,TTL 也应短于正常值;查询不存在与 Redis 请求失败不能使用同一个占位结果。

练习五:Pub/Sub 通知后所有实例都能立即看到新配置吗?答案:不能保证。离线订阅者会漏消息,在线实例还可能被旧加载重新填充。短 TTL、可靠失效记录、generation 与关键操作权威校验分别覆盖不同窗口。

练习六:缓存命中率 99.9%,能否据此宣称一致性良好?答案:不能。命中只说明找到了键,不说明版本正确。至少结合缓存年龄、版本落差、失效延迟以及用户实际允许的陈旧窗口评估。

原始文档 · database-course/17-Redis事务Lua锁与持久化复制.md

17 Redis事务、Lua、锁与持久化复制

14章解决命令,15章解决成本,16章解决缓存协议。本章解决“多个操作看起来一起执行以后,面对失败还剩下什么”。实验以Redis7.x基础命令为基线;新版本扩展命令需另查。本课程的Redis实验室只启动临时Unix socket实例,不连接项目服务。

1. Pipeline节约往返,不提供隔离

客户端连续发送多条命令后集中读取响应,减少网络RTT与协议开销。它不等于数据库事务,其他客户端的命令可在执行边界介入;连接中断还可能只知道一部分响应。重复发送INCR可能重复计数,不能把pipeline当成一组可安全整体重试的请求。

批次过大也会占用客户端/服务器缓冲和事件循环时间。应同时考虑总字节、响应大小和命令成本,而不只是条数。一次GET百万字节与一次GET十字节不该使用相同容量估算。

2. MULTI/EXEC与WATCH

MULTI开始排队,EXEC集中执行排队命令;排队阶段语法错误与执行阶段类型错误不同。EXEC期间某条命令因WRONGTYPE失败,不自动撤销前面已执行写入,其他可执行命令仍可能继续。DISCARD丢弃尚未执行队列,不是提交后撤销。

SET course:tx:count 1
MULTI
INCR course:tx:count
LPUSH course:tx:count value
SET course:tx:done yes
EXEC
GET course:tx:count
GET course:tx:done

在隔离实例预期count=2、done=yes,中间LPUSH报类型错。这解释为什么Redis事务不能按关系库“任一步失败全部回滚”来编排。

WATCH在EXEC前检查监视键是否被修改,失败则放弃事务,由客户端重新读取计算。它是乐观竞争控制,重试必须有次数/期限限制。过期也可能导致WATCH失效,细节依Redis版本。不要在WATCH期间执行慢RPC,让竞争窗口无限扩大。官方事务语义

3. Lua原子执行的真实边界

脚本执行期间不与其他普通命令交错,适合比较后删除、计数后设置过期等短逻辑。但脚本已写入后再报错,不会自动撤销之前写入。应先验证参数、键类型和所有可预见错误,再执行必要写入;脚本也不能访问MySQL形成跨存储原子事务。

长循环、大集合遍历会阻塞其他请求,不能把业务报表放进Lua。脚本访问的键通过KEYS显式传递;Redis Cluster多键操作通常要求同槽,使用hash tag时也要防一个租户全部热点挤到一个槽。脚本缓存丢失可能导致EVALSHA返回NOSCRIPT,客户端需有正确回退加载逻辑。

4. 锁所有权、租约与旧持有者

获取锁常用SET key token NX PX ttl,token标识本次持有者。不能SETNX之后再独立EXPIRE,因为两步之间崩溃会遗留无过期锁。释放用Lua原子比较token后DEL,避免A读到自己锁、锁过期后B获得、A再DEL误删B。

if redis.call('GET', KEYS[1]) == ARGV[1] then
    return redis.call('DEL', KEYS[1])
end
return 0

这只保护“不能删别人锁”,不保证旧A停止业务。A暂停超过租期,B获取并写库,A恢复仍可能写库。资源端必须用业务版本、条件更新、幂等或fencing拒绝过期执行者。watchdog续约减少某些过期情形,但网络分区和长暂停仍需要明确假设。

项目RedisLock第38行〔本地文件〕接收timeUnit但实际使用SECONDS;第55行〔本地文件〕脚本把当前GET存本地变量再与当前GET比较,没有使用ARGV持有者token。由此可推导旧持有者调用释放时可能删新锁,实际可达性取决于调用时序。教程不修改项目,只用隔离脚本演示正确所有权检查。

5. RDB与AOF保护不同恢复路径

RDB保存某个时点的数据快照,恢复通常直接加载快照,之后的更新可能不在快照中。后台保存涉及fork与写时复制,写密集时要预算额外内存。磁盘有足够空间不代表内存峰值足够。

AOF记录写操作并按配置刷新。appendfsync everysec通常以约一秒刷新周期降低同步成本,但不保证任意故障下严格最多丢一秒;操作系统与存储兑现也重要。always增加刷盘开销,no更依赖系统策略。重写压缩历史以表达当前状态,不等于停止所有写入;Redis7多文件AOF布局应按版本工具处理。

RDB/AOF是持久化机制,不是异地备份策略。错误删除会进入复制和日志;备份需要独立保留点、权限与恢复验证。同时启用两者时启动加载策略按版本文档确认,不能手动删某个文件后猜Redis会自动选最完整历史。官方持久化

6. 主从复制、Sentinel与Cluster

复制让副本追随主节点,通常异步传播。首次或无法增量追赶时全量同步代价高,复制backlog大小影响断线后的部分重同步机会。副本数量增加读能力,也增加主节点复制与网络开销;副本读可能陈旧。

Sentinel监控并协调主从故障转移,不负责把数据按键分片;Cluster将键映射到16384槽并配合分片副本与路由。客户端需要处理MOVED/ASK等重定向和拓扑变化。仅把普通单节点地址换成一个Cluster节点不一定得到正确客户端行为。

异步复制允许原主确认的写未到新主,故障切换后可能丢失;WAIT可请求副本确认以降低某些风险,但不把Redis变成所有故障下线性一致的事务数据库。需要持久幂等事实时,必须明确选择的保证而非只看“有两个副本”。复制文档

7. Streams也需要处理确认与重领

消费者组将消息分配给消费者,未确认记录进入pending。XACK表示客户端确认处理,不自动与MySQL业务提交原子。先ACK后写库可能丢处理;先提交后ACK可能重放,因而业务写需要幂等。领取旧pending前要考虑旧消费者仍活跃的竞争。

裁剪stream会影响历史与pending可读内容,不能只用MAXLEN节约内存而不检查最老待处理消息。保留、重试、死信和积压监控要整体设计。Pub/Sub没有同样的持久待确认协议,发布成功不意味着每个终端都收到。

8. 实验与答案

实验室验证错误token不能释放、正确token可释放、旧token不能释放新锁,以及MULTI和Lua出错不回滚先前写入。它不验证多节点故障切换或watchdog,不能从单实例断言分布式安全。

练习:A锁过期后B写版本11,A带版本10写库,如何拒绝?数据库WHERE version=10应影响零行,调用者停止并重读;如果业务允许新版本之外的特定操作,要重新定义条件,而不是忽略零行继续成功。

练习:有AOF为何还需备份?AOF可能记录误删,磁盘故障也可能同时损坏数据与日志;独立备份与恢复演练解决另一个故障域。

练习:限流Lua原子是否保证限流服务可用?不保证。Redis不可用时仍须决定放行、拒绝或本地降级,固定窗口还有边界突刺,算法和故障策略应分别测试。

原始文档 · database-course/18-MongoDB文档建模与CRUD.md

18 MongoDB 文档建模与 CRUD:从页面对象走到持久化约束

前端同学第一次看到 MongoDB,容易觉得终于有数据库可以直接保存页面上的对象了。订单详情本来就包含地址、商品数组、操作记录,似乎把 JSON 原样传给数据库就完成了后端。但页面对象描述的是某一时刻的展示需要,数据库文档还要承担类型、并发、历史、查询和生命周期的责任。用户点击保存时,页面可能已经过期;商品名称修改后,去年的订单不能跟着改;数组不断追加后,一条文档可能成为每次读取都要搬运的负担。本章从这些具体问题出发,建立能够落地的文档模型。

阅读边界。“源码事实”指本地指定 Java 文件能直接证明的行为;“推导”指根据代码和数据库语义提出的条件性结论;“教学设计”指 lab_ 集合及示例,不代表项目已经采用;“未执行”表示作者没有连接 MongoDB 验证。本文核对了官方 MongoDB 8.0 文档,实验面向 MongoDB 8.0 与 mongosh 2.x;项目实际 MongoDB 服务端版本、索引、数据分布、部署拓扑均未查询。例子统一使用 tenant_id=1,这是一项教学隔离约定,不应反推真实 Teambition 集合存在该字段。

18.1 先把项目中真正使用的东西读清楚

TbTaskRepository.java〔本地文件〕 继承 MongoRepository<TbTask, String>,声明了 findFirstByProjectIdAndUniqueId。这里的 String 是 Java 层 ID 类型,并不等于底层 BSON 一定以字符串存储。TbTask.java〔本地文件〕 将 projectId 映射到 _projectId,并明确使用 FieldType.OBJECT_ID;tagIds、ancestorIds 也有 ObjectId 类型映射。判断一次查询为什么为空,应同时检查 Java 属性名、映射后的数据库字段名、传入值与 BSON 类型。

TbUserRepository.java〔本地文件〕 中的 findAllByNameIn、findAllByNameContaining 表明项目使用派生查询,而不是只调用通用 findById。TbServiceImpl.java〔本地文件〕 的 buildBaseCriteriaList、search、getSubTasks 则使用 Criteria、Query、MongoTemplate 组合条件,部分查询显式构造 ObjectId。同一模块采用 Repository 与 Template 两种入口是源码事实;“所有查询都经过一个自动租户过滤器”并非这些文件能够证明的事实。

再看 MongoConfig.java〔本地文件〕:它创建客户端,并使用 MappingMongoConverter,通过 DefaultMongoTypeMapper(null) 去掉 _class 字段。这个设置影响类型元信息的写入,不会自动开启 schema 校验、事务或多租户隔离。配置来自环境和解密流程,教材不展示连接值,也不要求读者复制业务配置。模块 pom.xml〔本地文件〕 声明 MongoDB starter,根 pom.xml〔本地文件〕 导入 Spring Boot 2.7.3 BOM;这里只确认依赖声明,没有运行完整依赖解析,因此不把某个驱动补丁版本或服务端版本写成项目事实。

18.2 BSON:长得像 JSON,不代表类型可以混用

初始化和执行方式见 实验 README。运行 init.js〔本地文件〕 后,实验库 lab_erp_mongodb 包含五个订单。下面取其中一条说明结构,代码是 mongosh 语法,不是浏览器中的普通 JSON:

db.lab_orders.findOne({ tenant_id: 1, order_no: "O1001" })
// 核心字段:
// _id: ObjectId("000000000000000000001001")
// tenant_id: Int32(1)
// created_at: ISODate("2026-01-01T00:00:00Z")
// items: [{sku:"A", qty:2, unit_price:Decimal128("19.90")},
//         {sku:"B", qty:5, unit_price:Decimal128("6.00")}]
// total: Decimal128("69.80"), note: null, version: 0

BSON 有 ObjectId、Date、32 位整数、64 位整数、Decimal128 等类型。ObjectId 是 12 字节标识,不是 24 字节文本;它常以 24 位十六进制字符串展示。Date 表示相对于 Unix epoch 的毫秒时间,写入后不会替你保留原始业务时区名称。财务金额用 Decimal128 或约定单位的整数表达更合适,不能把 JavaScript 0.1 + 0.2 的二进制浮点误差当成数据库自动修正的问题。大整数还要避开 JavaScript Number 的安全整数上限,不能先在前端丢失精度,再期待保存成 Long 后恢复。参见 BSON 类型 与 金额建模。

先执行两个看起来相同的查询:

db.lab_orders.findOne({tenant_id:1, _id:"000000000000000000001001"})
// 预期:null
db.lab_orders.findOne({tenant_id:1, _id:ObjectId("000000000000000000001001")})
// 预期:O1001

这里不是索引坏了,而是类型不相等。HTTP 接口传进来的字符串需要在边界校验并转换;非法十六进制字符串应成为参数错误,而不是等到内部构造 ObjectId 时返回不明原因的服务器异常。另一方面,数值 BSON 类型在很多比较场景中可以相互比较,不能把“ObjectId 不等于字符串”机械扩展为“所有不同 BSON 类型必然不匹配”。本实验对租户字段使用校验器限制为整数,是为了约束写入契约,而不是依赖一次查询碰巧能匹配。

日期筛选也要先确定“业务日期”。例如北京时间 2026 年 1 月 2 日的订单,应转成对应 UTC 边界再查询,使用左闭右开区间可以避免毫秒尾值问题:

db.lab_orders.find({tenant_id:1, created_at:{
  $gte: ISODate("2026-01-01T16:00:00Z"),
  $lt: ISODate("2026-01-02T16:00:00Z")
}}, {_id:0, order_no:1})
// 预期:O1002

字符串日期的字典序、不同偏移格式和 Date 的时间比较不是同一件事。进入 Java 层时,同样需要明确 Date 与接口格式之间的转换,不应让服务器默认时区偷偷决定报表归属日。

18.3 嵌入还是引用,要从访问与修改边界开始推导

本实验把订单明细嵌入 items,把商品主数据独立保存到 lab_products。理由不是“MongoDB 喜欢嵌套”,而是订单页通常一次读取订单和明细,明细数量有业务上限,且成交价格属于订单历史。商品 A 当前价为 21.00,订单中的成交单价仍为 19.90。读取订单时不能通过商品现价重新算订单金额,否则仅仅修改商品价格就会改写过去的销售额。

商品名称是否冗余保存,要看它表达的时间。item_name_snapshot 表示下单时名称,可以允许与商品主档不同;current_product_name 表示当前展示名,需要引用查询或明确刷新机制。两个字段都叫 name,却没有说明时间语义,才是后续对账争议的根源。嵌入模型的价值是把需要一起读取、一起更新的一组数据放入单文档原子边界;引用模型的价值是让独立更新、无限增长或被多处共享的数据有独立生命周期。官方建模原则也从访问模式出发,而不是要求把关系数据库每张表一比一复制成集合。文档建模

反例是把某个订单的所有操作日志、每次重试响应、所有聊天消息都追加到 history 数组。日志会持续增长,订单摘要却被高频读取,二者的生命周期和访问量都不一致。文档存在 16 MiB 大小限制,接近上限之前,大数组的读取、更新和索引维护成本就已经值得关注。较合理的教学设计是订单保留必要摘要,完整事件存到独立 lab_activities,通过订单 ID 和时间检索。独立集合失去单文档原子边界后,是否需要事务,则要看“订单变更与审计事件必须同时存在”是否是强约束;第 20 章继续讨论。BSON 大小限制

18.4 灵活 schema 不等于没有写入契约

实验初始化给 lab_orders 加了 $jsonSchema 校验,要求租户是整数、明细数量为正整数、金额是 Decimal128,状态只能取指定枚举,并将明细数组上限设为 100。这个上限是教学业务规则,不是数据库固有限制。校验器拒绝错误文档,能阻止脚本、后台任务等入口绕过接口校验后污染数据,但它不会自动检查商品 SKU 是否存在,也不会自动保证 total 等于明细求和。关联完整性和跨字段业务公式仍需明确负责者。

下面尝试写入字符串租户号,预期收到校验失败,错误代码为 121:

db.lab_orders.insertOne({
  tenant_id:"1", order_no:"INVALID", status:"open",
  created_at:new Date(), version:NumberInt(0), items:[]
})

这是保证失败的反例,自动实验会捕获并断言该错误。上线既有集合的校验规则时,则必须先统计旧数据类型、决定迁移与兼容顺序,再逐步收紧;直接把最严格规则套到历史数据上,可能让原本只改一个无关字段的请求也失败。可参考 schema validation,但本教材没有执行项目集合迁移。

“字段缺失”与“字段存在但值为 null”也要约定清楚。实验中 O1001 的 note 为 null,O1002、O1004、O1005 没有 note,O1003 有文本:

db.lab_orders.find({tenant_id:1, note:null}, {_id:0, order_no:1})
// 预期:O1001、O1002、O1004、O1005(无排序时顺序不保证)
db.lab_orders.find({tenant_id:1, note:{$type:"null"}}, {_id:0, order_no:1})
// 预期:只有 O1001
db.lab_orders.find({tenant_id:1, note:{$exists:false}}, {_id:0, order_no:1})
// 预期:O1002、O1004、O1005

如果业务把 null 解释为“用户明确清空”,缺失解释为“旧版本从未采集”,第一种查询就不能用来统计用户清空次数。源码 buildSearchCondition 使用 ancestorIds isNull 或空数组筛根任务,阅读时同样应意识到缺失字段也可能进入候选结果,不能单凭 Java 字段声明推断历史数据完整性。查询 null 或缺失字段

18.5 数组查询:同一文档满足,与同一元素满足不同

现在需求是“查出 SKU A 至少买了五件的订单”。O1001 买了 A 两件、B 五件;O1002 买了 A 五件。错误写法如下:

db.lab_orders.find({tenant_id:1,
  "items.sku":"A", "items.qty":{$gte:5}
}, {_id:0, order_no:1})
// 预期:O1001、O1002

O1001 被选中,是因为文档里存在一个 sku 为 A 的元素,同时存在一个 qty 大于等于五的元素,两个元素可以不是同一个。把两个条件放入同一 $elemMatch,才把约束绑定到同一个数组元素:

db.lab_orders.find({tenant_id:1,
  items:{$elemMatch:{sku:"A", qty:{$gte:5}}}
}, {_id:0, order_no:1})
// 预期:只有 O1002

这不是可有可无的性能优化,而是先修正语义;第 19 章还会看到它对 multikey 索引边界的影响。另一个常见误解是认为过滤用 $elemMatch 后返回的 items 就只剩匹配项。查询过滤决定文档能否进入结果,普通投影仍可能返回完整数组;若需要筛出全部匹配明细,应在聚合中用 $filter,或明确选择适合的数组投影方式。官方定义强调至少一个数组元素同时满足指定条件。$elemMatch

18.6 CRUD 的重点是条件,而不只是方法名

先在临时集合建立一个请求记录。这一节的操作只影响 lab_crud,不会改变后续聚合用的五个订单:

db.lab_crud.deleteMany({tenant_id:1}) // 仅重置本节临时数据
db.lab_crud.insertOne({_id:"draft", tenant_id:1,
  request_id:"draft-1", title:"待补资料", version:0,
  shipping:{city:"杭州", address:"教学地址"}})
db.lab_crud.updateOne({tenant_id:1, _id:"draft"},
  {$set:{"shipping.city":"上海"}})
db.lab_crud.findOne({tenant_id:1, _id:"draft"})
// 预期:city 改为上海,address 仍为教学地址

$set: {shipping:{city:"上海"}} 的含义是替换整个 shipping 子文档,旧 address 会消失;$set: {"shipping.city":"上海"} 才是更新子字段。更危险的是把不完整的接口 DTO 当成整份文档做 replaceOne,使页面没加载的字段被删除。save 也不应被当作任意局部补丁接口:阅读实际框架版本和映射行为,确认是新增、按 ID 保存还是字段级更新,再选择 API。

删除需要同样的边界意识。教学上的物理删除可以写成 deleteOne({tenant_id:1,_id:"draft"});生产业务如果采用软删除,还要决定唯一键是否允许重新使用、列表是否统一排除、关联记录如何展示。不要以为实体有一个 isDeleted 字段,MongoDB 就会像某些 ORM 的全局逻辑删除插件一样自动过滤所有查询。源码显式加入 isDeleted=false,恰好说明阅读具体入口的重要性。

18.7 并发保存、upsert 与幂等不是一回事

两个操作员打开同一个页面,都读到 version=0。A 先提交,B 随后用旧内容提交;如果过滤条件只有 _id,第二次覆盖可能静默发生。为避免丢失更新,可以把用户读到的版本放进更新条件,并让版本递增与内容更新发生在同一原子写中:

db.lab_crud.updateOne({tenant_id:1,_id:"draft",version:0},
  {$set:{title:"A保存"},$inc:{version:1}})
// 第一次预期 matchedCount=1
db.lab_crud.updateOne({tenant_id:1,_id:"draft",version:0},
  {$set:{title:"B旧页面保存"},$inc:{version:1}})
// 第二次预期 matchedCount=0

故障时序不是数据库抛异常,而是业务忽略了第二次返回的零匹配:浏览器看到“保存成功”,数据库却没有改动。后端应区分“记录不存在”“无权访问”“版本冲突”,同时避免向无权限用户泄露记录存在性。modifiedCount=0 也不总是冲突:更新值与原值一样时,可能匹配成功但没有实际变化;判断乐观并发条件是否成立,首先看匹配结果。单文档原子更新语义见 Atomicity and Transactions。

如果改成 upsert,必须另外考虑唯一业务键。没有唯一索引时,两个并发请求都认为不存在,可能产生两个业务上相同的文档。实验为 (tenant_id,request_id) 建了唯一索引,保护租户内请求标识;$setOnInsert 可以仅在插入时设置初始字段。但收到重复键并不等于可以无条件返回成功:同一个 request_id 携带了不同商品和数量时,应该拒绝冲突,而不是把旧结果冒充为新请求成功。正确幂等需要保存关键请求参数或指纹,并比对重试意图。

可练习以下教学写法,但不要把它误解成跨集合事务:

db.lab_crud.updateOne({tenant_id:1,request_id:"import-001"},
  {$setOnInsert:{title:"导入单",version:0}}, {upsert:true})
// 同样参数重放,不再创建第二条;真正并发下仍需处理唯一键冲突并核对旧记录。

租户过滤应来自服务端可信身份上下文,不能让浏览器自己提交 tenant_id=1 就获得读取权限。本文固定租户仅为让练习的筛选、索引、关联条件可核对;所有集合间关联也要带上租户维度。Repository 的方法名不会天然携带未声明的隔离条件。

18.8 练习、答案与验收

练习一: 用初始化数据回答“备注为空的订单有多少”之前,需要先向业务确定什么?写出两种定义对应的查询。答案: 确定是否包含未采集字段。{tenant_id:1,note:null} 为四条;{tenant_id:1,note:{$type:"null"}} 为一条。缺失值和明确空值在埋点、数据迁移中经常具有不同含义。

练习二: 为什么 O1001 会被 items.sku=A 且 items.qty>=5 命中?答案: A 两件满足前者,B 五件满足后者。必须使用 items:{$elemMatch:{sku:"A",qty:{$gte:5}}},结果仅 O1002。不能把两个独立路径条件误当成 SQL 中同一明细行的两个列条件。

练习三: 产品 A 涨价到 21.00,O1001 应是多少金额?答案: 仍为 2×19.90+5×6.00=69.80。本实验商品集合初始价格已经故意与成交价不同,用来阻止通过当前主档重算历史单据的错误。若确实要改历史订单,应通过显式调价业务及审计完成。

练习四: 第二个版本条件更新匹配零条,是否应自动去掉版本条件重试?答案: 不应。去掉条件会恢复原本要防止的覆盖问题。应返回冲突,让用户重读或按业务合并;自动合并只能用于已定义可交换语义的操作,不能把任意表单覆盖当成安全重试。

练习五: 商品引用无对应记录时,schema validation 能否拒绝订单?答案: 本实验 $jsonSchema 只能检查文档结构和局部约束,不会替你查询商品集合并执行外键约束。应用要选择提交校验、历史快照、事务或后续校正机制,并解释选择的业务一致性。

验收时应能先预测结果,再执行 queries.js〔本地文件〕 的 Q1、Q4 断言。本文中所有“预期”均由固定样本推导,不是生产数据或作者实测输出。作者完成了源码阅读、官方资料核对与脚本静态检查;未连接业务服务,MongoDB 运行态验证状态以 实验 README 为准。继续阅读 第 19 章,把同一批文档变成可解释的统计结果。

原始文档 · database-course/19-MongoDB聚合索引与性能.md

19 MongoDB 聚合、索引与性能:先证明结果,再解释成本

一个 ERP 看板从“能显示数字”走到“数字可信且高峰期可用”,需要跨过两道门槛。第一道是语义:统计的单位究竟是订单、明细、商品还是任务?第二道是成本:为了返回二十条记录,数据库扫描了多少索引项和文档,在哪里排序,是否产生巨大中间结果?先解决第二道而忽略第一道,会得到一个更快的错误报表。本章沿用 第 18 章 的五个订单,先手算,再写管道,最后用 explain 建立性能证据。

事实与实验边界。项目源码来自 TbServiceImpl.java〔本地文件〕,文中以方法名精确定位;示例均为 tenant_id=1 的独立教学集合。官方行为按 MongoDB 8.0 文档核对。这里没有线上采样、索引清单、慢日志或生产 explain,所有“预期结果”都是固定数据推导。作者没有执行数据库脚本;可运行入口为 实验 README、init.js〔本地文件〕、queries.js〔本地文件〕。

19.1 把管道当成一系列有输入输出形状的变换

需求是统计未付款订单每个 SKU 的件数和成交金额。初始化样本如下,金额都是 Decimal128:

订单 状态 明细 订单金额
O1001 open A×2,单价19.90;B×5,单价6.00 69.80
O1002 open A×5,单价19.90 99.50
O1003 paid B×3,单价6.00 18.00
O1004 open 空数组,教学中的草稿单 0.00
O1005 cancelled A×1,单价19.90 19.90

先执行第一阶段,确保过滤语义正确:

db.lab_orders.aggregate([
  {$match:{tenant_id:1,status:"open"}},
  {$project:{_id:0,order_no:1,items:1}}
])
// 预期:O1001、O1002、O1004,共3个订单文档

第二阶段展开明细。$unwind 把一个数组的每个元素变成一条输出文档;输出中的 items 从数组变成了单个明细对象。默认情况下,空数组、null 或缺失字段不会产生输出。本例三个订单经过展开,得到三条明细:O1001/A、O1001/B、O1002/A,O1004 没有明细因此消失。这里“输入三条,输出三条”纯属样本巧合,并不表示文档与明细一一对应。$unwind 官方语义

db.lab_orders.aggregate([
  {$match:{tenant_id:1,status:"open"}},
  {$unwind:"$items"},
  {$project:{_id:0,order_no:1,sku:"$items.sku",qty:"$items.qty",
    line_amount:{$multiply:["$items.qty","$items.unit_price"]}}}
])
// 预期:O1001/A/2/39.80;O1001/B/5/30.00;O1002/A/5/99.50

最后按 SKU 分组,此时才可以对明细数量与明细金额求和:

db.lab_orders.aggregate([
  {$match:{tenant_id:1,status:"open"}},
  {$unwind:"$items"},
  {$group:{_id:"$items.sku",qty:{$sum:"$items.qty"},
    amount:{$sum:{$multiply:["$items.qty","$items.unit_price"]}}}},
  {$sort:{_id:1}}
])
// A:qty=7,amount=139.30;B:qty=5,amount=30.00

反例是在 $unwind 后求 {$sum:"$total"}。O1001 被展开两次,69.80 也被重复两次,结果变成 69.80×2+99.50=239.10,正确订单总额应为 169.30。如果需求是订单额,就应在订单粒度上求和;如果确实必须展开,应先恢复订单粒度再汇总,并解释重复键处理。不要看到 $group 就认为自动实现了业务去重。

preserveNullAndEmptyArrays:true 可以保留草稿,但并不能直接把草稿变成有效商品行。展开后可能没有 SKU,继续分组会产生空分组。报表若要同时显示“订单总数”和“有效商品件数”,应让两个指标沿不同粒度的管道计算,而不是在一个含义模糊的中间表上凑数字。

19.2 $lookup:关联的是业务身份,而不是一个看起来相同的值

现在要给明细附上商品当前名称。下面的关联同时使用租户和 SKU,避免把其他租户的同名 SKU 当成同一商品:

db.lab_orders.aggregate([
  {$match:{tenant_id:1,order_no:"O1001"}},
  {$unwind:"$items"},
  {$lookup:{from:"lab_products",
    let:{tenant:"$tenant_id",sku:"$items.sku"},
    pipeline:[
      {$match:{$expr:{$and:[
        {$eq:["$tenant_id","$$tenant"]},
        {$eq:["$sku","$$sku"]}
      ]}}},
      {$project:{_id:0,name:1,current_price:1}}
    ],as:"product"}},
  {$project:{_id:0,order_no:1,items:1,product:1}}
])

预期 A 明细对应一个商品,名称为扫码枪,当前价 21.00;B 对应标签纸,当前价 6.50。product 是数组,不是自动选中的单个对象。即使业务说一对一,也需要唯一约束支撑;实验在商品上建立 (tenant_id,sku) 唯一索引。如果关联键类型不一致,得到的可能是空数组,而不是错误;若关联端有重复数据,得到多个对象,继续 unwind 后又会放大金额。要先解释零条、一条、多条各代表什么,再选择保留缺失项、报错或降级展示。

$lookup 外表索引是否可用,与关联表达式形状和字段类型有关;$expr 中符合限制的字段与常量比较可以使用索引,并不是任意表达式都能高效查询,相关比较还存在 multikey 等限制。因此“把循环查询改成 lookup”只是改变执行位置,不是性能保证。先限制主表候选,再观察关联端扫描量和返回数组大小。$lookup 行为及索引限制

19.3 $facet:同一输入流计算列表、总数和摘要

项目 search 的源码先 count,再附加分页执行 find,这是两次数据库操作。若两次之间有新任务写入,总数与列表可能对应不同时间。这里能从代码推导“存在这个时间窗口”,但不能断言线上必然出现了用户可见错误,更不能凭此宣布必须重构。

对于教学列表,可以让相同筛选后的输入流进入 $facet 的多个分支:

db.lab_orders.aggregate([
  {$match:{tenant_id:1,status:"open"}},
  {$sort:{created_at:-1,_id:-1}},
  {$facet:{
    page:[{$limit:2},{$project:{_id:0,order_no:1}}],
    count:[{$count:"value"}],
    totals:[{$group:{_id:null,amount:{$sum:"$total"}}}]
  }}
])
// 预期 page=[O1004,O1002];count=[{value:3}];totals.amount=169.30

三个分支接收同一批管道输入,避免了客户端分两次请求的那个窗口。但是不能把它宣传成“所有并发情况下都自动有事务快照”;读取一致性仍受 readConcern、部署与执行语义约束。count 分支遇到零输入时得到空数组,而不是必然得到 {value:0},接口序列化应明确补零规则。

把 $facet 放在第一阶段会导致集合扫描;前置可使用索引的 $match、$sort 有利于减少读取成本。它还有自身内存限制,不能靠 allowDiskUse:true 把 $facet 的 100 MB 限制消除,最终输出文档仍受 16 MiB 限制。因此 page 分支应限制数量,不能把整个历史订单列表塞进一个巨大数组。详情见 $facet 限制与索引行为。

19.4 回到项目:最新活动聚合为什么需要检查数组形状

TbServiceImpl.getLatestAssignActivities 的源码流程是匹配 boundToObjects._objectId、按 created 降序、按 boundToObjects._objectId 分组,再用 $first 取活动。TbActivity.java〔本地文件〕 将 boundToObjects 声明为列表,TbBoundToObject.java〔本地文件〕 将 _objectId 映射为 ObjectId。这些是代码事实。数组路径作为聚合表达式,可能得到 ID 数组;未 unwind 时,分组可能以整个数组作为键,而非逐任务分组。是否影响当前业务,取决于实际数组形状与后续处理,不能仅靠注释下定论。

实验故意准备三条活动:e1 绑定任务 t1,e2 绑定 t1 与 t2,e3 绑定 t2;时间递增,执行人分别是 Alice、Bob、Carol。若按绑定 ID 数组直接分组,会保留 [t1]、[t1,t2]、[t2] 三组。业务想要的却是 t1 最新 e2,t2 最新 e3,共两组。把数组键直接 toString() 也不会神奇变成某个单任务 ID。

下面是仅针对教学集合的展开方案,不是已提交的项目修复:

const wanted = [ObjectId("000000000000000000002001"),
                ObjectId("000000000000000000002002")];
db.lab_activities.aggregate([
  {$match:{tenant_id:1,action:"update","boundToObjects._objectId":{$in:wanted}}},
  {$unwind:"$boundToObjects"},
  {$match:{"boundToObjects._objectId":{$in:wanted},
           "boundToObjects.objectType":"task"}},
  {$sort:{created:-1,_id:-1}},
  {$group:{_id:"$boundToObjects._objectId",activity_id:{$first:"$_id"}}},
  {$sort:{_id:1}}
])
// 预期:t1 -> e2;t2 -> e3

前面的 match 过滤候选活动,后面的 match 过滤展开后的目标绑定。省掉第二次过滤时,一条同时绑定目标与非目标对象的活动会把无关对象带进统计。_id 作为时间相同时的第二排序键,使“最新”选择具有确定规则;它并不自动代表更准确的业务时间,如果业务需要事件序号,应显式建模该序号。

19.5 数据转换失败是质量问题,不只是表达式技巧

源码 stats 给 storyPoint 做空串判断,再 $toDouble,外层 $ifNull 兜底。空串与 null 可以被处理,但“待评估”这样的非数值文本会让 $toDouble 报错,外层 $ifNull 不会捕获转换异常。Java 实体字段是 Double 也不能证明历史 BSON 从未存入字符串;本章不声称项目一定存在脏值,而是让读者理解查询对输入的假设。

实验 lab_type_cases 分别存了 "3.5"、""、"待评估"、null。教学写法用 $convert 将失败显式转成 null,同时把非法或缺失值计入质量指标:

db.lab_type_cases.aggregate([
  {$match:{tenant_id:1}},
  {$set:{numeric:{$convert:{input:"$storyPoint",to:"double",
    onError:null,onNull:null}}}},
  {$group:{_id:null,sum:{$sum:"$numeric"},
    invalid:{$sum:{$cond:[{$eq:["$numeric",null]},1,0]}}}}
])
// 预期:sum=3.5,invalid=3;invalid 包含空串、非法文本和null

如果报表要求区分“未评估”和“格式错误”,还应把原始类型和值分开计数。本例将二者合并,只是明确标注的教学口径。把所有转换错误悄悄写成零,虽然页面不再报错,却可能把漏填估时误报成低工作量。$convert 的 onError/onNull

19.6 复合索引要从完整查询形状推导

常见列表查询为租户内、指定状态、按创建时间倒序取两条。教学索引是:

db.lab_orders.createIndex(
  {tenant_id:1,status:1,created_at:-1,_id:-1},
  {name:"ix_order_page"}
)
db.lab_orders.find({tenant_id:1,status:"open"})
  .sort({created_at:-1,_id:-1}).limit(2)

等值条件先缩小索引区间,接着沿排序字段读取,_id 解决同时间记录的稳定顺序。这符合常见的等值、排序、范围设计思路,但不应把 ESR 当成机械定律:范围选择性极高时,牺牲索引排序以更早减少扫描也可能合理,需要对实际分布比较。没有 status 条件的查询,不能直接假设同一索引就自然提供全租户按时间排序,因为中间的状态维度改变了索引顺序。ESR 指南

深分页还有额外成本:skip(100000) 不等于通过数组下标瞬间跳到第十万条。对于连续翻页,可以使用上一页最后一条的 (created_at,_id) 作游标,按相同排序条件查询更早的数据:

db.lab_orders.find({tenant_id:1,status:"open",$or:[
  {created_at:{$lt:ISODate("2026-01-02T00:00:00Z")}},
  {created_at:ISODate("2026-01-02T00:00:00Z"),
   _id:{$lt:ObjectId("000000000000000000001002")}}
]}).sort({created_at:-1,_id:-1}).limit(2)
// 接在第一页 O1004、O1002 后,预期得到 O1001

游标分页不能天然跳到任意页,记录排序字段若被修改也可能产生移动,因此接口应明确游标含义、过滤条件是否绑定及翻页一致性需求。与其只说“MongoDB 分页慢”,更有用的表达是“深偏移造成扫描增长,当前交互是否可以换成继续加载”。

19.7 multikey:数组索引不是一个普通标量索引

给数组路径建索引时,MongoDB 自动把它处理成 multikey,一个文档可能贡献多个索引项。实验为同一个 items 文档数组的两个子字段创建索引:

db.lab_orders.createIndex(
  {tenant_id:1,"items.sku":1,"items.qty":1}, {name:"ix_order_item"}
)
db.lab_orders.find({tenant_id:1,
  items:{$elemMatch:{sku:"A",qty:{$gte:5}}}
}).hint("ix_order_item").explain("executionStats")

$elemMatch 把两个约束绑定在同一元素上,也给优化器组合符合条件的索引边界提供语义依据。省略它不仅会改变结果,还可能无法获得相同的边界收紧效果。不要为追求索引扫描量减少而删除或添加会改变业务含义的条件。Multikey bounds

复合 multikey 不能任意索引两个独立数组。假设某文档同时有 tags:["urgent","erp"] 和 watchers:["u1","u2"],把 tags 与 watchers 放进同一个复合索引会遇到并行数组限制;同一 items 数组下的标量子路径是不同情况。数组越长,写入要维护的索引项越多,磁盘和缓存成本也会上升。某些 multikey 查询不能成为覆盖查询,特别是要返回数组本身或使用 $elemMatch 等条件时,不能仅凭投影字段出现在索引里就断言不用读取原文档。Multikey 索引限制

唯一 multikey 索引也不是“数组内部元素不能重复”的校验器:它主要约束不同文档之间的索引键冲突。若业务要求一个订单每个 SKU 只出现一次,要在写入逻辑或适当校验中单独保证,不能误用唯一索引代替明细内部规则。唯一索引

19.8 explain 应回答什么,不能回答什么

queries.js〔本地文件〕 对同一查询输出两份计划,一份 hint({$natural:1}) 强制集合扫描作为教学对照,一份 hint("ix_order_page") 强制候选索引。它没有写死耗时,也没有断言五条数据的优化器一定主动选哪种计划:

db.lab_orders.find({tenant_id:1,status:"open"})
  .sort({created_at:-1,_id:-1}).limit(2)
  .hint("ix_order_page").explain("executionStats")

先看 nReturned 是否符合预期两条,再看 totalDocsExamined、totalKeysExamined,最后沿计划树看扫描与排序阶段。索引扫描后还需要取回文档是正常的 FETCH 行为;出现 IXSCAN 也可能扫描大量无用键。扫描/返回比很高时,要找是哪一段条件没能收紧范围;返回数为零时不能机械除零,应该直接报告扫描绝对值。只有五条样本时,耗时常接近测量粒度,无法证明生产收益。

classic 与 slot-based 引擎的计划结构不同,聚合 explain 也可能将阶段与游标信息组合在不同层级,所以自动审查不应只读取一个固定 JSON 路径。explain 不使用现有计划缓存,也不会把本次胜出计划缓存进去;其耗时不能直接当作稳定线上请求延迟。需要结合真实查询形状、数据基数、应用端响应、服务端资源再判断。Explain 输出说明

源码 stats 设置了 allowDiskUse(true)。这允许适用的聚合阶段在满足条件时使用磁盘,不等于所有阶段不限内存,更不等于管道已经优化。大范围排序、分组产生大量临时数据时,磁盘溢写可能使查询从报错变成慢查询。先将可前置的过滤条件前置,控制关联与展开后的规模,再考虑资源预算。包含式文本搜索同样要具体分析:源码的 contains 匹配和 ".*"+name+".*" 正则不能因为字段建了普通 B-tree 索引,就假定可以快速定位任意子串;受控前缀查询与任意包含查询是不同负载。正则索引使用

19.9 练习、答案与验证标准

练习一: open 订单展开后有三行,是否意味着 open 订单都有一条明细?答案: 否。O1001 两行、O1002 一行、O1004 零行。应同时报告输入订单数和输出明细数,不能只看总行数碰巧相同。

练习二: 为什么 unwind 后求订单 total 得到239.10?如何修正?答案: O1001 的69.80重复一次,正确总额169.30。若统计订单金额,应在展开前求和或单独 facet 分支求和;若统计 SKU 销售额,应以明细单价乘数量计算。

练习三: 给活动 e2 绑定 t1、t2,直接按绑定数组分组为什么错?答案: 数组作为整体分组键会把 [t1,t2] 视为独立组,而需求单位是任务。先展开,再匹配目标任务、稳定排序并按标量 ID 分组,结果为 t1/e2、t2/e3。这个实验能证明语义风险,不能证明线上已经出现相同数据。

练习四: facet 返回总数为3、page只有2条,是不一致吗?答案: 不是。总数分支不分页,列表分支有 limit2。真正应检查的是两个分支使用同一筛选口径,以及空集合时如何把 count 空数组映射成零。

练习五: explain 显示 IXSCAN,但扫描十万键只返回十条,能判定优化成功吗?答案: 不能。还要检查索引边界、后置过滤、排序以及扫描/返回比例;扩大数据集做对比时保持结果一致,再比较吞吐、延迟与写入成本。不能把本章小样本推导伪装成压测结论。

本章验证标准是能解释每阶段的数据形状、独立算出金额、识别数组分组与类型转换反例,并读懂自己环境输出的真实 explain。事务、一致性与部署边界见 第 20 章。作者只完成静态核对,尚未取得 MongoDB 实际执行计划与耗时证据。

原始文档 · database-course/20-MongoDB事务副本集与分片.md

20 MongoDB事务、副本集与分片

本章接18—19章,配套labs/mongodb。示例服务端基线MongoDB8.0、mongosh2.x;项目Spring Data客户端版本另见24/26章,不能把教学服务端版本当线上事实。先区分单文档原子、跨文档事务、副本一致性与分片路由四个边界。

1. 单文档原子是建模的重要工具

对一个文档的修改具有单文档原子性。库存文档把available与reserved放一起,一次带条件的$inc可维护两列关系,不必为了两字段立即使用跨文档事务。

db.lab_stock.updateOne(
  {tenant_id:1, sku:"A", available:{$gte:2}},
  {$inc:{available:NumberInt(-2), reserved:NumberInt(2)}}
)

检查matchedCount或相应结果,不要因API没抛异常就宣称预占成功。正数数量在应用校验,schema负责类型等约束。若同一请求重复提交,上述命令仍会重复扣,所以单文档原子不等于业务幂等。

在文档内保存无限已处理事件数组可以做局部去重,但会导致增长、索引和文档大小问题。若需要长期事件账本,通常需独立集合与明确事务边界。嵌入关系用于有界且共同更新的数据,不是把整个租户所有订单塞一个文档。

2. 跨文档事务的条件与流程

事务需要支持的副本集或分片部署,独立standalone不能直接等同。使用session,在该session关联的数据库句柄执行所有操作,事务级指定readConcern、writeConcern与readPreference。忘记传session可能让某一步在事务外提前提交。

配套queries.js的可选事务段:先查询同request_id预占记录,已存在则校验SKU和数量;否则条件修改库存,再插入唯一请求记录,最后提交。注入异常应使库存和预占一起回滚。请求唯一约束抵挡先查后写的并发竞争,不是先查本身具有排他性。

事务不要包含外部HTTP请求、对象上传和长时间用户等待。snapshot读关注与majority写关注需配合理解,不能只指定snapshot就断言读到所有多数提交数据。事务运行时与资源上限受版本配置限制,超长事务也会增加冲突与资源占用。官方事务

3. 重试事务与重试提交不是同一动作

TransientTransactionError通常意味着重新执行整个事务尝试;UnknownTransactionCommitResult意味着提交结果未知,需要按驱动协议重试提交或核实结果,不能立即另开一个不同业务ID重复执行全部效果。驱动方便API可以处理部分重试,但回调可能执行多次。

因此事务回调里不能无条件发短信或调用一次性外部扣款。所有重试都保持稳定业务身份、截止时间和明确终止条件。DuplicateKey不一定都代表同一请求已成功,也可能是其他唯一约束或并发冲突,需读取记录并核对请求摘要。

教学queries.js刻意没有实现完整生产重试,只演示正常提交、注入回滚、顺序重复幂等;脚本注释明确提交未知时不能据abort宣称未提交。不要把它直接复制为线上交易服务。

4. Read preference、read concern、write concern

readPreference选择倾向去哪个角色/节点读取,例如primary、secondaryPreferred;它不定义读取数据已达到何种提交状态。readConcern描述可见性保证,例如local、majority、snapshot等;writeConcern描述写入确认要求,例如w:1、w:majority和超时。

majority读不是“任意节点最新”。一个副本可以只返回它已应用且满足关注条件的数据;要获得因果会话内读己之写等保证,需要合适的读写关注与session关联。线性一致读还有独立条件与成本,不能把所有关注等级当简单加速/减速开关。因果一致性组合

writeConcern超时并不证明写没发生。调用者知道的是未在期限内得到所需确认,必须用业务身份处理不确定性。把所有超时当作可生成新请求的失败,会重复产生业务效果。

5. 副本集选举与oplog

副本集主节点接收写,副节点通过oplog追随,选举用于可用性恢复。选举期间应用可能遇到不可写、拓扑变化或选择节点超时;驱动重试能力需要匹配写入类型和幂等设计,不能替代业务正确性。

oplog是有保留范围的复制日志,不是无限审计档案。落后超过可追赶窗口可能需要重新同步,网络/磁盘和繁忙副本会扩大延迟。跨机房复制还涉及延迟、投票拓扑与故障域,单机启动三个进程只能练协议,不能证明真实容灾。

单节点副本集支持学习事务,但没有冗余或多数节点故障容忍。实验室明确采用这一轻量拓扑,不能把事务测试通过写成“高可用已验证”。主从延迟实验要另建多节点并记录实际节点与关注设置。

6. 分片键决定很多后续成本

分片集群包括mongos路由、配置服务与分片,各分片通常用副本集。分片键决定数据如何分布和查询能否定向。高基数、分布均衡、查询携带和热点风险都要考虑,不存在适合所有ERP的固定键。

tenant_id利于租户定向,但一个超级大租户仍可能热点;只按递增时间分片可能让新写集中末端;hash有助分散等值键,却削弱某些范围局部性。复合键能改善某些问题,也改变查询约束和唯一索引条件。官方分片架构

查询缺少可定向条件可能scatter-gather到多个分片,再归并排序分页。返回20条不代表只处理20条;大型聚合、lookup与跨片事务尤其要测量。分片不是解决坏查询的第一步,先确认模型、索引与单节点瓶颈。

7. 唯一性、迁移与变更流

分片集合的唯一索引受分片键相关限制,不能按单集合未分片时的直觉保证任意字段全局唯一。业务身份应在分片策略中可证明,或者使用独立协调。索引能创建成功和业务全局去重正确是不同判断。

Change Streams利用恢复令牌继续消费,适用于受支持部署。令牌不能跨任意历史保留无限恢复;消费效果与checkpoint仍要避免先推进后写导致丢失。全量快照接增量时要建立无缺口边界,Schema变化与删除事件也要处理。不能把Change Streams叫成自动提供跨数据库恰好一次。

项目任务查询Service〔本地文件〕选择当前或历史集合并按ID查询。它证明多集合读取路径,不能据此推断线上使用了事务、副本集或分片。阅读配置类也只能确认客户端装配,不代表集群运行拓扑。

8. 实验与答案

按README初始化,普通模式验证BSON、数组、聚合、唯一键;打开事务标志后,故意抛异常应保持库存5/0和0预留,正常提交后3/2和1预留,再重复同请求保持不变。服务器不可用时记录未执行,不用纯JS模拟冒充MongoDB验证。

一:save一个对象能否自动保护同时修改?普通整文档保存可能覆盖并发字段,需要版本或原子字段更新。原子性防半文档,不防业务丢失更新。

二:secondaryPreferred为什么读不到刚写入?它主要是路由偏好,不自动强制副本追到当前操作;考虑会话因果与关注组合,或关键读用主节点并明确语义。

三:跨文档事务为什么仍要唯一键?事务不自动让先查不存在的两个并发请求共享同一意图,唯一约束是最终竞争裁决的一部分。

四:为何事务回调不能直接发送外部订单?回调可能重试,外部效果不随数据库回滚。保存持久意图并用稳定事件ID处理外部传播。

原始文档 · database-course/21-备份恢复迁移与数据库运维.md

21 备份、恢复、迁移与数据库运维

会写SQL还不够:数据丢失能否恢复,结构变化能否与旧代码共存,故障时能否判断是连接、锁、IO还是复制,是数据库工程的交付标准。本章提供隔离演练流程,不操作业务实例。命令中的库名仅指本课程独立教学环境。

1. 先定义恢复目标

RPO是可接受的数据损失时间范围,RTO是从故障到恢复可用的目标时间。每日备份并不自动实现24小时RPO:备份失败、损坏或恢复缺权限时可能更差;有连续增量日志则可能更好。RTO包括发现、定位、准备环境、取备份、恢复、应用增量、校验、切流,不仅是导入SQL耗时。

副本不是备份。错误DELETE会被正常复制,账号滥用可能同时影响多个在线节点。备份需要独立保留、访问边界与版本管理;加密备份还要验证密钥恢复与授权,只有文件没有密钥等于不能恢复。

2. 逻辑备份与物理备份

逻辑备份导出表结构与数据,便于检查和选择性恢复,但大库导出/导入及重建索引可能耗时。物理备份更贴近数据文件与引擎恢复要求,通常适合更大规模,版本兼容、日志准备和恢复流程更严格。直接复制一个正在写入的数据目录不是自动一致的物理备份。

MySQL的单事务逻辑备份主要面向事务表一致快照。备份期间DDL、非事务表和跨资源业务状态有额外边界;不能仅加--single-transaction就宣称所有东西在同一时刻一致。routines、events、triggers、用户权限和配置是否包含也要列清单。

在已经创建的隔离事务容器中,可练习以下基线备份。它不覆盖PITR位点和全实例权限,仅验证教学库的逻辑恢复。

docker exec db-course-transactions mysqldump -uroot \
  --single-transaction --routines --events --triggers \
  --set-gtid-purged=OFF --no-tablespaces lab_transactions > lab-transactions.sql

执行后检查退出码、文件大小与内容结构,再在另一个明确的空教学实例恢复,不在源库试着覆盖。恢复后核对库存、流水和约束,而不只看mysql客户端退出0。MySQL备份类型

3. PITR是基础备份加连续日志

时间点恢复先还原基础备份,再从与该快照对应的位置重放binlog到目标边界。缺了中间日志、起点错了或重放超出误删事务,都会产生错误。ROW事件需要正确解码与目标环境,不能随意把显示出来的伪SQL当原始可执行恢复流。

演练按顺序创建快照B,记录其一致位点;提交事件E1,记下提交位置;执行教学误删E2;在新实例恢复B,只应用到E2之前的事务边界。校验E1存在、E2未发生,并对比金额、行数和约束。时间字符串受时区与边界精度影响,优先核对确切事务/日志位置,避免切到事务内部。

生产恢复通常需要完整操作审计、双人核对与隔离目标验证。本教材不提供把未知生产binlog直接管道执行的命令,因为缺少实际备份位点时无法生成正确方案。这里的缺失是具体恢复输入,不是SQL语法问题。官方PITR

4. PostgreSQL、MongoDB、Redis分别恢复什么

PostgreSQL逻辑备份与物理基础备份+WAL归档用途不同,时间点恢复需要连续WAL、正确时间线及目标设置。复制槽保留WAL有助消费者追赶,却可能在消费者长期失效时撑满磁盘,监控保留量与最旧需求。

MongoDB备份要与部署拓扑匹配。对持续写入的集群随意分别导出各集合,不自动得到跨集合一致业务快照。分片备份还需协调配置元数据和各分片;工具版本和restore选项要核实。先定义恢复集合、索引、校验器与用户权限范围,再选择官方支持流程。

Redis恢复区分缓存与不可替代状态。普通缓存可以从权威库限速重建,但全量回源可能形成惊群;会话丢失可让用户重新登录,却不能把任务唯一事实也当成可丢弃。RDB/AOF备份应包含实际版本需要的文件集合,并验证启动加载和最终键状态,不能只复制旧版本记忆中的一个文件。

5. 在线DDL也需要锁和资源

INSTANT、INPLACE、COPY表达不同算法能力,不是按名字自动承诺所有ALTER都能无锁完成。支持范围依表结构、操作、版本而异。即使允许并发DML,也可能在准备或切换阶段获取MDL,长事务阻塞DDL,等待的DDL还可能影响后续请求。

实验:A开启事务查询lab_stock并保持不提交;B尝试ALTER增加教学列;C查看元数据锁和进程等待。A回滚后B继续。仅在独立实验库进行,提前定义等待超时与清理。不能在生产用无限等待的ALTER探测锁情况。

上线加索引需要估算额外磁盘、redo/binlog、IO和副本延迟。显式指定支持的算法/锁要求有助在不满足时失败,而不是意外退化到重表操作;具体语法必须按目标版本核对。在线DDL并发

6. Expand-contract迁移

把旧amount分改成带币种的decimal,不应同一发布直接删除旧列。先扩展新列,部署兼容读取与明确权威写入,分批回填,再对账、切读、观察,最后在旧版本退场和回滚窗口结束后清理旧结构。

双写在同一表事务中容易协调,在跨库时需要额外恢复协议。回填与线上新写竞争时要有版本或“仅未填值”的条件,不能用昨日快照覆盖今天修改。回填记录游标、批次、异常与校验结果,失败后可续跑。

版本化迁移工具如Flyway/Liquibase可管理顺序和校验,不意味着本目录已部署它们,也不替你证明DDL可在线运行。历史已执行迁移通常新增修正版本而不修改旧脚本,避免环境间校验失配。回滚代码不自动逆转数据转换,不可逆迁移需保留恢复与向前修复方案。

7. 最小可用数据库看板

应用侧量连接获取等待、连接持有、SQL次数、SQL延迟、事务时长、失败分类。数据库侧量活跃连接、锁等待、慢查询、IO、缓存/内存、日志写入、磁盘空间。复制侧量接收与应用进度、延迟分布、错误与最旧保留位点。业务侧量库存差额、重复事件、报表水位和任务最老年龄。

慢SQL日志只覆盖达到阈值的SQL,不覆盖所有连接排队或百次短查询。数据库CPU低也可能所有线程在等锁/网络/连接。用同一时间窗口对齐应用、数据库和变更记录,避免只看一个峰值就决定扩容。

项目数据库阻断过滤器〔本地文件〕是动态规则型保护入口,是否加载、注册和命中需要运行证据。不要因类名含CircuitBreaking就假设它具备自动半开恢复状态机。停止错误写入和恢复处理吞吐也不是同一个目标。

8. 排障手册与练习

故障一:连接池满而数据库CPU低。先观察锁等待和长事务、未归还连接、下游等待,限制低优先级导出,再定位阻塞源。盲目加连接可能只扩大等待。

故障二:磁盘快速增长。区分数据、索引、undo、binlog/WAL、临时文件与备份堆积,再检查长事务与消费者水位。不能先删除不认识的日志文件“释放空间”,可能破坏恢复链。

故障三:恢复成功但页面缺附件。数据库与对象存储恢复点不一致。恢复清单应包括对象版本、映射关系和保留周期,业务验证必须读取实际文件。

练习一:制定库存服务RPO/RTO并写演练表。答案应包含目标、实际恢复点、每阶段耗时、未覆盖故障域与业务对账,不只填“备份每天一次”。

练习二:改列类型后旧应用写失败如何退?必须分析旧新协议兼容与数据是否可逆。若已删除旧列,简单回滚应用无效;需要向前修复或经过验证的数据恢复方案。

练习三:数据库恢复后能否立即重放全部消息?先确定恢复位点与消费者checkpoint是否一致,验证幂等并限制速度。否则可能重复处理或跳过恢复后缺失的数据。

原始文档 · database-course/22-跨数据库建模与ERP综合实战.md

22 跨数据库建模与ERP综合实战

1. 综合项目的目标与边界

本章把前面的知识合成一个可以验收的数据库工程。项目是多租户订单与库存预占:订单收到付款后申请库存,取消则释放,发货则消耗预占与实物量。数据库课程不实现真实支付或物流网络调用,这些动作使用固定的教学事件。你需要证明同一事件重放不会重复改变库存,失败后可以查询状态,报表能够与流水对账。

这项练习分三个等级。第一等级只使用MySQL实现正确的关系模型与事务。第二等级增加Redis查询缓存,但缓存不可用时事实依然正确。第三等级增加MongoDB任务文档和报表投影,明确各存储的权威归属与同步水位。不要一开始就同时引入所有产品,否则错误出现时难以知道是哪层破坏了假设。

模型名称采用独立的cap_前缀,避免与各专题的lab_实验表混淆。所有数量为整件,金额若扩展则必须带币种和单位。暂不支持负库存、预售与残次品;这些不是以后加一个布尔字段就能解决的功能,需要重定义可用量公式和流水类型。

2. 给每份数据指定唯一权威来源

数据 本练习权威来源 其他副本 更新规则
库存余额、预占与流水 MySQL本地事务 Redis展示缓存 提交后失效,缓存不参与最终扣减判断
商品标签关系 MySQL唯一约束 页面筛选缓存 唯一性由租户、商品、标签确定
导出任务进度 MongoDB单文档状态机 SSE或Redis通知 通知丢失后查询任务文档
店铺日报 可重建的报表表 图表缓存 标注水位、口径和计算版本
外部事件原始记录 持久事件账本 消费队列 同一event_id对应相同意图

“唯一权威来源”不是整个系统只许用一种数据库,而是一份业务事实必须有清楚的裁决位置。MySQL说库存已预占、Redis说没预占时,以事务状态为准。报表少了一笔订单时,不能直接修改订单去迎合报表。缓存删除失败需要补偿失效,不能把已经提交的订单自动视为失败并重新扣库存。

MongoDB任务状态与MySQL业务结果跨库,不能靠一个普通@Transactional自动提交二者。教学方案让MySQL事务写出待处理事件,由可重试的投影者更新任务或报表。这里仅定义持久化边界和幂等条件,消息调度与跨服务协议留给后续分布式模块。

3. 先用不变量约束设计

库存余额的不变量是0 <= reserved <= on_hand。同一租户、事件和效果类型最多产生一条已提交效果。一个订单预占的剩余量等于成功预占,减成功释放,再减成功出库。收到重复取消不能重复释放,收到出库后的取消也不能把已发出的货变回可用库存。

这些条件需要分层实现。单行数量关系可以使用CHECK与条件UPDATE;事件唯一性使用唯一键;订单状态转换使用带旧状态或版本的更新;多行余额与流水同步使用同一数据库事务。跨表SUM无法简单写成一条普通CHECK,所以还需要事务算法与对账查询。

每一条不变量都要写反例:如果去掉唯一键会怎样?如果先提交余额再写流水会怎样?如果取消只看当前余额而不检查该订单的预占记录会怎样?只有能解释反例,才知道某个约束不是装饰。

4. 第一阶段:余额表、事件表和事务

下面的DDL用于独立教学数据库,目标MySQL8.0.18+。先创建你自己的空实验库,在该库执行,不使用业务连接。脚本没有自动删除已有表;重复运行遇到同名表时先核对实验环境,再自行重建。

CREATE TABLE cap_stock (
  tenant_id BIGINT NOT NULL,
  warehouse_id BIGINT NOT NULL,
  sku_id BIGINT NOT NULL,
  on_hand BIGINT NOT NULL,
  reserved BIGINT NOT NULL DEFAULT 0,
  version BIGINT NOT NULL DEFAULT 0,
  PRIMARY KEY (tenant_id, warehouse_id, sku_id),
  CONSTRAINT ck_cap_balance CHECK
    (on_hand >= 0 AND reserved >= 0 AND reserved <= on_hand)
) ENGINE=InnoDB;

CREATE TABLE cap_effect (
  tenant_id BIGINT NOT NULL,
  event_id VARCHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
  warehouse_id BIGINT NOT NULL,
  sku_id BIGINT NOT NULL,
  effect_type VARCHAR(16) NOT NULL,
  quantity BIGINT NOT NULL,
  PRIMARY KEY (tenant_id, event_id),
  CONSTRAINT ck_cap_quantity CHECK (quantity > 0)
) ENGINE=InnoDB;

INSERT INTO cap_stock VALUES (1, 10, 1001, 10, 0, 0);

简化事件只作用于一个SKU。真实多SKU事件需要事件头与效果明细,或把效果身份明确为(tenant_id,event_id,sku_id,effect_type),不能直接照搬这个简化主键。事件ID使用大小写敏感的ASCII排序规则,让业务生成的不同标识不会因默认不区分大小写而意外相等。

一次预占的成功路径如下。它是一段需要应用控制分支的事务,不是可以忽略ROW_COUNT()继续提交的批脚本。

START TRANSACTION;

INSERT INTO cap_effect
  (tenant_id, event_id, warehouse_id, sku_id, effect_type, quantity)
VALUES (1, 'reserve-0001', 10, 1001, 'RESERVE', 6);

UPDATE cap_stock
SET reserved = reserved + 6, version = version + 1
WHERE tenant_id = 1 AND warehouse_id = 10 AND sku_id = 1001
  AND on_hand - reserved >= 6;

SELECT ROW_COUNT() AS updated_rows;

此时应用必须检查updated_rows。等于1才允许COMMIT;等于0必须ROLLBACK并返回库存不足或记录不存在。实验者分别手动执行对应分支,不能让客户端自动运行两条互斥分支。首次成功后实物10、预占6、可用4、版本1,事件表有一条记录。

重复执行同一事件时,INSERT碰到唯一键。如果旧事件已经提交,先结束当前失败事务,再读取旧记录,确认仓库、SKU、效果类型和数量全部一致,然后返回旧操作结果。相同ID却传7件是幂等键冲突,不是重复成功。实际系统可以保存规范化请求摘要和结果;比较摘要前还要定义字段顺序、缺省值和数值单位。

两个请求同时插入同一事件ID时,唯一性检查会协调竞争,并不是两个请求都必然立即得到重复键。后来的请求可能等待先前事务提交或回滚。若先前回滚,后来者有机会继续执行,这正是把事件和余额放在同一事务中的价值。

5. 不同事件争抢同一库存

重置教学数据后,会话A用事件A预占6件,会话B用事件B预占6件。两者都在同一个库存主键上执行条件UPDATE。A先成功并提交后,B应重新按写入时可用状态判断条件,影响零行并回滚自己的事件插入。最终仍是预占6件,不是12件,也不是两条效果却只有一次余额变化。

如果先在Java里SELECT可用量10,再无条件UPDATE reserved=reserved+6,两个事件都可能通过应用预检查。CHECK可成为最后拒绝屏障,但应用应将受控条件更新作为正常竞争路径,不能用大量约束异常代替清楚的业务反馈。

采用版本号乐观锁也可以,但语义不同:WHERE version=:oldVersion要求自读取以来没有其他提交;条件更新要求当前余额足够。高冲突热点上版本重试可能产生大量无效工作。选择悲观锁、条件更新还是版本锁,必须考虑不变量是否单行可表达、修改是否依赖复杂读取和冲突概率。

多SKU预占先按稳定的仓库/SKU顺序处理,失败则回滚全部。统一顺序降低死锁概率,但不能承诺绝无死锁,因为索引维护和其他业务路径也可能形成循环。捕获数据库死锁后重试整个事务,并保持同一事件身份和有界退避;不要只重放最后一条UPDATE。

6. 释放与出库需要预占身份

余额充足不等于允许释放。要新增cap_reservation,以租户、订单行或预占ID标识归属,记录预占总量、释放量和出库量。释放操作先以状态/版本约束该记录,确认剩余可释放量,再减少库存reserved,两者在同一事务中提交。

假设订单A占6件、订单B占2件,总reserved为8。A已经全部出库,B还未出库。此时A收到重复取消,如果只执行reserved >= 2的检查,可能错误释放B的库存。库存总量约束不能证明订单归属,必须检查具体预占身份。这是“SQL执行成功,但业务语义错误”的典型反例。

出库通常同时减少on_hand与reserved,数量相同,因而可用量保持不变。退货验收入库只增加on_hand;退款不必然增加库存。把资金状态和实物状态分开,才能处理仅退款、退货途中、部分验收和拒收等实际场景。

7. 对账查询怎样避免再次算错

若增加流水表,每条记录保存实物增量和预占增量,从零或期初快照开始应满足余额等于期初加流水。先把流水按完整库存身份聚合,再与余额一对一关联;不要先JOIN订单明细和物流包裹,再SUM库存流水,那会重新引入明细放大。

对账必须对齐观察时点。余额查询在流水事务提交后,而流水扫描使用更早快照时,可能制造虚假差额。可选择同一一致性快照、停写窗口或明确水位下的历史余额重建。副本延迟也会影响对账,不能在两个不同步的节点各取一半数据再宣布库存错误。

发现差额先保存身份、基线、扫描水位和相关事件,判断是漏写、重复、读取不一致还是口径变化。修复使用有唯一身份的调整事件,记录前后值与理由,不以无审计的直接覆盖余额消除证据。补偿本身也要可重试,否则修复重跑会制造第二次错误。

8. 第二阶段:给查询增加Redis

缓存键可为course:stock:v1:tenant:1:warehouse:10:sku:1001,值包含展示数量、数据库版本和生成时间。缓存缺失时查库、设置有限TTL。写操作始终在MySQL执行条件更新;页面看到可用4件并不构成抢购或库存保证,最终提交仍以数据库判断为准。

读旧值、写提交并删缓存、读线程再回填旧值的时序必须测试。有限TTL只能限制某些陈旧持续时间,不能证明立刻一致;延迟双删也没有消除全部时序。更强方案可以用版本防旧值覆盖,但所有缓存写入口必须遵循同一个比较协议,而且缓存重建、删除和版本存储丢失也要设计。

本项目验收不要求实现强一致缓存。要求你清楚写出允许陈旧时间、失败重试、数据库回源保护、热点合并和监控。如果库存展示允许短暂陈旧而写入准确,这是一种明确的产品取舍;如果库存数据承担授信或付款承诺,则需要重新设计读取语义。

9. 第三阶段:MongoDB任务投影

一个导出任务文档可包含tenantId、taskId、state、version、cursor、rowsWritten、fileRef、attempt、leaseOwner、leaseUntil。不要把全部导出行嵌入任务文档。任务状态使用条件更新,例如只允许持有匹配owner且租约有效的worker推进当前attempt,版本随更新增长。

文件发布是外部副作用。先上传完整对象,再将引用与完成状态写入任务;失败后可能留下孤立对象,需要清理。若先标记完成再上传,用户可能得到不存在的文件。Mongo单文档原子更新不覆盖对象存储,这个边界必须出现在故障矩阵中。

任务重复执行时以任务与attempt区分临时文件,以最终fileRef指向确认后的对象。租约失效的旧worker不能覆盖新worker结果,条件更新影响零条时应该停止发布状态。单纯使用Mongo事务也不会让外部上传自动回滚。

10. 交付与参考验收

交付至少包含DDL、样例数据、事件语义、事务伪代码、幂等冲突处理、对账SQL、执行计划、故障矩阵和恢复记录。每项失败场景都要指出最后已提交的状态,不能只写“发生异常则重试”。

场景 应观察到的结果
同一事件连续提交10次 一个效果,余额只变化一次
相同事件不同数量 明确冲突,不覆盖旧意图
库存不足 余额不变,效果插入也回滚
提交后响应丢失 同键重试返回既有结果
两个不同事件争抢 只有符合当前余额的请求提交
缓存不可用 写入正确,读有受控回源与负载保护
副本未应用写入 关键回查选定主库或验证等待策略
对账程序中断 有水位可续跑,修复事件不重复
任务租约过期 旧worker状态更新被条件拒绝

答辩题: 为什么不只用Redis锁保证库存?参考答案必须包含租约过期、旧执行者恢复、锁服务故障、数据库最终约束、事件幂等与事务范围,而不只是说“分布式锁不可靠”。

答辩题: 一个事务执行成功就证明整体成功吗?参考答案应区分提交确认丢失、异步投影尚未追上、缓存陈旧和外部副作用,同时指出本地不变量已经由哪些约束保证。

源码对照: 阅读项目库存事务入口〔本地文件〕和批量库存增量SQL〔本地文件〕。把教学方案与项目实际边界逐项比较:事务前读了什么,哪些写属于一个资源,是否跨多个批次,幂等在哪一层。这里要求提出可验证的问题,不把教学表的约束假装成项目现有能力。

原始文档 · database-course/23-实验答辩与数据库能力检查.md

23 实验答辩与数据库能力检查

1. 怎样判断自己已经掌握

记得术语与能独立交付不是一回事。数据库能力至少有四级:能复述概念,能写出正常查询,能构造失败反例,能在给定约束下选择方案并用证据验证。下面按问题给出答案骨架,你应先独立写答案,再检查是否遗漏边界。不要把这些答案当成唯一标准措辞;能用数据和时序证明更重要。

每次答辩提交四份证据:最小结构与数据、完整执行顺序、真实观测、推导。性能题还要记录规模、分布、版本、缓存冷热、并发和计划。没有运行数据库的题可以先做纸面推演,但记录必须明确“推演”,不能在实验报告写“通过”。

2. 建模与SQL:解释结果每一行代表什么

问题一:商品与标签为什么需要关联表?

一个商品有多个标签,一个标签属于多个商品,是多对多关系。关联表每行表示“某租户的某商品拥有某标签”。唯一性通常是这个完整三元组,不能只对商品建唯一键。若商品和标签的ID只在租户内唯一,外键或应用归属检查也必须带租户,不能只校验数字ID存在。

进一步追问:把标签存成逗号字符串有什么代价?成员查询、去重、引用完整性和索引支持会变复杂;字符串1不能和11混淆。JSON数组提供结构不等于自动获得关系约束,数组成员索引和查询语法还依赖产品及版本。小且固定的展示字段可以冗余,核心关联仍要按访问与一致性需求设计。

项目对应标签关系DDL〔本地文件〕。两个索引列顺序分别支持从商品查标签、从标签查商品,不能因包含相同三列就认定重复。还要考虑唯一约束用途和覆盖读取,不能只比较索引名。

问题二:两条明细、三笔退款,为什么报表六行?

订单与商品、退款分别为一对多。以订单为连接条件直接关联两张子表,会得到每个商品匹配每笔退款的六个组合。商品金额重复三次,退款金额重复两次。SUM(DISTINCT amount)按金额值去重,会把两笔同额真实交易错误合并。

正确答案先定义目标粒度,再分别聚合到该粒度后一对一连接。如果需要每条商品分摊退款,还必须定义分摊规则和舍入尾差,不能用减少JOIN行数来替代业务算法。性能优化也不能以改变口径换取更快结果。

问题三:LEFT JOIN之后WHERE筛右表为什么丢失空店?

无匹配时右表列补NULL。WHERE orders.status='PAID'在补空行上不是TRUE,因此该行被过滤。条件放在ON可以约束匹配并保留左侧店铺。计数使用非空匹配键而不是COUNT(*),否则补空行也算一条。SUM无输入返回NULL,是否转零应按报表口径决定。

问题四:NOT IN遇到NULL怎么办?

先确认子查询和左表达式可空性。候选集合含NULL时,某个不等于所有已知值的表达式仍无法确认与未知值不等,WHERE会排除UNKNOWN。可以使用符合语义的NOT EXISTS;若业务确实要求排除空值,应显式过滤并解释左侧NULL如何处理。不能只记“NOT IN慢,NOT EXISTS快”,语义与优化器是两个层次。

问题五:为什么游标必须包含唯一尾键?

同一时间可能有多条记录,仅保存时间并使用大于条件会漏掉同时间余下记录。采用稳定排序元组,例如created_at与id,并使续页比较和ORDER BY方向一致。筛选改变后旧游标失效;排序列变化会影响一致遍历,需要固定快照、水位或业务禁止修改等额外策略。

3. 索引与执行计划:说清楚减少了什么工作

问题六:联合索引(a,b,c),查询只有b就绝对不能用吗?

不能做绝对断言。常规定位依赖前导列,但优化器也可能选择全索引扫描或版本支持且条件适用的skip scan。是否“用索引”要细分索引定位、索引过滤、覆盖和排序,看到key字段非空不等于高效。答案应解释为何缺少a通常削弱定位,再用计划验证实际选择。

问题七:范围条件后所有列都失效吗?

范围往往限制后续列进一步收窄连续扫描区间的能力,但后续列仍可能用于索引条件下推、过滤或覆盖。排序能否被索引直接提供还要看等值前缀、范围与排序列关系。必须区分“定位扫描边界”和“仍可发挥其他作用”,不要用一句口号覆盖所有用途。

问题八:给每个WHERE列单独建索引好吗?

通常不能替代面向实际查询的联合索引。多个索引可能通过index merge组合,也可能只选一个,但每个索引都有写维护、存储和统计成本。先归类核心查询,分析选择性与排序,再提出候选,比较计划和写入负担。低选择性字段并非永远没用,放在合适联合索引或覆盖查询里可能有价值。

问题九:估计10行,实际100万行,怎么排查?

检查谓词是否符合类型、统计信息是否失真、数据倾斜、列相关性和参数分布。更新统计或使用适用直方图可能改善估计,但不是替代索引设计的万能按钮。记录优化前后计划和代表性参数,避免只让小租户更快却使大租户更慢。EXPLAIN ANALYZE实际执行查询,应在受控环境测量。

问题十:深分页优化为什么不能只改成更大的内存?

大OFFSET要求跳过候选结果,回表和排序又可能放大成本。延迟关联可先获取较窄的键再取宽列,但仍可能扫描大量偏移项;游标改变了访问方式,但不支持任意跳页的同等体验。需求若必须随机跳页,需要明确允许成本、结果快照、上限或预计算,而不是宣称一种改写解决全部分页。

4. 事务与锁:写出A/B时序

问题十一:RR下每次SELECT结果一定相同吗?

需要区分快照读、锁定读、自己的修改,以及Read View建立时点。普通一致性读与FOR UPDATE不遵循完全相同的读取方式。一个事务还可能读到自己的写入,与旧快照组合成外部任何单一时刻都没出现过的状态。不能把“可重复读”扩展成所有语句冻结整个数据库。

问题十二:索引为什么影响锁范围?

InnoDB锁关联实际访问的索引记录和范围。完整唯一键等值命中、非唯一范围扫描、查找不存在记录、不同隔离级别都会影响锁定。无合适索引可能扫描并锁定大量记录,业务WHERE最终匹配一行不代表只接触一行。解释时写出表结构、索引、谓词、级别和计划,再观察data_locks等诊断数据。

问题十三:行锁为什么还会死锁?

A持有记录1等待记录2,B持有记录2等待记录1,形成循环。锁粒度小不代表无循环。还可能由二级索引、外键或间隙相关竞争导致。缩短事务、统一访问顺序、合适索引可降低概率;应用仍需要识别受害者并重试整个事务,且重试不能重复事务外副作用。

问题十四:锁等待超时等于整个事务已经回滚吗?

不能统一假设。数据库错误类型与配置决定语句或事务回滚行为;死锁与锁等待超时也不能混为一谈。应用在异常路径应明确结束当前事务、释放资源并重建重试边界。连接池归还前必须恢复合理状态,避免把未结束事务留给下一次请求。

问题十五:什么时候需要SELECT FOR UPDATE?

当业务决定依赖若干当前值,并且后续修改需要保护这些值免受竞争时可以考虑。若单条条件UPDATE就能表达不变量,直接更新通常更简洁。锁定读取必须在有效事务内,且所有竞争写路径遵守相同数据约束;对数据库行上锁不会锁住外部API或Redis里的另一份状态。

5. 复制、分片与恢复:区分提交和传播

问题十六:主库提交后读副本为什么还是旧数据?

事务提交发生在主库,副本需要接收日志并应用。异步链路允许延迟,某些半同步确认也不等于副本SQL已应用。写后关键回查可以路由主库,或使用明确的位点等待与超时策略;固定睡眠只是假设延迟上界,无法证明一致性。

问题十七:读副本可以避免主库压力吗?

能分担适合陈旧容忍的读取,但副本也有复制应用、IO、锁和长查询的资源竞争。把所有大报表放到副本可能拖慢复制,进一步扩大陈旧。连接池与查询限额应按节点职责分配,必要时引入专用报表投影。容量提升与一致性代价必须一起评估。

问题十八:分片后UNIQUE还保证全局唯一吗?

通常只保证实际执行约束的那个物理范围。需要明确分片键如何把同一业务唯一身份定位到同一分片,或设计全局唯一身份与协调机制。跨片JOIN、分页、排序和聚合可能需要扇出归并,SQL能被中间件解析不等于成本低或事务原子性自动成立。

问题十九:CDC进度什么时候推进?

推进点应与目标端已持久化处理的范围对应。先推进再写目标会在宕机时漏数据;先写目标再推进会在宕机时重放,因此目标需要幂等。一个批次只有部分租户成功时,必须明确重放和去重粒度。内存收到了数据不是持久化完成。

问题二十:备份文件存在为什么不等于能恢复?

还要验证一致性基线、增量日志连续性、密钥权限、目标版本容量、恢复工具和业务校验。恢复到指定时间后检查关键不变量、文件引用与用户结果。RPO关注能恢复到哪一时刻,RTO覆盖发现、恢复、校验与切换全部阶段,不能只量导入命令运行时间。

6. Redis、MongoDB与ORM:拒绝跨产品错误类比

问题二十一:Redis事务和MySQL事务一样吗?

不一样。MULTI/EXEC组织命令执行,WATCH提供乐观检查,但运行阶段命令报错不意味着所有先前效果回滚。Lua隔离执行也不是自动撤销已发生写入的数据库事务。脚本先校验输入,再写入,限制执行时间,并明确持久化与复制边界。

问题二十二:Redis主从切换后锁会怎样?

复制延迟可能让已在原主创建的锁未出现在新主。即使没有故障切换,租约过期也会允许新执行者获得锁,而旧执行者可能继续运行。token比较解锁防止删别人的锁,不等于阻止旧执行者写业务资源;后者需要资源端版本或fencing等约束。

问题二十三:Mongo数组中两个条件一定约束同一元素吗?

多个点路径条件可能由不同数组元素分别满足。需要同一元素同时满足时使用合适的$elemMatch,并检查索引multikey约束。查询匹配语义、投影返回哪些数组元素、更新定位哪个元素是三件事,不能互相推断。

问题二十四:Mongo majority读取就是全局最新吗?

majority描述读到的数据满足相应提交可见性条件,不自动保证任何节点立即返回最新写入。读偏好、会话因果约束、读写关注和节点应用进度共同决定结果。要求读自己的写入时需要匹配的会话与关注设置,不能只改单个参数后宣称线性一致。

问题二十五:ORM自动生成SQL就不用看SQL了吗?

框架生成的SQL仍受索引、连接次数、事务边界和结果集大小约束。循环调用Repository可能成为N+1;自动分页COUNT可能比取一页慢;逻辑删除、租户与乐观锁插件还可能改写SQL。学习者必须能从调用方法反推最终语句,并在日志或测试中核实参数与影响行数。

问题二十六:MyBatis一级缓存能当业务缓存吗?

它的生命周期与SqlSession等框架行为相关,不提供跨实例业务缓存的完整更新协议。事务、刷新与配置会影响命中。二级缓存也要考虑跨Mapper修改、关联数据和序列化。不能把框架为了减少重复查询提供的机制当成普遍一致的业务缓存。

问题二十七:增加连接池maxActive可以解决超时吗?

只有数据库有剩余服务能力且瓶颈确实是可用连接不足时才可能有效。慢SQL、长事务或锁等待导致连接长期占用时,更多连接可能增加竞争。分别测获取等待、连接持有、SQL执行和事务时间,再决定限制入口、优化查询、缩短事务或调整池容量。

7. 实操评分与下一模块入口

评分按正确性40、机制解释20、性能证据20、故障恢复20分。任何跨租户读取、重复扣库存或无法恢复的写入,都不能靠查询很快补分。性能没有实际计划和数据分布只记推测;恢复没有隔离演练记录只记方案。目标是诚实定位自己的能力,而不是凑满分。

完成本模块后,后续分布式课程承接数据库提交与外部传播之间的边界,系统讲消息投递、Outbox、Saga、幂等协议与一致性模型;高并发课程承接数据库容量,讲负载建模、排队、限流、隔离、背压与压测。两者都会复用这里的不变量与实验数据,而不是重新背一遍技术名词。

原始文档 · database-course/24-ORM与数据访问技术选型.md

24 ORM 与数据访问技术选型

本章解决一个具体问题:浏览器提交的订单查询,如何变成数据库能够执行的操作,又如何变回页面上的金额、编号和列表?理解这条往返路径之后,才能判断该用 MyBatis、MyBatis-Plus、Spring Data MongoDB,还是直接使用 JDBC。本章负责建立选型和对象映射的整体认识;第 25、26 章分别展开 API,第 27 章展开连接池、驱动、类型和工具链。Spring 事务传播、代理和业务分层原则由第 09 章负责,这里只说明数据访问 API 接入事务时的必要边界。

24.1 先确定事实和版本,再讨论框架

以下源码核对日期为 2026-11-10,链接相对本课程目录,行号是当前工作区快照。旧手册索引只作为发现入口,下面的结论均重新读取了实际代码。没有启动业务应用,没有访问业务数据库,也没有执行配置中心查询。因此“源码存在”“依赖声明”“运行时生效”是三个不同层次的结论。

erp-admin/pom.xml 第 423 行〔本地文件〕导入 Spring Boot 2.7.3 BOM,第 621 行管理 MyBatis-Plus starter 3.5.5;第 21、25 行分别声明 Druid 1.2.20 和 PageHelper starter 1.4.7。dependencyManagement 只管理版本,并不等于每个子模块都已引入该依赖。ticket 模块 POM 第 178 行〔本地文件〕确实声明 MongoDB starter。Boot 2.7.3 官方依赖表管理 Spring Data MongoDB 3.4.2 和 Connector/J 8.0.30;这是没有其他覆盖时的基线,不是本次通过依赖解析获得的最终运行版本。

不能把整个工作区视为一个版本统一的应用。例如 erp-item/pom.xml 第 60 行〔本地文件〕声明 Connector/J 8.0.19,物流模块父 POM 第 62 行〔本地文件〕声明 MyBatis-Plus 3.3.2。后者不能直接照抄面向 3.5.5 的插件配置。本课程示例以 Java 8、Boot 2.7.x 生态为理解基线,明确标记教学用的新类、新表;不将历史基线当作面向新项目的安全升级建议。

本次对工作区 Java 文件和 POM 检索了 spring-boot-starter-data-jpa、hibernate-core、JpaRepository、EntityManager、javax.persistence.Entity、jakarta.persistence.Entity,没有匹配结果。因此只能说“在已检索源码与直接声明中没有发现 JPA/Hibernate 使用证据”。未解析的私有依赖、未检出的分支和部署制品不在证明范围内。MongoDB 的 @Document 和 MongoRepository 也不是 JPA。后文 Hibernate/JPA 仅作技术对照,不描述成仓库已有实现。

24.2 一次请求有三套类型系统

浏览器处理 JSON;Java 处理对象、泛型和时间类;关系数据库处理列、NULL、精度、约束和事务。三套类型系统并不天然一致。Java Long 可以精确表示的整数,JavaScript Number 未必能够精确表示;Java BigDecimal 中的十进制数,如果先经浏览器浮点运算,进入 Java 时可能已经失真;JSON 缺少字段,与明确传入 null,在更新接口里也可能代表不同动作。

假设页面查询某租户的订单,本章采用以下教学契约。租户身份从服务端可信身份上下文取得,不允许页面通过传入一个 tenantId 切换数据归属。排序名称是 API 约定的枚举,不是数据库列名。页码从 1 开始,页大小限制在 1 到 100,具体限制应由业务服务统一落实。

// 教学前端:ID、金额保持字符串,不先转成 Number。
const query = new URLSearchParams({
  status: 'PAID', pageNo: '1', pageSize: '20', sort: 'newest'
});
const response = await fetch('/api/orders?' + query.toString());
if (!response.ok) throw new Error('查询失败');
const page = await response.json();
// page.items[0] 示例:
// { id: "9007199254740993", amount: "123.40", createdAt: "2026-11-10T08:00:00Z" }

请求 DTO 表达调用者能够提交什么;DO 或持久化实体表达数据库中如何保存;响应 DTO 表达调用者能够看到什么。它们可以有相同字段,却有不同的修改权限。version 可以让客户端携带用于条件更新,deleted、tenantId、审计创建人则不能因此自动成为可写字段。将请求反序列化到持久化实体,再把所有非空属性交给通用更新方法,是典型的越权赋值入口。

下面只展示类型关系,省略普通访问器;实际示例类使用 JavaBean 构造和 getter/setter,不能在 Java 8 项目直接复制使用 record。

class OrderQueryDTO {
    private String status;
    private Integer pageNo;
    private Integer pageSize;
    private String sort;
    // getter/setter
}
class OrderDO {
    private Long id;
    private Long tenantId;
    private BigDecimal amount;
    private LocalDateTime createdAt; // 教学表约定 DATETIME 中存 UTC 墙上时间
    private Integer version;
    // getter/setter
}
class OrderViewDTO {
    private String id;
    private String amount;
    private String createdAt; // 明确带 Z 或偏移量的接口时间
    // getter/setter
}

映射必须显式体现语义:金额用 toPlainString() 输出;ID 用 Long.toString();只有当数据库列确实采用 UTC 约定时,才能把 LocalDateTime 按 UTC 转为 Instant。字段同名不是转换正确的证明。MapStruct 能把赋值生成到编译期,但不会替开发者决定币种、时区、舍入模式,也不会自动判断一个字段是否允许外部写入。

24.3 关系数据库路径:SQL 的前后发生了什么

完整的教学路径可以写成:前端参数 → HTTP 绑定与校验 → 请求 DTO → 服务端身份和查询条件 → Mapper 方法 → MyBatis 映射语句 → 带占位符的 SQL 与参数映射 → JDBC PreparedStatement → 连接池借出的连接 → 数据库驱动 → 数据库 → ResultSet → TypeHandler → DO/查询投影 → 响应 DTO → JSON → 页面。数据库驱动负责协议编码与网络通信;连接池负责复用物理连接;ORM 或映射框架负责对象与数据库操作之间的转换。它们不是互相替代的产品。

public interface OrderMapper {
    List<OrderDO> findPaid(@Param("tenantId") Long tenantId,
                           @Param("limit") int limit);
}
<select id="findPaid" resultType="course.OrderDO">
  SELECT id, tenant_id AS tenantId, amount, created_at AS createdAt, version
  FROM course_order
  WHERE tenant_id = #{tenantId} AND status = 'PAID' AND deleted = 0
  ORDER BY created_at DESC, id DESC
  LIMIT #{limit}
</select>

这里 #{tenantId} 是参数绑定,最终 SQL 形状类似 tenant_id = ?。驱动收到 SQL 模板与参数,不需要把用户输入当成 SQL 语法拼进去。结果列可以通过别名、驼峰配置或显式 resultMap 对应 Java 属性。MyBatis 的查询返回对象通常是普通对象,修改 order.setAmount(...) 本身不会自动执行 UPDATE,仍需明确调用更新 Mapper。这与有持久化上下文和脏检查的 ORM 模型不同。参数和结果映射的基础契约见 MyBatis 3 映射语句文档。

Mapper 接口通常由框架代理实现,不必手写同名实现类。XML 的 namespace 必须匹配接口全限定名,语句 id 必须匹配方法名。接口扫描和 XML 资源扫描是两件事:扫描到了接口,不代表找到了 XML。多数据源时还需要确认这个接口绑定的 SqlSessionFactory,否则 SQL 正确也可能发往错误的数据源。以上是实际排障时比“这个框架性能好不好”更早要回答的问题。

24.4 仓库中一条可逐段检查的真实调用链

以发版日志列表为例,ReleaseNoteController 第 34 行〔本地文件〕接收 /biz/releaseNote/list,第 36 行调用 startPage(),第 37 行调用 Service,第 38 行把列表封装为表格响应。ReleaseNoteServiceImpl 第 40 行〔本地文件〕继续调用 Mapper;ReleaseNoteMapper 第 28 行〔本地文件〕声明查询方法;ReleaseNoteMapper.xml 第 26 行〔本地文件〕用动态条件查询 release_note。

回程从 XML 第 7 行的 ReleaseNoteResult 开始,publish_time 映射到 publishTime,gmt_created 映射到 gmtCreated,组成 ReleaseNote 列表再原路返回。这里 Controller 确实复用了实体接收筛选条件,并非本章教学示例的独立请求 DTO。读源码时应描述事实,再讨论这种复用会让接口字段和表字段耦合;不能为了符合分层图,编造一个实际不存在的 DTO 转换器。

连接装配可继续追到 MyBatisConfig 第 118 行〔本地文件〕:它创建 SqlSessionFactoryBean 并注入 DataSource、类型别名、Mapper XML 和配置资源。DruidConfig 第 45 行〔本地文件〕定义主数据源工厂,第 51 行创建 RayDruidDataSource,第 54 行配置 MySQL 驱动类。实际最终路由、属性覆盖和连接参数需结合运行装配验证,不能仅凭这两个类断言线上连接池的最终大小。

本次未找到与该接口一一对应的前端源码,因此前端片段是教学客户端,不声称来自仓库页面。JDBC 与数据库交互的下半段是根据框架机制解释的执行路径,不是线上抓包记录。把证据边界写清楚,能够避免读者将一个合理示意图误当成已验证的生产拓扑。

24.5 MongoDB 路径为何不经过 JDBC

MongoDB 的路径是 DTO → Repository/MongoTemplate → 映射转换器 → BSON 查询或更新 → MongoDB Java Driver → 驱动管理的连接池 → MongoDB → BSON 文档 → 实体 → 响应 DTO。它没有关系型 SQL,也不通过 MySQL Connector/J,更不能用 HikariCP 参数配置 Mongo 驱动连接池。框架名称同属 Spring Data,不表示底层协议相同。

仓库中的 TbTaskRepository 第 10 行〔本地文件〕继承 MongoRepository<TbTask, String>;方法 findFirstByProjectIdAndUniqueId 根据 Java 属性名生成条件。TbTask 第 28 行〔本地文件〕又把 projectId 映射为 _projectId,并指定 BSON ObjectId 类型。Java 是 String,不等于 BSON 中也是字符串;查询不到数据时,应先检查实际存储类型,再怀疑索引或网络。

Repository 适合固定查询与通用 CRUD;复杂动态条件、聚合、局部更新、动态集合通常由 MongoTemplate 表达。两者可以共用实体映射,不需要让每个业务操作只能选一个。仓库 TbServiceImpl 第 234 行〔本地文件〕使用 Template 做计数和分页,而第 151 行使用 Repository 查单个任务。这是可直接观察到的组合使用。

24.6 按查询和一致性需求选型

技术 开发者主要控制什么 合适场景 需要承担的成本
JDBC/JdbcTemplate SQL、参数、逐行转换 小而明确的 SQL、批处理、特殊驱动能力 自行维护映射和方言,原生 JDBC 还需管理资源
MyBatis SQL、动态片段、结果图 复杂查询、报表、已有表、分片 SQL XML 与接口一致性、显式更新、SQL 测试
MyBatis-Plus 单表 CRUD 与条件构造器,必要时 XML 规则明确的业务表、统一分页和审计 插件链、版本兼容、自定义 SQL 的保护范围
Spring Data MongoDB 文档模型、Repository、Template 文档聚合、可变属性、面向文档查询 BSON 类型、索引、文档增长、跨文档一致性
JPA/Hibernate,仅对照 实体关系、持久化上下文、查询计划 适合实体关系模型且团队熟悉其语义的应用 脏检查、加载策略、flush 时机和关联查询成本

MyBatis 常被称为 SQL Mapper 或半自动 ORM:它没有消除 SQL,而是把样板化的参数绑定与结果映射交给框架。MyBatis-Plus 在此基础上生成通用 SQL,不意味着任何复杂查询都适合改写成 Wrapper。一个几十行的清晰聚合 SQL,往往比层层嵌套的构造器更易审查。反过来,简单单表更新没必要复制几十份 XML 来维护同一套逻辑删除约定。

JPA 是规范,Hibernate 是实现之一,Spring Data JPA 是建立在 JPA 上的 Repository 抽象。它的 save、托管实体修改、flush 与数据库提交需要区分;把 MyBatis 普通对象的行为直接套到 Hibernate 会出错。关联懒加载可能导致列表中的逐项查询,序列化托管实体还可能触发意外加载。这里仅作对照,依据 Hibernate ORM 5.6.15.Final 官方手册,不为本仓库添加 Hibernate 配置或使用结论。

24.7 选型必须算上批量、分页和失败路径

N+1 是访问模式,不是某个 ORM 的专属缺陷。先查 20 个订单,再循环查每个订单的明细,就是 21 次访问;MongoDB 中循环查每个任务的项目名称同样存在。对列表页,常见方案是先按稳定顺序查一页主记录,收集其 ID,一次或分块查所有明细,再以 ID 分组组装响应。这样保留主记录分页语义,也避免直接联表分页将同一个订单的多条明细误算成多条订单。

批量也不是把输入无限堆进一个 IN。需要限制单批行数和参数数,预估报文大小,避免长事务占用连接过久。批次大小是测量结果,不是框架 API 名称决定的常量。批量插入、JDBC executeBatch、MyBatis ExecutorType.BATCH、Mongo bulkOps 各有不同失败语义,必须定义部分成功后如何重试以及业务唯一键如何去重。

分页必须考虑稳定排序。只按创建时间排序,同一时间的多条数据可能在相邻页移动;通常再加唯一 ID。深页可以改为游标条件,而不是无限增加 OFFSET。计数与列表两次查询可能观察到不同数据版本,普通管理列表可接受短暂变化,财务对账则可能需要快照或固定截止边界。框架返回 Page 并不自动提供跨语句快照保证。

事务只简述一条必要事实:同一个业务方法上的事务标记,只有在正确的事务管理器与底层资源参与时才有意义。关系库本地事务不会自动包含 MongoDB 或远程 HTTP;Mapper、连接池和驱动也不会把跨系统更新自动变成原子操作。传播和异常回滚细节请结合第 09 章,本章不重复展开。

24.8 构建、迁移、测试和可观测性也属于选型

一个框架能够生成 SQL,不代表它负责部署表结构。MyBatis XML、JPA 映射、Mongo 注解表达应用需要怎样的数据;Flyway/Liquibase 等迁移工具记录结构如何演进;代码生成器根据结构生成样板;数据库客户端用于查看和分析。这些工具处于不同阶段。不能让代码生成器覆盖定制查询,也不能让“自动建表”替代受控迁移历史。

依赖选型要核对 JDK、Boot、框架核心、Spring 适配层、数据库驱动和解析器的组合。升级 starter 时,可能同时改变 MyBatis 或 SQL 解析器,而不只是修改一个版本号。没有完整私有依赖时,可以先做源码分析,但结论必须保留“最终依赖树未验证”。第 27 章给出不会启动业务的构建检查命令和独立容器测试方案。

测试应验证框架与数据库相接的地方:绑定包含引号的文本,读取 NULL 和大整数,金额精确往返,跨时区写读,空列表不变成全表查询,分页无重复,更新版本冲突可识别。Mock Mapper 适合测试服务编排,却不能证明 XML、方言和插件重写正确。监控应能区分连接池等待、SQL 执行和结果组装耗时,同时避免把完整绑定值、连接凭据或敏感 JSON 记录到日志中。

24.9 练习与参考答案

练习一: 页面收到 ID 后先执行 Number(id),保存时又转回字符串;Java 使用 Long,数据库使用 BIGINT。数据库没有溢出,为什么仍可能更新错对象?

答案: 精度可能已经在浏览器转换时丢失。超过 JavaScript 安全整数范围的相邻整数可能变成同一个 Number,转回字符串不能恢复。应在 HTTP 契约、组件状态、表格主键和路由参数中保持字符串,并测试 9007199254740993 的完整往返。

练习二: 把一个 Spring Data Repository 改名为 TaskDao,是否意味着从 ORM 改成 JDBC?

答案: 类名不决定底层技术。应检查继承接口、扫描配置、代理工厂和实际调用。仓库中的 MongoRepository 走 MongoDB Driver;MyBatis Mapper 走 JDBC。DAO、Repository 是职责名称,不能代替调用链证据。

练习三: 一个列表返回 50 个订单及各自明细,选择“联表后 LIMIT 50”还是“主表分页后批量查明细”?

答案: 如果接口要求 50 个订单,优先先分页主表再批量取明细。联表后的 50 行可能只属于几个订单。批量明细查询仍需租户条件、数量限制、稳定组装和缺失关联处理;是否要求两次读取一致,应由该接口的业务语义决定。

练习四: POM 存在 MyBatis-Plus 3.5.5,是否可以宣布租户插件已保护全部 SQL?

答案: 不可以。先确认模块真正引入依赖,再核对使用的 SqlSessionFactory、拦截器注册与顺序、忽略策略、自定义 SQL 支持情况,最后在隔离数据库验证生成 SQL 和越权用例。依赖存在只是证据链的第一步。

原始文档 · database-course/25-MyBatis与MyBatisPlus完整实战.md

25 MyBatis 与 MyBatis-Plus 完整实战

本章从建表、依赖、Mapper 接口、XML、实体映射一路讲到分页、批量和插件测试。目标是能够写出可检查的 CRUD,并解释执行出来的 SQL 为什么符合业务条件。事务传播和 Service/Component 如何划分由第 09 章讲解;这里仅保留 MyBatis 加入事务的 API 约束。所有 course_* 表、course.* 类都是独立练习设计,不是仓库已部署的业务对象。

25.1 先选一套可控的装配方式

本章采用 Java 8、Spring Boot 2.7.3 语境,MyBatis-Plus 示例固定为 3.5.5,与 erp-admin/pom.xml 第 621 行〔本地文件〕的管理版本一致。原生 MyBatis 入门可使用适配 Boot 2.7 的 starter 2.3.x;这里的独立实验示例固定 2.3.2,而不声称仓库解析到了这个版本。官方 starter 的版本适配表说明各代 starter 对 Boot/JDK 有要求,不能给 Boot 2 项目直接换上面向 Boot 3/4 的 starter。MyBatis Spring Boot Starter 官方说明

下面的 POM 片段放在以 Boot 2.7.3 为 parent 的独立实验项目中。先用原生 MyBatis 跑通,切换 Plus 时替换 starter,不在同一个练习工程同时添加两套自动配置。数据库只能指向本地隔离容器,环境变量只表示注入位置,不提供任何业务配置值。

<dependency>
  <groupId>org.mybatis.spring.boot</groupId>
  <artifactId>mybatis-spring-boot-starter</artifactId>
  <version>2.3.2</version>
</dependency>
<dependency>
  <groupId>mysql</groupId><artifactId>mysql-connector-java</artifactId>
  <scope>runtime</scope>
</dependency>
<!-- 使用 Plus 时,以此依赖替换上面的 MyBatis starter:
<dependency>
  <groupId>com.baomidou</groupId>
  <artifactId>mybatis-plus-boot-starter</artifactId>
  <version>3.5.5</version>
</dependency>
-->
spring:
  datasource:
    url: ${COURSE_JDBC_URL}
    username: ${COURSE_DB_USER}
    password: ${COURSE_DB_PASSWORD}
mybatis:
  mapper-locations: classpath*:mapper/**/*.xml
  configuration:
    map-underscore-to-camel-case: true
    default-statement-timeout: 5

启动类加 @MapperScan("course.mapper"),XML 放到 src/main/resources/mapper/OrderMapper.xml。使用 Plus 自动配置时,把相应映射配置放到 mybatis-plus 前缀下。手工创建工厂则必须自己把配置与插件安装到实际使用的工厂;不能指望任意一个 YAML 前缀都自动生效。Plus 通用方法需要其 SQL 注入机制,手工配置时应使用 MybatisSqlSessionFactoryBean 等与 Plus 匹配的装配方式。

仓库的 MyBatisConfig 第 126 行〔本地文件〕显式创建原生 SqlSessionFactoryBean。因此,阅读这个模块时不能仅从父 POM 有 Plus 依赖就认定 BaseMapper 和全部 Plus 插件已生效。本次在 erp-admin Java 源码中未检索到 PaginationInnerInterceptor、TenantLineInnerInterceptor、OptimisticLockerInnerInterceptor 的直接注册证据;私有依赖和运行上下文尚未验证。

25.2 建表和实体要先约定空值、金额与版本

CREATE TABLE course_order (
  id BIGINT NOT NULL AUTO_INCREMENT,
  tenant_id BIGINT NOT NULL,
  order_no VARCHAR(64) NOT NULL,
  amount DECIMAL(18,2) NOT NULL,
  status VARCHAR(16) NOT NULL,
  remark VARCHAR(200) NULL,
  created_at DATETIME(3) NOT NULL,
  version INT NOT NULL DEFAULT 0,
  deleted TINYINT NOT NULL DEFAULT 0,
  PRIMARY KEY (id),
  UNIQUE KEY uk_tenant_order (tenant_id, order_no),
  KEY ix_tenant_page (tenant_id, deleted, created_at, id)
);

这个实验表选择有符号 BIGINT、两位小数金额、UTC 约定的 DATETIME,以及不可复用的租户内订单号。逻辑删除后唯一键仍保留,重新插入相同订单号应失败,这是明确的业务规则;如果希望复用,需要另行设计唯一性,不能简单假设加一个 deleted 就能无限次删除重建。

OrderDO 使用 Long、BigDecimal、String、LocalDateTime、Integer 属性,提供无参构造与 getter/setter;MyBatis 示例不依赖 Lombok。主键插入前为 null,所以不能用基本类型 long 的零值表达“尚未生成”。remark 的 null 是数据库空值;它和空字符串含义不同。version 是并发控制版本,不是展示给用户的商品版本名称。实体字段与请求可写字段分开定义,尤其不直接接收外部 tenantId、deleted 和 createdAt。

25.3 写完整的 Mapper 和 XML

下面的接口与 XML 可配套使用。OrderDO 位于 course.domain,接口位于 course.mapper;省略 import 时,@Param 来自 org.apache.ibatis.annotations。多参数必须明确命名,避免依赖编译器是否保留参数名。使用 @Param("row") 包装后,XML 也要写 row.amount,不能再写裸的 amount。

public interface OrderMapper {
    int insert(@Param("row") OrderDO row);
    OrderDO findOne(@Param("tenantId") Long tenantId, @Param("id") Long id);
    List<OrderDO> findPage(@Param("tenantId") Long tenantId,
                          @Param("status") String status,
                          @Param("offset") long offset,
                          @Param("limit") int limit);
    int updateAmount(@Param("tenantId") Long tenantId, @Param("id") Long id,
                     @Param("amount") BigDecimal amount,
                     @Param("version") int version);
    int markDeleted(@Param("tenantId") Long tenantId, @Param("id") Long id,
                    @Param("version") int version);
    List<OrderDO> findByIds(@Param("tenantId") Long tenantId,
                           @Param("ids") List<Long> ids);
}
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
  "https://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="course.mapper.OrderMapper">
  <resultMap id="orderMap" type="course.domain.OrderDO">
    <id property="id" column="id"/>
    <result property="tenantId" column="tenant_id"/>
    <result property="orderNo" column="order_no"/>
    <result property="amount" column="amount"/>
    <result property="status" column="status"/>
    <result property="remark" column="remark"/>
    <result property="createdAt" column="created_at"/>
    <result property="version" column="version"/>
    <result property="deleted" column="deleted"/>
  </resultMap>
  <sql id="columns">
    id, tenant_id, order_no, amount, status, remark, created_at, version, deleted
  </sql>
  <insert id="insert" useGeneratedKeys="true" keyProperty="row.id" keyColumn="id">
    INSERT INTO course_order
      (tenant_id, order_no, amount, status, remark, created_at, version, deleted)
    VALUES (#{row.tenantId}, #{row.orderNo}, #{row.amount}, #{row.status},
            #{row.remark,jdbcType=VARCHAR}, #{row.createdAt}, 0, 0)
  </insert>
  <select id="findOne" resultMap="orderMap">
    SELECT <include refid="columns"/> FROM course_order
    WHERE tenant_id = #{tenantId} AND id = #{id} AND deleted = 0
  </select>
  <select id="findPage" resultMap="orderMap">
    SELECT <include refid="columns"/> FROM course_order
    <where>
      tenant_id = #{tenantId} AND deleted = 0
      <if test="status != null and status != ''">AND status = #{status}</if>
    </where>
    ORDER BY created_at DESC, id DESC LIMIT #{limit} OFFSET #{offset}
  </select>
  <update id="updateAmount">
    UPDATE course_order SET amount = #{amount}, version = version + 1
    WHERE tenant_id = #{tenantId} AND id = #{id}
      AND version = #{version} AND deleted = 0
  </update>
  <update id="markDeleted">
    UPDATE course_order SET deleted = 1, version = version + 1
    WHERE tenant_id = #{tenantId} AND id = #{id}
      AND version = #{version} AND deleted = 0
  </update>
  <select id="findByIds" resultMap="orderMap">
    SELECT <include refid="columns"/> FROM course_order
    WHERE tenant_id = #{tenantId} AND deleted = 0
    <choose>
      <when test="ids != null and ids.size() > 0">
        AND id IN
        <foreach collection="ids" item="id" open="(" close=")" separator=",">
          #{id}
        </foreach>
      </when>
      <otherwise>AND 1 = 0</otherwise>
    </choose>
  </select>
</mapper>

插入返回值是受影响行数,生成的 ID 则回填到 row.id。二者不是一回事;不要把返回的 1 当订单主键。单条查询无结果返回 null;如果条件意外匹配多条,而返回类型是单个对象,可能抛出结果数量异常。列表查询无结果应按空列表处理。结果映射中 <id> 是识别对象身份的映射声明,不会替数据库创建主键。

这里显式映射全部列,因此不依赖驼峰开关。自动映射适用于简单字段,联表时最好显式起别名和指定 resultMap,尤其避免两个表都叫 id、name。association 表示一个嵌套对象,collection 表示集合;用它们做嵌套结果映射时要正确标出父子身份列,否则重复行合并可能错误。它们也可以触发嵌套查询,但列表场景容易形成 N+1。

25.4 从前端更新金额到结果判断

教学前端发送 {"amount":"19.90","version":2},路径中 ID 为字符串,Controller 将其解析为 Long。请求 DTO 包含 BigDecimal amount 和 Integer version,分别限制非空、非负、金额精度及版本非负。Java 8 的 Boot 2 项目使用 javax.validation,不要混入 Boot 3 示例的 jakarta.validation。

// 方法片段:tenantId 必须来自可信身份;amount 已完成位数/范围校验。
public void changeAmount(Long tenantId, Long id, BigDecimal amount, int version) {
    int affected = orderMapper.updateAmount(tenantId, id, amount, version);
    if (affected != 1) {
        throw new IllegalStateException("记录不可更新,请刷新后重试");
    }
}

绑定之后,数据库执行的是带租户、主键、旧版本和未删除条件的 UPDATE。成功时版本加一,返回 1;返回 0 可能是记录不存在、属于别的租户、已删除或版本过期。接口是否区分这些情况要考虑信息泄露和额外查询成本,不能把零行更新都报告为“数据库异常”。多行更新则违反单记录操作预期,应让测试和监控立即暴露问题。

普通 Mapper 调用进入 SqlSessionTemplate,再经 Executor、StatementHandler、ParameterHandler 和 TypeHandler 使用 JDBC。回程把 ResultSet 转成 DO,再由应用组装响应;修改返回的 DO 不会自动更新数据库。这条链能解释为什么 DTO 的 Jackson 注解不会改变 JDBC 参数绑定,以及为什么 SQL 正常但返回字段全为 null 时应先检查列名与映射,而不是重启连接池。

25.5 动态 SQL 的语法与安全是两件事

if 决定片段是否出现;where 负责需要时添加 WHERE,并去掉开头多余的 AND/OR;set 去掉末尾多余逗号;trim 可以自定义前后缀;choose/when/otherwise 表达互斥分支;foreach 遍历集合。它们解决 SQL 拼装,不负责业务授权。即使语法正确,缺少租户过滤仍然可能越权。MyBatis 3 动态 SQL 官方文档

<!-- 假设接口另声明 patchRemark,setRemark 表示是否修改该字段。 -->
<update id="patchRemark">
  UPDATE course_order
  <set>
    <if test="setRemark">remark = #{remark,jdbcType=VARCHAR},</if>
    version = version + 1
  </set>
  WHERE tenant_id = #{tenantId} AND id = #{id}
    AND version = #{version} AND deleted = 0
</update>

这段区分“不修改备注”和“将备注清空为 NULL”。单靠 remark != null 无法表达清空。若没有任何业务字段变化,应用应提前拒绝或返回无变化,而不是默默递增版本。if test="status != ''" 适用于字符串,不要把这个判断套到数字零或布尔 false,避免表达式类型转换带来误判。

#{value} 是值绑定,${value} 是文本替换。参数绑定不能绑定表名、列名、ASC/DESC 等结构。排序用 API 枚举在服务端选择固定片段最容易审查,例如 sort == 'amount' 时输出 amount DESC, id DESC,否则输出 created_at DESC, id DESC,不要直接 ${request.sort}。LIKE 参数应先按接口语义处理 %、_ 等通配符;参数绑定防注入,并不会把模糊查询自动变成字面匹配。

空集合必须有明确策略。上面的 findByIds 对空集合返回空结果;批量删除对空集合应直接返回零或拒绝。不能省掉 IN 条件后执行剩余 DELETE。超大集合分块时仍需每块带上完整租户和业务条件。动态表名也只能来自内部映射或白名单,不能把调用者输入作为 SQL 标识符直接拼接。

25.6 两种分页不能在同一条 SQL 上叠加

原生示例由调用者校验 pageNo/pageSize 后计算 long offset = (pageNo - 1L) * pageSize,XML 自己写 LIMIT。PageHelper 的用法则是在目标查询前开启分页,由插件改写下一条适用的查询。仓库 ReleaseNoteController 第 36 行〔本地文件〕采用 startPage(),PageUtils 第 25 行〔本地文件〕实际调用 PageHelper。

如果开启分页之后先执行了一条查字典的 SQL,这条 SQL 可能消耗分页状态,真正的列表反而没有分页。如果分支提前返回而查询没执行,还要防止线程局部状态残留;可用 try/finally 在请求内 PageHelper.clearPage()。已经有 XML LIMIT 的 SQL,不再叠加 PageHelper;使用 Plus 分页时也不要对同一 SqlSession 同时启用 PageHelper 改写。

Plus 3.5.5 的分页片段如下,前提是已经安装 PaginationInnerInterceptor。其中 pageNo 从 1 开始,pageSize 有上限,布尔条件控制是否添加状态筛选。Lambda 引用的是 Java 属性,不是客户端输入的列名。

LambdaQueryWrapper<OrderEntity> wrapper = Wrappers.lambdaQuery();
wrapper.eq(OrderEntity::getTenantId, trustedTenantId)
       .eq(status != null, OrderEntity::getStatus, status)
       .orderByDesc(OrderEntity::getCreatedAt, OrderEntity::getId);
Page<OrderEntity> page = plusMapper.selectPage(new Page<>(pageNo, pageSize), wrapper);

COUNT 也需要单独观察:联表、DISTINCT、GROUP BY 和自动删减 JOIN 都可能让计数与记录语义不一致,复杂查询可用明确的 count SQL。对大表同步可用游标分页。仓库 ErpKjDomesticIncubationMapper.xml 第 21 行〔本地文件〕按 nick、sad_type、id 续页,还区分 sad_type 的 NULL 分支,说明游标条件必须完整复现排序规则,不能只拿最后一个 ID 代替任意排序的游标。

25.7 MyBatis-Plus 的实体、CRUD 与 Wrapper

以下是独立 Plus 分支的实体片段,字段与上面的表一致,仍需普通访问器。BaseMapper<OrderEntity> 提供 insert、selectById、selectList、updateById、deleteById 等方法;通用方法不是免授权入口,按 ID 查询时仍需要保证租户隔离。

@TableName("course_order")
public class OrderEntity {
    @TableId(type = IdType.AUTO)
    private Long id;
    private Long tenantId;
    private String orderNo;
    private BigDecimal amount;
    private String status;
    private String remark;
    private LocalDateTime createdAt;
    @Version
    private Integer version;
    @TableLogic(value = "0", delval = "1")
    private Integer deleted;
    // 无参构造、getter/setter
}
public interface OrderPlusMapper extends BaseMapper<OrderEntity> {}

QueryWrapper 按字符串列名构造,LambdaQueryWrapper 按方法引用构造,后者能减少字段重命名造成的拼写问题。eq(condition, column, value) 的第一个参数表示是否加入谓词,必须确保必需的安全条件不会因为 null 而被省略。Wrapper 是可变对象,不要作为单例字段,也不要跨请求复用。

常规查询可用 .eq()、.in()、.between()、.orderByDesc();更新用 LambdaUpdateWrapper 的 .set(),其中 .set(OrderEntity::getRemark, null) 可以明确清空字段。实体更新中的 null 是否被忽略取决于字段更新策略,不能由调用方凭直觉推断。last()、apply()、inSql() 等接受 SQL 片段的 API 不应承接前端原文;Lambda 只保护字段引用的可维护性,不会把任意 SQL 片段自动变安全。

25.8 插件链:租户、乐观锁、逻辑删除、分页

下面是 Plus 3.5.5 实验配置。trustedTenantId() 是教学占位方法,要求从已认证上下文返回租户 ID,并在缺失身份时抛错;不能返回默认租户。这里仅放行 course_order,遇到未知表直接拒绝,以免教学配置在新增表后静默绕过隔离。真实项目应维护明确的租户表和公共表清单。

@Bean
public MybatisPlusInterceptor courseInterceptor() {
    MybatisPlusInterceptor chain = new MybatisPlusInterceptor();
    chain.addInnerInterceptor(new TenantLineInnerInterceptor(new TenantLineHandler() {
        @Override
        public Expression getTenantId() {
            return new LongValue(trustedTenantId());
        }
        @Override
        public String getTenantIdColumn() { return "tenant_id"; }
        @Override
        public boolean ignoreTable(String tableName) {
            if (!"course_order".equalsIgnoreCase(tableName)) {
                throw new IllegalStateException("未配置的数据表");
            }
            return false;
        }
    }));
    chain.addInnerInterceptor(new OptimisticLockerInnerInterceptor());
    PaginationInnerInterceptor page = new PaginationInnerInterceptor(DbType.MYSQL);
    page.setMaxLimit(100L);
    chain.addInnerInterceptor(page);
    return chain;
}

Expression、LongValue 来自 JSqlParser,其他类来自 MyBatis-Plus 插件包。分页放在本示例插件链最后,使分页与 COUNT 处理基于已施加的过滤。当前官方分页页注明从 3.5.9 起拆分了 mybatis-plus-jsqlparser,这是后续版本变化,不应误说成 3.5.5 必须采用的依赖结构。官方分页插件说明

租户插件通过解析 SQL 添加条件,但 SQL 是否可解析、JOIN 别名、忽略规则、插入时已有 tenant_id 如何处理,都需要验证。尤其插入实体已经包含 tenant_id 时,不能指望插件总会把错误租户值覆盖;服务端必须先设置可信租户。公共表白名单必须审查,线程上下文在异步、线程池和任务调度中也必须正确传递与清理。它只处理本工厂经插件的 SQL,不保护原生 JDBC、其他数据源或 Mongo 查询。官方租户插件说明

乐观锁要求版本字段和拦截器配套。典型流程是读取实体,保留旧 version,只修改允许字段,再调用 updateById 并检查受影响行数。不要为了让更新成功先查询最新版本并覆盖客户端旧版本,那会掩盖并发冲突。失败后直接复用已经被插件修改的实体或 Wrapper 也有风险,应重新读取并按业务决定是否重试。自定义 XML 不应假定自动获得正确版本条件,本章原生 XML 已显式写出版本比较。官方乐观锁说明

逻辑删除主要作用于 Plus 生成的相关语句:查询过滤删除标记,删除变为更新。它不是一个能替任意手写 SQL 补上条件的通用“逻辑删除拦截器”;自定义 XML 要自己确保过滤。@TableLogic 不会删除关联表,也不会解除唯一约束。删除操作是否也要求版本匹配,应明确写成条件更新并验证,不能仅看到 @Version 就认为所有删除 API 都检测版本。官方逻辑删除说明

25.9 批量与 N+1:用可计数的访问方案

为订单列表补明细时,先查一页订单,去重收集订单 ID,按受控块大小查询明细,最后用 Map<Long,List<LineDO>> 组装。主列表为空时跳过第二次查询。查询明细也必须带 tenant_id,不能认为主表已验证租户就能省掉子查询保护。关联缺失应有明确展示策略,不要在循环中悄悄回查,重新制造 N+1。

foreach 可以生成多行 VALUES,也可以构造 IN,但这与 JDBC batch 不同。前者是一条较大的 SQL,后者可能是相同 SQL 模板绑定多组参数。MyBatis ExecutorType.BATCH 会延后发送,调用 Mapper 时得到的返回值不能直接视作最终行数,要看 flush 后的批次结果和异常。flushStatements() 发送批次不等于提交事务,提交边界仍由事务资源管理。

在 Spring 中使用 BATCH 应配置专用 SqlSessionTemplate(factory, ExecutorType.BATCH) 并保证 Mapper 绑定正确;不要在一个已经绑定 SIMPLE 会话的事务中随意切换执行器类型。Plus saveBatch 的实际效果受版本、批大小、驱动与 SQL 形状影响,方法名不保证一条多行 INSERT。驱动的 rewriteBatchedStatements 是另一个层次的优化,不能替代批次幂等和失败处理设计。

仓库 广告触达 Mapper 第 58 行〔本地文件〕用 foreach 生成多行插入,并通过唯一键冲突更新累计信息;接口第 42 行〔本地文件〕明确 records、targetDate 参数名。这里的幂等来自唯一键和更新规则,不来自“批量”二字。SQL 中 VALUES(column) 属于需要按目标 MySQL 版本评估的旧写法,不能照抄后宣称适配所有版本。

25.10 与事务、缓存和测试的必要接点

MyBatis-Spring 通过 Spring 管理会话与连接,事务管理器应与 SqlSessionFactory 使用同一个 DataSource。不要对注入的 Spring SqlSession 手工 commit/rollback/close;原生 openSession() 则是另一种生命周期,不能和 Spring 管理的会话混用。MyBatis-Spring 事务文档说明了这一资源对应关系,更完整的事务规则见第 09 章。

一级缓存与会话作用域有关,并不是全局业务缓存;二级缓存需显式启用并考虑命名空间之间的失效。跨表更新、租户上下文、不同 Mapper 的关联读取都可能使缓存语义复杂。不要为了减少 SQL 数量直接启用缓存掩盖 N+1,应先把查询结构设计正确。

完整验证至少分两层:不连数据库时检查 XML 能否解析、namespace/id 是否匹配、空条件生成的 BoundSql 是否保留安全谓词;隔离 MySQL 中验证列类型、生成主键、动态 SQL、分页和真实受影响行数。测试数据包含两个租户相同订单号、同创建时间的多个订单、已删除数据、含引号的备注、空 ID 集合和过期版本。Mapper mock 不会执行这些逻辑,因此不能作为映射测试的替代。

启动失败可按路径排查:Invalid bound statement 查 XML 是否打进 JAR、namespace 与方法名;Parameter not found 查 @Param 与表达式;未知列查迁移和别名;插件不执行查实际工厂;更新零行查条件与版本。日志只展示必要的 SQL 形状和安全摘要,不能把绑定值和连接凭据完整贴进工单。

25.11 练习与参考答案

练习一: findByIds 的 ids 为空时,为什么不直接省掉 foreach?

答案: 省掉整段条件可能退化为查询全部租户内数据,若连租户条件也动态省略则更危险。应明确空集合返回空结果;示例通过 AND 1 = 0 兜底,调用层也可以提前返回空列表。删除场景必须拒绝或返回零。

练习二: 两个请求同时读到 version=7,都更新金额,怎样确定只有一个成功?

答案: 两条更新都带 WHERE version=7 并执行 version=version+1。数据库中先成功的一条将版本变为 8,后一条匹配零行;服务必须把零行解释为不可更新,测试断言成功次数为一。仅加 Java synchronized 不能替代跨实例条件更新。

练习三: Plus 的 deleteById 隐藏了记录,手写 XML 为什么还查得到?

答案: 物理记录仍存在;手写 SQL 没有自动继承所有通用 CRUD 的逻辑删除规则。检查 XML 是否包含 deleted=0,以及查询走的是哪个工厂。需要历史审计查询时应使用明确授权的专用接口,而不是随意关闭过滤。

练习四: Controller 已调用 PageHelper,随后又调用 Plus selectPage,能否获得“双重保护”?

答案: 不应叠加。两个分页机制可能重复改写 SQL、重复计数或产生不同分页语义。每条查询选择一种分页机制,针对 JOIN、页边界和总数写数据库集成测试。

练习五: 字段使用 <if test="remark != null">,为什么页面无法清空备注?

答案: null 被解释为“不更新”。应让请求表达“字段是否出现”或明确的清空动作,然后生成 remark = NULL 的绑定更新;同时拒绝空补丁和未经授权的字段,不能简单改成把所有 null 都写入数据库。

原始文档 · database-course/26-SpringDataMongoDB与Repository实战.md

26 Spring Data MongoDB与Repository实战

项目确实使用Spring Data MongoDB:TbTaskRepository〔本地文件〕继承MongoRepository,TbServiceImpl〔本地文件〕使用MongoTemplate。本章以这些代码解释框架如何生成BSON、转换对象与组织查询。教学API以项目Boot2.7/Spring Data MongoDB3.4附近版本理解,不能直接照抄最新版包名。

1. MongoRepository不是关系型ORM

它提供对象到文档映射与数据访问抽象,不经JDBC,不生成MySQL SQL。调用链是Repository代理或MongoTemplate、MappingMongoConverter、Java Driver、驱动连接池、MongoDB命令,返回BSON再映射Java对象。JPA的持久化上下文、脏检查等机制不能原样套入MongoRepository。

save(entity)与局部字段更新有重要区别:它可能按身份插入或保存整个实体对应文档,读取到的旧对象再次保存可能覆盖别人改过的字段。选择性更新应表达为$set/$inc及条件,而不是把所有表单字段套在旧实体上保存。并发保护可用版本,但必须验证API是否参与版本检查。

2. 字段映射与ObjectId

TbTask〔本地文件〕使用@Document指定集合,@Id的Java类型为String,projectId通过@Field映射到_projectId且目标类型OBJECT_ID。Java属性名、BSON字段名、JSON响应字段名是三个不同层次。

因此数据库里的ObjectId不能简单拿字符串等值查询。框架的映射查询可能按实体元数据转换,而原始Document、原生命令或不同重载未必走同一转换。项目findByIds显式把字符串转换ObjectId;如果输入不是合法格式,应在接口边界校验并返回清晰错误,避免转换异常变成系统故障。

@Document(collection = "lab_task")
public class LabTask {
    @Id
    private String id;
    @Field("tenant_id")
    private Long tenantId;
    private String status;
    @Version
    private Long version;
}

这是教学实体,需补构造与访问器。@Version不等于给任意raw update自动附加WHERE version;使用的save/update API及版本字段行为要逐项测试。金额映射也需明确Decimal128而不是字符串或double的意外转换,日期精度与UTC约定同样要验证。

3. 派生查询按Java属性解析

项目findFirstByProjectIdAndUniqueId按实体属性解析,底层字段转换后查Mongo。First限制数量,但若没有排序且存在重复匹配,不保证稳定挑哪条。若业务应唯一,建立对应复合唯一索引并清理历史重复,而不是用First隐藏异常。

教学Repository可以声明:

public interface LabTaskRepository extends MongoRepository<LabTask, String> {
    List<LabTask> findByTenantIdAndStatusOrderByIdAsc(Long tenantId, String status);
    Page<LabTask> findByTenantIdAndStatus(Long tenantId, String status, Pageable pageable);
}

Page通常需要总数查询;Slice关注是否有下一段,可能减少COUNT,但具体实现依版本和返回类型。大页码仍可能产生skip成本;高频长列表采用稳定键游标。分页必须包含租户条件,框架不会因为实体有tenantId就自动隔离。

方法名过长难以维护时转向明确的@Query或MongoTemplate。排序字段只能来自服务端白名单,不能把客户端原始BSON片段直接当查询。灵活检索API尤其要限制操作符、深度、结果量和执行预算。

4. MongoTemplate组合查询

Query query = Query.query(Criteria.where("tenantId").is(1L)
        .and("status").is("OPEN"));
query.with(Sort.by(Sort.Order.desc("id"))).limit(20);
query.fields().include("id").include("status");
List<LabTask> rows = mongoTemplate.find(query, LabTask.class);

与实体结合的映射查询可使用Java属性名,由转换器处理字段映射。只投影部分字段后得到的是部分实体,不应再将它整文档save回库,否则可能丢失未加载字段。查询DTO或显式局部更新更清楚。

项目第89—104行〔本地文件〕根据history选择集合,查ID、ancestorIds并过滤删除/归档状态。isNull语义需要结合框架生成查询与Mongo缺失/null规则,不能从Java方法名推断只匹配显式空值。

动态集合名应由服务端枚举决定,不能接受浏览器随意指定集合。当前与历史集合一起查询后在内存拼接,也要讨论分页、排序和上限,两个集合各取20不自动等于全局正确20条。

5. 原子更新与乐观竞争

Query query = Query.query(Criteria.where("tenant_id").is(1L)
        .and("sku").is("A").and("available").gte(2));
Update update = new Update().inc("available", -2).inc("reserved", 2);
UpdateResult result = mongoTemplate.updateFirst(query, update, "lab_stock");
if (result.getMatchedCount() != 1) {
    throw new IllegalStateException("stock unavailable");
}

这个重载使用集合名而无实体类型,字段按BSON名称表达,不应期待实体注解转换。updateFirst与updateMulti、replace与update、upsert与insert有不同语义。upsert在查询里包含不合适状态条件时可能尝试新插入而非更新目标,唯一约束应兜住身份,应用明确解释结果。

findAndModify可原子返回修改前或后的文档,适合领取任务或取新计数;是否返回新值由选项控制。读取后update是两个操作,不能仅因在同一个Java方法里就视为原子。

6. 聚合、数组和映射结果

Repository适合简单查询,复杂$match/$unwind/$lookup/$group可用Aggregation API或受控原始管道。先在mongosh验证语义,再映射成Java调用,避免同时调试管道和类型转换。输出字段可能是_id嵌套或计算别名,需要专门结果DTO。

数组字段两个条件可能由不同元素满足,必须在需要时使用elemMatch。@Field映射应用在哪些聚合阶段,取决于typed/untyped aggregation与版本,原始字段字符串尤其要检查。不能将SQL列名或Java字段名随意混用。

项目Service批量加载用户、标签、状态与项目再组装任务,提供了避免逐任务N+1的入口。阅读第204行附近〔本地文件〕,关注ID去重、缺失关联、内存上限和结果排序。批量读取降低往返,不保证所有集合来自同一一致快照。

7. 索引声明、事务与异常

@Indexed或@CompoundIndex是索引意图,自动创建是否启用和是否成功必须验证。唯一索引遇到历史重复会创建失败;把应用启动作为大表索引发布流程可能导致启动阻塞或失败。生产索引通常需要独立可审阅迁移与状态检查。

Mongo事务需要正确MongoTransactionManager与支持的部署。多管理器时@Transactional应选择匹配管理器,关系库事务管理器不自动管理Mongo。Reactive链路又有不同上下文传播,不能混用阻塞会话假设。

DuplicateKey、OptimisticLockingFailure、节点选择超时、写关注失败等异常需要不同业务策略。框架转换异常便于统一处理,不会消除提交未知或重试回调重复执行问题。20章给出一致性和重试边界。

8. 测试与练习

测试必须覆盖Java String与BSON ObjectId、金额Decimal128、缺失与null、数组elemMatch、部分投影后不得整文档覆盖、版本冲突和租户条件。Mock Repository只能验证调用,不能证明实际生成BSON、索引和事务。

练习一:查询无结果但数据库有ID,先查什么?比较BSON类型、字段映射、集合选择与删除条件;不要先添加全表扫描。

练习二:为什么save旧表单会覆盖同事改的备注?整文档保存与局部更新边界不同,使用版本冲突或明确定义可合并字段,不能自动删除version重试。

练习三:Repository返回Page为何两次查询?内容和总数承担不同功能,检查实际命令与COUNT成本,再决定Page、Slice或游标接口。

参考:Spring Data MongoDB 3.4参考手册、MongoRepository API。

原始文档 · database-course/27-JDBC连接池类型映射与数据库工具链.md

27 JDBC、连接池、类型映射与数据库工具链

本章将应用与数据库之间常被忽略的层连接起来:构建依赖、驱动、数据源、连接池、框架映射、事务、诊断、迁移与测试。项目同时使用MyBatis/Plus、Druid和Mongo驱动,不能以一个统一“ORM配置”解释所有路径。

1. 从POM到实际驱动

POM中dependencyManagement只管理版本,不自动引入所有依赖;starter引入传递依赖,父POM、BOM、profile和排除规则共同决定最终版本。插件版本也不自动等于运行框架版本。排障先看有效依赖树,再查对应版本文档。

在有依赖访问条件的隔离开发环境,可以执行Maven dependency:tree针对mysql-connector、mybatis、druid、mongodb-driver等筛选;effective-pom用于理解最终声明。不要因缺私有仓库权限就随意升级全部依赖。当前课程未构建业务工程,不能声称已解析所有私有starter。

JDBC是Java访问关系数据库的接口规范,MySQL Connector/J和PostgreSQL JDBC分别实现协议;Druid管理连接与统计/过滤;MyBatis负责SQL参数与结果映射。MongoDB Java Driver走自己的协议与连接池,不由Druid管理。

2. PreparedStatement真正保护哪里

String sql = "SELECT sale_id,total_amount FROM lab_sale "
        + "WHERE tenant_id=? AND status=?";
try (Connection connection = dataSource.getConnection();
     PreparedStatement statement = connection.prepareStatement(sql)) {
    statement.setLong(1, tenantId);
    statement.setString(2, status);
    statement.setQueryTimeout(3);
    try (ResultSet rows = statement.executeQuery()) {
        while (rows.next()) {
            long saleId = rows.getLong("sale_id");
            BigDecimal amount = rows.getBigDecimal("total_amount");
            consume(saleId, amount);
        }
    }
}

这是独立JDBC读取片段,tenantId由可信身份取得,consume为教学输出函数。参数绑定把数据值与语句结构分开,但不能用?绑定表名、列名或ASC/DESC。动态标识符必须经过服务端白名单;MyBatis的${}是拼接,不具备#{ }同样的数据绑定语义。

原始JDBC代码进入Spring事务时,直接getConnection不一定复用Spring绑定资源,应使用合适的JdbcTemplate或DataSourceUtils等集成方式。try-with-resources保证关闭句柄,但连接代理的close通常是归还池,不是每次关闭底层TCP。

3. 连接池容量要从占用时间算

连接是一种有限数据库并发资源。平均借用速率100次/秒、平均持有50毫秒时,稳定条件下平均占用约5条,但这不是直接建议maxActive=5。峰值、尾延迟、事务串行依赖和数据库最大安全并发都要实验决定。

连接等待、连接建立、网络读、SQL执行、事务总时长是不同超时。设置statement timeout不等于覆盖借连接等待;HTTP超时也不一定取消正在执行的SQL。外层预算应包含排队与返回开销,内部工作要有取消或最终状态查询机制。

多个应用实例每个池100条,十实例就是潜在1000条连接;增加副本部署会扩大总数据库并发,不能只看单实例配置。REQUIRES_NEW、批任务和后台导出还可能额外占用连接,容量规划需要分业务类计算。

4. 连接泄漏、失效连接与会话污染

泄漏常见于异常路径未close、自行缓存Connection、流式ResultSet未消费关闭。症状是活跃连接持续增长、等待变长而业务吞吐下降。泄漏检测提供线索,但误设极短阈值可能把正常长查询误报;不要自动终止所有长连接。

失效连接来自网络空闲回收、数据库重启等。连接验证、保活和最大生命周期要与实际网络/数据库策略匹配,过于频繁验证会增加负载。连接失败重试只在能证明业务安全时进行,写提交未知不能简单重发。

会话变量如time_zone、sql_mode、isolation若由业务动态修改,池归还是否恢复需验证。ThreadLocal租户路由与MDC也要finally清理或恢复原值,但这两类上下文不是数据库连接状态本身。

5. 类型映射是数据正确性的一部分

BIGINT映射Long后传浏览器可能超出Number安全范围,接口可采用字符串ID。DECIMAL用BigDecimal,避免先转double再构造,舍入模式在业务层明确定义。金额单位同时写进字段/契约,不让amount有时是分有时是元。

JDBC的getLong遇到SQL NULL可能返回0并需wasNull判断,包装类型映射更能保留未知语义。时间列TIMESTAMP、DATETIME与Java Instant、LocalDateTime各有不同含义,驱动连接时区不能替代业务时区约定。保存北京时间墙上时间后又当UTC输出会偏移八小时。

布尔tinyint、枚举代码、JSON、二进制字段也要定义TypeHandler或Converter。MyBatis自定义TypeHandler应处理写入、读取、NULL与异常代码;未知枚举不能悄悄映射成默认有效状态。Mongo的Decimal128/ObjectId转换参见26章。

6. 大结果流式读取与批写

fetchSize不是通用“每次只从库取这么多”的保证,行为依驱动、游标模式和自动提交设置。MySQL流式/游标路径和PostgreSQL fetch行为各有条件。必须用堆和网络观察验证,不因设置了数字就认为不会OOM。

流式结果未读完会长期占连接,消费过程中如果慢速上传文件,数据库连接也被拖住。可分页取数据、及时释放连接,再写文件;需要跨页一致性时明确水位/快照代价。不要边持有巨大ResultSet边向数据库执行无法兼容的第二条语句。

批写减少往返,但驱动rewrite批语句、MyBatis BATCH和数据库多VALUES不是同一层。错误时要检查批结果、事务是否回滚、哪些单元已提交,不能只捕获一个异常后把整文件标成功。约束冲突是否跳过必须是产品规则。

7. 工具链分别解决什么

环节 工具类别 应产出的证据
模型设计 ER图、DDL、迁移SQL 主外键、粒度、约束与数据契约
查询调试 mysql/psql/mongosh、数据库GUI 精确语句、参数类型、结果与版本
框架诊断 SQL日志、BoundSql、驱动命令监控 实际执行次数、SQL/BSON和映射
性能 EXPLAIN、慢日志、连接指标 扫描、等待、循环、资源与分位延迟
版本迁移 受控SQL、Flyway/Liquibase等 执行顺序、校验、回退边界
测试 隔离实例、Testcontainers等 真实方言、事务和并发结果
恢复 备份工具、日志与隔离恢复目标 RPO/RTO与业务校验

表中工具类别不代表项目已使用全部产品。GUI让操作方便,不能自动阻止连接错环境;连接名称、只读账号、明确库名与教学数据范围仍重要。课程实验默认不读取业务连接配置。

SQL日志应隐藏凭据和客户敏感字段,生产全量参数日志可能本身成为性能与数据泄露问题。开发环境展示占位符与脱敏参数,按trace关联到慢调用,既能调试又不必把完整请求体复制到教程。

8. 如何写有价值的集成测试

H2/SQLite可以验证一部分关系计算,但不等同MySQL的排序规则、DECIMAL、锁与优化器。Mock Mapper不能测试最终动态SQL。Testcontainers能自动管理真实数据库容器,但需要可用Docker与镜像,当前环境没有可用daemon,因此课程把实际未执行项记录出来。

测试重点放在风险:空IN不能扩大更新范围、跨租户关联被拒绝、金额类型正确、分页稳定、事务失败整体回滚、并发条件更新、Mongo数组语义与Redis错误后状态。不要只测getter/setter或框架已经保证的机械代码。

练习一:加线程池后数据库超时增加,第一步查什么?总连接并发、持有时间、排队、数据库等待,再决定限并发或优化SQL;线程更多不增加共享数据库能力。

练习二:参数都绑定了,ORDER BY仍可注入吗?若列名直接${}拼接仍可改变语句结构。用API排序枚举映射服务端固定列,绑定只用于值。

练习三:测试库通过线上失败?比较服务端、驱动、sql_mode、字符集排序规则、时区、事务级别和实际DDL;“都是MySQL”不足以证明环境一致。

官方参考:JDBC基础、Connector/J配置、PostgreSQL JDBC查询、Druid源码。

原始文档 · database-course/开发陷阱深化.md

数据库开发陷阱深化:从“SQL 能跑”到“修改范围可证明”

本篇是第二轮补缺,面向已经会写 Mapper、做列表和批量导入的前端转 Java ERP 开发者。先修是 MyBatis 与 MyBatis-Plus、JOIN 与分页和 JDBC 工具链。不重列注解、SQL 语法和索引分类,而是沿真实库存、用户权限、广告汇总代码,推演“输入变了以后,数据库究竟操作哪些行”。

本文的源码事实只指本次读到的代码;条件风险必须满足列出的调用或数据条件才会出现,不是线上事故结论;改进设计均为教学建议,未修改业务;验证区分已经执行的无服务实验与仍待执行的 MySQL、插件及业务集成检查。项目中的 user_id 保留原名,只有教学表使用 tenant_id,不假定所有系统的用户编号都等于租户身份。

离线实验固定 MyBatis 3.5.13、Spring 5.3.39、H2 2.2.224;它们是本实验版本,不代表各模块最终解析的依赖或生产版本。MySQL 机制按官方 8.4 手册核对,不能据此宣布生产采用 8.4。本文未读取业务 YAML、环境变量值、连接串或秘密配置,未启动 ERP 或连接外部数据库。审阅范围和缺口状态见 闭环记录。

1. 空集合的三种结果:条件消失、语法错误、明确不匹配

源码事实。 SysSkuStorageStockMapper.xml#L116〔本地文件〕 的 deleteByExample 只在参数非空时包含 Example_Where_Clause;条件片段#L22〔本地文件〕 遍历 oredCriteria,仅输出有效组。Example#L125〔本地文件〕 的有效性定义是组内条件数大于零。因此 null、未添加组的 Example、只有无效组的 Example,均可能没有任何条件正文。<where> 的职责是有正文才添加 WHERE,不是补一条安全条件。MyBatis 动态 SQL 官方说明

条件风险。 如果上述对象直接到达 Mapper,原始 BoundSql 会是 delete from sys_sku_storage_stock。但不能据此宣布业务会全库删除:还没有证明某个入口确实传空、SQL 是否经过额外插件以及分片最终落到哪些物理表。可以确认的是,该 Mapper 自身没有拒绝空条件的闭合保证。updateByExampleSelective#L240〔本地文件〕 也有相同 WHERE 结构;只设置 enableStatus 并提供空 Example,同样会生成无 WHERE 更新。

另一个容易误判的分支是空 IN。andSysSkuIdIn#L378〔本地文件〕 调用的 addCriterion 在 #L144〔本地文件〕 检查 null,没有拒绝空 List。空 List 条件仍然存在,而 foreach 没有元素,结果可能留下 sys_sku_id in,属于不完整 SQL。真实的 deleteUserByIds#L250〔本地文件〕 也会在空数组下留下 where user_id in。这与“外层 if 连同 IN 一起删掉”是不同故障,不能都叫全表更新。

改进设计。 把前端的“未选择任何行”和“选择全部筛选结果”拆成不同命令。批删除入口应要求可信身份、非空去重 ID、受限数量;全选要带受控筛选版本或任务身份。Mapper 再保留拒绝匹配分支,而不是依赖按钮状态:

<!-- 教学片段:tenant 由后端身份解析,不来自请求任意字段。 -->
DELETE FROM lab_order WHERE tenant_id = #{tenant}
<choose>
  <when test="ids != null and ids.size() > 0">
    AND id IN
    <foreach collection="ids" item="id" open="(" close=")" separator=",">#{id}</foreach>
  </when>
  <otherwise>AND 1 = 0</otherwise>
</choose>

验证。 SqlShapeChecks.java〔本地文件〕 已从上述两个真实 XML 提取指定节点、展开其 include,用 MyBatis 生成 BoundSql;验证了空 Example 无 WHERE、空 IN 留下不完整谓词、教学防线保留 1=0。没有执行任何真实 Mapper SQL。实验以 Map 模拟属性结构,没有加载生产 DO、Mapper 接口、插件或分片配置,因而不是完整生产映射测试。

练习与答案。 前端传入 [null] 是否等同空列表?不是,长度为一仍可进入 IN;SQL 中 NULL 参与匹配也不是“全部”。入口应拒绝非法 ID,再对清洗后的集合重新判断非空,不能先判断长度、过滤后直接调用 Mapper。

2. CASE 批更新:限定范围之外,还要证明“这一批是什么”

源码事实。 batchUpdateStorageStock#L405〔本地文件〕 在 CASE 分支比较 user_id + sys_sku_id + storage_id,在 #L465〔本地文件〕 用首条的 userId 限定整个 UPDATE,再用 (sys_sku_id, storage_id) IN (...) 限定键对。这不是无 WHERE 更新。库存调用点 #L6363〔本地文件〕 对非空更新列表分为每块五十条;查询辅助方法 #L6061〔本地文件〕 也会对空 SKU 集合直接返回。这些现有防线必须保留在分析中。

条件风险。 该 SQL 隐含整批属于首条用户。如果某个新增调用混入其他用户,后续用户的 CASE 分支可能永远匹配不到;而其键对仍进入首条用户的 WHERE 集合。若首条用户恰好存在同键库存,CASE 的 ELSE 保持库存,却仍可能更新公共 gmt_modified。所以风险不应粗略描述为“必然把另一用户的库存加到当前用户”,更准确的是遗漏、额外触及行,以及不可靠的成功统计。空列表访问 list[0] 还可能在参数求值阶段失败,应提前拒绝。

重复键是另一种问题:同一用户、SKU、仓库出现两条增量 +2、+3,CASE 取首个匹配分支,不会因为 WHEN 写了两遍就累计为 +5。库存聚合#L1442〔本地文件〕 已对部分 SKU 增量做汇总,这说明代码作者意识到了这一类问题;不能脱离调用路径认定重复问题已实际发生。另需注意“增量”和“覆盖值”的冲突规则不同,残次品覆盖值不能照搬求和。

改进设计。 批次在服务边界固定一个可信用户,所有条目必须同属此身份;合并键使用完整的用户、SKU、仓库三元组。对可加字段求和,对覆盖字段拒绝冲突或采用明确版本策略。WHERE 中保留成对的复合键,不改成两个独立 IN:输入 (SKU1,仓1)、(SKU2,仓2) 时,独立 IN 会扩大为四种组合。SQL 参数个数、报文长度和事务时长决定批大小,不能把“五十”误认为所有数据分布下都最佳。

验证。 离线 H2 已验证相同 CASE 条件取首个分支,不验证真实库存结果。待执行的目标 MySQL 用例应包含混用户、重复三元组、交叉仓库、全 null 增量、零增量及缺失基准行,比较“目标键集合、实际触及键集合、库存差值”,而不是只断言调用未抛异常。还要单独查看真实唯一键,不能从 Mapper 名称推出数据库必有三元组唯一约束。

练习与答案。 更新条目十条,影响行数十,能证明十次库存增量均生效吗?不能。存在重复输入、覆盖、零增量、无匹配分支但更新时间变化等情况。应先定义合并后的唯一目标和每键预期差值,再选择行数或结果对账作为证据。

3. 动态权限不是租户隔离:OR 的每个分支都要受约束

源码事实。 生成式库存 Example 条件#L25〔本地文件〕 用 OR 连接组,组内用 AND;${criterion.condition} 输出结构,值则使用 #{criterion.value}。andUserIdEqualTo#L228〔本地文件〕 生成固定字符串 user_id =。因此发现 ${} 不能直接认定来自请求的注入:必须追踪结构字符串的来源。

管理端 selectAllocatedList#L116〔本地文件〕 另插入 ${params.dataScope}。DataScopeAspect#L58〔本地文件〕 清空旧内容后处理权限,#L151〔本地文件〕 在首参数是 BaseEntity 时写回带括号的片段。这是组织数据权限的实现线索,不等于库存分片用户隔离或通用租户插件。两个项目的身份模型不能相互替代。

条件风险。 组合 (user_id=7 AND sku_id=1) OR sku_id=2 时,第二组已经不受用户条件限制。即使每个值都参数绑定、没有 SQL 注入,授权范围依旧扩大。另一类风险发生于新增 Mapper 旁路:它未经过负责填充权限的代理入口,却仍沿用可空 dataScope。是否可由外部触发、调用前是否另有鉴权,本次没有全链核验。

改进设计。 明确不可省略的身份条件与可选检索条件,结构应为 user_id=? AND (条件A OR 条件B)。若只能使用 Example 的 OR 组,则每组重复强制身份谓词;更稳妥的是封装专用 Repository 方法,禁止上层传任意 Example。动态排序、表名和权限片段采用后端枚举或受控构造器,不直接暴露 ${...} 参数。分片选中了一个库仍可能包含多个用户,所以路由正确不代表行级授权正确。参数绑定与文本替换的边界见 MyBatis Mapper XML 官方资料。

验证。 本次完成结构阅读,未验证真实鉴权、插件链与数据路由。待执行用例应在隔离数据集中安排两个用户有相同本地 SKU 编号,分别走 Controller、后台任务、直接 Repository 入口;记录脱敏 SQL 形状和返回身份集合。断言必须是“只有被授权用户的键”,而不只是“出现了 user_id 字样”。练习答案:给 WHERE 随便加一个用户条件并不充分,必须检查它的括号作用范围。

4. COUNT、LIMIT、对象去重:三个阶段的计量单位不同

源码事实。 SysUserResult#L7〔本地文件〕 用 user_id 标识父对象,用 collection 收集角色;selectUserVo#L49〔本地文件〕 连用户、用户角色关系和角色表。与此同时,selectUserList#L59〔本地文件〕 实际只联部门,不能把详情查询的一对多风险硬套给这个列表。分配角色列表 #L102〔本地文件〕 使用 DISTINCT,也需要按实际投影判断去重对象。

条件风险。 若将详情联表 SQL 直接用于分页,父 A 有两条子行、父 B 有一条:COUNT(*) 得到三条,LIMIT 2 拿到 A 的两条,MyBatis 再组装成一个父对象。前端看见 pageSize=2、rows.length=1、total=3,不是分页组件算错,而是服务端先按 SQL 行切页、后按父对象合并。把 COUNT 改成 DISTINCT 父 ID 只能修总数,不能修 LIMIT 已切断的对象;把整个投影 DISTINCT 后带上不同角色列,重复父仍然存在。

改进设计。 首先明确界面一行是订单、订单明细还是用户。父对象分页分两步:在同一身份与筛选条件下分页选择父键,再按这页父键取全部子项;最终按父键原顺序组装。若筛选要求“有某角色或有某类订单明细”,主查询用 EXISTS,COUNT 也复用相同存在性条件。排序追加唯一尾键。子查询要保留身份条件;只依赖第一页已校验身份,会让后续重用方法变脆弱。

还有时间语义:COUNT 和明细是两条查询,在并发写入下可能观察到不同状态。界面容忍轻微变化时约定 total 是当次估计性展示;导出或对账要求同一批快照时,设计一致性边界、截止时间或已固化的父键任务,不能靠“两个查询相邻”来证明同一快照。PageHelper 入口见 PageUtils#L18〔本地文件〕,插件配置与下一次查询的使用约束参见 官方用法。这里没有断言自动 COUNT 在当前安装版本会采用某一种改写。

验证。 离线关系实验已断言联表行数三、父数二、前两条联表记录只含一个父。它验证关系基数,没有启用 PageHelper,也没有验证 collection 的完整装配。待执行插件集成测试应同时断言生成 COUNT、分页 SQL、父对象数量、每个父的完整子集合,覆盖无子项、重复关系、同排序值以及权限过滤。

练习与答案。 前端对响应 rows 去重可以修复吗?不可以,被 LIMIT 排除的父或子行没有传过来,去重无法补回。应修服务端分页粒度。

5. 批执行异常:调用返回、flush、commit 是三个时点

源码事实。 分仓库存插入#L385〔本地文件〕 是 foreach 生成一条多 VALUES SQL;库存事务#L1427〔本地文件〕 循环执行分块更新。仅凭 batch 命名或 foreach,不能说该路径配置了 ExecutorType.BATCH。本节后半用独立 BATCH 实验解释若将来切换执行器,会新增哪些判断责任。

条件风险与机制。 MyBatis 3.5.13 的 BatchExecutor 官方源码 在 update 时返回占位值,flush 才取 JDBC 批结果。也可能在执行查询前刷新已排队批次,因此“查询方法抛插入唯一键错误”并不矛盾;检查的是之前加入队列的语句。即便 flush 成功,事务仍可能在随后操作失败时整体回滚。提前记录“已入库一千条”会误导导入状态。

JDBC 返回数组不是永远由正数组成:SUCCESS_NO_INFO 表示执行成功但未知精确行数;EXECUTE_FAILED 表示对应命令失败。批次出错时驱动可停止,也可继续处理剩余命令,数组长度及内容要按实际驱动解释,不能假设“异常前的 N 条已经持久成功”。依据见 Java 8 BatchUpdateException。

改进设计。 原子批次在一个事务内完成,失败向外传播并回滚;允许部分成功的导入则显式划分子事务和每块幂等键,分别记录已提交、拒绝、待重试。保存异常中的批次序号、有限错误码、对应输入索引,不保存完整 SQL 参数。动态更新字段不同会产生不同 SQL 模板、拆开批组;不能假设每个 BatchResult 与一条输入一一对应。真正成功状态应在提交结果确定后记录,提交响应丢失则进入查询或对账流程。

验证。 独立 MyBatis/H2 实验已检查占位返回值、flush 后另一个连接仍看不到未提交行,以及重复主键在 flush 报错后显式 rollback 留零行。这不是 MySQL 驱动继续执行策略的证据。rewriteBatchedStatements、真实驱动版本、批异常计数、生成键与事务失败路径仍待目标环境验证;官方还特别说明重写的批 upsert 可能无法把服务端总数精确分摊回各条命令。Connector/J 批重写说明

练习与答案。 捕获 flush 异常后返回成功列表,等待 Spring 自动发现失败,可以吗?不可以。必须保留失败的事务语义;异常已被吞掉时,外层代理可能只看到正常返回。事务是否已经被标记 rollback-only 也要另查,参见 Spring 深化篇。

6. 影响行数、INSERT IGNORE 与幂等:三个“成功”不能互换

源码事实。 库存基准行使用 INSERT IGNORE;补偿任务 insertIgnore#L4〔本地文件〕 也采用此形式。广告触达 upsert#L82〔本地文件〕 则在冲突时合并最早、最晚日期,并更新更新时间。源码展示了写入策略,不展示实际部署的全部索引、sql_mode 或连接属性,本次不据注释认定唯一约束已上线。

条件风险。 upsert 返回值并不等于“成功导入用户数”:按 MySQL 规则,单条新增通常计一,改变旧行计二,不改变旧值计零;连接的 found-rows 行为可能改变无变化计数。这个 SQL 还写入 updated_at,因此即使业务日期已达到目标,第二次也未必是零。应按“业务字段幂等”和“行完全未变化”分别判断。MySQL upsert 行数规则

IGNORE 也不是“只忽略本次请求重放”的专用关键字。某些本应报错的数据问题可能变为警告或被调整;哪些错误可忽略取决于语句与服务器规则。把“没有抛异常”当作“正确记录已存在”,会吞掉与幂等无关的问题。MySQL INSERT 与 IGNORE

改进设计。 对重要业务记录,优先普通 INSERT 捕获明确的唯一键冲突,再用可信身份与操作键读回原记录并核对请求摘要。同键不同意图应报冲突,不能返回旧请求成功。库存基准初始化若保留 IGNORE,应在后续写前验证目标行存在、身份匹配,且监测预期外警告。普通条件 UPDATE 的零行可代表不存在、版本冲突或无需变化;需要稳定检测成功时,采用版本递增等有业务意义的变化,并确认驱动报告口径。

验证。 本节已静态核对 SQL,并核对官方行数/IGNORE 文档;没有执行 MySQL upsert。待执行时用同一隔离表测试“新建、相同重放、业务字段改变、错误长度、不同唯一键冲突”,记录请求数、合并后实体数、JDBC 行数及警告,分别开关相关驱动选项。不要把任意两个返回数恰好相等当作普遍合同。

练习与答案。 十条 upsert 返回十五,是否有五条重复执行?不能这样推断;可能五条新增、五条更新,也可能有其他组合与连接语义。API 要展示实体处理结果,应依据业务键和明确操作结果统计。

7. 唯一键加逻辑删除:删除第二次时才暴露的设计错误

源码事实。 checkUserNameUnique#L169〔本地文件〕 只查 del_flag='0';deleteUserById#L246〔本地文件〕 把标记改成 '2'。因此应用层查重关注当前有效用户,物理行仍保留。这里没有核验部署表结构,不声称存在或缺失某个唯一索引。下面借这一需求讨论教学订单号的数据库设计,不给系统用户表直接提出迁移脚本。

条件风险。 UNIQUE(tenant_id, order_no) 表达终身不复用;加上二值 deleted 得到 UNIQUE(tenant_id, order_no, deleted),只允许一条有效记录和一条相同编号的已删记录。时间线是:创建 A、删 A、创建 B、删 B;第四步要把 B 改成与 A 相同的三元键,于是冲突。简单演示一次删除重建会漏掉这个问题。

另一个常见错误是 UNIQUE(tenant_id, order_no, deleted_at),有效记录的 deleted_at 为 NULL。MySQL 可空唯一索引允许多个 NULL,因此两个同时有效的同编号订单也可能都插入成功。NULL 不能直接充当“所有有效行共有的唯一值”。这正是 MySQL UNIQUE 索引规则 在业务建模上的影响。

改进设计。 先决定编号是否允许复用。单据审计通常可以选择终身唯一;若业务明确只要求“有效记录唯一”,可在 MySQL 8.4 教学表上增加生成列,让有效行统一映射为非空值,已删行映射 NULL:

-- 仅供独立教学库;本轮未运行 MySQL。
CREATE TABLE lab_active_order (
  id BIGINT PRIMARY KEY,
  tenant_id BIGINT NOT NULL,
  order_no VARCHAR(40) NOT NULL,
  deleted TINYINT NOT NULL DEFAULT 0,
  active_slot TINYINT GENERATED ALWAYS AS
    (CASE WHEN deleted = 0 THEN 1 ELSE NULL END) STORED,
  UNIQUE KEY uk_active (tenant_id, order_no, active_slot)
);

这样同租户同编号的有效行争抢 active_slot=1,已删除历史行可共存。生成列规则依版本核对 官方说明。它仍没有解决恢复策略:恢复历史订单可能与当前有效单冲突;引用应指向不可变主键,不能只保存可复用订单号;字符比较规则也必须与产品的大小写语义一致。若换用删除序列作为唯一键部分,也要保证序列唯一,秒级时间戳不天然唯一。

验证。 该设计是待执行 MySQL 方案,没有拿 H2 成功替代它。最小验收包含连续两轮删除重建、两个连接并发创建有效行、恢复历史行冲突、跨租户同编号、大小写差异、NULL 编号被 NOT NULL 拒绝。已有重复数据如何清理、加索引的锁与回滚安排是另一个迁移任务,本次没有执行。

练习与答案。 页面先查询“编号可用”后保存,是否可以不建唯一约束?不可以。两个请求都可能查到可用;数据库约束决定最终只有一个有效记录胜出。服务应把具体唯一键冲突翻译成业务提示,而不是无限重试。

8. 怎样复跑,以及哪些结论还没有证据

在工作区执行以下命令,使用本机已有缓存 JAR 和内存数据库;缺依赖直接退出,不触发下载,不运行 Maven,不读取业务配置。需要 JDK 11 或更高以支持 --release 8,生成物放临时目录并在结束时清理。

python3 spring-course/labs/pitfalls/run.py

本轮结果:数据库侧九组检查通过,Spring 侧八组检查通过。数据库实验覆盖四组真实 XML 形状、一组教学空集合防线、两组关系/CASE 机制和两组 BATCH 机制。SQL 形状实验没有访问数据库;关系与批执行只访问进程内 H2,不连接服务。实验入口和限制也可直接阅读 run.py〔本地文件〕。

仍待执行:真实 Mapper 参数对象与插件装配、MySQL 唯一键/NULL/IGNORE/upsert、驱动批重写、分片落点、权限旁路、COUNT 改写与生产数据分布下的锁范围。本文提供的可操作断言不是完成这些验证的替代。做完一项练习时,应同时写出“这次数据证明了什么”和“还不能证明什么”,才能把知识真正转成 ERP 变更的审核能力。

原始文档 · database-course/补充阅读.md

数据库课程补充阅读:Java基础与工程边界

本页是新增的跨课程入口,保留原28章内容与学习顺序,不修改原README或验证器。数据库知识需要与语言、授权和交付能力结合:SQL正确并不自动证明金额在进入SQL前没有丢精度,事务成功也不证明调用者有权操作该行。

遇到的问题 对应补充
不清楚当前目录有哪些后端项目,版本证据是什么 00 全目录技术栈证据与课程能力地图
List、泛型、异常与连接关闭难以理解 01 Java语言集合泛型异常资源管理与前端迁移
金额、时间与数据库类型对应不上 02 Java工程分层领域建模金额时间编码规范
参数化SQL之外还需要哪些安全边界 03 数据库访问安全权限注入凭据与迁移规范
如何把源码风险写成可验证的评审 04 项目反例与安全编码评审

完整入口:后端基础README、审阅与知识缺口。后续专题入口:分布式README、高并发README、运维README。后三个专题由并行任务交付,本页链接不代表已经验证其全部内容。

建议先用基础课明确类型与可信身份,再回到数据库课的事务、索引和迁移实验。源码阅读只证明实现形态;新补充没有连接业务数据库,也不改变旧课验证记录中的实测范围。

原始文档 · database-course/验证记录.md

数据库课程验证记录

日期:2026-11-10。编写依据是当前工作区源码与各章链接的官方资料,不是生产审计或线上性能测试。

本次实际结果

28章正文齐全,另有总目录、4组实验说明与本记录。静态检查155个本地链接及49处带行号引用,零错误;20条SQLite关系结果与3项约束拒绝通过;隔离Redis30项断言通过;两份Mongo脚本通过Node语法检查,但未在Mongo服务器运行。

离线HTML包含34份文档、18张表格、144个代码块。HTML内部锚点检查无缺失;已在浏览器打开并检查桌面排版、章节筛选、内部跳转,无页面级水平溢出。浏览器全文查找使用原生⌘F/Ctrl+F。未进行完整移动端与打印分页视觉审校。

验证类别

  1. validate.py检查00—27共28章存在、Markdown围栏、本地链接和源码行号范围,并解析Python脚本语法。路径存在不证明引用语义永远正确,源码变化后需要重新阅读。
  2. labs/mysql/verify_relational.py将本专题DDL的可移植部分转换为SQLite,在内存检查20条关系查询结果和3项约束拒绝。它不验证MySQL DDL、DECIMAL、排序规则、优化器、事务或InnoDB锁。
  3. labs/redis/verify.py启动临时Unix socket Redis、禁用TCP与持久化,检查30项命令、锁所有权、错误语义和版本下界回填,最后自动清理。不使用项目Redis配置。
  4. MongoDB脚本可进行JavaScript语法检查,真实BSON、聚合计划和事务必须在MongoDB执行,不能用普通Node运行代替。
  5. build_reader.py将正文和实验说明生成离线HTML,阅读不需要网络资源;本地链接与原始Markdown一起保留。

环境边界

当前机器未发现mysql或mongosh命令,Docker客户端存在但daemon不可用。因此MySQL双会话/崩溃/复制恢复和MongoDB服务器断言未执行,文内结果是明确前提下的预期或推导。没有连接业务数据库,没有运行ERP应用、私有依赖构建或集成测试。

数据库实操以各实验README版本为准:主要关系/事务实验MySQL8.4,MongoDB8.0/mongosh2.x,Redis基础命令以7.x能力理解;22章单独标出MySQL8.0.18+示例。项目实际服务端版本不能由客户端依赖倒推。

复验命令

python3 validate.py
python3 labs/mysql/verify_relational.py
python3 labs/redis/verify.py
node --check labs/mongodb/init.js
node --check labs/mongodb/queries.js

运行数据库实验后另附服务端版本、镜像digest、DDL/索引、实际输出与未覆盖场景。只有命令已执行且结果符合预期,才能把该项记为实测通过。性能结果必须注明规模和分布,不使用虚构QPS或固定提速倍数。

原始文档 · database-course/labs/mongodb/README.md

MongoDB实验室

服务端MongoDB8.0、mongosh2.x。init.js只接受lab_erp_mongodb库且要求LAB_RESET=1,重置白名单教学集合。queries.js普通模式验证类型、数组、聚合、索引、版本更新与唯一性;LAB_RUN_TRANSACTIONS=1额外验证跨文档事务。不得对项目Mongo连接运行这些脚本。

独立单节点副本集

在Docker可用环境执行。这个单节点副本集用于事务教学,不提供高可用和故障容忍。镜像实际补丁与digest应记录。

docker run --name db-course-mongo --network none -d mongo:8.0 \
  mongod --replSet labrs --bind_ip 127.0.0.1
docker exec db-course-mongo mongosh --quiet --eval 'db.adminCommand({ping:1})'
docker exec db-course-mongo mongosh --quiet --eval 'rs.initiate({_id:"labrs",members:[{_id:0,host:"localhost:27017"}]})'
docker exec db-course-mongo mongosh --quiet --eval 'db.hello().isWritablePrimary'

先等ping成功再初始化副本集,再等最后一条输出true。不要重复rs.initiate冒充等待。然后从本实验目录复制脚本,并在容器内运行:

docker cp init.js db-course-mongo:/tmp/course-init.js
docker cp queries.js db-course-mongo:/tmp/course-queries.js
docker exec -e LAB_RESET=1 db-course-mongo mongosh --quiet \
  'mongodb://localhost:27017/lab_erp_mongodb?replicaSet=labrs' --file /tmp/course-init.js
docker exec db-course-mongo mongosh --quiet \
  'mongodb://localhost:27017/lab_erp_mongodb?replicaSet=labrs' --file /tmp/course-queries.js
docker exec -e LAB_RUN_TRANSACTIONS=1 db-course-mongo mongosh --quiet \
  'mongodb://localhost:27017/lab_erp_mongodb?replicaSet=labrs' --file /tmp/course-queries.js

脚本输出PASS是当次断言结果;先前文中预期数字不代表已经运行。普通模式会重置lab_crud并创建教学索引,事务模式重置lab_stock/lab_reservations,所以不要在这些集合保留自己的其他数据。

预期与边界

初始化五订单;字符串_id不能匹配ObjectId。note:null匹配4条,显式BSON null为1条。同数组元素筛选只返回O1002。聚合SKU A七件139.30,B五件30.00。$facet总数3,首屏O1004/O1002。版本旧写匹配零条,重复请求键报11000,错误租户类型报121。

事务注入异常后库存5/0、预留0;正常提交后3/2、预留1;同请求再调用保持不变。此测试不覆盖并发重复、网络分区、选举、提交未知和跨分片事务,不是生产重试实现。

完成后仅清理专用容器docker rm -f db-course-mongo。本次交付机器没有mongosh和可用Docker daemon,因此只做脚本语法与静态审查,Mongo服务器断言未执行。

原始文档 · database-course/labs/mysql/README.md

MySQL查询实验室

服务端基线MySQL8.4/InnoDB,脚本自包含,不依赖旧手册。先读01—05章。只有独立教学库可执行初始化;schema.sql不删除旧表,重复运行会报同名表,重置推荐新建空库,不清理未知数据库。

初始化与运行

若本机Docker可用,可启动不开放端口的专用容器。以下空口令仅用于无网络的一次性容器,不用于其他环境。

docker run --name db-course-mysql --network none \
  -e MYSQL_ALLOW_EMPTY_PASSWORD=yes -d mysql:8.4
docker exec db-course-mysql mysqladmin -uroot ping
docker exec db-course-mysql mysql -uroot -e 'CREATE DATABASE lab_database_course CHARACTER SET utf8mb4'
docker exec -i db-course-mysql mysql -uroot lab_database_course < schema.sql
docker exec -i db-course-mysql mysql -uroot lab_database_course < seed.sql
docker exec -i db-course-mysql mysql -uroot lab_database_course < queries.sql

先等ping成功再执行后续命令。命令从本实验目录运行,容器名冲突时先确认用途。没有Docker时,在自己安装的独立MySQL实例创建同名空库,以本地练习账号导入,不读取项目连接配置。

结果检查

Q01为4/2/2。Q02第一条无结果,第二条1003/1004。Q03客户501两单240均值120。Q04三客户为501/2/240、502/0/0、503/0/0。Q05故意错误:订单1001被连接成4行,商品与收款均错误放大为240。Q06修正后1001与1002各120/120/0,1003为50/0/50。Q07普通SUM240而DISTINCT120。

Q08标签任意命中101/102,Q09全部命中101。Q10无标签104、无有效标签103/104。Q11错误NOT IN无行,正确反关联503。Q12累计120/240/290/320。Q13每客户最新501/1002、502/1004。Q14两张已付目标订单各120/120。Q15正常种子无对账异常。Q16游标1002/1001。Q19三日120/120/0。

Q17、18、20用于计划比较,没有预设必须命中哪个索引或必须多少毫秒的答案。Q20实际执行SELECT;小表可能全表扫描,05章提供十万行独立性能数据生成步骤。

约束与清理

单独尝试重复lab_item_tag关系、引用不存在客户、负商品价格,应分别被约束拒绝。确认错误后检查数据未被意外修改,勿把预期失败混入一次初始化而误判后续步骤已执行。事务与锁请转到事务实验室,它有独立表结构。

完成后只清理自己刚创建的容器:docker rm -f db-course-mysql。不执行批量容器删除或业务库DROP。服务端版本、实际结果和未通过项记录到个人实验日志。

本次交付未运行MySQL服务器;配套verify_relational.py只在SQLite内存验证部分关系结果,不验证MySQL语法、精度、优化器与锁。

原始文档 · database-course/labs/redis/README.md

Redis实验室

先读14—17章。这里包含可重复自动检查:String/Hash/Set、锁所有权、租约过期、MULTI运行时错误与Lua错误不回滚。脚本启动新的临时Redis,关闭TCP与持久化,仅使用临时Unix socket,结束后终止实例并清理目录。

python3 verify.py

需要本机redis-server、redis-cli和Python3。脚本不使用项目配置、不连接默认6379、不执行FLUSHALL。30项断言通过才返回成功;Redis错误响应可能仍使CLI退出0,因此同时检查响应和最终状态。

版本下界回填实验

cache_publish.lua参数为两个键(缓存Hash、版本下界String)以及version、payload、TTL毫秒;invalidate.lua参数为同样两个键和已提交version。版本限制为1至十亿的整数,TTL为1至86400000毫秒;两个键必须不同且在Cluster中同槽。下界不设置TTL,仅供教学,生产需要独立设计生命周期和故障恢复。

脚本拒绝低于floor或现存缓存版本的回填。失效事件提高floor,删除低版本缓存;相同或更高版本的缓存保留,迟到低版本事件不降低floor。实验用Python字典表示数据库已提交值,用真实Redis验证旧读取回填被拒绝。最后故意丢失floor,证明旧值又能回填,说明协议成立条件。

手工实验可在自己启动的独立实例里运行14章命令。务必采用course:前缀,并为个人实验记录键名、输入、结果和清理方法。持久化实验另建明确的数据目录;不能把临时无持久化实例的成功结果当作RDB/AOF恢复已验证。

双客户端WATCH实验

A执行WATCH course:balance,GET读取10;B执行INCRBY course:balance 1;A在同一连接执行MULTI、SET course:balance 8、EXEC,预期事务因监视键变化而放弃,最终仍11。WATCH与EXEC必须同连接,多个独立redis-cli进程不能拼成一个会话。

锁实验解释

脚本用owner-A、owner-B作为可读教学token,生产应使用足够唯一的每次持有身份。释放脚本在同一原子执行内GET比较ARGV后DEL。A过期、B获取后,A释放应返回0且B仍持有锁。这个结果只证明所有权检查,不能阻止A继续执行数据库写入。

扩展练习

  1. 建立Stream消费者组,读消息不ACK,检查pending,再在另一消费者重领;记录业务效果何时提交。只在明确版本支持相应命令时使用XAUTOCLAIM。
  2. 另建专用持久化实例,分别验证RDB快照前后写入与AOF恢复,记录配置与故障类型。进程kill不等同机器掉电。
  3. 三个副本或Cluster需要独立拓扑实验;当前自动检查未覆盖复制、选举、网络分区、槽迁移和watchdog,不报告这些项目已通过。
原始文档 · database-course/labs/transactions/README.md

事务实验室:从崩溃恢复到库存并发

本专题独立服务于 第06章、第07章、第08章 和 第09章。不依赖旧手册,不读取项目配置,不启动 ERP 应用,不连接业务服务。所有业务示例固定 tenant_id=1,所有表以 lab_ 开头。

边界声明:SQL 和时序是教学设计;下面的数字是按照给定前提推导的预期结果,不是本次实际运行日志。本次编写只做文档静态验证,未运行 Docker、MySQL、Java 集成测试或崩溃注入。MySQL 8.4 是实验基线,不代表业务数据库版本;实际练习必须记录 SELECT VERSION()。官方依据见各章相邻引用。

0. 建立完全独立的环境

若已有专用练习实例,可以使用它,但不要复制业务项目中的 JDBC 地址。下面提供一个可选的本机 Docker 方案:无宿主端口、无业务网络、无宿主目录挂载;空口令只用于这个网络隔离的一次性容器。容器名称必须属于本实验;名称冲突时先检查用途,不要自动删除同名容器。镜像 8.4 会随补丁更新,严格复现应另记镜像 digest 和实际服务版本。

docker run --name db-course-transactions --network none \
  -e MYSQL_ALLOW_EMPTY_PASSWORD=yes -d mysql:8.4 \
  --server-id=1 --log-bin=lab-bin --binlog-format=ROW \
  --innodb-flush-log-at-trx-commit=1 --sync-binlog=1

# 等初始化结束后检查;没有就绪就稍后重试,不要执行后续 SQL。
docker exec db-course-transactions mysqladmin -uroot ping

# 分别在终端 A、B、C 执行这条命令,获得三个独立会话。
docker exec -it db-course-transactions mysql -uroot --prompt='lab> '

先只在 A 执行下一节初始化,再在 A/B/C 分别执行会话初始化。会话 A/B 交替执行时,必须按步骤切换终端。某一步阻塞没有返回提示符,正是实验观测点;不能在同一终端继续粘贴假装进入另一个会话。ROW_COUNT() 必须紧跟对应写语句,不能夹入其他查询。

1. 独立初始化与完整重置

下列脚本只删除专用库的五张教学表。重置前,所有会话先执行 ROLLBACK;若某会话正在等待,先让持锁会话回滚,待等待语句返回后,再回滚等待会话。否则 DDL 可能卡在元数据锁。首次初始化后,预期库存两行均为10,区间键为10/20/30,值班两人均在岗,流水及导入表为空。

CREATE DATABASE IF NOT EXISTS lab_transactions CHARACTER SET utf8mb4;
USE lab_transactions;
DROP TABLE IF EXISTS lab_reservation;
DROP TABLE IF EXISTS lab_import_line;
DROP TABLE IF EXISTS lab_duty;
DROP TABLE IF EXISTS lab_range;
DROP TABLE IF EXISTS lab_stock;

CREATE TABLE lab_stock (
  tenant_id BIGINT NOT NULL,
  sku_id BIGINT NOT NULL,
  available BIGINT NOT NULL,
  version BIGINT NOT NULL DEFAULT 0,
  PRIMARY KEY (tenant_id, sku_id),
  CONSTRAINT ck_lab_stock_nonnegative CHECK (available >= 0)
) ENGINE=InnoDB;

CREATE TABLE lab_reservation (
  tenant_id BIGINT NOT NULL,
  request_no VARCHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
  sku_id BIGINT NOT NULL,
  qty BIGINT NOT NULL,
  PRIMARY KEY (tenant_id, request_no),
  CONSTRAINT ck_lab_reservation_qty CHECK (qty > 0)
) ENGINE=InnoDB;

CREATE TABLE lab_range (
  tenant_id BIGINT NOT NULL,
  slot_no INT NOT NULL,
  note VARCHAR(40) NOT NULL,
  PRIMARY KEY (tenant_id, slot_no)
) ENGINE=InnoDB;

CREATE TABLE lab_duty (
  tenant_id BIGINT NOT NULL,
  worker_id INT NOT NULL,
  active TINYINT NOT NULL,
  PRIMARY KEY (tenant_id, worker_id),
  CONSTRAINT ck_lab_duty_active CHECK (active IN (0, 1))
) ENGINE=InnoDB;

CREATE TABLE lab_import_line (
  tenant_id BIGINT NOT NULL,
  batch_no VARCHAR(32) NOT NULL,
  line_no INT NOT NULL,
  qty BIGINT NOT NULL,
  PRIMARY KEY (tenant_id, batch_no, line_no)
) ENGINE=InnoDB;

INSERT INTO lab_stock VALUES (1,101,10,0),(1,102,10,0);
INSERT INTO lab_range VALUES (1,10,'ten'),(1,20,'twenty'),(1,30,'thirty');
INSERT INTO lab_duty VALUES (1,1,1),(1,2,1);
SELECT * FROM lab_stock ORDER BY tenant_id, sku_id;

每个会话都执行以下设置。隔离级别要在事务外设置;SET autocommit=1 可能提交现存事务,故前面明确 ROLLBACK。每个实验若另有设置,以该实验为准。

ROLLBACK;
USE lab_transactions;
SET autocommit=1;
SET SESSION TRANSACTION ISOLATION LEVEL REPEATABLE READ;
SET SESSION innodb_lock_wait_timeout=30;
SELECT VERSION(), CONNECTION_ID(), DATABASE(), @@transaction_isolation;
SELECT @@innodb_page_size, @@innodb_flush_log_at_trx_commit,
       @@sync_binlog, @@log_bin, @@binlog_format,
       @@innodb_deadlock_detect, @@innodb_rollback_on_timeout;

以下是“快速重置”,用于每次实验前恢复基线,不重新建表。先结束 A/B/C 的事务,再只在 C 执行;不能在旧 RR 事务里查询来验收重置。

USE lab_transactions;
START TRANSACTION;
DELETE FROM lab_reservation WHERE tenant_id=1;
DELETE FROM lab_import_line WHERE tenant_id=1;
DELETE FROM lab_range WHERE tenant_id=1;
INSERT INTO lab_range VALUES (1,10,'ten'),(1,20,'twenty'),(1,30,'thirty');
UPDATE lab_stock SET available=10, version=0 WHERE tenant_id=1;
UPDATE lab_duty SET active=1 WHERE tenant_id=1;
COMMIT;

2. L1:提交、回滚与业务原子性

先快速重置。A 扣减库存后记录预占,故意回滚:

-- A
START TRANSACTION;
UPDATE lab_stock SET available=available-3, version=version+1
WHERE tenant_id=1 AND sku_id=101 AND available>=3;
SELECT ROW_COUNT(); -- 1
INSERT INTO lab_reservation VALUES (1,'L1',101,3);
SELECT available, version FROM lab_stock WHERE tenant_id=1 AND sku_id=101;
-- A 自己看到 7,1

此时 B 普通查询库存应看到10,查 request_no='L1' 应为零行;B 不要使用 FOR UPDATE。然后 A 执行 ROLLBACK,B 仍看到10和零行。再由 A 原样执行扣减和插入,将最后一步改成 COMMIT;B 在新语句中看到库存7和一条流水。此实验只证明提交可见性、回滚和单库原子性,不证明断电持久性。结束后快速重置。

反例也可独立复现:重置后 A 在自动提交模式直接扣3,再执行一个重复主键插入使第二条语句失败。第一条更新已提交,后面的 ROLLBACK 不会把库存恢复10。要制造重复键,先插入 (1,'L1-dup',101,3) 再重复插入同一行;预期库存7、流水一行。错误不是 InnoDB 忘记回滚,而是根本没有把两次写入纳入一个事务。

3. L2:RR 的快照、当前读与自身写入

快速重置,A/B 使用 RR。

-- A 第1步
START TRANSACTION;
SELECT available FROM lab_stock WHERE tenant_id=1 AND sku_id=101; -- 10

-- B 第2步,自动提交
UPDATE lab_stock SET available=7, version=version+1
WHERE tenant_id=1 AND sku_id=101;

-- A 第3步
SELECT available FROM lab_stock WHERE tenant_id=1 AND sku_id=101; -- 10
SELECT available FROM lab_stock WHERE tenant_id=1 AND sku_id=101 FOR UPDATE; -- 7
SELECT available FROM lab_stock WHERE tenant_id=1 AND sku_id=101; -- 仍为10
UPDATE lab_stock SET available=available-1, version=version+1
WHERE tenant_id=1 AND sku_id=101;
SELECT available FROM lab_stock WHERE tenant_id=1 AND sku_id=101; -- 6
ROLLBACK;

-- B 第4步:A 回滚的只是自己的 -1
SELECT available FROM lab_stock WHERE tenant_id=1 AND sku_id=101; -- 7

这里最后的6不是“在旧10上减1”。更新按照当前可修改版本7计算,之后自己的写入对自己可见。若 B 尚未提交,A 的锁定读会等待;那是另一个时序,不能声称结果必定立即返回7。结束后快速重置。

4. L3:快照究竟从什么时候开始

先重置。A START TRANSACTION,但先不查 InnoDB 表;B 把101库存改7并自动提交;A 第一次普通 SELECT 预期为7。仅执行 SELECT 1 或读会话变量不能代替读取这张表以建立本实验需要的读视图。

再次重置。A 在 RR 下执行 START TRANSACTION WITH CONSISTENT SNAPSHOT;B 改7并提交;A 第一次普通查询101库存预期10。A 回滚。再次重置,A 改用 RC 后重演 L2 的前两个普通 SELECT,预期先10后7。RC 下每次一致性读建立自己的快照,不应套用 RR 的固定读视图结论。

-- A:RC 变体的开始和结束
SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED;
START TRANSACTION;
-- 此处按 L2 执行 A 查10、B改7、A再查7
ROLLBACK;
SET SESSION TRANSACTION ISOLATION LEVEL REPEATABLE READ;

5. L4:缺失唯一键为什么也能阻塞插入

快速重置。主键为 (tenant_id,slot_no),已有 (1,10)/(1,20)/(1,30)。A/B 均为 RR。

-- A 第1步:空结果不等于没有锁
START TRANSACTION;
SELECT * FROM lab_range
WHERE tenant_id=1 AND slot_no=15 FOR UPDATE; -- Empty set

-- B 第2步:等待,不会立即完成
START TRANSACTION;
INSERT INTO lab_range VALUES (1,15,'fifteen');

此时在 C 执行第9节观测 SQL,应能看到 B 请求插入的等待,以及 A 在前后索引记录之间的间隙保护。A COMMIT 后 B 插入返回;B COMMIT 后 C 查到10/15/20/30四行。结束后快速重置。

对照一:A 锁定已存在完整主键 (1,20),B 插入15应立即成功,而 B 更新20需要等待。对照二:重置且 A/B 改 RC,再执行缺失键15的锁定查询与插入,B 插入应立即完成;本表没有外键,也未制造重复键冲突,因而避开 RC 仍可能出现的约束检查锁。每个对照结束 A/B 都回滚、恢复 RR,再快速重置,不能把新增15带入下一轮。

6. L5:next-key 范围不是 SQL 文本的机械翻译

快速重置。A 锁定10与20之间的范围,B 尝试插入15:

-- A 第1步,RR
START TRANSACTION;
EXPLAIN SELECT * FROM lab_range FORCE INDEX (PRIMARY)
WHERE tenant_id=1 AND slot_no>10 AND slot_no<=20 FOR UPDATE;
SELECT * FROM lab_range FORCE INDEX (PRIMARY)
WHERE tenant_id=1 AND slot_no>10 AND slot_no<=20 FOR UPDATE; -- 返回20

-- B 第2步
START TRANSACTION;
INSERT INTO lab_range VALUES (1,15,'inside'); -- 等待

20这个索引记录以及它前方的间隙 (10,20) 是本实验解释的重点;典型 next-key 区间为 (10,20]。实际还可能出现边界记录、其他索引记录或 supremum 上的锁,不能把本句简化为“只锁一个对象”,应保存执行计划和 C 的锁观测。A 回滚后 B 可以完成插入;B 回滚以保持原数据。

若要比较更新20,必须结束上一轮后重置并重新执行 A 的范围查询,再在 B 执行 UPDATE lab_range SET note='changed' WHERE tenant_id=1 AND slot_no=20,预期等待。不要在 B 等待插入时继续塞入更新语句。对照 RC:重新建立会话事务后相同范围查询仍锁定返回的20,但普通范围间隙不再按 RR 方式保护,插入15预期不等待。对20的更新仍会等待,说明“RC 不锁间隙”绝非“RC 没有行锁”。

7. L6:两行库存组成死锁环

快速重置,恢复 RR,确认 @@innodb_deadlock_detect=1。下列步骤4后,A/B中的任意一个都可能成为受害者,不能断言总是后执行者失败。

-- A 第1步
START TRANSACTION;
UPDATE lab_stock SET available=available-1 WHERE tenant_id=1 AND sku_id=101;

-- B 第2步
START TRANSACTION;
UPDATE lab_stock SET available=available-1 WHERE tenant_id=1 AND sku_id=102;

-- A 第3步:等待 B 的102
UPDATE lab_stock SET available=available-1 WHERE tenant_id=1 AND sku_id=102;

-- B 第4步:请求 A 的101,形成环
UPDATE lab_stock SET available=available-1 WHERE tenant_id=1 AND sku_id=101;

预期一个会话返回 ERROR 1213 (40001),其整个事务已被引擎回滚;另一个会话等待解除后完成第二次更新。只让成功者 COMMIT,失败者执行 ROLLBACK 清理会话,再由 C 验收两行均为9。不要在不知道哪边失败的情况下统一粘贴后续更新,否则自动提交可能创造第三种结果。

让失败者用新事务,按101、102顺序各扣1后提交,预期两行均8。这是“重放完整业务操作”的模型;真实请求还须携带原幂等键,见第08章。C 的 SHOW ENGINE INNODB STATUS\G 可以查看最近死锁;历史诊断只在隔离实例阅读,不能直接输出生产 SQL 或请求内容。若关闭死锁检测,通常转为等待到超时,不应继续期待立即1213。结束后快速重置。

8. L7:原子扣减与错误的读改写

先复现反例,快速重置后 A/B 都开始 RR 事务并普通读到10。A 计算 10-7=3,B 计算 10-6=4。按以下顺序写入:

-- A
UPDATE lab_stock SET available=3 WHERE tenant_id=1 AND sku_id=101;
COMMIT;
-- B:用自己早先读到的10算出的常量覆盖
UPDATE lab_stock SET available=4 WHERE tenant_id=1 AND sku_id=101;
COMMIT;

最终库存4,两个请求若都被当成成功,承诺发货13件而初始只有10件。CHECK (available>=0) 没有阻止它,因为4合法。这个反例不需要读到脏数据;RR 也不能替应用修复错误的业务算法。

重置后执行正确的竞争:

-- A 第1步
START TRANSACTION;
UPDATE lab_stock SET available=available-7, version=version+1
WHERE tenant_id=1 AND sku_id=101 AND available>=7;
SELECT ROW_COUNT(); -- 1

-- B 第2步:等待
START TRANSACTION;
UPDATE lab_stock SET available=available-6, version=version+1
WHERE tenant_id=1 AND sku_id=101 AND available>=6;

-- A 第3步
COMMIT;

-- B 第4步:等待结束后立即执行
SELECT ROW_COUNT(); -- 0,当前库存3不满足 >=6
ROLLBACK;

C 验收 available=3, version=1。B 的零行应映射为“本次预占未成功”,不能继续插入成功流水。若还需要区分 SKU 不存在与库存不足,应在明确的业务协议中查询诊断,不能把诊断值当作下一次扣减的依据。结束后快速重置。

9. L8:观测等待并区分1205和1213

C 在其他会话等待期间执行,只有专用实验实例才授予相应查询权限:

SELECT ENGINE_TRANSACTION_ID, THREAD_ID, OBJECT_NAME, INDEX_NAME,
       LOCK_TYPE, LOCK_MODE, LOCK_STATUS, LOCK_DATA
FROM performance_schema.data_locks
WHERE OBJECT_SCHEMA='lab_transactions'
ORDER BY OBJECT_NAME, ENGINE_TRANSACTION_ID;

SELECT w.REQUESTING_ENGINE_TRANSACTION_ID AS waiting_trx,
       w.BLOCKING_ENGINE_TRANSACTION_ID AS blocking_trx,
       r.OBJECT_NAME, r.INDEX_NAME, r.LOCK_MODE AS requested_mode,
       b.LOCK_MODE AS held_mode, r.LOCK_DATA
FROM performance_schema.data_lock_waits w
JOIN performance_schema.data_locks r
  ON r.ENGINE=w.ENGINE AND r.ENGINE_LOCK_ID=w.REQUESTING_ENGINE_LOCK_ID
JOIN performance_schema.data_locks b
  ON b.ENGINE=w.ENGINE AND b.ENGINE_LOCK_ID=w.BLOCKING_ENGINE_LOCK_ID
WHERE r.OBJECT_SCHEMA='lab_transactions';

锁 ID、事务 ID 及输出行数都是运行时数据,不提供伪造的固定值。X,REC_NOT_GAP 表示仅记录;X,GAP 强调间隙;插入等待常可见 INSERT_INTENTION;某些记录锁显示为 X,需结合索引位置解释 next-key。锁记录中的 LOCK_DATA 也可能为 NULL;不要为了展示它而假定它永远含完整主键。

超时实验:重置后 A 开事务锁住101;B 设置 innodb_lock_wait_timeout=3,开事务先把102减1,再尝试把101减1并等待。默认 innodb_rollback_on_timeout=OFF 时,预期约3秒后1205,B之前的102更新仍在事务中。B自己的普通查询看到102为9,C普通查询仍为10;B ROLLBACK 后两行恢复10,A也回滚。若配置开启了整个事务超时回滚,B不会保留之前的102更新。这个分支须按第1节记录的实际变量判断,不能凭错误码猜配置。最后 B 恢复等待超时30秒。

10. L9:RR 也可能发生写偏斜

快速重置,A/B 均 RR。两人轮值,业务要求至少一人留岗。A/B分别 START TRANSACTION,都执行 SELECT SUM(active) FROM lab_duty WHERE tenant_id=1 得2。A更新自己的 worker_id=1 为0并提交;B依据旧读数,把 worker_id=2 改0并提交。C查询预期总和0。两次写入不同主键,没有必然的写写冲突,但全局业务约束被破坏。

修正实验:重置后,A在事务里 SELECT worker_id,active FROM lab_duty WHERE tenant_id=1 ORDER BY worker_id FOR UPDATE;B执行同句会等待。A在读到两人后令1离岗并提交;B等待结束读到一人已离岗,因此不执行更新,提交结束。C预期总和1。这里锁定固定的两条成员行;如果成员可以动态增删,还需要明确成员集合的锁定协议,不能把本例推广成任意聚合约束都已经得到保护。

11. L10:客户端提交结果与服务崩溃

本实验可选,只适用于第0节自己创建的隔离容器。先快速重置,保持强持久性配置及 binlog 开启。A执行并确认客户端收到提交成功:

START TRANSACTION;
UPDATE lab_stock SET available=7, version=1 WHERE tenant_id=1 AND sku_id=101;
INSERT INTO lab_reservation VALUES (1,'L10-committed',101,3);
COMMIT;

B另开事务更新102为4,插入 (1,'L10-uncommitted',102,6),不要提交。此时在宿主机新终端执行:

docker kill --signal=KILL db-course-transactions
docker start db-course-transactions
# 等待就绪后执行,不要因第一次 ping 失败判定恢复失败。
docker exec db-course-transactions mysqladmin -uroot ping
docker exec -it db-course-transactions mysql -uroot

重连后先 USE lab_transactions,查询两张表。预期101为7、102为10;已提交流水存在、未提交流水不存在。这个故障注入模拟 mysqld 进程突停,不模拟宿主断电、磁盘损坏,也没有精确停在 prepare/binlog/commit 指令之间。不能从一次成功恢复推出所有硬件条件下零丢失,更不能通过反复手工 kill 声称已经证明每个两阶段提交分支。

扩展的“提交应答丢失”只做时序推演:服务提交成功后,网络在应答到达客户端之前断开,客户端可能报失败而数据库实际已提交。应使用 (tenant_id,request_no) 查询或重放幂等操作,而不是换新请求号再扣一次。实验结束后快速重置即可继续学习;彻底清理时只删除本实验容器及其匿名卷:docker rm -fv db-course-transactions,执行前确认名称属于自己创建的练习资源。

12. Java 验证契约与自测答案

本目录没有伪装成可运行项目的 Java 工程。第09章提供教学 Mapper 和服务片段,集成前须配置专用 DataSource、同源事务管理器、Mapper 扫描和测试依赖。建议按下面契约实施测试,而不是只断言“方法抛异常”:

场景 注入点 用独立连接验收的结果
正常预占3 无 库存7,原请求号流水一条
插入流水后抛异常 扣库存之前或之后 库存10,流水零条
重复同请求同参数 第二次调用入口 库存仍7,流水仍一条
同请求号换数量 重复请求检查 拒绝,不额外扣减
真实代理调用 通过容器中的 Bean 异常能触发整体回滚
this 自调用反例 绕过代理且外层无事务 可出现前一条语句已经提交
BATCH中重复键 flushStatements 整批事务回滚,不残留前几条
死锁重试 两个真实物理连接 失败尝试结束后新事务重放,无重复流水

练习一:L2 中 A 的最后一条普通查询为何从10跳到6?答案:当前读更新基于B已提交的7,自己的更新可见;读视图没有因此整体刷新,其他未被自己更新的记录仍可能看到旧版本。

练习二:L4空结果能否推出此时安全地新增15?答案:只有同一事务并遵守锁协议的后续操作才有对应保障;另一个事务插入会等待。先查后提交,再插入是新的竞争窗口。

练习三:L6死锁失败者只重试最后一条SQL会怎样?答案:其第一条更新已经随整个事务回滚,只重试第二条会把双SKU操作做成单SKU操作。应重放整个业务单元。

练习四:L8收到1205后能否直接COMMIT已有改动?答案:引擎默认可能允许,但对要求两行一起修改的业务会造成部分提交。教学服务应主动回滚整个业务事务,再按重试策略决定是否重放。

练习五:L10未提交流水消失能否证明事务没有产生过redo?答案:不能。未提交修改也能产生并刷出redo;恢复可以先重做物理修改,再利用事务状态和undo撤销未完成事务。

实际执行时请自行记录日期、版本、会话连接号、实验编号、观察值和与预期的差异。本 README 中没有把静态推演写成“全部实验通过”。

学习阶段 03

Spring核心与应用工程

IoC、代理、事务、接口与资源管理

原始文档 · spring-course/README.md

ERP Spring系统课程:从前端转向后端工程

新增开发陷阱深化:多数据源资源绑定、路由时机、rollback-only、新事务连接预算、提交后事件和测试掩盖缺陷,配合真实Spring隔离实验及代理图阅读。

本课程结合当前目录的ERP项目,围绕“对象怎样组织、调用怎样增强、数据怎样保持正确、资源怎样保持有界”组织20章教程。重点覆盖IoC/DI、Bean与注解、AOP、事务、MVC、安全,以及海量数据场景中的SQL、分页、批处理、线程池、并发和故障恢复。

推荐直接打开离线阅读版。它把正文、源码索引、实验说明与验证记录放在同一页,支持侧栏筛选、浏览器全文搜索、字号调整、明暗切换与打印为PDF。无需付费Markdown软件,也不需要启动服务;外部官方资料需要联网,正文完全离线。

怎样学,才能把概念变成能力

先读00,再跟01—04做对象装配与生命周期实验;接着读05—08,把代理、事务、HTTP和权限串起来。09—12是本课程的大数据主线,建议逐章回到源码计算工作量,不跳过SQL和连接池。13—16建立故障与发布思维,最后用18—19独立完成综合设计和答辩。17章在遇到注解时随时查询。

每章包含解释、项目或设计实例、边界与练习答案。代码分为三类:项目现有代码的只读引用、机制说明片段、独立可执行实验。没有标为实验源码的片段通常省略import或领域模型,不能直接当完整生产实现复制。

一、对象设计与容器

章节 核心能力
00 学习地图与Spring工程思维 前端经验如何迁移,如何区分框架与数据库责任
01 控制反转与依赖注入 手工DI、IoC/DIP区别、接口与依赖方向
02 Bean注册与依赖解析 扫描、BeanDefinition、Qualifier、Provider、循环依赖
03 生命周期与扩展点 后处理器、初始化、资源关闭与就绪
04 Boot启动与配置 自动配置条件、配置覆盖、版本与动态更新

二、调用边界、事务与接口

章节 核心能力
05 AOP与动态代理 JDK/CGLIB、自调用、切面顺序、路由与权限
06 事务传播与一致性 REQUIRED/REQUIRES_NEW、回滚、短事务、幂等
07 MVC与接口契约 请求链、参数绑定、状态码、分页与异步接单
08 校验与多租户安全 DTO、资源授权、SQL租户条件、序列化与日志

三、海量数据与并发性能

章节 核心能力
09 SQL与数据访问性能 工作量账本、真实广告SQL、N+1与连接预算
10 分页批处理与内存 Keyset、快照、批执行、流式、分块恢复
11 线程池与背压 队列、拒绝、Async/Future、容量与饥饿死锁
12 Java并发与上下文 JMM、锁、共享字段、ThreadLocal与租户传播

四、稳定性与工程交付

章节 核心能力
13 缓存事件与可靠任务 L1/Redis、缓存注解、提交后事件、Outbox与调度
14 超时重试与隔离 deadline、重试放大、限流、配置阻断与恢复
15 可观测性与容量 指标、追踪、JVM、连接等待、压测与验收
16 测试发布与演练 测试层级、H2边界、滚动兼容、故障矩阵

五、查阅与综合实战

章节 核心能力
17 注解速查 注解由谁读取、生效条件、常见失效边界
18 可靠导出综合设计 任务表、幂等接单、租约epoch、分块与manifest
19 故障复盘与能力验收 10个事故推演、评审模板、分阶段产物

配套材料

与数据库课程怎么配合

Spring侧问题 数据库侧前置知识
事务代理正确,为什么仍超卖 锁与库存并发
SQL只取100行为什么慢 索引、执行计划
从库路由为何没达到预期 复制与读写分离
缓存删除后为什么还能脏 缓存一致性
Mapper接口如何执行SQL MyBatis
加线程为何更慢 JDBC连接池工具链

版本与证据约定

仓库包含不同版本的Spring/Boot应用,教程不把它们统称为同一技术栈。常见语法按Java8和Spring5时代讲解;独立实验实际使用JDK17、Spring5.3.39、H2 2.2.224、JUnit4.13.2。H2依赖要求较新JDK,编译目标为Java8不代表实验整套依赖能在Java8运行。

Spring5.3.39用于复现既有机制,不是新项目生产选型推荐。没有启动业务应用、连接业务数据库或修改业务代码。源码只证明实现形态;部署版本、实际流量、容量与完整安全性需要额外证据。文中容量数字均明确作为教学假设,不能直接拿来设生产参数。

重新生成阅读版

已生成的HTML可直接打开;只有修改Markdown后才需要下面的Python步骤。在本目录执行:

python3 -m venv /tmp/erp-spring-reader
/tmp/erp-spring-reader/bin/pip install -r requirements-reader.txt
/tmp/erp-spring-reader/bin/python build_reader.py
/tmp/erp-spring-reader/bin/python validate.py

生成器不连接任何业务服务。验证器检查章节编号、代码围栏、本地链接、引用行范围、HTML锚点和外部运行资源,不负责证明所有示例在生产环境可用。

原始文档 · spring-course/00-学习地图与Spring工程思维.md

00 学习地图与Spring工程思维

这套课程接续数据库课程,把关注点移到“谁创建对象、如何组织依赖、谁拦截调用、如何管理资源、怎样在巨大数据量下保持正确和稳定”。数据库课程讲清楚一次SQL的语义与代价;这里讲一条HTTP请求、一个定时任务或一次异步执行怎样产生那些SQL,以及每一层会放大多少工作。

课程基于当前目录的ERP源码,不假定所有项目采用同一Spring版本,不连接业务服务。示例用Java8可理解的语法,机制实验固定Spring5.3.39;实际运行测试的JDK及结果见验证记录。这个旧版基线用于解释仓库年代相近的机制,不是建议新项目直接使用旧依赖。

1. 从前端概念进入Spring

你可以把一个后端服务理解为一张长期存在的对象协作图。Controller接收请求,Service组织业务步骤,Mapper访问数据库,Remote适配外部接口。Spring容器构造和连接这些对象,Web框架把请求分派给它们,代理在调用前后执行事务、鉴权、异步等基础设施逻辑。

前端组件也有依赖、生命周期和上下文,但后端常见的singleton Bean会同时服务多个请求。把tenantId、当前订单或临时List放到Service实例字段里,相当于让不同用户共享正在编辑的表单状态。代码在单次调试中正常,在并发中可能串租户或覆盖数据,这不是加一个注解就能消除的问题。

前端经验 可迁移的直觉 需要修正的部分
props注入依赖 调用者提供协作对象 DI不等于框架,手工构造也能注入
全局store 跨调用共享状态 singleton对象可能被多个线程同时访问
路由中间件 调用前后执行公共逻辑 Filter、Interceptor、AOP作用边界不同
Promise 异步结果与错误传播 Java执行器有线程、队列、拒绝和下游容量
列表分页 只展示少量数据 后端可能为20行扫描百万行或执行COUNT
前端禁用按钮 减少重复点击 后端仍须处理重试、重复事件和多端竞争

2. IoC、DI与DIP放在不同层次理解

控制反转IoC关注谁掌握创建、调用和生命周期控制。传统业务对象内部自己new数据库客户端、读取配置并决定实现;反转之后由外部装配者创建并提供,业务对象只使用依赖。框架也可以掌握回调时机,例如HTTP请求到来时调用Controller,而不是业务主函数自己无限循环收请求。

依赖注入DI是组织对象依赖的一种实现方式:构造器、setter或字段接收外部对象。它解决“对象从哪里来、怎样连接”,不要求每个类都写接口,不要求必须使用Spring。最简单的new Checkout(new PriceRepository())已经体现由外部装配依赖。

依赖倒置DIP是设计原则:核心业务面向稳定抽象,细节实现向业务需要靠拢。例如库存用例依赖StockRepository接口,MyBatis适配器实现它。即使全部用了@Autowired,如果核心业务直接依赖某厂商SDK并到处传播SDK模型,也未必做到了依赖倒置。

容器带来的价值不仅是少写new:配置选择、单例复用、生命周期回收、基础设施增强、测试替换都能在装配层统一管理。代价是行为分散在定义、条件、后处理器和代理中,所以必须学会追踪“定义—实例—代理—调用”的完整路径。

3. 给每段代码标出四种对象

第一类是BeanDefinition,描述怎样创建Bean,包括类型、工厂、作用域、条件等;第二类是业务目标对象,真正执行方法体;第三类是代理对象,调用可能先经过拦截链;第四类是依赖资源,例如连接池、线程池、客户端。它们不一定同寿命,也不一定同线程。

你注入的Service可能是代理,this.method()中的this仍可能是目标对象,因而绕过拦截。你new出的普通对象不是容器Bean,不会自动执行完整Spring生命周期。构造器结束时,依赖注入后处理、初始化和最终代理暴露也未必完成。因此不要在构造器里启动依赖自己代理的任务或调用远端加载海量数据。

核心阅读问题是:谁注册这个定义?何时实例化?依赖如何选择?返回的是目标还是代理?调用是否穿过代理?资源何时关闭?这些问题比背诵注解列表更能解释真实故障。

4. 真实项目入口不是一行run那么简单

ErpItemWebApplication〔本地文件〕包含组件扫描范围、自动配置排除、Mapper扫描、XML导入、缓存与事务启用,还有多个内部@Enable注解。排除默认Redis自动配置不等于整个服务没有Redis,私有starter可能提供另一套装配。

启动入口还按profile处理配置并执行后置动作。因此“跑一下main看看”可能连接外部服务或发送通知,不适合作为本课程机制实验。配套实验使用独立AnnotationConfigApplicationContext、内存H2和本地线程池,不启动任何ERP应用。

Spring Boot负责按约定与条件减少装配代码,Spring Framework提供容器、AOP、MVC、事务等核心能力,Spring Security负责安全链。Spring Cloud及内部starter再引入配置、RPC和治理。它们是相互组合的组件,不是一个注解自动覆盖所有能力。

5. 海量数据问题先量工作量

一次请求的成本可以拆为:排队时间、连接等待、SQL执行次数及每次扫描、结果传输、对象创建、映射序列化、远端调用与返回。SQL单次5毫秒,循环1000次就是数秒级工作;只返回20行,也可能先扫描和排序几百万行。系统瓶颈往往来自工作量放大,而不是某个框架函数调用多了几纳秒。

内存大致随“同时在途任务数×每任务持有数据”增长。导出分页1000行不意味着只占1000行内存,如果每页都提交异步线程而队列保存100页,仍然持有十万行。相反,串行分批也未必足够快,需要在明确数据库预算后有限并发。

Little定律使用平均到达率与平均停留时间,不能把p99直接代入当线程数公式。连接池、线程池、HTTP客户端和数据库共同构成资源网络,提高其中一个上限可能让另一个等待更长。性能改动至少写出瓶颈假设、正确性边界、测量指标和回退条件。

6. 全课程的能力顺序

阶段 章节 证明材料
设计与容器 01—04 手工DI、Bean选择、生命周期与自动配置解释
代理与请求 05—08 自调用反例、事务边界、请求/安全链
大数据与并发 09—12 查询成本、有限内存、队列背压、线程上下文
稳定与交付 13—16 缓存/任务恢复、超时预算、监控、故障测试
查阅与综合 17—19 注解速查、综合导出设计、事故答辩

先做实验室里的手工注入与Primary/Qualifier测试,再读01—03;先观察事务代理与self调用的差异,再读05—06。性能章节回连数据库课程的索引、MVCC与复制章节,避免把Spring行为和数据库行为混成同一机制。

7. 学习记录模板

每读一个项目例子,记录业务入口、可信租户来源、依赖类型与实际实现、代理边界、事务资源、线程切换、数据规模、失败状态和可观测证据。只看一个方法体无法证明调用者的事务,也无法证明私有依赖的内部行为,未知项要留下而不补想象。

每做性能实验,记录数据规模与倾斜、请求分布、并发、暖机、工具版本、成功率、p50/p95/p99、队列最老年龄、连接等待、CPU/堆/GC和数据库工作量。固定种子的小测试证明机制,不能被包装成生产容量数字。

8. 起步练习与答案

一:用了@Autowired就是依赖倒置吗?不是。要看高层是否依赖稳定抽象、细节是否被隔离。字段自动注入解决装配,不自动改善业务架构。

二:singleton为什么不等于线程安全?容器保证的是实例作用域,不会自动为每个方法加锁;共享可变字段仍受并发读写影响。优先无状态Service与局部变量,把业务状态交给明确持久化协议。

三:为什么不能把每条明细查库都改成CompletableFuture来提速?那可能把N+1串行放大成N+1并发,压满连接池与数据库。先合并查询减少总工作,再按资源预算并行。

四:为什么教程不直接启动ERP验证?机制实验不需要触发业务环境,独立容器与本地资源能隔离变量;真实集成仍需明确配置和服务依赖,验证记录不能混用两种结果。

原始文档 · spring-course/01-控制反转与依赖注入的设计思想.md

01 控制反转与依赖注入的设计思想

本章面向已经写过前端组件、请求模块和状态管理,但尚未建立后端对象模型的读者。我们沿着“运营用户分页计算”这条实际业务线,先手工创建对象,再集中装配,最后让 Spring 接管装配。目标不是记住几个注解,而是能够回答:谁选择实现,谁创建对象,谁持有资源,谁负责关闭,以及并发请求是否会共享同一份状态。

本章与后续三章使用 Java 8 语法,以 Spring Framework 5.3.22、Spring Boot 2.7.3 的本机源码包为机制核对基线。项目 Java 版本声明〔本地文件〕和 Boot BOM 导入〔本地文件〕分别声明 Java 8 与 Boot 2.7.3;这仅是构建证据,不能证明部署进程实际加载了这些版本。文中的教学类不属于业务源码,不需要启动 ERP 或连接任何业务服务。

1. 从前端熟悉的依赖说起

假设页面组件里直接创建一个 HTTP 客户端,写死服务器地址,然后请求运营用户列表。组件既决定界面,也决定通信实现。单测必须拦截网络;换一个后端来源时,还要修改组件。后端 Service 如果在方法里直接创建远程客户端,也面临同样的问题,只是后果更严重:客户端可能持有连接池、线程池或后台心跳,一个请求创建一份就可能耗尽资源。

我们先把问题缩小到无网络的教学模型。以下类型按顺序放入一个独立练习目录,每个 public 类型使用同名文件;共同使用 package course.ioc;,所需集合导入为 java.util.List、java.util.Arrays、java.util.Collections、java.util.Objects。这是供读者复制的实验材料,本次写作没有生成 Java 文件。

public interface UserPageSource {
    List<Long> readPage(long tenantId, int pageNo, int pageSize);
}

public final class DemoUserPageSource implements UserPageSource {
    @Override
    public List<Long> readPage(long tenantId, int pageNo, int pageSize) {
        if (tenantId <= 0 || pageNo <= 0 || pageSize != 2) {
            throw new IllegalArgumentException("invalid demo request");
        }
        return pageNo == 1 ? Arrays.asList(11L, 12L)
                          : Collections.emptyList();
    }
}

这里故意只返回编号,避免把 ORM、网络异常和金额计算一起塞入第一步。tenantId 是调用参数,表达这一次操作属于哪个租户;它不是写进单例字段的“当前用户”。pageSize 固定为二仅用于验证装配,不能把这个演示实现当作完整分页适配器。

首先看一个反例:

public final class BadUserCounter {
    private final UserPageSource source = new DemoUserPageSource();

    public int firstPageSize(long tenantId) {
        return source.readPage(tenantId, 1, 2).size();
    }
}

变量类型虽然是接口,但对象仍在业务类内部决定。明天需要改成 HTTP、数据库或固定失败的测试实现,都要修改这个类。面向接口声明和依赖注入并不等价;接口只是表达契约,装配权是否移出业务对象是另一个问题。更不能把“没有直接 new”当作最终标准:如果业务方法改成静态 GlobalClients.get(),依赖仍然被隐藏,只是藏到了全局注册表里。

2. 第一步改造:把必需依赖放进构造器

public final class UserCounter {
    private final UserPageSource source;

    public UserCounter(UserPageSource source) {
        this.source = Objects.requireNonNull(source, "source");
    }

    public int firstPageSize(long tenantId) {
        if (tenantId <= 0) {
            throw new IllegalArgumentException("tenantId must be positive");
        }
        return source.readPage(tenantId, 1, 2).size();
    }
}

业务对象不再知道实现类。构造器声明:“想使用我,必须先给我一个能分页读用户的对象。”这就完成了 DI,即 Dependency Injection,依赖注入。此时完全没有 Spring。注入描述的是依赖如何进入对象,不是某个框架的专有动作。

构造器的好处不只是少写一个注解。对象创建成功,就已经具备完成工作的基本条件;依赖可以是 final 字段,调用方和测试者都能一眼看见它。若改成先创建对象、以后再调用 setter,两个动作之间可能存在未完成装配的状态。setter 并非永远错误,可变且确实可选的协作关系可以使用它,但必须说明什么时候可调用、空值代表什么以及并发修改是否允许。

注意 final 只表示这个引用不能重新赋值,不表示引用的对象线程安全。一个 final 的 ArrayList 仍然可以被多个线程同时修改。构造器注入能改善依赖完整性,无法替你设计并发算法,也不会自动补齐权限验证、分页条件或远程超时。

3. 第二步改造:建立 composition root

public final class ManualMain {
    public static void main(String[] args) {
        UserPageSource source = new DemoUserPageSource();
        UserCounter counter = new UserCounter(source);
        if (counter.firstPageSize(7L) != 2) {
            throw new AssertionError("unexpected page size");
        }
    }
}

ManualMain 就是一个极小的 composition root,中文可称“装配根”。它位于应用入口附近,负责选择实现并连接对象。运行时调用方向是 main → counter → source,装配时创建方向则通常从底层资源向上:先客户端,再服务,最后入口适配器。大型项目不要求所有 new 写在一个文件里,而是把创建策略集中在配置模块,避免散落在业务分支中。

这一步的价值可以用替换实验看见。把 source 改成一个 lambda,返回空列表,业务类不改就能验证空页;把 lambda 改为抛出异常,就能验证异常传播。测试的前提变得清晰:它证明计数逻辑与调用契约,不证明远程协议或数据库行为。依赖注入降低测试成本,是因为替换点明确,而不是因为容器神奇地消除了外部依赖。

UserPageSource empty = (tenant, page, size) -> Collections.emptyList();
UserCounter counter = new UserCounter(empty);
if (counter.firstPageSize(7L) != 0) {
    throw new AssertionError("empty page must stay empty");
}

如果 source 持有可关闭资源,装配根还应确定资源所有者。多个服务共享同一个客户端时,不能每个服务用完都 close;共享资源应由创建它的应用级生命周期统一关闭。手工装配并不低级,小型工具用几行明确的构造代码往往足够。容器的收益在于对象图扩大以后,能够系统地维护创建顺序、作用域、配置覆盖与资源清理。

4. IoC、DI、DIP 解决的是不同问题

IoC 是 Inversion of Control,控制反转。对当前案例而言,业务对象原来控制“使用哪种依赖、何时创建”,现在这部分控制交给外部装配者。更广义的 IoC 还包括框架调用你的回调:前端给按钮注册事件处理函数,随后由事件系统决定调用时机,也体现控制方向变化。不能把所有 IoC 都缩成 @Autowired。

DI 是实现对象协作的一种方式:依赖从外部传入。DIP 是 Dependency Inversion Principle,依赖倒置原则,关注模块在源码层面依赖谁。高层业务规则应依赖稳定的抽象,低层通信细节也适配这个抽象,而不是让业务规则被某个 SDK 的细节绑住。若 UserCounter 的构造器直接接收某厂商具体客户端,虽然发生了 DI,却未必形成合适的 DIP 边界。

反过来,一个类依赖接口,却自己 new 接口实现,可以体现一部分抽象设计,却没有把装配责任移出去。还有一种常见误区是“每个类都生成一个同名接口”;只有一个实现且没有明确替换边界时,这可能只是增加跳转层数。抽象应围绕稳定的业务能力定义,例如“读取某业务线的用户页”,而不是机械复制远程 SDK 的所有方法。

判断设计时可以分别问三个问题:控制权从谁移给谁,依赖从哪个入口进入对象,源码依赖指向业务能力还是通信细节。三个问题分别对应 IoC、DI、DIP,它们经常一起出现,却不是同义词。

5. 第三步改造:把装配根交给 Spring

以下配置与前面的教学类型放在同一个包,增加 org.springframework.context.annotation.Bean、Configuration、AnnotationConfigApplicationContext 的导入。独立实验只需 Spring Context 5.3.22 及其依赖,无需 Boot、Web starter 或数据库。

@Configuration
public class CourseConfig {
    @Bean
    public UserPageSource userPageSource() {
        return new DemoUserPageSource();
    }

    @Bean
    public UserCounter userCounter(UserPageSource source) {
        return new UserCounter(source);
    }
}
public final class SpringMain {
    public static void main(String[] args) {
        try (AnnotationConfigApplicationContext context =
                 new AnnotationConfigApplicationContext(CourseConfig.class)) {
            UserCounter counter = context.getBean(UserCounter.class);
            if (counter.firstPageSize(7L) != 2) {
                throw new AssertionError("unexpected page size");
            }
        }
    }
}

业务类与接口没有修改,改变的是装配者。@Bean 方法描述创建方式;容器先读取这些描述,再解析 userCounter 的参数需要哪个对象。默认 singleton 的含义是每个容器内、每个 Bean 定义共享一个实例,不是全 JVM 的某个 Class 永远只有一个对象。两个独立容器各自注册同一配置,会各自拥有实例;同一个类也能用不同 Bean 名注册多次。

只有进入容器管理路径的对象,才按相应生命周期被管理。@Bean 方法里 new 出并返回的对象是被注册的产品;临时 new 出的辅助对象不因创建位置在配置类里就自动成为 Bean。new CourseConfig() 也只是普通 Java 对象,不能把调用它的方法等同于通过容器获取 Bean。第三章会解释配置类增强和生命周期的具体机制。

应用入口可以从容器取出顶层对象,但业务层不应到处 getBean。后一种方式常被称为 Service Locator:依赖在运行时查询,构造器看不出来,拼错名字甚至可能到请求发生时才失败。容器应承担装配根,业务方法应继续调用显式依赖。

6. 回到真实项目:看清哪些是事实,哪些是改进建议

项目 PaidOperationUserDataProvider〔本地文件〕把业务线标识、分页读取和用户历史读取放在接口中。本土海外 Provider〔本地文件〕使用 @Component 与 Lombok 的 @RequiredArgsConstructor,final 字段指向 LocalOverseasDataxClient。这里构造器由编译期 Lombok 生成,Spring 在运行时使用构造器;不能说 Spring 运行时读 Lombok 注解替它生成代码。

任务入口〔本地文件〕持有具体 Provider,并把它传给 calculate 方法〔本地文件〕。这段代码展示两层选择:任务选择业务线,计算方法依赖 Provider 契约。不能据此声称整个系统已经“全部面向接口注入”;入口仍有具体类依赖,计算服务也还有其他具体协作者。我们读取的是局部调用链,不是对全仓架构的无条件背书。

尤其要读 UnavailableLocalOverseasDataxClient〔本地文件〕:它能够被注册,却在调用方法时明确抛错。Bean 存在不等于外部能力已接入,容器启动成功也不等于业务操作成功。这种显式不可用比悄悄返回空列表更容易辨别“未接入”和“确实没有用户”,但是否应允许应用带着不可用实现就绪,仍取决于该功能是否是必需能力。

7. 把数据规模、并发与安全放进对象设计

真实计算方法每页请求 1000 条,并在循环外维护策略汇总 Map。分页意味着每次读取有界,不代表整个任务内存天然有界:循环外累计状态、单页关联数据和下游缓存都可能增长。要估算任务峰值,应把“页内临时数据 + 全程累计状态 + 同时执行任务数”一起考虑。SQL 的访问路径接着读 数据库课程第05章,不要用“已注入分页服务”替代查询成本分析。

容器单例通常适合无状态业务服务,以及本身设计为线程安全的客户端。不要把当前租户、当前页、当前导出结果保存进单例的可变字段。两个请求会交替读写,轻则计数混乱,重则将一个租户的数据交给另一个租户。请求信息应沿调用参数传递,权限验证后的租户身份应来自可信入口,不能因为前端提供了 tenantId 就直接信任。

如果把用户身份放入 ThreadLocal,还需处理线程池复用和清理;依赖注入并不会替你传播或清除上下文。更基础的解决办法是先让核心业务函数接收显式上下文,并在数据访问契约中保留业务线和租户条件。完整数据隔离与联合键讨论衔接 数据库课程第22章。

资源共享还需要容量边界。共享连接池可以减少重复建连,却不能让数据库无限承压;每请求创建一个池则会把容量控制打散。对象图应明确谁是共享资源、谁是单次操作数据、谁负责限流和超时。连接池的等待时间、查询超时与服务总预算详见 数据库课程第27章。这些约束不是学完 Spring 后才补上的优化,而是选择对象生命周期时就必须考虑的设计输入。

8. 练习与参考答案

练习一: 不使用 Spring,为 UserCounter 注入一个总是抛异常的实现。它测试什么,不能测试什么?

答案: 使用 UserPageSource failed = (t, p, s) -> { throw new IllegalStateException("demo failure"); };,构造 counter 后调用 firstPageSize,断言异常传播。它验证调用没有把失败伪装为空页;不能证明真实客户端的超时、重试、认证和资源回收。若捕获异常后返回零,测试应该失败,因为零有明确业务含义。

练习二: 给 UserCounter 加 private long currentTenant;,调用前写入、读取时使用。为什么构造器注入和 final source 都救不了它?

答案: 两者只保证 source 引用的装配和稳定性,无法保护 currentTenant。单例并发调用会覆盖身份。把身份保留为方法局部参数,并在入口校验权限,才能避免这个共享状态来源;数据库查询仍须包含隔离条件。

练习三: 测试把真实 Provider 换成 fake,是否说明遵守 DIP?

答案: 这是存在可替换点的证据,但还应检查接口是否被高层业务能力定义、是否泄漏厂商类型、错误语义是否稳定。本项目 Provider 返回外部领域类型,说明抽象边界仍带有集成背景,不能仅凭 interface 关键字宣称完全解耦。

练习四: 两个 Spring 容器都注册 CourseConfig,两个 counter 是否应当 ==?

答案: 不应当。singleton 的范围是容器与定义。同一容器重复获取同名 singleton 通常得到同一实例;跨容器不能据此推断。多个业务类各自 new 同一种客户端也不会因该类带注解就自动合并。

9. 官方依据与本章验证边界

IoC、构造器注入和作用域可交叉阅读 Spring 5.3 IoC 官方参考。机制源码核对入口为 5.3.22 DefaultListableBeanFactory.resolveDependency,本文实际读取了本机同版本 sources.jar,并非根据方法名猜测行为。

版本迁移不能只换 import:Boot 3.0 要求 Java 17、Spring 6,并迁移 Jakarta EE 相关 API,见 官方迁移指南。本文坚持 Java 8 语法,没有使用 record、var 或较新集合工厂方法。旧版本用于解释现有代码,不代表建议新系统直接采用这个历史补丁版本。

本章交付的是课程正文和内嵌实验,已经静态阅读所链接的项目代码及框架源码;没有编译或执行教学 Java,也没有启动 ERP、读取业务配置值或连接业务。练习输出属于预期结果,不能当作实测报告。下一章继续拆解注册、候选筛选和注解处理器,让“容器替我装配”变成可以逐步排查的流程。

原始文档 · spring-course/02-Bean注册依赖解析与注解.md

02 Bean注册、依赖解析与注解

读完上一章,你应该已经能手工装配一个订单服务。本章把手工装配翻译成Spring内部的工作:先登记对象的创建说明,再解析依赖,最后取得可以调用的对象。理解这条链,才能解释“扫描到了为什么注入失败”“明明有两个实现为什么运行时选错了”“给类加注解为什么没有效果”。本章以Spring 5.3的常见注解配置为基线;私有starter的额外注册规则必须看其实现。

1. BeanDefinition不是Bean

可以把BeanDefinition看成一张创建说明书,记录类、工厂方法、作用域、依赖、初始化方法、是否延迟等信息。它不是已经构造好的业务对象。容器先有定义,再根据需要实例化。因此,修改定义的扩展点和修改对象的扩展点有不同执行时机。

一个常见流程是:扫描或导入配置→注册BeanDefinition→处理定义→解析依赖→创建对象→初始化→可能包装代理→供调用者使用。扫描能成功,只说明候选定义被找到;构造器抛异常、缺少依赖、循环依赖、重复名字或条件不满足,仍可能让应用启动失败。

Bean的名字也不等于Java类型。一个接口可以有多个Bean,同一实现类也能注册多个不同配置的实例。排查时至少同时记录:Bean名称、声明类型、实际类型、配置来源、是否代理、作用域。只打印getClass().getName()遇到代理类时通常还不够。

2. 五条常用注册入口

入口 谁产生定义 适用场景 易错点
@Component及派生注解 组件扫描器 自己维护的业务类 类必须处于扫描范围
@Bean 配置类解析器 第三方客户端、按参数装配 工厂方法直接互调受配置模式影响
@Import 配置类或选择器等 模块能力开关 导入注解本身只是入口
XML bean定义 XML读取器 旧项目、RPC配置 XML也可能引入外部资源
注册器/后处理器 基础设施代码 Mapper代理等 接口无需普通构造器也能成为Bean

项目启动入口ErpItemWebApplication〔本地文件〕同时使用扫描、@ImportResource、@MapperScan和多种@Enable...。这说明该应用的依赖图不是只有@Service。例如Mapper接口背后通常是扫描器登记工厂Bean,再由工厂生成数据库代理。看不到实现类不意味着Spring凭空实现了SQL。

@Controller、@Service、@Repository均具有组件语义,但它们表达不同职责。@RestController还组合了响应体语义。@Repository可以参与异常转换,前提是相应基础设施存在且访问技术支持;不能把它理解成“自动连接数据库”。

3. 依赖解析到底选择谁

下面是教学片段,完整可执行机制实验见实验室。

public interface FreightQuote {
    long quoteInCents(long weightInGrams);
}

@Service
public class ShipmentService {
    private final FreightQuote freightQuote;

    public ShipmentService(@Qualifier("contractQuote") FreightQuote freightQuote) {
        this.freightQuote = freightQuote;
    }
}

常见的单值注入先根据类型寻找候选,再结合限定条件、Primary等规则确定对象;具体解析还涉及依赖名称、优先级、泛型、容器版本及自定义候选解析器,不应背成一个所有场景通用的机械顺序。关键是将歧义写清楚:@Qualifier表达此位置需要的候选范围,@Primary表达多个候选存在时的优选默认。

如果所有运费策略都应该参加计算,用List<FreightQuote>或Map<String, FreightQuote>更合理;如果只有一个策略应该参与,注入整个容器再遍历猜名字反而使业务隐含依赖。集合的顺序需要明确约定,不能把源码文件顺序当运行顺序。

单构造器在Spring 4.3及以后通常无需额外写@Autowired。构造器让必需依赖在对象建立时就有效,也方便普通JUnit测试。字段注入使实例创建和可使用状态分离,自己new出来的对象字段仍为null。Setter适合真正可选、允许晚绑定的协作对象,而不是用来隐藏必须解决的循环。

@Resource常用于按指定名称取得对象,其默认名字及类型回退与@Autowired不同;javax.annotation和jakarta.annotation又属于不同版本生态。维护现有Boot 2应用不要随手复制Boot 3的import。必需依赖写明确,错误在启动时暴露,通常比上线后某条路径才NPE便宜。

4. 配置类的两个模式

@Configuration(proxyBeanMethods = false)
public class ExportConfiguration {
    @Bean
    public ExportPolicy exportPolicy() {
        return new ExportPolicy(500);
    }

    @Bean
    public ExportService exportService(ExportPolicy exportPolicy) {
        return new ExportService(exportPolicy);
    }
}

这里以工厂方法参数取得容器里的依赖。proxyBeanMethods=false时,自己调用exportPolicy()就是普通Java方法调用,可能产生另一个实例;不能依靠该调用获取容器单例。传统full配置类通过增强拦截符合条件的@Bean方法调用,使它们遵从容器语义。采用参数注入可以避免业务代码依赖这种特殊调用行为。

要区分“工厂被调用一次”和“对象天然全局唯一”。singleton默认是在一个容器里按Bean定义共享;同一进程两个ApplicationContext、两个Bean名字、两个服务实例,都可能有各自对象。数据库连接池、缓存和线程池如果重复注册,资源消耗也会重复。

5. 作用域、延迟创建与Provider

singleton适合无请求状态的服务;prototype每次向容器请求通常创建新实例;request绑定一次Web请求;session绑定会话。把prototype直接注入singleton构造器,只会在该singleton建立时取一次,之后字段一直指向同一个对象。想每次操作获取一个新实例,可以注入ObjectProvider<Worker>并在业务边界调用getObject()。

这不是建议用prototype解决所有并发问题。大多数业务处理器应当保持无状态,将请求数据作为参数传递。大量短命Bean也有创建和依赖解析成本。request scope通过作用域代理延迟取得当前请求对象时,离开Web线程或异步边界未必还能取得合法上下文。

@Lazy可推迟真实对象创建,减少启动时工作,但也把缺失配置、连接失败等问题推迟到首次请求。对于必需的核心能力,应有受控的预热或就绪检查,不能把“启动快了”当“系统可用了”。

容器通常不负责prototype对象完整的销毁生命周期;如果它持有文件或套接字,要由调用者明确释放。最好的方案往往是不让短命业务对象直接拥有昂贵资源。

6. 循环依赖揭示的设计问题

订单服务依赖库存服务,库存服务又依赖订单服务。如果两者都通过构造器要求对方,谁也无法先完整构造。部分单例字段或Setter循环在特定配置下可以通过提前引用解决,但有条件、受代理影响,并非所有版本默认允许。Boot 2.6起默认限制循环引用,不能用其他项目的成功经验推断这里一定能启动。

设计上应先问:库存扣减为什么需要整套订单服务?如果只需要订单号与数量,传入命令即可;如果需要编排,新增上层CheckoutUseCase同时调用两者;如果需要通知完成,考虑事件,但事件会引入交付和一致性问题,见13章。通过@Lazy或允许循环引用临时解除启动阻塞,不能替代边界重构。

所谓三级缓存主要解释部分singleton循环依赖与提前代理引用的实现,不是业务缓存,不是Redis三级架构。没有理解“未初始化对象被提前暴露”的风险,死背三个Map的名字并不会提升系统设计能力。

7. 项目追踪:从接口走到真实实例

看AsyncTemplateConfig〔本地文件〕:配置类用Lombok生成构造器,接收AsyncResultStorage,再通过@Bean返回AsyncTemplateImpl。读懂这段应继续追踪三个问题:存储接口由哪个实现提供;该实现来自源码还是依赖包;哪些条件和环境选择了它。

可以从项目目录运行只读检索:

rg -n 'implements AsyncResultStorage|AsyncResultStorage|@Bean' erp-index
rg -n '@ComponentScan|@Import|@MapperScan|@ImportResource' erp-item/erp-item-web

找不到实现时明确记为“可能来自依赖,尚未核实”,不要把接口名当事实。例如叫RedisStorage不证明部署一定使用Redis,叫Async也不证明线程切换真的发生。

8. 性能与安全检查

容器装配通常发生在启动期,HTTP慢时优先检查数据库、远端、队列和锁,不要未经测量归咎于依赖注入。真正值得警惕的是每次请求创建客户端、意外注册多个池、初始化阶段全表加载、延迟创建触发首次请求阻塞,以及singleton保存用户状态。

组件扫描范围过大可能误纳测试配置或不应启用的模块。扩展点能读取配置并执行代码,来自不可信依赖的自动装配不是纯数据;依赖治理和配置来源都属于供应链边界。本课程不会扫描或展示业务密钥。

9. 练习与参考答案

  1. 两个Repository实现都能注入,给其中一个标Primary是否总是正确?只有它确实是合理默认时才正确;不同场景选择不同实现应在注入点用Qualifier或策略选择表达,不能用Primary掩盖错误扫描。
  2. 给singleton注入prototype后,为何请求间仍共享同一实例?依赖仅在singleton构造时解析一次。需要时用Provider重新获取,或更直接地改为无状态服务加方法参数。
  3. @Bean方法上加事务能否保护返回对象的后续调用?不能如此推导。创建对象的工厂调用和对象业务方法是两个边界,事务应放在明确的业务入口并验证代理路径。
  4. 把new Service()改成@Autowired后测试变复杂,说明什么?通常说明业务类依赖过多、依赖类型过于基础设施化。先手工构造一个可测试的小用例,再决定由容器装配哪些对象。

资料:Spring 5.3 Core容器文档。实证:实验室IocTest验证手工DI、候选选择、作用域及生命周期,不验证业务starter。

原始文档 · spring-course/03-容器生命周期与扩展点.md

03 容器生命周期与扩展点

对象何时创建、何时能调用、谁负责关闭资源,直接决定ERP是否能稳定发布。一次容器刷新不是简单地遍历类然后new;定义解析、依赖建立、对象初始化和代理包装相互影响。本章重点是从启动问题追到资源责任,避免把启动成功误认为业务已经可用。

1. 从容器级别看refresh

常见ApplicationContext刷新过程可以按职责理解为:准备环境和BeanFactory→执行定义级后处理器→注册对象级后处理器→建立事件和其他基础设施→初始化剩余非延迟单例→完成刷新。具体子类、Web容器及版本会加入额外步骤,这个顺序图用于建立定位坐标,不替代源码调用栈。

定义级扩展点看到的是“准备创建什么”;对象级扩展点看到的是“已经创建出来的对象”。把两者混用会提前触发不该创建的Bean,导致它没有经过完整后处理器集合,最终出现“某个对象没有事务代理”的难查问题。

扩展点 主要操作对象 典型用途 主要风险
BeanDefinitionRegistryPostProcessor 定义注册表 批量登记Mapper等定义 注册冲突、提前取Bean
BeanFactoryPostProcessor 定义与工厂元数据 修改属性、解析配置 误触发对象实例化
BeanPostProcessor 实例 注入、包装、增强 把每个业务类都纳入昂贵处理
InitializingBean / initMethod 当前对象 验证配置、完成初始化 长时间阻塞启动
SmartLifecycle 可启停组件 协调消息消费等生命周期 停机回调失约导致超时

2. 单个Bean的典型生命周期

普通单例的教学顺序是:选择构造器并创建实例→填充属性→部分Aware回调→初始化前后处理→初始化方法→初始化后处理(可能返回代理)→供调用者取得→关闭时销毁。@PostConstruct由相关后处理器触发,处在初始化阶段;InitializingBean.afterPropertiesSet()和自定义init方法通常随后执行。某些实例化感知处理器能更早介入,因此不要把这张简图背成所有Bean无例外的完整实现。

前端类比可以帮助起步:构造函数类似创建组件对象,初始化类似挂载后准备资源,销毁类似卸载清理。但后端初始化通常只发生一次,对象之后长期并发运行;一次初始化泄漏的线程可能影响整个进程生命周期。

原始对象构造
  → 依赖注入
  → 初始化回调
  → 可能返回代理对象
  → 外部调用进入代理

为什么不建议在@PostConstruct里调用自己的@Transactional方法?因为此时是对象初始化路径,而且自身方法调用通常绕过外部代理。即使应用启动后注入的是代理,也不能反推初始化中的那次调用经过代理。需要事务性初始化时,应设计独立、明确受控的执行入口,并处理重复启动与多实例竞争。

3. 看真实线程池的创建位置

AsyncTemplateConfig〔本地文件〕在afterPropertiesSet()创建线程池字段,再由@Bean方法创建AsyncTemplate。它展示了初始化回调可以承担装配工作,但池自身不是在这段代码中以独立@Bean返回的。

由此不能直接宣称项目一定泄漏线程:其他组件或包装器可能负责关闭。正确审查路径是查找谁持有真实执行器、谁实现close或destroy、Spring关闭时会调用谁,以及未完成任务的状态由谁收敛。资源所有权无法明确指向一个对象,才是需要进一步核查的信号。

ScmDistributorItemThreadConfig〔本地文件〕在@PostConstruct中给static执行器赋值。static并不服从某个ApplicationContext的单例边界。测试里创建第二个容器可能覆盖字段,旧执行器仍被任务引用;关闭一个容器也不自动说明static资源已关闭。应将进程级全局状态与容器所有权分开审查。

4. 生命周期友好的资源装配

下面是独立教学模式,参数仅用于说明,不是生产推荐值:

@Configuration(proxyBeanMethods = false)
public class WorkerConfiguration {
    @Bean(destroyMethod = "shutdown")
    public ExecutorService exportExecutor() {
        return new ThreadPoolExecutor(
            2, 2, 30, TimeUnit.SECONDS,
            new ArrayBlockingQueue<>(16),
            new ThreadPoolExecutor.AbortPolicy());
    }
}

这样至少明确了关闭责任,但shutdown()只停止接收新任务并让已有任务继续执行,不保证关闭钩子会等到业务结果持久化。完整优雅停机需要:入口停止接单→就绪探针下线→消费者停止抢任务→等待受预算约束的在途任务→释放数据库和客户端资源→超时任务由租约或重试接管。

顺序非常重要。如果连接池先关闭,工作线程随后提交最后一批数据就会失败;如果HTTP先继续接单而执行器已关闭,用户会收到随机失败。复杂组件可采用SmartLifecycle分阶段协调,销毁顺序仍需结合实际依赖图及运行容器验证。进程被强杀不会保证这些回调执行,因此恢复能力必须依赖持久状态。

5. BeanFactory与FactoryBean别混淆

BeanFactory是容器服务接口,负责取对象、检查定义等;FactoryBean是某个Bean用来生产另一个对象的机制。取得普通名称时通常拿到工厂产品,使用&前缀才拿到工厂本身。MyBatis等集成利用这种机制向容器提供接口代理。

理解这一点能避免两个调试误区:第一,配置里注册的是工厂,却拿业务接口的构造器去找实例化位置;第二,误把产品作用域与工厂对象作用域当成一回事。遇到代理、FactoryBean、装饰器同时存在时,先画对象链,再决定在哪一层加日志或替换测试对象。

6. 事件与就绪不是同一时刻

Spring容器刷新事件、Boot启动事件、Runner执行及Ready事件有不同语义。ApplicationRunner或CommandLineRunner适合受控启动动作,但不能无限制扫描业务表,也不能把非必要远端故障变成整个服务无法启动。Runner抛异常可能使启动失败,是否需要这种失败策略必须事先决定。

“监听到Ready就发送消息”也不等于消息可靠交付:进程仍可能在发送前崩溃。项目启动类在run返回后还有发布通知相关逻辑,这也是本课程不直接启动业务应用的原因。实验使用独立Context,不触发项目的环境和通知副作用。

应用就绪检查应回答“本实例现在能处理它声称提供的业务吗”,而存活检查回答“是否需要重启这个进程”。短暂数据库抖动同时让所有实例存活探针失败,可能触发重启风暴。数据库不可用时拒绝特定请求、保留诊断能力,与把整个进程杀掉是不同决策。

7. 源码阅读练习:后处理器如何工作

读Spring源码时,可按AbstractApplicationContext.refresh进入,再定位AbstractAutowireCapableBeanFactory的创建与初始化流程。不要一开始就追所有分支;先用实验室的生命周期列表观察实际顺序,再对照每个记录点。

写自定义BeanPostProcessor时应让无关Bean快速通过;如果每次处理都扫描整个类路径或访问远端,启动复杂度可能随Bean数量成倍放大。后处理器的依赖也应尽量简单,避免引入大半个业务图并造成提前实例化。

初始化阶段读取一次配置形成不可变对象,是一种常见方案;动态配置则需要原子替换快照和版本记录。不要让多个配置字段分别更新,导致请求读到“新超时+旧重试次数”的中间组合。动态配置深入见14章。

8. 故障推演与答案

场景一:发布卡在启动,CPU低。 先看线程栈是否停在远端连接、配置中心或初始化数据库查询;再看超时是否有上界。CPU低不能证明没有瓶颈。启动日志中最后一个Bean不一定就是根因,应取得调用栈和等待资源。

场景二:测试单独运行通过,整套运行后挂住。 检查Context是否close,执行器是否shutdown,static字段是否留存、测试是否共享端口或文件。线程泄漏比简单地增加测试超时更值得查。

场景三:给方法加事务,初始化仍部分写入。 先确认初始化是否调用自身方法、是否经过代理,以及资源是否受同一管理器控制;不要先调隔离级别。

场景四:销毁回调执行了,仍有一笔导出消失。 销毁回调只覆盖正常关闭;任务应先有持久化记录,执行中有租约,发布后能重新发现可恢复状态。

实验室IocTest验证典型初始化前后回调与销毁顺序。实际生产生命周期还涉及RPC、调度器、容器和私有starter,需要集成环境补充验证。Spring 5.3容器扩展点是本章机制参考。

原始文档 · spring-course/04-SpringBoot启动自动配置与配置管理.md

04 Spring Boot启动、自动配置与配置管理

Spring提供容器和编程模型,Spring Boot提供常用应用的装配约定、依赖管理和启动支持。把“Spring会注入对象”和“Boot根据条件帮你注册对象”分开,才能排查项目为何启动、某个Bean为何存在、另一环境为什么行为不同。本章结合本目录的Boot 2时代应用;升级到Boot 3及以后需要另做兼容性核验。

1. 从main到可服务请求

启动大体包括准备Environment、建立ApplicationContext、加载配置来源、刷新容器、建立Web服务器及相关组件、执行Runner、发布相应启动事件。具体事件顺序以使用版本为准。SpringApplication.run不是单纯返回一个服务器端口;其间任何自定义初始化都可能访问配置、网络或数据库。

项目ErpItemWebApplication〔本地文件〕组合了扫描包、自动配置排除、Mapper扫描、缓存、事务、XML和私有能力注解。分析启动故障应将这些入口展开为依赖树,而不是看到@SpringBootApplication就认为全部行为来自Boot默认配置。

2. 自动配置是有条件的定义注册

@SpringBootApplication组合了配置类、组件扫描和自动配置等能力。自动配置通常判断classpath有没有某类、用户是否已经定义某个Bean、属性是否开启、当前是否是某种Web应用,然后登记默认组件。

例如“classpath存在数据库驱动”只满足部分条件;是否有DataSource、URL来源、是否有用户配置替代、是否被排除,都决定最终结果。starter是依赖与自动装配的分发形式,不是运行时远程服务,也不保证所有组件都会启用。

Boot 2.3常见的自动配置候选登记依靠META-INF/spring.factories;Boot 2.7开始支持新的AutoConfiguration.imports方式,跨版本不能照搬文件位置。项目本身与私有starter可能年代不同,应从实际解析后的依赖版本判断。

3. 条件判断不能当注解口号背

条件 想表达的约束 读代码时继续追问
ConditionalOnClass 某类可见 类来自哪个依赖、版本冲突了吗
ConditionalOnMissingBean 用户未提供替代 检查的类型/名字是什么、处理顺序如何
ConditionalOnProperty 属性符合约定 属性来自哪里、缺失时默认如何
Profile 某环境分组激活 实际激活列表是否符合预期
ConditionalOnWebApplication 应用类型符合 Servlet和Reactive是否混用

ConditionalOnMissingBean不是线程间动态检查,也不是请求时每次择优;它发生在配置阶段并依赖已处理的定义。给自己的业务Bean随意堆条件可能造成环境分叉,应该为关键组合写Context测试。

项目排除了RedisAutoConfiguration,只能证明不采用该默认配置入口,不能证明不使用Redis。Redisson、私有starter或手工@Bean都可能提供Redis能力。同理,启动类加了@EnableCaching只说明启用缓存注解基础设施,具体缓存提供者、键与TTL仍需查配置。

4. 配置覆盖是一条来源链

默认值、配置文件、profile文件、环境变量、系统属性、命令行等存在优先级;Boot版本与外部配置系统又会影响加载方式。排查时不要仅看仓库中的application.yml:运行时值可能被环境覆盖。正确证据包括最终值、来源、实例、配置版本和生效时间,敏感字段只记录来源或指纹。

Boot 2.4引入的Config Data机制与较早配置加载模型有差异,Spring Cloud的bootstrap上下文及私有配置中心还需独立确认。不能在一个Boot 2.3项目里直接套用Boot 2.7文档的所有加载细节。

环境标签不是安全边界。名叫dev的profile如果引用了正式服务地址,依然会影响真实环境。本课程只运行独立实验,不复制业务配置启动服务。

5. 用类型化配置建立约束

以下教学片段使用Boot 2的javax.validation生态,需要相应校验依赖和属性扫描/启用配置:

@Validated
@ConfigurationProperties(prefix = "erp.export")
public class ExportProperties {
    @Min(1)
    @Max(5000)
    private int batchSize = 500;

    @Min(1)
    @Max(32)
    private int concurrency = 2;

    public int getBatchSize() { return batchSize; }
    public void setBatchSize(int batchSize) { this.batchSize = batchSize; }
    public int getConcurrency() { return concurrency; }
    public void setConcurrency(int concurrency) { this.concurrency = concurrency; }
}

这些范围仅为教学约束;实际最大值由资源预算决定。配置还需要跨字段校验,例如“并发×每任务最大连接需求不超过分配给导出的连接预算”,单字段合法并不代表组合安全。

@Value适合少量独立属性;成组参数用ConfigurationProperties更易校验、测试和生成元数据。不要把配置读取散布在几十个业务类里,否则一次单位调整会造成秒/毫秒混用。时间、大小应使用类型和明确单位,记录默认值与回滚值。

6. 配置热更新是一个小型发布系统

动态更新线程数、超时、路由或限流规则并非简单set字段。需要处理解析失败、非法组合、部分实例未应用、旧任务仍按旧参数运行和回滚。建议先解析完整候选快照,再校验,然后原子替换引用,保留最后成功版本与错误原因。

改变队列容量通常不能简单修改既有ArrayBlockingQueue;更换执行器又涉及旧队列排空及资源回收。变更前应明确哪些参数可原位调整,哪些必须新建资源并做交接。否则“调小并发”可能短期同时运行新旧两个线程池,真实并发反而翻倍。

读项目NacosDbDegradeImpl〔本地文件〕时,应分别检查空配置、解析异常和成功加载行为。控制台显示发布成功,只证明配置服务接受了请求,不证明每个实例已应用。14章进一步讨论降级规则。

7. 版本和依赖的工程判断

本目录包含不同项目,不应说“整个ERP都是Spring某一个版本”。例如admin的Boot依赖管理与item的旧式依赖基线不同;私有父POM还可能覆盖传递依赖。读取POM得到的是声明线索,Maven依赖树或effective POM才更接近实际解析结果,但执行它们可能需要下载私有依赖,不能编造解析结果。

Boot BOM用于协调依赖版本,并不保证你手动覆盖的库也兼容。升级不是只改版本号:Java最低版本、javax到jakarta、Security配置API、循环依赖默认行为、路径匹配、序列化和监控端点,都可能改变。应逐项做契约、集成和启动矩阵测试。

实验室固定Spring 5.3.39用于解释既有代码机制,不包含Boot自动装配测试,也不构成“这个版本适合新生产系统”的建议。生产选型需要单独核对当前支持期限和安全更新。

8. 常见启动诊断路径

没有Bean: 先看扫描与导入,再看条件是否匹配,再看定义是否被排除;不要直接在全部类上加@Component。

有多个Bean: 列出名称、来源、预期职责,再决定Qualifier、Primary或减少重复注册;不要单纯打开Bean覆盖来隐藏冲突。

端口已监听但请求失败: 检查就绪与依赖可用性,是否首次延迟初始化、是否配置应用落后。端口监听是网络事实,业务就绪是更强的结论。

生产慢而本地快: 核对实际连接池、超时、代理、日志级别及数据规模,避免只对比源码。不要通过公开环境端点来“方便排查”;诊断接口必须授权且敏感值脱敏。

9. 练习与答案

  1. 排除Redis自动配置以后仍能连接Redis,是否矛盾?不矛盾,检查其他注册入口。
  2. 配置中心把批量大小从500变成50000,服务没有重启就安全吗?不安全,内存、SQL包大小、锁持有时间和失败重放成本都会放大,必须校验和灰度。
  3. 所有实例的配置版本一致是否代表行为一致?还需检查代码版本、旧资源是否排空、连接和缓存是否刷新,以及实例是否实际执行新配置。
  4. 为什么不在教程里统一升级所有业务POM?教程目标是理解现状,升级需要独立兼容性、服务依赖及回归验证,本次未修改业务代码。

参考:Boot 2.7.18 Reference。对本目录较旧Boot项目,遇到版本差异应回查相应版本文档及依赖声明。

原始文档 · spring-course/05-AOP动态代理与注解生效边界.md

05 AOP、动态代理与注解生效边界

图解 · 可横向查看
事务代理:外部进入与this自调用是两条不同路径时间从上到下;虚线箭头表示返回。this.inner()不重新进入代理;但可能仍处于外层已经开启的事务内。;没有外层事务时,自调用不会仅凭内部@Transactional注解创建新事务。 事务代理:外部进入与this自调用是两条不同路径调用者Spring代理目标Service数据库外部调用方法开始或加入事务调用目标方法this.inner()执行同线程SQL结果 / 异常返回按规则提交回滚返回调用者this.inner()不重新进入代理;但可能仍处于外层已经开启的事务内。没有外层事务时,自调用不会仅凭内部@Transactional注解创建新事务。
事务代理调用时序:自调用不重新触发增强

图示为教学简化,需结合下文的适用条件、故障窗口和项目证据阅读。

本章面向已经理解“容器创建对象,再把依赖交给对象”的前端开发者。我们要继续回答:注入进来的对象为什么有时不是自己写的那个类?为什么代码上明明有注解,事务、权限或数据源选择却没有发生?主线是 ERP 的从库查询和数据权限,不把注解当作魔法。数据库路由的背景请衔接 数据库第10章:主从复制与读写分离,本章只解释 Java 调用如何触发这些能力。

阅读与验证说明。 示例按 Java 8、Spring Framework 5.x、Boot 2.x 的同步代理模型编写;代码块标为“教学”的均不是对业务代码的修改。已静态阅读下列源码,未启动应用、连接数据库、Redis、配置中心或业务接口。erp-item 的 POM 第32行〔本地文件〕 声明的是 Boot Maven 插件版本,不能据此认定运行时 Framework 版本;erp-admin 的 BOM 导入〔本地文件〕 也只是依赖管理输入,仍需结合有效 POM、解析依赖和启动进程确认。本文引用的 Framework 5.3.39 源码用于解释机制,不宣称生产正在运行这个补丁版本。

1. 从前端函数包装理解代理,但不要停在类比

在 JavaScript 中,可以把请求函数包装成 withTiming(withAuth(loadStock)):调用先经过计时器,再经过权限检查,最后执行查询,返回时沿相反顺序退出。AOP 的重要价值也是把横切逻辑从每个业务方法里抽出来。不过 Java 里的 Spring AOP 不是把每个方法源码自动改写。通常是容器保留一个目标对象,再向调用者暴露代理对象;代理决定这次调用匹配哪些增强,然后把调用交给目标。

这里 IoC、DI 与 AOP 连成了一条链。组件扫描或 @Bean 先产生 Bean 定义;容器实例化对象、注入依赖;自动代理创建器作为 Bean 后处理基础设施评估候选增强,在正常初始化流程中包装适用对象。其他 Bean 通过容器拿到的引用通常是代理。因此,“把对象交给 Spring 管理”和“调用经过 Spring 暴露的引用”是两个独立前提。你自己 new StockReader(),即使类上有 @Component,新出来的这个实例也不会自动接受容器代理。

注解本身只是元数据。@Retention(RUNTIME) 让运行时能够读取;@Target(METHOD) 限制能写在哪里;真正执行行为的是读取它的处理器。例如事务基础设施把事务注解解析成传播、隔离和回滚规则;自定义切面把标记匹配到拦截链。没有消费者的自定义注解,只是编译器允许贴上的标签。不要把 @Aspect 与 AspectJ 字节码织入混为一谈:Spring 可以读取 AspectJ 风格注解,却仍然采用自己的代理机制。

仓库中的 UseSlaveDataSource 定义〔本地文件〕 同时允许标在类和方法上,并保留到运行时。随后 SlaveDataSourceAspect〔本地文件〕 同时声明 @Aspect 和 @Component,前者提供切面元数据,后者使它有机会被扫描成 Bean。是否真的扫描到、是否启用了代理基础设施,还要看所在应用上下文;仅搜索到两个注解不能替代运行验证。

2. 一次调用究竟经过什么

先建立最小词汇:目标对象负责业务;连接点是可被拦截的执行位置,在 Spring AOP 中主要是方法执行;切点决定哪些执行匹配;增强是匹配后执行的逻辑;Advisor 将匹配条件与增强结合。多个增强组成链,而不是多个无关的后台监听器。

可以阅读官方固定版本的 ReflectiveMethodInvocation。它保存当前位置并在 proceed() 时推进到下一个拦截器,链尾调用目标。由此得到一个重要工程结论:环绕增强必须清楚自己是否继续执行。少调用一次 proceed() 可能使库存操作完全不发生;调用两次可能重复扣库存;捕获异常后返回空值可能让外层事务误认为操作正常完成。

// 教学:业务计时只观察结果,不改变调用次数和异常语义。
@Aspect
@Component
public class StockTimingAspect {
    @Around("execution(public * demo.stock.StockReader.*(..))")
    public Object time(ProceedingJoinPoint point) throws Throwable {
        long begin = System.nanoTime();
        try {
            return point.proceed();
        } finally {
            long elapsedNanos = System.nanoTime() - begin;
            // 记录固定方法标签、耗时和结果分类;不要序列化全部参数。
            recordDuration(point.getSignature().getName(), elapsedNanos);
        }
    }
    private void recordDuration(String method, long nanos) {
        // 教学留空:实际接入有界指标系统,不在这里同步调用远端日志服务。
    }
}

这里用单调时钟测量耗时,因为系统墙上时间可能校准;finally 保证失败也计时,但真实指标实现还应保证自身失败不会覆盖原始业务异常。不要把用户编号、商品编号放进指标标签:千万商品会造成时间序列基数膨胀。诊断某个具体商品应使用受控、脱敏、采样的日志或链路字段,指标只保留操作类型、结果类型等低基数维度。

3. JDK 和 CGLIB 的边界必须逐个解释

JDK 动态代理实现目标所暴露的接口,调用者通过接口引用进入代理。它不是目标实现类的子类,所以把 JDK 代理强转为实现类可能失败。CGLIB 则生成目标类型的子类,用可覆盖的方法参与代理。final 类不能被这样继承,final 方法不能被覆盖,private 方法也不是可覆盖入口。不要把“JDK 代理可以代理接口”误读成“接口实现方法如果是 final 也一定不可拦截”:JDK 代理拦截的是接口入口,与 CGLIB 的覆盖限制不同。

纯 Framework 的常规选择与 Boot 自动配置要分开。Boot 2.3.3 官方说明,其 AOP 自动配置默认使用 CGLIB,并可通过 spring.aop.proxy-target-class=false 改变;这依赖自动配置生效,不能用它替代具体 Bean 的检查。见 Boot 2.3.3 AOP。仓库 ApplicationConfig〔本地文件〕 设置的是 exposeProxy=true,它并不等价于“所有 Bean 都是 CGLIB”。

对教学 Bean 可以执行以下只检查类型的代码;不要顺便打印整个对象,某些对象的 toString() 会暴露连接配置。

Object bean = context.getBean("stockReader");
boolean proxied = AopUtils.isAopProxy(bean);
boolean jdk = AopUtils.isJdkDynamicProxy(bean);
boolean cglib = AopUtils.isCglibProxy(bean);
Class<?> businessType = AopUtils.getTargetClass(bean);
// 在隔离实验中断言这些值,再验证一次真实入口调用是否触发增强。

看到代理仍不足以证明某个方法增强生效:Bean 可能因为缓存增强被代理,而从库切点没匹配。方法上的注解可能位于接口、实现类、桥接方法或组合注解上,不同消费者的解析策略也不同。框架事务注解的解析能力不能直接推广成自定义 method.getAnnotation(...) 的能力。编写自定义解析器时,应明确最具体目标方法和组合注解规则;最稳妥的教程实验先把注解放在具体实现的 public 方法上,减少歧义,再逐项测试接口声明和继承。

4. 自调用为什么绕过增强

下面代码是反例。即使 load() 从外部通过代理进入,执行到目标对象内部时,this.loadFromReplica() 仍是普通 Java 调用,不会重新穿过代理。切换 CGLIB 不能解决这个问题。

@Service
public class BadStockReader {
    public String load() {
        return this.loadFromReplica();
    }
    @UseSlaveDataSource
    public String loadFromReplica() {
        return "teaching-result";
    }
}

首先应按业务边界拆 Bean,让依赖关系直接表达需要经过的入口。下面 StockQueryService 编排查询,ReplicaStockReader 表达允许延迟的只读查询;容器注入后,后者引用可以是代理。注意这只是让代理有机会执行,不代表示例真的连接了从库。

@Service
public class ReplicaStockReader {
    @UseSlaveDataSource
    public String load() {
        return "teaching-result";
    }
}

@Service
public class StockQueryService {
    private final ReplicaStockReader reader;
    public StockQueryService(ReplicaStockReader reader) {
        this.reader = reader;
    }
    public String load() {
        return reader.load();
    }
}

也有人使用 AopContext.currentProxy(),仓库确实开启了代理暴露,但这依赖当前线程正在经过启用暴露的代理调用;普通线程、初始化阶段和异步任务不能随意取到它。自注入又会引入循环依赖和生命周期复杂性。因此它应是有明确理由的兼容手段,而不是所有自调用的标准答案。若必须增强内部执行,可以研究 AspectJ 编译期或加载期织入,但那是另一套构建、部署和排错模型,不能仅加一个注解就宣称已实现。官方 代理机制说明 对自调用边界仍有相同约束。

5. 从库切面:顺序、上下文和真实执行端

仓库切面的主体先调用 useSlaveDataSource(),再 proceed(),最后 clearDataSourcePreference()。它直接做的是修改线程上下文,不是现场换一根 JDBC 连接。SlaveDataSourceHelper 第9行〔本地文件〕 的存储是 ThreadLocal<Boolean>,查询未设置时返回 false,清理时执行 remove。

继续追踪消费者,会到 HintInterceptor.needForceSlave〔本地文件〕。该方法先检查配置是否存在、开关和排除条件,再检查请求参数是否指定主节点;轮询注释分支也位于线程标记之前,到 第119行〔本地文件〕 才读取标记。因此准确说法是“注解影响 SQL hint 决策的一项输入”,而不是“注解无条件强制一切 SQL 走从库”。数据库是否接受 hint、事务期间如何处理、连接端点是什么,均未在本次静态阅读中验证。

@Order(1) 的注释表明作者想让路由发生在事务开始之前。对于同一条适用增强链,较小顺序值先进入、后退出;事务 Advisor 默认优先级较低时,可形成“路由设置→事务开始→业务→提交或回滚→路由清理”。但若外层事务早已获取并绑定连接,内层方法再设置标记不会凭空产生一笔新事务。在 JDBC 路由数据源模型中也不能假定已绑定连接自动替换;本仓库还涉及 SQL hint,必须单独验证数据库行为。这一限制在 下一章 继续展开。

清理不等于恢复。设外层查询设置 true,内层又经过同一切面设置 true,内层返回 remove,外层剩余 SQL 读到的就是默认 false。这由现有 helper 和 finally 的组合可以推导,是否有真实嵌套调用触发尚需调用链实验。若业务允许嵌套覆盖,教学改造应保存旧值并在退出时恢复,而不是一律清空:

// 教学替代设计:不是仓库现有 Helper 的 API。
public final class RouteContext {
    private static final ThreadLocal<Boolean> FLAG = new ThreadLocal<>();
    private RouteContext() {}
    public static Boolean current() { return FLAG.get(); }
    public static void restore(Boolean previous) {
        if (previous == null) FLAG.remove();
        else FLAG.set(previous);
    }
    public static <T> T withReplica(java.util.function.Supplier<T> action) {
        Boolean previous = FLAG.get();
        FLAG.set(Boolean.TRUE);
        try { return action.get(); }
        finally { restore(previous); }
    }
}

这里保留 null 是为了区分“没有上下文”和“显式主库”。不要在线程池任务之间共享可变上下文对象;普通 ThreadLocal 也不会自动跨线程传播。如果任务需要租户或追踪信息,应显式传递经过验证、最小化的上下文,在任务入口建立、finally 清理,不能把请求线程上的事务连接复制过去。

6. 权限切面与性能事故一起检查

DataScopeAspect 第58行〔本地文件〕 是方法注解驱动的前置增强,它先清空旧条件,再根据当前用户构造数据范围。它和从库切面的共同风险是“业务开发以为每条路径都经过标记入口”。直接调用 Mapper、自己 new 服务或新增一个没有注解的旁路,可能越过约定。代码中的权限条件还有首参数为 BaseEntity 的要求,不能把注解随便贴到任意参数结构上。授权必须在业务边界和查询条件共同落实,详见 第08章。

假设一个大商家导出百万条库存。错误方案是在 Controller 上贴从库注解、切面记录全部入参和返回值,并在事务内串行远程补充商品信息。结果可能同时出现堆内存膨胀、日志阻塞、事务占用连接、从库延迟和线程池上下文泄漏。代理本身那一点调用开销通常不是首要矛盾;决定吞吐的是增强里面做了多少工作,以及查询和业务执行持续多久。

更合理的教学设计是先验证导出权限和租户,再创建有唯一请求键的导出任务;工作线程按游标分批读取,只记录批次行数和耗时,输出写入受限文件流;导出读允许明确的陈旧窗口,扣库存与扣后核对则保持一致性要求。切面只承担短小、可预测的横切职责,不把海量序列化和远程调用隐藏在每次方法执行里。监控同时记录 p95/p99、连接等待、批次失败和副本延迟,才能知道“优化了路由”是否真的改善系统。

7. 练习与参考答案

练习一: public 方法 A 没注解,内部调用同类带从库注解的方法 B;把代理改成 CGLIB 是否足够?答案: 不足够。内部 this 调用不经过代理。把 B 拆到另一个容器 Bean 并经注入引用调用,再分别断言切面进入次数和 helper 值。不要以返回结果相同推断增强已执行。

练习二: 外层和内层都标从库,内层异常被外层捕获,外层还要查询。现有 finally 清理后是什么状态?答案: 内层 remove 后标记不存在,helper 返回 false;外层尚未结束也不会自动恢复 true。设计嵌套实验,分别观察进入外层、进入内层、内层退出和全部退出四个时点。若改为保存恢复,最后必须恢复到调用前的 null,而不是固定 false。

练习三: 为权限切面设置最小 order 是否就完成安全保障?答案: 没有。order 只影响匹配且经过代理的增强;它不能使漏掉的路由、Mapper 直调或未认证线程自动受保护。还要验证用户身份来源、方法调用边界及 SQL 中的资源归属约束。

练习四: 隔离实验应怎样证明切面稳定?答案: 用仅注册教学 Bean 的 AnnotationConfigApplicationContext,显式启用 AOP;对正常返回、异常、自调用、外部调用、嵌套和线程池复用各执行一次,记录固定事件列表并断言顺序;用无数据库的教学目标完成验证。性能实验再增加有界并发,确认观测代码本身没有同步远程依赖。本次文档工作没有执行这些 Java 实验,不能把练习预期写成实测结果。

8. 官方资料与本章交付边界

继续读 Spring 5.3 AOP 概念与配置,结合固定标签源码观察拦截链。迁移时另读 Boot 3.0 迁移指南:Java 17、Framework 6 和 Jakarta 命名空间属于新基线,不能直接放进 Java 8 示例。更高版本事务方法可见性也有变化,不能反向推导 Spring 5.x 的行为。

本章已完成原理、真实源码追踪、逐步示例、反例和练习答案。相对源码链接指向当前工作区行号,后续源码改动可能使行号漂移;这里的路由与安全风险是静态条件分析,不是对线上故障或漏洞可利用性的确认。

原始文档 · spring-course/06-Spring事务传播与数据一致性.md

06 Spring事务传播与数据一致性

事务是ERP后端的核心边界:库存、订单、资金和任务状态,必须明确哪些变化一起成功、哪些失败可以重试、哪些副作用需要补偿。先读数据库事务与MVCC和锁与库存并发,本章解释Spring怎样把业务方法连接到这些机制。

1. Spring管理边界,数据库执行事务

在常见JDBC本地事务模型中,事务拦截器找到指定的PlatformTransactionManager,开始或加入事务,把连接等资源与当前执行线程关联,调用业务,最后提交或回滚并清理资源。MyBatis-Spring或JdbcTemplate等需要参与同一资源管理机制,才能复用该事务连接。

@Transactional不是数据库的SQL关键字,也不会让任意网络请求一起回滚。一个方法同时操作MySQL、MongoDB、Redis和远程支付,本地JDBC事务最多覆盖它管理的连接资源。多种存储“都在一个方法里”只是Java控制流关系,不是原子性证明。

多个DataSource并存时要核对事务管理器与Mapper使用的数据源是否一致。读写路由也需要在获取事务连接前生效;外层已经绑定连接后再标从库,通常无法凭空替换该连接。具体分片或Hint实现仍需实测。

2. 声明式与编程式边界

@Service
public class ReserveStockService {
    private final StockRepository stockRepository;

    public ReserveStockService(StockRepository stockRepository) {
        this.stockRepository = stockRepository;
    }

    @Transactional(rollbackFor = Exception.class)
    public void reserve(ReserveCommand command) {
        int changed = stockRepository.decreaseIfEnough(command);
        if (changed != 1) {
            throw new InsufficientStockException();
        }
        stockRepository.insertReservation(command);
    }
}

这是业务结构示意,Repository与命令需要你按模型实现。调用方应通过容器代理调用public入口。rollbackFor=Exception.class扩大异常回滚范围,但仍不能撤销已经发送的远端消息。SQL层应以租户、SKU及条件更新保障业务不变量,而不是只在Java里先查后减。

TransactionTemplate适合在长流程中精确包住一小段数据库操作。项目StockComponentImpl〔本地文件〕在前置读取、分组处理后,在1427行附近〔本地文件〕使用模板更新库存。它让边界可见,但模板回调外读取是否处于更外层事务,要继续看调用链,不能只凭局部代码断言。

3. 七种传播行为按场景理解

传播 有现有事务时 没有事务时 适合讨论的场景
REQUIRED 加入 新建 同一用例的多个数据库步骤
REQUIRES_NEW 挂起原事务并新建 新建 需要独立提交的审计记录
NESTED 支持时建立保存点 通常新建 同一物理事务内局部回滚
SUPPORTS 加入 非事务执行 明确允许两种语义的只读操作
NOT_SUPPORTED 挂起 非事务执行 必须脱离事务的操作
MANDATORY 加入 抛异常 强制调用方建立事务
NEVER 抛异常 非事务执行 明确禁止事务上下文

REQUIRED产生多个逻辑事务范围,但可能共用同一物理事务。内层设置rollback-only后,外层即使捕获异常并正常返回,最终仍可能得到UnexpectedRollbackException;不能通过catch恢复已经标记回滚的共享事务。

REQUIRES_NEW是真正独立的事务范围:外层回滚,内层已提交的数据仍可保留。代价是外层资源挂起时仍可能占有连接,内层再申请连接。如果多个工作线程各持一条外层连接并等待新连接,连接池很容易被耗尽。它还可能访问外层尚未提交的数据或争夺同一行锁,产生等待甚至循环依赖。

NESTED不等于REQUIRES_NEW。典型JDBC实现依靠savepoint,内层“完成”仍等待外层最终提交;外层回滚会撤销其全部变化。是否支持取决于事务管理器和驱动,不能假定对JPA、Mongo或分布式事务同样成立。

4. 回滚规则是调用结果规则

在本课Spring 5.3基线,默认RuntimeException与Error触发回滚,checked exception默认不触发。实验室真实验证了受检异常默认提交以及显式rollbackFor回滚。新版本可能提供额外全局配置,本章不跨版本泛化。

代理开始事务
  → 业务抛RuntimeException
  → 业务自己catch并返回“失败结果”
  → 代理看到正常返回
  → 如果没有rollback-only,可能提交

这就是为什么不能把所有异常都吞掉再返回布尔值。若业务确实需要部分成功,应设计批次、子事务和结果表;若要求整体失败,应让异常越过事务边界或明确设置回滚状态。对同一方法自调用、异步线程、非受管对象,先判断事务是否存在,再谈回滚规则。

5. 隔离、只读和超时的真实边界

隔离级别主要约束数据库并发可见性;readOnly=true通常是给管理器/驱动/ORM的提示或优化信号,不是通用的安全权限。某些配置能在数据库层强化只读,但必须确认,不能靠它保护误写接口。

事务超时并不等于一个Java线程的硬截止定时器。超时如何传递到JDBC语句、数据库如何中断、在Java里做远程等待时是否被感知,都依赖具体实现。必须同时管理连接获取、SQL、RPC和整体请求预算。

隔离级别通常在创建新事务时应用;内层REQUIRED加入现有事务,不能仅靠注解就改变已有物理事务的隔离。对于读后写冲突,条件更新、唯一约束、版本号或锁的选择要结合业务不变量,不能机械地把全部事务升成SERIALIZABLE。

6. 事务长度如何放大系统成本

长事务不只是连接占得久。更新锁持有时间变长,并发冲突扩大;旧版本清理受影响;复制与故障恢复压力可能上升;失败重做成本更高。把一次百万行导出包进事务,可能获得某种一致读语义,却将数据库资源占用与用户下载速度绑定。

对于库存用例,可以将远端参数获取放在事务前,把数据库内的“校验版本、更新库存、写记录”放进短事务。但事务外读取可能过期,写入必须重新通过版本或条件保护;“缩短事务”不能以丢失一致性为代价。

项目对SKU排序获取多锁有助于减少顺序冲突,但锁存在开关与空客户端分支。Redis锁不能成为数据库唯一正确性边界。CASE批量增减是数据库内原子更新的形式之一,仍需验证业务事件唯一性、影响行数和非负库存条件。

7. 提交后事件与Outbox

在提交之后发通知,可以避免数据库回滚却通知成功的问题;但提交成功后到通知发出前进程崩溃,通知仍会丢。@TransactionalEventListener(AFTER_COMMIT)是进程内阶段绑定,不是持久消息系统。

需要可靠交付时,在同一数据库事务写业务数据和outbox记录,后台反复投递,消费者通过事件唯一键去重。投递成功与标记成功之间也可能崩溃,故通常设计至少一次投递加幂等消费。提交后监听器若还要持久化新业务写入,应明确新的事务边界,不能误以为旧事务还会再提交一次。

8. 幂等与重试:最容易漏掉的事务外问题

客户端超时不代表服务端回滚。可能数据库已经提交,但响应在网络上丢失。如果客户端重新扣库存,事务依然可以每次都原子地执行,业务却重复扣减。因此需要业务操作键,例如租户+订单+操作类型的唯一约束,并把去重记录与状态变化放进同一事务。

死锁重试也应在一个全新的事务尝试中执行,重试完整业务单元并设置次数、退避和总截止时间。不要在已被标记回滚的事务内部无限重试某条SQL。对未知提交结果,需要查询或对账确定,不要盲目重放非幂等动作。

9. 实验与答案

运行核心实验中的TransactionProxyTest,观察四组断言:外部代理调用与self调用;运行时异常回滚与绕过代理后的自动提交;REQUIRES_NEW独立提交;checked exception默认及显式回滚规则。

思考一:外层捕获内层REQUIRED异常为何仍失败?内层可能已把共享物理事务标成rollback-only,catch只改变Java控制流。

思考二:加大线程池后为何事务超时反而更多?并发申请连接和争抢行锁上升,每笔事务持有时间变长,形成更大的等待队列。

思考三:H2测试通过为何不能证明MySQL锁安全?事务代理属于Spring机制;锁范围、隔离实现、索引与执行计划属于数据库机制,必须在目标MySQL版本和表结构中验证。

参考:Spring 5.3事务文档、MyBatis-Spring事务。

原始文档 · spring-course/07-SpringMVC请求处理与接口契约.md

07 Spring MVC请求处理与接口契约

图解 · 可横向查看
请求调用链:身份、代理与数据库边界从客户端经授权和Controller进入事务代理,再到Mapper和数据库。远端资源不属于此本地事务。 请求调用链:身份、代理与数据库边界客户端输入DTO / 不可信租户参数认证与资源授权身份 → 租户 → 资源范围Controller参数绑定 / 校验 / 契约事务代理 → Service从代理进入才有该增强Mapper / JDBC参数绑定 + 租户谓词同一事务数据库资源条件更新 / 唯一键 / 提交外部调用事务边界:仅覆盖同一管理器实际参与的资源Redis、远端RPC、对象存储,不因写在同一个方法就一起回滚。HTTP不是唯一入口:RPC、消息、定时任务也必须落实授权与业务规则。
请求授权与数据库事务资源边界

图示为教学简化,需结合下文的适用条件、故障窗口和项目证据阅读。

前端通常从URL、JSON与状态码理解接口;后端还必须为每次输入分配线程、连接、内存和执行预算。MVC不是把JSON转成Java对象那么简单。本章从请求链路切入,解释注解如何参与分派,以及一个面向大数据ERP的接口应该如何限制工作量。

1. 一次请求经过哪些关卡

网络入口 / 反向代理
  → Servlet Filter链(可能包括安全过滤链)
  → DispatcherServlet
  → HandlerMapping选中处理器
  → HandlerInterceptor前置处理
  → HandlerAdapter调用Controller
  → 参数解析、转换、校验
  → Service代理及业务
  → 返回值处理 / 消息转换
  → HTTP响应

这是一条简化的Servlet MVC路径。异常可能在任何位置发生;未进入DispatcherServlet的过滤器异常,不一定由ControllerAdvice处理。流式响应已经提交之后也不能再随意把状态码改成JSON错误。

Filter擅长处理HTTP协议级工作、请求包装和认证链;Interceptor知道匹配到的处理器,可做请求级辅助逻辑;AOP作用于匹配到的Bean方法调用,可以覆盖HTTP以外的调用。不要把三者当可任意替换的“中间件”。

2. 请求注解背后有哪些组件

@RequestMapping及@GetMapping等参与映射注册,路径、方法、媒体类型都是契约的一部分。@PathVariable取得路径片段,@RequestParam处理查询或表单参数,@RequestBody通过HttpMessageConverter读取请求体。参数转换失败可以发生在业务方法调用之前。

@ResponseBody把返回值交给消息转换器,ResponseEntity还能表达状态与响应头。JSON字段名、时间格式、空值、枚举与精度不是内部实现细节;对前端而言它们就是公开API。改变ObjectMapper全局配置,会影响大量接口,应有契约回归。

Controller方法通常运行在请求线程上,调用一个阻塞Mapper会占用这个线程直到查询完成。返回CompletableFuture或使用Servlet异步可以改变等待模型,但若内部仍是阻塞数据库访问,数据库连接和工作线程并不会消失。

3. ERP列表接口先限制问题规模

一个查询只返回20行,也可能为了排序、关联、COUNT扫描大量数据。接口应表达允许的查询形状:时间窗口、状态集合、最大页大小、可排序字段、是否需要总数、是否允许跨租户汇总。前端给什么就查什么,会把数据库变成开放的计算资源。

下面是契约示意,不是对现有Controller的替换:

GET /api/orders?createdFrom=...&createdTo=...&limit=100&cursor=...

返回:
{
  "items": [...],
  "nextCursor": "opaque-value",
  "hasMore": true,
  "dataAsOf": "..."
}

tenantId应由可信认证上下文及授权选择得到,不能仅信任query参数。cursor应绑定筛选条件、租户、排序版本与有效期;可以签名防篡改,但签名不是授权,仍须在数据库谓词中限制租户。

对总数很贵的查询,可提供hasMore、延迟统计或估算值,但必须在产品契约中明确语义。不要把未计算的总数返回0,也不要为了“前端表格组件需要total”让每页执行昂贵COUNT。具体分页SQL见10章。

4. 状态码与业务码分开设计

GlobalExceptionHandler〔本地文件〕返回AjaxResult封装错误。这段代码提醒我们:JSON里的code字段不自动等于HTTP状态。HTTP状态取决于响应设置、注解和外层处理,审查时应以真实响应测试确认。

如果所有错误HTTP都返回200,网关成功率、浏览器缓存、重试器和监控可能无法正确理解失败。迁移旧接口时又不能直接改变已有客户端假设。因此先写清旧契约,再引入版本化或渐进兼容方案。

建议区分参数错误、未认证、无权限、状态冲突、过载、依赖失败和未知内部错误。对外消息应稳定且脱敏,内部日志保留traceId与根因。是否重试不能单靠“不是200”,应结合业务幂等性、状态和剩余预算。

5. 命令接口:前端防重不是幂等

创建出库单、提交采购、触发导出都可能重复:网络重传、用户多端操作、网关重试、服务端已提交但响应丢失。接口应支持一个业务幂等键,并明确同键同参数返回原结果,同键不同参数返回冲突。

POST /api/export-jobs
Idempotency-Key: client-generated-key

202 Accepted
Location: /api/export-jobs/{jobId}

202只表示已接受处理,不应在任务尚未可靠记录、执行器又可能拒绝时返回成功。最稳妥的接受点通常是持久任务记录已提交;后续抢占和执行可恢复。若只提交到内存线程池,进程退出就可能丢失,必须如实定义可靠性。

GET通常不应触发库存修改等业务副作用,因为浏览器、缓存和预取可能重复调用。日志和计量等附带行为不代表可以把非幂等业务写入放到GET。

6. 请求上下文与追踪

项目ProcessTraceInterceptor〔本地文件〕从header写入MDC,便于串联业务处理。这个类展示了写入点;是否存在全链路清理要继续查外层过滤器,不能只凭本类没有清理就宣称已发生串数据。

设计时应限制header长度、合法字符和日志输出格式。可由客户端提供业务追踪提示,但身份和权限不能来自任意可伪造header。线程池切换时,MDC默认也不会自动成为新任务的正确上下文,详见12章。

7. 大请求和大响应的资源账本

一次100MB的JSON上传不只是100MB:原始字节缓冲、字符解码、对象图、校验错误集合和日志复制可能形成多份驻留。要在入口限制body、集合数量、字符串长度和解析深度;应用级校验发生时,部分解析成本已经支付,所以网关与服务器限制同样重要。

响应也要考虑序列化:先查全表到List再“流式输出”并没有控制查询端内存。真正有界的路径是分页读取、有限对象转换、持续写出并及时释放。慢客户端下载可能长时间占据工作资源,更适合异步生成文件后提供受权下载。

远端调用、数据库超时、请求总超时应形成一个预算。客户端断开不保证服务端立即停止SQL,取消信号要明确传递,并且要处理“用户不等了但任务仍成功”的最终状态。

8. 接口测试应该断言什么

MVC测试不仅检查JSON字段,还要断言请求方法、媒体类型、参数边界、权限失败、状态码、响应头及错误脱敏。MockMvc可以验证MVC映射和部分过滤链;mock服务返回正常值不能证明数据库查询有租户条件,也不能证明真实序列化数据规模安全。

对于分页,应构造同一时间戳的多条记录,验证游标不漏不重;对于幂等,应并发提交相同键;对于授权,不能只测“未登录失败”,还要测已登录但访问其他租户的同结构ID。

9. 练习与答案

  1. 在Interceptor里加鉴权就覆盖所有访问吗?不能保证,RPC、任务和直接服务调用不经过MVC;HTTP安全也应正确接入安全过滤链和服务授权。
  2. 返回Future是否代表提高容量?只有资源等待与执行预算被正确控制才可能提升效率,阻塞下游容量没有因此增加。
  3. 把所有Exception转换成“操作失败”是否更安全?对外可以统一未知错误,但内部必须保留分类与追踪,否则监控和定位失效;同时不要泄漏原始异常消息。
  4. 列表total为什么可能比items更贵?COUNT常需处理整个符合条件的集合,分页结果只取一小段,两者执行计划不同。

机制参考:Spring 5.3 Servlet Web。本章接口片段是设计练习,未启动业务Web应用进行集成测试。

原始文档 · spring-course/08-校验异常序列化与多租户安全.md

08 校验、异常、序列化与多租户安全

ERP的安全不止登录。一个合法用户也可能查询不属于他的仓库、导出其他租户明细、修改只读字段或通过超大筛选范围耗尽资源。安全应贯穿请求、业务、SQL、任务和下载,而不是集中在一个注解上。本章将正确性、权限和性能作为同一个输入边界来讨论。

1. 四层校验各自负责什么

第一层是传输和结构:body大小、JSON格式、字段类型、长度与集合数量。第二层是字段语义:金额非负、数量正数、日期窗口合理。第三层是业务状态:订单是否可出库、库存是否足够、版本是否匹配。第四层是授权:当前主体是否可对这些资源执行该动作。

Bean Validation适合前两层及部分跨字段约束,数据库唯一约束、外键或条件更新负责最终并发不变量。只写@Min(1)不能保证并发扣减后库存不为负;只在Controller检查订单归属不能保证异步任务再次执行仍有权限。

@Valid常用于级联验证,@Validated支持分组以及相关Spring方法验证入口。方法验证仍需要对应后处理器等基础设施;Spring 5应用中的代理调用边界也要注意。注解存在不等于所有入口都执行验证。

2. DTO不是数据库实体的别名

将Entity直接作为请求体,容易让客户端设置服务端字段:tenantId、审核人、状态、删除标记、金额汇总等。应该针对用例定义允许输入的字段,由服务端填充身份和审计信息,再映射到持久层。

public class ReserveStockRequest {
    @NotNull
    @Positive
    private Long skuId;

    @NotNull
    @Min(1)
    @Max(10000)
    private Integer quantity;

    public Long getSkuId() { return skuId; }
    public void setSkuId(Long skuId) { this.skuId = skuId; }
    public Integer getQuantity() { return quantity; }
    public void setQuantity(Integer quantity) { this.quantity = quantity; }
}

此处数量上限是教学值,业务需要另行定义。命令中的tenantId来自认证后建立的授权上下文。即使系统允许用户切换租户,也要验证目标租户属于可访问集合,不能把“可切换”变成“任意指定”。

校验分组可以区分创建和更新,但过多分组会让同一DTO含义难懂。复杂ERP更适合按用例拆请求模型;部分更新还应区分未提供、明确置空和设置新值,避免null语义不明造成误清空。

3. 从认证追到资源授权

项目SecurityConfig〔本地文件〕配置安全链;TokenService〔本地文件〕提供token与登录状态相关处理。阅读时要区分“JWT能验签”和“用户仍有有效会话与权限”。本项目还涉及Redis登录状态,不能直接称为完全无状态权限系统。

认证回答你是谁,角色权限回答你可以做哪些种类的动作,资源授权回答你能对哪一张订单做这个动作。只检查order:export权限,不能自动允许导出所有租户订单。

CSRF是否需要防御取决于浏览器是否会自动携带凭证、是否使用cookie等实际认证方式。不能只因为代码写STATELESS或token就宣布不需要CSRF;CORS也不是服务端授权机制,非浏览器客户端不会受同样限制。这里分析设计边界,不对整个部署作安全结论。

4. SQL中的租户边界

SELECT order_id, status, amount
FROM erp_order
WHERE tenant_id = #{tenantId}
  AND order_id = #{orderId};

UPDATE erp_order
SET status = 'CONFIRMED', version = version + 1
WHERE tenant_id = #{tenantId}
  AND order_id = #{orderId}
  AND status = 'DRAFT'
  AND version = #{expectedVersion};

这是MyBatis SQL示意。读和写都带租户与状态约束,检查影响行数后再决定返回结果。客户端不能通过猜ID绕过租户条件。跨表关联也要核对关系是否在同一租户内,不能只在主表带tenant_id而从一张全局ID不唯一的明细表取到其他租户数据。

项目DataScopeAspect〔本地文件〕构造数据范围条件。应继续检查Mapper是否使用该条件、别名是否匹配、首参数类型是否符合切面约定、是否存在不经过切面的旁路。权限注解无法修复遗漏条件的手写SQL。

使用${}拼接SQL必须限制为可信、服务端生成且严格约束的语法片段;用户值用参数绑定。列名、排序方向不能直接用普通值占位符解决,可从枚举映射到固定SQL片段。不要把用户输入经过简单替换后当安全表达式。

5. 缓存、异步和文件同样需要隔离

缓存键包含tenantId只是第一步,还要考虑权限范围、数据版本和查询条件。如果不同角色可见字段不同,却复用同一个完整响应缓存,可能泄漏字段。适合缓存共享原始数据时,也需要在返回前执行适当授权和字段裁剪。

异步任务应该保存可信租户、发起人、请求摘要和业务授权依据。执行时是否重新校验权限要由产品定义:权限撤销后仍允许已批准任务完成,还是立即取消?无论如何,下载时应重新鉴权并检查任务归属,不能凭一个可枚举jobId返回文件。

文件路径必须由服务端生成和约束,避免用户提供路径穿越。导出CSV时还要考虑表格软件公式解释:以=、+、-、@等开头的非可信文本可能被当公式。应根据目标格式采用明确文本编码策略,测试数据保真与安全,不能只给整行加引号就假定问题消失。

6. 序列化的正确性与成本

Java Long可能超过JavaScript安全整数范围,订单ID传到前端后可能被舍入,随后查询或更新错误资源。对标识符可采用字符串契约;金额使用明确币种、精度与小数规则,避免double累计资金误差。时间则区分Instant、当地时间和业务日期,明确时区及边界。

返回实体还可能暴露内部字段或触发懒加载,从而形成序列化期间的N+1查询。DTO投影可以同时限制数据量和公开字段。日期格式、null策略、枚举改名与全局ObjectMapper变更,都应有契约测试。

深层嵌套对象、双向引用和巨大集合还会导致递归、内存和响应体膨胀。不要把无限对象图直接交给序列化器;设计有界DTO和分页嵌套资源。

7. 异常应该在哪里转换

底层数据库异常可转成应用层可理解的错误,再在接口边界映射对外协议。保留原因链便于诊断,但不把SQL、表名、连接信息、token或用户隐私直接放进响应。

项目GlobalExceptionHandler〔本地文件〕有若干直接返回异常message的处理路径。这是需要结合异常内容审查的泄漏风险,不代表每条异常一定含敏感信息。改进方向是稳定错误码、公开安全消息、内部traceId与脱敏日志。

日志记录也有成本与安全边界:完整请求体可能含客户电话,完整批量列表可能撑爆日志。记录数量、耗时、错误分类与有限样本通常更有用。租户或订单ID适合受控日志/追踪字段,不宜直接成为高基数监控标签。

8. 安全也是资源治理

合法查询仍能造成拒绝服务:空条件全表查询、几十万IN参数、复杂正则、无限pageSize、并发导出、失败自动重试。入口应限制单次工作量,按租户配额,设置有界队列与超时。恶意与误操作在资源上可能具有相同效果。

性能优化也可能破坏安全。例如删除租户条件让索引“更容易命中”,或绕过权限切面直接查Mapper,都不是可接受优化。必须在相同授权语义下减少工作量,查询计划和权限断言一起验证。

9. 对抗练习与参考答案

  1. 用户A用用户B的订单ID调用已登录接口:期待无数据或拒绝,不能返回B的信息;读写SQL均要检查租户与权限。
  2. 同一幂等键换参数:应比较稳定请求摘要并拒绝冲突,不能悄悄返回不相关结果。
  3. 导出开始后用户权限撤销:按照明确定义处理任务,下载入口必须重新检查当前访问资格。
  4. 请求quantity=0被校验拦住,是否证明库存安全?没有,并发条件仍需数据库原子约束。
  5. 全局异常处理后监控全绿但用户大量失败:检查真实HTTP状态和业务失败指标,不仅看接口有没有抛到容器。

参考:Spring MVC校验与异常处理、Spring Security 5.7参考。本章案例来自局部源码阅读,不等同完整安全审计。

原始文档 · spring-course/09-海量数据下的SQL与数据访问性能.md

09 海量数据下的 SQL 与数据访问性能

本章把前面学到的依赖注入、Mapper 代理和事务边界放进一个具体问题:广告明细持续增长,运营看板仍要快速响应,库存服务还必须与它共享有限的数据库容量。前端把数组过滤移到 Web Worker 可以减少页面卡顿;后端把数据库查询移到线程池,只是换了等待位置,数据库扫描、连接占用和结果对象仍然存在。理解性能的起点,是沿一次业务操作数清楚实际做了多少工作。

阅读顺序是本章的代价模型,再读第 10 章的分页与内存,最后到第 11 章计算并发预算。索引内部结构不在这里重复铺陈,请衔接 database-course 的索引设计、执行计划实战和连接池工具链。这里解决的是 Spring 服务如何正确使用这些数据库机制。

1. 先建立一次请求的账本

将串行请求耗时近似拆成:入口排队、取得连接的等待、各 SQL 的网络往返与执行、结果传输、Java 映射聚合、响应序列化。它们不一定能直接相加到毫秒,因为驱动读取与对象构造可能交叠;这个分解的作用是避免将“接口耗时一秒”直接解释成“数据库执行一秒”。同时记录 SQL 次数 Q、实际检查的行数 S、返回行数 R、平均返回行字节 W、连接持有时间 H。返回只有一行的 COUNT 可能检查几百万行;返回五百行的窄投影可能比返回二十行的大文本更便宜。

一个教学估算:单次往返固定成本假设为 2ms,循环查询一千个 SKU,即使每次索引查找只需 0.2ms,串行固定成本也已超过两秒。这个假设不是线上测量。将请求分成每批二百个 ID 后,往返从一千次变为五次,却不能承诺总耗时恰好下降二百倍:IN 列表扩大了参数数量、返回行数和一次执行时间,远端还可能把一次调用拆成多条 SQL。应用调用次数、驱动发送次数、数据库语句次数必须分开计数。

批量更新同样如此。十条独立 UPDATE、一个带十个 WHEN 的 UPDATE,以及 JDBC 的十次 addBatch 后 executeBatch,并不是同一种执行方式。第一种可能有十次往返,第二种是一条更复杂的 SQL,第三种还受驱动批重写与执行器影响。只有读取 Mapper XML、执行器配置与有效驱动行为,才能说清楚发生了什么;方法名里有 Batch 不能代替证据。

2. 从真实广告源码追到数据库工作量

真实入口在 ErpKjDomesticIncubationServiceImpl 的同步方法〔本地文件〕。它枚举两种日期字符串格式,再枚举五个广告位,每个组合独立翻页。页大小在第 43 行〔本地文件〕固定为 500。Mapper 接口在第 30 行〔本地文件〕用 @Param 明确绑定六个参数;真正的查询在 XML 第 21 行〔本地文件〕。

这里的 IoC/DI 并没有消除 SQL。Spring 创建 Service,构造器注入 MyBatis 创建的 Mapper 代理;调用接口方法时,MyBatis 根据 namespace 与方法名查找 mapped statement,处理动态标签并绑定参数,再通过集成层取得 SqlSession/连接。@Param 是供 MyBatis 读取的参数元数据,@Service 是供组件扫描识别的元数据;两种注解由不同机制处理。XML 中的 #{pageSize} 是绑定值,不能理解成 Spring 为它自动实施了大小限制。

设第 j 个日期与广告位组合实际有 n_j 条合格来源记录,P=500。当前循环只在读到空页时退出,所以每个组合查询次数为 ceil(n_j/P)+1,空组合也查询一次。十个组合的总读取调用次数为 Σceil(n_j/P)+10。非空页经过标准化后还有有效昵称才执行一次 upsert,因此写入调用数不大于 Σceil(n_j/P)。这是从循环结构得到的静态结论,不包括数据库内部操作、重试或其他接口查询。

若一日共有一百万条且十个组合各有十万条,读取调用数是 2010,写入调用数最多 2000。原始行数仍是一百万,游标没有把全日同步变成常数时间;它避免的是随着页码增大反复跳过旧记录。应用仅保存一页来源和该页聚合结果,不能据此说整个流程“只处理五百行”。

3. 为什么这个游标必须与排序保持同一语义

查询固定 date_desc、ad_id,排除空 nick,然后按 nick, sad_type, id 升序读取。接续条件逐层比较这三个字段,id 负责解决昵称和行为相同的重复行。以下简化 SQL 只演示三个字段都非空的分支;实际 XML 另有 sad_type 为空时的处理,不能直接用本段替换它。

SELECT id AS sourceId, nick, sad_type AS sadType
FROM tb_middle_ad_detail
WHERE date_desc = :dateDesc AND ad_id = :adId
  AND (nick > :lastNick
       OR (nick = :lastNick AND sad_type > :lastSadType)
       OR (nick = :lastNick AND sad_type = :lastSadType
           AND id > :lastSourceId))
ORDER BY nick, sad_type, id
LIMIT :pageSize;

反例是只保存 lastNick:第一页最后一条 nick 为 alice,而第二页还有 alice 的其他明细,nick > 'alice' 会跳过它们。另一个反例是 Java 把末行昵称 trim 后当作游标,数据库实际却按原始字符串和排序规则排序;这样 WHERE 和 ORDER BY 的边界已经不相同。真实 Service 在第 167 行〔本地文件〕使用来源页原始末行推进,业务聚合的标准化只用于物化表。

XML 注释写明预期复合索引为 (date_desc, ad_id, nick, sad_type)。这是仓库的设计说明,不能证明部署库拥有该索引,也不能证明优化器一定使用它。只有在 InnoDB、id 确为主键等条件成立时,才可以进一步讨论二级索引附带主键对排序与覆盖读取的帮助;其他引擎、索引前缀长度、字符排序规则、OR 范围展开都可能改变计划。应在隔离副本或合成数据上核验执行计划、检查行数、是否额外排序,再决定是否增加显式 id 索引列。不要根据注释直接发建索引变更。

深 OFFSET 的代价可用一个受限模型理解:若每页都从匹配索引区间起点跳过旧行,第 k 页约需越过 kP 条,完整扫描 m 页累计约为 P*m*(m+1)/2。游标有合适访问路径时,更接近一次次范围定位加本页读取。真实计划可能因回表、排序和过滤差异偏离这个模型;MySQL LIMIT 官方说明解释了 LIMIT 与排序计划的关系,不能把 LIMIT 当作扫描行数上限。

4. 看板物化不是把成本变没,而是换执行频率

看板查询〔本地文件〕从去重后的触达用户物化表统计,不再每个请求都在广告历史明细上做全历史去重。代价从“每次请求重复计算”转为“同步时写入维护结果,加上读取物化表”。如果一天十万次看板访问,这通常比每次重扫明细合理,但物化表本身也可能越来越大,COUNT 与条件 SUM 仍然需要工作,不能称为 O(1)。下一阶段可能是按日聚合、缓存或预计算计数,是否需要由实际成本决定。

物化还引入新契约:页面看到的是截至某个同步阶段的数据。当前 SQL 返回的 MAX(last_touch_date) 是已有数据的最大日期,不等价于“该日所有广告位均同步完成”。若只完成第一个广告位就失败,最大日期仍可能是当天。更严谨的方案要独立记录任务状态、每个分片完成情况和发布水位;报表要展示已确认水位,而不是把某条数据日期当完成证明。

写入规则见 upsert 第 82 行〔本地文件〕:首次日期取较小值、最后日期取较大值,有 show 才合并展示日期。在唯一键正确存在、标准化语义一致的前提下,重复处理通常不会改变这些业务聚合值,但更新时间仍会变化。因此“可重跑”指业务结果,而不是每个列和审计记录完全不变。affectedRowCount 也不是新增用户数;MySQL upsert 对新增、更新、未改变以及连接选项的计数存在区别,见官方 upsert 语义。

5. 库存组件里如何数循环、SQL 与远端调用

StockComponent 接口〔本地文件〕声明批量库存修改,实现第 1295 行〔本地文件〕先校验用户信息,再把相同 SKU 的增量汇总,每十条调用一次 Mapper。假设输入有 N 条,去重合并后有 U 个 SKU,那么这里发出的 Mapper 更新调用数是 ceil(U/10),不是 ceil(N/10)。

再读 SysSkuMapper.xml 第 3280 行〔本地文件〕,可以确认它是 CASE WHEN 形式的单条 UPDATE,最后由第 3421 行〔本地文件〕的 ID 集合收敛范围。这才足以解释“每批一次调用”的 SQL 形状。多个字段各有 foreach,SQL 参数量近似随“本批 SKU 数 × 更新字段数”增长,所以把十直接改成十万会显著增加 SQL 构造、解析、传输与持锁代价。

这里还有安全边界:该段 WHERE 可见的是 id 集合,不能仅凭方法参数有 User 就断言 SQL 有租户过滤。需要继续核验 ID 来源、分片路由、授权和租户归属约束。空集合必须在应用边界拒绝或返回,不能让动态 SQL 在“省略条件”后扩大写入范围。性能优化必须保持租户条件和业务影响行数验证,不能为了减少索引列就删除隔离条件。

getOneDaySaleList〔本地文件〕则按配置分片,每片调用两个报表远端方法,再把结果整理到 Map。若功能开关开启、分片大小为 B、输入有 K 个 ID,这一层的远端调用数为 2*ceil(K/B)。它不是本地两条 SQL,远端可能查询不同存储;没有继续读取远端实现和运行指标,就不能写成“两个索引查询”。

6. 从反例逐步改成受控数据访问

下面是教学反例,不是对原仓库行为的转述。一个页面要返回 SKU 与销量,逐行调用会产生 N+1 次访问:

List<Sku> rows = skuMapper.findPage(tenantId, afterId, 100);
for (Sku row : rows) {
    row.setSales(salesMapper.findOne(tenantId, row.getId()));
}

第一步先限制入口页大小并固定授权后的 tenantId。第二步收集本页 ID,一次或分小批读取销量。第三步按 ID 归并,避免在每个 SKU 上重新扫描整个销量列表形成 O(N²) 的 Java 工作。下面的 Sku、Sales、Mapper 是待实现的教学领域类型,代码突出编排契约:

int size = Math.max(1, Math.min(requestedSize, 200));
List<Sku> rows = skuMapper.findPage(tenantId, afterId, size);
if (rows.isEmpty()) {
    return rows;
}
List<Long> ids = rows.stream().map(Sku::getId)
        .distinct().collect(java.util.stream.Collectors.toList());
Map<Long, Sales> salesById = salesMapper.findByIds(tenantId, ids)
        .stream().collect(java.util.stream.Collectors.toMap(
                Sales::getSkuId, java.util.function.Function.identity()));
for (Sku row : rows) {
    row.setSales(salesById.get(row.getId()));
}
return rows;

这个 toMap 故意要求每个 SKU 恰有一条聚合结果,若 SQL 意外返回重复键应暴露错误;如果业务允许多行,就先按业务规则聚合,不能用随意保留第一条掩盖。销量缺失要区分“真实零值”和“远端失败”,不能捕获所有异常后填零,让库存决策误把故障当销量下降。查询字段只保留响应需要的列,响应转换也不要把内部账户信息顺手输出。

7. 连接池预算决定并行上限

连接池是限制同时访问数据库的资源池,不是 SQL 加速器。用 Little 定律做一阶估算:稳定状态下平均连接占用约为业务到达率乘平均连接持有时间。假设每秒 200 次事务、每次持有 50ms,平均占用约 10 条;若事务内增加 500ms 的远端调用,持有时间变为 550ms,平均占用约 110 条。SQL 本身没变,连接池却可能被耗尽。这些是教学数字,容量规划还要给尾延迟和突发保留余量。

假设一个实例池上限 30,前台与其他任务峰值预算 18,后台最多先预算 8 条,留下 4 条余量;每个后台任务同一时刻占两条连接时,并发上限应进一步减半。十个实例各配置 30,数据库面临的是最多约 300 条连接及其他客户端,而不是 30。不要仅按 CPU 核数开数据库工作线程,也不要在父事务持有连接时等待子任务,子任务再争抢同一个池。

库存实现的第 1427 行〔本地文件〕用 TransactionTemplate 包住写入,前置查询在回调外。它展示了显式边界,但不能因此认定整个调用链一定没有外层事务,或前置读取与写入天然一致。需要检查调用方传播行为、管理器和并发条件。关于连接归属及隔离级别,请继续读 database-course 的 Spring 事务工程。

8. 练习、答案与验证边界

练习一:十个广告组合中,只有一个有 1001 条来源,其他为空;每页 500,且所有非空页都有有效昵称,读取与写入各多少次?答案:有数据组合读四次、写三次,其余九个各读一次,所以读十三次、写三次。不能把最后 1 条误认成循环已终止,真实实现仍读一次空页。

练习二:库存输入 103 条,其中只有 23 个不同 SKU,合并后每十个写一次,是否表示三次事务?答案:只能确认该段三次 Mapper 调用,事务次数必须看外层事务与管理器。若三条 UPDATE 在同一事务内,第一批锁可能一直保留到最后提交,分批不等于提前释放锁。

练习三:返回数据只有一行、接口仍慢,先调大连接池合理吗?答案:先分开连接等待和 SQL 执行,再看检查行数、排序、锁等待、事务持有时间。全历史聚合返回一行仍可能扫描很多行;盲目扩大连接池可能让数据库同时承受更多昂贵查询。

本章于 2026-11-10 读取上述工作区源码并核对行号;图谱工具不可用,使用 rg 定位。示例采用 Java 8/Spring 5.x/Boot 2.x 的编程风格。erp-index POM〔本地文件〕声明了 Boot Maven 插件版本属性与 Java 版本属性,它们不证明运行时 Spring 版本、部署配置或实际数据库类型。Boot 3.0 进入 Java 17、Spring 6 基线,见官方系统要求;不能把新版本配置或 API 直接套进旧项目。

完成的是教学文档与静态调用分析,没有启动 ERP、连接业务库、执行 EXPLAIN、压测或迁移索引;执行计划、唯一键存在性、真实池大小和吞吐量均仍需隔离环境验证。MyBatis-Spring 的 SqlSessionTemplate 文档用于核验代理背后的会话管理机制,具体版本要以有效依赖和实际部署制品为准。

原始文档 · spring-course/10-分页批处理导入导出与内存控制.md

10 分页、批处理、导入导出与内存控制

大数据后端的重要能力,是让单个任务处理的数据总量增长时,瞬时资源占用仍然有上界。不能因为有循环就说是流式,也不能因为SQL写LIMIT就说成本固定。本章用项目的广告明细处理作为主线,把查询、对象、队列、文件和恢复连起来。

1. 三种规模要分别计算

总记录数N决定总工作量;批大小B决定单批内存、SQL体积及事务长度;并发C决定同时争抢资源的任务数。最常见的错误是只控制B,却让C无限增长;或者数据库每页只读B条,Java却把每页都加进总List。

设每条转换后驻留对象约2KB,每批1000条,8个并发任务,每个任务同时保留原对象和输出对象两份。教学估算为2KB × 1000 × 8 × 2 ≈ 32MB,还没有算字符串、集合容量、驱动缓冲、编码缓冲和队列。这个数字不是项目实测;真正对象大小需要用目标JVM与采样验证。

因此内存模型应是“在途页数×页大小×每条驻留成本+队列闭包+框架缓冲”,不是简单的“文件大小”。小页无限预取同样会OOM。

2. OFFSET与Keyset不是新旧关系,而是访问模型不同

SELECT order_id, created_at, status
FROM erp_order
WHERE tenant_id = ?
ORDER BY created_at, order_id
LIMIT 1000000, 100;

深OFFSET通常要遍历并丢弃大量前面的记录。即使能走索引,也可能付出很高的扫描或回表成本。随机跳页的小规模后台可以接受OFFSET,但后台全量导出更适合按稳定游标推进。

SELECT order_id, created_at, status
FROM erp_order
WHERE tenant_id = ?
  AND created_at >= ? AND created_at < ?
  AND (created_at > ? OR (created_at = ? AND order_id > ?))
ORDER BY created_at, order_id
LIMIT ?;

候选索引以(tenant_id, created_at, order_id)为起点,还要看筛选、投影和实际执行计划。不能保证优化器在所有版本下都把OR范围处理为理想访问;必须EXPLAIN并测各页扫描量。首次查询应使用没有游标谓词的形状,别塞一个不属于数据域的魔法最小值。

排序末尾需要唯一且稳定的决定字段,否则同时间戳的记录可能被漏掉。多列NULL、排序方向和数据库collation也会改变比较语义。客户端游标必须包含完整排序位置,并与筛选条件绑定。

3. 项目里的“原始游标”和“业务聚合”

syncAdReachUsersByDateAndAd〔本地文件〕每次读取一页,只在页内用LinkedHashMap按标准化昵称聚合,随后批量upsert。页处理完就推进,没有把所有历史明细积累在一个List里。

Mapper〔本地文件〕固定date_desc与ad_id,按nick、sad_type、id排序,单独处理sad_type为NULL的续页。服务端用最后一条原始记录推进,即使这一页昵称全部被业务过滤,也会前进。

为什么不能用最后一个有效聚合昵称推进?因为TRIM前后可能不同、同一昵称有多个来源记录、被过滤页可能没有聚合结果;这样会重复读取或漏读。遍历位置属于存储排序,业务去重属于目标模型,是两种不同状态。

upsert的日期最小/最大合并,使重复页可收敛到相同业务边界;updated_at仍可能变化,因此应精确说“业务结果幂等”,不是整行所有字段逐字节不变。若源数据可删除、更正或回填,单纯取极值可能无法撤销旧事实,需要重建或修复策略。

4. Keyset不是快照

游标解决“从哪里继续”,不自动解决“数据在扫描期间变化”。如果排序字段更新到游标之前,可能漏掉;更新到之后,可能重复;新插入数据是否出现取决于排序位置和读取隔离。

可选择三种语义:业务允许滚动视图;固定时间或ID上界形成有限集合但承认更新影响;使用一致快照或不可变快照表以保证某时刻视图。长事务快照可能付出旧版本保留成本,快照表则付出存储与构建延迟。应在导出文件里写清数据截止口径。

“记录当前max(id)”只在特定单调、提交与变更模型下提供有限帮助,不能普遍代表提交时刻快照:较早分配ID的未提交事务可能稍后提交。要精确审计报表,应采用可证明的快照或版本协议。

5. 批量写入:一次SQL不一定一次业务事务

MyBatis foreach可生成多VALUES INSERT、IN查询或CASE更新;ExecutorType.BATCH则是客户端批执行策略,两者不是一个概念。批执行需要注意flush时点、语句复用、返回更新数及错误暴露延迟。SQL执行“已加入批”不代表已提交。

JDBC驱动批重写选项、服务器包大小、参数数量、事务日志与锁都会限制B。批量100000行可能减少网络往返,却导致大包、长锁、回滚昂贵;合理批量要用端到端吞吐、尾延迟和失败成本来选择。

导入先校验整份文件还是边读边提交取决于产品语义。要求全部成功才可见,可以先写暂存表,再校验与发布版本;允许部分成功,则每批事务和错误明细应可恢复。不要先每批提交,最后又在接口文案里承诺“全部原子导入”。

6. Java流式不等于数据库流式

list.stream()只是遍历已经驻留内存的List。MyBatis Cursor、ResultHandler、JDBC fetchSize可能帮助边读边处理,但实际是否流式受驱动、游标模式、事务和配置影响。fetchSize不是统一的网络协议保证。

数据库流式游标常会在整个遍历期间占用连接。若下游文件写入或远端上传很慢,连接被长期占有;分页读则更容易释放连接和重试单页,但要处理跨页一致性。选择由瓶颈和数据语义决定。

资源必须用try-with-resources或明确finally关闭,特别是异常、中断、客户端取消。不要把持有打开游标的Stream返回给一个不知道关闭责任的调用方。

7. 导出文件的分块与恢复

一种可恢复设计是每页生成不可变分块文件,记录块序号、游标、校验和、行数和对象存储位置。最后生成manifest并发布完整文件引用。重试使用相同块标识,避免“文件已经追加,数据库checkpoint没写”造成重复行。

如果直接追加同一个CSV,然后写数据库checkpoint,这两个资源不在同一事务里:任意一个先完成都会留下崩溃窗口。要么允许从头重建临时文件,要么采用可验证分块与幂等覆盖,不能只说加事务解决。

Excel格式还有限制和内存行为,需按具体库测试流式窗口、临时文件大小和样式数量。不要为每个单元格创建新样式;不要让临时文件无上限堆积。下载时再次检查权限,文件保留时间和清理策略也是系统的一部分。

8. 大表JOIN结果的隐性膨胀

先查订单与全部明细JOIN,再对结果LIMIT100,可能只得到少量订单的部分明细。对于一对多列表,应先以父订单维度分页,再按该页ID批量取明细,或使用明确的聚合投影。一次数据库往返更少不必然意味着数据更少或语义正确。

预先计算统计表可以将昂贵聚合从每次请求转移到增量任务,但需要新鲜度、修复和幂等保障。项目广告物化正适合对照这一思路;详细SQL分析见09章和数据库课程。

9. 性能实验怎么设计

保持数据与语义一致,对比OFFSET、Keyset及不同B。记录首、中、末页的扫描行、耗时、连接占用与堆峰值;加入倾斜租户、同时间戳、NULL、空白昵称和扫描期间更新。不要只用100行均匀数据证明百万行稳定。

故障注入点包括:读完未写、写完未记游标、记游标后文件失败、上传后进程终止、最终发布失败。每个点说明重跑会重复什么、如何去重、是否漏数据。容量与恢复测试需要隔离环境,本教程没有执行生产规模压测。

10. 练习与答案

  1. 每页1000条但OOM:检查是否累积页、预取队列、每个Future捕获大集合、并发数量及序列化副本。
  2. 用格式化后的昵称作为游标:会破坏原始排序的比较语义,必须使用原始完整排序元组。
  3. checkpoint先提交再写文件:可能跳过未写数据;顺序反过来又可能重复,需跨资源恢复协议。
  4. 用户要任意跳第10000页又要固定极低延迟:应讨论产品改为游标、定位筛选或预计算索引,不能靠注解保证。

延伸:数据库复杂查询、MyBatis完整实战。本章SQL为教学设计,索引收益须在目标数据库验证。

原始文档 · spring-course/11-线程池异步任务与背压.md

11 线程池、异步任务与背压

线程池的作用是管理有限执行资源。它不会增加数据库容量,也不会让任务自动可靠。前端转后端时,最容易把Promise式并行理解为“能开多少就开多少”;ERP里每个异步任务都可能带来数据库连接、SQL、远端请求和内存。先减少工作,再决定并行程度。

1. ThreadPoolExecutor的接收路径

常见执行路径可以概括为:工作线程少于core时尝试创建→否则尝试入队→入队失败再尝试扩到max→仍无法接受则拒绝。状态竞争和关闭过程还有额外校验,但这个模型足以解释多数错误配置。

core=5,max=10,无界队列
  前5个长期任务占住工作线程
  后续任务进入队列
  通常不会因为队列越来越长就扩到10

项目ScmDistributorItemThreadConfig〔本地文件〕正使用无容量参数的LinkedBlockingQueue以及core5/max10。不能把max10当作平时实际会达到的工作并发。队列虽然有实现上的容量上限,但在内存预算意义上接近无界。

2. 排队本身就是资源消耗

队列元素常常不是一个轻巧的ID,而是捕获请求DTO、几千条记录、用户上下文与回调的Runnable。任务滞留越久,对象存活越久,可能进入老年代并增加GC成本。堆变大只会让排队灾难推迟出现,不解决到达速度持续超过处理速度的问题。

Little定律在稳定平均条件下给出L = λ × W:平均在途数等于吞吐率乘以平均系统停留时间。假设完成率200任务/秒,平均总停留0.5秒,则平均在途约100。这是教学计算,不能把p99代入当严格推导,也不适用于无限积压时直接求稳定容量。

假设4个worker、每任务平均耗时0.2秒,理想吞吐上限约20任务/秒;若持续到达30任务/秒,平均每秒增加10个排队任务。调大队列只能延迟拒绝,不能改变长期收支。

3. 拒绝策略就是对用户的承诺

策略 行为 必须处理的业务结果
AbortPolicy 抛拒绝异常 接口明确过载,任务状态失败或待重试
CallerRunsPolicy 非关闭状态下由调用线程执行 提交者可能阻塞,HTTP/调度线程受影响
DiscardPolicy 静默丢弃 不适合没有补偿的可靠业务
DiscardOldestPolicy 丢队首并尝试接收新任务 老任务可能无结果,顺序与公平性受损

项目AsyncTemplateConfig〔本地文件〕有ArrayBlockingQueue(108)与DiscardPolicy。可确认存在这种底层策略;是否导致某业务任务永久悬挂还要检查AsyncTemplate、TTL与trace包装器及状态补偿,不能跳过包装层直接下事故结论。

核心机制实验表明:标准ExecutorService.submit先创建FutureTask,再提交;若执行器静默丢弃且没有取消或补偿,调用者可能拿到永不完成的Future。超时get能保护等待者,却不会自动修复任务状态。

4. 选择线程数先看下游预算

CPU密集任务受核数与调度成本限制;阻塞IO任务可以多于核数,但上限由数据库、远端限额、内存和延迟预算决定。CPU × 2不是通用公式,尤其在多个服务实例和多个线程池叠加时。

假设数据库允许本服务集群占用60条活跃连接,部署6实例,则平均每实例总预算约10,还要给HTTP、定时任务和突发留余量。若每实例导出开20线程并每线程持一条连接,单这个模块就可能远超预算。这里是容量模型,真实允许值要压测与数据库治理确定。

还要统计每任务最大同时连接数:REQUIRES_NEW可能额外借连接,多个异步子任务也可能并行借连接。限流应放在获取昂贵资源前,减少“线程都在连接池里等”的无效并发。

5. @Async是入口增强,不是语法糖魔法

@EnableAsync启用相关处理器,@Async方法通过代理交给执行器运行。self调用通常绕过代理;没有明确执行器名称时,默认选择受框架与Boot配置影响,不应凭感觉认定使用某个池。重要业务建议显式指定名字并测试。

@Async("exportExecutor")
public CompletableFuture<ExportResult> execute(ExportCommand command) {
    return CompletableFuture.completedFuture(exportWorker.run(command));
}

这里仍然是阻塞worker执行,只是调用位置改变。返回Future的异常可由调用方观察;void异步方法不能把异常直接返回原HTTP请求,应配置异常处理与业务失败记录。提交成功、开始执行、结果提交是三个不同事件。

外层线程的本地事务不会自动传给新线程。可以让异步入口调用另一个明确事务服务,由worker线程建立短事务;不要把未提交实体引用当作可靠事件交给异步任务。

6. CompletableFuture常见陷阱

未指定执行器的异步方法通常会使用公共池等默认设施,可能让数据库阻塞与其他组件竞争。显式执行器让预算清晰。allOf能等待组合完成,却不会自动减少任务数;一次构造十万个Future仍然占内存并可能压垮下游。

在固定小池里,任务A提交任务B到同池再阻塞join;当所有worker都执行A时,B只能排队,形成线程饥饿死锁。解决方式是改变组合结构、避免在同一受限执行资源内阻塞等待子任务,而不是只把池加大一点。

取消Future也不保证数据库或网络请求立即终止。中断是协作机制,代码应检查中断并正确结束;驱动和客户端是否支持取消,需要实测。不能因调用cancel返回true就宣布业务没有产生副作用。

7. 建立背压,而不是最后才OOM

背压是下游忙时让上游减速或拒绝。可通过有界队列、信号量、按租户限额、持久任务待处理状态和入口速率控制实现。关键是把“等待多久、能等多少、失败怎样通知”写成协议。

HTTP接单 → 持久化PENDING任务 → 返回jobId
调度器 → 按全局/租户并发预算抢任务
worker → 分批执行并记录进度
执行失败 → 可恢复状态与下次尝试时间

这种结构把可靠接单与内存执行队列解耦,但持久队列也不能无限堆积。要监控最老任务年龄、预计完成时间、租户公平性与存储增长,并在无法满足承诺时停止接单。

CallerRuns提供一种反向减速,却可能把重任务塞回HTTP线程,破坏响应SLO;它还会改变上下文和执行位置假设。不要当成永远安全的默认策略。

8. 监控和优雅停机

至少观察active、pool size、queue size、queue oldest age、rejected、completed、失败分类、任务执行与等待时间。仅看队列长度不够:10个一小时任务比100个一毫秒任务更严重。

停止接单后,给执行中的任务有界收尾时间;超时未完成的任务留下可恢复状态。执行器关闭不意味着远端副作用被撤销。资源清理与业务恢复分别设计,生命周期见03章。

9. 实验与答案

ExecutorTest〔本地文件〕用latch而非随意sleep控制时序,验证无界队列不扩容、有界拒绝、静默丢弃Future和ThreadLocal残留。所有等待均有上界并清理执行器。

一:队列容量从100改100000是否改善吞吐?通常只增加能排队的数量,吞吐受执行与下游限制,延迟和内存可能恶化。

二:加更多线程为何CPU仍低?线程可能等数据库连接、网络或锁。应查等待位置与下游饱和度。

三:两个线程池是否就是资源隔离?它们仍可能共享连接池、公共客户端和数据库热点,需要检查全部共享资源。

四:任务返回202之后被拒绝怎么办?可靠接单应先持久化,执行拒绝回到待调度状态;如果只在内存提交,则必须在接单契约中明确失败与恢复行为。

参考:JDK 8 ThreadPoolExecutor。线程池参数是部署资源策略,必须用真实负载验证。

原始文档 · spring-course/12-Java并发线程上下文与共享状态.md

12 Java并发、线程上下文与共享状态

Spring的singleton服务经常同时处理多个请求。容器管理创建与装配,不会让你的字段自动具备线程安全。本章从内存模型进入锁与上下文,把Java局部并发和跨实例业务一致性分开,最后回到ERP租户与日志传递。

1. 三类问题:原子性、可见性、顺序

count++包含读、计算、写,多线程可能读到同一旧值而丢更新,这是原子性问题。线程A写了停止标记,线程B未及时观察,是可见性问题。编译器与CPU允许某些重排,跨线程观察要依赖明确的happens-before关系,而不是源码顺序想象。

常见保证包括:同一锁的解锁先行发生于后续加锁;volatile写对后续相应读提供可见性与顺序约束;线程启动、join和并发工具建立相应关系。JMM不是“每次读取都直接访问主内存”的简单图解,应该从程序可观察行为理解。

volatile int count仍不能让count++变成原子操作。AtomicLong的增量可解决一个计数器更新,却不能自动解决“库存与预占量两个字段必须一起满足约束”。需要把不变量覆盖到同一个同步或数据库原子边界。

2. singleton服务应尽量无请求状态

@Service
public class UnsafeOrderService {
    private Long currentTenantId;

    public List<Order> list(Long tenantId) {
        currentTenantId = tenantId;
        return loadForTenant(currentTenantId);
    }
}

这是反例。请求A写租户1,请求B写租户2,A随后可能读到2。把字段改volatile只让错误值更可见,不解决共享状态设计。正确方向是参数与局部变量传递,服务字段只保存稳定依赖或经过明确同步的共享组件。

不可变对象有助于安全共享,但final引用不等于引用的List不可变。构造后仍向内部集合添加元素,仍需同步或防御性复制。发布对象时还应避免构造期间把this暴露给其他线程。

3. Java锁保护的范围

synchronized提供互斥与可见性,ReentrantLock提供更多可中断、定时尝试等能力;读写锁适合特定读多写少且临界区成本匹配场景。不要看到读多就立即换读写锁,竞争与维护成本可能抵消收益。

这些锁通常只协调当前JVM中的线程。ERP部署多个实例后,给Java方法加synchronized无法防止另一个实例同时扣同一SKU。跨实例正确性仍需数据库约束、状态机、版本或合适的分布式协调。

不要在持有锁时做不受控远端调用;否则一个慢请求会让所有竞争者等待。多锁按全局一致顺序获取可降低循环等待风险,但超时、重入和异常释放仍需处理。项目库存按SKU排序获取多锁体现顺序意识,不等于消除所有死锁条件。

4. 并发集合解决的是操作,不是整个协议

ConcurrentHashMap使其支持的单次操作具备并发语义,但containsKey→put仍是复合动作。可用putIfAbsent或compute等表达原子更新,不过映射函数应短小,避免阻塞数据库调用或递归更新相关映射。

即使Map操作原子,也不代表“写数据库+写Map”原子。缓存一致性仍需独立协议,见13章。LongAdder适合高竞争统计,但读取不是某种跨变量一致快照,不能用于库存余额等强业务账本。

锁粒度需要对应冲突域。给整个订单服务一把全局锁,会把不同租户与不同SKU无谓串行;每个任意字符串创建一把永久锁,又可能造成锁对象无限增长。按资源分片或使用有界管理器时,必须考虑键生命周期与冲突成本。

5. ThreadLocal为什么在线程池里危险

ThreadLocal把值关联在线程,而不是请求。池中线程长期复用,任务A设了tenantId后没有remove,任务B可能读到A的值。请求完成不等于线程销毁,局部变量的直觉在这里失效。

TenantContext previous = TenantContexts.currentOrNull();
try {
    TenantContexts.install(capturedContext);
    work.run();
} finally {
    if (previous == null) {
        TenantContexts.clear();
    } else {
        TenantContexts.install(previous);
    }
}

这是上下文包装伪代码。嵌套调用应恢复旧值,简单clear可能清掉外层合法上下文。capturedContext应是必要字段的不可变快照,避免捕获整个ServletRequest、巨大对象或可变登录对象。

提交任务时捕获与执行任务时读取也不同:后者可能读到worker以前的值。InheritableThreadLocal基于线程创建继承,不等于线程池每次提交传播。TTL等工具有助于包装,但要检查所有提交入口、包装顺序、取消及CallerRuns分支。

6. 项目上下文案例

ProcessTraceInterceptor〔本地文件〕写入MDC。下载任务线程〔本地文件〕展示后台任务重建用户上下文及后续清理路径。把这两个入口对照,可以学习“Web请求上下文”和“持久任务上下文”是不同生命周期。

Trace上下文主要用于观测,租户身份用于授权,事务连接用于资源管理。这三者不能被一个“复制ThreadLocal”的动作统一传播。尤其不能把数据库Connection跨线程复制;它的事务归属、并发安全和释放责任都不因此成立。

每个后台任务需要显式携带可信tenantId及必要审计信息,执行时按任务协议验证。日志有traceId不证明权限正确;正确授权也不代表trace自动连续。

7. 取消、中断与时间预算

中断是协作信号。阻塞方法抛InterruptedException时,如果当前层无法完成处理,通常应恢复中断标志并向上退出,而不是打印异常继续无限循环。业务部分写入之后被中断,需要依靠事务或checkpoint恢复,不能认为线程停止就是业务撤销。

超时等待Future只结束等待方的耐心;任务可能继续占连接。要把整体截止时间传到每个阶段,剩余时间不足就不再开始新的重试或批次。关闭进程时也要遵守有界收尾,避免一个永不响应中断的任务卡住发布。

8. 并发测试如何减少偶然性

不要靠sleep猜两个线程是否在某一行相遇。用CountDownLatch让它们到达同一边界,再释放竞争;使用有界await/get防止失败时测试永久挂起,finally中释放资源。实验室通过单线程池稳定复现ThreadLocal跨任务残留,随后验证remove。

测试能证明某个构造下的行为,不能穷尽所有线程交错。关键不变量应有代码级同步理由、数据库约束和运行监控共同支撑。压测没有复现不等于没有竞态。

9. 练习与答案

  1. 给currentTenantId加volatile能否修复串租户?不能,问题是不同请求共享同一业务槽位,应改为参数或正确隔离的上下文。
  2. ConcurrentHashMap保存库存是否防超卖?只能讨论当前进程内某个操作,不能覆盖多个实例、持久化与失败恢复。
  3. TTL传播了租户,是否可以传播事务连接?不可以,事务资源不能这样跨线程复用,应在worker建立自己的事务边界。
  4. finally里remove就永远正确吗?嵌套上下文要恢复旧值,顶层请求清理才通常是remove。
  5. 大量线程WAITING是否一定是死锁?可能只是队列、连接或任务等待。死锁需要建立等待环和持有关系,结合线程栈与数据库锁信息判断。

参考:JDK并发包内存一致性、ThreadLocal。Reactive、协程和虚拟线程有不同上下文模型,本课Java8风格的ThreadLocal讨论不能直接作为它们的完整方案。

原始文档 · spring-course/13-缓存事件调度与可靠任务.md

13 缓存、事件、调度与可靠任务

本章面向已经理解 Controller、Service 和事务代理的前端开发者。浏览器里一次状态更新通常只影响当前页面;后端一次用户环境切换,却可能同时影响数据库、Redis、每个 JVM 的本地缓存以及后台迁移任务。学习目标是解释这些对象分别由谁创建、由谁触发、故障后谁负责补偿,而不是记住几个注解。先衔接数据库课程的缓存一致性和应用事务,这里进一步讨论 Spring 如何把这些机制组织起来。

示例语法以 Java 8、Spring Framework 5.3、Boot 2.7 为基线。仓库 Java 版本声明〔本地文件〕与 Boot BOM 导入〔本地文件〕只能证明构建意图,不能证明某台服务器实际装载的版本、缓存容量或调度拓扑。下面明确区分已读源码、教学改造和独立实验;所有教学用户编号、数据和状态均为虚构,不启动业务应用。

1. 从 LocalCache 的方法体开始,而不是从名字猜能力

LocalCache 构造器〔本地文件〕接收容量、过期秒数、统计开关和可选开关函数,内部创建 Caffeine Cache。这是普通 Java 对象,不因为类名里有 Cache 就自动变成 Spring 缓存切面。初始化方法〔本地文件〕实际调用的是 expireAfterWrite,即写入后计时;旁边“上次访问时间”的注释不符合调用语义。读取很多次并不会按 expireAfterAccess 的方式续期。读源码时应优先验证可执行表达式,再解释注释。

带加载器的 get〔本地文件〕分三步:先 getIfPresent,没有值就执行 supplier.get(),最后 put。这三个步骤不是一个按键合并的原子加载操作。假设热点键过期,二百个请求都在首个数据库查询结束前读到空值,它们可以分别执行二百次 supplier。底层缓存线程安全,只说明内部结构不会因并发破坏,不说明整个业务序列只执行一次。

教学第一步可把同一 JVM 的读取合并到 Caffeine 提供的加载入口:

// Java 8 + Caffeine 2.x;假定 cache 已经由构造器注入。
public UserView find(long tenantId, long userId) {
    UserKey key = new UserKey(tenantId, userId);
    return cache.get(key, k -> repository.find(k.tenantId, k.userId));
}

这是集成片段,UserKey 必须实现包含两个字段的 equals/hashCode,UserView 应是不可变快照,repository 必须具有查询超时。这里使用同一个 cache 对象的同键加载机制,仍然不能合并不同 JVM 的回源,也不能让数据库查询自动可取消。Caffeine 的 Population 文档解释手工缓存与计算加载入口的差异。null 结果默认不会形成普通缓存项;若不存在的用户会被反复请求,可用明确的“未找到”包装值和短 TTL,但认证失败、网络错误不能一律缓存成不存在。

第二步才考虑内存与租户隔离。maximumSize 限制条目数,不是精确字节数。一个用户配置条目和包含十万订单的 List 都算一个条目,后者可能拖垮堆。估算应包括键、值、对象头、集合节点和复制峰值,必要时使用权重策略并实测 retained size。缓存键只用 userId 是否安全,要由编号是否跨租户唯一决定;教学中显式加入 tenantId,防止展示数据串租户。敏感授权结果需要权限版本和短失效预算,不能只追求命中率。

第三步审查开关。源码 cacheEnabled〔本地文件〕影响带 supplier 的读取;不带 supplier 的 get〔本地文件〕却直接读底层缓存。invalidate〔本地文件〕在开关关闭时返回 false,而 invalidateAll 没有这个条件。因此“关闭缓存”等不等于“所有读取绕过且旧值清空”,必须按调用入口回答。关闭期间忽略失效,随后再次开启,旧条目在 TTL 到期前仍可能暴露。教学改造应把“允许读取”“允许回填”“失效必须执行”分开定义,恢复时提升 generation 或清空本地条目,并控制冷启动回源速度。

2. 缓存注解背后仍是容器和代理

@Cacheable 本身只是运行期元数据。启用缓存基础设施后,Spring 注册 advisor 与拦截器,对符合条件的 Bean 创建代理;调用经过代理时,拦截器先解析缓存名、键和条件,再决定是否调用目标方法。因而以下结构要配合 @EnableCaching、实际 CacheManager、Bean 扫描与外部调用一起理解:

@Service
public class UserQueryService {
    private final UserRepository repository;
    public UserQueryService(UserRepository repository) {
        this.repository = repository;
    }
    @Cacheable(cacheNames = "labUsers", key = "#p0 + ':' + #p1")
    public UserView find(long tenantId, long userId) {
        return repository.find(tenantId, userId);
    }
}

这里用 #p0/#p1 避免把参数名保留策略当成必然条件。手工 new UserQueryService 没有经过容器增强;同一个对象内部 this.find(...) 在通常的代理模式下也绕过拦截。sync=true 是向缓存提供方提出同步加载请求,具体支持和限制由 provider 决定,不能解释成分布式锁。@CacheEvict 默认在被拦截的方法成功返回后执行,也不能无条件等同于数据库最终提交以后:事务 advice 与缓存 advice 的嵌套关系、调用链中外层事务是否还在运行都要核实。参见 Spring 5.3 缓存抽象。

如果每次修改都在同类里调用私有 clearCache() 并标 @CacheEvict,很可能根本没有拦截;如果把缓存删除放在 SQL 后面,事务还没提交时读线程又能加载旧值。这两种反例分别来自代理边界与时间边界,不应混成“注解偶尔失效”。

3. UserEnvConfig:修改数据库之后还有什么没有完成

UserEnvConfigServiceImpl 的更新方法〔本地文件〕先检查权限和原记录,再执行保护校验、Mapper 更新、Redis 删除;删除异常被捕获记录。这里没有在该方法上看到 @Transactional,所以只能陈述方法内的顺序,不能根据“Service”或“先更新后删除”断言存在本地事务。实际事务还可能来自外层调用、XML 或其他 advice,本章没有证明这些路径。

这个实例说明正确性不止是提交一条 SQL。若缓存删除失败,返回的 affectRow 可能仍表示数据库修改成功,但读缓存的调用者会看到旧路由。若方法最后的通知抛出错误,客户端收到失败也不能倒推出数据库未写入。用户重试可能再次触发副作用。因此教学 API 应返回操作编号与明确状态,业务写使用幂等键,通知与缓存补偿各有状态,不能用一个“成功/失败”覆盖所有系统。

第一版教学服务在事务中发布事件,事件只带标识和版本,避免跨线程传可变实体:

public final class EnvChanged {
    public final long userId;
    public final long version;
    public EnvChanged(long userId, long version) {
        this.userId = userId;
        this.version = version;
    }
}

// 位于受 Spring 管理的服务中,由其他 Bean 调用。
@Transactional
public void change(long userId, String env) {
    long version = repository.changeAndGetVersion(userId, env);
    publisher.publishEvent(new EnvChanged(userId, version));
}

@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void evict(EnvChanged event) {
    cache.invalidate(event.userId);
}

上述 repository、publisher 和 cache 是构造器依赖,片段不代表仓库已有此改造。监听注解经事件监听基础设施发现,方法被适配成监听器;事务事件适配器将处理绑定到当前线程事务完成阶段。AFTER_COMMIT 解决的是“什么时候运行”,不是“怎么持久保存”。默认没有活跃事务时事件不会交给这个监听方法,除非显式启用 fallbackExecution;开启 fallback 又意味着无事务时也可能运行,需要单独设计语义。Spring 5.3 API还提醒:回调时事务资源可能仍可访问,但原事务已经结束,不能依靠继续写入原事务来提交新数据。需要额外持久写时,用另一个代理 Bean 开启新事务,并接受它与原提交之间仍有崩溃窗口。

反例很简单:数据库提交完成,JVM 在监听器执行前退出。内存事件消失,删除永远没有执行。把监听器加 @Async 只把工作移入另一个线程池,进程退出后队列同样丢失;线程切换还不能自动继承调用线程的数据库事务。因此 AFTER_COMMIT 绝不是可靠 MQ,更不能宣称“事务事件保证消息必达”。

4. 从事件回调推进到可靠任务状态机

第二版教学方案在修改环境的同一个数据库事务中插入 outbox 记录。事件持久性由数据库事务承担,监听器最多用于唤醒扫描器,定期扫描仍是兜底。表设计与数据库原子性直接衔接跨库建模综合实战,这里聚焦执行协议:

业务事务:更新 lab_user_env + 插入 lab_outbox(PENDING)
领取事务:PENDING/到期RETRY -> RUNNING,owner=workerA,token=17
执行阶段:删除缓存或调用支持幂等键的教学端口
确认事务:仅 owner=workerA AND token=17 才能更新 DONE
失败阶段:写 attempts、next_attempt_at、有限错误码;超过阈值进入人工处理

领取必须用条件更新或锁让竞争者有明确胜者,不能先查 PENDING 再无条件改状态。以 SQL 条件更新为例,受影响行数为 1 才表示成功领取。执行 I/O 时不长时间持有扫描事务和连接;分页按稳定游标向前推进,每轮限定条数、耗时和每租户配额。海量积压时,单次扫描全部记录放进 List 会把数据库压力变成堆压力,任务线程再多也只是加快耗尽内存。

即使领取可靠,也会重复:删除缓存成功,更新 DONE 前进程退出,租约到期后另一个 worker 再次删除。对于删除操作重复通常可接受;对于发货、扣费、扩容,要把操作编号传给下游并要求下游保存执行结果,或者用业务唯一约束保证同一效果只生效一次。防并发、幂等、可靠交付是三个不同性质。租约过期时旧 worker 可能仍在执行,fencing token 只有被实际写入目标校验,才能拒绝迟到写;仅把 token 打进日志没有隔离作用。

监控应记录最老待处理年龄、领取失败率、重试次数分布、每租户积压和死信数量。只看“每分钟扫描成功”会漏掉一个毒消息永久失败。事件内容不应包含凭据或用户全量资料,事件编号也不应该直接成为高基数指标标签;排障用受控日志按编号查询。

5. 调度只是触发器,多实例仍需协调

@Scheduled 的发现和任务注册由 Spring 的调度后处理器负责。fixedDelay 从上一次同步调用结束后计时,fixedRate 表达固定频率计划;是否并发还受调度器、多个注册点以及是否又提交异步任务影响。cron 要明确时区,服务器默认时区不应隐含决定账期。每个应用上下文都注册任务,部署三份通常就有三个调度入口;单例 Bean 只在自己的容器内单例。

仓库的实际例子是 Quartz:ScheduleUtils 选择任务类〔本地文件〕,按配置选择并发或禁止并发实现;QuartzDisallowConcurrentExecution〔本地文件〕使用 Quartz 注解。其约束针对 JobDetail 身份而非所有相同 Java 类;跨节点协调还要求正确的共享 JobStore 与集群配置,源码出现注解不能证明线上已部署集群。错过执行时间后的策略在 misfire 分支〔本地文件〕区分忽略、补一次和跳过,业务必须选择“补每个账期”还是“只算当前快照”。依据见 Quartz JobDetail 教程。

EnvStrategyTask〔本地文件〕先读环境和人数,再据时间执行策略;策略二〔本地文件〕检查开启状态、计算迁移量、调用迁移服务。两个实例读到同样人数后都迁移,可能超过预期目标;这只是由当前读改序列推导出的竞争场景,是否被下层服务或调度部署消除需要另查,不能当作已证实线上故障。教学设计应让“领取这一轮迁移”“按版本提交计划”“每用户幂等迁移”都有数据库条件,并在执行前重新读取关闭开关。关闭调度入口不会自动取消已经开始的任务。

6. 无外部服务的确定性实验

以下 Python 3 程序可直接在终端运行,只用内存模拟故障窗口;它验证协议反例,不验证 Spring 回调或数据库持久性。先观察丢失回调,再观察重复交付,最后用幂等集合把效果收敛为一次。不要把内存集合移植成生产幂等存储。

python3 - <<'PY'
db, cache = {'env': 'blue'}, {'env': 'blue'}
db['env'] = 'green'  # 模拟已经提交
callback = lambda: cache.clear()
callback = None      # 模拟提交后、回调前进程丢失
assert db['env'] != cache['env']

outbox = [{'id': 'lab-1', 'state': 'PENDING'}]
effects, deliveries = set(), []
def deliver(event):
    deliveries.append(event['id'])
    if event['id'] not in effects:
        effects.add(event['id'])
deliver(outbox[0])    # 执行成功、确认前崩溃
deliver(outbox[0])    # 租约恢复后再次交付
outbox[0]['state'] = 'DONE'
assert len(deliveries) == 2 and len(effects) == 1

generation, cache_value = 0, None
started_generation, old_value = generation, 'blue'
generation += 1     # 修改事件导致失效
if started_generation == generation:
    cache_value = old_value
assert cache_value is None
print('PASS: callback loss, duplicate delivery, stale-fill rejection')
PY

进一步操作实验在独立教学 Spring 工程中进行:使用内存 H2 与 TransactionTemplate,注册一个计数监听器;正常提交计数增加一次,主动回滚保持不变,无事务发布默认不增加。然后在提交成功后、回调执行前设置人为终止点,重启只扫描 outbox,确认待处理记录仍能恢复。不要直接给整个测试方法加默认回滚的 @Transactional 后等待 AFTER_COMMIT,这会让测试永远没真正提交。本实验的 Spring 部分是操作步骤,交付时未运行。

7. 练习与答案

练习一: 同一热点键一百个 miss,把 getIfPresent + supplier + put 换成 cache.get,是否就能保证数据库只查一次?答案: 同一缓存实例的同键加载可合并,但不同实例、加载失败后的再次请求、不同键和主动失效都可能产生更多调用;还要限制总回源并发并设置超时。

练习二: 环境更新已经提交,AFTER_COMMIT 删除缓存失败,能否再抛异常让原事务回滚?答案: 不能把已经完成的提交撤回。应保存可恢复失效任务或由同事务 outbox 驱动补偿;客户端看到错误也必须能查询原操作结果,避免盲重试副作用。

练习三: Quartz 禁止并发,为什么还需要幂等?答案: 禁止重叠不禁止前一次完成效果但丢失确认后的重放,也不证明两个不同 JobKey 不调用同一业务。幂等保护的是业务效果,协调保护的是执行竞争。

练习四: 关闭本地缓存后数据库 QPS 激增,最快的安全动作是什么?答案: 先保留必要失效,限制回源预算和非核心请求,分实例逐步切换,观察数据库连接等待;不要全量关闭后立刻把连接池翻倍。恢复时处理旧缓存和冷启动,授权类操作保持权威校验。

8. 来源、版本差异与本章完成边界

项目源码链接均相对本章定位到已检查的方法入口。可继续阅读 Spring 调度与异步与事务事件。Java 8 示例应选兼容 Java 8 的 Caffeine 2.x;Caffeine 3.x 的 Java 基线不同,核对其 官方项目说明。Spring 6.1 对响应式事务事件等有扩展,不能倒推 Spring 5.3 已具备相同行为。

本章交付的是教程和可复制实验,没有修改 LocalCache、用户环境服务、Quartz 或业务配置,也没有验证真实 Nacos、Redis、数据库、消息系统的连接及运行状态。源码中的定时统计、通知与任务入口只作静态分析,未实际触发。阅读完成的标准是能画出提交与崩溃的时间线,并指出每一步的持久化责任;运行情况应以自己隔离实验的记录为准。

原始文档 · spring-course/14-超时重试限流熔断与资源隔离.md

14 超时、重试、限流、熔断与资源隔离

数据库和远端变慢时,服务最危险的反应是继续接单、继续排队、继续重试。原本局部的依赖故障会扩散成线程、连接和内存耗尽。本章建立一套明确的资源协议:每个动作等多久、失败重做几次、总共接受多少、哪些请求先被保护。

1. 把请求拆成预算

假设一个查询接口的教学目标是800ms内完成。需要分别为排队、连接获取、SQL、远端调用和序列化留预算,且考虑并行阶段的关键路径。给每个阶段都配置800ms,串起来可能远超800ms。若允许重试,总预算也必须覆盖退避与再次执行。

一种思路是入口建立单调时钟的deadline,进入下个阶段前计算剩余时间,再取阶段上限与剩余时间的较小值。业务日期和日志时间仍使用合适的墙上时钟;经过时间测量不能被系统校时干扰。

剩余预算 = 请求总预算 - 已消耗时间
本次调用预算 = min(依赖阶段上限, 剩余预算 - 必须保留的返回时间)
没有足够预算 → 不再发起新的昂贵操作

这些不是对项目现有超时的测量。真正预算需从用户体验、依赖延迟分布和故障恢复策略倒推。

2. 四种超时不要混成一种

连接建立超时约束建立网络连接;连接池获取超时约束等待可用池连接;读取/调用超时约束等待响应;整体业务超时约束所有阶段和重试。SQL执行超时、数据库锁等待超时又可能分别生效。

调用方超时返回后,服务端可能继续工作,甚至完成提交。客户端取消、Future取消、JDBC cancel和数据库中断是不同机制,必须实际验证。因此订单写入超时后的正确动作往往是按幂等键查询结果或安全重试,而不是直接告诉用户“操作没有发生”。

超时太长会占住资源,太短会制造误失败和重试。应结合正常尾延迟和拥塞状态选择,并区分连接失败、锁等待、慢查询和响应丢失。只统一设成30秒,通常无法表达不同业务的成本。

3. 重试会乘法放大

HTTP客户端重试3次,业务RPC再重试3次,数据库层再重试3次,最坏可能出现27次底层尝试。每层都自认为“只重试三次”,整个系统却形成重试风暴。

应集中定义:哪些错误可重试、在哪一层重试、最大尝试次数、指数退避与抖动、总deadline、幂等键和重试预算。参数错误、权限错误、明确业务冲突一般不应重试。连接中断后的写入结果未知,也不能盲目当作失败重做。

死锁可在完整新事务中有限重试;连接池耗尽时立即密集重试常使拥塞更严重。重试预算可按正常请求量的一小部分限制,避免故障期额外请求超过系统承受力。具体比例需要实测,本课不指定通用常数。

4. 限速与限制并发各自保护什么

速率限制控制单位时间进入多少请求;并发限制控制同时占用多少资源。相同QPS下,延迟从20ms变成2s,在途数会增加约100倍,单纯QPS限流未必防止线程与连接耗尽。

令牌桶允许一定突发,漏桶式平滑可以控制输出节奏,信号量控制在途数量。多实例本地限流的总量会随实例数变化,扩容时必须重新计算;全局限流增加了协调依赖与延迟,又需要决定协调服务失败时放行还是拒绝。

ERP里优先按成本分层:库存写、普通列表、全历史报表、批量导出具有不同工作量。一条巨大导出不应只按“一次请求”与一次轻量字典查询同价计费。按租户配额还要防止某个大租户独占队列,公平调度可结合全局与租户并发上限。

5. 熔断与降级要对应真实行为

经典自动熔断器通常有关闭、打开、半开状态,根据一定窗口内的错误或慢调用比例决定拒绝,并用有限探测判断恢复。限流是在容量边界拒绝,熔断是在依赖不健康时减少尝试,降级是提供可接受的替代服务;三者常协作但不是同义词。

项目CircuitBreakingConnectFilter〔本地文件〕根据配置快照中的JDBC URL集合拦截执行。它展示的是规则驱动的数据库访问阻断,不能仅凭类名推断它自动统计错误率并半开恢复。

源码以完整URL匹配为主,参数串或地址差异可能影响命中。配置控制面与真实实例URL是否一致,需要脱敏核验;不要把完整含敏感参数的地址公开到监控面板。配置更新通过构造后原子替换快照降低中间状态风险,快照中的可变对象也应在调用约定上防止外部修改。

6. 按SQL文本阻断的适用范围

CustomSlowSqlFilter〔本地文件〕包含按规范化SQL文本和参数匹配后抛SQLException的路径。这个分支不是通用慢查询计时器,类名不能替代对实现的理解。

文本匹配会受别名、子查询、大小写、空格和ORM生成形状影响。还要测试实际Druid回调是否覆盖execute、executeQuery、executeUpdate、batch及不同Statement类型,不能从重写一个方法就宣布覆盖所有SQL。

SQL阻断适合作为应急阀门,但长期治理应回到入口查询形状、索引、工作量和资源预算。底层直接抛异常时,上层必须正确分类并避免自动重试形成风暴。异常消息中的SQL还需要检查对外暴露路径。

7. 降级结果不能伪造业务事实

商品描述短暂展示旧缓存可能被产品接受;库存可用量、资金余额和审批权限通常不能随意返回旧值或默认成功。“数据库挂了返回空列表”会让用户误以为没有订单,“扣库存失败返回成功”会破坏账实一致。

降级应显式标识数据时间、是否部分结果、是否暂停写入和可恢复方式。关键写业务宁可明确拒绝,也不能制造不可审计的成功。对于异步报表,可以保留任务等待,并展示延迟,前提是待处理量有上限且任务可靠保存。

8. 隔离要隔离到真正瓶颈

给报表单独线程池,却仍和库存共享一个已经饱和的连接池,不能完整保护库存。进一步隔离连接池也可能只是把总连接数翻倍,反而压垮同一数据库。应从共享资源图判断:CPU、堆、线程、连接、数据库IO、热点行、Redis和远端额度。

隔离可以是预算分配,也可以是独立只读库、物化数据集、单独服务或分时调度。每次拆分都有数据新鲜度、复制延迟与成本代价。读从库不能解决所有问题:读后写一致性、主从延迟及主库写负载仍需处理。

9. 应急变更也是有状态操作

NacosDbDegradeImpl〔本地文件〕提供规则加载入口。运维应记录发布版本、每实例已应用版本、最后成功时间、解析错误和当前命中数。空配置与格式错误的行为不同,必须有明确回滚约定。

应急顺序可为:确认受影响业务→阻止放大流量→保护关键写路径→保留诊断证据→定位根因→小流量恢复→观察积压消化。一次性全量恢复可能引发缓存回源和任务重试洪峰,要有恢复速率限制。

10. 演练与答案

  1. 数据库延迟升高十倍但QPS没变,为什么线程爆满?每次请求持有资源更久,在途量增长;需要并发与排队预算。
  2. 加入熔断后成功率下降,是否一定是坏事?主动拒绝可能保护关键服务,应看端到端业务成功与恢复,不单看调用尝试成功率。
  3. 所有错误都重试三次有什么问题?不区分不可重试错误、未知提交结果和拥塞,会放大成本且可能重复写入。
  4. 配置发布成功但某实例没阻断:检查本实例应用状态、URL匹配、实际SQL回调和配置开关,不能只看控制台。

本章容量数字均为教学假设,项目过滤器只做源码分析。参考Spring事务资源管理与JDK执行器拒绝策略,实际RPC与Druid行为需用项目锁定版本验证。

原始文档 · spring-course/15-可观测性JVM诊断与容量规划.md

15 可观测性、JVM诊断与容量规划

性能专家的价值不在于记住多少参数,而是能把“系统慢”拆成可证伪的假设,找到工作量和等待的来源,再证明改动没有损害正确性。本章给出ERP接口、任务和数据库联合诊断方法。所有命令都是供隔离或获准诊断环境使用的示例;本次没有对业务进程抓堆或压测。

1. 建立用户、应用、资源三层指标

用户层看操作成功率、端到端延迟、报表新鲜度、任务完成时间和库存一致性。应用层看请求率、错误分类、p50/p95/p99、SQL次数、远端次数、批次大小和队列等待。资源层看CPU、堆、分配率、GC暂停、线程、连接、数据库扫描与锁等待。

每层都不可缺。CPU低但接口慢可能是在等连接;接口200很多但业务码失败很多,用户仍然失败;导出执行很快但队列等了一小时,用户体验仍很差。要区分服务时间与排队时间。

SLO是用户可理解的目标,例如“有效查询99%在某个预算内完成”“已接受导出在规定窗口完成”。具体阈值应由业务确定。错误预算是可以接受的失败空间,帮助决定是否继续发布,而不是允许随意丢业务数据。

2. 百分位的使用边界

p99表示某个统计范围内约99%的样本不超过该延迟,不代表最慢请求,也不能把多个实例的p99简单平均成全局p99。聚合应使用可合并的直方图桶或相应统计系统。采样、桶边界和请求量都会影响解释。

平均延迟也可能掩盖少量极慢请求。对于扇出调用,一个请求等待多个依赖全部完成,整体尾延迟可能被最慢支路主导;减少扇出数有时比优化单次调用更有效。不要把每个阶段的p99直接相加当成端到端p99的精确结果,它们的相关性与分布不同。

3. 一条慢请求如何拆账

总耗时
 = 入口排队
 + 业务CPU执行
 + 连接池等待
 + SQL执行/锁等待
 + 远端等待
 + 序列化与响应写出

实际存在并行时要看关键路径而非机械求和。Trace让你看某一条请求的时间分布,指标让你看群体趋势,日志补充业务状态和异常细节。只有日志而没有持续指标,通常只能在事故后猜测;只有指标而没有请求关联,也难解释特定租户为什么慢。

SQL次数尤其值得记录。100条订单每条查一次明细,数据库单次延迟只有5ms也会累计明显成本。把SQL并行化可能暂时降低单请求时间,却增加数据库瞬时竞争。09章的工作量账本应成为接口评审材料。

4. 指标标签与日志不是越多越好

将orderId、userId或任意SQL作为监控标签会造成高基数时间序列,指标系统本身可能被撑爆。标签应使用受控维度,如接口模板、结果类型、执行器名称;个体标识适合受控日志与trace,必要时抽样。

日志记录完整入参、批量明细和结果对象会增加序列化、IO和敏感信息风险。应优先记录数量、摘要、耗时、traceId和脱敏错误。异步日志也有队列和丢弃策略,不能因“不在业务线程写磁盘”就认为没有容量上限。

项目MDC拦截器与TTL执行器说明已有追踪接入点,但是否覆盖所有任务、是否清理上下文、是否正确采样仍需验证,不能把“用了Sleuth”当可观测性验收。

5. JVM内存:堆之外还有资源

堆中保存业务对象,但进程RSS还包括线程栈、元空间、代码缓存、直接缓冲、JNI及其他本地分配。堆没有达到Xmx而容器被杀,并不矛盾。线程池无限扩张也会消耗本地内存。

常见症状要分别诊断:分配率高但GC后回落,可能是对象抖动;GC后基线持续抬升,可能有长期持有或业务缓存增长;堆稳定但RSS增长,可能是堆外或线程等资源。不要看到OOM就只加Xmx。

导出路径中特别检查:分页列表是否累积、Map是否跨页不清理、Future闭包是否持有原始大集合、输出缓冲是否重复复制、缓存是否无界、ThreadLocal是否持有请求对象。

6. 诊断命令从低成本开始

下面的PID必须由你明确选择,不能直接照抄到任意业务进程。可用命令随JDK版本和发行版变化,先查jcmd <PID> help。示例偏向本次实验使用的JDK17,不能假定旧Java8发行版均支持相同命令。

jcmd <PID> VM.version
jcmd <PID> Thread.print -l
jcmd <PID> GC.heap_info
jcmd <PID> JFR.start name=erp-diagnosis settings=profile duration=60s filename=/tmp/erp-diagnosis.jfr

线程栈成本通常较容易控制,但频繁采集也有代价;JFR用于观察CPU、分配、锁与IO等事件,配置与事件支持需确认。类直方图或堆转储可能触发停顿和巨大磁盘写入,且包含业务敏感数据,必须预留空间并限制访问,不能作为第一反应无脑执行。

这类提醒对应真实诊断操作,不是要求本教程运行这些命令。本次仅运行独立测试JVM,没有连接业务进程。

7. 线程栈如何定位等待

大量线程停在连接池borrow/getConnection附近,说明连接获取等待,继续检查连接是否被长事务或慢SQL占有。大量线程停在socket read可能是依赖慢;但要结合客户端超时和远端状态。CPU高时观察热点栈是否是序列化、字符串处理、压缩或业务循环。

Java线程BLOCKED经常与monitor竞争有关;WAITING/TIMED_WAITING可能是正常队列、Future等待、park或条件等待。线程状态本身不是根因,需查看持有者、等待者、持续时间和重复采样。数据库死锁通常要查数据库锁等待图,Java栈只能告诉你正等SQL返回。

8. 容量模型:同时限制多个资源

假设教学负载每秒100请求,每请求平均占数据库连接0.08秒,则平均连接在用约8条。这个估算不含突发、尾延迟、事务嵌套和后台任务,也不说明配置8条足够。继续增加连接数会增加数据库并发,可能使单条SQL变慢,不能无限线性扩展。

再设每请求CPU时间3ms,在理想估算下每秒需要约0.3核CPU;但数据库可能先饱和。容量上限取决于最先达到约束的资源,而不是机器核数。要为HTTP、导出、同步和调度分配共享预算,实例数变化后重新计算集群总量。

连接等待时间、队列最老年龄和数据库锁等待通常比“已经OOM”更早提示问题。应在饱和拐点之前拒绝或减速,而不是把最大吞吐点当长期运行点。

9. 压测不是把并发数字调到最大

先定义业务混合比例、数据规模、热点分布、缓存命中率、读写比例和错误条件。准备足够真实的索引统计与数据倾斜,固定测试版本和环境。暖机与冷缓存场景应分别测,不能只报告最有利结果。

逐级增加到达率,记录吞吐、错误率、p99、连接等待、CPU与GC;找到哪项先出现非线性增长。测试工具若采用“收到响应才发下一次”的闭环方式,服务变慢时它会自动降低到达率,可能掩盖积压。应按目标流量模型选择工具,并记录超时与未完成请求。

还需要持续测试与故障测试:高负载保持后是否内存持续增长;从库延迟时是否误读;缓存失效时回源峰值;一个依赖慢时是否拖垮其他业务;恢复阶段是否发生重试洪峰。

10. 性能改动的验收表

维度 改动前后都要记录
正确性 行数、金额、去重、租户隔离、边界数据
工作量 SQL数、扫描行、远端次数、写放大
时延 排队、执行、端到端p50/p95/p99
资源 CPU、堆峰值、分配率、连接及线程
稳定性 拒绝、超时、重试、恢复时间
语义代价 数据新鲜度、部分成功、快照口径

11. 练习与答案

一:CPU只有20%就能加线程吗?先看数据库与连接等待,CPU闲可能是依赖饱和。

二:p99下降但失败率上升是否优化成功?不一定,可能把慢请求全部拒绝导致幸存样本更快,应按业务SLO综合看。

三:增加缓存后数据库压力下降是否结束?还要验证一致性、热键、失效洪峰、内存与恢复行为。

四:怎么证明一次优化是你改动造成?控制数据、版本、环境和负载,保留基线与重复样本,解释统计波动,并验证业务结果相同。

参考:Boot 2.7生产监控能力、JDK17 jcmd。未对本项目做生产容量测量,不提供虚构QPS承诺。

原始文档 · spring-course/16-Spring测试发布与故障演练.md

16 Spring测试、发布与故障演练

教程里的代码“看起来正确”不够,必须知道哪些结论被什么证据支撑。普通单元测试、容器测试、数据库集成、端到端与压测解决不同问题。本章既解释测试策略,也说明本课程实际执行到哪一步,避免把H2成功包装成生产安全证明。

1. 测试分层对应不同的不确定性

层次 主要回答 不能证明
普通Java单元测试 业务计算、状态转换正确吗 Spring代理、数据库行为
小型Spring Context 注入、生命周期、代理是否生效 Boot完整装配及外部服务
MVC或数据切片 局部框架集成正确吗 完整业务与真实依赖链
目标数据库集成 SQL、约束、事务行为正确吗 生产分布与容量
端到端 用户路径与多组件协作正确吗 所有并发交错、长期资源趋势
压测/故障演练 资源上限和恢复行为如何 未测试的数据与故障组合

测试应该有明确假设和失败标准,不能仅以“执行时没有报错”作为通过。库存测试应断言库存不负、重复事件不多扣、审计匹配;导出测试应断言不漏不重、权限隔离、失败后可恢复。

2. 先用手工DI测试业务

如果一个计算税额或选择库存策略的服务必须启动整个ERP才能测试,通常依赖边界太宽。通过构造器注入一个小接口,测试可使用内存替代。替代对象应模拟协议语义,如“条件更新影响0行”,而不是永远返回成功。

不要把所有协作对象mock掉后只验证调用过几次,就宣布业务正确。调用次数适合验证N+1回归等明确成本约束,业务结果仍要断言。测试实现细节过多会让重构困难,却无法发现真实数据错误。

实验室IocTest〔本地文件〕第一项就是脱离Spring的手工DI,随后才用Context验证容器选择。这能帮助你区分设计能力与框架装配能力。

3. 测代理必须通过容器取得对象

直接new Service()调用@Transactional方法,测试的是普通Java方法,不会自动验证事务。实验室TransactionProxyTest〔本地文件〕建立真实Spring Context和DataSourceTransactionManager,通过代理调用,并在方法内部检查事务是否激活、在外部查询实际持久化结果。

外部调用失败后数据不存在,与self调用失败后自动提交的数据仍存在,形成可观察的对照。这样的测试比只检查注解是否存在更有价值。REQUIRES_NEW与checked exception同样验证数据库结果,而不只看异常类型。

Spring测试框架常支持测试方法事务及默认回滚。它可能让所有测试共享一个外层事务,从而掩盖服务没有正确开启事务的问题,还可能让提交后事件没有真正触发。测试服务边界时应显式设计提交与观察方式,不要让测试事务替业务事务兜底。

4. H2的价值和边界

H2方便隔离验证JDBC事务与Spring代理,也容易为每个测试建立独立库。它不是MySQL InnoDB。排序、NULL、锁范围、隔离、SQL方言、执行计划、upsert及驱动批处理都可能不同。

因此本课程的11项测试证明框架与JDK机制,不证明项目SQL在MySQL上的性能,也不证明Redis锁或主从路由。需要目标数据库测试时,应创建独立数据库和明确版本,使用项目相近表结构与索引,并避免生产配置。

不应为了让H2通过而改写业务SQL语义,然后宣称MySQL已验证。可分开保留机制测试和方言集成测试,并清楚标注运行条件。

5. 并发测试要可控、可结束

实验室ExecutorTest〔本地文件〕使用CountDownLatch建立时序,有界get/await,finally中释放与关闭。验证的是线程池接收和上下文机制,不做机器吞吐比较。

业务并发实验可以安排两个事务同时读旧版本,再同时尝试条件更新,断言只有一个成功;或者并发发送同幂等键,断言只产生一笔业务影响。即使测试过程可重复,也只能覆盖设计的交错,仍需由约束和协议保障未覆盖时序。

线程池测试失败后若不清理线程,后续测试可能受干扰甚至进程不退出。资源清理也是测试质量的一部分。

6. 性能回归如何保持有意义

普通CI机器噪声很大,用“必须在10ms内”验证业务正确性容易产生不稳定测试。更稳妥的低成本检查包括固定数据集下SQL次数上界、分页每批最大记录数、不构建全量集合、拒绝超额请求等结构性约束。

真正吞吐和p99应在稳定环境中测试,记录机器、JVM、数据库版本、数据分布、并发与暖机。对比要包含正确性,不接受为了减少扫描而漏掉数据、为了降延迟而偷偷返回旧结果。

7. 发布数据库变更要兼容滚动部署

发布期间新旧应用可能同时运行。新增非空字段、修改枚举、删除列或更改消息格式,都可能让旧版本立即失败。常见路径是先扩展兼容结构→新版本双读/迁移或渐进使用→验证回填→收敛旧路径→最后删除。

回填应按有界批次、checkpoint和限速执行,不能在应用启动时每实例同时全表扫描。大索引创建的锁和IO成本依数据库版本与操作方式而异,必须在变更计划中验证,不能用“在线DDL”四个字保证无影响。

回滚应用版本不一定能回滚已经变更的数据语义。资金和库存写入尤其需要前后兼容与修复计划。配置回滚、消息兼容和缓存版本也需要一起考虑。

8. 故障演练矩阵

注入点 希望观察的行为 失败信号
任务提交后进程终止 持久任务被重新发现 已接受任务永久消失
SQL后响应丢失 幂等重试返回一致结果 重复扣库存或重复订单
连接池耗尽 有界等待与清晰拒绝 无界排队、线程持续增长
缓存清理失败 重试/修复收敛 长期无界脏数据
导出上传后崩溃 分块可校验并恢复 漏行、重复、未授权文件
权限撤销 按协议阻断后续访问 旧任务绕过下载鉴权

演练前记录基线、注入范围、自动停止条件和恢复步骤。不能把线上用户当测试数据;本次只提供演练方案,没有执行这些业务故障注入。

9. 发布后观察什么

先检查实例就绪、配置版本、错误分类、连接等待、队列最老年龄和业务关键指标。某个接口平均耗时下降但任务积压持续增长,可能只是把同步工作转到了后台,并没有真正解决成本。

灰度应能区分新旧版本指标,覆盖大租户和热点数据,不只测试内部账号。回滚触发条件应该在发布前定义,例如库存一致性异常立即停止、错误预算过快消耗暂停扩大,而不是事故后临时争论。

10. 练习与答案

一:mock Mapper后事务测试通过,有意义吗?只能验证控制流;没有实际事务资源就无法证明回滚。

二:测试方法自带事务,服务没有@Transactional也通过,怎么办?移除外层兜底或显式分离事务边界,在提交后从独立观察点验证结果。

三:压测提高到1000并发,错误很多但QPS更高,能交付吗?需要在成功率、尾延迟和资源稳定约束内评估有效吞吐,不能只看尝试数。

四:代码回滚后新字段旧数据仍存在,算回滚失败吗?需要事先区分代码回滚、数据兼容和数据修复,不能假设三者自动同步。

实际执行记录见验证记录,运行方法见实验室说明。参考:Spring 5.3测试。

原始文档 · spring-course/17-注解速查与机制对照.md

17 注解速查与机制对照

注解是元数据,不是独立执行引擎。看到注解时应追问:谁读取它、何时读取、创建什么定义或拦截器、调用满足哪些条件、异常怎样反馈。本章按机制组织常用注解,配合01—08章阅读,不代替逐章推导。以Spring5.x/Boot2.x项目为主,Spring6/Boot3的Jakarta迁移、方法可见性等需单独核对。

1. 注册与装配:让对象进入容器

注解 主要读取者/阶段 能力与容易误解的边界
@Component 组件扫描与BeanDefinition注册 注册候选Bean,不自动保证线程安全
@Service Component体系 表达业务层角色,不自动开启事务
@Repository 组件扫描及适用异常转换设施 持久层标记,转换能力取决于实际装配
@Controller / @RestController 容器注册与MVC处理器发现 后者组合响应体语义,不替代鉴权校验
@Bean 配置类解析、工厂方法 返回对象由容器管理,适合外部库与显式装配
@Configuration 配置类解析与可能的增强 full配置方法调用与lite模式不一样
@ComponentScan 扫描定义阶段 范围过大可能引入重复或不相关配置
@Import 配置解析 可导入配置、Selector、Registrar,常被@Enable封装
@ImportResource 配置解析 引入XML定义,项目Dubbo XML属于此类入口

一个普通类上的@Bean不等于full @Configuration方法调用会被拦截。proxyBeanMethods=false用于不需要配置方法互调保持容器单例语义的场景,推荐工厂方法参数显式注入,避免对普通Java调用产生误解。@Bean方法内部new返回的目标可由容器管理,但其内部另外new出的协作者不自动成为独立Bean。

项目启动入口〔本地文件〕导入XML并扩大扫描范围。实际装配同时来自扫描、工厂、导入和starter,不能在某包没找到@Component就断言没有该Bean。

2. 注入:选择依赖而非凭名字猜

注解/方式 常见语义 需要验证
构造器注入 必需依赖通过构造契约提供 多构造器选择,循环依赖与测试替身
@Autowired Spring按类型等规则解析注入点 多候选、required、泛型和集合规则
@Qualifier 缩小候选集合 与Primary/名字及自定义限定符的关系
@Primary 多候选中优先选择 不等于所有集合注入只保留它
@Resource 资源注入规则 名称与类型回退、javax/jakarta版本
@Value 属性或表达式注入 默认值、类型转换、敏感内容与动态更新
@ConfigurationProperties 批量绑定配置对象 前缀、校验、注册方式及最终配置来源
ObjectProvider 按需取得或遍历依赖 每次获取与作用域、缺失/多候选处理

集合注入可以构建策略表,例如平台编码映射到不同物流适配器;需要检查重复编码和未支持平台,不要用Map.put静默覆盖。接口不是为了多写一层文件,而是隔离会变化的协议与实现,稳定的业务值对象不必全部接口化。

@Lazy延后创建或通过代理延迟获取,能缓解某些启动依赖,但可能把配置错误推迟到第一次请求。循环依赖不应优先靠@Lazy和setter强行解决,先检查两个服务是否职责纠缠、是否能抽出共同协调者。Boot不同版本对循环引用默认策略不同。

3. 生命周期与作用域

@PostConstruct在相应生命周期处理器支持下执行初始化,@PreDestroy用于销毁回调;InitializingBean、DisposableBean和@Bean(initMethod/destroyMethod)是其他入口。准确顺序应结合实际接口、注解和后处理器,不能给出一张无前提的万能顺序图。

@Scope("singleton")通常是每容器一个实例,不是整个集群只有一个;prototype按获取创建,容器通常不负责完整销毁周期。将prototype直接注入singleton,singleton获得的那次引用不会每调用方法自动变新;需要Provider或作用域代理来表达后续获取。

request/session作用域与Web请求上下文相关,异步线程未必携带该作用域。把request对象长期存到队列不仅可能脱离生命周期,也会保留大量请求内存。工作任务应复制必要的不可变身份和参数,而不是捕获整个Controller上下文。

@DependsOn表达初始化/销毁依赖顺序,不等于业务调用互斥,也不等于确保远端服务已准备好。项目AsyncTemplateConfig〔本地文件〕有此用法,要区分envConfig Bean已经初始化和外部系统已经可用。

4. 条件与Boot启用注解

@SpringBootApplication组合配置、自动配置和扫描相关能力。@EnableAutoConfiguration通过候选导入与条件评估注册自动配置,@ConditionalOnClass、@ConditionalOnMissingBean、@ConditionalOnProperty等决定是否匹配;条件看的是当时的类路径、Bean定义和属性,不是某个对象“应该存在”的愿望。

@Profile也影响注册。配置文件存在不代表激活,命令行、环境变量、配置中心和程序化来源可覆盖。绑定成功后仍要验证值的业务范围,如线程数正值、队列容量上限、超时预算,不能让错误配置把实例变成无限排队。

自定义@EnableX通常通过@Import连接注册逻辑,但私有注解实现未提供时,只能描述入口和被导入能力的证据,不能编造内部源码。项目@EnableTableSharding、@EnableActionTemplate等应结合实际依赖解析后继续追踪。

5. AOP与事务:调用必须跨过增强边界

@Aspect声明切面,@Around控制方法前后和异常传播,@Before/@AfterReturning/@AfterThrowing分阶段观察,@Order影响优先级但需结合调用栈理解进入/退出顺序。日志切面若吞异常返回默认值,可能改变事务和接口语义;Around忘记proceed可能根本不执行业务。

@Transactional描述事务属性,由事务拦截设施读取,不是字节码中自动包含BEGIN/COMMIT。自调用、非托管对象、方法可见性、管理器选择、线程切换都影响生效。readOnly不自动替你路由副本,timeout也不等于端到端HTTP截止时间。

@EnableTransactionManagement注册相关支持,与项目数据库事务管理器共同工作;存在注解但选择错误资源时,某些写入可能在事务外。多数据源场景必须证明Mapper实际连接参与哪一个事务。

6. 异步、调度、缓存与事件

@Async依赖启用设施和代理路径,执行器选择决定队列、线程和拒绝。返回void的异常与Future异常处理不同;调用者忽略Future可能看不到失败。自调用不会因为方法上有@Async就自动换线程。

@Scheduled由调度设施注册,fixedDelay与fixedRate语义不同,cron受时区影响;每个应用实例都可能注册自己的任务,不能把单机调度当分布式唯一执行。@EnableScheduling开启能力,不解决重叠、幂等或任务持久化。

@Cacheable、@CachePut、@CacheEvict通过缓存拦截器处理key与更新,后端CacheManager决定实际存储。默认key若没有可信租户维度可能混数据;返回的可变对象在本地缓存中共享也要考虑修改风险。缓存注解与事务注解的顺序影响删除是否真在提交后。

@EventListener通常是容器事件监听入口,执行是否同步取决于广播器和监听器配置。@TransactionalEventListener绑定事务阶段,AFTER_COMMIT不等于持久可靠队列:提交后进程崩溃仍可能没有执行监听。事件中再次写库还需明确新的事务边界。

7. Web校验与安全注解

@RequestMapping及派生Get/PostMapping定义路由;@RequestBody走消息转换,@RequestParam/@PathVariable绑定不同位置。@Valid触发约束验证还需相应验证设施,@Validated支持分组及方法校验相关用法。字段格式合法不等于业务归属合法,更不等于有权访问。

@ControllerAdvice/@RestControllerAdvice统一异常和绑定逻辑,不能把所有异常转HTTP200再让监控只看状态码。@PreAuthorize等方法权限需启用对应安全支持,表达式中使用的身份必须可信;Controller权限不覆盖直接RPC或任务入口,业务层仍需定义权限边界。

@JsonIgnore、@JsonFormat等属于序列化库范畴,非Spring容器注解;Lombok@RequiredArgsConstructor属于编译期代码生成,也不是运行时注入器。它生成构造器后,Spring才能按构造器注入规则处理。分清处理者,才知道出问题应该看编译产物、容器日志还是HTTP转换器。

8. 阅读任意注解的六步法

找定义与@Retention/@Target;找元注解与@Import;找扫描或后处理器;找注册后的Bean或Advisor;验证调用是否到达它;用最小反例确认失败边界。自定义注解只有被读取才产生功能,@Retention(RUNTIME)只是允许运行时读取,不会自动执行。

练习:@Service+@Transactional+@Async的一个方法会发生什么?答案不能只列三个名词,应说明代理链顺序、调用线程、事务在哪个线程创建、执行器拒绝、异常观察及自调用边界,最后用测试验证当前配置。

练习:@Primary是不是最高优先级安全控制?不是,它解决依赖选择,不限制调用权限。若生产错误装配测试实现,应检查条件/profile和配置,不用安全名词掩盖装配问题。

官方查阅:Spring5.3核心、事务、MVC、Boot2.7自动配置。

原始文档 · spring-course/18-综合实战大型ERP可靠导出系统.md

18 综合实战:大型ERP可靠导出系统

图解 · 可横向查看
可靠导出:任务、文件和数据库之间的恢复边界持久任务抢占后分批上传并短事务记录进度,故障后退避重抢,全部完成才发布成功。 可靠导出:任务、文件和数据库之间的恢复边界PENDING任务已持久化RUNNINGowner+epoch+租约分块上传不可变对象+校验和短事务记账块记录+连续checkpoint继续下一块检查租约 / 取消 / 预算RETRY_WAIT过期回收 / 有限重试SUCCEEDED发布完整manifest抢占确认上传还有数据下一批全部核验完成故障/过期退避后重抢上传后、记账前崩溃:允许孤儿对象,不能提前推进checkpoint。本图省略永久失败与取消终态;只有连续完成前缀可被安全跳过。
可靠导出的持久任务与分块恢复边界

图示为教学简化,需结合下文的适用条件、故障窗口和项目证据阅读。

这一章把IoC、事务、SQL、线程池、上下文、授权与恢复串成一个完整设计练习。它是从本目录真实代码提炼的教学方案,不是声称项目已经实现了全部能力,也不是可以直接部署的生产模块。下面的DDL和伪代码尚未在MySQL运行;完成实验时要使用独立库和测试对象存储。

1. 先定义正确性,再讨论速度

假设用户需要导出一个租户在限定时间内的订单,最多涉及千万级记录。千万级是设计场景,不是本次测得的项目数据量。我们要求:租户不可越权;同一请求重试不重复接单;已接受任务可恢复;最终文件不漏不重;资源有界;完成与失败可追踪;下载时重新鉴权。

先确定数据口径。本方案选择“导出一个预先确定且不可变的订单快照版本”,分页基于该版本。若实际系统没有快照,可采用其他口径,但必须重新分析更新和插入造成的漏重。固定时间窗口本身不等于不可变快照。

再确定交付语义:用户得到jobId时任务已持久化;文件只有在全部分块验证并发布manifest后才标记成功;中间文件不可作为完成结果下载。允许内部至少一次尝试,通过确定块编号与校验实现业务去重。

2. 用依赖倒置组织模块

ExportController
  → ExportApplicationService
      → AuthorizationPort
      → ExportJobRepository
      → SnapshotCatalog

ExportScheduler
  → ClaimRepository
  → ExportWorker
      → SnapshotOrderReader
      → ChunkStorage
      → ExportJobRepository

ApplicationService依赖用例需要的接口,JDBC、对象存储SDK和线程池在配置层提供实现。这样单元测试可用内存对象验证状态机,集成测试再替换成真实适配器。接口的价值是表达边界和语义,不是给每个工具类都创建一个同名接口。

借鉴项目AsyncTemplateConfig的构造器装配思路,但将执行器生命周期、拒绝策略和容量显式定义。借鉴广告同步的“读一页、处理一页、推进原始游标”,但为导出文件增加跨资源恢复协议。

3. 数据模型与幂等接单

以下DDL省略具体排序规则与全部审计字段,最终应按目标MySQL版本验证:

CREATE TABLE export_job (
  id BIGINT NOT NULL PRIMARY KEY,
  tenant_id BIGINT NOT NULL,
  request_key VARCHAR(80) NOT NULL,
  request_hash CHAR(64) NOT NULL,
  snapshot_id BIGINT NOT NULL,
  status VARCHAR(24) NOT NULL,
  last_order_id BIGINT NOT NULL DEFAULT 0,
  next_chunk_no INT NOT NULL DEFAULT 0,
  processed_rows BIGINT NOT NULL DEFAULT 0,
  attempt INT NOT NULL DEFAULT 0,
  epoch BIGINT NOT NULL DEFAULT 0,
  lease_owner VARCHAR(80),
  lease_until DATETIME(6),
  next_run_at DATETIME(6) NOT NULL,
  manifest_key VARCHAR(255),
  created_at DATETIME(6) NOT NULL,
  updated_at DATETIME(6) NOT NULL,
  UNIQUE KEY uk_request (tenant_id, request_key),
  KEY idx_schedule (status, next_run_at, id),
  KEY idx_lease (status, lease_until, id)
);

CREATE TABLE export_chunk (
  job_id BIGINT NOT NULL,
  chunk_no INT NOT NULL,
  start_after_id BIGINT NOT NULL,
  end_id BIGINT NOT NULL,
  row_count INT NOT NULL,
  object_key VARCHAR(255) NOT NULL,
  checksum CHAR(64) NOT NULL,
  PRIMARY KEY (job_id, chunk_no)
);

接单先校验权限、筛选范围与租户配额,再计算稳定参数摘要,并插入PENDING任务。唯一键冲突时查询原任务,验证request_hash一致后返回原结果;不同参数同键返回冲突。摘要必须包含业务相关条件、格式版本和快照标识,不能直接对字段顺序不稳定的任意JSON字符串计算后假设等价。

幂等键保留期限也是协议。如果旧任务清理后同键重新出现,系统是否允许新任务必须明确。配额检查在并发下也可能超卖,需要数据库条件更新或有明确误差界限的配额机制,不能只先count再insert。

4. 抢占:不要长事务锁住整个导出

先查询少量候选,然后针对单个任务做条件更新。多个调度器可以看到同一候选,但只有一个条件更新成功。数据库时间用于租约比较,避免应用机器之间的时钟差异;数据库主节点切换等仍是需要演练的边界。

UPDATE export_job
SET status = 'RUNNING',
    lease_owner = ?,
    lease_until = DATE_ADD(CURRENT_TIMESTAMP(6), INTERVAL 60 SECOND),
    epoch = epoch + 1,
    attempt = attempt + 1,
    updated_at = CURRENT_TIMESTAMP(6)
WHERE id = ?
  AND status IN ('PENDING', 'RETRY_WAIT')
  AND next_run_at <= CURRENT_TIMESTAMP(6);

租约回收应有独立条件更新,将已过期RUNNING转为RETRY_WAIT或重新抢占,并增加epoch。需要考虑最大尝试次数、失败分类及退避。不要用一个复杂OR查询同时扫描所有状态而不检查索引计划;待调度与过期回收可用不同访问路径。

抢占后取得当前epoch。每次续租、推进checkpoint与最终成功都带id、owner、epoch、status及有效租约条件。旧worker即使暂停后恢复,也不能更新新执行者的状态。租约长度60秒只是教学值,应由批次耗时分布与续租预算确定。

5. Fencing保护哪些地方

UPDATE export_job
SET lease_until = DATE_ADD(CURRENT_TIMESTAMP(6), INTERVAL 60 SECOND),
    updated_at = CURRENT_TIMESTAMP(6)
WHERE id = ? AND lease_owner = ? AND epoch = ?
  AND status = 'RUNNING'
  AND lease_until > CURRENT_TIMESTAMP(6);

影响0行意味着不能继续自认为拥有任务,应停止新业务动作。epoch在数据库中能阻止旧worker推进,但对象存储若不检查epoch,旧worker仍可能上传。解决方式不是宣称“有fencing所以一切安全”,而是让上传写不可变且隔离的对象键,最终只有受epoch保护的manifest引用能成为正式结果。

例如对象键包含jobId、epoch、chunkNo和内容校验和。旧worker产生的文件成为待清理孤儿,而不会覆盖新worker的完成文件。对象存储条件写、幂等上传与访问权限应依据实际服务能力验证。

6. 一页处理的完整顺序

1. 检查任务状态和剩余预算
2. 按snapshot_id + tenant_id + order_id读一页
3. 转为有界输出缓冲,生成不可变分块对象
4. 上传并确认校验和
5. 在一个短数据库事务中:
   a. 校验并锁定当前job的owner、epoch、状态和租约
   b. 插入export_chunk,保证块编号唯一
   c. 推进last_order_id、next_chunk_no、processed_rows
6. 释放该页对象,进入下一页

第5步三项必须在同一事务,且重复块要核对边界与校验和;不能简单忽略唯一键异常就推进游标。若只有上传成功但事务未提交,重试会重新生成或核验相同逻辑块,旧对象可后续清理。若事务已经提交,新的worker从已提交checkpoint继续。

物理上传允许重复,但最终manifest按逻辑块编号只引用一份。快照数据与格式算法必须稳定,重试才能产生相同边界与内容。若算法版本变更,任务应固定版本或明确重建策略。

7. 分页与SQL工作量

SELECT order_id, order_no, amount, status
FROM export_order_snapshot
WHERE tenant_id = ?
  AND snapshot_id = ?
  AND order_id > ?
ORDER BY order_id
LIMIT ?;

候选索引是(tenant_id, snapshot_id, order_id)。若快照表存储订单明细,唯一游标可能需要order_id与line_id;不能沿用仅订单ID的游标。金额要用精确定点表示,导出ID用不会被表格软件或JS舍入的格式。

对每页1000订单取明细时可批量查询这一页ID,但IN大小需控制。也可以预构建适合导出的快照投影,减少运行时JOIN。选择要比较写入成本、存储、数据新鲜度和读成本。

8. 线程与内存预算

假设每实例分给导出的活跃连接预算2条,则不能因为机器有16核就开32个同时查询worker。可让执行器负责有限任务,信号量限制数据库阶段,但也要防止大量任务持有内存等待信号量。更清晰的初版是低并发、每任务单页在途。

队列保存jobId和少量上下文,不保存整页明细。拒绝时任务回到可调度状态,不能静默丢弃。上传与查询的并行流水线若以后引入,需要有界预取、独立预算和顺序发布,收益经过压测才保留。

处理一千万行不等于堆要容纳一千万对象。目标是瞬时内存约随批大小和并发变化,随已完成总行数保持有界。manifest如果包含过多块也需分页构建或限制,不要在最后一步又把所有内容合并到堆。

9. 成功、取消与下载

最后一页为空并不直接意味着可以返回成功。应核对块序号连续、游标边界、累计行数与校验和,创建不可变manifest,再用受owner/epoch保护的条件更新设置SUCCEEDED和manifest_key。跨资源仍可能产生孤儿manifest,但不能产生指向未完成文件的成功任务。

取消可采用CANCEL_REQUESTED状态,worker在批次边界停止,最终条件更新避免取消后又标成功。若业务允许任务完成与取消竞态,必须定义谁先成功改变状态谁获胜。不是所有已上传文件都要同步删除,可由保留期清理。

下载接口验证当前身份、租户、任务归属和状态,使用短时受限下载链接或代理流。对象键不可充当权限。日志不记录完整签名URL,任务详情也不暴露内部存储凭证。

10. 验收用例和答案

故障 期望结果
同键并发接单 一条逻辑任务,同参数返回同结果
上传后宕机 块未记账可重做,最终文件不重复
checkpoint提交后宕机 新worker从下一块继续
旧worker租约过期后恢复 不能推进状态,孤儿文件不被发布
一个租户提交海量任务 其他租户仍有预算,入口能拒绝
用户切换tenantId访问任务 授权拒绝,无文件信息泄漏
格式版本在执行中升级 老任务按固定版本完成或安全重建

练习一:为什么Redis锁不能代替epoch?锁过期后旧worker可能继续运行,持久状态与外部写入需要防止旧执行者越权推进。

练习二:为什么不是上传和DB一起加@Transactional?对象存储不是该JDBC事务的参与资源,必须设计崩溃恢复。

练习三:怎么验证“不漏不重”?用独立快照真值集合比对完整ID与金额,不只比较行数;相同的行数也可能同时漏一条多一条。

练习四:哪些部分已经运行?本章是设计与故障推演;本课程运行的是核心11项Spring/JDK实验,不包含该完整系统。落实此实战应单独增加目标数据库、存储适配与故障注入测试。

回读:IoC设计、批处理、线程池、可靠事件、数据库综合实战。

原始文档 · spring-course/19-故障复盘与能力验收.md

19 故障复盘与能力验收

成为能负责ERP后端的人,不是背出所有注解,而是在陌生代码和不完整证据下提出可验证假设,保护业务正确性,找到最小有效改进,并解释残余风险。本章用十个案例检验整套课程。案例是基于项目代码形态设计的练习,不表示这些事故已经在当前项目真实发生。

1. 事务注解在,库存仍部分更新

现象: 某库存批处理在第三个SKU报错,前两个仍改变。开发者说所有方法都有@Transactional。

先问: 业务承诺是整批原子还是逐SKU部分成功?入口从代理进入吗?有self调用吗?是否捕获异常继续?哪些SQL在TransactionTemplate回调外?是否多个事务管理器?Redis或远端变化是否被错误地当作同一事务?

参考判断: 项目库存组件存在逐SKU异常处理和局部事务边界的代码形态,应先明确实际承诺。部分成功可能是设计,不一定是框架失效。若要求整批原子,不能只扩大注解范围,还要评估锁、资源数量、长事务成本以及跨资源不可原子问题。

证据: 记录每个业务操作键、事务激活状态、提交时刻和实际数据库结果。用核心事务实验复现代理问题,再在独立目标数据库验证业务边界。

2. max线程数很大,队列仍持续增长

现象: pool core5/max10,但长期只有5个活跃worker,内存增长。

参考判断: 无界LinkedBlockingQueue会使后续任务先排队,通常不触发扩到max。增加max本身没有解决到达率大于服务率。项目ScmDistributorItemThreadConfig可作为代码阅读入口。

处理思路: 量化任务到达、执行时间、下游容量和队列对象大小;减少工作量;采用有界接收及可观察拒绝;持久任务分离接单与执行;按租户和资源预算限制并发。测试无界排队机制,不要在业务环境故意堆满内存。

3. 异步调用没有报错,却一直查不到结果

现象: 提交接口成功,Future永久等待,日志没有异常。

候选原因: 底层DiscardPolicy丢弃任务、任务挂在数据库等待、同池子任务join死锁、状态写入失败、异常未被观察。

参考判断: 先检查任务是否开始执行、线程栈和队列,再检查拒绝处理。标准submit与DiscardPolicy组合可能返回永不完成的Future,实验室可复现。项目包装器是否补偿必须另查,不能直接归罪。

验收: 过载时提交结果明确,业务状态最终收敛,等待有上界,已接受任务可恢复;只增加Future超时时间不算完成。

4. 大表导出越往后越慢

现象: 第一页50ms,后续秒级,CPU不高。

候选原因: 深OFFSET丢弃大量记录;每页执行全量COUNT;缺少合适索引;一对多JOIN膨胀;连接竞争或缓存冷热差异。

参考判断: 比较各页执行计划与扫描量,拆COUNT和列表耗时。Keyset使用完整稳定排序元组,游标与过滤条件绑定;它不是快照。参考项目广告同步的原始nick/sad_type/id推进,不能换成业务归一化昵称。

验收: 对同时间戳、NULL、空白值及并发更新定义语义,比较完整结果集合,测各页资源。不能只展示第一页更快。

5. 加缓存后偶尔读到旧权限

现象: 权限撤销后部分实例仍允许操作。

候选原因: L1未失效、广播丢失、TTL过长、缓存键缺身份范围、更新与失效乱序、请求已经持有旧授权快照。

参考判断: 区分数据缓存和授权缓存,对撤销定义传播时限。项目用户环境配置的DB更新、Redis失效与广播顺序可作为检查点;某一步异常是否阻止后续动作,要沿调用链看。缓存删除成功也不能排除旧读回填。

验收: 多实例、失效失败、重启和广播中断后权限按协议收敛。高风险操作可在权威边界再校验,不能把短TTL当严格即时撤权。

6. 租户A的后台任务出现租户B日志

现象: 线程池复用后trace或tenant字段混乱。

候选原因: singleton字段保存请求状态、ThreadLocal未清理、任务提交时未捕获、只依赖InheritableThreadLocal、包装顺序或CallerRuns路径改变上下文。

参考判断: 区分日志错误与真实数据越权,两者都要查,但不能凭日志单独证明数据泄漏。任务携带可信租户快照,执行前安装、finally恢复;SQL仍要带租户条件。核心实验可稳定复现ThreadLocal残留。

验收: 同worker依次执行不同租户任务、异常任务和嵌套任务,确认上下文正确;验证数据库访问集合与任务租户匹配。

7. 数据库连接池满了,扩连接后更慢

现象: 活跃连接增加,锁等待与p99同步上升。

参考判断: 池大小是数据库并发入口,不是免费资源。可能已有慢SQL、长事务、热点锁、REQUIRES_NEW额外连接或导出占池。先看连接持有时间和SQL等待,再决定是否扩池。

处理思路: 限制重任务并发,缩短合理事务边界,优化查询工作量,隔离关键业务预算。保持正确性条件,不把锁删掉或隔离随意降低来制造表面吞吐。

验收: 在相同成功率与正确性约束下,连接等待和端到端延迟改善;数据库吞吐不进入更差的拥塞区间。

8. 配置中心发布成功,部分实例仍不降级

候选原因: 实例未收到或解析失败、保留旧快照、完整JDBC URL匹配不一致、过滤器未挂到实际DataSource、SQL走了未覆盖回调。

参考判断: 项目CircuitBreakingConnectFilter是配置规则拦截,不能假设存在自动半开。建立“发布版本→实例应用版本→规则命中→上层响应”的证据链。日志不要泄露连接参数。

验收: 正常SQL、预编译SQL、批处理以及规则清空/非法输入分别测试。恢复流量分阶段,不让积压一口气回灌。

9. 任务完成了,文件却缺一页

候选原因: checkpoint先提交但文件未写;租约过期旧worker仍推进;上传成功后错误标记;分页排序不稳定;取消与成功状态竞争。

参考判断: JDBC事务不能包住对象存储。采用不可变分块、校验和、逻辑块唯一键、受epoch保护的进度和manifest发布,或明确从头重建。要写出每个崩溃窗口的恢复动作。

验收: 不能只对行数。对照快照真值的主键集合、金额与字段摘要;同时测试旧worker恢复及下载越权。18章提供完整设计推演。

10. 性能报告很好,上线还是失败

候选原因: 测试数据太小、没有热点租户、缓存全热、没有真实COUNT、只记录成功样本、工具闭环降低实际到达率、缺少持续测试和恢复测试。

参考判断: 性能证据必须包含负载、数据分布、硬件、软件版本、失败率、未完成请求和持续时间。报告的QPS若包含快速失败,不能代表有效业务吞吐。

验收: 保留可重现基线和原始指标,明确容量边界与适用范围。未经生产规模验证就写“支持千万数据毫秒级”不是专业结论。

11. 分阶段能力验收

阶段 必须能独立完成的产物
基础 手工DI实例、Bean来源图、请求调用链
机制 代理边界实验、事务传播对照、线程池拒绝复现
数据 SQL工作量账本、索引与分页方案、事务不变量
生产工程 资源预算、超时重试表、授权与日志边界
综合 可恢复任务状态机、故障矩阵、容量与回滚报告

可以按六个学习阶段推进,每阶段先读对应章节,再选本项目一个真实入口完成产物。学习时间依基础而定,不把某个周数当成为专家的保证。真正进阶来自在约束下作决策并接受代码、数据与故障证据检验。

12. 一份可复用的技术评审模板

业务目标与不可违反的不变量:
可信身份与租户来源:
入口、Bean依赖、代理和事务边界:
每请求SQL数、扫描量、远端次数:
数据规模、热点、分页和快照语义:
线程、队列、连接、内存预算:
超时、重试、幂等与未知结果处理:
缓存新鲜度、失效和修复:
故障状态、恢复动作和最终收敛条件:
指标、追踪、脱敏和告警:
测试证据、未验证项与上线回滚:

读代码时逐项填“已证实、推断、未知”。例如源码证明存在有界队列,却不能证明生产并发合适;测试证明事务代理有效,却不能证明线上路由到正确库。把边界说清楚,是可靠工程判断的一部分。

13. 最终综合题与参考答案结构

题目:一个租户触发全历史报表,接口超时后重试,后台线程池积压,数据库连接耗尽,其他租户库存接口失败。要求给出止损、根因、设计改进与验收。

参考答案应包含:先限制重报表入口和重试,保护关键库存预算;检查SQL、COUNT、OFFSET与长事务;将大报表改为持久任务和有界分批;定义快照、幂等键与文件恢复;按租户限额与全局数据库预算调度;拆排队与执行指标;故障恢复后限速消化积压。不能只写“加Redis、加线程池、分库分表”。

还要说明代价:异步报表增加等待和状态管理,物化数据增加存储与新鲜度问题,资源隔离降低部分峰值利用率但换来关键业务稳定性。对ERP,正确账本、租户隔离与可恢复性不能作为优化的牺牲品。

继续学习分布式模块时,应在这里的事务、幂等、租约与资源预算基础上深入共识、消息交付、跨服务一致性与容灾。当前课程先把Spring应用侧的机制和工程决策建立完整。

原始文档 · spring-course/开发陷阱深化.md

Spring 开发陷阱深化:事务标记背后的资源、时序与测试

本篇接续 AOP 与代理、事务传播、事件与可靠任务和 测试。已有正文解释了注解、传播类型与 Outbox,本篇不再背一遍表格,而是解决 ERP 开发中的下一层疑问:方法显示事务激活,为什么某张表仍提交了?自调用一定没有事务吗?补偿用了新事务,为何错误高峰反而无法落库?测试全绿,为什么提交后动作从未被测到?

每项明确区分源码事实、条件风险、改进设计、验证。源码仅代表本次审阅的文件与方法,不能证明所有入口、配置及线上行为;教学改造没有写入业务仓库。实验固定 Spring Framework 5.3.39 与 H2 2.2.224,采用同步、线程绑定、本地 JDBC 事务模型。不是对响应式事务、JTA、生产 Sharding-JDBC 多物理连接事务的验证,也不宣称项目实际运行的补丁版本与实验一致。

本次不读取真实连接配置或凭据,不启动 ERP,不连接服务;唯一执行的数据库是进程内 H2。两篇教程和隔离实验的事实边界汇总在 审阅闭环记录。SQL 范围、批更新和影响行数的另一半问题见 数据库深化篇。

1. 多数据源事务:URL 相同,也不代表同一事务资源

源码事实。 管理端 DruidConfig#L140〔本地文件〕 创建 @Primary 的动态数据源,放入主数据源,并按 Bean 是否存在尝试放入从数据源。MyBatisConfig#L118〔本地文件〕 接收 DataSource,将其传给原生 SqlSessionFactoryBean。另一个 MultiDataSourceConfig#L17〔本地文件〕 中的配置类代码是注释,不能被当作第二套已生效装配。这些证据只能画出候选资源链,尚未核验运行上下文中的事务管理器选择及私有依赖自动配置。

机制上,DataSourceTransactionManager 管理给定 DataSource 的连接资源;MyBatis-Spring 要让 Mapper 参与该事务,SqlSessionFactory 与管理器的数据源必须正确对应。Spring 5.3 DataSourceTransactionManager、MyBatis-Spring 事务装配

条件风险。 假设 A、B 是两个独立 DataSource 对象,即使 JDBC URL、账号和数据库都相同,A 管理器绑定的连接也不会自动覆盖 B 获取的连接。方法里查到 isActualTransactionActive()==true,只说明当前线程有事务状态,不证明每个 DAO 都用到了它。只检查事务注解或数据库名,会漏掉“一半回滚、一半保留”的跨资源写入。@Primary 只影响候选注入选择,不是多库原子提交协议。

改进设计。 把事务归属写成可审查的对应表,实际 Bean 名称由项目填写:

逻辑动作 事务入口 事务管理器管理的数据源 Mapper 工厂数据源 应有结果
库存及流水 一个应用用例 库存逻辑源 同一逻辑源 任一步失败均回滚
独立报表写入 单独用例 报表源 报表源 独立结果,不伪装为库存原子步骤
事件任务写入 业务原事务 业务源 业务源 和业务记录一起提交

多管理器时在注解或模板构造中明确选择管理器,并检查 MapperScan 对应的 factory/template。若事务管理器使用路由源,Mapper 却绕过它直连某个底层池,也需核验资源键和代理解包,不能只凭“最后都到主库”认定正确。诊断可以记录逻辑 Bean 名、资源绑定布尔值和去敏后的连接标识,不打印 DataSource.toString 或连接 URL。

验证。 新增 TransactionChecks#L68〔本地文件〕 的资源实验创建同 URL 的 A、B,A 事务里分别写两行,然后主动回滚。断言 A 写入消失、B 写入仍在,已通过。它使用 JdbcTemplate 验证 Spring 资源绑定,不是对生产 MyBatis 工厂的集成证明。下一步待执行测试是在隔离装配中同时用真实配置风格的工厂与 Mapper,注入第二步失败,再从事务外逐表检查。

练习与答案。 给两个管理器都起名 transactionManager 能解决吗?不能,名字甚至可能发生覆盖或歧义;必须让每个入口选择正确资源。两个本地事务先后提交,也不等于一个原子跨库事务。

2. 路由生效时机与上下文恢复:同一线程也有两条时间线

源码事实。 erp-item 的 DynamicDataSource#L17〔本地文件〕 继承 AbstractRoutingDataSource,用 InheritableThreadLocal 保存枚举键。DataSourceAspect#L39〔本地文件〕 设置目标源,finally 调用 clear。SlaveDataSourceAspect#L15〔本地文件〕 则显式标注顺序一,意图先设置从库偏好。这是两套不同机制的代码,不能把一个切面的顺序保证套给另一个。

条件风险。 AbstractRoutingDataSource 路由的是获取连接操作,不是每执行一条 SQL 都重新替换事务连接。官方路由数据源 API 因此时间线可能是:外层事务先在 A 获取并绑定连接,内层把路由键改为 B,Mapper 从事务资源取得的仍是 A 的连接;直到原事务清理后,新一次获取连接才可能使用 B。若引入懒连接代理,物理连接选择还涉及首次实际取用的时机,应按真实装配验证,不能只数注解顺序。

第二条时间线是上下文栈:外层设置 A,内层设置 B,内层 finally 直接 remove,外层继续执行时已失去 A。这是“清理了”仍可能不正确的场景。是否确有嵌套调用本次未证明;如果不存在嵌套,单层 finally 清理仍是合理防线。InheritableThreadLocal 只在创建子线程时继承初始值,并非线程池每次提交任务都刷新;复用线程容易保留过去任务的身份。Java 8 InheritableThreadLocal

改进设计。 路由键的进入与退出应采用作用域:保存旧值,设置新值,finally 恢复旧值;原来没有值才 remove。跨线程任务显式接收最小可信身份,在任务边界建立和清理自己的路由。不要复制 Spring 事务资源映射或 JDBC Connection 到子线程。业务中若要求切库,把边界拆清楚:结束上一笔本地事务后再开启另一用例,或明确采用独立事务并接受非原子语义。将“切换路由键”作为跨库事务方案是概念错误。

验证。 离线路由实验已在 A 事务内改成 B,断言前两条写入都留在 A;事务结束后的第三条写入才到 B。它用教学路由类验证标准 JDBC 绑定时序,没有加载生产切面、Hint 算法及分片数据源。嵌套路由、懒连接代理、线程池身份恢复是待执行矩阵:每层分别记录进入键、退出键、实际写入库,并验证异常分支恢复,而不只测试正常路径。

练习与答案。 把路由切面顺序调得更早,就能修复所有问题吗?不能。它只能影响当前穿过的增强链;外层已经绑定资源、内部自调用未经过切面、线程池复用上下文,都不是同一个顺序问题。

3. 自调用不等于“一定没事务”:真正失去的是新的拦截边界

源码事实。 StockComponentImpl#L1391〔本地文件〕 是 private 方法,却在 #L1427〔本地文件〕 显式执行 TransactionTemplate。这个事实不能用“private 方法事务注解失效”概括,因为它不是依靠 private 方法上的注解触发代理。模板会直接调用事务管理器,其执行语义见 TransactionTemplate 5.3 API。

条件风险。 代理模式下,同对象内部调用一个标记 REQUIRES_NEW 的方法,不会因此经过新的事务拦截。若调用前没有事务,可能直接自动提交;若外层已有事务,内层 SQL 仍可能参与外层事务,只是 REQUIRES_NEW、独立超时和回滚规则未生效。所以“内层查到 active=true”不能证明新事务已创建。新事务必须观察独立的提交与回滚结果,而不只观察一个布尔值。

已有实验 TransactionProxyTest#L48〔本地文件〕 已覆盖无外层事务的 self 调用;本轮增量覆盖的是有外层事务时的误判。真实库存模板也不应被过度解读:若模板采用 REQUIRED 并进入已有事务,它仍只是加入者,局部回调结束不代表物理事务提交。模板外的前置读取也可能处于更外层事务中,需继续看入口。

改进设计。 需要独立语义的操作放到另一个代理 Bean,并通过容器注入调用;需要精确小边界时采用明确管理器的模板。不要在共享单例模板上按请求临时修改传播或隔离属性,这会引入并发配置竞态;不同语义使用预先构造的不同模板。事务前读取的旧库存不能凭“进入事务后写了”获得新鲜性,写入仍要使用版本条件或业务不变量保护。

验证。 本轮实验对比两条路径:外层事务调用自己的 REQUIRES_NEW 方法后抛错,所有写入回滚;外层调用另一个 Bean 的 REQUIRES_NEW 后抛错,内层记录保留。两者均已通过。没有把教学反例标成生产库存自调用故障。待执行检查应选择真实用例入口,确认注入对象、目标方法增强链、模板管理器及异常越界位置。

练习与答案。 给 private 库存方法新增一个 @Transactional 能让模板的事务更可靠吗?不会自动形成第二道保护。应先验证模板已经管理哪些连接;多贴一个在代理模式下不可拦截的注解,可能只增加误导。

4. rollback-only:catch 改变了 Java 控制流,却未必改变提交结局

源码事实。 库存 事务回调#L1427〔本地文件〕 内顺序写两类库存;这使“第二步失败如何传播”成为实际需要核验的边界。另一方面,补偿调用#L2227〔本地文件〕 会捕获任务落库异常并加入原始异常的 suppressed 信息。这里不能看到 catch 就认定吞掉了所有失败,也不能把任意 catch 都说成会触发 UnexpectedRollbackException。

条件风险与机制。 考虑外层代理开启事务,调用另一个 Bean 的 REQUIRED 方法;内层抛运行时异常越过自己的事务拦截器,共享事务被标记 rollback-only。外层随后 catch 并正常返回,最后仍无法提交,通常在外层得到 UnexpectedRollbackException。相反,如果异常在同一方法内部被 catch,尚未越过负责回滚的拦截边界,且资源没有另行标记回滚,那么外层可能正常提交。默认回滚规则与传播细节以 Spring 5.3 事务传播文档 为准。

还要区分“主动把当前顶层事务标记回滚”与“参与者使共享事务意外回滚”:前者可能正常结束但回滚,并非总会抛 UnexpectedRollbackException。数据库异常是否使数据库事务不可继续、Spring 是否已标记回滚,也随资源和调用方式而异。因此不要把某条 PostgreSQL 或 MySQL 错误的行为推广到所有异常。

改进设计。 一个必须原子的库存用例不要把内部失败转成普通成功返回。允许失败的旁支明确独立提交需求,或者移至事务外处理。若业务要求局部回滚,先确定 NESTED/savepoint 是否适用:它仍属于同一物理事务,不是独立审计持久化。重试应在失败事务完全结束后开启新尝试,并使用幂等键;在已经 rollback-only 的事务里重试查询成功,也不能清除原来的回滚结局。

验证。 离线实验已经复现“跨 REQUIRED 边界后 catch,外层提交失败且零行”,以及“异常在方法内被 catch,写入提交”两种结果。待执行的业务测试应故障注入第二次 Mapper 调用,断言两张表最终状态与对外错误码;不能仅断言抛过异常,也不要 mock 掉所有真实事务资源后宣布回滚成立。

练习与答案。 把 rollbackFor=Exception.class 改上去就能解决异常被捕获后提交吗?不能。代理必须看到符合规则的异常,或事务已被明确标记回滚;返回一个包含 error 字段的 DTO,不会自动触发异常回滚规则。

5. REQUIRES_NEW 补偿:独立提交需要连接,也需要独立的数据依赖

源码事实。 CrossBorderForwarderCompensationServiceImpl#L38〔本地文件〕 的 record 明确使用 REQUIRES_NEW,创建补偿任务后调用 insertIgnore。提交入口#L266〔本地文件〕 标注事务,失败撤回分支在 #L2228〔本地文件〕 通过注入的 compensationService 调用它。独立记录失败后仍保留错误并记录需人工补偿,不应把该代码描述为已经保证补偿任务必达。

条件风险。 同一池中,外层事务挂起并不代表它的连接已经归还。设 N 个工作线程都持有一条外层连接,池总共 N 条,大家同时申请内层新连接:没有空闲连接可推进内层,也就无法退出外层释放连接。最终可能靠获取连接超时打破等待,这叫连接资源饥饿,未必是数据库检测到的行锁死锁。官方最新传播页也明确提醒新事务的额外连接需求;这里引用其资源论述,不把页面的新版本能力套进 5.3 实验。Spring REQUIRES_NEW 资源说明

N+1 只在“每个外层持一条、内层至多一层、没有其他竞争、内层能及时结束”等简化条件下提供推进机会,不是生产连接池推荐公式。另一个反例甚至不缺连接:外层更新了某库存行,内层补偿又更新同一行,内层等外层释放锁,外层同步等待内层返回。或者内层插入引用外层尚未提交记录的数据,出现可见性或约束等待。增加连接池无法消除这些依赖环。

不要从 Java 默认值认定线上容量。DruidConfig#L64〔本地文件〕 虽设置 maxActive,随后调用属性应用方法;DruidProperties#L53〔本地文件〕 重新设置容量与等待参数。本轮不读取其真实值,更不能用管理端的池大小推断 erp-item 的池。

改进设计。 补偿记录只带稳定身份、请求号及必要错误摘要,尽量不依赖外层未提交业务行;限制同时持外层连接的工作数量,并给获取连接与业务整体设置有界等待。补偿队列需要可观测的落库失败和人工恢复入口。对于可在业务事务中预先保存的可靠动作,考虑同库持久任务;对已经在外部成功而本地回滚的动作,明确独立补偿记录的失败窗口,不能因为用了新事务就宣布没有丢失路径。

验证。 已执行的实验只证明另一 Bean 的新事务可在外层回滚后保留记录,没有使用连接池,因而没有验证池饥饿。可执行但本轮待做的隔离池实验:池容量二,两线程各开启外层事务,使用屏障确保都持有连接,再调用独立新事务;获取连接超时设为有限值,断言等待有界且失败被记录。然后容量三重复,观察简化模型可推进;再单独构造同一行锁依赖,证明“有多余连接”仍可能等待。禁止拿生产请求触发这些演练。

练习与答案。 失败时再开一个新线程写补偿,是否免费解决连接问题?不会。新线程仍需要连接,也失去原调用栈事务和上下文;若只放进内存队列,进程崩溃还会丢任务。需要重新设计资源预算和持久化协议。

6. 提交后事件:监听器还拿得到资源,不代表原事务会再提交

源码事实。 UserEnvConfigServiceImpl#L150〔本地文件〕 中先更新 Mapper,再删除缓存,finally 发送通知;该方法处没有事务注解。这里只能确认局部顺序,不能证明外层没有事务,也不能断言它已经采用事务事件。以下 AFTER_COMMIT 是针对这类“数据库写完还有副作用”的教学改进,不是现有实现描述。

条件风险。 AFTER_COMMIT 默认只响应事务内发布且成功提交的事件;无事务发布默认不会执行,回滚也不会执行。回调阶段原事务已经完成,但某些资源可能尚未清理。此时用 REQUIRED 写数据库,可能仍访问原资源,却没有后续的原事务提交可以依赖。官方明确要求新持久写考虑独立事务;不要用“还能查询”“active 仍为真”来判定可继续追加提交。TransactionalEventListener 5.3 API

另外,不同回调入口的异常传播并不一致。TransactionSynchronization.afterCommit 与事务事件在完成阶段的适配不是同一个调用点,不能笼统保证“监听器异常一定抛给 HTTP 调用者”。无论错误最终记录、传播还是异步收集,都不能撤销已经成功的业务提交。回调阶段资源与错误处理的细节可对照 TransactionSynchronization API。

改进设计。 如果只是进程内失效提示,监听器幂等执行,并记录失败;需要新增持久审计则调用另一个 Bean 的 REQUIRES_NEW。它也有额外连接占用,不能绕开上一节的资源预算。若要求崩溃后恢复,应把业务变更与任务记录写进同一数据库事务,监听器仅唤醒扫描器。把 outbox 插入放到 AFTER_COMMIT 的新事务里,并没有消除“业务已提交、任务尚未写入”的窗口;这是二轮最容易误用的地方。

对页面操作接口,要区分业务已接受、数据库已提交、后续通知已完成。一次通知异常后的重试必须用原操作号查询状态,不能重新执行库存扣减。事件只传稳定标识和版本,不把可变实体、Connection 或登录上下文整个传给异步线程。多事务管理器场景还要确认事件绑定的是哪个事务的完成阶段。

验证。 离线小型 Spring Context 已验证三条路径:无事务发布不触发,主动回滚不触发,正常提交后触发一次;监听器调用独立事务写入的记录从事务外可见。没有测试向旧资源继续写入的驱动特定结局,也没有执行进程崩溃或真实缓存失败。待执行可靠性交付测试需持久任务存储,分开注入“提交前、提交后未执行、执行后未确认”三个停止点,检查恢复与重复效果。

练习与答案。 把 fallbackExecution=true 加上去让测试通过,可以吗?只有产品确实接受无事务时立即处理,才可以这样设计。它改变的是业务语义,不能用来掩盖测试没有建立事务或真实入口事务失效。

7. 事务测试陷阱:测试替业务兜底,反而隐藏了缺陷

源码事实。 旧实验 TransactionProxyTest#L69〔本地文件〕 手工创建小 Context,通过容器取服务,不在测试方法上加外层事务;独立提交验证#L87〔本地文件〕 从调用结束后的观察点查询结果。这种测试结构已经避免一部分自动回滚掩盖,本轮保留旧文件不改,新增更细反例。

条件风险。 若给测试统一加 Spring 测试事务,即使服务方法本身漏注解或 self 调用绕过代理,JdbcTemplate 仍可能加入测试替它开启的事务。测试最后回滚,“没有残留数据”的断言便看似成立;线上调用没有这个外层事务,前一步早已自动提交。相反,默认回滚的测试永远不进入成功提交阶段,AFTER_COMMIT 监听器没有运行,测试却可能只检查 publishEvent 被调用过。

线程是第三个边界。某些抢占式超时机制在另一个线程执行测试体,或业务自己提交线程池任务,原测试线程的事务不会自动转移。工作线程写入可自行提交,测试线程回滚后数据仍在。真实 HTTP 随机端口测试也跨到服务线程,不能依赖测试客户端线程上的事务清理服务端提交。Spring 5.3 测试事务及抢占式超时说明

改进设计。 验证服务边界时不让测试外层替它开启事务;从容器代理进入,用真实内存资源做框架机制实验,在服务调用结束后从独立观察点查询。必须使用 TestContext 的场景,可以用 TestTransaction 明确结束当前测试事务,再验证已提交状态,或将观察放入 AfterTransaction 阶段。测试独立提交路径要单独清理,因为 REQUIRES_NEW 的结果不会随外层测试回滚。使用每例独立库名能减少残留串扰,但不能代替正确断言。

不要把 H2 的方便误写成 MySQL 已通过。代理与线程资源绑定属于本轮可验证机制,唯一键 NULL、驱动批重写、分片事务、InnoDB 锁范围属于另一层验证。Mock Mapper 只会按设定抛错,不会证明它实际复用同一数据库连接。测试覆盖度数字也不能替代具有反例的断言。

验证。 新实验已复现:外层教学事务包住错误 self 调用时,失败后零行;同一服务没有外层包装时,失败后仍残留一行。另一个实验在线程池写入后回滚父事务,断言工作线程数据仍存在。这里模拟了测试外层的资源语义,没有使用 Spring TestContext 的监听器,也没有实跑 JUnit 抢占式超时或 HTTP 服务器。后两项应保持“官方机制已核对、具体集成待执行”的状态。

练习与答案。 为防卡住,给所有事务测试加 @Test(timeout=...) 是否总安全?不总安全,某些框架会切换执行线程。应先确认超时实现,给等待操作本身设置有界期限,结束时释放屏障和线程池,并验证写入确实处于预期事务线程。

8. 本轮执行结果与下一步验收方式

本轮新增实验仅手工装配教学 Bean、内存 DataSource 和事务管理器,没有组件扫描 ERP 包,也未加载 Boot 或真实环境配置。复跑入口:

python3 spring-course/labs/pitfalls/run.py

脚本使用本地已有固定版本 JAR;缺少依赖会列出缺失制品并停止,不下载。需要 JDK 11 或更高,编译为 Java 8 字节码。临时编译目录自动清理;H2 数据只在当前 Java 进程内保留,进程结束释放。源文件见 TransactionChecks.java〔本地文件〕、SqlShapeChecks.java〔本地文件〕 与 run.py〔本地文件〕。

已通过八组 Spring 检查:同 URL 不同 DataSource 的独立资源、事务中切路由、捕获 REQUIRED 后 rollback-only、同方法局部 catch、self 与跨 Bean 的 REQUIRES_NEW、外层测试事务掩盖缺陷、提交后事件及独立写、线程池写入逃离父事务;数据库侧另有九组,共十七组。这里的“组”是带断言的场景组,不是十七个生产接口测试。

仍待执行的重点是生产风格 Mapper/事务管理器装配、真实连接池并发饥饿、嵌套路由恢复、分片物理资源、目标数据库锁等待及持久任务崩溃恢复。学习者的验收报告应按“入口经过哪个代理→选择哪个管理器→取得哪个资源→失败越过哪里→最后从哪里观察”写出证据链,才能判断一次修复是真的解决一致性问题,还是只让异常暂时不再出现。

原始文档 · spring-course/源码索引.md

源码索引与证据边界

本索引记录课程中高价值的阅读入口。行号对应本次整理时的本地文件,后续代码变化可能使行号偏移。链接存在及行号范围会由validate.py检查;这不替代人工核对语义。

设计与容器

源码 观察点 对应章节
ErpItemWebApplication〔本地文件〕 扫描、XML、Mapper、Enable注解、自动配置排除 02、04、17
AsyncTemplateConfig〔本地文件〕 构造器依赖、初始化、Bean工厂、有界队列 01、03、11
ScmDistributorItemThreadConfig〔本地文件〕 PostConstruct、static执行器、无界队列 03、11

请求、事务与数据

源码 观察点 对应章节
SlaveDataSourceAspect〔本地文件〕 切面次序、路由上下文 05、06
StockComponentImpl〔本地文件〕 多锁排序、锁开关、逐SKU处理 06、09
库存局部事务〔本地文件〕 TransactionTemplate边界 06
广告明细同步〔本地文件〕 页内聚合、原始游标、有界内存 09、10
广告Mapper〔本地文件〕 复合排序、NULL续页、批量upsert 09、10
SecurityConfig〔本地文件〕 HTTP安全链 07、08
DataScopeAspect〔本地文件〕 行级权限表达式及调用前提 05、08
GlobalExceptionHandler〔本地文件〕 异常响应、业务码、消息脱敏 07、08

上下文、缓存与稳定性

源码 观察点 对应章节
ProcessTraceInterceptor〔本地文件〕 header写MDC、清理需追全链路 07、12、15
下载任务线程〔本地文件〕 后台上下文重建与清理 12
LocalCache〔本地文件〕 expireAfterWrite与分步加载 13
CircuitBreakingConnectFilter〔本地文件〕 规则快照、URL匹配、执行前阻断 14
CustomSlowSqlFilter〔本地文件〕 文本/参数匹配、回调覆盖边界 14
NacosDbDegradeImpl〔本地文件〕 配置应用与错误处理 04、14

使用证据的规则

源码中的配置值证明当前文件写了什么,不证明线上实际加载了什么。看见某类没有关闭或清理方法,只说明此处没有,必须继续找资源所有者或外层清理。看到一个性能风险形态,也不代表已经发生事故;需要流量、调用路径和运行证据。

同样,项目里有Redis锁不证明所有路径受保护,MyBatis存在不证明每条查询有租户条件,Spring注解存在不证明调用经过代理。独立实验验证通用机制,真实应用仍需要独立集成测试。

正文官方参考主要包括Spring5.3 Core/Data/Web/Testing、Boot2.7、JDK并发API与MyBatis-Spring。链接用于进一步查阅,不以文档版本号代替项目实际依赖解析。

原始文档 · spring-course/补充阅读.md

Spring课程补充阅读:框架之前与之外的能力

本页新增衔接入口,保留原20章正文、README、实验与验证器。Spring可以组织对象、代理调用和事务资源,但不会替业务决定金额口径、可信租户来源或异常是否适合公开。掌握这些边界后,再看注解会更容易理解它究竟承担了哪一段责任。

学习困惑 对应补充
POM声明、装配与运行版本是什么关系 00 全目录技术栈证据与课程能力地图
单例共享对象、泛型、异常和中断为什么重要 01 Java语言集合泛型异常资源管理与前端迁移
Controller、Service、领域对象和Mapper如何分责 02 Java工程分层领域建模金额时间编码规范
权限切面需要哪些前提,秘密与迁移怎样管理 03 数据库访问安全权限注入凭据与迁移规范
如何评审异常处理、缓存、线程池和HTTP工具 04 项目反例与安全编码评审

完整入口:后端基础README、审阅与知识缺口。进一步学习:分布式README、高并发README、运维README。后三个专题由并行任务交付,本页只提供约定入口,不替它们宣布验收完成。

先用普通Java测试领域规则,再用小型容器验证代理,最后在隔离目标环境验证数据和权限;不要让一个Mock测试承担它无法证明的数据库正确性。新增章节的故障推演均明确前提,没有把业务服务实验写成已执行。

原始文档 · spring-course/验证记录.md

Spring课程验证记录

整理日期:2026-11-10;交付复核:2026-11-11。验证只针对教程产物和独立实验,未启动业务项目、连接业务数据库或调用业务接口。

已执行的机制验证

独立实验使用Zulu JDK17.0.15、Spring Context/JDBC5.3.39、H2 2.2.224、JUnit4.13.2,Maven编译release8。Spring版本用于历史机制学习;H2运行要求与编译目标不同,因此使用JDK17执行。

执行命令,在labs/core目录:

mvn -B -s settings.xml -Dmaven.repo.local=/tmp/spring-course-m2 test

首次执行结果:11项测试,0失败,0错误,0跳过,BUILD SUCCESS。包括IoC3项、事务代理4项、执行器与ThreadLocal4项。交付前复核结果另列于本记录末尾。

文档验证范围

validate.py检查00—19各一章、Markdown标题和代码围栏、本地链接存在、源码行号在文件范围内、Python语法、HTML节数、内部锚点、代码块保留及无外部运行资源。链接和行号正确不等于代码含义自动正确,关键案例另外结合源码人工阅读。

阅读器由Python Markdown3.7生成,所有课程正文嵌入HTML。官方参考链接需要联网,源码链接依赖本地项目目录继续存在。浏览器全文搜索可跨全部正文;章节筛选只筛侧栏,不隐藏正文。

未执行或不能据此证明

  • 没有运行ERP应用的集成测试、业务SQL、业务调度与通知。
  • 没有连接项目MySQL、Redis、MongoDB、Nacos、RPC或对象存储。
  • H2实验不证明MySQL索引、锁、执行计划、主从与分布式事务行为。
  • JDK线程池实验不证明项目TTL/Trace包装器全部行为或生产容量。
  • 第18章可靠导出是教学设计,DDL和完整状态机尚未实现为可部署服务。
  • 章节中的容量数字是教学假设,没有以项目真实流量或生产规模测量冒充结果。
  • 源码审查指出需要核实的风险形态,不等同完整安全审计或已经发生事故的判断。

只有明确写在实验目录且纳入测试的代码被计入11项通过结果;正文中的扩展练习、设计片段和故障演练不计入。

交付复核结果

  • Maven 3.9.16重新执行核心实验:11项通过,0失败、0错误、0跳过;Surefire报告与控制台结果一致。
  • 文档共20章、24份Markdown,约5.5万汉字;156个本地链接、87处源码行引用通过存在性与行范围检查。
  • 离线HTML包含24个文档节和53个围栏代码块;内部锚点检查无缺失,未引用外部运行脚本或样式。
  • 阅读器JavaScript通过Node语法检查;Chrome实测章节筛选、明暗切换、字号调整与章节跳转。窄屏检查发现长方法名链接可能撑宽页面,已在生成器增加自动换行处理;修复后390px移动视口与页面宽度均为390px,无页面级横向溢出,内部锚点缺失数为0。
  • 第13章内存模拟程序实际执行通过:提交后回调丢失、重复交付幂等、旧值回填拒绝三组断言。它不计入11项JUnit测试,也不证明数据库持久性。
  • 生成Markdown的私钥标记及明显长凭据赋值模式扫描均未命中;这是有限静态检查,不等同完整敏感数据审计。

阅读版已根据最终Markdown重新生成。此记录不声称第18章完整导出系统、业务集成或生产规模压测已经执行。

原始文档 · spring-course/labs/core/README.md

Spring核心机制实验室

这是独立教学Maven工程,只创建本地Spring容器、H2内存数据库和短生命周期线程池。它不读取业务项目配置,不连接ERP的MySQL、Redis、MongoDB、配置中心或RPC,也不启动业务应用。测试数据均为虚构。

1. 环境与运行

本次验证:Zulu JDK17.0.15、Maven、Spring Context/JDBC5.3.39、H2 2.2.224、JUnit4.13.2。源码编译release8,仅表示语言/API编译目标;H2等依赖的运行要求使本实验选择JDK17,不能推断可直接用Java8运行全部依赖。

cd /Users/try/work/admin/spring-course/labs/core
mvn -B -s settings.xml -Dmaven.repo.local=/tmp/spring-course-m2 test

如果mvn未在PATH,本机可使用/Users/try/.local/bin/mvn。首次运行需从Maven Central下载依赖;settings.xml固定镜像到Central,不包含业务账号。Maven输出及H2不会创建持久业务库,编译产物在target,下载缓存位于指定临时目录。

预期:Tests run: 11, Failures: 0, Errors: 0, Skipped: 0。重新运行结果以当次输出为准,记录见验证记录。

2. IoC:3项测试

IocTest.java〔本地文件〕先手工装配Checkout,再引入Spring验证Primary与Qualifier选择、同名singleton复用、prototype Provider返回不同对象。生命周期列表验证构造、初始化前处理、InitializingBean、初始化后处理和关闭销毁的可观察顺序。

先读代码并预测结果,再运行;然后试着移除Qualifier,解释默认选择如何改变。修改实验副本时保留原始通过版本,避免把你新引入的变化当成教材错误。

该测试不证明所有Bean都有完全相同顺序,未覆盖循环依赖、FactoryBean或Boot自动配置。它给你一个小而清晰的容器观察窗口。

3. 事务与代理:4项测试

TransactionProxyTest.java〔本地文件〕使用实际事务管理器与随机命名H2内存库,覆盖:

  1. 容器返回代理,外部@Transactional调用有事务,自调用绕过代理没有该事务。
  2. 代理调用抛运行时异常后插入回滚;自调用路径的JDBC自动提交插入仍存在。
  3. REQUIRES_NEW审计提交,即使外层事务随后回滚仍保留。
  4. checked exception默认不回滚,显式rollbackFor则回滚。

要观察数据库结果,而不是只看异常被catch。实验中查询使用小表,与业务库存表无关。没有验证MySQL的gap lock、next-key lock、主从延迟或跨数据库事务。

4. 线程池与上下文:4项测试

ExecutorTest.java〔本地文件〕通过CountDownLatch固定任务时序,验证:

  1. core1/max4配无界队列,worker阻塞时后续10任务入队,池仍为1。
  2. 有界队列满时AbortPolicy明确拒绝。
  3. DiscardPolicy静默丢弃submit任务,返回Future不完成,限时get超时,随后取消清理。
  4. 单线程池复用worker时ThreadLocal残留,finally remove之后后续任务读取为空。

这些测试没有用随机压力碰运气。等待和关闭均有上界,避免失败时挂住进程。它们证明JDK机制,不测本机最大QPS,也不覆盖项目TTL/Trace包装器所有行为。

5. 建议的扩展练习(未交付为已运行测试)

  • 用两个不同Bean比较self调用与跨Bean事务,并加入REQUIRED rollback-only场景。
  • 添加MVC测试,验证JSON业务码与HTTP状态码不是同一个字段。
  • 添加提交后事件测试,分别覆盖提交、回滚和无事务发布。
  • 在独立目标MySQL中验证条件扣库存、死锁重试和租户唯一键。
  • 按第18章实现文件分块与epoch,在每个持久化边界终止后恢复。

扩展练习需要相应依赖与环境,当前11项结果不包含这些项目。不要使用业务配置来“省略准备工作”。

6. 从失败到定位

依赖下载失败先看网络与Maven Central访问,不要换成业务私服凭据;编译失败先确认JDK17与mvn实际使用的Java;断言失败先看target/surefire-reports对应测试,而不是跳过测试。线程测试在极端资源不足时可能超时,需记录环境并确认原因,不能简单无限增大等待。

本工程不修改业务POM,不要求整个ERP能在当前机器启动。学习重点是将“注解应该生效”的猜测转为“调用路径与持久结果可观察”的证据。

学习阶段 04

分布式系统

RPC、消息、幂等、租约与一致性

原始文档 · distributed-course/README.md

ERP 分布式后端:从故障窗口到可恢复协议

新增开发陷阱深化:沿实际消息代码追踪提前ACK、后台吞异常、去重相等性、入队中断窗口、顺序扇出与毒消息恢复。

面向前端基础扎实、正在转向 Java ERP 后端的读者。阅读顺序是先识别不确定性,再设计契约和持久化边界,最后做故障验收。本文档只研究代码与协议模型,不连接任何业务服务。

章节

  1. 00 分布式基础、一致性与故障模型
  2. 01 RPC 与 Dubbo:契约、超时、重试
  3. 02 RocketMQ:投递、顺序消费与死信
  4. 03 幂等、Outbox、Inbox 与状态机
  5. 04 分布式锁、租约、fencing 与调度
  6. 05 分布式事务、Saga、TCC 与对账
  7. 06 CDC、数据同步与分片迁移
  8. 07 订单库存消息综合实战与故障验收
  9. 无外部服务的 Python 故障模型实验

阅读约定

源码链接相对本目录指向兄弟项目,使用 相对路径#L行号,以本次读取的工作树为依据;后续源码变化可能导致行号漂移。明确标作“教学设计”的 SQL、Java 伪代码和时序不代表项目已采用。所有风险都需要所述条件才能触发,静态阅读不证明线上发生过事故。没有审计部署配置、依赖最终解析版本或远端服务。

RocketMQ 原生客户端、云厂商 ONS 和项目封装存在不同契约。官方 4.x 与 5.x 文档用于说明对应代际的机制,不能把新版默认值套给仓库。实验仅是协议模型,不是 Broker、Redis、Dubbo、数据库隔离级别或网络故障验证。

先修与衔接

线上阅读站仅打包教程与实验,不附业务源码。相对源码链接仅供本地对照,不能通过复制兄弟业务仓库来补齐线上链接。HTML 阅读器由主代理统一生成。

完成标准:能指出每个确认动作究竟确认什么;能在任一持久化边界前后插入崩溃并说明恢复路径;能用业务不变量判断恢复是否正确,而不是只看接口返回码。

原始文档 · distributed-course/00-分布式基础与一致性.md

00 分布式基础:一致性承诺从故障模型开始

返回目录 · 下一章

1. 从一次页面提交转向多个独立事实

前端调用下单接口时,通常用 loading、成功和失败描述界面。但后端至少存在订单已创建、库存已预占、消息已接收、页面已收到通知四个事实。它们分别发生在不同进程甚至不同存储中。页面请求超时,只说明浏览器未在等待期限内得到响应,不能推出订单不存在。把这两件事混为一谈,再让用户重新点击,是重复订单最常见的设计来源之一。

单机程序可以依赖调用栈传播异常,跨进程调用却会丢失这种确定性:服务执行完后回复可能丢失;客户端退出后服务仍可能运行;网络只中断一侧时,两端对连接状态的判断还可能不同。因此后端契约应允许“处理中、结果待查”,而不是强迫每次响应都代表确定的成功或失败。请求标识、查询接口、持久化状态共同组成一次操作,HTTP 或 RPC 只是传递它的渠道。

先定义业务不变量。比如同一商家、同一外部订单最多创建一条业务订单;任何时刻可售库存不能因为并发预占而为负;已取消订单不能被迟到的预占回执重新激活。它们比“系统强一致”具体得多,也能直接写成测试断言。通知允许延迟,不代表库存允许超卖;同一产品可以对不同对象提供不同的一致性承诺。

2. 故障模型不是错误码大全

本课程假设进程可能崩溃并重启,消息可能延迟、重复、乱序或暂时丢失,网络可能分区,线程可能长时间暂停,持久化存储在明确提交后可以恢复。这里没有假设节点恶意伪造协议,也没有假设任意数量磁盘同时永久损坏。安全审计和备份恢复要另行覆盖这些边界,不能因为模型测试通过就宣布系统抵御一切故障。

需要特别区分 crash-stop 与 crash-recovery:前者进程停止后不再参与,后者重启后会带着磁盘状态重新参与。ERP 消费者通常属于后者,恢复时必须知道哪些消息已经影响库存。只存在 JVM Set 中的“已处理标记”会随进程消失;磁盘上的标记若早于库存提交,又可能导致恢复时错误跳过。

超时是一种怀疑机制,不是死亡证明。网络慢和节点死在观察窗口内可能完全一样。时钟也不能随意拿来裁判因果:两台机器的墙上时间存在偏差,校时可能回拨。持续时间宜使用单调时钟;跨节点先后关系宜使用业务版本、日志位置或由权威节点分配的序号。给消息加一个本地毫秒时间戳,并不能解决两台生产者的顺序争议。

3. CAP 应当落到具体读写对象

CAP 中的一致性通常指线性一致性:每次操作仿佛在调用开始与返回之间某个瞬间生效,且遵守真实时间先后;可用性要求非故障节点收到的请求最终得到符合对象语义的响应;分区意味着节点之间的信息可能无法送达。分区期间,两侧无法既独立持续响应,又保证共同维护同一份线性一致的可变状态。这不是任意时刻随意“三选二”的产品标签。定义和不可能性证明可查 Gilbert 与 Lynch 的原始论文。

用库存 1 件举例:分区两侧都不知道对方是否卖出。如果双方都承诺销售成功,就可能卖出两件;若一侧拒绝销售或等待权威侧恢复,则牺牲该侧写入可用性。业务可以事先把库存额度分给两侧,让每侧只消费自己的额度,但那改变了对象和协议,不能视为突破 CAP。额度转移本身仍需要可靠协调。

最终一致性则要求在没有新更新、通信及修复机制继续推进的条件下,副本最终收敛。它没有自动提供“最多延迟两秒”的时间上界。承诺两秒需要容量、重试、积压、依赖恢复时间和运维保障共同支撑。读己之写、单调读、因果一致性又是不同性质:页面提交后立即刷新能看到自己的修改,不代表别的商家读者看到的也是最新值。

4. 真实源码:SUCCESS 到底确认了哪一层

读取 RocketMqOrderedTradeQueueMessageListener.java〔本地文件〕,第 57—66 行先解析消息,将对象放入 tradeMessageUniqueBlockingQueue,随后返回 ConsumeOrderlyStatus.SUCCESS。第 91—103 行另有后台线程取出批次并并发提交任务,第 124 行才调用 messageSync。这是入口确认与业务执行分离的事实。

Broker            监听器             进程内队列           业务同步
  |---消息---------->|                    |                  |
  |                 |---put------------->|                  |
  |<--SUCCESS-------|                    |                  |
  |                 |       [故障点 A:进程退出]             |
  |                 |                    |---取出并处理----->|

此处不能直接写“系统必然丢消息”。准确的风险是:若 SUCCESS 已被客户端推进为消费确认,业务尚未形成可恢复记录,且进程内待处理项没有其他持久化补偿来源,那么在故障点 A 崩溃,已确认消息可能无法仅靠这条消费链恢复。是否实际丢失,要继续核验客户端确认行为、队列实现、平台重拉和补偿任务。后续章节会读取队列实现,本章先学会把结论限制在证据以内。

这也解释了为什么“监听器处理 2 毫秒”未必代表系统很快。它可能只测到了入队,而真正业务积压已经持续十分钟。观测必须分别记录接收、持久化接管、业务完成和通知送达时间,不能用一个 consume_time 包办四种语义。

5. 安全性与活性必须分开验收

安全性描述坏事永不发生,例如库存不重复扣减;活性描述好事最终发生,例如依赖恢复后所有有效订单最终进入终态。一个永远拒绝订单的服务可能没有超卖,但没有业务价值。一个不停重试的系统看似努力推进,却可能因毒消息堵塞顺序队列而使其他订单永远无法处理。

教学设计可以写成两个判断:每次状态变化后检查 available >= 0;当外部依赖恢复、重试次数预算允许、调度公平时,检查所有待处理任务最终完成或进入有责任人的人工队列。这里“公平”意味着任务不能永远被新来的高优先级请求挤出。死信并非完成业务,只是把自动恢复责任移交给另一个明确流程。

性能也要放进模型。平均每秒到达 1000 条、平均完成 800 条,积压每秒增长 200 条;增加重试可能进一步放大到达量。扩大内存队列只延迟崩溃,并未增加服务能力。真正的稳定方案需要限制进入速率、划分租户配额、控制并行度并保证失败后可以从持久化任务继续。

安全反例是直接信任消息中的 userId 并据此切换租户。消息来自内部网络,不等于字段可信:错误发布者或越权重放都可能把订单写到其他租户。入口要验证身份与租户绑定,幂等键、查询键、日志访问权限也应包含租户边界。业务不变量必须在授权范围内成立。

讨论一致性时还应明确观察对象。数据库行已经提交,不代表搜索索引已更新;索引已更新,不代表浏览器缓存已失效。排查“订单状态不一致”时,先给每个副本标注所有者、版本和最后应用位置,再确认差异属于预期延迟、停滞还是错误回盖。没有这张因果图,团队很容易反复清缓存,却从未修复真正停止推进的消费任务。

6. 故障推演与练习答案

练习一: 库存扣减成功后服务端进程退出,客户端只收到超时。能否立即重新执行扣减?

答案: 不能根据超时推断失败。应使用相同业务请求键重试,并由服务端原子查重返回旧结果;或查询该请求状态。如果只提供随机新请求键,服务端无法判断这是恢复还是新交易。对无法幂等的外部平台动作,应先查业务流水,进入待确认状态后再决定下一步。

练习二: 网络分区时,两个机房都返回“库存只剩 1 件”,读接口是否已经证明系统可安全接单?

答案: 没有。展示旧值和承诺扣减是两个对象语义。可以允许商品页显示带更新时间的近似库存,同时只让权威库存服务决定预占。若必须双机房独立销售,需要事先分配可消费额度,并验收额度总和守恒。

练习三: 上面的异步消费模式应该如何最小化故障窗口?

答案: 在返回成功前把完整任务和稳定标识持久化,再由后台工作者执行;或者让监听线程在业务事务提交后才确认。前者需要任务扫描、幂等、租约和失败转人工;后者需要严格控制处理时长与背压。二者都不能把一个内存队列当成数据库。

官方与原始资料

原始文档 · distributed-course/01-RPC与Dubbo服务治理.md

01 RPC 与 Dubbo:让远程契约承受超时和重试

返回目录 · 上一章 · 下一章

1. 类型一样,不代表调用语义一样

前端的 TypeScript interface 能约束调用形状,Java 的 RPC 接口也能帮助编译器检查参数。但编译通过只说明当前代码理解这个类型,不能证明远端部署的是相同版本,更不能证明一次调用只执行一次。RPC 会跨越序列化、网络、服务发现、路由、线程池和业务事务,每层都有独立失败方式。

真实契约可从 StockDubboService.java〔本地文件〕 入手:第 25 行是退款入库,第 30 行是销售出库,第 42 行是订单预占,第 58 行是修复预占数据。同一个接口包含查询、写入、修复动作,不能给它们统一套用“失败自动重试”。查询旧值一般不产生重复副作用,重复出库却可能破坏库存守恒;修复命令还可能范围很大,需要独立权限与限速。

接口设计至少要回答:请求键是谁生成的、同键不同参数如何处理、超时后在哪里查询、业务拒绝如何表达、批次部分成功如何返回。教学接口可以采用 reserve(tenantId, requestId, orderId, skuId, qty),响应携带业务状态、预占流水号和当前版本。不要只返回 boolean,因为 false 无法区分余额不足、权限不足、依赖不可用和结果未知。

2. 沿一次调用拆开服务治理

调用方代理 -> 服务目录快照 -> 路由筛选 -> 负载均衡 -> 网络请求
                                                   |
提供方:鉴权 -> 限流 -> 工作线程 -> 参数验证 -> 本地事务 -> 响应

注册中心回答“候选实例在哪里”,不负责证明库存事务成功。缓存目录允许调用方在注册中心短暂不可用时继续访问已有实例,但失效节点也可能暂时留在候选集合。负载均衡回答“这次选谁”,不是幂等保证。切换到另一个健康实例重试时,必须仍能找到同一条业务请求记录,因此去重状态不能只保存在单实例内存。

版本与分组是路由维度,不等于接口语义兼容。新增可选字段通常比修改原字段含义更容易兼容,但仍要验证序列化器、默认值和旧消费者处理未知枚举的行为。不要把新增枚举直接当作旧分支的默认成功。对金额、数量、时间要明确单位、精度和时区,否则“反序列化成功”可能掩盖实际业务错误。

3. 真实配置中的重试边界

BaseDubboConfig.java〔本地文件〕 第 26—41 行中,部分重载传入 3,并通过 ref.setRetries(retrty < 0 ? 3 : retrty) 设置消费端引用。第 49—52 行把服务配置中的超时赋给引用。第 67—72 行的提供端构造方法还把小于 3 的 retry 值变成 3;另一个构造方法则仅对 null 设置默认值。不同入口并不完全等价。

这说明配置封装值得逐个追踪,不能只看调用者写了 0 就认为实际关闭重试。不过这些是构造代码,不证明某条线上调用使用了它,也不证明提供端参数最终覆盖了消费端或方法级配置。完整核验需要找到实际 Bean 构建路径、方法级覆盖、集群策略和生效 URL;本教材没有读取部署配置。

Dubbo 2.7 的 Failover 文档把 retries 定义为首次调用以外的重试次数,并描述 Failfast 等不同策略。因此在适用 Failover 且失败可重试的条件下,retries=3 最多可能产生四次尝试,业务异常等分支不应直接套同一公式。参考 Dubbo 官方容错策略。

教学反例是网关重试 2 次、订单服务重试 2 次、库存调用又重试 2 次:若三个层级均执行首次加两次重试,最坏可放大为 27 次底层调用。真实数量受截止时间和错误分类限制,但乘法揭示了重试风暴的来源。应选定负责重试的层,其他层传播错误和剩余预算。

4. 超时预算要包含排队与恢复

假设页面动作总预算为 1500 毫秒,鉴权与本地操作预留 250 毫秒,返回和网络波动预留 150 毫秒,剩余 1100 毫秒才能用于依赖调用。库存单次预算 400 毫秒,即便考虑第二次尝试,也要扣除第一次实际耗时和退避时间。不能让每一层都重新获得完整的 1500 毫秒。

// 教学伪代码:具体 Deadline API 需要自行实现
long remaining = deadline.remainingMillis();
if (remaining <= reserveForReply) return pending(requestId);
try {
    return inventory.reserve(command, Math.min(400, remaining - reserveForReply));
} catch (TransportTimeout ex) {
    // 同一个 requestId,随后查询或在预算内受控重试
    return pending(requestId);
}

这个 pending 只有在请求已经形成可查询记录,或明确表示“待确认、不得当成功”时才有意义。不能把未落库的请求伪装为已可靠受理。更不能把 Future.cancel、线程中断或客户端超时当成远端事务已回滚。取消通常是协作请求;是否停止执行,必须有服务端状态与协议证据。

队列等待也消耗预算。线程池工作线程都在等慢数据库时,新请求即使网络连接很快,也会在服务端积压。只增加超时会让占用持续更久。应限制并发数和排队容量,在进入昂贵操作前检查剩余预算,区分连接失败、排队超时、业务处理慢和响应丢失。

5. 限流、熔断、隔离各管一件事

限流控制单位时间或在途请求数量,保护提供方不被压垮;熔断在依赖持续故障时暂时停止尝试,避免把资源浪费在大概率失败的调用上;隔离避免一个依赖占满所有线程、连接或租户额度。三个机制相互补充,不能因为加了熔断就把线程池设为无限队列。

性能反例是将慢报表与实时库存共用同一无界执行池。报表突发使库存请求排队,客户端超时重试,又向同一执行池注入更多工作。教学修正是为关键写链路设置较小、有界的在途预算,报表走独立配额;用随机退避打散恢复时的同时重试,并保留少量探测请求判断依赖是否恢复。

安全上,传入的 tenantId 和 User 对象不是授权事实。调用方只能代表被授予的租户,提供方应从可信身份获取授权范围并校验请求。RPC 附件中的 traceId 适合串联日志,不适合单独证明身份。不要把完整订单、买家信息和鉴权材料作为超时日志内容;按需记录请求键、方法、租户摘要、耗时分段和错误分类即可。

如何证明某次慢调用发生在哪里

一次远程调用总耗时高,不能直接归因于网络。教学观测应记录调用方开始与结束、获得连接的等待、提供方收到请求、进入业务方法、数据库事务结束与写回响应等阶段。跨机器绝对时间存在偏差,优先比较各进程自己的持续时间,并借助请求标识关联。只有提供方处理很短而客户端等待很长时,才进一步检查传输、排队和响应回程;不能看到 timeout 就先扩大线程池。

如果一次调用并行查询五个依赖,整体响应常受最慢分支影响。每个依赖平均很快,也可能因为尾部延迟叠加使总请求频繁超时。需要观察分位数与在途数量,并为可选信息提供明确降级:商品详情可以暂缺推荐信息,库存写入却不能因超时伪造成功。降级必须遵守业务不变量,而非统一返回空对象。

排错时还要把协议成功与业务成功分开。RPC 传输正常返回一个带业务错误码的响应,在基础设施监控里可能算成功,但订单仍可能失败;反过来,客户端记录超时,业务却已提交。将两类指标分开并用请求键联查,才能避免以传输成功率掩盖业务异常,或把正常待确认流程全部误报为失败。

6. 故障推演:已扣库存,但回复丢失

时间线是:调用 A 到达库存服务,预占事务提交;响应回程超时;订单服务在 B 实例重试。若去重只靠 A 的本地缓存,B 无法知道已经执行。正确设计是把请求记录与预占流水放在同一本地事务,唯一键包含租户和操作类型,B 查到已提交结果便原样返回。

还要防止同键不同内容。客户端把数量从 2 改成 3 却复用旧 requestId,服务端应比较规范化参数摘要并返回冲突,不能悄悄返回原结果导致界面误解。若第一次仍在执行,第二次返回处理中或等待同一记录,不能另外扣一次。去重过期时间必须覆盖客户端重试和人工重放周期,否则旧请求会在过期后再次生效。

7. 练习与答案

练习一: 将库存写方法设成 retries=0,是否就保证最多扣一次?

答案: 不保证。浏览器、网关、订单任务、人工补偿均可能重新发送相同业务请求。关闭某层重试只是减少尝试次数,正确性仍来自唯一业务键、原子事务和结果复用。

练习二: 读接口失败可以无限重试吗?

答案: 也不可以。读操作可能无写副作用,但会占用资源、放大故障,还可能读到不同版本。必须限定总截止时间、重试预算和最大并发,必要时返回带新鲜度说明的缓存结果。

练习三: 新版服务增加 RESERVED_PENDING 枚举后如何灰度?

答案: 先让消费者容忍并正确展示待确认状态,再发布生产该状态的提供方;或通过协议版本隔离路由。回滚也要考虑已持久化的新状态,不能只回滚 Jar。验收应包含新旧消费者交叉调用和未知字段/枚举用例。

官方参考

原始文档 · distributed-course/02-RocketMQ投递顺序与死信.md

02 RocketMQ:投递成功、消费成功和业务成功

返回目录 · 上一章 · 下一章

1. 消息系统提供的是边界清晰的承诺

异步消息把请求和执行解耦:订单服务不必等库存消费者执行完成,就能继续处理其他工作。但解耦也拆开了成功的含义。生产者收到发送结果、Broker 保存消息、消费者收到消息、库存事务提交、消费者确认、浏览器收到通知,是六个不同事件。任意两个事件之间都可能崩溃。

消息语义常分为至多一次、至少一次和恰好一次。至多一次容忍丢失而避免某些重复;至少一次依靠重投恢复,却要求消费者处理重复;恰好一次必须说明范围。某个存储或事务通道内部的恰好一次,不会自动涵盖外部 HTTP、短信、打印机和另一套数据库。ERP 应把“同一业务效果最多一次”落实在业务流水上,而不是只相信消息 ID。

发送超时也不是未发送证明。Broker 可能已经保存消息,只是回复丢失。生产者重发时应保持稳定 eventId,消费者以该标识识别同一事件;Broker 为不同物理发送生成的标识,不能替代业务身份。发送端还应区分可重试网络错误与不可重试的权限、消息格式或大小错误。

2. 源码阅读一:路由失败被日志吸收

MessagePushConsumerListener.java〔本地文件〕 第 32—43 行遍历批次,第 36 行解析 JSON,第 38 行调用 SSE 路由。路由抛出的 Exception 在第 39—40 行被记录,随后方法仍返回 SUCCESS。注意解析在 try 之外,因此不能写成“所有异常都吞掉”:解析异常与路由异常走的是不同路径。

对瞬时页面提醒,容忍通知失败可能是有意取舍:用户刷新后从数据库读取最终结果即可。但如果产品把这条 SSE 提示当成唯一订单确认,则路由异常被吸收会造成用户未获知结果的风险。触发条件是通知失败且没有补查或持久化通知机制;当前源码没有证明线上存在通知丢失事故,也没有证明页面无法补查。

这里还有安全与性能上的教学点:第 35 行记录完整 msgBody。是否含个人信息取决于实际 DTO 内容,不能直接断言泄漏。但若消息内携带收件信息或高频大字段,完整日志既增加数据暴露面,也增加序列化、磁盘和采集费用。日志应优先记录 eventId、消息类型、目标数量和失败摘要。

3. 源码阅读二:内存去重不等于可靠消费

RocketMqOrderedTradeQueueMessageListener.java〔本地文件〕 的 rocketConsume 入队后返回成功,而业务调用在后台执行。继续读取 UniqueBlockingQueue.java〔本地文件〕:内部是 ConcurrentHashMap 和 LinkedBlockingQueue;第 34—35 行先登记再放入队列;第 52 行在批次取出时删除去重项。该类没有持久化机制。

因此它主要合并等待队列中的重复项,去重相等性还取决于元素的 equals/hashCode。取出后同一对象可能再次进入,进程重启后标记也消失。它不是“业务成功账本”。若 put 在登记后被中断而没有清理 map,则还需分析是否出现有标记却无队列项的情况;这里指出条件窗口,不推定实际发生过线程中断。

另一方面,有界队列可以形成背压:满时 put 阻塞,监听器不会无止境接收。但阻塞时间必须与客户端消费超时、关闭流程和线程池容量共同评估。把容量无限加大只会把过载变成内存压力。业务在第 98—103 行并发执行,也意味着入口的顺序接口本身不能证明业务完成顺序。

4. 顺序需要明确到某个业务键

订单 O 的创建、付款、取消有因果关系;不同订单通常无需全局排队。教学上可使用 (tenantId, orderId) 作为顺序分组键,让同一订单的事件进入同一顺序通道。只使用 orderId 而忽略租户,可能使不同商家的同号订单互相阻塞;只使用 tenantId,又会让大商家的一条慢事件拖住全部订单。

RocketMQ 4.x 顺序消费围绕队列与监听器契约展开,5.x FIFO 文档强调消息组内的生产与消费顺序。两代 API 与云 ONS 行为不能混用;这里只讨论机制,部署版本必须单独核验。参考 4.x PushConsumer 和 5.x 顺序消息。

同一订单的发送顺序:Created(v1) -> Reserved(v2) -> Cancelled(v3)
监听器依次收到:     v1 -> v2 -> v3
转交异步线程后:     v3 提交 -> v1 提交 -> v2 提交  (可能)
正确保护:同键串行执行,或业务版本/合法状态转移拒绝旧事件覆盖

版本检查也不是万能的。完整快照可以在收到 v3 后忽略 v2;增量事件如“加 2”不能随便丢弃 v2,否则会丢业务效果。必须明确事件是状态快照、不可交换命令还是可交换增量,并为版本缺口选择等待、补拉或重新构建。

5. 重试、毒消息与死信是恢复协议

暂时故障可以退避重试,例如数据库短时不可用;永久错误如字段无法解析、租户不被授权,需要隔离和人工或程序化修正。把所有异常都无限重试会让顺序队列被毒消息卡住;把所有异常都返回成功则会隐藏未完成工作。两者都把恢复责任丢给了运气。

教学消费流程是先验证消息边界,再在本地事务中完成 Inbox 与业务变更,提交后返回成功。事务暂时失败走相应客户端的重试返回值;确定无效的消息先写入可审计隔离记录,再按策略确认。隔离记录至少包含事件标识、租户、失败类型、原始内容的受控引用和可重放版本,不能把敏感负载无期限裸存。

死信表示自动重试预算已耗尽,并不表示业务被正确取消。监控需要统计死信数量、最老年龄、租户分布和处理责任人。重放必须沿用业务 eventId,修正数据必须记录修正原因和操作者;如果人为换新 ID 来绕过去重,就可能再次扣库存。原生普通消息、顺序消息和云服务的重试次数与死信策略不同,教材不假定统一默认值。

消费组扩容为何不能只看机器数

同一消费组中的实例通常分担工作,不同组则可独立处理同一业务事件,例如库存投影与审计各自消费。扩容前要核验订阅关系是否一致、顺序分区是否足够,以及热点业务键是否集中在少数分区。一条必须串行的订单链,不会因为增加十台机器就获得十倍吞吐;把它拆散并行可能提升数字,却破坏业务因果。

重平衡时,分区归属会变化,旧实例上的在途任务和新实例接管可能形成重复处理窗口。具体锁定与交接行为取决于客户端版本,业务仍需以幂等和状态条件兜底。优雅关闭应先停止接收,等待已接管任务完成或可靠留存,再释放资源;不能仅关闭线程池并假定已返回成功的任务会由 Broker 自动找回。

积压评估应同时看条数和年龄。十万条短事件与一百条每次等待外部平台一分钟的事件,需要完全不同的恢复预算。统计失败原因与业务键分布,能识别是普遍容量不足还是少数毒消息拖住顺序通道。只提高重试频率会使依赖更忙,反而延长恢复;隔离永久错误、限制重试并恢复持久化任务,才使积压真正下降。

6. 故障推演:批次中间失败怎么办

设一个批次有 A、B、C。A 已提交,B 失败,C 未执行。如果整个批次被重投,A 会再来一次;如果直接返回全部成功,B、C 可能无法恢复。正确答案取决于客户端提供的确认粒度,但无论哪种粒度,业务都要允许 A 重复到达而不重复生效。不要把“正常情况下批次只有一条”当成接口永久保证。

在本课程实验中,Broker 被简化为可重复交付的列表。消费事务提交后、确认前注入崩溃,重启时再次消费同一 eventId,预期业务扣减不变。这个实验验证的是应用协议的幂等假设,不能验证真实 Broker 的落盘、复制、队列锁或重试调度。

7. 练习与答案

练习一: 顺序消费者收到取消事件后启动 CompletableFuture,再立即返回 SUCCESS,有什么问题?

答案: 返回只证明任务被提交,不能证明取消完成。线程调度可能让后续事件先提交,崩溃还可能丢掉未持久化任务。应在确认前持久化接管,且同一业务键串行或通过状态机保护。

练习二: SSE 推送失败必须让订单 MQ 永久重试吗?

答案: 不一定。订单业务与页面提醒应分别定义可靠性。如果订单已完成,提醒可由独立通知任务重试,页面通过查询恢复;不要让离线浏览器阻塞核心订单流。若通知本身是合规必达,则需持久化送达状态与独立验收。

练习三: 重放死信时生成新 eventId 是否更干净?

答案: 对同一业务事件应保留身份,让幂等账本识别它。确实需要产生新业务修正时,应创建有独立语义的新事件,关联原事件并记录授权,而不是无声绕过去重。

官方参考

原始文档 · distributed-course/03-幂等Outbox与Inbox.md

03 幂等、Outbox 与 Inbox:把恢复责任写入数据库

图解 · 可横向查看
Outbox / Inbox:两次本地提交,不是一笔全局事务时间从上到下;虚线箭头表示返回。发送后、标记SENT前崩溃会重发;消费提交后、ACK前崩溃会重投。;消费者靠同一事务内的去重记录和业务变化收敛;Broker确认含义依产品契约核验。 Outbox / Inbox:两次本地提交,不是一笔全局事务业务服务订单数据库投递器Broker消费者业务+Outbox写入事务提交成功读取待发事件发送固定eventId收到发送确认投递,可重复Inbox+业务提交提交后ACK发送后、标记SENT前崩溃会重发;消费提交后、ACK前崩溃会重投。消费者靠同一事务内的去重记录和业务变化收敛;Broker确认含义依产品契约核验。
Outbox与Inbox保护两笔本地事务

图示为教学简化,需结合下文的适用条件、故障窗口和项目证据阅读。

返回目录 · 上一章 · 下一章

1. 幂等是业务身份与原子边界的组合

数学上,幂等表示重复应用某个操作不再改变结果;工程上还要约定重复请求拿到什么响应。将库存设置为 8 看起来幂等,但如果这是旧快照,重复写仍可能覆盖更新的 5。把“减 2”改成“设为 8”并不能自动修复分布式协议,它只是换了一种错误。幂等必须同时考虑请求身份、版本和合法状态。

为订单预占定义业务键 (tenantId, orderId, action, revision)。tenantId 隔离商家,action 区分预占与释放,revision 区分订单修改后的新命令。eventId 标识一次已经形成的业务事件,requestId 标识一次外部操作,traceId 标识观测链路,它们不应混为一谈。重试沿用业务身份,新的合法业务操作使用新身份。

真实 UniqueBlockingQueue.java〔本地文件〕 通过 putIfAbsent 避免等待期间重复入队,在第 52 行批次取出时删除标记。这是吞吐优化,不是持久化幂等:业务还没成功,标记已经消失。把这个类命名中的 Unique 理解为“永远只执行一次”,就是把局部性质扩大成系统承诺。

2. 两次写之间总有崩溃窗口

教学反例一是先创建订单,再发 MQ。数据库提交后进程退出,订单存在却没有消息。反例二是先发 MQ,再提交订单。消费者可能抢先执行,随后订单事务回滚,产生没有订单的库存预占。把发送放在 afterCommit 能避免未提交就发布,但仍会在提交后、回调执行前崩溃,因此不能独立解决可靠发布。

Outbox 的关键是订单与待发事件在同一数据库、同一事务、同一可原子提交边界内保存。若订单分片与 Outbox 实际位于不同事务资源,“同一方法加注解”并不会让它们自动原子。可以每个订单分片维护自己的 Outbox,再由分片感知的扫描器或 CDC 发布。

-- 教学 SQL,省略审计字段;不是业务库迁移脚本
BEGIN;
INSERT INTO orders(tenant_id, order_id, status, version)
VALUES (:tenant, :order, 'PENDING_STOCK', 1);
INSERT INTO outbox(tenant_id, event_id, aggregate_id, version, status, payload)
VALUES (:tenant, :event, :order, 1, 'NEW', :payload);
COMMIT;
-- 必须有订单业务唯一键以及 outbox(tenant_id,event_id) 唯一键

此后进程即使退出,扫描器仍能发现 NEW。扫描器发送成功后再标记 SENT;若发送成功但标记前退出,下次会重复发送。这正是 Outbox 的设计取舍:允许可识别的重复,避免不可恢复的遗漏。SENT 只说明发布责任完成,不说明消费者已经处理。

3. Outbox 自身也需要状态机

教学状态为 NEW -> CLAIMED -> SENT,失败可进入 RETRY_WAIT,永久错误进入 QUARANTINED。CLAIMED 保存 owner、leaseUntil、attempt 和领取版本。领取应通过条件更新或短事务锁完成,发送不应占着数据库事务等待网络,否则慢 Broker 会拖住大量连接和行锁。

租约到期后其他扫描器可接管。旧扫描器恢复时,更新发送状态必须带领取版本条件,防止覆盖新扫描器结果。重复发送仍可能发生,所以消费幂等不能省。扫描索引应支持按状态和下次执行时间读取,小批次领取并控制总在途量;不加索引地全表扫描会把可靠性功能变成主库负担。

对于顺序事件,还要防止多个扫描器把同一订单的 v2 先于 v1 发出。可按聚合键分配执行分区,或者领取时只允许该键最早未发送事件推进。增加线程数量不会自动保持顺序。使用 CDC 发布 Outbox 可以避免轮询争抢,但需要正确处理日志位置、路由键、重放与结构变化。Debezium Outbox Event Router 提供这种事件路由机制;本章是教学设计,不表示仓库已接入它。

4. Inbox 必须与业务效果一起提交

消费端先查去重表、发现不存在、然后扣库存,是典型竞态:两个线程都可能查不到。唯一约束负责最终裁决,且去重记录与库存变更必须在同一事务中。先单独写“已处理”,再扣库存,会在崩溃后永久跳过;先扣库存,再单独写“已处理”,会在重投后重复扣减。

开启本地事务
  插入 inbox(tenantId,eventId,payloadHash) —— 唯一约束争夺处理权
  如是同键重复:校验摘要,读取已完成结果,结束本次处理
  校验订单命令状态与数量
  条件更新库存:available >= qty 才允许预占
  写 reservation 流水与结果事件 outbox
提交事务
向消息客户端返回消费成功

重复键处理要适配实际数据库与事务框架:有的异常会使当前事务回滚或变成 rollback-only,不能在 catch 后继续随意写。可以使用明确支持的冲突处理语句,或回滚后在新事务读取已完成结果;不能用 INSERT IGNORE 静默忽略所有数据错误。库存不足是业务结果,可连同 Inbox 一起提交拒绝事件,避免无限重试一个确定拒绝。

如果消费动作包含外部扣款,Inbox 与本地事务不能包住远端副作用。应该将“请求外部扣款”再写为可靠任务,用对方支持的幂等键执行并查询流水;对方不支持幂等或结果查询时,自动重试的安全范围就受到实质限制。

5. 状态机比“是否处理过”更强

订单可能经历 PENDING_STOCK -> RESERVED -> CONFIRMED,也可能从 PENDING_STOCK 或 RESERVED 进入 CANCELLED。预占成功事件迟到时,如果订单已经取消,应保持 CANCELLED,并产生释放任务。只检查“这个消息 ID 没见过”并不足以阻止状态倒退,因为迟到事件完全可能是第一次到达。

教学更新采用 UPDATE ... WHERE status='PENDING_STOCK' AND version=:expected。影响行数为 0 时需要读取当前状态,区分重复、冲突和合法取消后的迟到,不应一律抛出可重试异常。业务版本按聚合递增,时间戳只用于观测,不作为跨机器因果的唯一裁判。

Inbox 保留周期决定了可识别重复的时间范围。若人工能在半年后重放历史消息,而去重表只保留一周,就必须靠永久业务流水唯一键继续兜底,或把重放限制在可证明安全的范围内。归档和清理是协议的一部分,不能只按表大小随意删除。

结果事件也要可靠形成

库存消费成功后,如果只是直接发送“预占成功”而没有本地结果 Outbox,原来的双写问题会在链路下一跳重现:库存已冻结,订单永远等不到结果。因此可靠性不是只在入口加一张表,而是在每个需要跨资源传播业务事实的边界上重新检查原子性。库存流水与结果事件一起提交,订单消费结果时也原子更新自身状态与 Inbox。

请求结果的保留也要设计。幂等服务可以保存完整响应,或保存足以重建响应的稳定结果引用;不能每次重复请求都读取当前可变库存后生成不同含义的结果。首次预占成功、后来库存卖完,并不改变第一次请求已经成功的历史事实。响应中可同时区分“该请求的结果”和“当前资源状态”,避免客户端误判。

当业务键和消息键都存在时,应分别约束。一个上游缺陷可能给同一订单预占命令生成两个不同 eventId,Inbox 对它们都判定首次到达;永久预占流水的业务唯一键仍可阻止重复冻结。这个双层防线是防范身份生成错误的手段,并不意味着可以忽略上游错误,应记录冲突并修正产生重复身份的路径。

6. 故障推演与可观测性

第一次投递完成库存事务后,在返回确认前崩溃。重投命中 Inbox,摘要相同,返回已处理结果;库存仍只预占一次。第二种故障发生在扣库存后但事务提交前,此时事务整体回滚,Inbox 也不存在,下次可以正常执行。第三种故障发生在发布器已发送、尚未标记 SENT 时,事件会重复,但消费者结果保持不变。

这三条链路解释了为什么要分别测“消息物理发送次数”和“业务生效次数”。发送两次并不必然是事故,业务扣减两次才可能违反不变量。应监控 Outbox 最老未发时间、租约回收次数、Inbox 重复命中、同键参数冲突、状态转移拒绝与隔离队列年龄,不能用单一错误率替代恢复质量。

安全反例是接收任意客户端传入的 eventId 后就无条件返回旧响应。若唯一键缺少租户,攻击者可能碰撞别人的 ID 并获得结果。重复请求同样要授权,结果摘要也要按当前访问权限过滤;幂等不是绕过鉴权的捷径。

7. 练习与答案

练习一: Redis SET NX 成功后再执行数据库事务,能代替 Inbox 吗?

答案: 不能直接代替。标记成功、数据库回滚时会错误跳过;标记过期后旧命令又可能执行。可以把 Redis 用于降低重复压力,但最终正确性仍需业务数据库的唯一约束和原子提交。

练习二: Outbox 发布成功就删除记录是否可行?

答案: 理论上可在具备可靠审计与恢复设计时清理,但立即删除会削弱排查与重建能力。应先形成明确发布状态,再按保留政策归档;发送成功、删除前崩溃仍会重复,消费幂等必须存在。

练习三: 取消命令比预占命令先到,怎么办?

答案: 为业务键留下取消墓碑,阻止迟到预占重新占用;若预占已经存在,则释放且记录已释放。取消重复到达只返回同一结果。这是下一章及事务章节将继续使用的状态机思想。

官方参考

原始文档 · distributed-course/04-分布式锁租约与调度.md

04 分布式锁、租约、fencing 与调度

图解 · 可横向查看
租约到期不等于旧执行者停止:写入端还要校验token时间从上到下;虚线箭头表示返回。前提:授权方提供单调token,资源端原子比较并拒绝旧写入。;普通Redis锁或任意对象存储不自动具备此能力;外部文件可用隔离键+受控发布。 租约到期不等于旧执行者停止:写入端还要校验token旧 worker租约授权方新 worker受保护资源取得 token=7暂停 / 长GC到期后取得8带8写入,接受恢复后带7写入拒绝旧token前提:授权方提供单调token,资源端原子比较并拒绝旧写入。普通Redis锁或任意对象存储不自动具备此能力;外部文件可用隔离键+受控发布。
租约过期与旧执行者写入的fencing保护

图示为教学简化,需结合下文的适用条件、故障窗口和项目证据阅读。

返回目录 · 上一章 · 下一章

1. 锁是一段有条件成立的独占权

前端常通过禁用按钮避免重复点击,单进程 Java 通过 synchronized 保护临界区;多实例部署后,每个 JVM 都有自己的锁,无法协调另一实例。分布式锁把竞争转移到共享协调资源,但网络与进程暂停使“我曾拿到锁”和“我现在仍有权写”不再等价。

锁保护的是特定资源和临界区,幂等保护的是同一业务命令不能重复生效。顺序执行两次扣库存,即便从未同时持锁,也可能重复扣减。因此锁不是去重表的替代品。对于数据库内可表达的不变量,唯一约束、条件更新和事务往往比跨网络锁更直接;锁可以减少竞争,但不应抹去最后一道数据约束。

2. 真实出库锁把释放点放在事务之后

HandOutboundOrderCreateLock.java〔本地文件〕 第 25—35 行检查 Redisson 是否可用,并以用户 ID 组成锁键。服务不可用时抛出业务异常,没有无锁继续。第 33 行调用 tryLock(5, TimeUnit.SECONDS):这里的 5 是等待获取锁的时长,不是显式租约时长,不能讲成“五秒后自动释放”。

第 37—45 行在 TransactionTemplate 内注册事务同步回调,第 40—41 行在 afterCompletion 解锁。第 50—53 行仅在尚未登记事务回调时兜底释放。这体现一个重要边界:如果加入已有外层事务,方法返回时事务可能还没提交,必须等实际事务完成再释放,否则另一线程拿锁后仍可能读到旧状态。

但这段源码不证明锁永不失效。没有显式租约时,常见 Redisson RLock 依赖 watchdog 续租;实际行为取决于依赖版本和配置,应对照 Redisson 官方锁说明。长时间暂停、续租失败或连接异常可能让旧持有者失去锁。当前阅读未核验运行时配置,也未证明发生过双持有者事故。

3. 随机 owner 与 fencing token 解决不同问题

简单 Redis 锁通常用带过期时间的原子写入,value 保存不可预测的 owner;释放通过原子比较 owner 后删除。不能先 GET 再 DEL,因为两条命令之间锁可能过期并被别人获取,旧线程就会删掉新锁。owner 解决的是“不要删除别人的锁”,并不阻止旧线程在锁失效后向数据库写入。

fencing token 是随每次新的有效授权单调递增的编号,例如 41、42。受保护资源持久化已接受的最大编号,并原子拒绝旧编号。旧工作者即使不知道自己失锁,只要新工作者的更高编号已经在资源侧生效,旧写就无法覆盖新结果。编号生成与授权必须由可证明正确的协调协议绑定;随手用本地时间戳或可能回滚的计数器不能提供同样保证。

时刻 0:A 获得 token=41,随后长时间暂停
时刻 8:A 租约到期,B 获得 token=42
时刻 9:资源接受 B 的 token=42 写入,并保存 maxToken=42
时刻 10:A 恢复,提交 token=41 -> 资源拒绝

教学 SQL 可以把 token 条件放进同一写入:

UPDATE task_result
SET result = :result, last_token = :token
WHERE tenant_id = :tenant AND task_id = :task
  AND last_token < :token;

这里假定每次授权只提交一次结果;若同一 token 下需要多步更新,就要把“接管 token”与“同 owner 的操作序号/幂等”分别建模,不能照搬严格小于号。初始行创建同样需要唯一约束。fencing 也不等于自动跨资源原子提交:数据库接受 token 后,对象存储、外部平台是否同样验证,需要逐一说明。

4. 租约无法用一个更大的 TTL 彻底修复

TTL 太短,正常长任务容易被接管;太长,真实宕机恢复会很慢。续租能改善正常执行期间的可用性,却不能排除进程暂停超过租约后又恢复。因而 TTL 是恢复速度与误接管概率的参数,不是无条件互斥证明。

从资源端看,fencing 的常见保证是阻止旧 token 覆盖已经接受的新 token。若要求“租约一到期,旧客户端任何写都绝不接受”,资源还必须在线校验当前授权或在同一权威资源中管理租约;单纯记录最大已见 token 无法知道尚未到达的新授权。这一细节能避免把 fencing 神化。

在我们的实验中,用整数逻辑时间模拟过期,用显式步骤安排 A 暂停、B 写入、A 恢复。它只验证资源拒绝较旧 token 的状态转移,不模拟 Redis 主从切换、时钟漂移或 Redisson watchdog。实际系统仍需故障注入验证暂停、断网和协调存储故障。

5. 调度器成功与业务完成不是同一事实

HandStockOccupiedJobHandler.java〔本地文件〕 第 64—99 行读取已处理用户集合,循环调用处理方法,异常返回 FAIL,正常返回 SUCCESS;第 103—107 行的已处理集合来自业务配置工具。这个入口体现了按用户执行与跳过机制,但仅凭它不能证明每条订单都形成持久化进度,也不能把配置中的已处理集合当作完整任务账本。

XXL-Job 负责触发、路由与执行反馈,业务还要设计重复触发与中途退出。推荐教学任务键 (jobType, tenantId, windowStart, windowEnd, revision),任务表保存游标、owner、租约和状态。每页业务提交后更新同一事务内的进度;进度先更新、业务后提交会跳过数据,业务先提交、进度后更新会重复,所以后者仍需幂等兜底。

扫描变化中的数据时,页码分页可能漏项或重复。可用稳定主键游标,固定本轮上界,并说明新增数据交给下一轮。多个工作者通过条件领取分片任务,重入执行相同窗口也不会重复生效。不能只用“上次跑完标记”为整个租户背书,因为一个租户可能有数百万条订单,部分完成必须能恢复。

6. 性能、稳定性与安全反例

商家级锁实现简单,但大商家所有出库串行,慢外部调用会延长持锁时间。若能证明不同仓库、订单不会共享不变量,可以拆分锁粒度;否则贸然拆锁会换来竞态。临界区尽量只包含需要独占的状态变更,外部网络操作转成可靠任务,但不能为了缩短持锁而把事务提交移到解锁之后。

当多个资源必须同时锁定,应按稳定顺序获取,例如按租户、仓库、SKU 排序,并设总等待预算。否则 A 持有 SKU1 等 SKU2,B 持有 SKU2 等 SKU1,会形成死锁或持续超时。任务恢复也要限速,避免故障恢复后一瞬间所有过期租约被抢占而压垮数据库。

安全反例是允许普通调用者指定任意锁键、任务租户或 fencing token。它可以制造跨租户阻塞,甚至用巨大 token 拒绝后续合法写。键和授权应由可信服务根据已验证的业务身份生成,token 只能来自可信授权路径。重放与强制解锁需要审计,不能作为常规排错按钮随意使用。

任务领取与结果发布也需要所有者校验

教学任务表可以保存领取代数:工作者甲领取时获得第七代,暂停后租约过期,工作者乙以第八代接管。甲恢复后即使完成了计算,也必须用 WHERE generation=7 AND owner=甲 条件提交结果;更新零行说明已经失去发布资格。这个条件必须与结果持久化属于同一原子边界,仅在计算开始前检查一次没有作用,因为资格可能在计算过程中变化。

如果结果是导出文件,上传文件本身可以使用包含任务代数的临时名称,最后再由带代数条件的数据库更新决定哪个文件成为可见结果。失败代数留下的临时对象由清理任务处理。这样旧工作者即使完成上传,也不能覆盖新任务的下载链接。实际对象存储是否支持条件写需要另行验证,不能把数据库里的检查误认为已经保护了任何外部副作用。

调度任务的运维指标也应该围绕所有权和进度:最老未完成任务年龄、持续无进展时间、租约回收次数、重复领取次数、结果提交被拒绝次数。频繁接管可能是任务太慢、暂停太久或租约设置不合适;仅延长租约会掩盖根因并拖慢真实宕机恢复。先测量任务各阶段耗时,再调整并发、批量与租约,才有可解释的优化依据。

7. 练习与答案

练习一: 为什么随机 UUID owner 不能代替 fencing token?

答案: UUID 能判断是否同一持有者,却不表达新旧顺序。资源收到两个不同 UUID 时不知道谁已失效;单调 token 配合资源端比较才能拒绝旧授权。

练习二: 出库方法 finally 解锁,外层事务稍后提交,有什么窗口?

答案: 下一请求可能在旧事务尚未提交时获得锁并基于旧状态决策。真实锁类通过事务完成回调延迟释放,但仍需检查事务参与关系和失锁场景。

练习三: 调度器显示成功,是否可以删除业务任务记录?

答案: 不应仅凭调度返回值。需要业务终态、提交证据与对账结果;按保留策略归档,确保重复触发和人工复核仍可解释历史执行。

官方参考

原始文档 · distributed-course/05-SagaTCC补偿与对账.md

05 分布式事务:Saga、TCC、补偿与对账

返回目录 · 上一章 · 下一章

1. 本地回滚无法撤销已经发生的远程事实

在 Java 方法上添加 @Transactional,通常约束的是当前事务管理器参与的本地资源。远端库存服务有自己的连接和事务;订单服务随后抛异常,不会自动撤销远端已经提交的预占。把整个调用链画成一个大的事务框,只是一种视觉愿望,除非所有参与者确实实现并加入同一分布式协议。

读取 StockDomainServiceImpl.java〔本地文件〕,该分支注释说明在特定标签发货且开启预占的场景,需要先释放预占再扣库存。第 364—374 行构建请求并调用 iRdsTradeRpcService.tradeOccupiedStock,第 375—376 行根据响应错误抛出异常。这是一个真实跨服务编排点,适合追问远端成功、本地后续失败时如何收敛。

不能仅凭这几行断言已有不一致漏洞:是否有幂等流水、后续补偿、调用方事务和平台重拉,需要完整追踪。本章没有证明部署事故,也不把项目说成已经采用 Saga 或 TCC。下面给出的协议是围绕这个业务问题建立的教学设计。

2. 先判断能否减少分布式边界

若两个数据变更本来属于同一业务聚合、由同一服务和数据库拥有,优先考虑一个本地事务,避免为了“微服务”把天然不变量拆开。若必须跨订单、库存、支付等独立所有者,就要明确哪些短暂中间态可见、多久允许收敛,以及失败后由谁恢复。

两阶段提交一类协议通过准备与统一决议协调参与者,但会引入参与者状态、协调者恢复和资源占用。它并不能让所有远端 API 自动具备事务能力。Saga 用已提交的本地动作加补偿收敛;TCC 则要求业务显式预留资源,再确认或取消。两者都需要持久化协议状态,选择依据是业务资源能否预留、补偿是否可行和中间态能否被接受,而不是哪个名称听起来更强。

3. Saga:补偿是新的业务动作

教学订单 Saga 的正向步骤为创建待确认订单、预占库存、申请履约;如果履约申请明确失败,则释放预占并取消订单。每一步都是独立的本地事务,之前的结果对其他业务可能已经可见。补偿不是数据库时间倒流,而是新的、可失败、需审计的反向业务动作。Seata Saga 官方说明同样强调本地提交与业务补偿,并指出隔离性需要额外处理。

NEW -> ORDER_CREATED -> STOCK_RESERVED -> FULFILLMENT_ACCEPTED -> DONE
                             |
                       明确业务拒绝
                             v
                  RELEASE_PENDING -> STOCK_RELEASED -> CANCELLED
                             |
                     暂时故障 -> 延迟重试
                     不可判定 -> MANUAL_REVIEW

协调器保存 sagaId、每步请求键、输入摘要、执行状态、结果引用、尝试次数与下次执行时间。它先持久化“准备执行该步骤”,再发送幂等命令;宕机恢复后查询或重试相同命令。不能只在内存 List 中记住哪些步骤成功,否则协调器重启就失去补偿依据。

如果预占请求超时,协调器不能立即推断失败并补偿。它可能实际成功,接下来需要查询同一业务流水,或以同一幂等键重试得到确定结果。补偿也有相同歧义:释放成功但回复丢失时,应重复返回已释放结果,不能再把库存加一次。状态应允许 UNKNOWN 或待确认,避免把通信失败误记为业务失败。

4. 为什么补偿不能机械取反

库存从 10 减到 8 后,另一订单又减到 5。补偿第一笔应增加其对应的 2,并核对预占流水,而不是把库存恢复为旧快照 10。退款也不是把账户余额直接设置回之前的值,因为期间可能存在别的流水。反向动作必须与原业务效果建立一对一关系,并通过唯一补偿键保证最多生效一次。

有些动作不可真正补偿:邮件已经被看到、快递已经揽收、外部税务单据已经生效。此时补偿是通知更正、拦截包裹或开红字单据等新的流程,可能有时间限制和人工成本。设计 Saga 时应尽量把不可逆动作推迟到足够确定之后,同时保留“无法自动恢复”的业务终态,不能永远显示处理中。

Saga 缺少天然隔离,会出现中间态被其他流程消费。库存释放尚未完成时订单已显示取消,前端应说明释放进度;履约系统不能把 PENDING_STOCK 订单当作可出库订单。可以用语义锁,即通过状态限制允许的业务动作,而不是跨服务持有长数据库锁。这种限制必须被所有写入口遵守。

5. TCC:先预留,再确认或取消

库存天然适合讨论 TCC。Try 检查可用量并把数量转入冻结;Confirm 把冻结转为已售;Cancel 释放冻结。教学模型保持 total = available + frozen + sold,其中 total 是本次模型的初始额度,不覆盖实际仓库的采购、损耗和盘点。三种动作都依据同一分支键,且各自事务提交。

NONE --Try成功--> TRIED --Confirm--> CONFIRMED
  |                 |
 Cancel             Cancel
  v                 v
CANCELLED <------ CANCELLED

规则:CANCELLED 上的迟到 Try 拒绝;CONFIRMED 上的 Cancel 拒绝并上报冲突。

空回滚是 Cancel 先于 Try 到达,此时不释放并不存在的库存,但要记录 CANCELLED 墓碑。悬挂是已取消后迟到的 Try 又成功冻结资源,墓碑用来阻止这种复活。重复 Confirm 或 Cancel 必须返回原结果;Try 与 Cancel 并发时,通过同一分支唯一键和本地锁/条件状态更新裁决,不能依赖先查后写。

Confirm 不宜再次执行可能失败的可用库存检查,因为资源应已由 Try 预留。不过数据库故障仍可能使 Confirm 暂时失败,协调器必须重试直至完成或进入人工处理。全局提交决议一旦持久化,就不能因某次 Confirm 超时擅自切换到 Cancel,否则不同分支可能走向不同终态。参考 Seata TCC 模式。

6. 对账是独立的正确性检测通道

协议设计再严密,也可能遇到历史数据、代码缺陷、人工误操作和边界外故障。对账不应简单重放所有失败日志,而应比较业务不变量:已确认订单是否拥有匹配数量的预占或出库流水;取消订单是否仍有冻结;每条补偿是否对应原流水;同一业务键是否出现多个有效结果。

对账有时间窗口。刚创建的订单还没收到库存回执,不应立即当成错误。可设观察宽限期,并记录双方版本、最近修改时间和源流水标识;宽限期是业务恢复目标,需要通过容量与故障恢复测试建立,而不是随意写一个常数。修复任务沿用可靠任务协议,有自己的幂等键、授权、前置条件与结果审计。

只比汇总金额或库存总数可能漏掉抵消错误:一笔多扣 2,另一笔少扣 2,总数仍相等。应该先分租户、仓库、时间段定位差异,再比较明细集合与业务关联。对于正在变化的数据,应使用相同截止点或可解释的快照/水位,避免把观察时间不同造成的差异误认为实际错误。

7. 故障推演与性能安全反例

设 Try 成功后协调器宕机。库存不能仅凭“过了五分钟”擅自释放,因为全局决议可能已经提交,只是 Confirm 没到。恢复应查询可靠协调状态,或使用协议中预先约定且不会与提交决议冲突的超时规则。任意本地定时清理冻结记录,会破坏全局承诺。

性能反例是在 Saga 全流程持有数据库事务,等待外部物流响应几十秒。连接池、行锁和重试相互放大,最终把局部慢调用传播到所有订单。应让每步快速本地提交,外部操作由持久化状态驱动。稳定性上,补偿重试需要与正向流量分配配额,否则故障后的补偿洪峰会阻断新订单并延长恢复。

安全反例是运营接口允许凭订单号直接“释放库存”。订单号可能属于其他商家,或早已完成出库。修复必须验证租户、原预占流水、当前状态和操作权限;高风险批量修复应形成可审阅差异与审计,不能把补偿包装成没有条件的加减库存接口。

8. 练习与答案

练习一: Saga 补偿失败能否把 Saga 标记为失败后结束?

答案: 可以结束某次执行,但不能丢弃恢复责任。状态应保留待补偿或人工处理,持续记录重试预算和未恢复资源,直到业务承认并处理残留。

练习二: TCC Cancel 先到,记录不存在时直接返回成功够吗?

答案: 不够。还需要持久化取消墓碑并与 Try 竞争同一唯一键,否则迟到 Try 会冻结资源,形成悬挂。重复 Cancel 不释放两次。

练习三: 为什么对账数量相等还要抽查明细?

答案: 多记和少记可能抵消;还可能把 A 租户的记录错误归入 B 租户。需要集合身份、数量、状态和租户同时匹配。修复前要保存差异证据,修复后再次验证对应不变量。

官方参考

原始文档 · distributed-course/06-CDC同步与分片迁移.md

06 CDC、数据同步与分片迁移:位置比“同步成功”更具体

返回目录 · 上一章 · 下一章

1. 数据库变化不等于领域事件

CDC 捕获已提交的数据变化,常用于报表、搜索和下游镜像。它观察的是表与行的变化,不天然知道“订单已完成支付”这种业务语义。一次业务操作可能修改多张表,一行更新也可能只是修正备注。若把任何订单表 UPDATE 都解释成付款成功,就把存储变化误当成领域事件。

需要稳定业务语义时,可以在本地事务中写 Outbox,再让 CDC 捕获 Outbox;需要构建读模型时,可以消费相关表的变化,并维护字段映射、版本与删除语义。不能因为数据来自 binlog 就跳过租户隔离和授权,下游往往聚合更多数据,访问面甚至比源库更大。

2. 真实 DTS 消费器的确认边界

AbstractConsumerListener.java〔本地文件〕 第 70—75 行集中调用 record.commit("")。第 79—105 行可按开关把记录放入 LinkedTransferQueue,满足数量阈值或在后续消费调用中发现距上次刷新超过十秒时,再取出批次。注意这里只看到了由 consume 调用触发的时间判断,不能据此断言有独立定时器保证十秒内必刷。

第 110—124 行转换业务模型,空模型列表直接提交;非空时调用 consumeWhetherCommit,为 true 才提交。第 138—147 行按 userId 分组并汇总所有任务的布尔结果。第 209—212 行返回业务结果并清理 ContextHolder 与 MDC。这里体现了“业务处理结果决定提交”和线程复用后的上下文清理,都是重要的正确性边界。

如果一个用户处理成功,另一个失败,整个批次暂不提交,则成功用户可能再次处理。因此下游写入仍应幂等。至于未提交记录何时重投、commit 是否按分区累计推进,要核验所用 DTS SDK 的实际契约,本次未验证 SDK 内部或服务部署,不能仅凭方法名推断。

3. 过滤逻辑也是同步协议的一部分

RdsOrderTableDtsSyncConsumerListener.java〔本地文件〕 第 59—68 行只让匹配表名的 UPDATE 进入该监听器;第 95—129 行转换 before/after 数据与 userId,一些过滤分支返回 null。基类对空模型提交原记录,意味着这类过滤是主动放弃处理,而不是稍后重试。

因此不能把这个监听器讲成“完整复制订单表的 INSERT、UPDATE、DELETE”。它服务于特定业务更新,其他动作可能由别的链路承担,本章没有推断全项目缺失其他监听。风险分析的条件是:若产品要求这条监听器独自构建完整镜像,却未提供首次装载和其他操作类型处理,则新行或删除可能无法正确反映。该条件不等于现有部署事实。

过滤规则上线后再撤销,也不会自动找回已经提交跳过的历史记录。必须明确是否需要从可保留的日志位置重放,或按业务范围重新快照。字段级容错同样如此:第 149—155 行解析扩展字段异常时跳过该字段更新并记录日志,这是局部可用性取舍,后续需要知道哪些记录缺少字段,才能定向修复。

4. 快照与增量必须覆盖同一条时间线

教学错误流程是先扫描全表,扫描结束才开始订阅增量。扫描期间发生的修改可能既没有出现在已扫描页,也没有进入订阅,形成缺口。相反,先订阅并回放新值,再无条件导入旧快照,则可能用旧数据覆盖新值。正确协议需要快照与日志位置之间的衔接,并处理重叠而非假定没有并发写。

源数据库:---提交 e1---[一致性切面 L]---提交 e2---提交 e3---->
快照:                  读取与 L 对应的状态
增量:                  从协议定义的位置持续追赶 e2、e3
目标:                  合并快照与增量,重复可识别,旧值不可回盖

不同 CDC 引擎可能采用一致性快照、分块快照、高低水位或其他协调方法,不应把图中的单一 L 机械套到所有实现。Debezium MySQL 官方文档说明快照与日志读取的具体机制。此处用于原理对照,真实项目引用的是阿里云 DTS 记录类型,不能据此宣称它使用 Debezium。

日志位置不是普通时间戳。它可能包含分区、事务、文件位置或 GTID 等信息,不同日志流的 offset 不能直接比较大小。下游保存的 checkpoint 应对应已完成的连续前缀:若 10、12 已完成,11 未完成,直接推进到 12 可能跳过 11。并行处理可以记录完成集合,但对外安全水位只能推进到没有缺口的位置。

5. 目标幂等与删除墓碑

教学读模型按 (tenantId, entityId) 唯一,保存 sourceVersion。完整快照更新只有比现有版本新才生效;重复版本需验证内容一致,旧版本忽略并记录指标。增量加减事件不能简单套用“旧版本忽略”,因为跳过中间增量可能改变结果;需要连续序列、去重账本或从源重建。

删除也要带版本。若 v7 删除目标记录后完全遗忘版本,迟到的 v6 更新可能把记录重新插入。可以保留删除墓碑 (key, version=7, deleted=true),直到确认没有更旧的重放来源。墓碑清理与日志保留、人工回放期限相关,不能仅按磁盘压力随手删除。

目标写入与 checkpoint 提交也有双写窗口。先写目标、后提交位置,会在崩溃后重复,适合用幂等吸收;先提交位置、后写目标,会在崩溃后漏掉效果。若引擎提供端到端事务保证,需要明确连接器、目标存储和配置适用范围;普通异步回调并不自动拥有这个保证。

6. 分片迁移要迁移所有写入口

真实 TableShardingUtil.java〔本地文件〕 第 60—64 行通过 ID 对映射中的表数量取模,第 72—76 行据此生成初始分表配置。静态映射中出现 EXAMPLE,不能拿它推断所有线上表的分片数量。可以确定的是:取模基数参与路由计算,改变基数会改变一部分已有 ID 的归属。

比如教学 ID 7 在两片时落到 1,在三片时仍落到 1;ID 8 从 0 变成 2。简单改配置不会搬运旧行,读写就可能分离。一个可审阅迁移协议应包含旧路由版本、目标路由版本、快照复制、增量追赶、校验和切换栅栏。切换前必须处理仍持有旧路由的请求、异步任务、重试消息和人工修复入口。

教学步骤是先让目标只接受迁移写,源继续作为唯一业务写权威;完成快照与增量追赶后,短暂阻止待迁租户的新写,等待在途旧写结束,记录最终水位并追平;校验后切换路由版本,使新写只到目标;保留旧库只读用于复核。若无法停写,需要更复杂的双写仲裁与 epoch 检查,不能把“同时写两边”当作原子复制。

回滚也有时间方向。目标开始接受独有新写后,直接切回旧源会丢掉这些新写。必须先反向追平、校验并再次建立切换栅栏,或者明确越过不可快速回滚的阶段。迁移方案中的回滚条件应在执行前写清楚,而不是故障时临时决定。

7. 故障推演、性能与安全

若快照吞吐低于新增变化速率,增量永远追不上;迁移期间大批扫描还可能争抢主库缓存和 I/O。应按租户与分片限速,记录源水位、目标水位、最老未应用事件年龄和预计追赶时间,预留日志保留空间。只看“队列长度为零”不够,断开的订阅器同样可能没有收到任何消息。

安全反例是把所有源字段复制到报表库,再给报表使用者全库权限。字段最小化、脱敏、租户过滤和删除传播应在同步设计阶段确定。重放工具只允许操作指定范围,不能让普通用户任意指定源表或目标分片。扩展字段解析失败应记录标识和错误类型,不应把整个敏感行作为默认日志。

结构演进也会影响恢复。增加字段时应先让目标能够容忍旧事件缺少该字段,再启用新映射;重命名或改变单位时需要协议版本,不能把历史日志按新含义解释。回放前固定转换器版本与字段规则,记录回放范围和目标水位,才能在结果不同的时候区分源数据变化与转换逻辑变化。

8. 练习与答案

练习一: 并行处理到 offset 20,但 18 还没完成,能提交 20 吗?

答案: 如果该 offset 表示同一分区的累计进度,就不能;最多提交到连续已完成前缀。多个分区各自维护水位,不存在一个随意取最大的全局数字。

练习二: 删除目标行后收到旧更新,怎样避免复活?

答案: 保留带版本的删除墓碑,旧更新被拒绝。重新创建同一个业务 ID 时需要新的合法版本或新生命周期标识,避免被误当成旧数据。

练习三: 迁移前后行数相同是否足够?

答案: 不够。可能一行缺失、一行多余,也可能字段值或租户归属错误。应按稳定快照或水位比较主键集合、字段摘要与关键业务总量,差异缩小后再做明细核验。

官方参考

原始文档 · distributed-course/07-订单库存综合实战.md

07 订单、库存与消息:把故障验收写进设计

返回目录 · 上一章 · 故障实验

1. 先定义一个可被推翻的业务承诺

本章教学场景是商家提交订单,订单服务可靠记录请求,库存服务异步预占,订单收到结果后确认或拒绝,页面通过通知或查询获知终态。取消可以与预占并发。教学目标不是复刻全部 ERP,而是让每个中间状态、每次确认和每条恢复路径都能接受故障检验。

定义三个独立所有者:订单服务拥有订单及其 Outbox;库存服务拥有可用量、预占流水、Inbox 与结果 Outbox;通知服务拥有通知任务和送达状态。订单不能直接修改库存表,库存不能偷偷更新订单终态。每个所有者的本地事务可以原子提交,跨所有者依靠事件和状态机收敛。

业务不变量为:同租户同外部订单唯一;同一预占命令最多生效一次;预占不让可用量为负;已取消订单不能被迟到回执重新确认;已释放的预占不能再次释放。活性目标则是依赖恢复且任务持续调度后,有效订单最终到达确定终态,无法自动处理的订单进入有责任人的人工状态。不要用“接口最终返回 200”代替这些承诺。

2. 四个真实项目提供了哪些学习入口

在 StockDubboServiceImpl.java〔本地文件〕 第 255—276 行,订单预占入口创建日志标识、调用校验、检查开关并进入预占操作。这是追踪请求如何进入库存领域的入口。局部设置 needCheckStock=false 不能脱离后续调用链解读成“系统不校验库存”;实际约束可能分布在其他条件和更新路径,本章没有做这样的断言。

在 StockDomainServiceImpl.java〔本地文件〕 第 1198—1217 行,代码筛选需要同步的 SKU,构建库存异步消息,设置 userId、shardingKey、itemLogKey 和 msgKey,随后调用发送封装。msgKey 使用用户与首个 SKU 拼接,不能据名称推断它是覆盖完整业务语义的幂等键;生产封装是否持久化、是否保证顺序,需要进一步核验。

RDS 的 订单队列监听器〔本地文件〕 展示入队后成功返回的边界;消息推送的 SSE 监听器〔本地文件〕 展示通知失败与消费确认的取舍;DTS 的 批量监听基类〔本地文件〕 展示处理结果与记录提交的关联。这四个入口是真实阅读证据,不代表它们已按本章方案连接为同一条生产链路,也不证明发生过线上事故。

3. 请求、事件和结果各自建模

外部提交请求携带稳定 requestId,服务端从可信身份确定 tenantId,并计算规范化参数摘要。数据库以 (tenantId, requestId) 唯一,首次请求创建订单并写 ReserveRequested;重复请求返回同一订单,同键不同参数拒绝。前端超时后继续使用同一个 requestId 查询或重试,而不是生成另一张订单。

教学事件包括 eventId、tenantId、aggregateId、aggregateVersion、eventType、schemaVersion、causationId 与必要业务数据。traceId 用于观测但不参与业务身份。schemaVersion 约束数据解释方式,aggregateVersion 约束同一订单的变化顺序,两者不能混用。事件不带授权密钥,只带完成业务所必需的数据。

页面 -> 订单事务:请求记录 + PENDING_STOCK + ReserveRequested Outbox
发布器 -> Broker -> 库存事务:Inbox + 条件预占 + 预占流水 + 结果 Outbox
结果发布器 -> Broker -> 订单事务:Inbox + RESERVED/REJECTED + 通知 Outbox
通知服务 -> 页面 SSE;页面也可按订单标识查询业务终态

这里每个箭头都可能重复,任何进程都可能在箭头前后退出。正确性不依赖箭头恰好发生一次,而依赖接收端能识别身份、原子提交并验证状态。对于批量订单,应返回每个订单的处理状态,避免一个整体 success 掩盖部分失败。

4. 库存事务必须保护最后一件商品

教学库存表以 (tenantId, warehouseId, skuId) 唯一,预占流水以 (tenantId, reservationId) 唯一。事务先争夺 Inbox 或业务流水身份,再执行条件扣减,只有更新一行才记录预占成功;不足时记录拒绝结果。多 SKU 订单如果要求全有或全无,应在一个可覆盖相关库存行的本地事务中按稳定顺序锁定和更新;跨分片时则不能假装仍是同一事务。

-- 教学片段,须和流水、Inbox、结果 Outbox 放在同一事务
UPDATE inventory
SET available = available - :qty,
    reserved = reserved + :qty
WHERE tenant_id = :tenant AND warehouse_id = :warehouse AND sku_id = :sku
  AND available >= :qty;
-- 更新行数为 1:预占成功;为 0:区分缺失、权限与库存不足

数量必须在入口验证为正整数,并控制上限。否则传入负数会把扣减变成增加,数据库的非负检查也未必能拦住。金额与数量的单位转换要在契约中定义,不接受前端拼接的 SQL 条件或任意仓库归属。内部消息同样要验证租户、仓库与 SKU 关联,不能因它来自 Broker 就省略授权边界。

5. 取消与迟到成功如何收敛

订单在 PENDING_STOCK 时收到取消,先进入 CANCEL_REQUESTED 并可靠发出取消预占命令。库存侧若尚无预占,建立取消墓碑;若已经预占,则释放一次并记录 RELEASED。迟到的 ReserveRequested 看到墓碑后拒绝,不得重新冻结;迟到的成功回执在订单侧看到取消状态后,也不得把订单改回 RESERVED。

对于“库存已经成功,但成功回执还没到”的情况,取消命令仍能通过预占业务键找到并释放资源。释放回执丢失时重复执行 Cancel 返回相同结果。订单最终显示 CANCELLED 应以协议中约定的资源释放确认或可解释的取消完成条件为准,不能在还有冻结资源时悄悄丢弃恢复任务。

已发货订单的取消属于不同流程:可能需要拦截、退货或退款,而不是直接释放已出库库存。状态机必须拒绝把履约后取消当成预占阶段取消。业务动作的可逆性决定协议,不是一个通用 cancel 方法可以包办所有阶段。

6. 故障验收要同时证明安全性与恢复能力

在提交订单事务前失败,应看不到订单和 Outbox;提交后、发布前失败,重启扫描应继续发布。发送成功但标记前失败,允许物理消息重复,预占流水必须只有一条。库存事务提交前失败,Inbox 和库存均回滚;提交后确认前失败,重投返回原结果。不能把“日志没有异常”当作上述断言的替代。

进一步注入取消先到、预占先到、结果乱序、租约过期、旧工作者恢复、CDC 旧快照覆盖和删除后旧事件回放。每次都记录注入点、持久化前后状态、恢复动作与最终不变量。真实隔离环境还应测试进程强杀、断网、Broker 重平衡、数据库死锁和日志保留不足,但本任务只提供离线协议模型,未连接这些服务。

验收中的活性要带前提:在依赖恢复且调度持续运行的条件下,未完成任务能收敛;若每次都在同一位置强制崩溃,当然不能要求成功。恢复上界需要根据积压量和剩余处理能力估算,例如积压十万条、恢复后净消化每秒两千条,理论排空至少五十秒,还未计算热点和失败重试。

7. 可执行实验覆盖与未覆盖范围

实验源码〔本地文件〕使用两个独立 SQLite 文件表示订单侧和库存侧,用列表表示假定可重投的 Broker,用显式异常表示应用故障点。TCC、租约与 CDC 是串行内存状态机。它没有完整实现上面的订单取消编排、多 SKU 事务、Saga 协调器或生产鉴权;这些内容是设计与答辩要求,不冒充已完成的集成系统。

准确运行命令为:

python3 -B -m unittest discover -s distributed-course/labs -p 'test_*.py' -v

本次实际运行 18 个测试全部通过。两个反例测试特意复现错误:提前确认导致未执行工作消失,缺少 fencing 导致旧持有者覆盖新结果。它们通过意味着反例成立。其余用例覆盖持久化恢复、幂等、租户键隔离、数量校验、TCC 终态和 CDC 版本保护,详细对应关系见 实验说明。

8. 性能与发布不能破坏协议

提速应先定位瓶颈:是 Outbox 扫描慢、消息分组热点、消费者等待数据库,还是通知服务拖慢业务线程。不同订单并行、同订单有序;限制单租户在途数量,避免大商家占满处理能力。重试流量与新流量共享总预算,恢复任务有保底配额,不能无限扩线程把瓶颈推给连接池。

灰度发布要让新旧消费者都理解过渡期事件。先部署能兼容新字段和新状态的读方,再逐步启用写方;保留旧事件处理能力直到回放窗口结束。回滚代码不等于回滚已发布事件和已保存状态。上线后观察新状态分布、最老任务年龄、幂等冲突、租户异常与对账差异,发现协议不兼容时停止新状态生产并保留恢复证据。

本教材线上发布只打包教程和实验,不附业务源码。章节中的 ../项目/...#L行号 链接仅供有本地工作区权限的读者对照;线上阅读站不应通过打包兄弟仓库来修复这些链接,也不应暴露配置文件或业务环境信息。

9. 练习与参考答案

练习一: 产品要求提交后立即显示成功,库存结果异步返回,应怎样解释接口?

答案: 可以显示“订单已受理,库存确认中”,但不能把受理等同预占成功。响应返回可查询订单标识,页面能恢复轮询或订阅;只有确定库存结果后才展示对应业务终态。

练习二: 发送两次、扣减一次,是失败验收吗?

答案: 在至少一次投递设计下是允许且应被测试的恢复过程。需要确认事件身份相同、幂等账本存在、结果一致,并监控重复率是否异常升高。不同业务事件误用相同键则是冲突,应拒绝而非静默合并。

练习三: 18 个测试通过后能宣布订单链路可上线吗?

答案: 不能。它们证明所列协议模型在指定顺序下满足断言,不证明真实客户端配置、数据库并发、Broker 持久化、权限或业务调用链。上线验收需要隔离环境集成测试、容量验证、恢复演练与对账;本次交付没有执行这些活动。

官方参考

原始文档 · distributed-course/开发陷阱深化.md

分布式开发陷阱深化:从实际 ACK 找回业务责任

本篇是第二轮源码审阅,先读了本课程第 02、03、07 章,再沿监听入口、队列、消息对象与下游返回值继续核对。已有正文讲过至少一次、Inbox、Outbox;这里不重复定义,而是回答一个更难的问题:在某个失败时刻,哪一层还承认自己欠着这件工作? 对前端开发者而言,MQ 返回 SUCCESS 类似接口返回“已处理”,但浏览器提示、数据库提交、消费位点推进并不是一个动作。下面的时间线都是条件推演,不是生产事故记录。

全文使用四种标签:源码事实是本地可定位实现;条件风险必须列出触发前提;改进设计尚未写入业务代码;验证区分已完成静态核对与待执行故障注入。没有读取环境连接配置,没有启动消息客户端,也没有确认任何线上版本或消费位点。

一、路由异常被 catch 后,ACK 具体承认了什么

源码事实。 MessagePushConsumerListener.java#L32〔本地文件〕 接收列表,逐条处理。第 36 行〔本地文件〕 的 JSON 解析在 try 外;第 38 行路由调用在 try 内;第 39—40 行捕获 Exception;第 43 行〔本地文件〕 返回顺序消费 SUCCESS。因此“异常会让 MQ 重试”和“所有异常都被吞掉”都过于笼统。解析失败会逃出这个方法;路由抛出的 Exception 会被记录后继续处理下一条。Error 也不在该 catch 的类型范围内。

失败时间线 A: t0 收到 A、B、C;t1 A 的路由调用返回;t2 B 路由抛出异常,catch 结束;t3 C 路由调用返回;t4 返回 SUCCESS。若客户端把本批处理为成功,B 不会因为这次已被吞掉的异常进入正常失败重投链。不能据此说 Broker 物理删除了 B;准确说法是应用对该批次不再提出失败重试要求。

条件风险。 假如 SSE 是唯一通知渠道,且没有通知账本、页面补查或其他恢复源,B 的业务通知可能丢失。若 SSE 只是“有更新请刷新”的提示,丢一次可能属于已接受的产品语义。A 的 route 返回也不证明浏览器已经收到并展示:本次没有追踪客户端确认协议。改成遇错直接抛出后,A 可能重投;不能只解决 B 而忽略 A 的重复副作用。

改进设计。 将业务完成与通知送达拆开:完成事件写入可查询任务,页面按任务 ID 查询权威结果;通知消费可独立重试。必达通知应先形成持久通知记录,送达策略再明确“服务端发送”“通道接受”“客户端确认”分别是哪种状态。若只是刷新提示,明确允许合并、丢弃并通过刷新修复,避免用相同 SUCCESS 掩盖两种产品承诺。

验证。 已核对方法边界。待执行使用假的 route 处理 A/B/C:B 抛 Exception 时断言方法返回 SUCCESS;JSON 解析失败时断言不会到达返回语句;再用隔离客户端确认批次及重投行为。框架将返回值如何变成位点更新,须按实际客户端核对,不能把 ONS、4.x 原生接口、5.x API 的术语混用。RocketMQ 4.9.8 官方实现 的 processConsumeResult 在 autoCommit 分支把 SUCCESS 对应到队列提交,失败分支则结合重试次数处理;这里用它解释机制,不宣称项目运行此版本。

二、成功入队之后,下游失败已经无法改变上一次返回

源码事实。 RocketMqOrderedTradeQueueMessageListener.java#L57〔本地文件〕 解析消息、设置 msgId、调用 put,然后第 63 行立即返回 SUCCESS;异常才返回 SUSPEND_CURRENT_QUEUE_A_MOMENT。第 91 行〔本地文件〕 后台取批次,第 98—103 行并发提交业务处理。第 118 行〔本地文件〕 的开关为 false 时直接 return,业务异常在第 125 行捕获,仅记录日志。外层 lambda 随后仍可返回整数 1;这个 1 不能当作业务提交证明。

失败时间线 B: t0 消息进入本地队列;t1 监听器返回 SUCCESS;t2 客户端推进消费进度;t3 进程退出,后台尚未取到该任务。若没有另外的持久接管或上游补拉,队列任务随进程消失,正常消费进度也不再指向它。另一个变体是 t3 后台调用失败后被 catch;监听器早已返回,后来即使增加日志也无法反向撤销那个成功状态。

条件风险。 “开关关闭”容易被理解为暂停:运营预期打开后继续,实际这个分支是在已接管的消息上结束处理。源码只证明该局部分支;消息是否能通过定时补偿恢复仍未知。必须在产品说明中区分“停止接收”“可靠接收后延后处理”和“忽略并确认”。不要把配置开关的名字当语义。

改进设计。 需要异步卸载时,在 ACK 前将任务写入本地可靠账本,包含业务键、负载摘要、状态和下次执行时间;后台按租约领取。ACK 后未完成的工作由账本负责。暂停只影响领取,不删除待办。确实要忽略的事件需记录明确的业务理由和计数,不能和成功落库混合统计。这个设计仍要求业务变更与消费记录原子提交,并不因多一张表就自动可靠。

验证。 已读到早返回和后台 catch;未运行进程崩溃实验。待执行验收点应分别放在“账本提交前”“提交后 ACK 前”“ACK 后 worker 前”“业务提交后状态回写前”,检查待办可恢复、业务最多生效一次、租约接管不覆盖新结果。只在监听函数入口抛一次异常,覆盖不了这些责任交接点。

三、重试键、去重键和事件键,不应由一个 equals 包办

源码事实。 UniqueBlockingQueue.java#L33〔本地文件〕 先 putIfAbsent 登记,再进行阻塞 put;重复时返回 false。上面的监听器没有检查这个布尔返回值。队列第 52 行〔本地文件〕 在取出批次时删除 distinctMap 标记。继续追到实际导入的 TradeMessage.java#L105〔本地文件〕:equals/hashCode 使用 sellerId、platform、tid、messageType、memberId,不包含 content、msgCreated、msgId。这比笼统说“内存去重不可靠”更具体。

失败时间线 C: t0 同一订单的内容 P1 入队;t1 同类型、不同内容 P2 到达,相等字段完全一样;t2 put 返回 false,监听器仍 SUCCESS;t3 后台只处理 P1。如果事件表达不可遗漏的增量,P2 的独立效果可能丢失。若两条只是触发一次“重新拉取最新订单”的通知,合并可能合理,但必须证明下游拉取覆盖 P2,不能从类名 Unique 得到这个结论。

失败时间线 D: t0 生产线程成功登记 key=K;t1 队列已满,put 阻塞;t2 线程被中断,元素未入队;t3 监听器返回暂停重试;t4 相同元素重投,map 已有 K,put 返回 false;t5 返回 SUCCESS,但队列从未持有 K。这个推演要求中断发生在登记后、实际插入前,且重试对象相等、map 未被其他路径清除。它是可注入的窗口,不是已发生事件。

改进设计。 分开四类身份:业务事件键 (tenant,eventId) 标识不可更换的事实;聚合顺序键 (tenant,orderId) 约束因果;重试账本键 (consumerGroup,tenant,eventId,handlerVersion) 记录尝试与错误;物理 msgId 仅关联一次消息传输。handlerVersion 是否属于重试键取决于迁移策略,但不能因此绕过稳定业务幂等键。不同处理器共享一个失败次数,会让一个消费者耗尽另一消费者的预算;每次重试换业务 eventId,则让幂等形同虚设。

队列若继续采用先登记再入队,失败路径需要安全撤销本次登记,并防止并发新拥有者被误删;更好的聚合方案应说明“保留最新值”或“触发重新读取”的语义及负载上界。参数摘要冲突须隔离,不能把不同内容直接当重复成功。去重 TTL 要覆盖可重放范围;重试次数 TTL 到期不能把旧毒消息变成永远的新事件。

验证。 已核对相等性和返回值。待执行:两个相等字段相同而 content 不同的对象;填满队列后在 put 阻塞点中断;同键对象取出但业务未完成时再次投递。断言应分别检查队列内容、map 标记、返回值与业务效果,不能只看 put 调用了几次。重试账本是建议方案,本次没有发现或建立一个可据此宣称全链路幂等的现成账本。

四、顺序入口为什么仍能乱序,毒消息如何隔离才不跳过业务

源码事实。 上述后台对一批 TradeMessage 并发调用 extracted;因此即使入口按队列顺序收到,完成顺序仍取决于下游耗时。注册点 TradeONSDistinctRocketMqConsumer.java#L56〔本地文件〕 还只传入 msgList.get(0)。本次未确认有效批次大小;不能断言默认就丢批次,但当一次回调包含多条时,这个包装层并没有遍历其余元素。

另一条直接处理路径 OnsOptionLogMessageListener.java#L112〔本地文件〕 在开关关闭时返回 SUCCESS,第 133 行业务调用正常返回后才成功,限流或异常返回暂停。它与内存队列版的可靠性边界不同,不能根据相近类名给出统一结论。

失败时间线 E: t0 v1 与 v2 顺序进入本地队列;t1 worker1 执行 v1,远程请求变慢;t2 worker2 先提交 v2;t3 v1 恢复并覆盖 v2。这要求下游没有版本条件保护;本次没有证明所有下游写入均无保护。若改为严格串行,另一种失败是 t1 的格式错误永不改变,反复暂停导致后续正常事件饥饿。无限重试保证不了顺序业务最终完成。

改进设计。 按聚合键串行,或用业务版本条件更新。完整快照可以拒绝过旧版本;“库存加二”这样的增量不能随意跳版本。毒消息先持久隔离再确认,并将该聚合标为需要修复;其他聚合可继续,同一聚合的后续事件应等待缺口修复、补拉权威快照,或按明确可交换规则执行。隔离后直接继续所有后续消息,可能把“队列不堵”换成“订单状态错乱”。修复重放沿用原事件身份;真正的业务修正创建新事件并关联被修正事件。

验证。 已静态核对异步扇出、单元素转交和失败返回。待执行用两个可控闸门固定 v2 先提交,检查版本防线;用一条永久坏消息和两个不同订单,检查坏订单被隔离、正常订单能前进、同订单后续事件不跨越不可丢的增量。批次验收应主动传入两条,不能只沿用单条样本。RocketMQ 官方消费实践 用于核对接口;本章未把某个默认批量参数当作永久契约。

五、带答案的审查练习

题一: 监听日志出现异常后,又看到消费成功指标增加,能否认定指标有 bug?答案: 不能。路由异常已被 catch,客户端确实拿到 SUCCESS。先标出异常边界,再分别定义“消费回调成功”“业务完成”“通知确认”指标。用一个指标表达三层成功,才是可观测性设计的问题。

题二: 把队列 map 换成 Redis 是否修复时间线 D?答案: 不能。先登记后入队仍是两次写,Redis 标记甚至可能在进程重启后继续阻止恢复。需要原子接管或能够可靠回收的状态机;共享存储仅改变存活时间,不会消除窗口。

题三: 内容 P2 被合并后是否必须重放?答案: 先确认事件语义。若是增量,应恢复遗漏效果并保留身份;若是拉取触发器,先证明一次最新快照读取已覆盖 P2。不能为追求发送次数相等盲目重放库存命令。

题四: 毒消息转隔离成功后就关闭事故吗?答案: 还不够。需要责任人、最老隔离年龄、修复版本、相关订单缺口、重放审计和最终对账结果。技术上 ACK 成功仅完成责任转移,隔离账本仍欠业务工作。

闭环边界。 本篇提供已读源码与故障验收设计,未运行真实 MQ/Redis/数据库实验,也未改业务代码。取消与许可的可执行模型见 高并发深化,日志可信度和发布后的恢复责任见 运维深化;这些章节不能代替消息客户端集成验证。

原始文档 · distributed-course/labs/README.md

无外部服务的分布式故障模型

返回课程目录 · 综合实战 · 实验源码〔本地文件〕

这只是协议模型,不是 Broker 验证。 不启动或连接 RocketMQ、ONS、Redis、Dubbo、MySQL、DTS 或任何业务服务,不读取环境配置。只需 Python 3.8+ 的标准库 unittest、sqlite3 等,无需安装依赖。

运行

在 /Users/try/work/admin 执行:

python3 -B -m unittest discover -s distributed-course/labs -p 'test_*.py' -v

也可在任意目录执行:

python3 -B /Users/try/work/admin/distributed-course/labs/test_fault_model.py

每个用例在本 labs 目录创建独立临时子目录,分别保存订单与库存 SQLite 文件,结束后自动清理。-B 禁止生成字节码缓存。测试只使用虚构租户和订单,不包含业务配置。

模型如何表达故障

订单与 Outbox 同一 SQLite 事务;库存与 Inbox 在另一 SQLite 文件的同一事务,体现两个独立提交边界。Crash 异常注入指定窗口,未提交事务回滚;restart() 关闭并重新打开连接,检验已提交记录可重新读取。这是受控异常与重新打开文件,不是杀进程、断电或磁盘损坏测试。

BrokerModel 只是 Python 列表,假设它在应用重启期间仍保存已发送消息。发送后、标记 SENT 前失败会再次发送;提交消费事务后、确认前失败会再次调用消费。测试观察物理投递两次但库存只减少一次。模型没有复制、落盘确认、队列分配、重平衡、真实消费超时或死信调度。

LeaseModel 使用整数逻辑时间,假定授权方提供不回退的递增 token;FencedResource 假定写入与 token 比较原子。TccModel 与 Projection 是内存中的串行状态机,不验证协调器持久化、并发竞争、认证或分片。库存模型只有每租户一个库存数量,不包含多 SKU、仓库、确认出库及完整订单 Saga。

验收映射

故障或约束 核心预期 对应用例
订单写入后、Outbox 写入前失败 两者均回滚 test_order_and_outbox_rollback_together
本地提交后应用重启 待发事件仍可执行 test_committed_outbox_survives_restart
发送后标记前失败 重复投递,业务仅生效一次 test_send_then_crash_duplicates_delivery_not_effect
消费事务提交前失败 Inbox 与库存一起回滚 test_inbox_and_effect_rollback_together
消费提交后确认丢失 重投不重复扣减 test_ack_loss_after_commit_does_not_rededuct
同键不同参数、跨租户同号 冲突可见、租户隔离 payload 与 tenants 两个用例
库存不足、负数量 确定拒绝、不改变库存 stock 与 negative 两个用例
提前确认、无 fencing 明确复现错误结果 两个 test_counterexample_* 用例
旧锁持有者恢复 新 token 生效后拒绝旧写 test_fencing_rejects_resumed_old_owner
空回滚、重复取消、重复确认 不悬挂、不多释放、终态不冲突 三个 test_tcc_* 用例
乱序快照、删除、同版冲突 不回盖、不复活、冲突可见 三个 test_cdc_* 用例

反例测试通过,表示错误结果被成功复现,不是表示错误设计安全。请把断言读出来:提前确认后库存完全没变;没有 fencing 时旧结果覆盖了新结果。

练习与答案

  1. 把消费提交放到 Inbox 提交之后会怎样?答案:存在 Inbox 已记、库存未变的窗口,重投被错误跳过。请在副本中实验,勿修改业务仓库。
  2. 把所有 eventId 每次重试都随机化会怎样?答案:Inbox 无法识别同一事件,重复发送可能再次扣减;生产级还需要永久业务流水唯一键。
  3. 这些测试能证明 MySQL 并发扣库存安全吗?答案:不能。它们使用串行 SQLite 操作,未覆盖 MySQL 隔离级别、死锁、网络与多进程竞争。
  4. 能用整数版本处理“加 2、再减 1”的任意乱序吗?答案:不能。Projection 接收完整快照;增量事件需要不同的连续性或去重协议。

实际运行记录

2026-11-11,在课程工作区实际执行上述 unittest discover 命令,退出码 0:

Ran 18 tests in 0.046s
OK

耗时仅为本机本次运行值,不是吞吐基准;测试数量为 18,包含两个成功复现错误的反例用例。

官方参考

学习阶段 05

高并发与性能

工作量、热点、背压与容量验证

原始文档 · high-concurrency-course/README.md

ERP高并发与性能工程课程

新增开发陷阱深化:配额作用域、公平调度、取消与资源退出、许可漏还/多还、静默拒绝和关闭恢复;含13项可执行模型测试。

本模块承接数据库与Spring,强调从业务正确性到资源预算,再到稳定恢复。示例结合实际线程池、库存与广告同步代码;设计方案与已存在实现明确区分。

  1. 00 从业务不变量到容量模型
  2. 01 执行器背压与结构化任务边界
  3. 02 热点缓存与多租户流量治理
  4. 03 库存并发幂等与数据库正确性
  5. 04 海量数据流水线与性能编码
  6. 05 压测基准尾延迟与故障验收
  7. 06 高并发综合实战与编码检查表

独立实验 / 统一彩色阅读站 / 分布式课程 / 运维课程

先运行Spring的线程池实验,再运行本模块确定性协议模型。模型验证反例与不变量,不代表生产容量、真实数据库锁或消息服务已验证。本次不修改业务代码、不启动ERP、不连接业务服务。

原始文档 · high-concurrency-course/00-从业务不变量到容量模型.md

00 从业务不变量到容量模型

高并发不是线程很多,而是在并发请求和局部故障下,仍然满足正确性、延迟和资源约束。本课程承接Spring的线程池与事务章节,进一步把单点机制组合成容量、准入、热点和恢复协议。读者已经熟悉前端异步,但后端的Promise背后有真实线程、数据库连接、行锁、内存与远端额度。

1. 先写不能错什么

ERP的首要约束通常不是“每秒十万请求”,而是库存不能错误扣减、同一付款不能重复入账、租户不能互相读数据、任务接受后不能无声消失。吞吐只能在这些约束成立时讨论。如果通过关闭校验、去掉租户过滤或静默丢任务获得更高QPS,那是改变业务,不是性能优化。

用一个库存命令举例:输入包含可信租户、操作键、SKU、数量;结果可能成功、库存不足、幂等重放或结果未知。技术超时不等于业务失败,重复请求也不一定是新业务。系统必须为每个状态设计查询和恢复路径。

2. 到达率、完成率与在途数

到达率表示每秒进来多少任务,完成率表示每秒最终完成多少。稳定状态下二者长期接近;到达持续大于完成,差额会变成积压或拒绝。QPS不描述任务成本:一个字典查询和一个全历史报表都是一次请求,数据库工作量可能相差百万倍。

Little定律在稳定平均条件下给出在途量=吞吐率×平均停留时间。教学例子:每秒200个任务,平均停留0.5秒,平均在途约100。它不是线程数公式:在途可能包含入口、队列、连接等待和执行;p99也不能直接替代平均值。

端到端延迟 = 接入等待 + 执行器排队 + 获取连接等待
             + SQL/锁等待 + 业务CPU + 远端等待 + 输出

存在并行时应按关键路径分析,不能将重叠阶段重复相加。批处理还需要区分单条和单批指标,否则提高批量后“每秒任务数变少”可能掩盖实际行吞吐上升。

3. 把所有池画在同一张图里

HTTP线程池→业务执行器→数据库连接池→数据库CPU/IO/锁,是串联资源。RPC客户端和缓存也可能共享内部执行器。如果每实例允许20条导出连接,部署10实例就是最多200条,还没算HTTP和定时任务。把每个模块单独调到看起来合理,集群合计仍可能超载。

项目AsyncTemplateConfig〔本地文件〕按CPU数量确定线程数,并使用容量108的队列。源码只能证明参数形态,不能证明CPU倍数与下游容量吻合。项目ScmDistributorItemThreadConfig〔本地文件〕又有另一个池,不能只统计其中之一。

建立资源表:每类请求的SQL次数、单次连接占用、远端次数、在途对象字节、最大并发、失败重试上限。把后台同步、导出、消息消费也列进去,它们不会因为不是HTTP就不消耗数据库。

4. 从复杂度到真实工作量

两个嵌套循环对1000订单和1000明细比较,可能做百万次匹配;按订单ID构建Map后可接近线性遍历,但Map增加内存且要处理重复键。减少算法复杂度比把原循环分给更多线程更可靠。

数据库N+1同理:每条订单查明细造成N次网络往返,先按页取订单,再批量查该页明细,可减少调用次数。不能因此把整个租户所有明细读进内存;优化必须同时约束输入规模。

Amdahl思路提醒我们:若大部分时间花在串行热点行锁,再优化并行序列化收益有限。先测占比,再选择改动;测量必须包含失败请求和排队,不能只挑成功样本。

5. 容量拐点与安全余量

低负载增加并发可能提高吞吐;接近饱和后,等待增长而吞吐趋平;继续增加并发可能让锁争用、上下文切换与GC把吞吐拖低。这就是为什么最大线程数、最大连接数通常不是越大越好。

容量试验应逐级提升固定的到达负载,并持续观察成功吞吐、尾延迟、队列最老年龄与错误。选择长期运行点时保留故障、热点、发布与突发余量。这里不提供可直接复制的生产线程数,参数必须由依赖容量和业务SLO共同决定。

6. 成本预算也要能执行

纸面约定“每租户同时两份导出”若没有并发安全的准入,就可能被同时到达的十个请求穿透。预算需要明确执行点:网关速率、应用信号量、调度并发、数据库约束或资源配额。全局限制与本地限制的语义不同,扩容后本地上限会相加。

预算还需要归还协议:异常和取消要释放许可;进程崩溃后持久任务依赖租约回收;已过期的旧worker不能无限占用外部资源。下一章深入执行器,分布式课程解释租约与fencing。

7. 练习与答案

  1. CPU低但连接池满,应该加线程吗?先查连接持有时间、慢SQL和锁等待;CPU闲可能是下游饱和,不是线程太少。
  2. QPS增长而用户成功数下降是否优化成功?不是,应计算满足正确性和SLO的有效吞吐。
  3. 批大小1000是否意味着最多1000行内存?不是,还要乘并发、预取页数、对象副本和队列捕获对象。
  4. 一台机器测得容量后如何推集群?先识别共享数据库、热点键与全局限额,不能简单乘实例数。

延伸:Spring容量诊断、数据库连接池。本章公式是分析模型,示例数字不是项目运行数据。

原始文档 · high-concurrency-course/01-执行器背压与结构化任务边界.md

01 执行器、背压与结构化任务边界

图解 · 可横向查看
线程池决策:core → 队列 → max → 拒绝worker不足core时创建,否则先尝试队列,队列拒绝后再尝试扩容,最后执行拒绝策略。 线程池决策:core → 队列 → max → 拒绝收到任务execute / submitworker 少于 core?不是先扩到 max创建 worker 执行接收失败仍需处理队列接受成功?有界容量 / 已关闭状态排队等待等待时间与对象内存有成本还能创建 worker?少于 max 且创建成功扩容执行不是数据库自动扩容拒绝处理显式失败 / 持久待调度是否是否是否无界队列通常先持续排队;静默丢弃可能让submit返回的Future永不完成。这是接收决策简图,关闭状态竞争与创建失败还需参考JDK实现。
core、队列、max与拒绝策略的执行器决策

图示为教学简化,需结合下文的适用条件、故障窗口和项目证据阅读。

线程池已经在Spring课程解释过原理。本章把它提升到任务协议:谁提交、何时承诺接受、失败由谁观察、超时如何取消、进程结束后谁恢复。只有这些问题有答案,异步才是可维护的工程能力。

1. 看懂两种真实配置

SCM配置〔本地文件〕使用无容量参数LinkedBlockingQueue、core5/max10。通常超过core的请求先排队,无界队列使max难以发挥预想的扩容作用。它的static字段还意味着生命周期不只由容器实例决定,要继续找关闭责任。

Index配置〔本地文件〕采用有界ArrayBlockingQueue和DiscardPolicy。队列有界保护内存,但静默拒绝可能让业务不知道任务没有运行。实际业务是否补偿取决于AsyncTemplate和包装器,局部源码不足以确认事故。

这两个例子说明:无界队列和有界丢弃都不是默认正确答案。前者可能用内存隐藏过载,后者可能用数据丢失隐藏过载。正确答案应是有限接收、可观察拒绝和可恢复状态。

2. 明确任务的四个时刻

请求到达 → 可靠记录已接受 → worker开始 → 结果已提交

内存队列入队只证明当前进程持有一个对象。若接口返回“导出已创建”,应该说明任务是否已持久化;若需要重启后继续,就应先创建持久任务记录,再由调度器按预算取任务。

拒绝发生时,不要把记录留在RUNNING。任务可以保持PENDING并稍后重试,也可以明确FAILED并反馈用户;需要通过条件状态转换避免并发提交者误更新其他执行尝试。

3. 实现有限并发的最小结构

以下为Java8风格结构片段,省略业务模型;它只体现本进程准入,不保证持久可靠性。

public Future<Result> submit(Command command) {
    if (!permits.tryAcquire()) {
        throw new BusyException();
    }
    try {
        return executor.submit(() -> {
            try {
                return worker.execute(command);
            } finally {
                permits.release();
            }
        });
    } catch (RejectedExecutionException failure) {
        permits.release();
        throw failure;
    }
}

这段仍有必须设计的取消边界:任务入队后尚未开始就被cancel,Runnable的finally可能根本不会执行,许可便可能泄漏。反过来,在FutureTask.done中无条件释放也不完整:运行中的Future可以先进入取消终态,但任务体仍占用连接或远端调用资源。一次性标记只防重复释放,不能防提前释放。

生产方案应明确许可保护的资源,并让“取消未开始任务”和“取得开始权”原子竞争。确认任务不会再启动时可归还;已开始的任务必须等受保护资源真正退出后归还。明确拒绝另行归还,静默拒绝则不能依赖异常回调。完整状态表、反例和可执行模型见取消与资源所有权深化。以上片段仅用于分析正常路径,不应作为支持取消的完整提交组件直接复用。

更简单的持久调度方案是仅在worker真的可用时抢任务,让执行器容量和抢占批量匹配;仍需处理抢占成功但进程崩溃的租约恢复。不要在一个短片段里暗示已解决全部可靠性。

4. 队列是延迟与内存预算

如果4个worker每个平均每秒完成5任务,持续服务率约20。容量100的队列在近似均匀情况下已意味着数秒等待,长尾会更严重。队列不能根据“想缓存多少请求”随意扩大,应从最大允许等待和任务内存推导。

任务闭包尽量只保存ID、必要不可变参数和截止时间。不要捕获ServletRequest、整个查询结果、用户完整对象或数据库连接。队列里的对象会延长引用链生存期,OOM时最值得查的往往就是这些引用链。

5. Future、异常与取消

execute与submit的异常观察方式不同。submit一般把异常保存在Future中,没人get或注册完成处理,就可能看不到业务失败。void的Async也需要明确异常处理器与任务状态落库。

Future等待超时只是调用者不再等,数据库可能继续执行。取消通常依赖协作中断,驱动与远端未必停止。结果提交与取消可能竞争,需要业务状态机决定最终状态,而不是看cancel返回值。

固定池里父任务提交子任务到同池后join,所有worker可能都被父任务占满,子任务永远排队。把任务依赖组合成非阻塞回调或在上层协调,优于盲目增加线程数。不要把公共ForkJoinPool当阻塞数据库工作的无限备用池。

6. 结构化思路,不强行升级运行时

结构化任务边界的思想是:子任务属于一个明确作用域,父任务负责等待、取消和错误汇总,避免后台工作失去主人。可以在Java8用清晰的Future集合、截止时间和finally实现部分约束,不必为了概念立即升级到预览API。

虚拟线程降低某些阻塞场景的线程成本,但不会增加数据库连接、热点行吞吐或远端限额。即使未来升级,也仍需限并发、上下文隔离、超时与可观察性;本目录以Java8年代项目为主,不能直接复制新版API。

7. 隔离与公平

库存、报表、外部同步可以使用不同执行器避免相互挤占worker,但共享连接池仍会把故障传播回来。隔离应配合资源预算,不能为每个模块新建大连接池,使数据库总连接数失控。

单个租户海量提交任务时,FIFO可能让其他租户长时间等待。可以采用每租户小队列、轮询调度与全局上限,并给长期任务分批让出执行机会。公平不是简单地把所有队列长度设成一样,应该考虑任务成本与业务优先级。

8. 实验和答案

先运行Spring执行器实验,验证无界排队和DiscardPolicy的基础机制;再运行本课程labs模型,观察到达率超过服务率后积压与拒绝。

一:把CallerRuns作为通用背压安全吗?它可能阻塞HTTP或调度线程,关闭状态下也有丢弃语义,必须检查调用者能否承受。 二:finally释放许可为什么仍会泄漏?排队取消的任务可能从未进入finally,需要覆盖取消和拒绝。 三:有两个线程池就故障隔离了吗?没有,还需审查共享数据库、内存、缓存和远端额度。

参考:JDK8 ThreadPoolExecutor、FutureTask。

原始文档 · high-concurrency-course/02-热点缓存与多租户流量治理.md

02 热点缓存与多租户流量治理

缓存不是给数据库外面加一个Map就结束。高并发下真正困难的是同一个时刻很多请求做同一件事,以及某些请求比其他请求昂贵得多。本章讨论热点合并、缓存失效、限速与并发限制,强调所有优化必须保留权限和数据语义。

1. 从真实LocalCache理解击穿

LocalCache.get〔本地文件〕依次getIfPresent、调用supplier、put。这几个操作分别可以线程安全,但组合不是每key只有一个loader。热点过期后,100个请求可能同时发现缺失,分别查数据库。

同文件初始化〔本地文件〕调用expireAfterWrite,注释却描述访问时间。可确认的是可执行方法语义与注释不同;不能据此推断线上一定发生缓存事故。频繁读取不会按expireAfterAccess语义延长它的有效期。

2. Singleflight究竟合并什么

同进程按key合并进行中的加载,让其余请求等待同一个Future,可以减少重复回源。需要处理loader异常后清除进行中标记、等待者超时、key数量上界和递归加载死锁。不能把一个失败Future永远留在Map里,也不能让等待者无限等待。

这类合并通常只覆盖当前JVM。十个实例仍可能同时产生十次回源,未必需要为了降到一次就引入分布式锁:如果数据库承受十次且协议更简单,本地合并就可能是合理取舍。关键看热点强度和新鲜度要求。

同步缓存加载也会让许多请求共享一次慢加载的延迟。可用过期前刷新、有限旧值服务或快速失败改善体验,但库存与权限不应默认允许旧数据。必须按业务分类定义最大可接受陈旧度。

3. TTL抖动与雪崩

批量写入相同TTL可能导致同时过期。加入受限随机抖动可以摊开失效时间,但不解决单个超级热点,也不解决Redis故障时全量回源。缓存不可用时应有独立回源并发预算,避免把缓存故障升级成数据库故障。

负缓存可减少不存在资源的穿透,但要有短期界限、容量限制与租户隔离。新资源创建后仍命中不存在缓存,属于一致性代价。布隆过滤器可能有误判且需要维护删除/重建语义,不能用它作为权限判断或精确存在性依据。

4. 写入与失效的竞态

读线程读取数据库旧值
写线程提交新值并删除缓存
读线程把旧值放回缓存

这条时间线说明“先更新数据库再删缓存”仍可能出现旧值回填。延迟双删可以降低某些窗口概率,但没有对所有调度和故障给出严格证明。可以引入版本、generation或有序事件处理,拒绝旧版本回填;版本更新自身也要可靠,多个资源之间仍有失败窗口。

对于普通看板可定义最终一致与修复周期;对权限和库存关键判断应回到权威写入边界验证。缓存能提速读路径,却不应成为唯一业务账本。

5. 速率限制与并发限制

令牌桶允许有限突发,每个请求消耗token,按时间恢复。并发信号量限制同时执行数量。依赖从20ms变成2秒,即使QPS不变,在途资源也可能增长百倍,因此只有速率限制通常不够。

本地令牌桶不等于全局限流;实例数扩容会扩大合计额度。Redis集中协调又增加了新的依赖和延迟,需要说明Redis故障时是拒绝、保守本地额度还是放行。金融和库存写通常不应默默无限放行。

可按成本加权,例如大报表消耗更多预算,但成本估算不准时也要有运行中硬限制:最大时间范围、最大返回行、批次截止时间和取消机制。让前端禁用按钮只能减少误点,不能替代服务器配额。

6. 租户隔离与热key拆分

缓存键至少包含必要租户和业务维度。若缓存完整响应,还要考虑角色字段可见性、语言、排序、筛选条件和数据版本。错误复用响应可能同时造成数据不正确和越权。

热key拆分适合可合并计数或只读复制,不适合未经协议设计的库存余额。把一个库存key随机拆成多个key会引入额度分配、超卖和回收问题。应先理解业务一致性,再考虑散列分摊。

公平调度可以结合租户并发上限、全局预算与任务优先级。不要把租户ID直接作为无限高基数指标标签;可在受控日志中记录,指标按业务等级或热点集合聚合。

7. 如何做故障验收

同时过期、loader异常、Redis不可用、新旧版本乱序、租户切换和权限撤销都要测试。关注数据库回源率和排队,而不只看缓存命中率:99%命中率仍可能因剩下1%的超重查询压垮数据库。

练习一:Caffeine线程安全为什么组合get→load→put仍击穿?线程安全覆盖单次操作,不自动合并跨操作协议。 练习二:TTL抖动能防止Redis全挂后的雪崩吗?不能,还要控制回源和明确降级。 练习三:权限缓存设一分钟是否意味着立即撤权?不是,必须声明传播时限并为高风险操作提供权威校验。

继续阅读数据库缓存一致性、Spring可靠事件。缓存提供者具体API和同步行为应按项目依赖版本核对,不能把某库特性当所有实现通用。

原始文档 · high-concurrency-course/03-库存并发幂等与数据库正确性.md

03 库存并发、幂等与数据库正确性

库存是检验后端工程思维的好例子:一个减法跨越重试、数据库事务、多实例、缓存和外部同步后,就不再只是计算。本章从本地条件更新建立最小正确性,再分析项目锁与批量事务。不要将本章SQL直接跑在业务表上,所有表名均为教学设计。

1. 先查后写为什么会超卖

A读可用量10;B读可用量10
A判断可买8;B判断可买8
A写入结果;B写入结果

如果把新库存直接写成旧值减数量,可能发生丢更新;如果两次都执行增量扣减但没有非负条件,可能得到负库存。事务只能按其隔离与锁语义执行,普通读后写不自动串行化这个判断。

一个可讨论的最小写法是让数据库同时检查并更新:

UPDATE lab_stock
SET available = available - ?, version = version + 1
WHERE tenant_id = ? AND sku_id = ? AND available >= ?;

数量必须正数、两个数量参数一致,租户来自可信上下文;检查影响行数是否为1。还需要区分记录不存在和库存不足的产品语义,但不能为了详细错误而破坏写入原子判断。

2. 原子扣减不等于幂等

扣减已提交,响应丢失,客户端重试同一订单。如果没有业务操作唯一键,第二次扣减也能完全原子地成功。必须将“这个操作是否处理过”与库存变化放进同一数据库事务。

CREATE TABLE lab_stock_operation (
  tenant_id BIGINT NOT NULL,
  operation_key VARCHAR(80) NOT NULL,
  request_hash CHAR(64) NOT NULL,
  outcome VARCHAR(24) NOT NULL,
  PRIMARY KEY (tenant_id, operation_key)
);

事务先占用唯一操作键,再扣库存并写操作结果。重复键时读取已有结果,核对request_hash,不能同键不同数量也直接返回成功。若库存不足的失败结果也要幂等保存,应在同一事务内记录确定的拒绝结果,而不是全部抛异常导致操作记录回滚;这与异常型回滚协议不同,需要明确设计。

幂等键作用域要覆盖业务:租户、订单、操作类型、必要版本。多次合法追加预占不能误用同一键被去重。键保留期短于客户端重试窗口也会导致旧操作再次生效。

3. 悲观锁、乐观锁和条件更新

SELECT FOR UPDATE适合需要先读取一组字段再基于它们决策的场景,但要确保在正确事务里、走合适索引,并控制锁顺序和持有时间。乐观version检查适合冲突较少且重试代价可接受的场景;高冲突热点上无限CAS重试可能浪费资源。

单条条件更新可以将简单不变量下推数据库,往往比“先查→加分布式锁→再查→写”更简单,但复杂库存包括仓库、可用、占用、冻结与在途,必须写清跨字段和跨表守恒关系。不能只保护available一个字段,就认为库存账本完整。

4. 项目多锁案例的边界

StockComponentImpl〔本地文件〕在客户端缺失或开关关闭时走不加该分布式锁的分支;开启时按锁名排序构建MultiLock,等待与租约有固定参数。排序有助减少锁顺序冲突,但不能证明不存在其他锁、数据库锁或超租约执行。

源码还对逐SKU业务异常进行处理,意味着不能凭外层方法名就认定整批全有或全无。其局部TransactionTemplate〔本地文件〕包住两类数据库写入,而某些读取在回调之前。需查外层事务和写入条件,不能自动认定此前读取仍然新鲜。

因此项目阅读时应列三个不变量:无锁路径如何保证正确;锁过期后旧worker继续写如何处理;同一业务重复执行如何防重复。Redis锁有价值,但不应把数据库约束撤掉。

5. 批量操作和部分成功

批量CASE更新减少往返,但可能扩大锁集合;锁持有越长,其他请求越容易等待。按稳定SKU顺序处理可降低死锁概率,但不同业务若采用不同顺序仍会冲突。

逐批提交可以降低事务长度,却意味着整个任务可能部分成功。需要记录每个业务操作结果以及重试边界;不要接口返回“失败”后让客户端把所有SKU作为全新操作再提交。按原操作键重放才能收敛。

库存流水用于解释账本变化,应有唯一业务来源、方向、数量和关联单据。流水写入与库存更新应遵循一致协议;对账发现差异时,不能简单把库存覆盖成某个不明来源的总数。

6. 死锁与未知提交结果

数据库死锁检测可能回滚一个事务;可重试的是完整业务单元,并在新事务中有限重试。退避和抖动降低同一批请求再次同时争锁。不是所有SQLException都可重试,连接中断发生在提交期间可能意味着结果未知。

未知结果通过操作键查询来消歧,不能无条件补扣或补回。补偿也应幂等:重复释放预占可能把库存加多,使用原预占状态到已释放的条件迁移,并与回补原子执行。

7. 一份最小验收矩阵

场景 必须验证
两个请求争最后一件 至多一个成功,库存不负
同键并发重复 一次业务影响,同一最终结果
同键不同请求摘要 明确冲突,不静默复用
提交后响应丢失 查询或重试不多扣
多SKU部分失败 用户可知道成功集合,重试不重复
锁禁用/租约过期 数据库不变量仍受保护
释放重复消息 库存只回补一次

练习:库存条件更新影响0行,是否可以直接重试100次?不行,可能库存不足、租户不匹配或版本冲突;先分类,重试必须有业务意义和预算。

练习:Redis锁保护了整个方法,还要操作唯一键吗?需要。锁协调同时发生的操作,幂等处理先后重复操作,解决的问题不同。

延伸:数据库锁课程、分布式课程。目标数据库隔离级别、驱动与索引行为需独立集成验证。

原始文档 · high-concurrency-course/04-海量数据流水线与性能编码.md

04 海量数据流水线与性能编码

数据库快不代表应用快。巨大结果集的传输、Java映射、Map去重、JSON序列化、压缩和日志都可能成为主要成本。本章从已存在的游标同步代码出发,讨论有界流水线和性能编码,不把“Stream写得短”当成“运行得快”。

1. 项目的正面示范

广告明细同步〔本地文件〕每次取一页,在页内聚合,批量upsert后推进最后原始记录的nick/sad_type/id。这比一次性读全部数据再groupBy更容易控制堆。

关键不只是LIMIT,而是循环内的对象不会永久积累到外层集合。游标也不是最后一个有效聚合昵称:过滤空白昵称后可能一条都不剩,仍要从原始页前进,否则可能反复读同一页。

对照Mapper〔本地文件〕的排序与NULL续页,再理解“存储顺序”和“业务归一化”不能混用。该形态不自动证明扫描期间的快照一致性,来源可变时仍需定义更新语义。

2. 从串行分批到有界流水线

串行读→转换→写最容易推理,适合作为正确基线。如果测量显示读与写之间有可重叠的等待,可以考虑固定数量的在途批次。但无界提交Future会把数据库分页重新变成内存全集。

读取器 → 容量2的批队列 → 转换器 → 容量2的写队列 → 写入器

每个阶段必须规定异常如何传播、上游如何停止、未完成批次如何重试、队列中的对象由谁释放。写入器失败后读取器仍无限读取,是常见的流水线失控。顺序要求也不能忽略:并行完成顺序可能与游标顺序不同,checkpoint只能推进到连续完成前缀,不能直接取最大已完成ID。

3. 内存预算推导

设每批B条、每条Java对象及字符串平均M字节、在途批数P、转换副本倍数K,则核心工作集约B×M×P×K。还要加驱动缓冲、集合余量、压缩与上传缓冲。M应测实际对象结构,不能用数据库行长直接代替。

假设教学值B=1000、M=2KB、P=4、K=2,工作集约16MB;十个同类任务就可能约160MB,尚未算框架和缓存。减少单批大小却提高预取数,可能没有降低总占用。

4. 集合与字符串的成本

根据可预测规模为ArrayList或Map设合理容量,可减少扩容复制;但为上界一亿提前分配又会浪费内存。Map建立索引能将嵌套扫描变线性,但要处理重复键和内存边界。toMap遇到重复键应有明确合并语义,不能为了不报错随意保留最后一个业务对象。

频繁拼接巨大字符串、每行创建格式器、重复JSON解析和深拷贝都可能形成分配热点。应先用采样定位,再改热点;不要把所有清晰代码改成难维护的手工优化。金额使用精确类型,不能为了速度把BigDecimal换double破坏财务正确性。

并行Stream默认执行资源可能与其他任务共享;阻塞IO与有状态累加尤需谨慎。把可变ArrayList在parallelStream中并发add不仅性能未知,还可能数据竞态。优先清楚的单线程基线和受控批处理。

5. SQL优化与对象优化一起评估

只取必要列降低网络与对象构造。关联表一对多JOIN可能重复父字段,把数据库往返减少了却增大传输。先按父实体分页,再批量取明细通常更容易控制语义和大小,但需要验证SQL计划与一致性要求。

巨型IN、CASE或多VALUES语句减少往返,也增加SQL解析、参数包和锁集合。最佳批量不是固定1000:应比较吞吐、单批p99、失败重做成本和连接持有时间,按资源预算决定。

6. 日志不是免费的

项目库存路径存在对列表进行JSON序列化的日志调用形态。即使后面是异步日志,参数序列化可能在调用前已发生。完整明细会增加CPU、内存与日志存储,还可能泄漏客户数据。

应优先记录业务ID摘要、行数、批号、耗时、错误分类和traceId;必要样本做脱敏与长度限制。日志级别判断可以避免部分无用构造,但不能把业务审计随意采样丢掉,诊断日志与审计记录要区分。

7. 输出端的背压与恢复

慢客户端下载会延长服务端资源持有。如果把数据库游标直接绑到下载流,用户网络慢可能长期占连接。异步生成文件后下载能分离两种资源,但要增加任务状态、文件权限、过期清理和恢复协议。

分块文件+checkpoint跨数据库和对象存储不是单事务,应按崩溃窗口设计。Spring第18章已经提供租约、epoch和manifest案例;本课程进一步强调并行分块下的连续提交水位,不能只看最快完成的块。

8. 练习与答案

  1. 读取批1、2、3,完成顺序3、1、2,能先记游标3吗?不能,否则崩溃后跳过1和2。记录每块状态,只推进连续完成前缀。
  2. Stream比for循环一定更慢吗?不是,应在相同语义下测量;主要收益通常来自工作量减少,而不是语法偏好。
  3. 日志换AsyncAppender就消除序列化成本了吗?不会自动消除调用前参数构造,队列也有内存和拒绝边界。
  4. 只要分页就不OOM?还要检查外层累积、预取、并发、转换副本和输出缓冲。

延伸:Spring批处理、可靠导出。

原始文档 · high-concurrency-course/05-压测基准尾延迟与故障验收.md

05 压测、基准、尾延迟与故障验收

优化需要一份可信的对照实验。没有数据分布、错误率和业务真值的QPS数字,几乎无法用于容量决策。本章给出可落地的测量步骤,并区分微基准、机制测试和端到端压测。

1. 明确这次测试回答什么

验证线程池拒绝策略,用几个受控任务即可;验证百万行游标性能,需要真实规模、索引与分布;验证服务过载恢复,需要持续到达流量、依赖故障和恢复阶段。用一个小JUnit通过替代生产容量证据,是类别错误。

本课程labs是确定性模型实验,Spring课程的11项测试是框架/JDK机制实验,都不是项目生产压测。必须保留这个边界,否则学习材料会鼓励错误上线判断。

2. 数据集应该包含哪些分布

ERP租户通常不均匀:大租户占大量订单,少数SKU是热点,日期筛选偏近期,历史数据却很大。只造均匀一万行会低估大表扫描、统计估计误差和热点锁竞争。

测试数据包括小/中/大租户、同时间戳、NULL、超长文本、多明细订单、冷缓存和热缓存。写请求包含重复操作键、库存临界值、状态冲突和请求超时重试。数据真值用独立算法或快照建立,不只比较计数。

3. 开环与闭环负载

闭环是固定虚拟用户收到响应后再发下一次。服务变慢时发起速率自然下降,可能隐藏真实用户持续涌入造成的积压。开环按目标到达率持续提交,更适合观察准入和队列,但压测机必须能按时产生流量,并记录发送迟滞。

两者都可以使用,关键是报告负载模型。不能将闭环下的低错误率直接解释为能承受同QPS持续到达,也不能忽略负载生成器已经CPU饱和的情况。

4. 采集与比较

版本与配置:应用提交、JDK、驱动、连接池、数据库、索引
数据:规模、倾斜、热点、缓存状态、统计信息
负载:到达率、并发、读写混合、重试与持续时间
结果:有效吞吐、失败率、排队时间、端到端p50/p95/p99
资源:CPU、堆、分配率、GC、连接等待、扫描行和锁等待
正确性:主键集合、金额、幂等、租户隔离、恢复结果

p99不能从各实例p99简单求平均;使用可聚合直方图。也不能只统计成功请求延迟,拒绝掉全部慢请求后成功样本自然变快。报告应把拒绝、超时和未完成样本单独列出。

5. 逐级找拐点

先建立低负载正确性基线,暖机后分级提升到达率,每级保持足够观察时间。吞吐趋平但队列和p99上升时已接近饱和,不应继续把线程数加到最大作为解决方案。

找到限制资源后做一个最小改动,例如批量查询减少N+1,而不是同时升级JDK、改索引、改缓存和线程池,导致无法归因。重复对照并记录波动。回滚要恢复配置和数据口径,而不只是代码文件。

6. 微基准与JIT

用单次System.nanoTime测一段Java代码容易受到JIT、死代码消除、常量折叠、GC与CPU调频影响。需要微基准时使用针对JVM设计的工具与正确暖机、结果消费和多fork设置,但微基准仍不代表端到端收益。

例如Map查找快了30%,若这部分只占接口CPU的1%,整个请求提升可能很小。优先从trace和采样找到真实热点,再决定是否值得微优化。不要为了好看的微基准牺牲业务可读性。

7. 故障压测与恢复压测

注入数据库延迟、缓存不可用、RPC超时、消息重复、worker重启与配置部分生效,观察过载是否被限制在相应边界。故障解除后也要测:积压消费、缓存回源和重试可能同时爆发,形成第二次故障。

演练前设自动停止条件、数据隔离、回滚负责人和观察窗口。线上真实资金/库存不得用于无保护压测。本课程不执行任何业务故障注入,只提供隔离实验和设计方法。

8. 练习与答案

一:优化后QPS翻倍,但错误率从0.1%变50%,能验收吗?应比较满足业务正确性与SLO的有效吞吐,不能只算收到多少请求。 二:本地H2与MySQLSQL结果一致,能推断性能一致吗?不能,计划、锁、日志和驱动行为不同。 三:压测没触发死锁是否证明无死锁?没有,只覆盖了部分时序;仍需锁顺序和重试协议。 四:怎么发现测试工具限制?看生成器CPU、网络、计划发送与实际发送差、连接与错误,同时对比服务端接收率。

参考:OpenJDK JMH、Spring容量诊断。

原始文档 · high-concurrency-course/06-高并发综合实战与编码检查表.md

06 高并发综合实战与编码检查表

综合题:多个租户同时触发订单同步与报表导出,热点SKU持续扣减,外部平台偶尔超时,消息至少一次交付。要求库存正确、任务不丢、关键写请求不被报表拖垮,并在故障恢复后逐步消化积压。以下是设计练习,不声称当前项目已完整采用此方案。

1. 划分业务通道,而不是统一大线程池

交互库存写、普通查询、批量同步、导出四类通道有不同SLO。建立各自准入和执行预算,再汇总数据库总连接及SQL工作量。库存热点必须遵循数据库条件更新和幂等键,导出通过持久任务异步处理,查询限制时间范围与页大小。

资源隔离不意味着每类服务无限增加连接。假设教学预算每实例数据库并发10,其中关键写保留4、查询3、后台3,只是设计起点,还要考虑事务嵌套和多实例合计。预算应根据真实负载验证,不可照搬这些值。

2. 入口、执行、持久状态

导出请求完成授权与参数校验后,原子创建唯一任务,返回jobId;调度器按租户公平性和全局预算抢任务;worker读取一页、生成不可变块、推进受epoch保护的checkpoint。成功发布manifest后才允许下载。

同步消息则以业务事件键去重,在短事务中执行业务状态迁移和消费记录。事件顺序不能只依赖消息到达顺序,业务版本应拒绝过旧更新。提交后ACK失败允许重投,重复事件返回已处理结果。

当消息处理包含远端调用时,本地事务无法撤销远端副作用。通过远端幂等键、状态查询、补偿与对账解决;不要把一个大事务跨越几十秒RPC等待。

3. 把每个失败写成状态转换

NEW → PENDING → RUNNING(epoch) → SUCCEEDED
                  │
                  ├─ 可重试故障 → RETRY_WAIT → PENDING
                  ├─ 永久失败 → FAILED
                  └─ 租约过期 → 可回收(新epoch)

所有转换使用旧状态、版本和必要所有者条件,影响行数不符合就停止推进。attempt记录执行次数,next_run_at控制退避,失败原因分类而不是仅存一段异常文本。

不能让catch只打日志而任务一直RUNNING;也不能所有错误都重试。参数非法、权限不足与业务终态一般不能通过重试修复。未知提交结果要先消歧。

4. 停机与恢复

发布时先停止新接单/抢占,允许有界在途批次收尾;超时未完成的任务依靠租约恢复。关闭执行器只是资源动作,业务是否成功要以持久结果判断。

恢复后按限额释放积压,优先保护当前交互流量。消息批量重放、缓存回源和任务恢复应共享容量认知,不要由三个团队各自把速率开满。观察最老任务年龄而不仅是队列数量。

5. 安全与规范进入代码评审

评审问题 常见错误 合格证据
租户从哪里来 信任请求中的tenantId 授权来源与SQL谓词测试
重复如何处理 前端按钮禁用代替幂等 唯一操作键及重复断言
队列有无上界 newFixedThreadPool隐含无界队列 容量、拒绝、等待预算
异常谁观察 submit后丢弃Future 完成回调、持久失败状态
上下文谁清理 ThreadLocal仅set不remove 异常与嵌套恢复测试
大数据谁持有 分页后仍加总List 堆占用与批次生命周期
SQL是否可控 用户输入排序片段 白名单、参数绑定
日志是否安全 全量订单、token与签名链接 脱敏、截断与审计分离
副作用是否原子 DB与RPC放同一方法就当事务 状态机、对账与补偿

6. 与真实代码对照

对照SCM无界队列,解释为什么max不是自动弹性;对照Index的DiscardPolicy,检查业务状态是否感知拒绝;对照LocalCache分步加载,构造热点同时缺失;对照库存组件,找无锁分支、局部事务和逐SKU结果。

这些是阅读和复现任务,不是直接修改业务代码的授权。应把“已确认的局部机制”“潜在业务影响”“还需检查的调用方”分列,避免用一个片段给整个项目下结论。

7. 独立实验验收

本课程标准库模型覆盖有界队列、重试放大、令牌桶、旧worker隔离、连续checkpoint和幂等库存。它们让你能稳定看到失败时序,而不是依赖随机线程竞争。

下一步应在独立MySQL、真实消息系统及对象存储替身中验证协议,再进行目标版本集成与容量测量。模型通过不证明Java代码、驱动或分布式环境已经正确实现。

8. 答辩题与答案方向

题一:用户超时后重试,如何保证只扣一次?操作键唯一约束、摘要校验、与库存变化同事务、结果可查询;未知状态不直接重扣。

题二:报表压力大,为什么不加100个线程?先减少扫描与N+1,再控制数据库并发和内存;线程只放大到达依赖的速度,不增加依赖容量。

题三:过期worker如何不覆盖新worker?持久状态检查epoch,外部对象写不可变隔离键,仅允许新epoch发布正式结果。

题四:如何证明系统可恢复?在每个持久边界注入崩溃,重启后比较独立真值、任务终态、重复副作用和资源回收,而不只是看到日志“成功”。

课程完成标准:能独立画资源图、写业务不变量、列故障状态、实现有界接收与幂等原子单元,并提供测量与恢复证据。背出线程池七个参数只是起点。

原始文档 · high-concurrency-course/开发陷阱深化.md

高并发开发陷阱深化:取消之后,资源到底归谁

本篇先审阅第 01、02、06 章,再沿真实导入服务和执行器追踪任务生命周期。它补充旧文中两个容易被误读的点:公平信号量不是租户公平;FutureTask.done() 能观察取消,也不能无条件等同于任务体已经退出。对于前端转后端的同学,页面不再等待、Promise 进入失败分支、服务端任务停止、数据库不再持有连接,是四个不同事实。后端必须为每个事实建立可检查的状态。

每节严格区分源码事实、条件风险、改进设计、验证。所有失败时间线均为条件推演。本文没有更改 Java 业务代码,没有执行业务 Maven 测试,也没有读取动态配置值。新增的 Python 实验只证明显式任务模型中的资源守恒,不证明 JDK 的线程调度、CAS、可见性、驱动中断或远程回滚。

一、同一个供应商的并发上限,为什么可能不止三个

源码事实。 ScmItemServiceImpl.java#L368〔本地文件〕 的 importDistributorItem 每次调用在第 371 行新建 Semaphore,许可数由方法返回,不能从源码推定运行配置。第 389 行〔本地文件〕 批量 runAsync 后,任务进入 worker 才 acquire。共享池 ScmDistributorItemThreadConfig.java#L28〔本地文件〕 使用无容量参数的 LinkedBlockingQueue,第 33 行 core=5、max=10。

失败时间线 A: 假设单次许可配置为 3。t0 供应商 A 发起导入请求 R1,创建 S1;t1 A 再发 R2,创建 S2;t2 两个请求各自允许最多三个任务越过自己的信号量。实际同时运行仍受池和其他资源约束,不能直接写成必定六个;可确定的是 S1 不知道 S2,无法共同执行“供应商全局最多三个”的约束。多个实例会进一步扩大可用执行资源。

条件风险。 如果产品承诺每个导入请求最多三个,这种作用域可能合理;如果承诺每供应商或全系统最多三个,就与局部对象的作用域不一致。另一个条件是 A 有大量分销商:A 的任务先填入队列,其中等待 acquire 的任务也占 worker,后来的租户 B 即使拥有自己的空闲额度,仍可能排在队列后面。限制真正业务并发,没有限制已提交任务总量和 worker 等待成本。

改进设计。 将配额的主体写成契约:请求、供应商、实例、集群各是多少;先用全局在途上限保护进程,再在调度层选取有租户额度的任务。每租户有限队列加轮询或按成本加权调度,让未获得许可的任务留在调度器,而不是占满 worker 等待。任务只保存必要 ID 和不可变参数,降低排队对象保留成本。跨实例额度需要额外协议,不能把静态 Map 中的 Semaphore 称为集群限流。

验证。 已核对对象创建位置、acquire 位置和线程池队列。待执行在不加载 Spring 的隔离 Java 程序中,以可控闸门同时发起两个请求,分别统计每请求与每租户正在执行数;再让 A 先提交长批次、B 后提交一个短任务,检查 B 的最大等待时长。测试不应依赖随机 sleep,也不应以“平均吞吐提高”代替公平性验收。

二、公平不是一个 true 参数,更不是 RateLimiter 的副作用

源码事实。 SCM 使用 Semaphore 的单参数构造,并未显式启用公平。另一路 RedisSseMessageRouteRegister.java#L36〔本地文件〕 在每个匿名监听器内持有 RateLimiter,第 42 行惰性创建,第 46 行 acquire,再调用业务回调。这是每个监听器对象的速率限制,不是从这段代码就能得到的全局用户限额;回调所在线程是否共享、是否并发调用,仍需核对 Redisson 版本及调度环境。

失败时间线 B: t0 用户打开三个订阅连接,形成三个 limiter;t1 每个分别按自身速率通过;t2 合计速率可能超过“单用户限制”的产品预期。另一个模型是租户 A 在许可释放瞬间不断执行无参 tryAcquire,B 已排队等待,A 仍可能抢到许可。换为 fair=true 后继续使用无参 tryAcquire,并不能得到所想象的严格排队。

机制核对。 JDK 8 Semaphore 区分公平等待与无超时 tryAcquire 的插队语义;需要尊重公平设置时可评估带超时的重载,包括零超时形式,但还需处理中断。公平顺序约束的是内部获取点,不是网络到达时间或租户份额。Guava RateLimiter 官方 API 说明它限制速率且不保证公平;此处核对通用语义,未验证项目实际 Guava 版本。

改进设计。 明确公平目标:活跃租户都有机会,还是某等级保底,或按任务成本分摊。大任务按批次让出机会,记录每租户等待时间上界与拒绝原因;忙等 tryAcquire 不应作为调度器。全局额度与租户额度一起使用时,应有固定获取次序和失败回滚,不能拿着最后一个全局许可无限等租户额度。对于 SSE,等待限速可能阻塞共享回调线程;需要有界转交和允许丢弃的通知策略,但必达业务不能随之丢弃。

验证。 本次只完成静态作用域和官方语义核对。待执行用固定到达顺序比较 FIFO、轮询和成本加权的最长等待;验证多连接是否突破单用户预算。Python 取消实验不包含真实公平调度,不应被引用为此节的实证。

三、finally 既可能漏还,也可能多还

源码事实。 ScmItemServiceImpl.java#L392〔本地文件〕 获取许可,InterruptedException 被转换为 BizException;外层 第 449—451 行〔本地文件〕 finally 清理上下文并无条件 release。该局部没有 acquired 标志,也没有在这个 catch 中恢复中断标记。与“提交前获取、任务 finally 释放”的旧文教学片段不同,此处获取发生在任务体内,必须分别分析。

失败时间线 C: t0 三个许可都被占用;t1 第四个 worker 阻塞在 acquire;t2 被中断,未成功获得许可;t3 catch 抛业务异常;t4 若前面的上下文清理正常返回,finally 执行 release;t5 许可计数增加,但没有与之配对的获取。Semaphore 不替业务维护所有权账本,因此这种路径可能凭空放大额度。若清理本身抛异常导致 release 未执行,则是另一条路径,不能混在同一因果链。

改进设计。 worker 内获取时记录是否成功,只有成功获取才释放;清理上下文和归还资源各自保证 finally 范围,避免一个清理异常挡住另一个动作。处理中断时应传播中断语义或恢复标记,并由任务状态区分取消、失败和可重试。将中断一律改成“系统繁忙”可能让调用者发起不必要重试。

旧文“提交前获取”的结构则有另一条失败时间线 D:t0 准入许可减一;t1 FutureTask 入队;t2 调用 cancel,任务尚未进入业务体;t3 worker 后来取到已取消包装器,不执行 callable;t4 callable 内 finally 永远没有机会归还许可。两条时间线说明,release 的位置必须与 acquire 的范围配对,不能机械背诵“放到 finally 就好了”。

验证。 已静态核对 SCM 中断路径;待执行 JDK 测试应通过闸门固定 acquire 等待后再中断,检查许可未越界且任务状态终结。新增 test_cancellation.py〔本地文件〕 对时间线 D 提供故意错误策略的反例断言,但没有模拟 SCM 的真实线程和异常类型。

四、done 回调修好了排队取消,却可能提前放开运行额度

机制事实。 FutureTask 官方 API 说明 done 在完成或取消后调用;OpenJDK 8u 实现 的 cancel 会推进 Future 状态并触发完成处理,并不 join 正在运行的 callable。不能把 isDone=true 解释为线程已经退出。也不要把这套机制照搬到 CompletableFuture:其 JDK 8 文档 明确说明 mayInterruptIfRunning 在该实现中不用于控制执行。

失败时间线 E: t0 总预算一,任务 A 已开始远程调用;t1 调用 cancel(true),Future 进入取消完成态;t2 done 无条件 release;t3 任务 B 获得许可并开始;t4 A 的驱动忽略或尚未响应中断,仍在占资源。许可即使只归还一次,也已经归还得太早。单纯 AtomicBoolean 防双重释放只保证次数,无法保证释放时刻。

改进设计。 先说明许可保护什么。若只限制“尚未完成的 Future 数”,取消完成可以释放;若保护真实执行中的连接、CPU 工作或远程调用额度,就要等待相应资源边界退出。教学模型选择更保守的“准入直到任务体退出”预算,并分开结果可见性与资源所有权:

当前状态 事件 下一状态 本次能否归还
ADMITTED 执行器明确拒绝 REJECTED 能,尚未执行
ADMITTED / QUEUED 取消先取得控制权 CANCELLED 能,必须禁止以后启动
QUEUED worker 先取得控制权 RUNNING 不能
RUNNING 请求取消 CANCEL_REQUESTED 不能,任务体还活着
RUNNING 任务体退出 SUCCEEDED / FAILED 能,恰好一次
CANCEL_REQUESTED 任务体退出 CANCELLED 能,恰好一次

生产实现需要把“取得开始权”和“取消未开始任务”做成原子竞争;两个不受保护的布尔量不够。模型假设每个状态转换原子完成,真实 Java 需锁或 CAS 保证。完成先赢时保留成功;取消先赢时禁止旧 worker 发布结果,但已发生的外部副作用仍可能存在,需使用业务幂等键查询和消歧。网页可以显示“取消请求已接受,正在确认”,不应过早显示“所有操作已撤销”。

验证。 标准库模型覆盖 start/cancel 两个先后顺序、finish/cancel 两个先后顺序、运行取消仍持许可、排队取消禁止后续启动、重复通知不重复释放,并故意构造 done 提前释放导致两个活跃任务进入容量一的反例。待执行 Java 版本需要 latch 驱动的不响应中断任务,验证实际包装器、TTL、trace 装饰层和关闭行为;Python 通过不能替代它。

五、静默丢弃没有失败回调,进度条为什么一直转

源码事实。 AsyncTemplateConfig.java#L43〔本地文件〕 将 ThreadPoolExecutor 包在 TraceableExecutorService 和 TTL 包装中;队列容量 108,拒绝策略为 DiscardPolicy。第 38 行把执行器交给外部 AsyncTemplateImpl,本次未得到其完整实现,因此不能宣称项目所有业务任务都会悬挂。但底层静默丢弃是可定位事实。ThreadPoolExecutor 官方说明 可核对拒绝策略语义。

失败时间线 F: 假设调用链使用标准 submit 包装任务且未补偿拒绝。t0 任务状态已写为排队;t1 执行器饱和;t2 DiscardPolicy 返回,不抛异常也不运行任务;t3 submit 返回的 Future 无人完成;t4 页面持续查询,后台既没有成功也没有失败更新。给 worker 加 try/catch、给 Future 加超时 get,都不能证明这个未运行任务已经得到业务终态。

SCM 另有一个不同边界:ScmItemServiceImpl.java#L454〔本地文件〕 的 exceptionally 处理异步执行异常;若 runAsync 在提交时直接抛拒绝异常,后面的回调尚未注册。不能把异步回调当提交失败的统一捕获器。这里默认池与 Index 池不同,不应把 Index 的 DiscardPolicy 移植成 SCM 的既有事实。

改进设计。 持久状态使用 PENDING、CLAIMED、RUNNING、RETRY_WAIT、终态;写 RUNNING 应对应实际获得执行权。明确拒绝应归还本次许可并把记录保留待调度或标失败。静默策略若用于可丢诊断任务也要计数;可靠导出不能用它隐藏拒绝。超时回收必须带 attempt/epoch,旧 worker 的迟到写不能覆盖新尝试。调用者超时只是停止等待,不自动回收仍在占用的执行额度。

关闭证据。 Threads.java#L49〔本地文件〕 等待后调用 shutdownNow,未接收返回的未启动任务列表;第 54 行只写未终止日志。ExecutorService 官方契约 描述它尝试中断并返回待执行任务,不保证运行任务立即停止。若任务只有内存状态,关闭还需处理队列退回与运行未决,不能把关池成功等同业务完成。

验证。 已静态核对三条不同路径;模型测试覆盖“丢弃不产生终态”以及显式取消补偿,不宣称能自动发现真实线程池的丢弃。实际 AsyncTemplate 的提交、拒绝与状态保存仍待隔离验证。

六、可执行实验、练习和验收答案

从工作区根目录运行,只有 Python 标准库:

python3 -B high-concurrency-course/labs/test_cancellation.py -v

模型记录 available、acquired、released、release_count、body_active、future_done、published,并检查“空闲许可 + 尚未归还的所有者 = 总容量”。已获得许可的终态恰好归还一次;从未获得许可的准入拒绝归还零次;运行取消期间不可释放。它枚举六种事件的五步序列,共 7776 条,并显式结束残留任务。这个枚举是有界状态验证,不是无限状态证明,也没有自动证明活性:任务永不退出时许可就应该继续被占用。

题一: 排队任务取消后,许可回来了,但队列长度没有减少,是否模型错误?答案: 不一定。逻辑取消和物理移除是两件事;旧包装器留在队列也必须通过开始权检查而不执行。真实队列内存回收需要额外移除策略,模型不验证其内存上界。

题二: 运行取消后许可迟迟不归还,可以用定时器强制 release 吗?答案: 若资源仍在使用,强制 release 会突破预算。应限制外部请求时间、隔离不响应取消的工作、暴露未退出任务并执行恢复策略;不能用修改计数掩盖仍存活的调用。

题三: worker 清理与取消回调都 release,但加 AtomicBoolean 是否足够?答案: 只解决重复释放。运行取消回调先赢仍会提前释放;必须同时证明“不会再开始”或“资源确已退出”,再执行一次性归还。

题四: .exceptionally 返回 null 后,能否让任务表标成功?答案: 异常链恢复后的 Future 完成,不等于原始业务成功。保存明确业务结果;日志、Future 状态和任务状态是三个观察面,不能互相冒充。

阅读与验证边界。 运行结果和完整验收范围见 审阅清单。阅读第 01 章的许可示例时,应同时检查本文对获取位置、排队取消和运行取消的区分。新增模型是设计校验工具,迁移到 JDK 前仍须完成上述隔离验证。

原始文档 · high-concurrency-course/验证记录.md

高并发模块验证记录

2026-11-11,在隔离教学目录执行python3 -m unittest -v test_protocols.py:8项测试全部通过。测试文件位于labs,使用Python标准库和SQLite内存数据库,没有业务配置、外部服务或生产数据。

覆盖队列容量与显式拒绝、重试组合计数、令牌桶、乱序checkpoint、epoch保护、租户隔离、幂等库存、提交前回滚和确定拒绝。具体8个测试方法见实验源码。

没有运行Java业务程序、MySQL并发集成、Redis、真实Broker、网络分区或性能压测。SQL和Java片段是教学设计;容量数字不是测量结果。数据库幂等测试串行执行,不能证明多线程和目标数据库隔离级别已正确实现。

文档本地链接、源码行号范围与统一阅读版锚点由backend-learning/validate.py检查。原数据库、Spring的编号Markdown保留不动。

原始文档 · high-concurrency-course/labs/README.md

高并发协议模型实验

在本目录执行python3 -m unittest -v test_protocols.py,仅用Python标准库与独立SQLite内存库,不需要业务服务。

8项实验覆盖:有界过载与显式拒绝、三层重试放大、令牌桶突发和单调时间、乱序完成的连续checkpoint、旧epoch拒绝发布、库存幂等与租户隔离、提交前故障回滚、库存不足结果稳定。

先预测测试中的队列数和checkpoint序列,再运行。尝试把checkpoint改为最大完成块,观察顺序3、1、2时为何会跳过未完成数据;移除幂等查询,观察重放如何重复扣库存;取消队列上界,观察积压如何失去约束。

边界:这是确定性协议模型与SQLite本地事务实验,没有创建Java线程、模拟真实网络分区或验证MySQL锁;fencing测试假设最终写入端会检查epoch,不能证明任意对象存储天然具备此能力。重试放大测试只是组合计数,不模拟真实RPC中间件。本次结果不能用作QPS或生产可靠性证据。

真实JDK执行器实验见Spring实验室。

取消与许可所有权增量实验

执行python3 -B test_cancellation.py -v,新增13项测试,包括7776条有界事件序列,检查排队取消、运行取消、明确拒绝和重复通知时的许可守恒。它同时构造finally-only漏还与done过早释放两个反例。模型把状态转换视为原子动作,不模拟JDK线程、可见性或真实IO取消;具体解释见开发陷阱深化。

学习阶段 06

运维与排障

日志、网络、JVM、发布与恢复

原始文档 · operations-course/README.md

ERP Java 后端运维与可靠性教材

新增开发陷阱深化:事件与trace计量、日志输入完整性、MDC作用域、日志故障、schema和发布回滚兼容性,附验收矩阵与练习答案。

面向前端基础扎实、正在承担 Java ERP 后端工作的开发者。本课程把一次“接口很慢”拆成可验证的问题:谁在等待、资源归谁、证据在哪里、怎样恢复、恢复后怎样证明业务正确。按 00—06 顺序阅读;每章包含原理、真实源码定位、条件化风险、故障推演和练习答案。

完整目录

章节 学习结果
00 Linux 进程线程文件网络基础 区分进程、线程、文件描述符、CPU 与 I/O 等待,建立只读取证顺序
01 HTTP DNS TCP TLS 连接排障 按连接阶段定位超时,理解重试、证书与响应语义
02 日志体系与查询实战 读懂 Logback 路由,管理 MDC,使用虚构 JSONL 分析日志
03 指标告警 SLO 与链路追踪 定义可计算的用户体验目标,以证据关联指标、日志和追踪
04 Maven CI CD 容器与发布治理 识别跳过测试、制品漂移、发布阶段和回滚兼容性
05 JVM GC 内存 CPU 事故诊断 区分堆、原生内存、CPU、GC 与容器限制,控制诊断成本
06 备份恢复容灾与 Runbook 用 RPO/RTO 验收恢复,设计可停止、可回退的演练
日志实验与测试边界 完全离线运行 Python 标准库分析器和 unittest
验证记录 本次实际验证范围及未验证事项

阅读约定与证据边界

源码链接相对于本目录指向同级业务仓库,格式为 ../仓库/路径#L行号;行号以写作时的本地文件为准,后续改动可能使其漂移。所有“源码事实”来自本次读取的对应方法或配置片段。教学代码明确标注为示意,不宣称已经进入业务仓库。本文不提供业务地址、凭据或生产日志。

本次只写 operations-course/,保留其他教程;不运行业务程序、Maven 生命周期、部署脚本、容器或数据库操作,不连接业务服务。命令默认用于 Linux 的只读观察,且只展示、不代表已经执行;实际执行的只有本目录虚构数据实验及文档静态校验。网络探测示例只允许在另行准备的隔离实验环境使用。JVM attach、堆转储、JFR、备份、恢复、停止服务均单独注明影响,不能视为无成本的只读查询。

现有文件能证明后台脚本、商品服务 Dockerfile 与 Maven 配置存在,不能证明生产正在使用它们。本次在所检索业务目录按 Dockerfile、Jenkinsfile、*k8s*、*deployment* 等文件名未发现可据以说明 Kubernetes 现状的部署清单;这不是对所有外部发布平台的否定。Kubernetes、Prometheus 和 OpenTelemetry 的方案均按教学拓展描述,未证明已部署。源码中的潜在缺陷也不等于已发生线上事故。

与已有教材衔接

建议先手工解释每章故障链,再运行实验,最后查看答案。验收不以记住命令数量为标准,而以能否提出可证伪假设、保留现场、说明风险条件、验证恢复后的业务结果为标准。

原始文档 · operations-course/00-Linux进程线程文件网络基础.md

00 Linux 进程、线程、文件与网络:把“服务活着”拆开

前端开发常把浏览器标签页当作程序边界;到了后端,一个 Java 进程里可能同时跑 HTTP 请求、RPC、定时任务、连接池维护和日志写入。看到 PID 只说明内核中还有这个进程,看到端口也只说明某个 socket 正在监听。订单能否提交,还取决于请求是否得到执行、依赖是否可达、事务是否提交,以及响应能否返回。这一章先建立资源模型,再讨论命令。

1. 进程是资源容器,线程是执行路径

进程持有虚拟地址空间、打开文件表等资源;同一进程的线程共享大部分内存,但各有栈、寄存器状态和调度身份。Java 的普通平台线程通常对应操作系统线程。两个请求改同一个对象,会遇到可见性与互斥问题;两个线程各自局部变量同名,不意味着它们共享栈。浏览器事件循环“等一个 Promise 不占用当前调用栈”的直觉不能直接套到同步 JDBC:阻塞调用会让当前工作线程等待,直到成功、失败或超时。

Linux 调度器让可运行线程竞争 CPU。线程在等待锁、连接、网络或定时器时,通常不持续使用 CPU。因此低 CPU 加高延迟完全可能:HTTP 工作线程全在等连接池,机器还有空闲核也无法完成请求。反过来,线程很多也不一定很忙;大量定时等待线程可能几乎不消耗计算。需要把“数量”“状态”“单位时间 CPU 增量”分开测量。

真实配置见 ThreadPoolConfig.java#L20〔本地文件〕:普通任务池核心线程数 50、最大 200、队列 1000,第 41 行使用 CallerRunsPolicy。这不是“启动就有 200 个线程”。常规 ThreadPoolExecutor 调度是先扩至核心数,再入队,队列满后才继续扩到最大数;仍无法接受时触发拒绝策略。若提交者是 HTTP 线程,CallerRuns 会让它亲自执行任务,于是原本的异步耗时回到请求路径。成立条件是线程池饱和且仍在运行;不能仅凭配置认定线上已发生请求阻塞。

另一个池容易被混淆:ThreadPoolConfig.java#L48〔本地文件〕 创建 ScheduledThreadPoolExecutor,并没有把上面的 1000 队列容量应用给它。AsyncManager.java#L43〔本地文件〕 把任务延迟 10 毫秒调度。10 毫秒是最早可执行时间约束,不是完成时间承诺;等待任务积累仍可能保留大量对象。把两个 Bean 的参数混成一个容量结论,会直接误导事故分析。

2. 文件描述符把磁盘、日志、连接串起来

文件描述符是进程打开资源的整数句柄,普通文件、管道、socket 都能占用它。连接数大并非只有网络成本,还会消耗描述符与内核缓冲区。泄漏也不一定表现为 Java 堆持续增长:如果异常路径漏关流,可能先报“too many open files”。临时把限制调高只能延后失败,不能修复生命周期。

文件名只是目录项,进程打开后关联的是底层文件对象。删除日志文件后,若进程仍持有打开引用,磁盘块可能不会立即释放。因此“目录小了、磁盘仍满”不矛盾;df 观察文件系统占用,du 遍历可见路径,二者口径不同。先确认是否存在已删除但仍打开的大文件,再由运维选择受控轮转或重新打开,不能拿删除当通用修复。inode 用尽时即使还有容量,也可能创建不了新文件。

后台日志位置来自 logback.xml#L4〔本地文件〕 的 ${user.home}/logs;启动脚本 ry.sh#L7〔本地文件〕 又根据当前目录设置 LOG_PATH,但第 29 行把标准输出和错误都重定向到空设备,并没有使用该变量。这里能证明的是脚本写法,不是现场日志已经丢失:Logback 文件 appender 可能仍正常写盘,运行环境也可能根本没用这个脚本。要分别确认 JVM 控制台、应用文件、采集器的路径。

3. 建立不泄漏参数的只读观察顺序

下面命令仅供 Linux 隔离练习,PID 必须替换成已确认的目标编号;不要照抄去扫描未知业务进程。命令未在本次业务机器执行。特意不打印命令行、环境变量或 socket 对端,避免把启动参数、令牌和业务地址带入取证材料。

PID=12345                       # 教学占位编号
ps -p "$PID" -o pid,comm,stat,etime,%cpu,%mem
ps -L -p "$PID" -o pid,tid,stat,pcpu,comm
awk '/^(State|Threads|VmRSS|VmSize):/' "/proc/$PID/status"
find "/proc/$PID/fd" -mindepth 1 -maxdepth 1 -printf '.' | wc -c
df -h .
df -i .
vmstat 1 5
ss -s

第一步记录 UTC 时间、实例身份、部署版本及影响窗口,随后看进程,再看线程、内存、描述符、磁盘和网络汇总。VmSize 是虚拟地址空间规模,不等于驻留物理内存;VmRSS 也不等于 Java 堆。ps 的 CPU 数值有其采样/平均口径,不要把单次读数当瞬时火焰图。vmstat 的首行通常是启动以来的平均值,后续行才更接近所设间隔;要看同一窗口内多次变化。

Linux load average 与 CPU 利用率也不是同一个指标:它包含可运行任务和部分不可中断等待任务。若负载高、CPU 不高,又有很多 D 状态线程,应研究存储或内核等待;若可运行队列长、CPU 忙,再研究计算热点和 CPU 配额。wa、线程状态只能缩小方向,不能直接证明某块磁盘坏了。容器还可能有独立 PID 命名空间、CPU quota 和内存上限,宿主机很空闲不意味着容器没有被限流。

网络是文件资源模型的延伸:监听 socket 接收连接,已建立 socket 负责传输;连接池复用传输通道,工作线程复用执行资源,两者是不同的池。连接空闲不代表请求线程空闲。TIME_WAIT 通常属于正常连接关闭机制,只有数量变化与端口压力、重连速率、失败现象相互对应时才值得归因,不能见多就调内核参数。

观察权限也是资源边界的一部分。读取某进程的诊断信息可能被用户身份、命名空间和系统安全策略限制,权限不足不能解释为进程已经退出。服务重启后 PID 可能变化,旧编号甚至可能被别的进程复用;连续取证应同时记录启动时间与实例身份,避免把两个不同进程的内存曲线拼成一次泄漏。教材中的 Linux 命令不能直接等同于当前 macOS 工作机的命令语义,尤其 /proc 和 ss;本次没有为了演示而启动或进入任何业务容器。

4. 故障推演:报表变慢,重启后短暂恢复

设想一个纯教学场景:报表请求每秒 80 个,每个同步下游等待 2 秒。稳态下平均在途工作约为 80 × 2 = 160,这是 Little 定律在稳定系统、统一统计边界下的直观应用,不是实际线程数的精确预测。若下游突然变成 10 秒,在流量不变且无拒绝的假设下,需求变为约 800 个在途工作。扩线程可能把更多请求压到下游,排队对象又把堆撑大。

下游响应变慢
  → 请求线程占用更久
  → 队列增长,等待时间增长
  → 上游超时并重试,输入进一步增加
  → 内存/连接/描述符压力升高
  → 重启暂时清空排队,但根因仍在

第一轮证据应是同窗口的请求速率、完成速率、等待时长、线程栈、连接池借用等待和队列长度。若栈集中在 socket 读,且池借用几乎不等待,优先查下游响应;若栈集中在连接池获取且已用数顶满,则需分辨慢查询、长事务和连接泄漏。只有观察到提交确实经过指定任务池,才把前面的 CallerRuns 风险与事件联系起来。不能看到“配置 200”就宣布“线程数不够”。

止血通常围绕减少进入系统的工作量、暂停昂贵任务、缩短无效等待、隔离故障依赖;具体变更需另行评估,本文不执行。kill -9 会跳过正常关闭,可能丢失缓冲日志和未落盘进度。即使选择重启,也应先记录现场和恢复条件,否则下一次只能重新猜测。

5. 练习与答案

练习一: CPU 只有 15%,订单 p99 却从 200 毫秒升到 8 秒。能否排除资源瓶颈?请给出两种不同的下一步证据。

答案: 不能。连接池等待会在低 CPU 下拉长延迟,可查看借用等待分布与活跃连接;线程锁竞争也可能低 CPU,可用连续线程栈查等待对象及持锁者。若运行在容器,还要核对 CPU throttling。三者是不同假设,不能用同一张主机 CPU 图替代证明。

练习二: info.log 已删、du 下降而 df 未下降,直接再次删除别的日志是否合理?

答案: 不合理。先在授权范围核查已删除文件的打开引用、文件系统边界和快照占用,确认是否为同一挂载点。删除活动文件可能只移除名字而保留占用,还破坏现场证据。处理必须针对确认的资源持有者,不能批量清空目录。

练习三: 任务池有 1000 容量、调度延迟只有 10 毫秒,所以异步任务最多排队 1000 个且会在 10 毫秒内完成,对吗?

答案: 两部分都错。1000 来自普通任务池,不适用于这里独立创建的调度池;调度延迟是开始执行的时间下界,完成时间还包括排队、执行和依赖等待。应分别识别 Bean、队列类型及调用方。

官方参考与继续阅读

Linux 各字段的定义可查 内核 /proc 文档;资源统计必须按字段口径解释。线程池排队与拒绝语义见 Java 8 ThreadPoolExecutor,延迟任务见 ScheduledThreadPoolExecutor。下一章把网络等待拆为 DNS、TCP、TLS 和 HTTP 阶段。

原始文档 · operations-course/01-HTTP-DNS-TCP-TLS连接排障.md

01 HTTP、DNS、TCP、TLS:把一次“网络超时”切成阶段

浏览器 Network 面板给出了 DNS、连接、SSL、等待和下载时间,后端调用同样经过这些阶段,但还会多出连接池租借、线程排队、代理转发及重试。前端看到 504,只知道某个网关未及时得到上游响应;它没有告诉你数据库是否提交,也没有证明网络断了。本章的目标是把含糊的“接口不通”改写成可核验的阶段结论。

1. 请求经过什么,连接又复用了什么

第一次 HTTPS 请求通常先解析域名,把名称映射为候选地址;然后建立传输连接;再通过 TLS 协商密钥、验证对端身份;最后发送 HTTP 请求并读取响应。DNS 可能命中本地缓存,连接也可能复用,因此不能要求每次请求都有独立的 DNS 和 TLS 耗时。HTTP/2 能在一个连接上并发多个流;HTTP/3 使用 QUIC,不走本章示意的 TCP 建连过程。排查前先确认协议版本与代理链。

业务调用者 → 等待连接池 → DNS → TCP → TLS → 发 HTTP 请求
                                             ↓
返回调用者 ← 读响应体 ← 首字节 ← 服务端排队/业务/数据库/下游

DNS 返回正确地址不保证端口开放;TCP 连上只证明当时可建立传输通道;TLS 握手成功不证明用户有业务权限;HTTP 200 也不保证业务成功。ERP 很多接口将业务错误放进 JSON 字段,必须同时记录传输状态与业务结果。反过来,客户端读超时也不保证业务失败:服务端可能已提交库存扣减,只是响应在返回途中丢失。

DNS 故障还存在缓存与实例差异。同名解析可能因 TTL、递归解析器、搜索域或运行环境得到不同结果。不要只在自己的电脑解析一次,就断言容器内也没有问题。TLS 中 SNI 用于向服务端表达目标名称,证书主机名校验用来确认收到的证书是否属于目标;二者相关但不是一回事。直接把 URL 改成 IP 可能改变 SNI、Host 和证书匹配条件,失去对照价值。

还要区分解析器与应用自己的缓存:操作系统查询得到新结果,不保证一个长期运行的 JVM 已经采用它。应核对该运行时的缓存策略与连接复用情况,不能只通过反复重启碰运气。任何刷新缓存、替换解析或变更路由都属于干预,应在保留原始证据之后受控进行。

2. 从真实 HTTP 工具类读出边界

HttpUtils.java#L65〔本地文件〕 的 sendGet 在第 74 行创建 URLConnection,第 78 行连接,然后循环读取全部响应到 StringBuilder。本方法没有调用 setConnectTimeout 和 setReadTimeout;标准 API 中这两个值为零表示无限超时。可以据此提出“这个调用路径缺少显式等待上限”的风险,但不能断言某个线上请求无限等待:还要确认调用链、实际 URLConnection 实现及外部代理/系统行为。不能把捕获 SocketTimeoutException 误读为已配置超时。

教学改造应先明确预算,再设置不同阶段的约束,而不是复制一组常量:

// 教学片段:未修改项目。只展示 URLConnection 层面的等待限制。
URLConnection connection = url.openConnection();
connection.setConnectTimeout(800);
connection.setReadTimeout(1500);
try (InputStream in = connection.getInputStream()) {
    // 用有上限的读取器消费响应;大文件应流式处理。
}

这仍不是“请求最多 2.3 秒”的证明。读超时限制的是等待数据的阻塞读取,持续缓慢地到达数据可能让总时长更长;DNS、连接池、重试也未必包含在这两个设置内。完整方案需要端到端截止时间,进入每一层时扣除已消耗预算,并核对所选客户端对超时和取消的具体支持。只取消 Future 不一定停止底层 I/O,必须验证取消是否向实际调用传播。

同一方法 HttpUtils.java#L87〔本地文件〕 捕获异常后记录日志,最后在第 117 行返回累积字符串。这意味着空响应、部分响应和异常可能被压成同一返回类型。调用方若把空字符串当“无订单”,就可能把基础设施故障转成业务结论;这是条件化风险,本文没有追踪所有调用点。更清晰的契约是保留错误类别、阶段、状态码及可重试性,且禁止把不完整响应视为成功。

安全边界更值得警惕:HttpUtils.java#L199〔本地文件〕 给连接安装自定义 TrustManager,第 212 行安装自定义 HostnameVerifier;第 247 行起〔本地文件〕 的证书检查方法为空,主机名验证在第 271 行直接返回 true。若实际请求使用这一方法,正常的证书信任与名称校验就被绕过,存在被中间人伪装的风险。源码能证明绕过逻辑,不能证明已经遭到攻击。排障不得把“忽略证书后能访问”当修复,应核对信任链、名称、有效期、时钟与受控证书配置。

3. 超时预算与重试放大

假设用户请求预算 3 秒,入口排队已耗 0.3 秒,本地校验和数据库预留 0.5 秒,留给下游及返回的时间不到 2.2 秒。如果下游每次最多等 2 秒,又自动重试两次,最坏等待会超过上层预算;上游已经取消,下游仍工作,这叫无效工作扩散。多个层各重试一次,还可能把原始一次调用放大成多次实际尝试。

应按操作语义判断重试。查询通常较易处理重复,但也要限制次数、加入退避抖动并共享总预算。创建运单、扣库存、支付回调不能仅按 HTTP 方法判断安全性:需要业务幂等键、持久化去重和结果查询。读超时后应先查已知操作的结果,不能立即换一个幂等键重发。服务端返回明确拒绝和“结果未知”是两种业务状态,必须在日志与 UI 中区分。

连接池也会制造“还没上网就超时”。借连接等待超时发生在网络之前;连接超时发生在建立通道时;读超时发生在已连接后的读取阶段。把三者都归成 timeout 会丢掉关键诊断信息。合理的事件字段是 phase=pool_acquire/connect/tls/read 与归一化 error_code,不要靠分析整段异常字符串长期维持告警。

4. 只观察本地,再在隔离环境主动探测

默认只读的起点是已有连接统计、客户端阶段计时和脱敏错误计数。以下 curl 模板会主动建立连接,因此不是零影响查询,本次没有执行。它只用于另行搭好的教学环境;.invalid 是刻意不可解析的占位域,不得替换成真实业务地址随意运行。

curl --silent --show-error --output /dev/null \
  --connect-timeout 1 --max-time 3 \
  --write-out 'dns=%{time_namelookup} tcp=%{time_connect} tls=%{time_appconnect} first=%{time_starttransfer} total=%{time_total} status=%{http_code}\n' \
  https://lab.invalid/health

这些值大多是从开始到相应事件的累计时间。对一次无代理、无重定向、新建 HTTPS 连接,才能近似用 tcp-dns 估计 TCP 阶段、tls-tcp 估计 TLS 阶段。first-tls 还包括请求发送和路径等待,不是纯服务端执行时间。复用连接、代理、重定向会改变解释,零值也不能直接读作“阶段没有成本”。不要开启带凭据的 verbose 输出分享给他人,更不能用 -k 形成生产方案。

若 TLS 完成很快而首字节很晚,要结合服务端入口时间、线程排队和下游 span;若客户端看到超时但服务端根本没有入口记录,要考虑请求未到、日志采样/丢失或实例查询错误。没有日志不是未到达的充分证明。只有多个独立证据在统一时间窗口对齐,才能逐步排除假设。

5. 故障推演:504 与重复扣库存

教学场景中,客户端在 3 秒收到网关 504,库存服务却在 3.2 秒提交事务。用户点“重试”,系统生成新业务编号,再扣一次。网络层的超时只是触发器,重复扣减来自业务身份没有跨重试保持。若只把网关超时调到 30 秒,峰值期间会保留更多在途请求;问题可能由重复扣减转成线程耗尽。

取证应按同一个操作标识串联:网关接收与返回时间、库存服务接收时间、幂等记录、提交时间及重试来源。跨机器时间差要考虑时钟偏移,不可用毫秒顺序伪造因果。若数据库已经提交,恢复动作是返回已有结果或进行经过业务核验的补偿,而不是再次执行原始变更。性能修复还要检查耗时主要在池等待、锁等待还是外部接口,以免用重试把依赖进一步压垮。

6. 练习与答案

练习一: DNS 为 0.01 秒、TCP 累计 0.04 秒、TLS 累计 0.10 秒、首字节累计 2.10 秒。能说 TLS 花了 0.10 秒、业务花了 2 秒吗?

答案: 在前述新建直连条件下,TLS 增量约 0.06 秒。后面的 2 秒还包含发送、网络、服务端排队与处理;没有服务端证据时不能全部归给业务代码。若有代理或重定向,必须重新解释这些数值。

练习二: 关闭证书校验后请求成功,是否证明证书过期?

答案: 不能。也可能是主机名不匹配、缺失中间证书、不可信 CA、客户端时钟错误或被拦截。应取得非敏感的握手错误类别和证书元数据,在受控环境核对;恢复校验始终是完成条件。

练习三: 读超时后捕获异常并返回空字符串,让上游继续执行,有什么问题?

答案: 空数据与失败被混淆,调用者可能作出错误业务决策,还失去未知结果处理机会。应保留失败类型并在边界决定降级或重试。对于写操作先查询幂等结果;对于读取明确展示不可用,不能伪造“没有记录”。

官方参考

阶段计时字段见 curl 官方手册;状态码和方法语义见 RFC 9110;TLS 身份认证机制见 RFC 8446。Java 层默认值与限制见 URLConnection API。继续阅读 Spring 超时、重试与隔离。

原始文档 · operations-course/02-日志体系Logback结构化trace与查询实战.md

02 日志不是打印语句:Logback、结构化事件与 trace 查询

前端控制台往往服务于眼前的一次交互;后端日志需要在实例退出后仍能回答“哪个请求、哪个版本、哪一步、最终结果如何”。把所有对象打印出来既昂贵又危险。可靠的日志体系首先定义事件契约,再决定路由、存储、保留、查询和权限;日志量越大,不代表解释能力越强。

1. 从 logger 到磁盘:经过三道判断

调用 log.info 后,先按 logger 的有效级别决定是否产生事件;再按 logger 层级和 additivity 路由给 appender;各 appender 的 filter 最后决定是否接收。级别是事件优先级,不是存储目标。LevelFilter(INFO) 只匹配 INFO,而 ThresholdFilter(INFO) 才表达 INFO 及以上。混淆二者,事故时就会在错误文件里找一个永远不会进去的 WARN。

真实配置 logback.xml#L28〔本地文件〕 对 file_info 使用 INFO 精确匹配、其他级别 DENY;第 50 行〔本地文件〕 的 file_error 只接受 ERROR。第 104 与 109 行分别出现 root 配置。不能仅凭重复 root 标签就宣称“后一段覆盖前一段”,应在实际依赖版本下查看 Logback 状态输出和最终 appender 绑定。就已读文件而言,WARN 不符合这两个文件 appender 的条件;若控制台有效,它仍可能从控制台输出。

结合 ry.sh#L29〔本地文件〕,可以提出具体反例:假如实际用该脚本启动,并且没有其他 appender/采集路径,WARN 没进 info/error 文件,控制台又被丢弃,就可能留下观察空白。这一结论有启动方式、日志配置和采集路径三个前提,本文没有验证部署,不能表述为“生产 WARN 全部丢失”。

SQL logger 在 logback.xml#L92〔本地文件〕 设置 DEBUG 和 additivity=false,直接送 SQL_FILE。这解释了为什么 root 为 INFO 仍可能出现特定 logger 的 DEBUG 输出:事件由子 logger 的有效级别判断,父级阈值不会再次统一过滤已通过的事件。也解释了 SQL 日志为何不一定在控制台出现。查日志前必须先识别 logger 名称、级别和路径。

2. 滚动、容量与异步写入的取舍

logback.xml#L19〔本地文件〕 的时间滚动保留 60 天,不能推出总量有上限;一天突增百倍仍可能耗尽磁盘。SCM 测试配置#L16〔本地文件〕 同时设置按日期与大小滚动、50MB 分片、7 天历史和 20GB 归档上限,是有用的对照。但它位于 src/test/resources,不能说生产已具备同样保护;归档上限也不是整个文件系统的硬配额,活动文件、采集缓冲和其他日志仍占空间。

后台 pattern 在 logback.xml#L6〔本地文件〕 带 %method,%line,获取调用者信息有成本;高吞吐热路径应实测它对 CPU 与分配的影响。参数化日志能避免无谓字符串拼接,却不能避免参数表达式提前执行:log.debug("{}", expensiveSerialize(obj)) 在 DEBUG 关闭时也会先求值。更重要的是不要把整个请求、SQL 参数或响应对象记录下来;白名单字段才能从源头限制隐私泄露和体积。

异步 appender 把写入移到后台,并没有消除 I/O。队列满时会丢弃、阻塞还是施加背压,要按实际配置与版本核对;进程突然退出还可能丢失缓冲事件。审计要求不能简单靠“改成异步”满足,应区分诊断日志、业务审计与可靠业务事件。日志系统失效也需要独立指标,否则你只会看到一段令人误判为“恢复了”的安静期。

3. MDC 是线程上下文,不是自动分布式追踪

商品服务的 TraceIdFilter.java#L27〔本地文件〕 先读 RPC attachment,再从 MDC 取 X-B3-TraceId,非空时写回双方。报表服务的 对应过滤器#L27〔本地文件〕 具有相同结构。两者在 invoker.invoke 周围未显示 finally 恢复,也没有在值为空时生成新的 trace 标识。这只能证明这两个方法的局部行为;外层过滤器可能负责创建或清理,是否串线必须结合完整调用链测试。

线程复用时,残留 MDC 可能让请求 B 继承请求 A 的标签;切到线程池时,原线程上下文又不会天然正确传播。下面是教学包装器的关键思路,未提交到业务代码;上下文只应传白名单诊断字段,不承担鉴权。

// 在提交线程调用 wrap;在执行线程保存并恢复原上下文。
static Runnable wrap(Runnable task) {
    Map<String, String> captured = MDC.getCopyOfContextMap();
    return () -> {
        Map<String, String> previous = MDC.getCopyOfContextMap();
        try {
            if (captured == null) MDC.clear();
            else MDC.setContextMap(captured);
            task.run();
        } finally {
            if (previous == null) MDC.clear();
            else MDC.setContextMap(previous);
        }
    };
}

为什么恢复 previous 而不是一律 clear?嵌套执行或 CallerRuns 可能让任务在调用线程直接运行,一律清除会破坏外层上下文。RPC attachment 也有自己的作用域,不能只修 MDC 就声称整个传播链正确。外来 trace 字段必须校验长度和格式,防止换行注入与过大标签;trace 不是登录身份,不能拿它判定租户。当前后台 pattern 没有 %X{X-B3-TraceId},所以有 MDC 也不等于已有文本日志会显示它。

4. 把日志设计成能计算的事件

结构化事件以 schema 为边界。教学实验使用 request_completed,每次请求完成只记一次,包含带时区的时间、事件 ID、服务、路由模板、trace、状态、业务 outcome 和毫秒耗时。事件 ID 用于去重,trace 用于关联;一个 trace 下可以有多个不同服务事件,因此不能用 trace 去重请求。路径必须归一化为模板,禁止把订单号塞进指标标签。

{"ts":"2026-01-01T00:00:08Z","event":"request_completed","event_id":"e08","service":"demo-api","route":"/orders/{id}","trace_id":"t08","status":503,"outcome":"error","duration_ms":900}

JSON 编码器应负责引号、换行和异常字符串转义,不要通过字符串拼接伪造 JSON。时间戳用于跨事件关联;单次耗时应来自单调时钟,避免墙上时钟调整造成负值。JSONL 一行一个事件适合逐行读取,但多行异常堆栈需要封装进字段;不能把每个栈帧当一个失败请求。

离线实验 实现严格校验、半开时间窗口、重复事件识别及 nearest-rank p95。坏行只输出原因计数,不回显内容,避免二次泄露;未知业务结果按失败计算;零样本返回 null,避免把没有数据误认成 100% 成功。分析器在读入前不需要任何业务配置,只处理仓库中的虚构样本。它保存窗口内事件和耗时,精确分位数会占用随样本数增长的内存,因此设置输入行数与行长上限,不能直接替代生产日志平台。

5. 故障推演:ERROR 减少了,用户却更不满意

设想一次发布后 ERROR 行数从每分钟 100 降至 20,但请求数从每分钟 1000 降至 100。错误行少了,错误比例可能更高;若一次失败有五段堆栈,行数与请求数又完全不同。进一步排查发现重试循环由 ERROR 改为 WARN,查询只检索 error 文件,观测口径也变了。此时“错误减少 80%”没有业务意义。

应先固定窗口、入口服务、完成事件 schema 与去重口径,再统计失败请求数和总请求数。对照部署版本和采集丢失率,确认样本覆盖是否变化。然后从慢请求或失败事件抽取 trace,回查关联服务。若 trace 在切线程后消失,先验证传播;不能直接认定下游没有收到。最后把日志结论与入口计数器、客户端体验对齐,形成可以被反驳的解释。

事故中还有两种常见的“有日志却不可用”:文本时间只含时分秒,跨天合并后顺序混乱;机器时区不同,简单字符串排序把事件排错。实验将所有有时区时间转换为 UTC 后比较,并使用 [start,end),相邻窗口不会把边界事件重复计入。缺少时区的日志应明确按什么来源补充,不能默认为分析者本机时区。

查询实战还需要处理延迟到达。事件发生在一分钟窗口内,但采集器可能在下一分钟才送达;若按采集时间统计,问题会被平移到错误窗口。离线分析器使用事件的 ts,不实现实时水位线;生产查询应规定允许的迟到范围,并在窗口稳定后重新计算。迟到不是重复,重发的相同事件才需要去重,不能用“只收第一次时间范围”的办法同时解决两者。

schema 变更也要像接口变更一样管理。例如旧版本耗时单位为毫秒,新版本误改为秒但字段名不变,p95 会突然好看一千倍。校验类型无法发现这种语义错误,需要字段命名、版本契约、合理值域和代表性样本验证。新增 outcome 枚举时应先让消费者理解它;未知值不能默认 success。最终查询报告应写清输入覆盖、时间窗口、单位、过滤规则和去重方式,让另一位同事能用相同输入复算,而不只是贴一张无法追溯的图。

6. 练习与答案

练习一: root 为 INFO,某个子 logger 为 DEBUG 且绑定独立 appender。为何仍有 DEBUG 文件?

答案: 有效级别由子 logger 决定,appender 自己还会过滤;父 logger 的 INFO 不会重新否决所有向上传播的事件。要检查 additivity 与 appender filter,不能只看 root。测试应覆盖各级别各发一条并核验目标。

练习二: 线程池任务结束时 MDC.clear(),是否永远正确?

答案: 不一定。若运行在线程原有诊断上下文之内,clear 会删掉外层信息。提交时捕获,执行时保存 previous,finally 恢复,并对异常、嵌套和 CallerRuns 情况测试。鉴权与租户上下文要另外设计,不能借用 trace 传播替代。

练习三: 两条日志 trace 相同但事件 ID 不同,能去掉一条吗?

答案: 不能。它们可能来自同一请求的不同服务或不同阶段。实验只按事件 ID 去重,并对同一 ID 不同内容单独报告冲突;冲突意味着统计可信度受损,需要检查生产端和采集端,不能悄悄选一个当真。

官方参考

路由与滚动机制见 Logback Appenders,上下文范围见 Logback MDC,精确级别与阈值区别见 Logback Filters。实验解析基础见 Python json 与 datetime。

原始文档 · operations-course/03-指标告警SLO链路追踪排障.md

03 指标、告警、SLO 与链路追踪:从红灯走到证据

开发者经常把“装一个监控面板”当成可观测性建设。面板只能展示已经定义好的数据;如果分母不完整、标签无限增长、失败被当成功,再漂亮的图也会误导。ERP 用户关心的是能否及时查单、库存是否准确、导出是否完成,不是某个 JVM 是否拥有一个 PID。本章从用户旅程定义目标,再建立指标到日志、追踪和现场状态的证据链。

1. 三种信号各回答一个问题

指标把大量事件压缩为时间序列,适合回答“什么时候开始、大概影响多少、哪个维度异常”;日志保留具体事件,适合回答“这次为什么失败”;追踪描述一次调用跨服务的阶段关系,适合回答“时间花在哪、哪个环节传递了错误”。它们应共享服务、版本、实例等有限维度,用 trace 标识连接具体事件,但不应把每个 trace 变成指标标签。

一个 Counter 表示累计完成数量,要通过时间窗口内的增量或速率解释,不能把当前值当每秒请求。进程重启会让计数器归零,直接做差可能出现负数;查询系统的 counter rate 会处理常见重置。Gauge 描述当前值,如队列长度与活跃连接;Histogram 把观察值累计进桶,可聚合多个实例的分布。均值把长尾压平,最大值易受单个异常干扰,分位数才适合表达“多数用户”与尾部体验,但也有采样和桶精度限制。

下面是教学指标,未证明项目已经暴露这些名字。为避免把 HTTP 200 业务失败漏掉,完成计数器直接带 result=success/error/unknown 这个有限枚举。

# 必须配合有流量条件;零分母不能伪装成成功。
sum(rate(demo_request_completed_total{result!="success"}[5m]))
/
sum(rate(demo_request_completed_total[5m]))

# 经典 histogram:先聚合各实例的桶,再算分位数。
histogram_quantile(0.95,
  sum by (le, service) (rate(demo_request_duration_seconds_bucket[5m]))
)

不能平均各实例 p95。设实例 A 处理 10000 次请求,实例 B 只处理 10 次,平均两个 p95 相当于把它们当同样重要,还丢掉了分布。聚合经典 histogram 时必须保留 le,且各实例桶边界可兼容。桶设为 0.1、0.3、1、3 秒,无法精确描述 500 毫秒目标边界;面向 SLO 应在目标处设计桶或直接计数好事件。实例级图仍需保留,否则总量可能掩盖一个坏实例。

2. 为 ERP 用户旅程写出可以算的 SLO

SLI 是测量结果,SLO 是带窗口的目标,SLA 是对外承诺及责任安排,三者不能混用。以“订单详情查询”为教学旅程:在滚动 30 天内,合格请求中业务成功且入口到完整响应不超过 500 毫秒的比例至少 99.9%。必须事先约定认证失败、参数错误、用户主动取消、网关限流是否属于合格请求,并在发布前固定规则,不能事故后排除最差请求美化统计。

好事件可以定义为 业务成功 ∩ 耗时达标,坏事件就是合格请求减好事件。一次失败又超时只计一个坏事件,不能把错误率与慢请求率简单相加导致重复扣预算。日志实验使用 HTTP 200—399 且 outcome=success,再加入 500 毫秒条件,这是教学契约;真实接口如果 3xx 不算业务完成,应调整契约而非照搬数字。

请求型 SLO 的错误预算是 合格请求总数 × (1 - 目标)。若一个月有 200 万次合格请求、目标 99.9%,预算为 2000 个坏事件;不能自动换成“停机 43.2 分钟”,那是按时间比例计算的另一种口径,只有流量条件适合时才有近似联系。活动高峰一分钟失败与凌晨一分钟失败,对请求预算消耗可能相差百倍。

窗口 burn rate 等于 当前坏事件比例 / 允许坏事件比例。教学样本 40% 的坏事件率除以 0.1% 得到约 400,意味着此错误比例持续时消耗预算的速度远高于目标,并不意味着已经消耗 400 个月预算。想换算消耗份额,还需窗口长度与流量占比;请求流量不均时不能只按时间外推。

异步导出更要重新设计分母。提交接口返回“已受理”只完成第一个旅程,用户关心的可能是 10 分钟内拿到完整文件。导出完成率应按有足够观察时间的已受理任务批次统计,同时看最老待处理任务年龄,避免尚未超时的新任务被提前判坏,也避免只数完成事件把永远挂起的任务从分母里抹掉。库存同步同样需要端到端新鲜度,而不只是消费者是否在线。

3. 告警必须能引导动作

CPU 超过某阈值不是用户故障的充分条件,但可以作为容量预警;SLO 快速消耗需要值班响应,慢速消耗可能进入日间处理。设计告警时,把影响、时间窗口、流量、持续性和动作写在一起。短窗口响应快却容易被瞬时抖动触发,长窗口稳定却恢复慢,因此可以要求长短两个窗口都超过预算消耗阈值,而不是仅靠一根尖峰。

例如教学规则把“1 小时及最近 5 分钟的 burn rate 均超过 14.4”用于快速消耗提示,另设更慢的观察规则。这个数字来自一种 30 天预算分配思路,不是所有业务的标准答案。低流量业务还要结合请求数量、合成检查或任务年龄:十分钟只有一次失败会得到 100% 错误率,却与百万请求中的 100% 不同。不能只加最小流量门槛,导致夜间彻底无监控;需要用独立的缺数据/不可达信号补足。

告警内容应能直接定位“哪个旅程、何时开始、影响多少、当前版本、进入哪个 Runbook”。依赖服务已告警时可抑制重复通知,但不能删除业务影响证据。关闭告警不等于恢复,静默时间应有到期机制;恢复条件应包括用户指标正常、积压消退和数据正确。预警、事故、数据质量异常要有不同处理方式,避免值班者被无行动价值的消息淹没。

4. 真实项目中的信号接点与缺口

ThreadPoolConfig.java#L32〔本地文件〕 暴露普通线程池 Bean,可以围绕活跃线程、队列长度、排队时间和拒绝次数设计埋点;它采用 CallerRuns,单看“拒绝异常数为零”不能说明没有过载,因为任务可能已经转移到提交线程。应单独记录发生这种退让的次数和提交端延迟。这里是改造建议,本次没有增加埋点,也没有证明已有面板覆盖这些指标。

AsyncManager.java#L45〔本地文件〕 的调度调用适合测量“提交到开始”和“开始到完成”两个阶段;若只测任务内部执行,就会遗漏最长的排队。已读的 TraceIdFilter.java#L28〔本地文件〕 传播一个 B3 trace 字段,却没有展示 span 生命周期、父子关系或采样决策,因此不能因为有 trace ID 就断言已有完整链路追踪。

教学时序可以这样拆:

入口 span ────────────────────────────────── 完成
   排队 ─── 业务 span ────────────────────────
               DB span ─────
               RPC span ───────────
                                   序列化 ──

并发 DB 与 RPC span 的时长不能简单相加,父 span 包含子 span,重复相加会超过请求总时长。相同 trace 能关联,不自动证明因果;父子关系、实际发送/接收和统一时钟口径才支持解释。异步消息可以用传播上下文或 link 表达关联,长任务不必强行保持一个持续数小时的同步请求 span。

标签治理是稳定性问题。service、route 模板和 result 通常可控;订单号、完整 URL、用户 ID、异常原文若作为标签,会形成大量时间序列,占用监控系统内存并拖慢查询。具体 trace 放日志或 exemplar,敏感字段按白名单脱敏。采样追踪不能直接当全量失败率:头部采样可能漏掉少量失败,尾部偏向慢/错请求又会改变样本分布,SLO 应来自完整口径计数。

5. 故障推演:CPU 不高,订单接口 SLO 快速消耗

教学现场中,入口吞吐不变、延迟桶向长尾移动、连接池活跃数触顶,线程栈反复停在借连接,数据库执行耗时却没有同步恶化。可能是长事务持有连接、连接归还遗漏或池容量与并发不匹配。此时直接扩应用实例可能增加数据库连接总数,使依赖更差。需要对照事务持续时间、连接借用/归还和实例总量,才有条件区分原因。

若追踪显示大部分时间在 DB span 外,还应确认 span 是否从获得连接后才开始;埋点边界可能漏掉连接等待。若日志没有错误,可能请求尚未完成,也可能 WARN 路由有缺口。把三种信号互相校验,才能发现“面板没画出来的时间”。恢复验收不仅看 p95 回落,还看失败率、最老积压和数据一致性;发布回滚成功也不能自动证明先前超时请求没有重复落库。

6. 练习与答案

练习一: 1000 次请求里 10 次失败、20 次慢,其中 8 次既失败又慢,坏事件多少?

答案: 联合条件的坏事件是 10+20-8=22,好事件 978;目标 99.9% 时 burn rate 为 0.022/0.001=22。如果失败与慢的分母不同,这个计算无效,先统一合格请求集合。

练习二: 两台机器 p95 为 100 毫秒与 1 秒,系统 p95 是 550 毫秒吗?

答案: 无法从这两个数推出。需要请求分布或可合并桶及请求数量;均值分位数没有整体分位数的数学含义。还需查看是否只有某个实例或路由异常。

练习三: 追踪面板没有错误 span,日志也没有 ERROR,是否可以关闭事故?

答案: 不能。采样、未完成请求、传播中断、采集失败和错误日志路由都能产生空白。用独立入口完成计数与用户旅程验证,并确认积压和数据补偿完成,再按恢复条件关闭。

官方参考

告警预算方法见 Google SRE:Alerting on SLOs;聚合分位数见 Prometheus Histograms and summaries;传播机制见 OpenTelemetry Context propagation。这些工具是教学拓展,不代表业务仓库已部署相应平台。可以用 日志实验 手算并验证本章的联合 SLO。

原始文档 · operations-course/04-Maven-CICD容器发布回滚配置密钥治理.md

04 Maven、CI/CD、容器与回滚:发布的是可追溯的系统状态

前端打包成功与网页能访问之间隔着上传、缓存、路由和运行配置;Java 后端同样如此,还增加了 JVM、依赖连接、数据库兼容和在途事务。“BUILD SUCCESS”只描述执行过的构建目标,不表示测试运行、部署成功或用户业务恢复。可靠发布需要把源码、依赖、制品、配置与数据结构的关系固定下来,并为每一个阶段定义可观察的成功条件。

1. Maven 生命周期不是一条万能命令

Maven 把 validate、compile、test、package、verify 等阶段串起来,插件目标绑定到阶段后才实际工作。package 常产出 jar,install 放入本地 Maven 仓库,deploy 通常把制品上传 Maven 仓库,并不等价于把服务部署到生产。前端熟悉的 npm build 与发布脚本也有类似边界,但不能因为名字相近就互换概念。

多模块 Reactor 负责模块构建顺序;-pl 选模块,-am 连同所需上游模块一起构建。dependencyManagement 约束依赖版本但不自动引入依赖,pluginManagement 提供插件配置但也不等于所有目标已经执行。为了判断实际行为,应沿父 POM、激活 profile、插件配置和流水线参数核对,不能只看到一段插件声明就说它运行过。

本次读到的事实有三种不同跳测方式:商品根 POM#L82〔本地文件〕 设置 maven.test.skip=true;报表根 POM#L347〔本地文件〕 的 dev profile 内也设置这个属性;RDS 根 POM#L29〔本地文件〕 设置 skipTests=true,并在 第 714 行〔本地文件〕 把它接到 Surefire 的 <skip>。这些文件可以说明默认配置风险,却不能证明某次 CI 没有通过命令行覆盖。

还有 SCM 根 POM#L316〔本地文件〕 直接写 <skip>true</skip>。不能不检查有效配置就承诺一条通用 -DskipTests=false 对所有项目生效。skipTests 通常跳过执行、仍编译测试;maven.test.skip 被相关插件支持时还会跳过测试编译。真正的验证证据是选定模块和 profile 下的测试报告、用例数量与退出码,测试为零也需要解释。本次不运行这些仓库的 Maven,因为测试可能加载外部依赖配置。

2. 构建一次,晋级同一制品

后台模块 POM#L146〔本地文件〕 绑定 Spring Boot repackage,且 第 169 行〔本地文件〕 指定最终名称;商品 Web POM#L230〔本地文件〕 指定 erp-item-web 并配置 repackage。可执行 jar 和普通 jar 不是只改个扩展名:启动器、依赖布局和入口处理都可能不同,所以验收必须使用最终制品。

商品根 POM 的 第 893 行〔本地文件〕 定义 dev profile,在第 912 行设默认激活,并在 第 1141 行〔本地文件〕 对资源开启过滤。Maven profile 是构建时选择,Spring profile 是运行时选择,二者可能通过过滤桥接,却不是一个开关。若每个环境重新构建并换一组 SNAPSHOT 依赖,“同一提交”仍可能得到不同字节;回滚到旧提交再构建也未必得到旧制品。

更容易审计的设计是固定源码修订、JDK/Maven、依赖与插件来源,构建后记录制品摘要,晋级相同摘要,并让受控环境配置在运行时注入。若现有架构必须按环境构建,就要为每个构建分别保存依赖清单、过滤参数的非敏感版本标识和制品摘要,不能宣称它们是完全相同的包。锁定版本也不代替安全升级,更新应作为可回滚的独立变更验证。

教学流水线可以用如下状态机表达;它不是仓库现有 Jenkinsfile,也未执行:

固定源码与依赖
 → 编译与测试报告
 → 打包并计算摘要
 → 制品存储、权限与来源校验
 → 注入指定配置版本
 → 小范围启动、就绪与业务验证
 → 逐步接流量、观察 SLO
 → 晋级完成 / 停止扩量 / 回滚已知摘要

每一箭头都应记录开始结束时间和结果。上传成功不是服务启动成功,端口监听不是业务就绪,单次健康请求也不是长尾和积压已恢复。灰度需要明确样本选择与观察窗口,避免只给内部用户或缓存命中请求而漏掉真正高风险路径。

3. 从现有 Dockerfile 学会读容器边界

商品 Web Dockerfile#L1〔本地文件〕 内容很短:基础镜像为 java:8,把 jar 复制为 App.jar,声明端口,并以 exec 形式启动 Java。这里没有证明镜像实际构建过,更没有证明部署平台是什么。EXPOSE 只是镜像端口元数据,不会自动打开主机端口;exec 形式让 Java 成为容器入口进程,信号路径比额外 shell 包装清楚,但应用仍要正确处理关闭。

该文件没有显式固定镜像 digest、设置 USER、配置健康检查或声明资源限制;不能因此推断生产一定以 root 运行或没有限制,因为运行平台可以覆盖部分设置。可以提出需要核验的事项:实际镜像身份、基础镜像更新来源、非特权用户、只读目录需求、临时空间、CPU/内存预算与关闭宽限期。不要仅凭 java:8 标签就宣布存在某个具体漏洞,漏洞判断需要实际镜像包版本与扫描证据。

容器内存上限不是 Java 堆上限,CPU 限制也不是线程数限制。若只给 1GiB 内存却设置 -Xmx1g,元空间、线程栈、直接内存和运行时开销可能把容器推到上限;“堆还没满就退出”完全可能。镜像层删除曾写入的凭据不能保证历史层里没有残留,凭据不应通过 COPY 或持久化构建参数进入镜像。发布包的可复用性与秘密的最小暴露必须同时考虑。

4. 配置与密钥有各自生命周期

普通配置应可比较、可追踪,秘密应只记录引用与版本,不打印内容。环境变量便于注入,但可能被诊断输出、进程转储或错误报告捕获;挂载文件也需要权限、轮换和读取时机设计。不能把“不是写在 Git 里”当治理完成。构建日志、有效 POM、完整环境转储及启动参数都可能意外暴露内容,因此本教程不展示业务配置,不以全量打印配置作为排障第一步。

轮换需要先识别使用者,再准备新旧凭据兼容窗口,验证客户端是否会重新加载、连接池是否需重建,最后停用旧版本并审计。若只更新服务端凭据而应用持有旧连接或旧缓存,故障可能延迟出现;若新旧版本混跑,回滚旧代码也可能拿不到已撤销的秘密。发布记录应包含“配置版本与凭据引用”,但绝不包含秘密本身。

数据库结构是另一种发布状态。新增可空列、兼容旧读写、分批回填、切换读写路径、最后删除旧结构,是一种 expand-contract 思路。先删旧列再发布新代码,回滚旧 jar 也救不回来。回滚策略必须说明数据是否已发生不可逆变换,以及需要前滚修复还是业务补偿;“保留上一个镜像”只是必要条件之一。

5. 故障推演:两个构建都成功,只有一个发布失败

教学场景中,一次成功与一次失败流水线都出现相同依赖警告,也都产出了 jar;失败运行在发布 API 阶段得到 HTTP 500。正确结论是当前证据把失败定位在发布阶段,服务端根因仍未知。不能因警告刺眼就归因依赖;同样不能看到 500 就认定服务器磁盘满,可能是认证、元数据、下游发布代理或内部异常,必须取得相应阶段证据。

逐阶段对比应包括工具版本、解析到的依赖、测试是否执行、制品摘要、上传响应、部署任务标识和状态转换。任何日志都先去敏感内容,保留阶段及关联 ID。若发布接口已受理但响应超时,盲目再次提交可能创建并行发布;先用任务身份查状态。恢复后还要确认线上运行摘要、配置版本、就绪状态及业务指标,不能仅凭下一次构建变绿关闭问题。

现有 ry.sh#L24〔本地文件〕 按进程列表匹配名称,第 29 行后台启动后立即输出成功,第 45 行发送 TERM 并循环等待。它没有在该路径等待业务就绪,名称匹配也可能碰到多个进程;这些是脚本级风险,是否影响部署尚未验证。本次只读脚本,未执行启动、停止或重启。可靠控制应使用明确的实例身份、启动结果、关闭期限和恢复判据。

6. Kubernetes 拓展:三个探针不是三个重复接口

本次按约定文件名检索没有发现可说明现状的 Kubernetes 清单,以下仅是拓展。startup 探针容纳启动期,readiness 控制是否接收流量,liveness 用于判断是否需要重启。把共享数据库可用性直接绑到所有实例的 liveness,可能在数据库短暂故障时重启全体应用,制造连接风暴。readiness 也要按依赖的重要性设计,不能因为非关键服务短暂失败就把所有容量摘除。

优雅退出顺序通常包括停止接新工作、摘流量并等待传播、处理有上限的在途工作、释放资源。容器宽限期必须覆盖实际关闭时间,但又不能无限等待。现有线程关闭逻辑在下一章与第 06 章继续分析;不要从 Kubernetes 默认值直接推断这套项目的关闭保证。

7. 练习与答案

练习一: 提交相同就能重新构建出可回滚的同一制品吗?

答案: 不一定。SNAPSHOT、插件、基础镜像、构建 JDK、资源过滤和外部下载都可能变化。应保存并校验原制品摘要,以及兼容的配置和数据结构;回滚优先选择已验证的原摘要。

练习二: CI 显示 BUILD SUCCESS,测试数量是零,应如何报告?

答案: 报告构建目标成功、测试未得到执行证据;检查跳测属性、插件有效配置、测试发现规则和目标模块。不要把零用例称为“全部测试通过”,也不要为了验证在未知环境启动连接业务库的测试。

练习三: 回滚旧镜像后仍报列不存在,原因是什么?

答案: 应用版本与数据库结构不兼容。镜像回滚不能自动恢复已删除的列及数据;需按预先设计的兼容迁移、前滚修复或受控恢复方案处理。还要核对配置和凭据是否支持旧版本。

官方参考

跳测语义见 Maven Surefire 官方说明,镜像指令语义见 Dockerfile reference,探针分工见 Kubernetes 官方探针文档。这三份资料对应不同层次,不能互相替代部署验证。

原始文档 · operations-course/05-JVM-GC内存CPU事故诊断.md

05 JVM、GC、内存与 CPU:让诊断结论经得起反证

前端开发者熟悉对象可达性、闭包保留和浏览器 GC,但 Java 服务经常持续运行数月,线程池、连接池、缓存、任务队列会长期持有对象。事故中的高内存不一定是泄漏,高 CPU 不一定是业务死循环,长时间无日志也不一定是 GC。正确顺序是确认现场版本、资源边界和故障时间,再选择成本最低且能区分假设的证据。

1. 先确认使用哪种 JVM,再解释参数

后台根 POM#L19〔本地文件〕 的 java.version 是 1.8,说明项目编译目标的配置意图,不能证明线上进程运行的就是哪个 JDK 发行版和补丁版本。ry.sh#L6〔本地文件〕 配置初始堆 512m、最大堆 1024m、最大元空间 512m、Parallel GC 及 Java 8 风格 GC 输出参数。这是脚本事实;容器入口、平台参数或其他启动方式可能完全不同。

参数还存在版本边界。Java 8 的 PrintGCDetails、PrintGCDateStamps 与较新 JDK 的统一日志体系不是同一写法,不能把一套命令复制到所有运行时。Parallel GC 偏重吞吐,与低暂停目标之间需要权衡;看到停顿就切到另一个收集器不是完整优化方案,还要核对 JDK、堆大小、对象分配模式、CPU 配额和延迟目标。配置写了某个收集器,也应通过受控运行时证据确认它真的启用。

该脚本开启 HeapDumpOnOutOfMemoryError,但 第 29 行〔本地文件〕 把控制台输出丢弃。GC 输出若没有另设持久化去向,可能失去关键诊断材料;OOM dump 则可能写到默认位置,受空间与权限影响。不能把“有这个参数”当作“事故一定有完整 dump”。转储可能含凭据与个人信息,不应直接上传公共分析网站或聊天;本次没有查看、生成或复制任何业务转储。

2. 堆只是进程内存的一部分

堆容纳大部分对象;元空间保存类元数据;线程栈保存调用帧;直接缓冲区、JNI、本地库、JIT 代码缓存及运行时结构还消耗其他内存。RSS 描述驻留物理页,虚拟地址空间还包括保留区和映射,二者都不能直接等同 -Xmx。容器的内存记账又可能包含该 cgroup 的其他进程、页缓存等,用单个 Java 堆图解释全部容器内存会漏掉重要部分。

因此至少要分辨几类失败:Java heap space 指向堆分配问题;Metaspace 指向类元数据空间;unable to create native thread 可能与原生内存、进程/线程限制有关;直接内存错误与缓冲区分配相关;容器被内核终止则可能没有 Java OOME 栈。退出码 137 通常与 SIGKILL 相关,但不能仅凭它断定 OOM,人工终止或平台动作也可能产生相同现象,需要结合 cgroup 事件和平台终止原因。

教学预算可写成:

容器上限 > Java 堆 + 元空间 + 栈 + 直接/原生内存
             + 运行时与记账开销 + 安全余量

这不是固定百分比公式。每个区域的实际驻留随工作负载变化,线程栈保留大小也不等于立刻全部提交。正确做法是从代表性峰值与长期运行的测量建立预算,给可增长资源设边界,而不是把容器限制全部交给 Xmx。

3. GC 图要看斜率、回落和暂停,而不是只看锯齿

多数短命对象被分配后很快失去引用,周期性回收形成锯齿是正常行为。分配速率上升、年轻代变小或存活对象增加,都会改变回收频率。暂停增多可能拖慢服务;反过来,下游变慢让更多请求及其上下文存活,也可能增加堆压力。因此“GC 多”和“接口慢”同时出现,只证明相关,需要判断先后关系。

教学观察窗口里,若每次较完整回收后占用基线持续抬高,应调查保留对象;但缓存预热、业务基数增长和队列积压都能导致基线上升,未必是生命周期错误。内存泄漏的核心是已不需要的对象仍被强引用保留。用支配树、保留大小和 GC roots 路径解释“谁留住了它”,比看某类对象数量第一名更有意义。一个共享数组可能被多个对象引用,不能把每个引用的 retained size 简单相加。

真实反例来自 HttpUtils.java#L79〔本地文件〕:方法循环读取全部响应并追加到 StringBuilder,第 85 行还记录结果。若返回体很大、并发很高、日志编码又产生临时副本,会推高分配与峰值内存。源码证明全量累积行为,但未证明实际有超大响应或事故。改造方向包括响应上限、流式解析、分页和受限日志;这些比单纯增大堆更接近对象生命周期问题。

另一个对象保留点是 AsyncManager.java#L45〔本地文件〕 提交的任务。队列里的 Runnable/TimerTask 可能通过闭包或成员保留整批订单。即使工作线程只处理小批量,大量待执行任务仍会把大对象留在堆里。将队列长度与回收后基线画在同一窗口,若积压消退后基线回落,更支持容量或背压问题;若任务结束后仍有静态集合持有它们,则需要继续查生命周期。

4. 从被动读数到有成本的诊断

先检查已有指标、既有 GC 记录、进程状态和容器事件。下面仅是 Linux 隔离环境模板,本次没有对业务进程执行。它不打印命令行或环境变量,PID 是占位编号。

PID=12345
ps -L -p "$PID" -o pid,tid,stat,pcpu,comm
awk '/^(State|Threads|VmRSS|VmSize):/' "/proc/$PID/status"
# 在确认的 cgroup v2 目标目录中,只读以下资源文件:
# memory.current、memory.max、memory.events、cpu.stat

必须先确认目标 cgroup 路径和版本,不能默认宿主根目录就是容器组。看 memory.events 的变化而不是只看历史累计值;看 CPU throttling 是否在故障窗口增长,而不是把宿主 CPU 空闲当容器容量充足。cgroup v1 文件和语义不同,需按实际环境选择文档。

若上述证据不足,再评估 attach 工具。jcmd PID help 可以确认当前 JVM 支持哪些命令;Thread.print 获取线程快照,GC.heap_info 查询堆信息。它们用于诊断但不是绝对零影响:attach 可能建立本地通信文件,线程转储可能造成短暂停顿,权限、命名空间和 JDK 版本也影响可用性。本教程只展示名称,不对未知 PID 发命令。用相容工具、已确认身份及受控输出路径取证,不直接打印全部 system properties 或 command line。

堆转储、对象直方图、强制 GC 和 JFR 必须进一步区分。有些选项会触发收集或显著停顿;大堆 dump 会占磁盘、增加 I/O,并包含业务数据。JFR 支持取决于发行版及版本,不能假定所有 Java 8 都有相同能力。Native Memory Tracking 通常需要启动时启用,事故发生后不能凭空补回历史。工具不可用不意味着 JVM 没问题,应回到已有指标与隔离复现实验,而不是强行附加多个高开销工具。

5. CPU 事故与等待事故的两条路径

高 CPU 时,先连续观察线程 CPU 增量,再把热点线程的十进制 TID 转为十六进制,与 Java 平台线程转储中的 nid 关联。只看一次快照可能恰好抓到正常序列化;若连续多个窗口都落在同一循环、正则、压缩或序列化路径,证据才增强。还要区分 GC 工作线程、JIT 编译线程和业务线程,否则会给错误模块做优化。虚拟线程与平台线程映射不同,不能把此 Java 8 经验不加说明地搬到所有新运行时。

低 CPU 高延迟时则看等待。大量 WAITING 可能只是空闲池线程,不能认定死锁;BLOCKED 指向 Java 监视器竞争,socket 读取也可能显示 RUNNABLE,不能按状态名字把它判为忙计算。要阅读栈与等待对象、观察持续性,并找到持有资源的一方。锁死循环、连接池等待、外部 I/O 阻塞应有不同证据和不同恢复动作。

启动慢也应用同样方法。假设两条初始化日志中间相隔 34 秒,这只是一个待解释区间;中间可能是远程初始化、类加载、锁竞争或没有埋点的计算。应该在同一次启动的区间中采样线程和资源,不能拿上周一次依赖异常充当本次原因。本文未启动任何业务 JVM,也没有本次启动耗时测量。

6. 故障推演:扩堆后更慢,容器最后退出

教学场景中,导出任务突然增多,队列增长、回收后老年代基线抬高,CPU 大部分消耗在 GC。第一反应把 1GiB 堆改成 2GiB,但容器限制仍为 2GiB,原生内存又无余量。大堆可能延后 Java OOME,却提高驻留量并加重回收工作,最终进程被终止,预期的 OOM dump 也没有出现。

证据链要分别回答:是哪一个限制触发终止?对象为什么仍存活?进入速度为何超过完成速度?若队列保留整批数据,处理应围绕任务粒度、并发上限、背压和流式输出,同时复核容器与 JVM 的预算。止血可以减少导出入口负载;具体执行需另行授权与验证,本章不修改任何参数。恢复成功不能只看重启后内存下降,还要看峰值流量下队列收敛、GC 暂停、请求 SLO 和导出完整性。

7. 练习与答案

练习一: RSS 持续增长但堆使用基本稳定,下一步是什么?

答案: 检查线程数、元空间、直接缓冲区、本地分配及映射,结合容器记账和已有 NMT 数据;不能直接称为 Java 堆泄漏。若没有 NMT,先用低成本指标缩小范围,再设计启用诊断的隔离复现,不能凭一次 RSS 值推导对象保留链。

练习二: 一次线程转储出现 200 个 WAITING,能否宣布线程死锁?

答案: 不能。空闲队列、定时等待和正常锁等待都会出现。需要看等待对象、持锁线程及循环关系,并结合多次快照;同时确认业务线程是否还有进展。线程数量与阻塞原因不是同一问题。

练习三: 开启 HeapDumpOnOutOfMemoryError 后进程以 137 退出却没有 dump,配置一定无效吗?

答案: 不一定。可能是内核/平台发 SIGKILL,没有机会由 JVM 处理 OOME;也可能转储路径无权限、空间不足或启动参数未生效。先查当前事件的终止原因和版本,不要为获得 dump 在现场强制触发 OOM。

官方参考

版本化原理参考 Java 8 GC 调优指南;诊断命令及影响分级参考 JDK 17 jcmd 手册,使用时仍以目标 JVM 的 help 为准;容器资源字段参考 Linux cgroup v2。对象及线程池背景可衔接 Spring 线程池与背压。

原始文档 · operations-course/06-备份恢复容灾Runbook故障演练.md

06 备份、恢复、容灾与 Runbook:证明数据和业务都回来了

运维能力的底线不是“昨天备份成功”,而是故障发生后能否在承诺时间内恢复到可接受的数据状态。ERP 订单、库存、履约、结算之间有业务约束:库能启动、表能查询,却可能重复发货或漏记库存。恢复必须同时回答技术可用性、数据完整性和外部副作用。本章只设计方案与桌面推演,不连接数据库、不执行备份、恢复、切换或删除。

1. RPO 与 RTO 要从用户损失定义

RPO 表示允许丢失的数据时间范围,RTO 表示允许的恢复时间目标。假设故障在 10:00,最新可验证的恢复点为 09:58,那么未覆盖窗口约两分钟;不能因为备份任务每分钟启动一次就声称 RPO 一分钟,还要看任务是否完成、日志是否持续归档、是否能解密并恢复。RTO 应从约定的业务中断时刻开始计,包含发现、判断、取回数据、恢复、验证和接流量,不应只计算数据库进程启动时间。

目标应按业务分层。商品图片索引可能允许较长重建时间,订单主记录通常要求更严格;缓存丢失可能影响性能,幂等记录丢失却可能造成重复业务动作。把所有 Redis 数据都当可丢缓存,把所有数据库都当同一 RPO,会掩盖最重要的损失模式。还需说明恢复后是否允许只读、哪些写操作暂缓,以及用户如何获得真实状态。

复制与备份解决的问题不同。副本能提高可用性,但误删除、错误更新或恶意操作也可能复制过去;备份保留历史状态,但恢复耗时可能较长。异地副本如果共享账号、密钥和删除权限,也未必抵抗同一故障。容灾要考虑故障域:机房、账号、权限、软件版本及操作人员的错误,都可能让“两个副本”同时失效。

2. 恢复链必须连续,文件存在只是起点

关系数据库的时间点恢复通常由一个一致的基础备份与之后的事务日志共同构成。基础备份要知道对应的日志位置/事务身份;归档要连续且覆盖目标点;恢复工具和版本要兼容;加密材料要可用。少一段日志可能让看似完整的链条在关键点断开。快照文件通过校验和只能证明取回字节与记录匹配,不能证明快照应用一致,也不能证明业务外键关系、索引或数据内容正确。

逻辑备份方便检查和跨环境恢复,体积、导出导入速度与大表成本却可能显著;物理备份通常更贴近数据库存储布局,对版本、工具和恢复步骤更敏感。并发写入、DDL、非事务表都会影响一致性策略,不能认为“备份命令不写业务数据”就没有负载或锁影响。本次不展示可直接连接业务库的备份命令,技术细节衔接 数据库备份恢复章。

Redis 的 RDB/AOF 提供不同的持久化与恢复特性,但异步复制、持久化策略和故障时间仍影响丢失窗口。恢复缓存前先识别用途:可重建读缓存可以逐步预热,分布式锁不能直接当作故障后仍有效的所有权证明,计数器和去重键也不能随意清空。缓存恢复到较新状态、数据库却恢复到较旧状态,可能把旧库存展示成新库存,或者让幂等标记阻止本该补做的工作。

ERP 往往还有对象文件、消息、配置和外部平台状态。数据库记录导出成功,但文件未恢复,用户仍下载不到;数据库回到发货前,物流平台却已发货,重新执行会产生副作用。因此恢复清单应覆盖“权威记录、可重建派生数据、不可撤回外部动作”的关系。不是每个系统都必须回到完全同一秒,但必须有明确对账和补偿规则。

3. 真实线程关闭代码揭示“正常退出”的边界

AsyncManager.java#L51〔本地文件〕 把 shutdown 委托给 Threads.java#L42〔本地文件〕。该工具先 shutdown,等待 120 秒;未结束则 shutdownNow,再等待 120 秒,仍不结束只记录日志。注释里提到“强制退出”,但本方法没有执行强制退出 JVM 的动作。必须依据实现解释保障,不能把注释当执行证据。

shutdownNow 主要尝试中断执行线程并返回尚未开始的任务,不保证任务立刻终止,也不会自动持久化未完成业务。这里没有接收并保存返回任务列表。若队列里是仅存在内存中的重要任务,退出或崩溃可能丢失进度;是否存在这种业务路径,需要另查调用点,本文不宣称已发生丢单。ThreadPoolConfig.java#L51〔本地文件〕 将调度线程设为 daemon,也说明不能把“后台线程还在”当 JVM 一定会等待的保证。

任务可靠性应建立在持久化任务身份、可恢复状态、幂等动作和重试治理上。正常退出只是减少中断概率,不能替代崩溃恢复。即使有 shutdown 方法,还要验证生命周期是否实际调用,以及平台关闭宽限期是否覆盖这些等待。方法存在不等于退出路径已经连通。忽略中断的任务可能超过期限,提前强杀又可能留下“外部已成功、本地未确认”的未知结果。

4. 一份可执行判断、不可盲目执行操作的 Runbook

下面是虚构订单查询服务的恢复手册。目标为 RPO 不超过 5 分钟、RTO 不超过 30 分钟;这些是教学目标,不是公司承诺。实际危险操作以动作说明表达,由有权限的执行者在经过批准的隔离或生产流程中实施,本教材没有任何执行这些动作的脚本。

状态 所需证据与动作 继续条件 停止条件
确认影响 记录事故时刻、业务范围、入口 SLI 与当前版本;保留脱敏证据 能识别受影响的写入域和实例 目标实例/环境身份不清
控制写入 指定事故负责人,限制受影响写入,保留原现场;隔离旧写入者 旧实例不再有有效写权限,已明确外部副作用 无法证明旧写入已停止
选择恢复点 核验备份清单、摘要、日志连续性、加密材料和兼容版本 恢复点满足目标或业务明确接受偏差 日志缺段、无法解密、摘要不符
隔离恢复 在独立目标上恢复基础数据与必要日志;外部发送能力关闭 数据库技术校验通过,未连接真实业务消费者 发现误连源环境或对外发送
业务验收 比较订单状态、库存流水、金额汇总、文件存在及去重状态 抽样和关键不变量通过,差异有处置结论 数据差异无法解释
受控切换 保留旧现场,以小流量只读验证,再按批准范围开放写入 SLO、积压、对账均满足恢复标准 新错误或双写迹象出现
结束观察 核对补偿与重放结果,记录实际 RPO/RTO,安排复盘 持续观察窗口通过,责任人确认 只恢复接口但业务结果未知

为什么“隔离旧写入者”要放在恢复之前?网络分区中旧实例可能稍后恢复,单靠新实例拿到锁不保证旧实例不再写。需要存储端可验证的 fencing 机制,例如单调递增令牌与拒绝旧令牌的写入条件,或者明确撤销旧实例写权限。租约到期只是一方的时间判断,不能自动让另一方停止执行。恢复到新库后也必须防止旧消费者把积压消息写向错误目标。

验收应看不变量而不是只看行数。例如订单主表与明细行数关系、库存变化是否能由流水解释、支付/退款合计是否一致、导出文件是否可打开。两张表各少同样数量的行,单看计数也可能“对齐”;抽样必须覆盖边界时间、失败重试和关键业务状态。大表全量校验可能昂贵,要预先设计分区摘要与重点样本,不能事故中临时做无界扫描压垮恢复实例。

5. 故障推演:恢复库成功,重放却重复发货

教学案例中,数据库恢复到 09:58,消息系统仍保留到 10:00 的事件。某订单 09:59 已调用物流成功,本地成功标记没有包含在恢复点里。消费者重新读取消息后再次发货;技术恢复成功反而制造业务事故。相同风险也存在于支付、短信、库存上传和外部平台同步,不能把“消息至少一次送达”当“业务只发生一次”。

恢复流程应保留原事件身份与业务幂等键,对未知结果优先查询外部系统,只有确认未执行才继续。消费位点、业务去重记录和数据库恢复点需要共同审查;把位点直接调到最新虽然消除了积压,也可能跳过未完成业务。重放必须限速,逐批核对错误率与下游容量,并且有可停止点。历史事件经过新代码时还可能遇到 schema 兼容问题,应保留事件版本与必要转换逻辑。

回切同样不是“把流量指回去”。如果恢复侧已接受新写入,旧侧就落后了;直接切回会丢失恢复期间的变更。应先定义同步、对账、写入冻结及切换策略,确认唯一写入者。为了避免用一个未知状态覆盖另一个未知状态,原现场与恢复产物应保留到验收完成,并限制删除权限。

6. 桌面演练与可以实际运行的离线检查

教学时间线设定为:10:00 中断,3 分钟发现确认,2 分钟控制写入,7 分钟取回并准备备份,8 分钟重放,6 分钟验证,2 分钟接流量,总计 28 分钟。若最新可验证恢复点为 09:58,潜在丢失窗口两分钟,在这个假设下同时满足 5 分钟 RPO 与 30 分钟 RTO。它只是算例,真实结果必须由演练时刻、恢复点与业务核验记录测得。

桌面演练可以在“日志缺一段”“密钥不可用”“旧消费者未隔离”“恢复后金额不一致”中逐项注入信息,要求执行者按表停止,而不是强行完成切换。失败的演练很有价值,它暴露准备不足;把所有检查口头设为通过,只训练了读手册。每轮记录哪个判断缺证据、谁负责补齐、下轮如何证明修复,不把具体个人失误当唯一根因。

本目录真正可运行的只是虚构日志分析与 unittest,用来练习事件去重、损坏检测、时间边界和统计验证。如下命令只读本地文件,校验和用于确认教学样本的字节身份,不冒充数据库备份可恢复性测试:

shasum -a 256 operations-course/labs/fictional.jsonl
python3 -B -m unittest discover -s operations-course/labs -p 'test_*.py' -v

测试中有坏行、冲突事件和超长输入的模拟,但没有执行真实备份恢复、数据库回放、故障注入、网络隔离或主从切换。若要验证容灾承诺,后续必须在独立、可销毁、无真实外发权限的环境做恢复演练;测试结果和生产容量之间不能画等号。

7. 练习与答案

练习一: 每五分钟生成一次备份,就能承诺 RPO 五分钟吗?

答案: 不能。还要考虑失败、归档延迟、一致性、解密和恢复可用性。应以最新可验证恢复点与事故时刻之差衡量潜在丢失窗口,并验证日志链是否连续。备份时间表是计划,不是恢复证据。

练习二: shutdownNow 后任务还在运行,是 JVM 不可靠吗?

答案: 不一定。中断是协作信号,任务可能忽略它或卡在不能及时响应的操作;方法不保证强制停止。需要任务超时、幂等、持久化状态和明确的终止升级策略。源码这里也没有实现注释暗示的强制退出。

练习三: 数据库恢复完成 20 分钟,业务验证再花 15 分钟,RTO 30 分钟是否通过?

答案: 若恢复目标定义为业务恢复,则至少 35 分钟,尚未包含发现与切换,已经不通过。不能删除验证步骤来让数字好看,应优化恢复路径、预先准备校验和缩小故障影响。

官方参考

恢复链原理见 MySQL 时间点恢复 与 备份策略,持久化取舍见 Redis persistence,中断与线程池终止语义见 Java 8 ExecutorService。MySQL 文档为 8.4 版本参考,不证明这些项目使用相同版本;实际恢复必须匹配现场版本和工具。

原始文档 · operations-course/开发陷阱深化.md

运维开发陷阱深化:日志看起来正常,证据可能已经失效

本篇先审阅已有第 02、04、05、06 章,再读日志分析器、Logback 路由、trace 过滤器和启动关闭代码。旧正文已经解释 MDC、SLO 和发布阶段;这里继续追问:统计口径与日志链路同时变化时,如何证明“恢复了”不是观测失真? 对前端转 Java 后端的开发者,浏览器 Network 里一个请求是一项具体工作,但后端一个 trace 可以跨服务、跨重试、跨多条日志。把关联线索当唯一事件身份,会在看板上凭空删掉工作。

每节明确源码事实、条件风险、改进设计、验证。例子均为虚构事件或条件推演,不是生产日志。没有读取真实日志、环境秘密配置、进程转储或线上指标;没有执行启动停止脚本。官方资料核对的是机制,不证明本项目已经采用某个版本或部署配置。

一、去重后两条请求,为什么只输出一个慢 trace

源码事实。 现有教学分析器 analyze_logs.py#L137〔本地文件〕 使用 event_id 查询 seen,并比较归一化后的整条记录;相同内容记 duplicates,不同内容记 conflicts。新 ID 才增加 requests。另在 第 150—151 行〔本地文件〕,慢请求的 trace_id 放入 set。因此 requests=2、slow_trace_ids 长度为 1 完全可能正确:两项不同的慢请求关联到同一链路,慢链路检索列表只需一个入口。

失败时间线 A: t0 网关完成事件 e1,trace=t,耗时 900ms;t1 订单服务完成事件 e2,trace=t,耗时 800ms;t2 采集器重发 e1;t3 按 event_id 去重得到两条事件、一条重复、一个慢 trace。如果运维把 slow_trace_ids 的长度当作请求数,就会把两个服务完成事件压成一个请求;若用两个服务事件共同计算“入口请求成功率”,又会把一次用户请求算成两次。正确去重并没有自动确定正确分母。

条件风险。 分析器本身没有 service 参数过滤,它会合计所有传入且符合事件类型的记录。因此若输入混入网关和内部服务,就不能直接称结果为用户入口 SLO。这不是 set 的 bug,是报告口径与输入范围不一致。另一个前提是 event_id 的唯一性范围:两个服务独立使用 event-1 时,第二条会被视为冲突,不能凭字段名推定它全球唯一。

改进设计。 先固定统计集合:例如某入口服务、某组路由、某个版本窗口里的完成事件。事件键使用全局稳定 ID,或明确约定 (service,instanceEpoch,eventId) 的命名空间;但若跨采集链路复制同一个事件,身份必须保持一致。trace_id 用于关联,span_id 用于跨度定位,attempt 用于解释重试,业务 requestId 用于识别业务操作,它们不能互换。OpenTelemetry 日志数据模型 将 TraceId、SpanId 作为关联字段,也区分事件时间与观察时间;本文教学 event_id 是自己的事件契约,不声称它是 OTel 自动提供的去重机制。

验证。 可执行的离线探针使用两个不同 event_id、相同 trace 和一条原样重发,断言 requests=2、duplicates=1、慢 trace 数=1;再使用相同 event_id、不同 service,断言 conflicts=1。已有测试也覆盖基础 trace 去重边界。生产事件 ID 的生成范围和入口采样覆盖仍待验证。

二、sample_complete=true 只能说明输入通过检查

源码事实。 analyze_logs.py#L62〔本地文件〕 对其他 event 类型返回 None;第 86 行〔本地文件〕 仅接受 success、error、unknown 三种 outcome;unknown 被接受后在第 146 行按非成功计入。新增字符串 timeout 则会成为 invalid,不是自动折算为失败。第 133 行先过滤时间窗口再做去重;第 160 行〔本地文件〕 的 sample_complete 只检查 invalid 与 conflicts 是否为零。

失败时间线 B: t0 入口实际完成 100 个请求,其中 10 个失败;t1 采集故障刚好漏掉失败请求;t2 分析器收到 90 个完全合法的成功事件;t3 输出 sample_complete=true、成功比例 100%。程序没有任何证据知道缺少十条。这个字段证明输入内未发现指定质量问题,不证明传输完整、没有采样或没有丢事件。

再考虑发布:t0 新版将失败 outcome 改名为 timeout;t1 旧分析器将这些行标记 invalid;t2 requests 的分母只保留仍合法的成功事件;t3 若看板忽略 invalid 和 sample_complete,成功率会虚高。反过来,新版把 event 改成 request_finished,这些行会计 ignored,甚至不使 sample_complete 变为 false。不能将“未知 outcome 枚举”和已定义的字符串 unknown 混为一谈。

改进设计。 展示统计值时同时给出输入覆盖、invalid、ignored、conflicts、采集迟到和独立入口计数。样本内完整性与端到端覆盖率分开命名;无样本显示未知,不能显示全绿。冲突时既不能静默覆盖也不能宣称先到的一条必真:当前分析器保留先到记录参与统计,报告要标为不可信并调查来源。重发应保存原事件时间和 ID,不能采集一次就改写一次 ts,否则会制造假冲突。

归一化也有边界:parse_record 返回对象#L88〔本地文件〕 只保留固定字段,额外字段不参与比较。因此只在新增 deployment_id 上不同的两条输入,仍会被判重复;增加 schema_version 却不修改消费者解析,也不会自动得到版本隔离。这是教学分析器的明确范围,不应被包装为生产通用 schema 引擎。

验证。 本轮离线探针检查:合法输入缺失无法被发现;新 outcome 被判 invalid;新 event 类型被 ignored;只改变未知扩展字段仍判重复。待执行生产验收要用独立入口计数或可控合成流量核对覆盖,不依赖同一条已可能丢失的日志链路自证完整。

三、MDC 污染会制造一条非常完整的错误链路

源码事实。 报表 TraceIdFilter.java#L28〔本地文件〕 先取 RPC attachment,空时从 MDC 回退,非空则写回双方;第 41 行〔本地文件〕 invoke 周围未显示 finally 恢复。本地方法没有证明外层也不清理,因此只能提出局部风险。后台 logback.xml#L6〔本地文件〕 的 pattern 又没有 trace 字段:即使 MDC 存在,文本输出也不自动包含它。

失败时间线 C: 条件是外层未清理且线程复用。t0 请求 A 在线程 T 写 trace=a;t1 A 抛异常退出;t2 请求 B 无 attachment,仍在 T 上执行;t3 过滤器回退读到 a 并传播;t4 运维查询 trace=a,看到 A、B 两批看似连贯的操作。此时链路“很完整”反而掩盖串线。若再用 trace 去重,B 的完成事件可能进一步消失。

改进设计。 定义每层作用域:入口校验或生成 trace,提交任务时捕获允许传播的诊断字段,执行时保存 previous,结束时恢复 previous。RPC attachment 也要按框架作用域恢复;只清 MDC 不代表附件已清。CallerRuns 可能在调用线程执行,直接 clear 会删除外层上下文。鉴权、租户身份应来自可信授权上下文,不能因为 trace 相同就视为同一用户。Logback MDC 官方说明 用于核对线程上下文机制。

验证。 已核对局部过滤器和文本 pattern。待执行用同一个隔离线程连续运行 A、B,覆盖 A 正常返回与抛异常、B 有无 trace、嵌套调用和 CallerRuns;断言 B 不继承 A,外层 trace 在返回后恢复。还需分别检查内存 MDC 与实际输出,避免测试只断言 MDC.get,却没验证日志内容。

四、日志故障可能同时隐藏异常和拖慢请求

源码事实。 后台 logback.xml#L28〔本地文件〕 的 file_info 用 LevelFilter 精确接受 INFO,file_error 在 第 50 行〔本地文件〕 精确接受 ERROR;因此 WARN 不匹配这两个文件 appender。滚动策略第 19—23 行〔本地文件〕 按天保存历史,不能从天数推定磁盘占用硬上限。ry.sh#L29〔本地文件〕 将标准输出和错误重定向到空设备,下一行立即输出启动成功。重复 root 标签的最终绑定行为仍需按实际依赖核验,不能说后一段必然覆盖前一段。

失败时间线 D: 如果使用此脚本且没有其他有效输出渠道,t0 依赖短暂抖动,程序写 WARN;t1 两个文件过滤器拒绝;t2 控制台输出被重定向丢弃;t3 查询 info/error 文件,看不到这条告警。另一条条件链是目录不可写导致 appender 启动失败,而内部状态消息也未被观察;应用可以仍在运行,日志却沉默。不能据“服务没报错”认定日志链路健康。Logback Filters 和 Appender 生命周期 支持这些机制区分。

条件风险。 慢磁盘、空间不足、采集器断连、超长消息分别影响不同边界。同步日志写入可能延长业务调用;改异步后则必须处理队列占用、丢弃策略和关闭时剩余日志。不能从当前配置断言项目已启用 AsyncAppender,也不能保证所有 I/O 故障都会抛到业务 catch。某个日志恢复成功不代表之前的业务任务会自动重做。

改进设计。 日志链路需要独立健康信号:文件写入错误、采集延迟、丢弃数量、队列占用、磁盘空间,以及不依赖同一失败目的地的报警。诊断日志可在明确策略下采样;关键业务审计应进入可靠存储或事务事件,不能只靠打印一行承担业务账本。热路径记录白名单摘要和错误分类,避免完整订单、巨大响应和重复堆栈放大故障。不要在 logger 的错误回调里递归写同一 logger 试图报告故障。

验证。 待执行的安全演练使用临时目录、假的失败输出流、隔离 Logback 配置和可控采集桩,分别模拟不可写、慢写、输出抛异常、采集暂停及恢复。不可通过填满共享磁盘来做“实验”。验收需观察业务延迟、日志损失、独立告警和恢复后重复事件,不能只有“异常被捕获”。本次未执行任何磁盘故障注入。

五、发布兼容性包括查询器,回滚镜像并不会回滚历史事件

源码事实。 当前分析器硬编码事件名、字段、单位和 outcome 集合,见 parse_record#L52〔本地文件〕。启动脚本在 ry.sh#L30〔本地文件〕 启动命令发出后就打印成功,没有在此路径等待业务就绪。关闭工具 Threads.java#L49〔本地文件〕 等待后 shutdownNow,未处理退回的队列任务;未终止时只记录日志。它们共同提示:进程动作、数据兼容、任务完成、观测可用必须独立验收。

失败时间线 E: t0 v1 生产端记录 duration_ms=800;t1 灰度 v2 改成 duration_ms=0.8,实际仍耗时 800ms;t2 旧解析器接受非负数字,无法发现单位偷换;t3 p95 看起来大幅改善;t4 决策者扩量。回滚 v1 只改变新事件,已有的错误单位事件仍在历史窗口中。仅校验 JSON 合法、字段存在和类型正确,无法证明语义兼容。

改进设计:发布前填写兼容矩阵。 以下是建议的验收契约,不是当前分析器已实现能力。

组合 验收要求 不满足时的动作
旧生产端 → 新解析器 旧字段、单位、枚举保持解释一致 停止替换解析器
新生产端 → 旧解析器 兼容窗口内仍可识别,或明确双写旧契约 先升级消费者,暂缓生产端
新旧生产端混跑 → 新查询器 同一口径归一化,版本可分组核对 停止扩量,排查覆盖偏差
回滚生产端 → 新解析器 继续理解旧格式,历史新事件仍可读 保留兼容读取,避免同步回滚所有层
历史归档重放 → 当前解析器 保留身份、原事件时间和单位转换记录 隔离不支持版本,不能默认成功

新增可选字段通常比改名删除容易兼容,但也要检查严格校验器。改变单位应换明确字段或版本,转换有可验证样本;新增失败枚举先让解析器识别,不能默默扔出分母。先扩展读取、再升级写入、最后清理旧支持,兼容窗口需覆盖旧实例、在途任务、回滚期和历史重放。双写两套事件若各有新 ID,会重复计数,必须限定单一统计入口或制定转换后的身份规则。OpenTelemetry Telemetry Schemas 讨论遥测生产者与消费者随版本演化的耦合;自定义 JSONL 不会因添加 schema_version 就自动获得其转换能力。

验证。 当前离线探针可证明“0.8 仍会被当成合法毫秒数字”,不能证明它识别了真实单位。待执行矩阵应固定一批已知请求,其中耗时、失败、重试、缺失 trace 和重复投递都已知,对每种组合比较分母、分子、p95 和冲突数。发生单位污染时给历史报告标注受影响版本与时间段,修复查询或重算,不能只说镜像回滚完成。

发布关闭也有失败时间线 F:t0 任务已被应用确认接管;t1 发布触发关闭;t2 排队任务从执行器退回但无人持久恢复;t3 进程退出;t4 新版本启动成功,旧任务仍未完成。应对接分布式篇的可靠接管账本、并发篇的取消状态和发布的关闭预算,而不是靠增加等待秒数解决持久性问题。实际环境的宽限期未知,本次不推定平台会等待工具类中的两次 120 秒。

六、练习答案与审阅报告口径

题一: 同 trace 两个 event_id、同 event_id 两个 service、同 event_id 只差新扩展字段,现有分析器分别怎样处理?答案: 第一种保留两个事件,慢 trace 列表可只有一个;第二种计冲突并保留先到记录;第三种若扩展字段不在归一化返回对象中,会被判重复。三种都不能直接推导业务请求总数,仍需限定入口范围。

题二: 失败请求被采集器漏掉,但 sample_complete=true,程序是否自相矛盾?答案: 没有。它只对收到的输入检查坏行和冲突,不知道未收到什么。报告必须写“输入内未发现质量问题”,并补充独立覆盖证据,不能写“全量生产请求已验收”。

题三: 将 unknown 改为 timeout,是否只是增加一个更清晰的名字?答案: 对人可能清晰,对旧程序是不支持枚举。unknown 是已知值并按失败统计,timeout 会被判 invalid。要先更新消费者契约,验证分母不变,再发布生产者。

题四: ERROR 数下降、p95 下降、新进程已启动,足以宣布发布成功吗?答案: 不足。需核对输入覆盖、单位、版本分布、业务成功率、任务积压、消息责任交接和就绪状态。每项证据都应能被独立复算;对未知原因保留未知,不能用指标变好替代因果调查。

完整结果见 审阅清单。八个探针已保存为test_log_contracts.py〔本地文件〕,在工作区执行python3 -B operations-course/labs/test_log_contracts.py -v即可复跑。它只用内存虚构事件调用现有纯分析函数;日志故障、真实trace传播和发布兼容矩阵均保留为待执行。阅读统计报告时,应同时核对输入范围和未验证条件,避免把局部实验通过理解为生产链路已得到证明。

原始文档 · operations-course/验证记录.md

运维课程验证记录

日期:2026-11-11。只在 /Users/try/work/admin/operations-course/ 新建教材、样本、分析器及测试;未编辑业务仓库,未覆盖已有数据库/Spring 教材,未提交 Git。未生成或修改 HTML 阅读器,响应式布局与静态站发布由主代理统一处理。

实际运行的实验

工作目录为 /Users/try/work/admin,以下命令已实际执行。Python 仅使用标准库,-B 禁止写入字节码缓存,不连接任何业务服务。

本次实际运行环境为 Python 3.13.5;分析器按 Python 3.9+ 标准库接口编写,但没有对所有 Python 次版本逐一运行兼容性测试。

python3 -B -m unittest discover -s operations-course/labs -p 'test_*.py' -v
python3 -B operations-course/labs/analyze_logs.py operations-course/labs/fictional.jsonl
python3 -B operations-course/labs/analyze_logs.py operations-course/labs/fictional.jsonl --start 2026-01-01T00:00:01Z --end 2026-01-01T00:00:07Z
shasum -a 256 operations-course/labs/fictional.jsonl

unittest 结果为 18 个测试全部通过,退出码 0。测试覆盖:完整样本统计、半开时间窗、等价时区、零流量、坏 JSON 与内容不回显、非法耗时、时间格式、冲突重复、trace 非去重键、业务失败与未知结果、延迟阈值、缺失 trace、重复 JSON 键、状态与标识校验、非法参数、输入上限、小样本分位数、本地 CLI。

输出项 全部样本 [00:00:01Z,00:00:07Z)
输入行数 14 14
有效且去重后的请求 10 6
重复事件 1 1
非法行 2 2
忽略心跳 1 1
窗口外有效事件 0 4
失败请求 3 0
SLO 好事件 6 6
nearest-rank p95 3000 ms 500 ms
SLO 好事件比例 0.6 1.0
burn rate 约 400 0

两种输出的 sample_complete 都为 false,因为输入包含故意构造的坏行;校验在时间过滤之前进行,不能假定坏行在窗口外。这个标志只表达脚本发现的数据质量问题,不保证采集源完整。浮点 burn rate 实际输出 399.99999999999966,测试采用近似比较。测试通过表示这些约定按预期实现,不表示虚构样本满足 99.9% 的目标。

样本 SHA-256:

906276468b0fb8dc3bf6729441e519e9a0d9a7830cf730615586ec98ce14263f

摘要只证明当前实验文件的字节身份,不证明数据库备份可恢复,也不提供业务数据完整性担保。

文档与源码校验

已读取真实 Logback 配置、HTTP 工具类、线程池/调度/关闭实现、trace 过滤器、指定 Maven 配置片段、后台启动脚本与商品 Web Dockerfile;教材引用均使用相对路径和 #L行号。静态校验核对 Markdown 相对链接的目标存在性、源码行号范围、00—06 共七章和 README 完整目录,并检查每章的汉字篇幅、练习答案及官方参考。

最终静态校验通过:10 个 Markdown 文件、67 个本地链接、41 处源码行号链接均有效,代码围栏成对。按 Unicode 汉字范围计数,00—06 分别为 2516、2590、2525、2676、2779、2789、3456 字;此口径不把英文代码长度计入汉字数。已确认各章包含故障推演、练习答案和官方参考。校验仅证明目标与行号存在,源码含义由写作时实际阅读核对,不能把链接检查当作自动语义验证。

官方参考使用 Linux、Java、Maven、Docker、Logback、IETF、Prometheus、OpenTelemetry、MySQL、Redis 和 Kubernetes 官方资料。文中保留版本边界;尤其 JDK 17 诊断手册及 MySQL 8.4 恢复文档不能当成这些项目实际版本的证据。未发现可说明现状的 Kubernetes 清单,只表示本次指定文件名与目录的检索结果,不排除外部部署平台。

明确未验证的范围

没有运行业务 Maven 构建、Spring 上下文、数据库测试、部署脚本、容器、网络探测或生产查询;没有启动 JVM 诊断、堆转储、JFR、真实备份恢复、故障注入或主从切换。所有业务源码风险均为条件化分析,未证明对应部署事故已经发生。Linux 命令与主动探测模板仅写入教材,没有在业务环境执行。

18 个测试不验证真实 Logback 路由、MDC 传播、采集器丢日志、在线 SLO、监控平台、海量日志性能或容灾承诺。分析器最多接受 100000 行、每行 16384 字符,保存窗口内事件及耗时,不是生产流式日志系统。route 与 trace 的规则只服务虚构教学 schema,不声称兼容所有真实 URL 或追踪协议。

本记录不替代主阅读站构建与页面检查;主代理可在全部章节落盘后统一构建,并独立验证响应式展示及静态发布。

原始文档 · operations-course/labs/README.md

虚构日志离线实验

这里的时间、服务、路由和 trace 均为人工编写,不来自业务日志。使用 Python 3.9 及以上的标准库,不安装依赖,不访问网络,不读取环境配置。fictional.jsonl 特意包含坏行,不能把它当成全文件合法 JSON 的样板。

文件入口:样本〔本地文件〕、分析器〔本地文件〕、unittest〔本地文件〕。在 /Users/try/work/admin 执行:

python3 -B operations-course/labs/analyze_logs.py operations-course/labs/fictional.jsonl
python3 -B -m unittest discover -s operations-course/labs -p 'test_*.py' -v
python3 -B operations-course/labs/analyze_logs.py operations-course/labs/fictional.jsonl \
  --start 2026-01-01T00:00:01Z --end 2026-01-01T00:00:07Z

-B 避免生成字节码缓存。命令只读取实验文件,输出到终端;测试以 StringIO 做内存输入,不创建业务数据。行数超过 100000 或单行超过 16384 个字符时拒绝继续,避免静默给出截断统计。超长行由受限 readline 在完整加载前拦截;上限是字符数,不是 UTF-8 字节数。

先手算再运行

样本共有 14 行:10 个完成事件、1 次完全重复、1 个无关心跳、1 行损坏 JSON、1 个布尔类型的非法耗时。合法耗时排序为 80,120,200,250,400,500,600,900,1500,3000。p95 使用 nearest-rank,位置为 ceil(0.95 × 10)=10,结果是 3000 毫秒;这不代表真实总体 p95 精确等于 3000。

失败定义为 HTTP 不在 200—399 或 outcome 不是 success。样本有 3 次失败,包括 HTTP 200 但业务 error。SLO 好事件还必须耗时不超过 500 毫秒,所以好事件 6 个,坏事件 4 个。目标 99.9% 时本窗口 burn rate 为 (4/10)/(1-0.999)=400,浮点输出可能接近而不严格等于 400。失败率 30% 与 SLO 坏事件率 40% 不矛盾,后者还纳入一次成功但慢的请求。

事件 ID 是去重键,trace 不是。时区归一化后,相同事件也能识别重复。若相同 ID 对应不同内容,报告 conflicts 并保留首条作暂定计算,sample_complete=false;这类统计不能用于正式 SLO 验收。样本含坏行,因此完整样本的 sample_complete 也为 false;这是显式暴露数据质量,不是测试失败。该标记只检查输入内部发现的问题,不能证明采集上游没有丢日志。

时间窗是 [start,end),第三条命令选中前 6 个完成事件,500 毫秒边界包含在好事件内,结果应有 6 个请求、6 个好事件、0 次失败、p95 为 500。非法记录在时间过滤前校验,仍会报告 2 个坏行,不能悄悄假设它们都在窗口外。无请求时比例和分位数为 null,不当作 100% 成功。

实验问题与答案

  1. 把 HTTP 200 当全部成功,会漏什么?会漏业务失败;本例 e10 就是反例。现实还要核对成功响应与持久化业务结果是否一致。
  2. 把 e08、e09 的 trace 改相同,是否只剩 9 次请求?不会,去重依据是 event_id;同一个 trace 可以关联多个事件。
  3. 为什么不打印坏行?原始内容可能含个人信息、换行注入或凭据。报告只提供固定错误类别,隔离保管原件应由独立受控流程完成。
  4. 能否把这个脚本直接跑在海量生产日志上?不能。它为精确分位数保存耗时,为去重保存事件,内存随有效样本增长;行数上限只是教学防护。生产需要分区聚合、采集质量监控、访问控制和可扩展分位数算法。

测试覆盖与边界

unittest 验证统计、p95、UTC 时区、半开边界、零流量、重复/冲突、缺失 trace、业务失败、500 毫秒边界、NaN/Infinity、布尔耗时、非法状态、重复 JSON 键、参数/输入上限及本地 CLI 输出。route 只接受教学用模板字符,不是通用 URL 校验器;trace 格式也是演示格式,不声称实现 W3C/B3 协议。

未验证真实采集器、Logback 运行时、MDC 传播、日志轮转、大规模吞吐、Prometheus、远程存储、真实告警或跨主机时钟。输入顺序无须按时间排序,但重复冲突保留首条的结果与顺序有关,报告会将其标为不完整。正式 SLO 的分母应以完整入口事件或计数器定义,不能以这个含坏行的教学样本代替。

实际测试次数与结果见 验证记录。

第二轮新增日志契约测试〔本地文件〕八项,固定复现同trace多事件、跨服务事件ID冲突、未知枚举/事件、扩展字段被归一化丢弃、错误单位和输入完整性边界。上面的unittest发现命令会一并执行,共26项;也可单独执行python3 -B operations-course/labs/test_log_contracts.py -v。详细解释见开发陷阱深化,完整二轮结果见主站验证记录。

学习阶段 07

项目专题延伸

复用既有手册:平台SDK、Elasticsearch、AI与RAG;不是本轮新增专题

原始文档 · erp-backend-handbook/16-平台SDK物流与外部系统集成.md

16 平台 SDK、物流与外部系统集成

前置知识、学习目标与阅读边界

前置知识:会用 Axios 调接口,理解 Java 对象、异常、数据库更新和消息消费即可。本章从“调用一个接口”走向“管理一个不可靠的外部系统”:平台模型如何进入 ERP,授权凭证如何使用,为什么 HTTP 成功不代表业务成功,以及物流失败后如何靠记录和补偿恢复。

学完应能回答六个问题:平台工厂到底选择了什么;统一订单是否只是改字段名;token 与签名有什么不同;限流和重试如何互相放大;订阅成功与运输签收为什么是两个状态;补偿任务为什么不是数据库回滚。

证据边界:本章依据当前工作区 erp-sdk、erp-logistics-service 的 Java 与 Mapper 源码编写。标为“源码事实”的内容来自实际可执行语句;标为“风险推演”的内容不是线上事故结论;标为“教学设计”的内容不是项目已有能力。源码链接全部相对本教材目录,使用 #L行号 定位。没有读取密钥配置,没有调用电商平台、物流、数据库、Redis、消息队列或调度服务,也没有运行可能加载这些服务的应用测试。动态开关值、真实部署拓扑、调度频率和外部接口当前契约均不由静态源码保证。

1. 从前端适配器理解后端 SDK

前端常把不同接口的响应转成同一种卡片数据,例如把 order_sn 转成 orderId。后端的平台 SDK 也有适配,但承担更多责任:不仅转换字段,还涉及商家身份、授权范围、平台状态、金额口径、解密权限、调用配额、异常分类与副作用。把平台 SDK 理解成一组 HTTP 工具函数,会遗漏最危险的业务边界。

阅读顺序建议是:业务能力抽象 → 平台选择 → 平台请求 → 响应校验 → 领域模型转换 → 失败处理。不要从一个巨大平台类第一行读到最后一行;先选择“查询一个订单”这样的窄路径,再用相邻路径比较差异。

源码入口是 MallApi,第48行〔本地文件〕。它是抽象类,许多方法提供默认实现并直接抛 UnsupportedOperationException。例如订单详情从第69行开始,发货从第120行开始。因此,“统一接口上存在方法”不等于“所有平台都支持该能力”。前端按钮是否可用也不能只依据统一 DTO 是否有这个字段,而要结合平台能力与业务状态。

2. 平台工厂、策略与代理:一次调用选了谁

2.1 工厂解决实现选择,不等于缓存

ApiFactory,第45行〔本地文件〕 的 getInstance 检查平台枚举,执行配置初始化入口,然后调用 getProxyMallApi。第62行开始先判断通用平台,再通过 switch 返回各平台实现。例如 JD 对应的是 JdSpMallApi,不能看到文件里还有 JdMallApi 就认为它被这条分支使用。

值得训练的源码习惯是“沿使用点,而不是按变量名下结论”。第43行确实声明了 ConcurrentHashMap,但本次阅读的 getInstance 路径没有先从这个 Map 查询实例;它进入创建目标对象和代理的逻辑。因此不能把这个工厂写成“已经实现平台单例缓存”。并发容器的声明只能证明存在容器,不能证明它参与了主要调用链。

2.2 代理加入横切行为

MallApiProxyFactory,第39行〔本地文件〕 使用 CGLIB,以目标对象的类为父类创建代理。第70行的拦截器通过反射调用目标方法,并统计调用结果。你可以类比 Axios interceptor,但要注意后端代理可能只拦截经过代理对象的调用;目标对象内部的直接调用不能凭空算作再经过一层代理。

工厂、适配器、代理分别回答“选择谁”“如何翻译协议”“在调用前后加什么行为”,不是同一个概念。排查重复调用时先画出对象和调用边界,比直接搜索 retry 更有效。

3. 模型转换不是简单复制:订单、金额、状态与时间

3.1 走读拼多多订单详情

PddMallApi,第206行〔本地文件〕 的一个详情重载把 isRds 转为查询参数,并通过 RetryUtil 调另一个重载。第219行开始构造平台请求、设置扩展参数和原始 token,然后调用 PddClientHelper。返回后先检查平台错误对象,再检查业务 isSuccess,最后处理订单列表。

这里有两个前端容易误判的边界。第一,网络调用返回对象后还要判断平台业务错误,不能仅凭 HTTP 成功确认订单取得成功。第二,第246行和第249行存在返回空 MallTrade 的分支,因此非空 Java 对象不一定包含有效订单。调用方还要理解订单主键、列表为空等结果契约,不能盲目把“没有抛异常”翻译为“找到订单”。

模型转换的真实入口之一是 PddTradeUtil,第60行〔本地文件〕。这里建立 MallTrade,设置店铺、平台订单号、优惠、支付金额和时间。原平台协议是外部语言,MallTrade 是 ERP 内部语言;转换层相当于防止外部语义直接侵入业务的边界。

3.2 状态必须同时考虑订单与退款

同文件第98行分别转换退款状态和订单状态。getPddTradeStatus,第366行〔本地文件〕 会把退款成功对应到交易关闭,再处理普通订单状态。第377行开始还有所有子单关闭时设置主单关闭的辅助逻辑。

由此得到的机制是:外部状态不是一个可以跨平台通用的数字。平台的“已发货”“已退款”“部分售后”等状态会形成组合,统一状态可能由多个字段共同决定。新增平台映射时,至少列出正常支付、未发货退款、发货后退款、子单部分关闭和未知状态的样本。未知值应该进入可观察的兜底,而不是随手映射为某个成功态。这是教学要求,不代表本仓库已经覆盖了上述全部样本。

3.3 金额字段要核实单位,不能靠名字猜

金额映射,第73行〔本地文件〕 对商品金额、优惠等使用了 BigDecimal.valueOf;第113行附近邮费的注释写“分”,支付金额注释写“元”,赋值本身没有在这几行统一除以一百。教材据此只能提醒“存在需要核验的字段口径”,不能擅自宣布所有金额都已转成元,更不能直接认定业务数据必错。必须进一步对照对应请求响应契约、上游取值以及调用方的单位约定。

BigDecimal 也不是自动正确的魔法:上游若已用浮点数表达,转换并不能恢复最初丢失的信息;最后调用 doubleValue 又回到浮点表示。ERP 对账需要明确币种、最小货币单位、舍入规则及优惠归属。前端显示两位小数只是展示,不能代替后端口径。

parseShippingTime,第388行〔本地文件〕 对空时间返回空值,解析失败记录错误并返回空。风险推演:一个“发货时间缺失”的页面现象可能来自平台未返回,也可能来自解析失败。正确排查应区分来源缺失、格式变化与时区假设,不要直接补当前服务器时间污染业务事实。

4. token、签名、refresh:三个不同层次

4.1 token 表示授权,签名绑定请求

access token 一般表示某个主体允许应用在某个范围内访问资源;refresh token 用于获得新的 access token,不应混同为 ERP 用户的登录态。签名则根据平台指定的规范化字符串与密钥计算,用来校验请求来源和完整性。签名不等于加密:请求内容仍需要 TLS 保护,签名本身也不证明当前 ERP 操作者有权操作这个店铺。

PddClientHelper,第14行〔本地文件〕 显示,这里的 token 还可能带多应用路由信息:先解析平台应用,再提取原始 token,最后交给匹配的 client。第28行的 syncGet 还设置目标 clientId。因此只验证 token 字符串“没过期”不够;应用、店铺、平台、授权范围必须配套。不要将路由包装串直接当作平台要求的原始 token,也不要把真实 token 贴进工单或教材。

4.2 读懂签名的规范化规则

SignUtil,第39行〔本地文件〕 的一个方法对参数名排序,忽略空白键值,以密钥前后包裹拼接内容,再生成大写 MD5。第72行〔本地文件〕 的另一个方法使用按键排序的 key=value 与 & 拼接,仅过滤空值;第170行〔本地文件〕 另有 HMAC-SHA256 实现。这些算法存在于同一个工具类,不表示每个平台都调用同一算法。

故障定位先比较规则:空字符串是否参与、数组怎样序列化、JSON 是否保持同一字节表示、编码发生在签名前还是签名后、时间戳单位和容忍窗口是什么。两个业务上等价的对象可能签出不同值。学习时用虚构字符串和固定输入验证;记录字段名、规范化规则版本与脱敏摘要,不输出拼接了密钥的完整待签名串。新协议选型不能因为旧平台要求 MD5 就默认 MD5 是现代认证设计的推荐方案。

4.3 有刷新方法,不代表刷新链路已经可靠

KsMallApi.getNewToken,第788行〔本地文件〕 构造刷新参数,并从响应中提取两种 token。但必须读到实际执行语句:第797行带 paramsMap 的调用被注释,第798行执行的调用传入的是新建空 Map。这证明“构造过参数”与“把参数传出去”不是一回事;这里不能被描述成已验证工作的刷新实现。本章未发起请求,也不依据这一点推断线上是否使用该方法。

教学设计中的可靠刷新应包含:提前量与时钟偏差、按平台应用和店铺隔离的 single-flight、刷新后原子保存凭证版本、对轮换 refresh token 的同步更新,以及刷新失败转重新授权的状态。两个线程同时刷新,较晚写入的旧结果可能覆盖新凭证;一个 JVM 的 synchronized 又不足以保护多实例。推荐用受控的版本条件更新或跨实例协调,但这些不是在本章所读方法中已经实现的能力。

5. 限额、错误码与重试:稳定性如何形成闭环

5.1 先区分 QPS、并发与日配额

QPS 限制单位时间内请求频率,并发限制同时在途数,日配额限制一段计费周期的总量。接口耗时由一百毫秒增加到三秒时,同样 QPS 会占用更多线程和连接,因此频率限制不能替代并发限制。多租户 ERP 还需要避免单店铺把所有平台额度耗尽。

XhsMallApi,第663行〔本地文件〕 创建按店铺键保存的本地 RateLimiter 缓存;实际代码是 RateLimiter.create(2),不能照附近“每秒一个”的注释讲成每秒一个。缓存最多一千项,实际访问过期是十分钟,也不是附近旧注释里的三秒。第701行〔本地文件〕 在开关允许时先 acquire,再进入重试。

由此可作有边界的推演:这是进程内状态,三个实例不会自动共享同一桶;内部重试发生在这次 acquire 之后,也不等于每次外部尝试都重新取令牌。不能把它写成“项目已经完成跨实例统一限额”。开关当前是否开启,本章没有读取配置来确认。

5.2 错误模型至少有三层

第一层是网络与协议,例如连接失败、超时、HTTP 非成功;第二层是平台业务错误,例如授权失效、参数非法、平台限流;第三层是 ERP 领域错误,例如订单已经发货、状态不允许修改。错误必须保留来源,否则“接口失败”四个字无法决定是否重试。

MallApiException,第13行〔本地文件〕 有 code 字段,但仅传 message 的构造器不赋 code,带错误码的构造器才赋值。前面拼多多详情错误分支使用了 message 构造,因此不能假设每个异常一定携带可机器分类的错误码。MallApiErrorEnum,第7行〔本地文件〕 当前只看到一个追加包裹错误项,也不能把它说成完整的平台错误字典。

教学分类表如下;它是调用策略建议,不是项目已经落地的统一枚举:

错误类别 自动处理方向 为什么
字段校验失败、能力不支持 不自动重试,修正输入或能力判断 同一输入不会因等待自然变正确
授权失效 检查凭证版本,受控刷新或重新授权 直接并发刷新可能形成风暴
限流 遵守平台反馈,退避并控制总预算 立即重试会继续消耗额度
查询遇到临时网络错误 有界重试,可加抖动 通常可重复,但仍有调用成本
发货请求读超时 先按业务标识查结果,再判断补发 远端可能已经完成副作用
明确已处理、重复业务意图 核验原结果并返回领域状态 文本含“重复”不等于绝对成功

5.3 两种重试次数语义不能混读

代理重试,第50行〔本地文件〕 根据异常 message 包含的关键词判断,固定等待两秒,stopAfterAttempt(2) 表示最多两次尝试,包含首次。第66行的单次两秒限时器被注释,所以不能声称每次调用已被这段代理限制为两秒。重试是否走这条分支取决于第72行的全局开关。

RetryUtil,第69行〔本地文件〕 的循环则先调用,再在异常时判断当前重试计数。参数为二时,满足关键词条件的失败最多可导致首次加两次重试,即三次尝试。第107行〔本地文件〕 同时检查公共和平台关键词;第133行开始按异常关键词查找等待时长。不能把它描述成内置指数退避或默认都有随机抖动。

风险推演:代理与内部工具都满足条件时,尝试数可能相乘。但要确认开关、异常包装、关键词匹配和调用路径;代理里 method.invoke 会带来反射异常包装,最终错误形态还受重试库影响。不能在没有离线桩验证的情况下断言每次一定调用六次。教学上的正确做法是统一请求 deadline、实际外部尝试计数与重试归属,并让写接口先有幂等或结果查询策略。

6. 物流记录与状态:三种“成功”不要混在一起

6.1 订阅关系、轨迹事实和业务状态分开看

用户点击发货后,至少存在三个独立问题:平台发货是否成功;物流服务是否接受轨迹订阅;包裹当前是否揽收或签收。订阅是让外部系统持续提供信息,不是让快递员完成配送。

LogisticsSubRecord,第9行〔本地文件〕 包含用户、快递公司、运单、订阅标记、错误类型、错误消息、重试次数和重试时间。第22行明确 subStatus=0 为订阅成功、1 为失败。LogisticsStatusEnum,第6行〔本地文件〕 则描述待揽件、运输、派件、签收等物流主状态,两者不能相互替代。

SubLogisticsStatusEnum,第12行〔本地文件〕 还将更细的子状态归属到主状态。例如“已放入快递柜或驿站”属于派送中,“从柜站取出”属于签收。前端若只按包含“签”字判断成功,就会误处理拒收、退签或代收等情况。真正的业务判断必须使用确定的状态映射和当前业务口径。

6.2 首次记录在哪里落地

DubboWlyServiceImpl,第427行〔本地文件〕 写运单业务关系,保存业务来源和业务唯一编码;第444行〔本地文件〕 构建订阅结果记录,设置成功或失败、初始重试次数、下一次重试时间,截断错误信息并落库。

这说明“保存关系”和“保存一次订阅结果”是不同的数据职责。本段证据不等于已经证明数据库唯一约束、跨服务事务或 exactly-once。设计幂等键时可考虑用户、快递公司、运单和业务来源的组合,但必须核实是否允许同一运单关联多个交易或售后,不能因为运单号看起来唯一就错误合并租户数据。

6.3 策略路由也有默认分支

LogisticsStrategyService,第23行〔本地文件〕 遍历注入的策略,找到匹配平台即返回,找不到时取列表最后一个。源码事实是“按列表匹配并回退到末项”,不是“任何场景都有显式命名的默认策略”。实际列表顺序与实现类装配还要继续核实。接入新平台时除了实现方法,也要验证匹配重叠、默认顺序和未知平台行为。

7. 补偿机制:恢复未完成的事实,而不是撤销历史

7.1 失败记录驱动的订阅补偿

CompensateSubJob,第51行〔本地文件〕 设置近两天窗口和最大重试次数六。第96行〔本地文件〕 按用户查询失败记录,限制创建时间与重试次数,每页一千条;普通遍历路径还开启到期重试时间过滤,显式指定用户的路径传入的参数不同,不能一概说所有入口都严格等待 retryTime。

过滤是否真的进入 SQL,要看 LogisticsSubRecordCustomMapper,第25行〔本地文件〕:用户条件总是参与,失败标记、创建窗口、retry_time <= now() 与重试次数条件按查询参数拼接。读任务只看 Java 注释不够,必须一路读到真正筛选记录的 SQL。

compensateSub,第166行〔本地文件〕 根据错误类型选择策略。手机号错误会使用候选信息;特定快递公司有重用既往错误号码的处理;暂时重试类错误再次订阅。不能把这一逻辑概括成“任何错误都重新发相同请求”。这里的个人信息只讨论字段职责,不复制真实号码。

结果更新,第213行〔本地文件〕 在成功时改订阅标志,失败时增加次数、设置下次重试时间、更新错误类型;捕获异常后也尝试记一次失败。教学启发是:重试必须改变可观察状态,否则系统只会无限循环同一条记录。成功分支并没有在这里清空所有历史错误字段,展示端也不能仅凭历史错误消息非空就判定当前仍失败。

调度入口 ErpCompensateSubJobHandler,第23行〔本地文件〕 限定 prod、pre Profile;预发没有指定参数会跳过,然后将分片信息交给任务。存在 Handler 不证明调度中心已经配置周期,更不证明每一轮都跑完。

7.2 回调乱序与补发消息是另一类恢复

pushLogisticsInfoHandle,第434行〔本地文件〕 会拒绝从非待揽件退回待揽件的更新,也比较轨迹时间以丢弃过期数据。这是已经存在的乱序防护,但不能提升为“完整的全状态单调迁移保证”:时间解析异常被捕获,最终写入在本段仍是按主键选择更新。并发下先检查再写是否足够,还需要检查数据库条件和更外层协调。

ResendLogisticsMessageJob,第73行〔本地文件〕 按记录游标查询,取得已知轨迹,再按开关向交易或售后补发消息。它不是重新获取授权,也不是订阅补偿,更不代表收件人已经收到包裹。接收方需要处理重复消息;任务成功返回只说明任务函数结束,不能代替每条下游业务完成的证据。

8. 故障诊断:先分类,再决定补偿位置

现象 先读哪条证据 排查与边界
单个平台突然全部签名错误 SignUtil 第39行及实际平台 client 比较规范化、时间和应用路由;不打印密钥,不直接刷新所有店铺
token 刷新后仍报失效 PddClientHelper 第14行、刷新实际调用 检查路由对应和凭证版本;不要由方法名推断请求参数已经发送
同一次查询出现多次平台访问 代理第50行、RetryUtil 第69行 用离线桩数实际尝试,区分首次和重试;核对异常包装和开关
本地限制两次每秒,平台仍限流 XhsMallApi 第663、701行 多实例独立桶、内部重试、其他接口共享配额都可能影响
订阅成功但页面没有轨迹 订阅记录与物流主状态 订阅成功不是产生轨迹;继续查推送、持久化和业务关系
失败记录迟迟不补偿 任务第96行及 Mapper 第25行 核对创建窗口、次数上限、重试时间、用户分片与调度实际触发
签收后偶尔退回较早状态 轨迹更新第434行 区分事件时间、接收时间与并发写;已有局部防护不等于全面防倒退

对初学者最重要的操作纪律是:先使用请求关联号、平台方法、错误类别、耗时与尝试计数定位,不拿真实授权串做手工测试,不在排障时直接触发大批量发货、重订阅或补发。教学演练只用本地假响应与匿名记录。

9. 离线练习与参考答案

练习一:手算两种重试

题目:离线假 client 连续返回同一种可重试异常。代理配置最多两次尝试;内部工具允许两次重试。分别执行时调用几次?如果嵌套,能否直接断言六次?

答案:代理单独最多两次,内部工具单独最多三次。嵌套的理论乘积为六,但不能直接作为项目确定行为;需要满足外层开关、两层关键词和异常形态等条件。离线桩应记录每次调用的请求 ID、入口层和时间,不调用真实平台。验收包含:不可重试异常一次、第二次恢复成功、预算耗尽以及反射包装异常四组。

练习二:退款成功的订单怎么转换

题目:平台返回普通订单状态与退款成功状态,前端仍按订单状态显示“待发货”,应优先核对什么?

答案:核对 PddTradeUtil 第98行与第366行的退款、交易组合映射,再检查调用方是否使用统一状态还是原始数字。完整答案还应区分主单与子单。不能为了让页面正确而在组件里新增一套与后端矛盾的退款映射。

练习三:构造刷新参数却传了空 Map

题目:读 KsMallApi 第788行后,能否写“刷新接口已经带齐 refresh token 参数”?

答案:不能。构造 Map 和实际调用参数是两条证据;执行行传入空 Map,带参数的旧调用是注释。学习者应明确列出“构造了什么、传了什么、返回映射了什么、没有验证什么”,而不是修项目代码或拿生产凭证验证猜想。

练习四:补偿任务为何没处理某条失败

题目:当前有四条匿名失败记录:甲创建于三天前;乙重试六次;丙重试时间在未来;丁满足全部条件。普通自动遍历路径中,哪些是候选?

答案:按本章所读默认窗口和过滤,只有丁是候选;甲超出两天窗口,乙达到上限,丙未到时间。答案必须注明这是普通自动遍历路径;显式指定用户时是否启用时间过滤要按入口参数分析。即使丁是候选,也不保证调度已触发或下游调用成功。

练习五:旧轨迹覆盖新轨迹

题目:匿名时间线上先到达签收事件,后到达更早的运输事件。如何设计离线断言?

答案:使用固定事件时间和内存中的当前记录,分别验证“时间较早拒绝”“非待揽件不能退回待揽件”“同时间不同事件如何处理”。再增加两个并发处理者都先读旧版本的场景,说明 Java 层检查与数据库条件更新的区别。不能把已有防护覆盖不到的场景直接写成已保证安全。

练习六:设计集成操作记录

题目:为一个不调用真实平台的教学模型,设计能解释“请求超时但远端可能成功”的记录字段。

答案:至少包含租户、平台、店铺、业务操作 ID、参数摘要、外部请求 ID、尝试次数、开始与结束时间、结果状态、错误分类、下次检查时间和脱敏结果引用。结果状态需要保留“未知”,不能只有成功或失败。幂等作用域包含租户;记录里不要存明文 token、完整待签名串或不必要的个人信息。这是教学模型,不是对本项目表结构的宣称。

10. 官方资料与复盘清单

以下资料用于理解协议与机制;平台实际错误码、签名串、限额和刷新参数仍应查对应平台当前官方接口文档。旧项目的适配代码不能替代外部契约。

复盘时依次检查:能力是否支持;平台对象是否选对;授权与请求签名是否各自成立;金额与状态是否完成语义转换;重试是否有总预算和幂等依据;订阅与轨迹是否分离;补偿是否有窗口、上限和可观察结果。后端集成的核心不是“接口能调通”,而是“不可靠边界两侧的业务事实仍然能解释、能恢复、不会越权”。

原始文档 · erp-backend-handbook/19-Elasticsearch与搜索工程.md

19 Elasticsearch 与搜索工程

前置知识与学习目标

前置:理解03的索引、聚合和分页,以及09的数据同步。目标:知道搜索引擎如何找到文档,区分全文检索与精确过滤,理解分片搜索成本、分页一致性和索引更新延迟,并读懂项目的工单与日志搜索代码。

1. 项目事实和版本边界

管理后台的 ElkAppService〔本地文件〕 第38行提供查询入口,第44行组装SearchSourceBuilder,第77行采用from/size分页和createTime排序。另一个 TicketEsService〔本地文件〕 第61行也构造query_string查询。

根 pom.xml〔本地文件〕 第270行附近声明Elasticsearch及High Level REST Client 7.1.0。依赖声明不证明最终依赖树或服务器版本。尤其PIT在后续版本才出现:本章的PIT建议属于升级或兼容版本上的教学方案,不能直接当成7.1客户端已可用接口。

2. 倒排索引从什么地方节省时间

数据库B+树适合按有序键定位范围;倒排索引把词项映射到包含它的文档集合。三份文档分别写“订单取消”“订单退款”“物流退款”,词项“退款”就指向后两份。查询时可以交集或并集候选集合,并按相关性打分。

写入文本之前,分析器会经过字符过滤、分词和词项过滤。用户搜索的文本也需要相容的分析方式。“支付失败”和“支付已失败”能否匹配,取决于分析器与查询类型,而不是字面字符串完全相等。中文分词通常需要额外配置;项目此处未核实实际分析器,不能推断已安装何插件。

text适合分词全文字段,keyword适合订单号、租户、状态等精确值。一份标题常同时有text主字段和keyword子字段,但这是mapping配置选择,不是所有字符串天然都有 .keyword。排障时先看实际mapping和analyze结果。

3. query、filter、match、term

match通常对输入进行分析,用于文本检索;term查精确词项,常用于keyword字段。对text字段用term搜整句可能找不到,因为索引里保存的是分词后的词项。对keyword字段用match也不能自动得到你想象的中文全文效果。

bool的must/should可影响匹配和评分;filter关注是否满足,不需要为该条件计算相关性。租户ID、状态和日期通常适合filter,文本相关性放must。缓存是否实际使用受查询、段和策略影响,不能把filter理解为必定命中缓存。

教学DSL如下,只用于说明假设的mapping,不是现有集群请求:

{
  "size": 20,
  "query": {
    "bool": {
      "filter": [
        {"term": {"tenant_id": "tenant-1"}},
        {"term": {"status": "OPEN"}},
        {"range": {"created_at": {"gte": "2026-11-01T00:00:00Z", "lt": "2026-11-02T00:00:00Z"}}}
      ],
      "must": [{"match": {"content": "库存扣减失败"}}]
    }
  },
  "sort": [{"created_at": "desc"}, {"ticket_id": "desc"}]
}

租户filter必须由服务端附加。允许用户输入DSL时也要限制索引、字段、复杂度和结果量,不能让一个页面搜索框成为任意集群查询入口。

4. query_string 不是字符串包含

项目使用queryStringQuery并在“精确”分支设AND与Fuzziness.ZERO,在另一个分支设OR与AUTO。这里“精确”只描述代码选择的选项,不等于SQL =:query_string还涉及查询语法、分析器、默认字段等。引号、通配符、保留字符和非法语法都可能改变结果或产生异常。

如果产品只需要普通关键词,match或受限的simple_query_string通常更容易定义契约;高级语法搜索可以保留,但应提供允许字段和复杂度限制。真实方案需结合实际mapping和用户需求,不能仅凭一个方法名改动。

高亮代码选择整个字段片段,可能放大响应。高亮标签与用户原始内容交织时,前端需要安全地渲染,不能因为返回内容来自搜索服务就直接信任任意HTML。应区分后端生成的受限标签和需要转义的文档内容。

5. 搜索为何会“刚写完搜不到”

Elasticsearch近实时搜索的可见性与写入确认不是同一个时点。refresh使新段对搜索可见,flush与translog/恢复是另一组机制。写入返回成功不能自动等价于所有搜索立即可见。

需要读自己的写时,比较返回刚写入实体、按ID读取、在支持版本使用适当refresh策略等方案。每条写入都强制refresh会增加小段和合并开销。具体持久性、复制确认和refresh行为要以版本与配置为准。

ERP的主事实通常由数据库保存,搜索索引是面向查询的投影。页面搜索结果可以短暂陈旧,但提交退款或修改订单前必须对可信业务状态重新校验。用搜索命中的旧状态作为更新许可会引入并发漏洞。

6. 分片查询和深分页

from=100000、size=20并不只处理20条结果。每个分片可能需要收集前100020条候选,协调节点再归并。分片越多、深度越大,内存与CPU代价越高。提高max_result_window只是放宽保护,不会消除成本。

游标式search_after使用上一页完整sort数组,查询和排序必须保持一致,并提供稳定唯一兜底字段。时间相同却没有兜底字段时可能遗漏或重复。若分页过程中refresh改变了集合,无固定视图也可能出现不一致。

兼容版本可以配PIT保存分页视图;7.1项目不能直接照搬后续客户端PIT API。批量扫描还可能使用scroll,它保持搜索上下文,须及时释放,不适合无限打开给交互用户。依据部署版本选择并验证,而不是把所有分页API混成同一种能力。

7. 聚合、doc values 与高基数字段

按店铺、状态做terms聚合,通常使用keyword等可聚合字段。列式的doc values为排序和聚合提供访问路径;text字段启用fielddata可能显著消耗堆,应先检查字段建模。不能把关系数据库里某个列可GROUP BY的经验直接映射到text字段。

terms返回的是候选桶,分布式聚合下top桶选择和误差需看具体算法与返回信息;基数统计也可能是近似。财务报表若要求精确总额和全量分组,不能不看语义就采用默认top10聚合。

对高基数的订单号进行大规模分组会制造大量桶。可以比较composite分页聚合、提前汇总、缩小时间范围和业务数据库分析方案。性能实验需同时测聚合内存、桶数、超时及结果正确性。

数组对象也有陷阱:普通object数组可能把跨元素条件组合匹配;nested用于保留每个子对象的关联,但增加隐藏文档和查询成本。例如“同一条记录同时满足作者A且状态失败”,不能只凭两个数组字段各自命中就认定同一元素匹配。

8. 索引同步与重建

用稳定业务ID作为文档ID能让重复写入覆盖同一文档,但还要防旧事件覆盖新状态。可用源端版本或有序日志位点进行比较;时间戳必须考虑同精度并发和时钟来源。删除需要传播,旧事件重放不能让已删除文档复活。

重建新索引时,先确定快照与增量交接协议:从哪个位点开始追增量,如何处理全量扫描中被修改的记录,什么时候切别名,旧索引保留多久。双写两个索引并不自动原子,失败应可重试并对账。

mapping中某字段类型通常不能任意原地改成另一种类型;常用新索引、重建、校验后切别名。应用也要兼容迁移窗口,查询字段和序列化不能在部署之间失配。不要把生产删索引作为试验步骤。

9. 查询变慢的排查顺序

先确认输入范围、返回字段、分页深度、超时和业务目标。检查实际mapping、索引分片、数据量、热点、refresh/merge与线程池拒绝,再看慢日志和profile。profile有开销且不涵盖全部网络与排队耗时,用于受控诊断。

若应用测2秒而搜索响应took只有50ms,继续查连接池等待、网络、序列化、高亮内容体积、其他串行调用。若所有查询都变慢,检查集群资源与分片恢复;若只有单类查询慢,优先分析DSL和字段访问路径。

不要一次性把分片、堆、线程池和超时全调大。每次提出一个假设,改变一个可控因素并记录结果,才能知道改动是否有效。

10. 练习、答案与检查表

练习一:订单号 AB-001 搜不准。 先检查字段是text还是keyword以及分析结果;检查查询是term、match还是query_string。订单号精确检索通常建keyword并用term,但必须核实大小写和规范化规则。

练习二:用户翻到很深页接口超时。 核实from/size与分片数。交互改为游标;需要一致视图且版本支持时评估PIT;批量任务使用适当扫描接口。不能靠默认扩大结果窗口解释性能改善。

练习三:修改后页面仍显示旧状态。 分开查数据库是否提交、索引事件是否发送/消费、写入是否成功、refresh是否可见,以及页面是否有缓存。每一环都需要事件ID和版本关联。

练习四:搜索总数与数据库不一致。 对齐租户、删除、状态、时区、近实时延迟和精确/近似计数选项,再逐业务ID比较。搜索无积压也不证明旧漏数已补齐。

交付检查:mapping可解释;租户过滤可靠;排序稳定;分页与版本兼容;高亮安全;搜索投影可重建;旧事件不覆盖新值;失败文档可追踪;性能结论带数据规模和DSL。

官方资料

原始文档 · erp-backend-handbook/17-AI与RAG后端工程.md

17 AI 与 RAG 后端工程

前置知识、学习目标与证据规则

前置知识:理解 HTTP、Java Service、关系数据库和异步请求即可。前端开发者通常先接触聊天框、打字效果和 Markdown 展示;后端工程还要负责文档如何进入知识库、检索是否找对证据、权限是否贯穿全过程,以及模型变慢、用户取消和费用超限时系统如何收场。

本章实际阅读的是 erp-admin/ruoyi-modules/ruoyi-ai-rag,不是根据模块名套用某个网上架构。阅读对象包括 POM、向量服务、普通对话、知识库对话、SSE 控制器、远程转发服务和导入监听器。源码链接采用相对教材目录的 ../ 路径并标注行号。全文区分四类结论:启用代码指没有被注释的实现,不保证线上已启用;注释代码没有执行效力;依赖声明只证明构建依赖存在;教学设计或待核实项不得当作已实现架构。

本章未读取密钥配置或连接信息,未启动应用、模型、数据库、Redis 与远程 RAG 服务,未执行可能访问真实服务的示例测试,也没有修改项目源码。远程服务的内部索引、权限和评估能力不在本次证据范围,不能从 admin 的转发 DTO 反向虚构出来。

1. 先建立直觉:RAG 不是把数据库交给模型

RAG 是检索增强生成:先根据问题找到相关材料,再让模型依据材料生成回答。可以类比前端搜索页面先取得候选结果,再进行排序与摘要,但生成模型不是确定性模板。它可能遗漏证据、混淆版本,甚至编造没有来源的规则。

一条教学链路是:文档加载 → 清洗 → 切片 → embedding → 向量存储;查询时则是问题 embedding → 相似候选 → 重排 → 上下文组织 → 模型生成 → 输出展示。embedding 将文本映射为固定维度数值向量;向量距离表达模型学到的相近程度,不是业务权限、事实正确率或答案置信度。

先问“资料有没有入库”,再问“有没有被召回”,再问“排序和上下文是否正确”,最后问“生成是否忠实”。如果制度文档压根没入库,换一个更贵的聊天模型也不能修复这个根因。排障和质量评估都应按阶段拆开。

2. 实际项目地图:本地 Solon AI 路径与远程路径并存

2.1 不要把框架名称混为一谈

模块 POM,第20行〔本地文件〕 明确声明 org.noear:solon-ai-repo-pgvector:3.9.4,同时声明 PostgreSQL JDBC 驱动,以及 HTML、Markdown、PDF 加载依赖。模块不是因为运行在 Spring Boot 中就自动变成 Spring AI 的 VectorStore 实现。真正使用了什么,应看 import、构造注入和调用点。

VectorServiceImpl,第54行〔本地文件〕 注入 PgVectorRepository、ChatModel、EmbeddingModel、RerankingModel 等 Solon AI 类型。ruoyi-ticket-start 的 POM,第30行〔本地文件〕 又声明了对 ruoyi-ai-rag 的依赖,说明模块与启动工程的构建关系。依赖关系和注入代码仍不能证明某个部署实例已成功加载全部 Bean。

2.2 三条对话路径不要拼成一条

路径 已读源码证据 能确认什么
本地普通对话 ChatService,第27行〔本地文件〕 直接组织 prompt 与会话,然后调用聊天模型;这里没有检索步骤
本地知识库对话 VectorServiceImpl,第218行〔本地文件〕 检索、重排、拼接上下文,再组织聊天请求
显式远程 RAG 转发 RagRemoteChatController,第51行〔本地文件〕 GET、POST 入口把请求交给远程转发服务,并传递用户令牌

远程 DTO RagChatRequestV2,第17行〔本地文件〕 有知识库、关键词候选数、分类、文档 ID、类型和阈值等字段。这只能证明 admin 接受并转发这些字段,不能证明远程已经实现 BM25、混合检索、分类权限或严格阈值。甚至 DTO 的说明默认值与 Java 字段初始值也可能不同,阅读时优先报告实际字段赋值,不把 Swagger 描述当成运行结果。

2.3 能力证据分级表

能力 当前证据级别 不能顺手推导的结论
文本加载、切片与保存 本地启用代码 不保证所有格式和超大文件均可用
查询向量与余弦距离 SQL 本地启用代码 不保证已经建立 HNSW 或 IVFFlat
候选召回后调用重排模型 本地启用代码 不保证重排已有评测收益或失败降级
PDF 加载支持 POM 依赖声明 不能宣称上传 PDF 已真正完成解析入库
旧 VectorStore 构造片段 注释代码 不能作为正在运行的 Spring AI 架构
文档级 ACL、成本台账、质量基准 本章所读主链未见完整实现 不等于全仓库或远程服务必定不存在

3. 文档入库:加载、切片、元数据和导入完整性

3.1 当前文本入口真正做了什么

insertTextContent,第116行〔本地文件〕 先验证内容,再以是否包含 </html> 选择 HTML 或 Markdown Loader,随后执行 RegexTextSplitter 与 TokenSizeTextSplitter(500) 的流水线。这里的五百是切分器参数,不能未经对应版本实现核实就说成“五百个中文字”或“五百个 Java 字符”。token 与中文字符、英文单词不是一一对应。

切片要平衡两个方向:片太大,噪声和生成输入成本高;片太小,条件、结论、表头与行数据容易分离。ERP 手册中“退款条件”和下一段“不可退款的例外”如果被分开召回,模型可能给出危险的片面回答。合理的教学实验是固定同一批制度文档,比较按标题、段落、token 窗口和重叠策略的召回效果。本方法没有显式展示自定义重叠参数,不能杜撰为“已经配置固定重叠百分比”。

同方法第139行开始在缺少知识库或文档 ID 时生成 UUID,第148行写入 knId、knDocId,第153行调用仓库保存。元数据提供来源关联,但这两个字段的存在不等于已执行权限过滤。也不能仅凭 save 名称推断稳定去重、版本迁移、整篇替换或失败回滚;这些都需要继续阅读库版本和外层业务协议。

3.2 embedding 的真实边界

文本保存路径把文档交给 PgVectorRepository.save,embedding 的具体批处理和写入机制委托仓库实现;本地分页查询则在 第278行〔本地文件〕 明确调用 embeddingModel.embed(query)。这两种证据的强度不同:可以确认查询向量调用,但不能在未读依赖源码时虚构仓库的默认批大小、内部线程数和事务范围。

机制上,文档向量与查询向量必须来自兼容的语义空间。更换 embedding 模型时,即使维度刚好相同,旧向量也不应自然视作兼容;维度不同通常直接无法比较。教学设计应保存模型版本、维度、切片版本、原文版本和内容哈希,用新版本重建并灰度切换,而不是直接覆盖配置后宣称升级完成。这些元数据未在当前文本入库片段中完整展示。

3.3 “支持上传”的注释与空实现

loadFileByType,第164行〔本地文件〕 的主要文件读取、PDF/Tika 处理和写入内容都被注释,实际方法最终返回 null。接口注释列出 PDF、Word 等格式,加上 POM 中 PDF 依赖,都不足以证明上传链路可用。VectorController,第63行〔本地文件〕 仍提供上传入口并包装返回值,所以“接口返回成功包装”也不等于文件产生了可检索片段。

这里适合培养工程化验收:上传接收成功、格式解析成功、片段生成成功、向量计算成功、存储成功、最终可检索,是六个不同的状态。后端若对用户显示“导入完成”,应有可查询的任务状态、片段数与失败数,而不只是一次 HTTP 200。此处是教学设计,不是本模块现有导入状态机的声明。

3.4 Excel 导入的实际风险

VectorController,第138行〔本地文件〕 使用 EasyExcel 与监听器导入。KnowledgeDocListener,第25行〔本地文件〕 拼接标题和内容,交给 Markdown Loader,并附加业务 ID 和创建时间;这条路径没有显式复用文本入口的五百 token 切片流水线,不能把两种入口讲成完全一样。

更需要注意第40行:累计进 cache 的是本次文档列表,但达到批大小后,第43行传给消费者的是当前 splitDocuments,接着清空整个 cache。在“每行恰好一个片段”的离线假设下,前一百行可能只提交第一百行,其余累计片段被清掉。这是可由局部代码推出的数据丢失风险,不是已经在线复现的事故;本章遵守只写教材,不改实现。

VectorServiceImpl.add,第259行〔本地文件〕 还使用异步保存。控制器返回“解析完成”不自然等于异步向量写入全部成功。导入质量至少要核对输入文档数、生成片段数、提交片段数和实际可检索片段数,不能只看日志有没有报错。

4. pgvector:相似度 SQL、索引与召回的区别

4.1 余弦相似度不是准确率

pageList,第270行〔本地文件〕 在有 query 时计算向量,用 embedding <=> ?::vector 排序,并将 1 - distance 命名为 score。pgvector 中 <=> 是余弦距离;距离越小越相近,转换后的余弦相似度越大越相近。这个 score 不是“答案有百分之九十概率正确”,也不保证不同 embedding 模型之间的数值可直接比较。

同方法的总数 SQL 是全表计数,并没有因 query 自动变成“达到某阈值的相关结果数”。前端分页如果把 total 当成命中数展示,含义会偏离实际。页大小只处理了下限,没有在本段设置统一上限,也没有自动带上租户条件。

值通过参数绑定传入,但表名以字符串拼接。参数化不能绑定 SQL 标识符,因此表名必须来自服务端受控来源并限制合法范围,而不是让用户请求任意指定。本章不读取表名配置值,仅讨论源代码的数据流与安全边界。

4.2 声明 pgvector 依赖不证明创建了 ANN 索引

精确最近邻通常检查更完整的候选空间;ANN 以部分召回率交换延迟。HNSW 构造分层图,通常查询效果好但建设和内存成本较高;IVFFlat 划分列表,依赖合适的数据分布与探测参数。该比较来自 pgvector 官方机制,不是项目已采用其中某种算法的证据。

本章核对的模块 Service、Web 与 POM 中没有建立足以确认线上 HNSW/IVFFlat 状态的 DDL 证据。仓库封装或外部迁移可能负责建表建索引,但未验证,所以状态应写“待核实”,而不是“未建索引”或“已自动建 HNSW”。证明实际状态需要离线导出的 schema 或经授权查看数据库索引和执行计划;本次没有连接数据库执行。

以下是隔离实验库教学 SQL,不是项目迁移,也未执行。三维向量只是为了容易手算,业务真实维度未知:

CREATE TABLE rag_lab_chunks (
    id bigint PRIMARY KEY,
    tenant_id bigint NOT NULL,
    content text NOT NULL,
    embedding vector(3)
);

CREATE INDEX rag_lab_chunks_tenant_idx ON rag_lab_chunks (tenant_id);
CREATE INDEX rag_lab_chunks_cos_idx
    ON rag_lab_chunks USING hnsw (embedding vector_cosine_ops);

SELECT id, content, 1 - (embedding <=> '[1,0,0]'::vector) AS score
FROM rag_lab_chunks
WHERE tenant_id = 101
ORDER BY embedding <=> '[1,0,0]'::vector
LIMIT 5;

实验前需在隔离环境安装并启用扩展,这里不提供任何真实连接地址。索引算子类要与距离度量匹配。为让索引有机会生效,按距离算子升序并配合 LIMIT;不要把所有 SQL 都改成按复杂相似度表达式倒序,再假定规划器必定仍使用同一索引。小数据集选择顺序扫描也可能合理。

5. 召回与重排:找不到,还是排不对

similaritySearch,第92行〔本地文件〕 默认 topK=5,执行 new QueryCondition(query).limit(topK),随后调用 rerankingModel.rerank(query, results)。因此可以确认本地是“先候选检索,再重排”,不是“只有向量相似度排序”;也不能因为远程 DTO 有关键词字段,就给本地补上一条不存在于本方法的关键词召回链。

第一阶段的候选集合决定上限:正确文档没有进入候选,重排无法凭空找回来。第二阶段对 query 与候选内容作更细的相关性判断,可能提高前排质量,但带来额外延迟与费用。本地方法没有显示独立的“召回五十、最终取五”参数,也没有在这一段显示最低相关性门槛、去重、多样性选择或重排失败降级策略。教学优化必须作为新增设计说明。

故障拆分方式如下:

  • 入库缺失:正确文档在存储中就不存在,先检查导入提交与异步完成。
  • embedding 不匹配:向量维度或模型版本不一致,先核实向量空间,不先调 prompt。
  • 召回不足:候选中没有标准答案来源,比较精确检索基线、ANN 参数与切片策略。
  • 重排异常:候选正确但正确材料排不进最终上下文,检查重排模型、输入截断和去重。
  • 生成偏离:证据已经在上下文里,但回答仍错误,检查指令、冲突版本、会话污染和输出约束。

不能只看“最后答得像不像”。当答案恰好正确但引用错误来源时,检索问题仍然存在;当资料互相冲突时,安全答案可能是提示版本冲突,而不是强行选一个更流畅的说法。

6. 权限过滤:登录成功不是文档可读

6.1 当前查询没有显示完整 ACL 条件

本地 similaritySearch 的 QueryCondition 只显示 query 和 limit;元数据有知识库 ID 但这里没有显式加入该 ID 或租户、角色条件。get 与 delete,第327行〔本地文件〕 的 SQL 按片段 UUID 定位,也没有在这些方法中出现文档归属约束。结论应限定为“所读本地方法没有展示 ACL 过滤”,不能以此直接断言系统所有接口匿名可访问。

SecurityConfig,第98行〔本地文件〕 存在白名单装配,最终 第137行〔本地文件〕 对其他请求要求认证。URL 认证与数据权限是两层机制;即使登录要求正确,也不代表当前用户能读到任意片段。动态白名单值没有读取,运行时具体哪些 URL 放行不在本章结论之内。

6.2 必须在材料离开受控边界前过滤

教学设计应从可信登录上下文计算允许的租户和知识库,而不是信任请求中的 kbId、documentIds。检索 SQL 或仓库过滤应限制可见集合;返回前再次校验来源;详情、删除、导出和会话历史同样约束。不能先把其他商家的片段发给外部重排模型或生成模型,再仅在浏览器隐藏引用,那时泄露已经发生。

逻辑上先限定可访问集合,与数据库物理执行顺序不是一回事。ANN 查询即使带 WHERE,也可能先扫描近邻索引再过滤,从而返回不足 topK;这影响召回和速度,但不意味着可以删除权限条件。可在隔离实验中比较过滤列索引、分区、增大候选和版本支持的迭代扫描;生产方案要同时验收零越权与可接受召回。

会话组织,第223行〔本地文件〕 根据传入 sessionId 从 Map 获取或创建 Redis 会话;ChatService,第30行〔本地文件〕 也有同类逻辑。这些方法本身没有展示 sessionId 与当前用户归属校验。UUID 难猜不能代替授权,Redis 持久化也不会自动隔离租户。会话命名空间、历史取读权限、知识库授权变更后的历史处理,都属于需要单独审查的设计。

7. 上下文与 prompt injection:检索结果不是系统指令

getChatRequestDesc,第227行〔本地文件〕 检索材料后将正文以换行连接,再把知识内容和用户问题放入同一个格式化 prompt。提示词要求无法回答时明确说明,但第230行附近“检索为空就提前返回”的旧逻辑被注释,所以空候选在这条启用路径中仍可能继续生成。

RAG 的间接提示注入发生在知识材料中:一段看起来相关的工单或文档,可能夹带要求模型改变行为的文字。即使资料来自内部系统,导入来源、编辑权限与供应链也不等于完全可信。本段上下文只有正文拼接,没有显式展示结构化来源标识、信任等级或文档指令隔离;不能宣称已经具备完整注入防护。

教学防线应分层:系统指令与不可信材料分开组织;材料附文档 ID、版本与可核验引用;限制上下文长度;对来源、权限和格式作确定性校验;模型输出视为不可信内容。强调“文档中的命令不得执行”能减少误导,却不是数学意义上的安全隔离;关键词黑名单也无法穷尽改写、编码或多语言内容。

如果将来接 ERP 操作工具,退款、发货、改库存必须由执行层重新校验登录身份、对象归属、金额或数量范围和确认状态,不能让模型文本决定权限。当前所读普通 ChatService 虽 import 了工具相关类型,但第27行方法没有注册工具;不能仅凭 import 断言项目已有自动退款 Agent。

前端仍有自己的边界:模型生成的 HTML、Markdown 链接与图片不能无条件渲染。需要安全渲染和外链策略;不把浏览器可以显示某段输出等同为可执行指令。后端日志也应尽量记录文档 ID、阶段耗时、模型版本和错误分类,而不是完整问题、答案、授权串与客户个人信息;本地现有查询和回答日志值得作为隐私审查点。

8. SSE 与取消:流式输出不是全流程异步

8.1 本地 SSE 已经绑定哪些清理

RagSseController,第54行〔本地文件〕 的知识库流接口检查 prompt 和正数 topK,创建六十秒 emitter,获取 Flux 后订阅发送 message。第93行与第94行将完成和超时回调绑定到 disposable.dispose。这些是明确存在的本地订阅清理机制,不能漏写成“完全没有取消处理”。

但 VectorServiceImpl,第252行〔本地文件〕 在返回流前先调用 getChatRequestDesc;其中包含同步检索、重排和上下文构建。因此 publishOn(boundedElastic) 出现在返回 Flux 之后,并不把此前所有工作自动搬到异步线程,也不让此前检索天然可取消。页面等首字很久,可能卡在查询 embedding 或重排,而不是聊天模型生成。

dispose 表示取消响应式订阅,是否同时关闭底层模型 HTTP 请求、停止远程推理及停止计费,还取决于对应客户端和提供方行为。本章没有做外部实验,所以只确认本地回调,不保证上游成本立即归零。取消请求、停止展示、释放线程和终止生成是四个不同事件,应分别计时验收。

8.2 远程 SSE relay 有不同的行为边界

RagRemoteChatService,第54行〔本地文件〕 检查目标地址是否配置、用户令牌是否存在,然后把转发提交到线程池。第75行〔本地文件〕 使用 HttpURLConnection,显式传递 Authorization,设置连接和读取超时。缺少令牌被拒绝是本地事实;令牌有效性和远程文档权限仍由后续处理证明,不能由“带了头”直接推断。

远程服务第64行的完成、超时回调仅结束 emitter;提交的 Future 没有在这里保存成取消句柄,连接在 relay 的 finally 才 disconnect。因此不能把本地 Flux 路径的 dispose 行为移植成远程路径也已有同样取消传播。慢上游、客户端断开、线程长时间读等待,都需要离线假上游验证。

协议解析也值得读细:第103行〔本地文件〕 遇到一个 data: 行就转发一次,且调用 trim;标准 SSE 是在空行处合并一个事件内的多行 data,并只按规范移除冒号后可选的一个空格。因此当上游使用多行 data 或有意义的前后空格时,当前 relay 不等于完整透明的标准解析器;上游若始终每事件一行 JSON,部分问题可能不显现。这里没有声称已经在线复现。

8.3 前端契约与背压

原生 EventSource 主要面向 GET,构造参数不能任意设置 Authorization 头;需要 POST 与自定义头时,可选 fetch 流式读取并正确解析事件。不要为了方便把长期令牌放到 URL,URL 可能进入浏览历史和代理日志。

流式接口一旦响应已发送,后续错误通常需要通过约定事件告诉页面,不能指望把已经发出的 HTTP 200 改回 500。本地流发文本消息;远程控制器说明了来源、文本、错误、结束等 JSON 类型,但 relay 只是转发,不应把两套事件契约混用。教学协议可增加 requestId、序号、终态和可核验引用,但不是当前本地接口已有能力。

boundedElastic 或缓存线程池不代表无限承载。每条慢连接都占用缓冲、发送线程或远程连接;需要同时限制活动流数、候选规模、上下文长度和发送队列。自动重连若再次触发一次模型生成,可能重复计费;Last-Event-ID 只有配合服务端可恢复状态才有续传意义,不能凭协议字段获得现成的断点续答。

9. 配额与成本:次数限流还不是预算系统

RateLimitService,第35行〔本地文件〕 调用 Redis 脚本计数,超过限制返回 false,异常时记录日志并放行。这是可用性优先的 fail-open 选择,不是财务意义的硬上限。脚本具体原子逻辑需要另外读实现,不能仅凭类注释宣称已采用某种精确滑动窗口算法。

本模块明确看到的调用位于 RagChatController,第86行〔本地文件〕:生图提交按当前用户三次每分钟限制。不能因此写成所有本地对话、知识库检索和远程 SSE 都已统一限流。频率约束更不等于 token、货币或并发预算。

教学成本模型可以写成:一次问答成本等于查询 embedding、候选重排、生成输入、生成输出与必要重试的总成本;导入还有每个片段的 embedding 成本。若三十个候选每个八百 token,重排的处理量明显大于五个短片段;历史会话和重复上下文也会增加生成输入。单价取决于供应方、模型、缓存与计费口径,本章不给项目虚构价格。

生产预算的教学设计是:发起前按租户预占预算,设置最大输入和输出、最大 topK、最大并发;完成后按可获得的实际 usage 对账;取消、超时和失败也要结算可能已发生的费用;无法立即取得 usage 时保留待对账状态,避免重复扣减或盲目全额退款。高费用路径可选择配额存储失效时拒绝、降级或人工放行,而不是默认继承当前计数服务的异常放行策略。这里没有证据证明模块已有完整成本台账。

10. 质量评估:从“看起来不错”变成可比较证据

KnowledgeDocListenerTest,第15行〔本地文件〕 是读取本机表格并输出片段数量的示例,不能作为标准 RAG 质量基准,也不适合在本次约束下直接运行。本章所读主链没有展示完整 Recall、排序、忠实度和越权基准;这只是本次范围内的结论,不否认其他工程可能存在评估体系。

教学评估集必须由可公开的虚构 ERP 文档组成,每题保存问题、身份、允许来源、标准证据和预期行为,并固定文档版本、embedding 版本、模型、切片参数和 prompt 版本。至少覆盖正常规则、跨段条件、过期版本冲突、找不到答案、同义改写、精确错误码、无权限资料和材料中的注入文字。

指标 含义 不足与配套
Recall@K 标准相关来源中有多少进入前 K 候选 先定义按文档还是片段,避免重复切片刷高分
Precision@K 前 K 候选中有多少真正相关 相关不代表可授权,权限必须单独评估
MRR 首个相关结果名次倒数的平均 适合强调第一条结果,不覆盖全部证据
nDCG@K 按相关性等级和位置折损评估排序 需要稳定标注等级与理想排序
证据忠实度、引用正确率 结论是否由允许来源支持,引用是否准确 模型评分需要抽样人工复核,不能自证正确
拒答正确率、越权泄露 无依据是否拒答、无权限材料是否外泄 单列安全失败,不被平均流畅度掩盖
首 token 延迟、总时长、取消延迟、费用 体验、资源回收与成本 同时报分位数、失败率与统计样本数

评估还要区分两种召回:ANN 相对精确近邻的算法召回,与相对人工标准答案的业务召回。前者很高,不证明 embedding 能理解某个 ERP 条款;后者很低,也未必是索引参数造成。比较版本时对同一批题作成对比较,保留逐题结果,不能换一批更容易的题后宣布提升。

安全评估只放虚构标记和假执行器。未发现某次泄露只能说明该样本未观察到失败;模型输出拒绝语也不能证明没有发生上游外传。应该分别观察传给重排和生成的材料、响应、引用、假工具调用以及配额结算。评估错误和缺失观测应记为未定,不能算成功拦截。

11. 故障演练与参考答案

练习一:PDF 上传返回成功,为何搜索不到

题目:只允许读源码,不能上传真实文件或连接模型,先检查哪里?

答案:看 VectorController 第63行调用的 loadFileByType,再看 VectorServiceImpl 第164行。主体处理是注释,实际返回 null;POM 的 PDF 依赖只声明能力组件。正确报告是“当前入口未看到启用的解析入库实现”,不是“embedding 服务一定故障”。离线验收应由假 loader、假 repository 统计真正提交片段数。

练习二:用一百零一行验证批处理完整性

题目:假设每个匿名 Excel 行解析为一个 Document,批大小一百。按当前监听器,何时提交、提交什么?

答案:第一百行达到阈值时,提交的是当前行的列表,而非累计一百行,随后累计缓存清空;第一百零一行在结束回调提交。该简化假设下只提交两个片段,而预期是一百零一个。离线桩用列表收集传入的 ID,断言提交集合等于输入集合且每个只出现一次;加入九十九、一百、一百零一和单行多片段边界。此处没有运行真实 EasyExcel 或向量服务,也没有修改监听器。

练习三:材料相似,但来自别的商家

题目:租户甲问退款规则,租户乙的片段相似度最高。能否先让模型生成,再让前端隐藏来源?

答案:不能。权限必须在材料发给重排或生成服务之前落实,且查询详情、历史会话和删除同样验证归属。把乙片段发给模型本身就可能越权。带 WHERE 的 ANN 返回不足五条是召回优化问题,不能拿取消权限条件解决。

练习四:topK 从五改成五十就一定更好么

答案:不一定。可能提高候选覆盖,但也会增加重排处理量、上下文噪声和成本。当前方法没有独立的最终上下文条数参数,要先确认返回集合与上下文拼接。用同一评估集比较候选 Recall、最终排序、答案忠实度、延迟和成本,不能只看回答长度变长。

练习五:点击停止后为何仍有费用

答案:浏览器停止与上游终止不是同一件事。本地 SSE 已绑定 dispose,但底层取消是否传播未知;检索与重排可能在返回 Flux 前就已执行;远程 relay 没有在当前完成回调中直接中断上游连接。离线假流应分别记录用户取消、订阅取消、上游关闭和最后一次计费事件,要求资源在约定期限内释放,不能把页面停止打字当成完整验收。

练习六:SSE 多行 data 应该收到几次

题目:假上游发送一个事件,包含两行 data:,最后用空行结束。标准客户端和当前 relay 可能有什么区别?

答案:标准将两行 data 以换行连接,分发为一个事件;当前代码按每个 data 行立即发送,可能变成两个事件,并因 trim 改变空格。离线测试还应覆盖中文跨读取边界、CRLF、注释心跳、空 data、id 和异常断开,不能只用一行 JSON 的理想输入证明完整符合标准。

练习七:材料中出现“忽略规则”,怎样评测安全

答案:把这句放进虚构知识片段而不是只放在用户问题里,才能测试间接注入;片段之外放一个无真实价值的测试标记,使用无副作用假工具,观察是否越权取数或调用。预期是保留正确业务摘要、不执行片段指令、不泄露不允许来源,并记录正常问题有没有被误拒。不能把关键字命中率当成完整安全率。

练习八:设计预算异常时的行为

题目:Redis 配额检查失败,是否应与现有 RateLimitService 一样总是放行?

答案:先区分保护目标。普通低成本请求可能选择可用性优先,但高费用生成需要硬预算、并发或降级保护。教学系统可在配额状态未知时拒绝高费用操作,并保留可追踪错误;所有预占和结算以请求 ID 幂等处理。不能仅因项目已有一个计数服务,就宣称已具备跨模型的费用上限。

12. 官方资料、版本注意与落地复盘

  • Solon AI 官方源码与介绍:核对 Document、Loader、Splitter、EmbeddingModel、Repository、RerankingModel 和流式接口。当前上游文档可能已变更,本项目声明的是 3.9.4,学习 API 时必须对应版本,不能直接用最新示例改写项目事实。
  • pgvector 官方 README:重点看距离算子、精确与近似搜索、HNSW、IVFFlat、过滤、索引使用和召回监测;扩展新版本特性不代表当前数据库已经可用。
  • PostgreSQL 行级安全官方文档:理解数据库侧权限防线;引入依赖不会自动启用 RLS,需设计角色、策略与测试。
  • WHATWG Server-sent events 标准:核对多行 data、空行分发、UTF-8、id、重连与 Last-Event-ID,不把自定义简化解析当作标准全部语义。
  • Reactor Core 官方参考文档:理解订阅、取消和调度边界,尤其是 publishOn 不会把调用之前已执行的同步工作搬走。
  • Spring MVC 异步请求官方文档:理解 SseEmitter 的生命周期与异步响应;框架文档版本要与项目实际依赖比对。
  • OWASP LLM Prompt Injection Prevention Cheat Sheet:学习间接注入、最小权限、输出安全与评估边界;提示词隔离不能替代执行层授权。

完成本章后,请为任意一条提问链路写出六张清单:输入与身份、入库与版本、候选与权限、上下文与引用、流与取消、配额与评估。每个结论都能指向真实代码或明确的待核实项,才算从“做出聊天界面”迈向“能承担 ERP 业务风险的 AI 后端工程”。

原始文档 · backend-learning/验证记录.md

课程补全与阅读站验收记录

日期:2026-11-11。前半部分保留第一轮课程补全的验收记录,文末追加第二轮深化与图解的实测结果。两轮均为结构普查及重点内容抽查,不是对所有业务代码、所有教材段落或全部部署环境的全面审计。

内容交付

  • 原数据库28章与Spring20章的编号Markdown保留;各新增补充阅读,旧HTML生成器纳入补充阅读并重新生成。
  • 新增Java工程基础5章、分布式8章、高并发7章、运维排障7章,共27章;附源码证据、反例、练习答案和实验说明。
  • 复用既有综合手册的平台SDK、Elasticsearch、AI/RAG三个专题,明确标作旧教材延伸,而非本轮新写。
  • 统一站包含六条主线与一个专题延伸分组,共78篇编号正文;连同目录、实验、审阅与验证说明约24万汉字。构建manifest记录实际纳入文件与内容哈希。
  • 12个顶级业务项目POM普查用于技术地图;12种源码风险示范区分局部事实、成立条件与待验证影响。不声称已证实线上事故或完成渗透测试。

实际运行的测试

范围 数量 结果与边界
分布式协议模型 18 全部通过;SQLite与内存模型,非真实Broker或网络分区
高并发协议模型 8 全部通过;有界队列、checkpoint、fencing与库存模型,非压测
虚构日志分析 18 全部通过;JSONL解析、去重、统计、时间窗与坏行处理
Spring机制复核 11 全部通过;Spring/H2/JDK实验,非业务集成

本轮新实验44项,加既有Spring复核11项,共55项通过。数据库旧实验未在本轮全部重跑,不能将其历史结果改称本轮验证。

静态与界面检查

统一验证器检查编号、Markdown围栏、本地链接存在、源码行号范围、HTML内部锚点、离线资产、生成内容哈希与发布包文件白名单。两套旧课程的原验证器也通过。有限敏感字面量检查未命中私钥标记、明显长凭据赋值或指定业务数据库主机模式;这不是完整秘密扫描。

JavaScript通过Node语法检查。Chrome实际检查320、390、768和1440宽度下布局,页面无整体横向溢出;长代码与表格保留独立横向滚动。检查了目录打开/关闭、全文搜索命中、无结果提示、清空、字号、明暗主题和锚点完整性。截图检查包含桌面首页、手机首页和手机深色正文。复制功能提供Clipboard API及受限环境的选中文本回退;未声称所有浏览器的剪贴板权限均已测试。

本地HTTP预览只绑定127.0.0.1,CSS与JavaScript返回200。没有发布到公网,也没有申请域名或托管账号。远程部署后的CDN缓存、TLS、访问控制和手机真实网络效果仍由部署环境验收。

发布与保留范围

发布包只包含index.html、assets/reader.css、assets/reader.js,不包含业务Java/XML/YAML、真实日志、环境配置或Maven凭据。正文仍可能描述内部结构和文件名,公开前应由你确认可公开范围,必要时使用受限访问。

原始Markdown及旧阅读版继续存在。新站不自动访问业务系统;本地源码引用转换为证据提示,线上不会试图下载业务仓库。所有教学参数与容量数字都不是生产推荐配置。

第二轮:开发陷阱深化与图解

新增数据库、Spring、分布式、高并发、运维五篇深化正文,以及外部输入/文件/网络安全、图解导读和补课路线。具体取证见数据库与Spring审阅、分布式到运维审阅。原编号章节内容保留,并在六处加入图示;对执行器章关于done归还许可的表述作实质纠正,明确逻辑取消不等于任务体和资源已经退出。

本轮新增六张本地SVG:请求调用链、事务代理、线程池接纳、Outbox/Inbox、租约fencing、可靠导出。图示是带前提的教学模型,不是生产拓扑。它们在图解导读与相关正文共放置十二次,构建时内联进HTML,不依赖Mermaid/CDN,不增加发布包必需文件。手机横向查看和放大弹窗使用同一矢量内容。

第二轮实际执行结果

执行范围 数量 结果及证据边界
新增数据库场景 9组 MyBatis真实XML片段生成BoundSql、H2关系与批执行;全部通过,不执行业务SQL
新增Spring场景 8组 数据源资源绑定、路由、rollback-only、自调用、提交后事件与线程边界;全部通过
新增取消模型 13项 全部通过,包含7776条有界序列;不模拟JMM或真实IO取消
新增日志契约探针 8项 全部通过,已保存为可复跑脚本;验证输入内口径,不证明采集完整
既有分布式模型复跑 18项 全部通过,内存/SQLite协议模型
既有高并发模型复跑 8项 全部通过,非生产压测
既有虚构日志分析复跑 18项 全部通过,不是对真实日志的完整性验证
既有Spring机制复跑 11项 全部通过,JUnit报告零失败、零错误、零跳过

本轮新增38个场景组/测试项,另复跑55项既有测试。这些计数口径分别保留,不将有界枚举序列数冒充独立集成测试数量。新Java实验使用缓存依赖、临时编译目录和进程内H2;没有业务应用启动、真实MySQL、MQ、Redis连接或生产压力测试。

第二轮阅读站验收范围

统一验证器增加SVG XML解析、标签与引用目标、内联图数量、活动脚本/外部引用检查;原有本地链接、代码围栏、源码行号、内容哈希和ZIP白名单检查保留。新深化篇同步纳入原数据库及Spring阅读版。Spring旧版图示同样内联,仍可单文件离线阅读。

统一验证器与数据库、Spring原验证器均已通过,JavaScript语法检查通过;发布ZIP仍只包含首页、CSS和JavaScript,内联图无需另下载资源。这些静态检查不能代替逐条SQL与源码语义的人工审查。

Chrome检查覆盖1440宽度下六张图的可读性、320与390宽度下图内横向滚动、放大弹窗、Esc退出、关闭后移除克隆,以及弹窗开启时无重复ID和断裂箭头引用。手机视口无页面整体横向溢出,全文搜索可命中新深化篇。只验证浏览器模拟视口,未把它描述为真实手机设备测试。正式发布后的网络缓存、宿主权限和目标手机兼容性仍需部署验收。

原始文档 · backend-learning/reviews/database-spring.md

数据库与 Spring 第二轮深化审阅记录

本记录说明深化篇补上了哪些知识缺口、结论依赖什么证据,以及哪些问题仍需要目标环境验证。面向从前端转 Java ERP 后端的读者,重点是把“知道规则”推进到“能判断真实调用是否满足规则”。本轮是按主题选择正文和源码进行审阅,不代表全量段落核验、全仓库代码审计或线上安全认证。

一、阅读范围与新增内容

先审阅已有相关正文,再围绕缺口定位具体源码。重点范围如下,未声称对表内每章的每个段落都重新逐句核验。

已有正文范围 已有知识 本轮加深的问题
数据库第 25 章动态 SQL、分页、插件、批处理与事务接点 空集合要有策略,批执行与多 VALUES 不同 真实空 Example 与空 IN 的结果区别、批结果何时可用
数据库第 09 章、27 章的事务资源与 JDBC 批写 资源一致、驱动与连接池有边界 同 URL 不同资源、行数与实体成功数的区别
数据库第 01、03 章的唯一性、NULL、JOIN 与分页相关段落 唯一约束、关系基数、稳定排序 二次删除重建冲突、NULL 有效标记、COUNT 与 LIMIT 粒度错位
Spring 第 05、06 章的代理、路由、传播与回滚 自调用绕过代理、传播规则 已有外层事务时的 self 调用、新事务的资源依赖
Spring 第 13、16 章的事件与事务测试相关正文 AFTER_COMMIT 不等于可靠消息、测试可能默认回滚 提交后资源仍可见、测试替业务开启事务的假阳性、跨线程逃逸

新增正文各七个深化主题,每项均包含源码事实、条件风险、改进设计和验证边界,并配有练习答案。实际篇幅按文件中 Unicode U+4E00–U+9FFF 汉字逐字计数,不把英文、路径、数字或标点计作汉字:

文档 实际汉字数 阅读入口
数据库开发陷阱深化 5,035 打开数据库深化篇
Spring 开发陷阱深化 5,965 打开 Spring 深化篇

两篇均超过 3,500 汉字。既有教程正文、README、构建器及业务代码未作修改;没有提交代码。新增实验与业务工程隔离。

二、数据库知识缺口闭环

缺口 源码事实与定位 已建立的结论及验证状态
空集合错误被统一描述为全表操作 库存 deleteByExample#L116〔本地文件〕、用户批删#L250〔本地文件〕 已验证空 Example 可生成无 WHERE;空 IN 则可能留下语法不完整的谓词。没有执行业务删除,未证明线上入口会传空。
CASE 批更新只有 WHERE 就认为安全 batchUpdateStorageStock#L405〔本地文件〕 明确整批同用户、复合键配对、重复增量聚合三个前提。已验证 CASE 首匹配机制;真实混用户写入与索引仍待验证。
参数绑定与身份隔离混淆 Example OR 组#L25〔本地文件〕、权限片段写入#L151〔本地文件〕 结构来源和 OR 括号作用域需分别检查;不能把组织权限、分片路由和租户隔离视为同一保证。真实旁路鉴权待验证。
COUNT 正确就认为分页正确 父子映射#L7〔本地文件〕、详情联表#L49〔本地文件〕 已用合成关系验证三条联表行、两个父对象、第一页仅一个父。明确现有普通用户列表并非该角色联表;未声称已发现线上分页故障。
batch 命名等于 BATCH 执行器 多 VALUES 插入#L385〔本地文件〕 区分单条大 SQL、JDBC batch、MyBatis BATCH。已验证占位返回值、flush 不提交、批异常回滚;MySQL 驱动行为待验证。
影响行数等于导入成功实体数 广告 upsert#L82〔本地文件〕、补偿 INSERT IGNORE#L4〔本地文件〕 分开业务幂等、数据库行变化与警告;官方机制已核对,真实 MySQL 行数、唯一键与连接属性待验证。
逻辑删除后唯一性只测一次 有效用户查重#L169〔本地文件〕、逻辑删除#L246〔本地文件〕 提供二次删除重建反例、可空唯一键反例及有效槽生成列设计。没有据 Mapper 推断部署索引;MySQL 方案明确待执行。

三、Spring 知识缺口闭环

缺口 源码事实与定位 已建立的结论及验证状态
同数据库地址就一定在同一事务 动态源装配#L140〔本地文件〕、工厂注入#L118〔本地文件〕 已验证同 URL 的不同 DataSource 不自动共享受管连接;生产管理器与 Mapper 装配待验证。
路由键变化等于事务立即切库 DynamicDataSource#L17〔本地文件〕、切面清理#L39〔本地文件〕 已验证事务绑定后改变路由仍使用旧连接;嵌套恢复、线程池身份、Hint 和懒连接组合待验证。
self 调用一定没有事务 private 库存方法#L1391〔本地文件〕、模板边界#L1427〔本地文件〕 区分模板直接管理事务与注解代理。已验证 self REQUIRES_NEW 未形成独立提交,跨 Bean 调用形成独立提交。
catch 后就能继续正常提交 库存写入回调#L1427〔本地文件〕 已验证跨 REQUIRED 拦截边界后的 rollback-only,与方法内局部 catch 后提交这两个不同结果。真实双表失败原子性待验证。
新事务补偿必然可以落库 补偿 record#L38〔本地文件〕、失败处理#L2227〔本地文件〕 已验证独立提交;提供连接池饥饿和锁依赖的有界实验步骤,但未实际执行连接池压力实验。
提交后还能取资源就还能原事务提交 环境更新副作用#L150〔本地文件〕 事件是教学改进,非现有实现。已验证无事务/回滚不触发,提交触发,独立事务写入可见;持久任务崩溃恢复待验证。
默认回滚测试能证明服务事务有效 既有代理测试#L69〔本地文件〕 已新增外层事务掩盖缺陷、线程池写入不随父事务回滚的反例。未把模拟外层事务等同完整 TestContext 或 HTTP 集成。

四、可复跑证据与适用边界

新增隔离实验的最终结果为 SQL 九组 + Spring 八组全部 PASS,进程退出码为零。各组包含结果断言,不是仅验证调用次数。实验固定 MyBatis 3.5.13、Spring Framework 5.3.39、H2 2.2.224;这些是实验版本,不是线上依赖版本证明。

文件 用途与证据
SqlShapeChecks.java〔本地文件〕 只读提取指定真实 Mapper 节点;验证 SQL 形状,使用合成 H2 表验证 JOIN、CASE 与 BATCH。
TransactionChecks.java〔本地文件〕 手工装配教学 Context;验证资源绑定、路由、代理、回滚标记、事件及线程边界。
run.py〔本地文件〕 使用固定版本的本地缓存 JAR;缺依赖即停止,无自动下载;临时编译目录结束后清理。

在工作区根目录运行:

python3 spring-course/labs/pitfalls/run.py

要求 JDK 11 或更高,产出 Java 8 字节码。SQL 形状检查不连接数据库;其余实验仅使用进程内 H2,没有启动 ERP 或连接业务服务。没有读取业务 YAML、环境配置值或秘密配置。实验不证明真实 Mapper 参数对象与插件装配、InnoDB 锁与驱动计数、分片资源事务或生产容量。

技术资料已按主题核对官方来源,链接就近放在正文:MyBatis 动态 SQL 与固定版本 BatchExecutor、MyBatis-Spring 事务装配、Java 8 JDBC 批异常、MySQL 8.4 UNIQUE/生成列/upsert/IGNORE、Connector/J 批重写,以及 Spring 5.3 事务、路由、事件和测试 API。引用当前 Spring 传播页的连接池警示时,已标明它与固定 5.3 实验的版本边界。

五、读者完成练习后的验收标准

数据库题应写出输入集合、身份条件、生成 SQL、匹配行粒度、提交结果五项;Spring 题应写出代理入口、管理器、受管资源、异常越界位置与独立观察点。不能以“有注解”“有 WHERE”“没有抛错”替代正确性证据。

本轮已闭合的是知识解释、源码定位和上述离线反例。目标 MySQL、真实插件、连接池及崩溃恢复属于明确保留的待验证项;应按深化篇中给出的数据集、故障时点和结果断言继续验收,而不是将本报告解读为这些运行风险已经被消除。

原始文档 · backend-learning/reviews/distributed-operations.md

第二轮深化审阅:分布式、高并发与运维

审阅日期:2026-11-11。范围为分布式、高并发与运维的三篇深化正文,以及隔离任务状态模型。报告区分源码静态事实、确定性模型结果和仍需集成验证的事项。

审阅顺序与证据范围

先读分布式第 02、03、07 章,高并发第 01、02、06 章,运维第 02、04 章及第 05、06 章相关段落,再查看具体实现。扩展内容集中在原文尚未展开的分支、相等性、许可所有权、事件解析语义和兼容窗口。

新增文档 本轮深化证据 失败时间线
分布式开发陷阱 SSE 解析与路由不同异常边界;RDS 早 ACK 与后台 catch;队列登记后中断;TradeMessage 相等性不含内容;入口只传第一条;顺序扇出与毒消息 A—E,共五条主线,另有条件变体
高并发开发陷阱 SCM 每调用新建信号量;worker 内等待;中断未获取也 release;Index 静默拒绝;SCM 异步异常回调与同步拒绝区别;关闭未接收退回列表 A—F,共六条主线
运维开发陷阱 event_id 去重与 trace 集合;unknown 与未知枚举区别;扩展字段归一化;sample_complete 范围;MDC 回退;日志级别与控制台去向;启动关闭边界 A—F,共六条主线

每篇包含具体源码证据、相对路径 #L 行号和带答案练习。源码事实、条件风险、改进设计、验证状态分别标明;推演不等于线上事故,建议方案不等于已部署能力。阅读 done 回调示例时,需特别核对“逻辑完成不等于资源退出”的前提。

环境边界:证据来自已定位实现、日志路由与虚构实验数据,不包含 application、bootstrap、环境变量文件、真实运行日志或业务转储的验证结果;没有连接业务服务。运行版本、动态配置和生产故障均不能由本报告直接推定。

官方核对与版本边界

已执行验证

新增 test_cancellation.py〔本地文件〕 只使用 dataclasses、itertools、unittest,无线程、sleep、网络、业务模块导入或配置读取。

python3 -B high-concurrency-course/labs/test_cancellation.py -v

实际结果:退出码 0,13 tests,OK。核心覆盖如下:

验证项 实际断言
准入拒绝 未获取许可者归还零次
执行器明确拒绝 已获取许可归还一次,重复拒绝/通知不多还
排队取消 不进入任务体也能归还,残留包装器不能再启动
入队前取消 不能重新入队或启动
运行取消 future_done 为真仍占许可,直到任务体退出
开始与取消竞争 两个线性化顺序均检查
完成与取消竞争 保留先赢状态,不发布被取消结果
失败及重复回调 归还恰好一次
静默丢弃 不会自动产生终态;显式补偿后才释放
关闭过程 退回排队任务与运行任务分别处理
两个错误策略反例 finally-only 漏还;done 提前归还导致容量一却有两个活跃任务
有界枚举 六种事件五步序列,共 7776 条,逐步检查守恒,显式完成清理

模型假设状态转换原子化。它没有验证 JMM、线程可见性、CAS 实现、真实 FutureTask 回调线程、中断响应、TTL/trace 包装器、连接释放、数据库事务或 MQ 可靠性。模型禁止取消后的结果发布,不代表外部副作用已经撤销。任务不退出时许可不释放,是资源仍被占用的体现,测试没有用超时虚构退出。

另有课程回归复核结果:分布式 18 项、高并发旧测试 8 项、运维 18 项、Spring 11 项均通过。高并发旧测试与本次新模型合计 21 项。此处区分独立回归复核与上述直接执行的新模型,避免重复计算或把其他课程测试冒充本模型覆盖。

运维离线内存探针实际结果:退出码 0,8 个场景全部通过。通过 runpy.run_path 取得现有分析器的纯分析函数,使用内存构造的 JSON 字符串调用,不运行其命令行入口,不创建数据文件,不连接服务。结果如下:

虚构输入场景 实际结果
两个不同事件共享 trace,第一条再投递一次 requests=2、duplicates=1、slow_trace_ids 长度=1
同 event_id、不同 service conflicts=1、sample_complete=false
outcome=timeout invalid=1、requests=0
event=request_finished ignored=1、sample_complete=true
同事件仅 deployment_id 扩展字段不同 duplicates=1,说明当前归一化不保留该字段
duration_ms=0.8 p95_ms=0.8、sample_complete=true;类型检查无法识别真实单位错误
只有一条合法成功记录 sample_complete=true、failure_ratio=0;不能证明输入外没有遗漏
outcome=unknown failures=1、invalid=0,与未知枚举不同

上述断言检验现有分析器的真实函数行为,没有模拟采集系统本身。八个场景现已保存为可复跑测试〔本地文件〕,执行python3 -B operations-course/labs/test_log_contracts.py -v。事件基本字段为带时区ts、request_completed、event_id、service、route、trace_id、status、outcome、duration_ms。脚本是同一组探针的持久化版本,不重复增加场景计数。

文档静态检查实际结果:全部相对文件链接存在,36 处源码 #L 引用的行号均在对应文件范围内,三篇正文均超过 2500 汉字。按中文字符区间计数,分布式 3173 字、高并发 3650 字、运维 3830 字;分别包含 5、6、6 条失败时间线。行号存在性检查与人工源码语义核对分别完成,前者不被当作后者的替代。

待执行闭环清单

  • [x] 先审阅已有正文,再沿具体源码定位分支。
  • [x] 文档逐项标出事实、触发条件、改进建议和验证边界。
  • [x] 用官方 API/实现核对 Future 取消、许可、公平和消费成功语义。
  • [x] 运行新增标准库取消模型,确认 13 项通过。
  • [x] 运行八个虚构日志契约探针,确认事件去重、枚举、扩展字段和单位边界。
  • [x] 检查正文长度、相对链接、源码行号与失败时间线;保留运行验证和静态核对的区别。
  • [ ] 隔离 Java 程序固定 acquire 中断点,验证未获取许可不 release,并验证中断标记。
  • [ ] 隔离 Java 程序验证排队取消、运行取消不响应中断、done 与真实退出时序,以及 TTL/trace 包装器。
  • [ ] 取得 AsyncTemplate 的完整实现,核验静默拒绝后 Future 和持久任务状态。
  • [ ] 使用假的 route 和隔离 MQ 客户端验证解析异常、路由异常、批次多条、位点推进和重投;不接业务服务。
  • [ ] 固定队列登记后 put 中断、同键不同负载及同订单乱序完成的故障点。
  • [ ] 核验业务事件身份、顺序键、重试账本键、毒消息隔离和同聚合版本缺口恢复。
  • [ ] 用可控到达序列验收租户最长等待与跨请求配额,不以 Semaphore 公平参数代替租户公平。
  • [ ] 使用隔离 Logback 与假的失败输出流验收日志不可写、慢写、丢弃、采集恢复及独立告警。
  • [ ] 单线程连续请求与嵌套调用测试 MDC/attachment 清理恢复;检查实际日志输出。
  • [ ] 完成旧新生产者、解析器、查询器、回滚与历史重放的 schema 兼容矩阵。
  • [ ] 生产级结论需另取得部署版本、输入覆盖、运行指标和授权演练证据;本轮不以模型结果代替。

这些未勾选项是生产化与集成验收边界。学习时可按其顺序设计隔离实验;在没有对应运行证据前,不应宣称真实客户端、数据库和部署环境已满足这些保证。

回到目录 ↑