# easy-join

**Repository Path**: wrxfxdd/easy-join

## Basic Information

- **Project Name**: easy-join
- **Description**: `easy-join` 是一个基于Java注解的自动外键转换/翻译工具，它能够在JSON序列化过程中自动查询并填充关联表的字段值，极大简化了数据关联查询的开发工作。

关联：外键自动转换、关联表自动填充、JSON序列化增强、数据库关联查询优化、一对一关联转换、一对多关联转换、自动关联数据获取、注解式外键处理
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 0
- **Created**: 2025-10-11
- **Last Updated**: 2025-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# easy-join

## 项目介绍

easy-join 是一个基于注解的自动外键翻译工具：引入依赖，无需额外配置，只声明“要补哪些字段”，序列化输出时自动补齐，不改变现有实体结构。

## 项目优势

- **注解驱动、零侵入**：不改表结构/实体结构，不影响原有查询逻辑
- **批处理预取**：对列表/数组序列化自动汇总外键并批量查询，显著减少 N+1
- **一对一 / 一对多**：`@EasyJoinOne` / `@EasyJoinList`
- **按需字段**：`@SelectColumn` 精确选择字段与别名（支持下划线/驼峰写法）
- **瞬时缓存**：内置 Caffeine，全局 5 秒过期（默认开启，可关闭）

## 适用场景

- **列表/分页接口**：返回一批对象，需要补充关联字段（收益最大）
- **快速开发**：减少 DTO 拼装与手写 join 的成本
- **关系简单~中等复杂度**：外键字段明确、关联字段可控

## 如何使用

### 1. 引入依赖

在项目的 `pom.xml` 中添加依赖：

jdk 8版本
```xml
<dependency>
    <groupId>io.gitee.wrxfxdd</groupId>
    <artifactId>easy-join</artifactId>
    <version>1.0.1</version>
</dependency>
```

jdk 17版本
```xml
<dependency>
    <groupId>io.gitee.wrxfxdd</groupId>
    <artifactId>easy-join</artifactId>
    <version>17.0.1</version>
</dependency>
```

### 2. 直接使用

#### 一对一关联示例
##### 正常情况
```java
public class Order {
    private Long id;
    @EasyJoinOne(target = UserInfoDO.class)
    @SelectColumn(column = "name")
    @SelectColumn(column = "phone")
    private Long userId;
}
```
序列化后 JSON 示例：

```json
{
  "id": 1,
  "userId": 1001,
  "name": "张三",
  "phone": "13800138000"
}
```
##### 特殊情况：
1.userId 对应 UserInfoDO 的 其他字段比如就叫userId或者 userNo 就需要指定对应的字段
2.查询的字段名和当前实体类有重名，可以通过注解属性中as取别名
```java
public class Order {
    private Long id;
    @EasyJoinOne(target = UserInfoDO.class, joinColumn = "userNo")
    @SelectColumn(column = "name", as = "userName")
    @SelectColumn(column = "phone", as = "userPhone")
    private Long userId;
}
```
序列化后 JSON 示例：
```json
{
  "id": 1,
  "userId": 1001,
  "userName": "张三",
  "userPhone": "13800138000"
}
```

#### 一对多关联示例
##### 正常情况
```java
public class User {
    private Long id;
    @EasyJoinList(target = UserInfoDO.class) 
    @SelectColumn(column = "name")
    @SelectColumn(column = "phone")
    private Long userId;
}
```
序列化后 JSON 示例：
```json
{
  "id": 1001,
  "userId": 1001,
  "userInfoDOList": [
    {
      "name": "张三",
      "phone": 21321312
    },
    {
      "name": "李四",
      "phone": 199924234
    }
  ]
}
```

##### 特殊情况
1.userId 对应 UserInfoDO 的 其他字段比如就叫userId或者 userNo 就需要指定对应的字段
2.查询的字段名想取别名 可以通过注解属性中as取别名
```java
public class User {
    private Long id;
    @EasyJoinList(target = UserInfoDO.class, joinColumn = "userNo")
    @SelectColumn(column = "name", as = "userName")
    @SelectColumn(column = "phone", as = "userPhone")
    private Long userId;
}
```
序列化后 JSON 示例：
```json
{
  "id": 1001,
  "userId": 1001,
  "userInfoDOList": [
    {
      "name": "张三",
      "phone": 21321312
    },
    {
      "name": "李四",
      "phone": 199924234
    }
  ]
}
```


## 注解说明

### @EasyJoinOne

用于一对一关联外键转换。

| 属性 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| target | Class | 否 | Void.class | 目标 DO/实体类（tableName 为空时用于推导表名） |
| tableName | String | 否 | "" | 关联表名（优先级高于 target） |
| joinColumn | String | 否 | "id" | 外键对应表的字段名（支持驼峰/下划线） |
| selectColumns | SelectColumn[] | 否 | {} | 兼容老写法（推荐改用字段上的重复 @SelectColumn） |
| cache | boolean | 否 | true | 是否启用缓存 |

### @EasyJoinList

用于一对多关联外键转换。

| 属性 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| target | Class | 否 | Void.class | 目标 DO/实体类（tableName 为空时用于推导表名） |
| tableName | String | 否 | "" | 关联表名（优先级高于 target） |
| joinColumn | String | 否 | "id" | 目标表中用于匹配外键值的字段（一般需要手动指定） |
| as | String | 否 | "" | 输出数组字段名；为空时默认生成：`xxxList` |
| selectColumns | SelectColumn[] | 否 | {} | 兼容老写法（推荐改用字段上的重复 @SelectColumn） |
| cache | boolean | 否 | true | 是否启用缓存 |

### @SelectColumn

指定要查询的字段及别名。

| 属性 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| column | String | 是 | - | 列名（支持下划线/驼峰；查询时会转为下划线） |
| as | String | 否 | "" | JSON 输出别名；不指定则：下划线列名转驼峰、驼峰列名保持不变 |

## 性能机制（已内置）

- **批处理预取**：集合/数组序列化时先预扫描元素，按 `tableName + joinColumn` 汇总外键值并批量查询，减少 N+1
- **瞬时缓存**：Caffeine 全局缓存，默认 `maximumSize=2000`、`expireAfterWrite=5s`，key 形如 `表名:外键字段:外键值`

## 注意事项

1. **触发时机**：主要在对象序列化输出时触发（例如接口返回 JSON）
2. **索引建议**：建议为 `joinColumn` 建索引；超大列表建议分页返回
3. **一对一多行**：若一对一查询返回多条记录，会默认取第一条并记录警告日志

## License

MIT License