binarywang/WxJava · error · RuntimeException

请确保微信小程序配置 appId 的唯一性

Error message

请确保微信小程序配置 appId 的唯一性

What it means

Thrown by the Spring Boot multi-account MiniProgram (小程序) starter when two tenants share the same appId, preventing Redis token/ticket cache key collisions (see WxMaRedisConfigImpl#setAppId). Unlike the Solon sibling, this message correctly says "微信小程序". After the check passes, the starter branches into SHARED vs ISOLATED multi-tenant mode.

Source

Thrown at spring-boot-starters/wx-java-miniapp-multi-spring-boot-starter/src/main/java/com/binarywang/spring/starter/wxjava/miniapp/configuration/services/AbstractWxMaConfiguration.java:56

    if (appsMap == null || appsMap.isEmpty()) {
      log.warn("微信小程序应用参数未配置，通过 WxMaMultiServices#getWxMaService(\"tenantId\")获取实例将返回空");
      return new WxMaMultiServicesImpl();
    }
    
    /**
     * 校验 appId 是否唯一，避免使用 redis 缓存 token、ticket 时错乱。
     *
     * 查看 {@link cn.binarywang.wx.miniapp.config.impl.WxMaRedisConfigImpl#setAppId(String)}
     */
    Collection<WxMaSingleProperties> apps = appsMap.values();
    if (apps.size() > 1) {
      // 校验 appId 是否唯一
      boolean multi = apps.stream()
        // 没有 appId，如果不判断是否为空，这里会报 NPE 异常
        .collect(Collectors.groupingBy(c -> c.getAppId() == null ? 0 : c.getAppId(), Collectors.counting()))
        .entrySet().stream().anyMatch(e -> e.getValue() > 1);
      if (multi) {
        throw new RuntimeException("请确保微信小程序配置 appId 的唯一性");
      }
    }

    // 根据配置选择多租户模式
    WxMaMultiProperties.MultiTenantMode mode = wxMaMultiProperties.getConfigStorage().getMultiTenantMode();
    if (mode == WxMaMultiProperties.MultiTenantMode.SHARED) {
      return createSharedMultiServices(appsMap, wxMaMultiProperties);
    } else {
      return createIsolatedMultiServices(appsMap, wxMaMultiProperties);
    }
  }

  /**
   * 创建隔离模式的多租户服务（每个租户独立 WxMaService 实例）
   */
  private WxMaMultiServices createIsolatedMultiServices(
    Map<String, WxMaSingleProperties> appsMap,
    WxMaMultiProperties wxMaMultiProperties) {

View on GitHub (pinned to 1c43293a3c)

Solutions

1. Enumerate `wx.miniapp.apps.*.appId` and ensure all are distinct and non-blank.
2. Restart once deduplicated.
3. Then verify `multiTenantMode` (SHARED/ISOLATED) matches your cache isolation intent.

Example fix

# before
wx.miniapp.apps:
  t1: { appId: wxmini001 }
  t2: { appId: wxmini001 }
# after
wx.miniapp.apps:
  t1: { appId: wxmini001 }
  t2: { appId: wxmini003 }

// Spring Boot Miniapp multi: pre-flight appId uniqueness
Set<String> seen = new HashSet<>();
for (WxMaSingleProperties p : appsMap.values()) {
    if (p.getAppId() == null || !seen.add(p.getAppId())) {
        throw new IllegalStateException("Duplicate/null miniapp appId");
    }
}

When it happens

Trigger: Two entries under `wx.miniapp.apps` with the same `appId`; two entries both with null appId (collapsed to key `0`).

Common situations: Reusing one mini-program appId on multiple tenant keys; blank appIds after partial config migration.

Related errors

• 请确保微信公众号配置 appId 的唯一性
• 请确保微信视频号配置 appId 的唯一性
• 请确保企业微信配置唯一性[{corpId}]
• 请确保微信公众号配置 appId 的唯一性
• 请确保微信开放平台配置 appId 的唯一性

AI-assisted analysis of binarywang/WxJava@1c43293a3c (2026-08-14). Data as JSON: /api/errors/08c3aa68d80dc113. Report an issue: GitHub.