基础框架文档中心

外观

用户设置 v1.8.3+ ​

用户在使用软件系统时，时常会按自己的需要更改一些设置，例如：系统主题、字体大小、表格显示列等。 为了满足用户的个性化设置需求，同时减少开发成本，框架提供了用户设置功能。

简介 ​

用户设置功能核心就是配置数据的保存和读取——保存用户提交的数据，然后在需要时读取。

在实际开发中，我们会将配置数据按照相关性合并归类，例如：基础信息、排版设置、数据设置等。 除了逻辑上更加清晰，在读取时也可以避免一次加载过多数据，减少无效内容。 框架使用“分类（Category）”标记一组相关的配置项。

配置数据存取基于强类型，即每一类配置必须定义对应的模型类，内部据此进行序列化和反序列化。 这样不仅可以避免保存恶意传入的非预期的配置项，也可以更方便地基于类属性访问配置项。

配置定义 ​

配置定义进行了简化。创建表示配置的模型类，然后使用@UserSettingData注解声明类别即可。 无需实现接口，也无需注册到服务容器。

示例如下：

java
@UserSettingData(categories = "locale", name = "用户语言设置")
public class UserCultureSetting
{
    @JsonProperty("lang")
    @NotBlank(message = "语言标识不能为空")
    private String language = "zh-CN";
    
    @JsonProperty("date")
    private string dateFormat = "Ymd";
}

上例定义了一个分类为“locale”的用户设置，可以接收两个配置项，language 为必填项，同时还提供了默认值。

提示

模型类可以正常使用验证注解，也可以根据需要设置配置项的默认值。

因为内部使用 fasterxml.jackson 序列化数据，因此可以使用相关注解控制序列化结果。

有时不同类别的配置会使用相同的数据结构，这时可以在注解中声明多个类别。

java
@UserSettingData(categories = {"page_10220341", "page_10220352"})
public class UserColumnSetting
{
    // 省略属性
}

更进一步地，如果这些类别命名相似，可以使用通配符*简化声明。

java
@UserSettingData(categories = "page_*")
public class UserColumnSetting
{
    // 省略属性
}

注意

使用通配符可以在未来新增相似分类时，自动适配而无需修改配置定义。 不过在获取配置时存在一些限制，请查看服务方法。

API ​

保存配置 ​

POST /api/user-settings/{category}

  • 说明：为当前登录用户保存配置，重复保存则覆盖。
  • 参数：
    • category {string} 类别，必须在后端注册。
    • body {string} 配置内容，必须为 JSON 字符串。
  • 返回：主键id
js
Post('/api/user-settings/locale', JSON.stringify({ lang: 'zh-Hans' });

获取配置 ​

GET /api/user-settings/{categories}

  • 说明：获取当前登录用户的指定配置。
  • 参数：
    • categories {string} 类别，多个以逗号分隔
  • 返回：配置数据，以 category 为对象键。
js
Get('/api/user-settings/locale,page1201');
// 返回结果
{
  "body": {
    "locale": {
      "lang": "zh-Hans"
    },
    "page1201": {
      "columns": [
        "name",
        "sex",
        "age"
      ],
      "cardStyle": false
    },
  },
  "code": 0,
  "msg": "操作成功"
}

服务方法 ​

用户设置服务提供了读取配置的方法，方便在后端使用。

获取用户配置 ​

<T> T get(String userId, Class<T> clazz)

  • 说明：获取配置。适用于配置类 T 仅对应一个类别的场景。如果对应多个类别，则结果无法保证与预期一致。
  • 参数：
    • userId {string} 用户编号
    • clazz {Class} 配置类类型
  • 返回：配置对象
java
@Autowired
private UserSettingService service;

UserCultureSetting setting = service.get("1046200001", UserCultureSetting.class);
System.out.println(setting.getLanguage());

获取用户配置 ​

<T> T get(String userId, String category, Class<T> clazz)

  • 说明：获取配置。适用于配置类 T 对应多个类别，或类别包含通配符的场景。
  • 参数：
    • userId {string} 用户编号
    • category {string} 类别
    • clazz {Class} 配置类类型
  • 返回：配置对象
java
UserColumnSetting setting = service.get("1046200001", "page1021", UserColumnSetting.class);
System.out.println(setting.getCardStyle());