架构与系统设计 / 系统课时
字典与功能开关
字典与功能开关
本课实现平台默认值与租户自定义值的合并,并让字典和功能开关在运行期间动态生效。完成后,同一套代码可以为不同租户返回不同选项和功能状态。
学习目标
- 理解字典项与功能开关的合并差异
- 实现平台默认值和租户覆盖值的解析逻辑
- 设计配置变更后的缓存刷新与生效验证
两类配置不能用同一种合并规则
字典是一组带业务编码的可选项,例如订单状态、退款原因和支付方式。租户通常需要修改名称、停用某项或增加自定义项,因此适合按 code 合并。
功能开关回答的是“某项能力是否启用”。租户值存在时直接覆盖平台默认值,不存在时回退到默认值。开关最好使用稳定的键,例如 partial_refund,不要使用页面标题作为键。
可运行的合并示例
下面的 Java 代码演示两种规则:字典按编码覆盖并保留顺序,功能开关按键覆盖。示例使用 JDK 17,不依赖第三方库。
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
public class TenantConfigMergeDemo {
record DictItem(String code, String label, boolean enabled) {}
static List<DictItem> mergeDictionary(
List<DictItem> defaults,
List<DictItem> tenantItems) {
Map<String, DictItem> merged = new LinkedHashMap<>();
// 先放平台默认项,再由相同 code 的租户项覆盖。
defaults.forEach(item -> merged.put(item.code(), item));
tenantItems.forEach(item -> merged.put(item.code(), item));
return List.copyOf(merged.values());
}
static Map<String, Boolean> mergeSwitches(
Map<String, Boolean> defaults,
Map<String, Boolean> tenantValues) {
Map<String, Boolean> merged = new LinkedHashMap<>(defaults);
merged.putAll(tenantValues);
return Map.copyOf(merged);
}
public static void main(String[] args) {
List<DictItem> defaultReasons = List.of(
new DictItem("DUPLICATE", "重复支付", true),
new DictItem("CUSTOMER_REQUEST", "客户要求", true)
);
List<DictItem> tenantReasons = List.of(
new DictItem("CUSTOMER_REQUEST", "顾客主动取消", true),
new DictItem("OTHER", "其他原因", true)
);
Map<String, Boolean> defaultSwitches = Map.of(
"partial_refund", false,
"manual_review", true
);
Map<String, Boolean> tenantSwitches = Map.of(
"partial_refund", true
);
mergeDictionary(defaultReasons, tenantReasons)
.forEach(item -> System.out.println(
item.code() + "=" + item.label() + "," + item.enabled()));
System.out.println(mergeSwitches(defaultSwitches, tenantSwitches));
}
}预期输出:
DUPLICATE=重复支付,true
CUSTOMER_REQUEST=顾客主动取消,true
OTHER=其他原因,true
{partial_refund=true, manual_review=true}CUSTOMER_REQUEST 保留原位置但名称被租户值替换,OTHER 作为新增项追加。功能开关中,租户只覆盖 partial_refund,未设置的 manual_review 继续使用平台默认值。实际输出中 Map 的展示顺序不应作为业务契约。
动态生效链路
动态生效不等于每次请求都查数据库。更常见的做法是读取缓存,配置发布后通过事件通知各实例失效对应缓存;下一次访问再从数据库加载新版本。

推荐的事件至少携带 tenantId、configType 和 version。消费者先比较版本,再删除本地缓存和共享缓存。删除缓存天然适合重复执行,因此比“收到事件后直接把消息里的值写入所有缓存”更容易保证幂等。
为避免数据库更新成功但事件发送失败,可以使用事务消息或本地消息表。配置变更不应依赖单次广播恰好成功,否则部分实例会长期读取旧值。
开关使用边界
功能开关应控制可逆、可降级的行为,例如灰度开放新流程或临时关闭高风险功能。不能用开关绕过权限校验、数据隔离或金额校验,因为这些属于安全边界。
代码读取开关时,应统一通过服务接口,例如 featureSwitchService.isEnabled(tenantId, "partial_refund")。不要让业务代码直接访问 Redis 或配置表,否则缓存策略、默认值规则和审计逻辑会散落在各模块中。
字典停用项通常只影响新建数据,历史记录仍需能够正确展示。保存业务数据时应保存稳定编码,展示时再解析名称;不能只保存中文名称,否则租户改名后无法区分历史语义。
验证动态生效
发布配置后,应按以下顺序验收:
- 查询数据库,确认新版本和内容已提交。
- 检查变更事件是否成功消费,旧缓存是否失效。
- 使用目标租户请求接口,确认返回租户覆盖值。
- 使用未定制的租户请求同一接口,确认仍返回平台默认值。
- 回滚配置版本,再次确认各实例恢复一致结果。
验证接口返回时应同时记录租户编号、配置版本和追踪标识,但不要在日志中输出敏感配置内容。多实例环境至少连续请求数次,确认没有部分节点仍返回旧版本。
本课总结
- 字典适合按业务编码合并,功能开关适合按稳定键直接覆盖
- 动态生效应采用版本化缓存与变更事件,而不是每次请求查询数据库
- 开关不能替代权限和数据隔离,历史数据应保存稳定字典编码
下一课预告
下一课将继续处理租户配置的发布与回滚,重点解决多实例环境中的版本一致性、审计记录和异常恢复。