架构与系统设计 / 系统课时

字典与功能开关

字典与功能开关

本课实现平台默认值与租户自定义值的合并,并让字典和功能开关在运行期间动态生效。完成后,同一套代码可以为不同租户返回不同选项和功能状态。

学习目标

  • 理解字典项与功能开关的合并差异
  • 实现平台默认值和租户覆盖值的解析逻辑
  • 设计配置变更后的缓存刷新与生效验证

两类配置不能用同一种合并规则

字典是一组带业务编码的可选项,例如订单状态、退款原因和支付方式。租户通常需要修改名称、停用某项或增加自定义项,因此适合按 code 合并。

功能开关回答的是“某项能力是否启用”。租户值存在时直接覆盖平台默认值,不存在时回退到默认值。开关最好使用稳定的键,例如 partial_refund,不要使用页面标题作为键。

可运行的合并示例

下面的 Java 代码演示两种规则:字典按编码覆盖并保留顺序,功能开关按键覆盖。示例使用 JDK 17,不依赖第三方库。

java
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));
    }
}

预期输出:

text
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 或配置表,否则缓存策略、默认值规则和审计逻辑会散落在各模块中。

字典停用项通常只影响新建数据,历史记录仍需能够正确展示。保存业务数据时应保存稳定编码,展示时再解析名称;不能只保存中文名称,否则租户改名后无法区分历史语义。

验证动态生效

发布配置后,应按以下顺序验收:

  1. 查询数据库,确认新版本和内容已提交。
  2. 检查变更事件是否成功消费,旧缓存是否失效。
  3. 使用目标租户请求接口,确认返回租户覆盖值。
  4. 使用未定制的租户请求同一接口,确认仍返回平台默认值。
  5. 回滚配置版本,再次确认各实例恢复一致结果。

验证接口返回时应同时记录租户编号、配置版本和追踪标识,但不要在日志中输出敏感配置内容。多实例环境至少连续请求数次,确认没有部分节点仍返回旧版本。

本课总结

  • 字典适合按业务编码合并,功能开关适合按稳定键直接覆盖
  • 动态生效应采用版本化缓存与变更事件,而不是每次请求查询数据库
  • 开关不能替代权限和数据隔离,历史数据应保存稳定字典编码

下一课预告

下一课将继续处理租户配置的发布与回滚,重点解决多实例环境中的版本一致性、审计记录和异常恢复。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

字典与功能开关

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通