# 通用字典翻译组件

**Repository Path**: xrRw/dictionary

## Basic Information

- **Project Name**: 通用字典翻译组件
- **Description**: 通用字典翻译组件后端服务（dictionary-backend）是一个高效的字典数据管理与翻译平台，提供统一的字典数据管理、多层级缓存策略、AOP自动翻译等核心功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-11
- **Last Updated**: 2026-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 通用字典翻译组件 - 技术文档

## 1. 项目概述

### 1.1 项目简介

通用字典翻译组件后端服务（dictionary-backend）是一个高效的字典数据管理与翻译平台，提供统一的字典数据管理、多层级缓存策略、AOP自动翻译等核心功能。

### 1.2 技术栈

| 技术         | 版本  | 说明                   |
| ------------ | ----- | ---------------------- |
| Spring Boot  | 3.2.5 | 核心框架               |
| MyBatis-Plus | 3.5.7 | ORM框架                |
| Redis        | -     | 分布式缓存（二级缓存） |
| Caffeine     | -     | 本地缓存（一级缓存）   |
| MySQL        | 8.0+  | 关系型数据库           |
| Java         | 17+   | 编程语言               |

### 1.3 项目结构

```
dictionary-backend/
├── pom.xml                          # Maven配置
├── src/main/
│   ├── java/com/example/dictionary/
│   │   ├── DictionaryApplication.java    # 应用入口
│   │   ├── annotation/                   # 注解定义
│   │   │   ├── DictField.java            # 字典字段注解
│   │   │   └── DictTranslate.java        # 翻译触发注解
│   │   ├── config/                       # 配置类
│   │   │   ├── RedisConfig.java
│   │   │   ├── WebConfig.java
│   │   │   └── MyMetaObjectHandler.java
│   │   ├── controller/                    # 控制器层
│   │   │   ├── DictTranslateController.java  # 翻译API
│   │   │   ├── DictTypeController.java        # 字典类型API
│   │   │   └── DictItemController.java        # 字典项API
│   │   ├── entity/                        # 实体类
│   │   │   ├── SysDictType.java
│   │   │   └── SysDictItem.java
│   │   ├── service/                       # 业务逻辑层
│   │   │   ├── DictCacheService.java      # 缓存服务
│   │   │   ├── DictTypeService.java
│   │   │   └── DictItemService.java
│   │   ├── provider/                      # 数据源提供者
│   │   │   ├── DictProvider.java          # 提供者接口
│   │   │   ├── DictProviderManager.java   # 提供者管理器
│   │   │   ├── DbDictProvider.java        # 数据库提供者
│   │   │   ├── EnumDictProvider.java      # 枚举提供者
│   │   │   └── RemoteDictProvider.java     # 远程HTTP提供者
│   │   ├── translate/                     # 翻译处理
│   │   │   ├── DictTranslateAspect.java    # AOP切面
│   │   │   └── DictFieldSerializer.java
│   │   ├── enums/                         # 枚举定义
│   │   │   ├── DictEnum.java              # 字典枚举接口
│   │   │   └── BooleanEnum.java
│   │   ├── repository/                    # 数据访问层
│   │   ├── vo/                            # 视图对象
│   │   └── DictionaryApplication.java
│   └── resources/
│       ├── application.yml                # 应用配置
│       └── schema.sql                     # 数据库初始化脚本
└── src/test/                              # 测试目录
```

---

## 2. 数据库设计

### 2.1 字典类型表 (sys_dict_type)

```sql
CREATE TABLE sys_dict_type (
    id          BIGINT AUTO_INCREMENT PRIMARY KEY,
    code        VARCHAR(100) NOT NULL COMMENT '字典类型编码',
    name        VARCHAR(200) NOT NULL COMMENT '字典类型名称',
    status      TINYINT DEFAULT 1 COMMENT '状态（0停用/1启用）',
    remark      VARCHAR(500) COMMENT '备注',
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_code (code)
);
```

### 2.2 字典项表 (sys_dict_item)

```sql
CREATE TABLE sys_dict_item (
    id           BIGINT AUTO_INCREMENT PRIMARY KEY,
    dict_type_id BIGINT NOT NULL COMMENT '字典类型ID',
    parent_id    BIGINT DEFAULT 0 COMMENT '父节点ID（0=顶级节点）',
    item_value   VARCHAR(200) NOT NULL COMMENT '字典值',
    item_label   VARCHAR(200) NOT NULL COMMENT '字典标签',
    sort_order   INT DEFAULT 0 COMMENT '排序号',
    status       TINYINT DEFAULT 1 COMMENT '状态（0停用/1启用）',
    ext_data     JSON COMMENT '扩展数据',
    create_time  DATETIME DEFAULT CURRENT_TIMESTAMP,
    update_time  DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    KEY idx_dict_type_id (dict_type_id),
    KEY idx_parent_id (parent_id)
);
```

### 2.3 内置字典类型

| 编码         | 名称     | 类型 | 说明         |
| ------------ | -------- | ---- | ------------ |
| gender       | 性别     | 扁平 | 男/女/未知   |
| status       | 状态     | 扁平 | 启用/停用    |
| region       | 地区     | 树形 | 三级地区数据 |
| organization | 组织架构 | 树形 | 四级组织结构 |
| menu         | 菜单类型 | 树形 | 带扩展配置   |

---

## 3. API 接口文档

### 3.1 字典翻译接口

#### 3.1.1 单值翻译

```
GET /api/dict/translate/{dictTypeCode}/{value}
```

**参数：**

- `dictTypeCode` - 字典类型编码
- `value` - 字典值

**响应示例：**

```json
{
  "code": 200,
  "data": "男",
  "message": "success"
}
```

#### 3.1.2 批量翻译

```
POST /api/dict/translate/batch
```

**请求体：**

```json
{
  "dictTypeCode": "gender",
  "values": ["1", "2", "0"]
}
```

**响应示例：**

```json
{
  "code": 200,
  "data": {
    "1": "男",
    "2": "女",
    "0": "未知"
  }
}
```

#### 3.1.3 刷新指定字典缓存

```
POST /api/dict/cache/refresh/{dictTypeCode}
```

#### 3.1.4 刷新全部缓存

```
POST /api/dict/cache/refresh-all
```

#### 3.1.5 清除指定缓存

```
DELETE /api/dict/cache/{dictTypeCode}
```

---

### 3.2 字典类型管理接口

#### 3.2.1 分页查询

```
GET /api/dict/types?keyword=&page=0&size=10
```

#### 3.2.2 获取全部

```
GET /api/dict/types/list
```

#### 3.2.3 按ID查询

```
GET /api/dict/types/{id}
```

#### 3.2.4 新增字典类型

```
POST /api/dict/types
Content-Type: application/json

{
  "code": "custom_type",
  "name": "自定义类型",
  "status": 1,
  "remark": "备注信息"
}
```

#### 3.2.5 更新字典类型

```
PUT /api/dict/types/{id}
Content-Type: application/json

{
  "name": "更新后的名称",
  "status": 1,
  "remark": "更新后的备注"
}
```

#### 3.2.6 删除字典类型

```
DELETE /api/dict/types/{id}
```

---

### 3.3 字典项管理接口

#### 3.3.1 获取字典项列表（扁平）

```
GET /api/dict/items/{dictTypeCode}
```

#### 3.3.2 获取字典项树形结构

```
GET /api/dict/items/{dictTypeCode}/tree
```

**响应示例：**

```json
{
  "code": 200,
  "data": [
    {
      "id": 6,
      "dictTypeId": 3,
      "parentId": 0,
      "itemValue": "110000",
      "itemLabel": "北京市",
      "sortOrder": 1,
      "status": 1,
      "children": [
        {
          "id": 7,
          "parentId": 6,
          "itemValue": "110100",
          "itemLabel": "北京市辖区",
          "children": [
            {
              "id": 8,
              "parentId": 7,
              "itemValue": "110101",
              "itemLabel": "东城区"
            }
          ]
        }
      ]
    }
  ]
}
```

#### 3.3.3 新增字典项

```
POST /api/dict/items
Content-Type: application/json

{
  "dictTypeId": 1,
  "parentId": 0,
  "itemValue": "3",
  "itemLabel": "其他",
  "sortOrder": 4,
  "status": 1,
  "extData": "{}"
}
```

#### 3.3.4 更新字典项

```
PUT /api/dict/items/{id}
```

#### 3.3.5 删除字典项

```
DELETE /api/dict/items/{id}
```

---

## 4. 核心功能说明

### 4.1 两级缓存机制

系统采用 **Caffeine（本地缓存）+ Redis（分布式缓存）** 两级缓存架构：

```
请求 → Caffeine（一级缓存）→ Redis（二级缓存）→ Provider（数据源）
```

**缓存配置：**

```yaml
dict:
  cache:
    caffeine:
      expire-seconds: 300    # 本地缓存5分钟过期
      maximum-size: 1000     # 最大1000条
    redis:
      expire-seconds: 1800   # Redis缓存30分钟过期
      key-prefix: "dict:"    # 缓存键前缀
```

**缓存策略：**

1. 查询时优先从 Caffeine 获取
2. 未命中则查询 Redis
3. Redis 也未命中则从数据源加载
4. 数据回填两级缓存

---

### 4.2 AOP 自动翻译

系统提供基于注解的自动翻译功能，只需两步即可实现：

#### 步骤1：在实体字段添加 @DictField 注解

```java
public class UserVO {
    @DictField(dictType = "gender")
    private String gender;      // 存储值
    
    private String genderLabel; // 自动翻译结果
}
```

#### 步骤2：在 Controller 方法添加 @DictTranslate 注解

```java
@RestController
public class UserController {
    
    @DictTranslate  // 添加此注解
    @GetMapping("/user/{id}")
    public Result<UserVO> getUser(@PathVariable Long id) {
        // 返回时自动翻译 gender → genderLabel
    }
}
```

**@DictField 注解属性：**

| 属性     | 类型   | 默认值       | 说明                   |
| -------- | ------ | ------------ | ---------------------- |
| dictType | String | -            | 字典类型编码（必填）   |
| ref      | String | 字段名+Label | 翻译结果写入的目标字段 |

---

### 4.3 多数据源提供者

系统支持多种字典数据来源，通过 `DictProviderManager` 统一管理：

#### 4.3.1 数据库提供者 (DbDictProvider)

从 `sys_dict_type` 和 `sys_dict_item` 表加载数据，**优先级最高（order=0）**。

#### 4.3.2 枚举提供者 (EnumDictProvider)

自动扫描实现 `DictEnum` 接口的枚举类。**优先级次之（order=10）**。

**使用示例：**

```java
public enum GenderEnum implements DictEnum {
    MALE("gender", "1", "男"),
    FEMALE("gender", "2", "女"),
    UNKNOWN("gender", "0", "未知");
    
    private final String code;
    private final String value;
    private final String label;
    
    @Override
    public String getCode() { return code; }
    @Override
    public String getValue() { return value; }
    @Override
    public String getLabel() { return label; }
}
```

#### 4.3.3 远程HTTP提供者 (RemoteDictProvider)

通过 HTTP 请求从远程服务获取字典数据。**优先级最低（order=100）**。

**配置示例：**

```yaml
dict:
  remote:
    enabled: true
    url: "http://remote-server/api/dict"
    timeout: 5000
```

---

## 5. 配置说明

### 5.1 应用配置 (application.yml)

```yaml
server:
  port: 8080

spring:
  application:
    name: dictionary-backend

  datasource:
    url: jdbc:mysql://localhost:3306/dict_db
    username: root
    password: root

  data:
    redis:
      host: localhost
      port: 6379
      database: 0

dict:
  cache:
    caffeine:
      expire-seconds: 300
      maximum-size: 1000
    redis:
      expire-seconds: 1800
      key-prefix: "dict:"
  remote:
    enabled: false
    url: ""
    timeout: 5000
```

### 5.2 配置参数说明

| 参数                                 | 默认值  | 说明                       |
| ------------------------------------ | ------- | -------------------------- |
| `dict.cache.caffeine.expire-seconds` | 300     | Caffeine缓存过期时间（秒） |
| `dict.cache.caffeine.maximum-size`   | 1000    | Caffeine最大缓存条目数     |
| `dict.cache.redis.expire-seconds`    | 1800    | Redis缓存过期时间（秒）    |
| `dict.cache.redis.key-prefix`        | `dict:` | Redis缓存键前缀            |
| `dict.remote.enabled`                | false   | 是否启用远程字典           |
| `dict.remote.url`                    | -       | 远程字典服务地址           |
| `dict.remote.timeout`                | 5000    | HTTP请求超时（毫秒）       |

---

## 6. 使用示例

### 6.1 前后端集成示例

**前端请求：**

```javascript
// 获取用户列表（已包含翻译）
axios.get('/api/user/list').then(res => {
  console.log(res.data); // [{id: 1, gender: "1", genderLabel: "男"}, ...]
});
```

**后端实现：**

```java
// 1. 创建 VO
public class UserVO {
    private Long id;
    
    @DictField(dictType = "gender")
    private String gender;
    
    private String genderLabel;
}

// 2. Controller
@RestController
public class UserController {
    
    @DictTranslate  // 关键注解
    @GetMapping("/api/user/list")
    public Result<List<UserVO>> list() {
        return Result.ok(userService.list());
    }
}
```

### 6.2 批量翻译场景

```javascript
// 前端批量翻译
axios.post('/api/dict/translate/batch', {
  dictTypeCode: 'status',
  values: ['0', '1', '2']
}).then(res => {
  console.log(res.data); // {"0": "停用", "1": "启用", "2": "处理中"}
});
```

---

## 7. 数据库初始化

系统启动时会自动执行 `schema.sql` 脚本，创建以下内容：

1. **表结构**：`sys_dict_type`、`sys_dict_item`
2. **初始数据**：
   - 5种字典类型（性别、状态、地区、组织架构、菜单类型）
   - 70+条字典项示例数据

---

## 8. 版本信息

- **项目版本**：1.0.0-SNAPSHOT
- **Java版本**：17+
- **Spring Boot版本**：3.2.5

---

## 9. 联系方式

如有问题，请联系项目维护者。