系统配置

为了更好的开发体验，我们将逐渐将全部的配置项整合到一张表中，并在 basic-paper-config 模块中统一维护。

由于配置项较多而繁杂，所以我们要进行分类维护，后端会使用不同的实现类来存储不同类别的配置，且对应着前端的配置菜单。在页面上也是分类维护，这里会按照不同的菜单来分类。 简而言之，后端的存储和前端的菜单展示是一一对应的关系。

国际化问题

配置项的国际化是在对应页面的组件中处理，不使用 vueI18n 进行国际化。是为了减少 index.js 的体积。会在下面的章节中详细介绍如何进行国际化处理。

后端指南

由于配置项属于系统参数，所以要在程序中完成细致的权限控制，以及配置参数是否有效的校验等功能。为了实现这个功能，我们会将全部配置项都编写在代码中，统一管理。

初始化配置项

添加配置项非常简单，只需实现 IBpConfigurationStore 接口后，将配置项信息写成常量即可。主要代码如下，详细信息可用看源码中的注释，或者参考已经写好的代码。

@Component
public class ExampleConfigurationStore implements IBpConfigurationStore {

    private static final String MENU_DATA_ID = "settingExample";

    private static final BpConfigurationAO[] BP_CONFIGURATIONS = new BpConfigurationAO[]{
            BpConfigurationAO.of(ExampleConfigurationKeyConsts.EXAMPLE, "30",
                    BpConfigurationType.PREFERENCE, RegexPattern.ZERO_ONE, ByteBooleanEnums.FALSE,
                    MENU_DATA_ID, "备注信息！用于说明配置信息，不需要展示给用户"
            ),
    };

    /**
     * 获取全部配置项
     */
    @Override
    public BpConfigurationAO[] configurations() {
        return BP_CONFIGURATIONS;
    }
}

API

属性名	类型	说明
configKey	String	配置的 key，为了防止重复，请携带对应的模块名称，如：工单模块一般都是使用 ticket 开头，为小驼峰命名方式
configVal	String	配置的值，可以根据时间情况而定，多数为字符串或者枚举值。
configType	BpConfigurationType	配置类型，分为运维配置和运营配置。运营配置-只要有管理员权限就可以修改，运维配置-只有在开启运维模式时才可用修改。
configValRegexPattern	Pattern	用于验证值的合法性，根据值的类型编写正则
isPublic	ByteBooleanEnum	是否为公开可查的，1-是，则会返回给前端，前端可用使用此值 0-否，仅后端可用，前端无法使用
menuDataId	String	所属菜单的 data-id，如果不设置则无法被查询到。
remark	String	备注信息！用于说明配置信息，不需要展示给用户

添加无鉴权配置项

某些配置项可能不需要登录即可访问，例如：登录页面的多语言信息、可切换语言。webcall 客户端的一些配置。这个时候就要将这些配置项暴露给无需鉴权的前端， 需要在 IgnoreAuthConfigurationKeyHolder 中配置。前端可以通过特定的接口，传入 category 来获取相关配置。

/**
 * 忽略鉴权的配置项的 key
 *
 * @author 王金城
 * @date 2024/6/12
 **/
public class IgnoreAuthConfigurationKeyHolder {

    /**
     * 登录页需要无鉴权查询的数据
     **/
    private static final List<String> LOGON = Arrays.asList(
            LocalizationConfigurationKeyConsts.PREFERRED_LANGUAGES,
            BrandingConfigurationKeyConsts.PREFERRED_THEMES
    );

    /**
     * webcall 客户端
     **/
    private static final List<String> WEBCALL_CLIENT = Arrays.asList(
            WebcallConfigurationKeyConsts.ADVERT_ENABLED_WEB_LEFT,
            WebcallConfigurationKeyConsts.ADVERT_BACKGROUND_WEB_LEFT
    );

    /**
     * 存储全部无需鉴权的配置 key，使用 category 存储，可以在 {@link com.simperfect.bp.config.controller.BpConfigurationController#queryExposeConfigurations(String)} 接口查询
     **/
    private static final HashMap<String, List<String>> IGNORE_AUTH_CONFIGURATION_KEYS = new HashMap<>();

    static {
        IGNORE_AUTH_CONFIGURATION_KEYS.put("login", LOGON);
        IGNORE_AUTH_CONFIGURATION_KEYS.put("webcall_client", WEBCALL_CLIENT);
        // 如有需要其他分类，直接添加即可
    }

    /**
     * 获取指定分类的配置 key
     *
     * @param category 分类名字
     * @return java.util.List&lt;java.lang.String&gt;
     * @author 王金城
     * @date 2024/6/12
     */
    public static List<String> get(String category) {
        return IGNORE_AUTH_CONFIGURATION_KEYS.get(category);
    }

}

前端指南

提示

这里是前端配置页面的编写教程，如何使用这些配置项请移步至 前端配置项使用 进一步了解。

1. 页面样布局可以使用 BpConfigurationContainer 组件快速编写。
2. 配置项可以 BpConfigurationItem 组件完成开发。
3. 可以使用 use-bp-configuration 来完成数据的查询和配置项的修改。
4. 为了方便管理，要创建自己配置项的专属目录来编写代码。参考 ticket 的代码。
5. 为了减少 index 打包体积，多语言需要在组件中完成，可以在自己的目录下创建 i18n.ts 存储多语言信息。

样例代码

<script setup lang="ts">
import { i18nUtils } from '@/config/i18n';
import BpConfigurationContainer from '../BpConfigurationContainer.vue';
import BpConfigurationItem from '../BpConfigurationItem.vue';
import { useBpConfiguration } from '../use-bp-configuration';
import { i18nData } from './i18n';
import type { ExampleConfigurationForm } from './types';

// 工单配置页面
defineOptions({
  name: 'ExampleConfiguration',
});

// 多语言存储 key
const { localeKey } = i18nUtils();

const { formData, loading, updateConfigHandler, updateConfigDebounceHandler } =
  useBpConfiguration<ExampleConfigurationForm>('settingExampleConfiguration');

// 多语言配置，这里写在 vue 文件中，可以缩小 index.js 体积
const cfgI18n = computed(() => i18nData[localeKey.value]);
</script>

<template>
  <bp-configuration-container :title="$t('menu.settingExampleConfiguration')" :loading="loading">
    <!-- 工单查询最值 -->
    <bp-configuration-item :label="cfgI18n.exampleQueryMax.label" :describe="cfgI18n.exampleQueryMax.desc">
      <el-input-number
        v-model="formData.exampleQueryMax"
        :min="1"
        :max="3600"
        :step-strictly="true"
        :value-on-clear="90"
        @change="updateConfigDebounceHandler('exampleQueryMax', $event)"
      />
    </bp-configuration-item>
    <!-- 获取形式 -->
    <bp-configuration-item :label="cfgI18n.exampleFetchType.label" :describe="cfgI18n.exampleFetchType.desc">
      <el-select @change="updateConfigHandler('exampleFetchType', $event)" v-model="formData.exampleFetchType">
        <el-option
          v-for="option in cfgI18n.exampleFetchType.options"
          :key="option.id"
          :label="option.label"
          :value="option.id"
        />
      </el-select>
    </bp-configuration-item>
  </bp-configuration-container>
</template>

国际化

需要在对应的配置目录下创建 i18n.ts 来存储自己配置项的国际化信息。例如：

import type { BpConfigurationI18nData } from '../types';

export const i18nData: BpConfigurationI18nData = {
  zhCN: {
    exampleFetchType: {
      label: '',
      desc: '',
      options: [
        {
          id: 0,
          label: '',
        },
      ],
    },
  },
  en: {
    exampleFetchType: {
      label: '',
      desc: '',
      options: [
        {
          id: 0,
          label: '',
        },
      ],
    },
  },
};

可以使用 i18nUtils 来获取当前语言的 key。代码如下：

// 多语言存储 key
const { localeKey } = i18nUtils();

数据类型 BpConfigurationI18nData

配置项多语言数据

属性	类型	说明
zhCN	Record<string, BpConfigurationItemI18nData>	中文
en	Record<string, BpConfigurationItemI18nData>	英文

数据类型 BpConfigurationItemI18nData

配置项选项多语言数据

属性	类型	说明
label	string	显示名
desc	string	描述
options	BpConfigurationOptionI18nData[]	数据可选值多语言数据

数据类型 BpConfigurationOptionI18nData

配置项选项可选值多语言数据

属性	类型	说明
id	number | string	选项枚举值
label	string	选项显示名

API

useBpConfiguration 方法

方法名	返回值	说明
updateConfigHandler	Promise<void>	修改配置项
updateConfigDebounceHandler	Promise<void>	修改配置项的防抖函数，这个在数字框时比较有用

BpConfigurationContainer 属性

属性	类型	默认值	说明
title	string	-	卡片标题
loading	Boolean	-	加载状态

BpConfigurationContainer 插槽

插槽名	类型	说明
default	BpConfigurationItemInstance	默认插槽，使用配置项组件

BpConfigurationItem 属性

属性	类型	默认值	说明
label	string	-	配置项标签名
describe	string	-	配置项描述信息

BpConfigurationItem 插槽

插槽名	类型	说明
default	-	配置项值组件，可以使用表单组件
label	-	配置项标签名
describe	-	配置项描述信息