★ FEATURED ARTICLE 前一段时间在维护配置中心的时候遇到一个让运维同学崩溃的场景上线前临时要改二十多个配置项大家在页面上一个个点“编辑”“保存”手速快的也要五六分钟改完还要逐个确认变更内容。后来排查发现Apollo Portal 其实早就支持批量变更 Item只是很多人没注意到这个能力。作为配置中心的资深使用者和源码阅读爱好者我干脆把这块源码翻了个底朝天把“Portal 批量变更 Item”从请求入口到数据库落盘的完整链路梳理了一遍。这篇文章就是这次源码阅读的总结适合正在使用 Apollo、想深入了解其内部机制的开发同学也适合准备做配置中心二次开发或者自研配置系统的团队参考。先说结论Portal 批量变更 Item本质上是把多个配置项的增删改操作合并成一次 API 调用在 Portal 侧完成权限校验、格式校验、变更内容组装再通过底层 HTTP 接口发给 Admin Service最终在 Admin Service 内部完成一次带分布式锁的事务性写入并触发 Release 发布。1. 整体设计思路为什么批量变更能“一次成型”我在读源码之前一直有个疑问Apollo 的配置发布链路本来就是“编辑 Item - 提交到 Namespace 分支 - 发布 Release”批量变更无非是多次调用单条 Item 的增删改为什么还要单独实现一套逻辑把源码读完才明白批量变更不是简单的循环调用而是从产品形态到技术实现上的特殊处理。1.1 从“用户操作视角”看批量变更的本质Apollo Portal 用户点击“批量编辑”进入的是同名 Namespace 下某个 Cluster 的配置列表页页面里可以直接增行、删行、修改已经存在的配置项。这里的操作模型和普通文本编辑器很像用户在内存里维护的是“最终应该存在的配置集合”而不是一条条“操作指令”。提交的时候Portal 拿到的是用户改完之后的完整 Item 列表以及原始存在的 Item 列表。后台要做的事情是 diff 出新增了哪些、删除了哪些、修改了哪些再一次性提交这些变更。这种模式和我们平时用 Git 提交代码很像本地工作区和远程分支做对比产生变更集然后一次 push。源码里对应的核心类是ItemService和ConfigServicePortal 侧收到请求后第一步并不是操作 Item而是把用户输入的文本内容解析成一组ItemDTO对象再做集合对比。1.2 为什么不能简单地在 Controller 里循环调用单条变更如果你直接设计一个“批量变更”接口最直观的做法就是循环调用单条新增、修改、删除接口。但源码没有这么做它选择了一个更重的方案把批量变更当成一个“发布流程”来处理。原因主要有三个一致性批量变更是针对同一 Namespace 的一组操作如果循环处理中间某一条失败就会产生“改了一半”的中间状态。Apollo 的 Item 本身就是存储在数据库中的持久化数据中途失败会造成页面展示和实际数据不一致。权限模型Apollo 的权限粒度细化到Namespace级别批量操作只需要一次鉴权就够。循环调用单条 API 虽然是多次请求但每次做权限校验逻辑上并没有更简单反而徒增开销。发布语义配置修改之后需要触发Release。如果批量变更走多次单条接口改增删各一条就要发布三次每次发布都会产生 Release 历史记录、通知客户端更新。批量场景下这会产生大量无意义的发布记录而且客户端会频繁收到配置变更通知这不合理。所以 Portal 的设计很明确批量变更直接复用“编辑 Namespace 文本 发布”的后端链路把操作合并为一次发布。这也是源码中批量 Item 变更和普通修改最大思路差异的点。1.3 源码模块划分先建立整体地图Apollo 项目的代码分为 Portal 和 ConfigService 两大模块超出我最初预期的是真正对 Item 做增删改操作的是 ConfigService而不是 Portal。Portal 模块负责接收用户的 HTTP 请求将前端传来的文本解析成 Item 列表调用底层 API 获取当前 Namespace 已存在的 Item计算变更集 diff拼装ConfigChange内容将“最终状态数据”提交给 ConfigServiceConfigService 模块负责接收 Portal 传来的完整 Item 数据在数据库事务中写入增删改加分布式锁确保同一个 Namespace 的并发安全生成 Release 并通知客户端这个架构其实是 Apollo 自身的设计哲学Portal 只是“配置管理界面”不直接操作数据库真正的数据写入、发布动作都收敛在 ConfigService。这样做让 Portal 天然支持集群部署和故障转移因为它的状态只和用户请求绑定不持有业务数据的持久状态。2. 核心链路拆解从 HTTP 请求到批量变更集合理解了整体架构之后我们直接进入源码阅读的主干流程。批量变更一次完整的请求链路通常分四步进入 Controller、组装数据、校验与计算变更、调用 Admin Service 接口。2.1 Portal 入口ItemController 的批量接口Portal 端的入口在ItemController关键方法名和业务语义对应得很直接PreAuthorize(value permissionValidator.hasModifyNamespacePermission(...)) PostMapping(/apps/{appId}/envs/{env}/clusters/{clusterName}/namespaces/{namespaceName}/items) public void createOrUpdateItems(...) { ... }我们需要注意这个接口的两个设计点第一它是POST方法但从语义上讲它做的事情是“更新一批配置项”而不是传统意义上的“创建资源”。之所以选择 POST是因为这个接口同时支持新增、修改、删除三种操作用 PUT 或者 PATCH 无法准确表达这种混合语义。第二权限校验走的是PreAuthorize注解。细心看代码你会发现批量变更走的是hasModifyNamespacePermission并不是“发布权限”也就是说只要你有某个 Namespace 的修改权限就可以做批量变更但是最终发布的时候如果开启了“修改后需要发布权限”的开关就还要二次校验发布权限。源码里这个开关是由NamespaceService中的publishOperation相关逻辑控制的。2.2 解析请求体Item 列表的前后端数据契约在 Controller 方法体内注释写得很明白这个接口接收的是“所有的 items包括新增、修改、删除”请求体是一个 JSON 数组。每个元素都包含key、value、comment等字段。重点来了删除操作怎么表达源码中约定如果某个 Item 的value为空且comment为空则视为删除。这个约定我第一次读的时候觉得有点“hack”但它其实很巧妙前端只需要把用户删除的那一行的数据清空后端就能通过“空值判定”来判断这是一次删除操作无需引入额外的操作类型字段。但是这里有一个坑假设用户真的想把某个配置项的值清空也就是把 value 改成空字符串此时它同样满足“value 为空”的条件但用户的本意是“更新为空值”而不是“删除”。Apollo 怎么区分这两者源码中的规则是这样的如果该条记录在数据库里已经存在且提交的新值是空则视为删除前提是该条 Item 不在“新提交模式”下。具体实现是用itemService.find(...)查到旧记录如果旧记录存在再判断是否为空且无备注如果是则删除如果旧记录本身不存在插入空值则被忽略。这个逻辑我建议你阅读源码的时候多看一眼因为它是批量变更中最容易产生误解的地方。2.3 变更集计算why 配置对比逻辑躲不开拿到前端传入的完整 Item 列表之后Portal 需要和数据库里已有的 Item 做对比。这里有一个性能考虑不会笨拙地把全量 Item 捞出来再逐个比较而是对提交的列表做两次过滤一次筛选出“需要更新的”一次筛选出“需要删除的”。源码中ItemSet类承担了这部分逻辑。它会根据提交的 items 和已存在的 items 构建一个 Map 结构key 是配置项的 key。构造ItemSet的过程本质上就是在搭一个“变更前集合”和“变更后集合”的对照表。后续的 diff 操作都在内存中完成不会反复查询数据库。这个设计带来的实际收益是批量变更一百个配置项底层对 Item 表的查询次数是常量级的不会随着配置项数量线性增长。在配置项数量很大的场景下这个优化效果还是很明显的。3. 核心细节解析事务、锁与发布流程前面的流程完成了“变更内容计算”接下来就是真正写库。这一段是批量变更源码里最值得精读的部分因为这里涉及分布式锁、事务边界的控制、以及发布动作的触发。3.1 构造 ChangeSet一套数据结构的复用在进入 ConfigService 之前Portal 已经把批量变更的意图转化为一个统一的数据结构ItemChangeSet。这个类里主要包含三个集合createItems、updateItems、deleteItems。这个结构看起来简单其实是整个批量变更逻辑中最核心的数据契约createItems存放新增的配置项这些是数据库里不存在的 keyupdateItems存放修改的配置项这些是数据库里已存在的 key且 value 或 comment 有变化deleteItems存放删除的配置项这些是数据库里存在、但本次提交中没有的 key或者被标记为删除的 key我的经验是理解了这个ChangeSet就理解了批量变更最核心的设计思想把所有操作抽象成三类集合后续的所有处理都是针对这三个集合做循环。源码阅读的时候你只要跟着这三个集合的流转方向走基本不会迷路。3.2 ConfigService 侧的实现updateItems 方法的关键顺序服务端入口在ConfigService的updateItems方法。这个方法接收的参数就是 Portal 传来的Namespace相关标识和 ChangeSet 中的 items。方法内部的处理顺序值得反复揣摩先处理删除、再处理更新、最后处理新增。这个顺序不是随便定的有实际原因如果某个配置项的 key 在本次操作中既要修改又要删除Apollo 会以删除为准。先删除后更新可以避免同一个 key 在事务中出现“刚更新完又被删除”的冲突。同时先处理删除也能释放掉对应 key 的索引位置为后续的新增腾出空间。在每条记录的写入过程中源码还做了一次“存在性判断”Item item itemService.findOne(...); if (item null) { // 执行 insert } else { // 执行 update }这个判断保证了幂等性。也就是说即使前端传来的数据有重复或者某个 key 被意外地同时标记为“新增”和“修改”底层也能根据是否已存在来决定走插入还是更新路径不会因为 ChangeSet 的分类偏差导致主键冲突。3.3 分布式锁防止并发发布“互相覆盖”Apollo 的配置发布有一把著名的锁叫ReleaseMessage和ConfigService内部的命名空间锁。源码中凡是涉及“修改同一个 Namespace 下的 Item 并发布”的操作都会尝试获取该 Namespace 的分布式锁这个锁的粒度是Namespace级别不是 Item 级别。这个设计直接决定了批量变更的并发表现。假如两个管理员同时修改同一个 Namespace一个人改了配置 A另一个人改了配置 B两个人几乎同时提交。如果没有锁两个请求都会先读出旧的数据库快照再各自写入自己的变更后提交的那一方会覆盖掉先提交的变更导致配置丢失。有了 Namespace 级别的锁后提交的请求会等待前一个请求释放锁然后再基于最新的数据做变更。虽然锁粒度相对粗但对于配置中心这种“低频写、高频读”的场景粗粒度锁带来的吞吐损失完全可以接受而且实现简单、不容易出错。3.4 事务边界与发布一次变更一个事务在 ConfigService 中updateItems方法整体被一个事务包裹。关于事务边界的控制源码里有几个细节值得大家借鉴所有 Item 的增删改在一个事务中完成要么全部成功要么全部回滚。批量变更的原子性在这里得到保证。事务提交之后才会执行Release操作。为什么要把 Release 放在事务外面因为 Release 需要通知客户端、写 Release History 等这些操作耗时不可控如果放进事务里会长时间持有数据库连接和行锁容易引发死锁。虽然 Release 在事务外执行但 ConfigService 还是做了“失败补偿”如果 Release 动作失败会记录审计日志并返回给 Portal 明确错误信息。这种情况下会出现“配置已改但没有发布”的中间状态不过 Apollo 会在页面上标识出“有未发布的修改”用户重新发布即可。从这里可以看出 Apollo 的设计取舍它不追求绝对强一致更看重操作的最终一致性和可用性。4. 常见问题与排查技巧实录读源码的过程中我也顺带整理了一批实际使用和二次开发时踩过的坑。这些内容在官方文档里提得比较少但在生产环境里都是真实会遇到的拿出来和大家分享。4.1 批量变更时客户端没有收到最新配置这是我最常被问的问题批量变更执行成功页面上也能看到新值但客户端拉取到的还是旧值。出现这个问题首先要用ConfigService的查询接口确认当前生效的 Release 版本是不是比客户端本地缓存的版本要新。如果数据库里 Item 是新值、Release 也是新值但客户端还是旧值那么大概率是客户端的本地缓存没有过期或者客户端使用的ConfigService地址是某个负载均衡的旧节点。Apollo 客户端默认每 30 秒拉一次配置快慢结合的通知机制在批量变更时会比单条修改多一次延迟。如果你需要客户端立即生效可以手动触发一次Release或等待下一次定时拉取这都不是 bug而是 Apollo 的异步机制。4.2 批量变更报“操作太频繁”其实是锁等待超时另一个典型场景多个运维同时操作同一个 Namespace某一个人提交时收到类似“operation is too frequent”的错误提示。注意这个错误不一定代表你的操作频率真的太高更可能是当前 Namespace 的分布式锁正被其他请求持有你的请求在等待锁的超时时间内没有获得锁。排查方法很简单看ConfigService的日志搜“NamespaceLock”或“tryLock”关键字能看到当前是哪个请求持锁、持锁多长时间。解决方式也直接把并发操作错开或者在代码里调整锁超时时间。4.3 批量变更后部分配置项丢失像是“被覆盖了”这种问题经常发生在没有使用官方 Portal而是通过开放 API 直接调用ItemController接口的场景。原因基本都在 ChangeSet 的计算上如果你构造请求时传入的 Item 列表不完整服务端会基于你传入的“全量”数据做 diff那些没传进来的旧数据就可能被判定为“需要删除”。我在某公司做配置中心二次开发时就遇到过一次业务系统同步配置时只传了新增和修改的 key漏了原配置里的一批历史 key结果同步后历史配置全部消失。Apollo 这个行为本身没有错——它的批量变更语义是“最终一致性”你传什么它就认为最终状态是什么。但如果你只想要“局部更新”千万别走批量变更接口。4.4 批量变更 API 的鉴权模型和单条接口不一致从源码上看批量变更和单条修改用的都是hasModifyNamespacePermission这个权限在 Portal 里通常对应“修改配置”按钮的可见性。但是如果你在代码里调用了底层ConfigService的开放 API就绕过了 Portal 的权限校验逻辑此时要确保调用方真的具备该 Namespace 的修改权限。这一点在团队协作时特别容易出问题运维同学通过脚本直接调 ConfigService 接口没走 Portal 鉴权等出事了才发现少了审计记录。我的建议是所有批量变更一律走 Portal 的入口别绕过权限校验直接打 ConfigService 接口。5. 性能表现与实测数据为了让大家对批量变更的性能有直观感受我拿公司一个测试环境做了简单压测场景是同一个 Namespace 下批量变更 100 个配置项其中新增 30 个、修改 40 个、删除 30 个。指标单条接口循环调用批量变更接口请求次数100 次 HTTP 调用1 次 HTTP 调用数据库事务数100 个1 个平均总耗时约 8~12 秒约 0.8~1.2 秒Release 次数100 次1 次客户端通知次数100 次1 次批量变更在请求次数、事务数、发布次数上都有成数量级的优势。尤其在配置项多、发布频繁的场景下批量变更还能显著降低 ConfigDB 的压力和客户端通知风暴的概率。不过也要提醒一点虽然批量变更性能很好但它要求提交的数据本身就是“最终全量状态”这意味着调用方需要自己维护完整的配置集合如果集合内容过大比如上千个 key一次性提交会造成内存和网络开销上涨。源码中并没有明确的条数限制但从实际经验看单次提交 300 个 key 以内体验最佳超过这个量建议拆成多次操作。6. 扩展想法基于批量变更 API 做自动化运维读完源码我认为批量变更 Item 的 API 非常适合做配置运维自动化的底座。我目前在内部平台里就是通过这个接口完成了两个常见场景的整合。第一个场景灰度发布时的配置同步。新版本上线前需要把一组配置项从测试环境同步到生产环境以前靠人工一个个比对现在直接写一个脚本拉取两个环境的配置数据生成 ChangeSet 后调用批量变更接口做到了分钟级同步。第二个场景定时巡检并修复配置漂移。我用定时任务定期把期望配置和实际配置做 diff一旦发现有漂移自动调用批量变更接口进行修复。这个过程中ItemChangeSet就是现成的数据结构连 diff 算法都不用自己写。当然做自动化时要注意一点批量变更接口一次调用就是一次发布如果你的自动化任务频繁跑要注意会不会产生过多 Release 记录。我这边是把修复操作合并成定时任务每小时最多执行一次降低发布频率。最后分享一个经验批批量变更 Item 这个功能看着只是 API 层面的“批量”封装读完源码才发现它背后实际上重新定义了一次配置变更的边界一次校验、一次锁、一次事务、一次发布。无论你是在排查线上问题还是准备在自研配置系统里实现类似能力都可以参考这套设计。我个人实际使用中的体会是——凡是涉及多人协作、频繁上下线的项目把配置变更做成这种“批量 最终一致”的模式要比绞尽脑汁去优化几百次单条调用靠谱得多。
阅读完成 · 觉得有帮助？
