动态字典

Shoulder 提供了一套开箱即用的字典管理能力,极大的降低了字典模块的编码成本。如:

  • 枚举 ←→ String/Number 自动转换

  • 可定制的存储模式,并提供多种默认的存储模式实现:

    • 适用于集群部署模式的DB模式

    • 适用于高并发场景的缓存查询能力

    • 适用于单机部署的无DB模式

  • 结合 Shoulder-Web 获得更丰富的功能:

    • 支持 JSR 303 规范的校验注解

    • 开箱即用的字典搜索、管理接口

    • 可视化的查询页面

核心接口

  • 字典类型(配置类型):DictionaryType

  • 字典项(配置项)DictionaryItem

如果是变化较少的场景,可采用以枚举代码为存储,枚举直接继承 DictionaryItemEnum 便能获得大量通用方便的类型转换工具代码(id → Enum、name → Enum、enum.order → Enum、compareWithXXX…​)。

静态字典-枚举模式

轻松实现枚举 & 字典转换,无需再为编写大量转换代码而担忧,保留代码原本的高可读性。

如对以下枚举可以直接在 Controller 的参数中接收多种格式

字典枚举示例
import org.shoulder.core.dictionary.model.NameAsIdDictionaryItemEnum;

public enum MyColorEnum implements NameAsIdDictionaryItemEnum<DictionaryTestEnum> {

    BLUE, YELLOW, GREEN, RED, BLACK, PINK, GOLDEN,
    ;
    @Override
    public String getName() {
        return name();
    }
    @Override
    public Integer getDisplayOrder() {
        return ordinal();
    }
}

这两种访问都能正确访问到接口

  • /color/updateFavorite?color=BLUE

  • /color/updateFavorite?color=0

初尝甜点
@RestController
public class MyColorController {

    @RequestMapping("/color/updateFavorite")
    public String updateFavorite(MyColorEnum color) {
        // /color/updateFavorite?color=BLUE
        // /color/updateFavorite?color=0
        return color.name();
    }
}
更多能力-校验
     /**
     * 接口中不使用枚举,使用DTO
     * 还支持设置 allowCodes、forbiddenCodes 来实现更有意思的设计,如 GOLDEN 只能由系统发放,而不能由用户设置。
     */
     @RequestMapping("/color/updateFavorite2")
     public String updateFavorite2(@DictionaryEnumItem(value=MyColorEnum.class, forbiddenCodes={"GOLDEN"}) DictionaryItemDTO colorDto) {
         return color.name();
     }
 }

更棒的 WEB 内置能力

若您引入了 shoulder-web,还可以获得开箱即用的字典查询 & 搜索接口,设置以下配置即可启用:

字典模块-web扩展启用
shoulder:
  web:
    ext:
      dictionary:
        enable: true

配置完成后,可直接访问 /ui/dictionary/page.html 打开内置的简易 UI 页面,查看应用所有的字典。

除此之外,您还可以直接使用以下接口查询您应用的字典项:

  • /api/v1/dictionary/type/all

  • /api/v1/dictionary/type/page

  • /api/v1/dictionary/type/listAll?limit=20

  • /api/v1/dictionary/item/listAll?limit=50

这里仅列举了几个简单的接口,更多详细接口介绍可启动 demo 后查看 swagger 接口文档。也可以直接搜索 Shoulder 源码类 DictionaryEnumControllerDictionaryItemEnumController 查看。

动态字典-数据库模式

Shoulder 字典模块不仅支持枚举,还支持通过数据库存储字典项,以实现动态字典能力。