# jackson-datatype-dict

**Repository Path**: MengGod/jackson-datatype-dict

## Basic Information

- **Project Name**: jackson-datatype-dict
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Jackson Datatype: Dict

一个 Jackson 扩展模块，为 JSON 序列化提供**字典字段翻译**能力。

## 功能

在 POJO 的字段上标注 `@Dict(dictType = "...")`，序列化时自动追加一个 `{fieldName}Desc` 虚拟字段，显示该字典编码对应的中文含义（或任意显示文本）。

```java
// 原始 POJO
@Dict(dictType = "gender")
private String gender;   // 值为 "M"

// 序列化输出
{ "gender": "M", "genderDesc": "男" }
```

## 适用场景

- **后端接口**：数据库只存编码（如 `"M"`、`"dev"`、`"active"`），但前端需要显示中文含义（"男"、"研发部"、"在职"）
- **多端统一**：翻译逻辑集中在序列化层，无需每个前端各自维护字典表
- **零侵入**：只用注解声明字典类型，不改变业务 POJO 结构

## 快速开始

### 1. 注册 Module

```java
ObjectMapper mapper = new ObjectMapper()
    .registerModule(new DictSerializerModule(yourDictProvider));
```

### 2. 标注字典字段

```java
public class Employee {
    private String name;

    @Dict(dictType = "gender")
    private String gender;       // "M" / "F" / "U"

    @Dict(dictType = "department")
    private String department;   // "dev" / "qa" / "hr"

    @Dict(dictType = "emp_status")
    private String status;       // "active" / "inactive" / "suspended"

    // getters & setters ...
}
```

### 3. 序列化（自动翻译）

```java
Employee emp = new Employee("张三", "M", "dev", "active", ...);
String json = mapper.writeValueAsString(emp);
```

输出：

```json
{
  "name" : "张三",
  "gender" : "M",
  "genderDesc" : "男",
  "department" : "dev",
  "departmentDesc" : "研发部",
  "status" : "active",
  "statusDesc" : "在职",
  ...
}
```

## 模块结构

```
com.fasterxml.jackson.datatype.dict
├── Dict.java                   ← @Dict 注解
├── DictProvider.java           ← 字典查询接口（函数式接口）
├── DictSerializerModule.java   ← Jackson Module 入口
├── DictBeanSerializerModifier.java
├── DictFieldSerializer.java    ← 增强序列化器
├── DictFieldMeta.java          ← 虚拟字段元信息
└── provider/
    ├── DictLoader.java              ← 字典数据加载接口
    ├── CachingDictProvider.java     ← ⭐ Guava Cache 实现（推荐生产使用）
    └── SimpleDictProvider.java      ← 内存 HashMap 实现（演示/测试用）
```

## 字典提供者

### SimpleDictProvider（演示/测试）

基于内存 `HashMap`，内置示例字典数据，开箱即用：

```java
DictProvider provider = new SimpleDictProvider();
```

### CachingDictProvider（推荐生产使用 ⭐）

基于 **Google Guava Cache**，支持自动过期、容量控制、并发安全：

```java
// 对接数据库的 DictLoader
DictLoader loader = dictType -> dictRepository.findByType(dictType);

// 缓存 30 分钟，最多 100 种字典类型
DictProvider provider = new CachingDictProvider(loader, 30, TimeUnit.MINUTES, 100);

ObjectMapper mapper = new ObjectMapper()
    .registerModule(new DictSerializerModule(provider));
```

**优势：**
| 特性 | SimpleDictProvider | CachingDictProvider |
|---|---|---|
| 数据源 | 仅内存硬编码 | 通过 `DictLoader` 对接任意后端 |
| 过期机制 | ❌ 无 | ✅ TTL 过期 + 手动刷新 |
| 容量控制 | ❌ 无 | ✅ 最大条目数，LRU 淘汰 |
| 并发安全 | ❌ 手动 ConcurrentHashMap | ✅ Guava LoadingCache 内置 |
| 适用场景 | 演示 / 测试 | 生产环境 |

## 运行 Demo

```bash
# 编译
mvn compile

# 运行
mvn exec:java -Dexec.mainClass="com.fasterxml.jackson.datatype.VirtualDictDemo"
```

Demo 演示了：
1. POJO → JSON 序列化
2. JSON → POJO 反序列化
3. Tree Model (JsonNode) 解析
4. 程序化构建 JsonNode
5. **字典字段翻译（SimpleDictProvider）**
6. **字典字段翻译（CachingDictProvider + Guava Cache）**

## 依赖

- Jackson 2.17.x
- Google Guava 33.3.1-jre
- Java 8+

## 内置示例字典数据

| 字典类型 | 编码 | 含义 |
|---|---|---|
| `gender` | M / F / U | 男 / 女 / 未知 |
| `emp_status` | active / inactive / suspended | 在职 / 已离职 / 停职 |
| `department` | dev / qa / ops / hr / finance | 研发部 / 质量部 / 运维部 / 人力资源部 / 财务部 |
| `yes_no` | Y / N | 是 / 否 |