# FlexSQL-Example

**Repository Path**: iJovi/flexsql-example

## Basic Information

- **Project Name**: FlexSQL-Example
- **Description**: FlexSQL使用案例
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2023-10-27
- **Last Updated**: 2026-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FlexSQL-Example

#### 介绍
这是一个示例项目，用来演示 **FlexSQL** ORM框架的各种功能特性。

###### FlexSQL ORM框架项目
- Gitee: [https://gitee.com/iJovi/FlexSQL](https://gitee.com/iJovi/vonce-sqlbean "FlexSQL")
- GitHub: [https://github.com/Jovilam77/vonce-sqlbean](https://github.com/Jovilam77/vonce-sqlbean "FlexSQL")

#### 技术栈
- **Java**: 21
- **Spring Boot**: 3.2.x
- **FlexSQL**: 最新版本
- **SQLite**: 默认嵌入式数据库（便于快速运行）
- **MyBatis**: SQL执行引擎

#### 快速开始

##### 1. 环境要求
- JDK 21+
- Maven 3.8+

##### 2. 运行项目
```bash
# 进入项目目录
cd sqlbean-example

# 编译项目
mvn clean compile

# 运行项目
mvn spring-boot:run
```

##### 3. 访问服务
服务启动后，默认端口为 `8080`，可以通过以下方式访问：
- API基础路径: `http://localhost:8080/`

#### 项目结构

```
sqlbean-example/
├── src/main/java/cn/vonce/sqlbean/example/
│   ├── ExampleApplication.java    # 启动类
│   ├── common/                    # 通用组件
│   │   └── Result.java            # 统一响应结果
│   ├── controller/                # REST控制器
│   │   ├── DbManageController.java  # 数据库管理
│   │   ├── DeleteController.java    # 删除操作
│   │   ├── InsertController.java    # 插入操作
│   │   ├── SelectController.java    # 查询操作
│   │   └── UpdateController.java    # 更新操作
│   ├── enums/                     # 枚举类
│   │   └── UserStatus.java         # 用户状态枚举
│   ├── model/                     # 数据模型
│   │   ├── BaseEntity.java         # 基础实体类
│   │   ├── entity/                 # 实体类
│   │   │   ├── Essay.java          # 文章实体
│   │   │   └── User.java           # 用户实体
│   │   └── vo/                     # 视图对象
│   │       ├── EssayUserVO.java
│   │       ├── EssayUserVO2.java
│   │       ├── EssayVO.java
│   │       ├── EssayVO2.java
│   │       └── UserVO.java
│   └── service/                    # 业务层
│       ├── EssayService.java
│       ├── UserService.java
│       └── impl/
│           ├── EssayServiceImpl.java
│           └── UserServiceImpl.java
├── src/main/resources/
│   ├── application.yml             # 主配置文件
│   ├── application-sqlite.yml      # SQLite配置
│   └── static/test.db              # SQLite数据库文件
└── pom.xml                         # Maven配置
```

#### FlexSQL核心功能示例

##### 1. 注解使用

| 注解 | 说明 | 示例 |
| :--- | :--- | :--- |
| `@SqlTable` | 标识数据库表 | `@SqlTable(value = "t_user", autoAlter = true)` |
| `@SqlId` | 标识主键 | `@SqlId(type = IdType.SNOWFLAKE_ID_16)` |
| `@SqlColumn` | 标识字段映射 | `@SqlColumn(notNull = true, remarks = "用户名")` |
| `@SqlVersion` | 标识乐观锁 | `@SqlVersion private Long version` |
| `@SqlLogically` | 标识逻辑删除 | `@SqlLogically private Boolean deleted` |
| `@SqlJSON` | 标识JSON字段 | `@SqlJSON private Map<String, Object> metadata` |
| `@SqlDefaultValue` | 标识默认值填充 | `@SqlDefaultValue(with = FillWith.INSERT)` |
| `@SqlJoin` | 标识表连接 | `@SqlJoin(mainKeyword = Essay$.userId, isBean = true)` |

##### 2. 查询操作（Select）

支持的查询特性：
- **基础查询**: 根据ID、条件查询
- **联表查询**: INNER JOIN、LEFT JOIN、RIGHT JOIN、FULL JOIN
- **子查询**: IN、NOT IN子查询
- **聚合函数**: COUNT、SUM、AVG、MAX、MIN
- **分组排序**: GROUP BY、HAVING、ORDER BY
- **模糊查询**: LIKE、NOT LIKE
- **范围查询**: BETWEEN、IN
- **空值判断**: IS NULL、IS NOT NULL
- **分页查询**: 支持多种分页方式

**接口示例**:
- `GET /getById?id=1` - 根据ID查询
- `GET /getAll` - 查询全部
- `GET /getByAgeAndGender?beginAge=18&endAge=30&gender=1` - 条件查询
- `GET /page1?pageNum=1&pageSize=10` - 分页查询
- `GET /selectWithInSubquery` - IN子查询
- `GET /selectWithGroupByHaving` - GROUP BY + HAVING

##### 3. 插入操作（Insert）

支持的插入特性：
- **单条插入**: 直接插入实体对象
- **批量插入**: 批量插入多个实体
- **自定义字段**: 只插入指定字段
- **字段过滤**: 排除指定字段
- **ID生成**: 支持UUID、雪花ID等
- **JSON字段**: 自动序列化JSON数据

**接口示例**:
- `POST /insert` - 单条插入
- `POST /batchInsert` - 批量插入
- `POST /insertWithJson` - 插入带JSON字段的数据
- `POST /insertWithFilter` - 插入时过滤字段

##### 4. 更新操作（Update）

支持的更新特性：
- **根据ID更新**: 通过ID更新记录
- **条件更新**: 根据条件更新
- **乐观锁更新**: 带版本号检查
- **字段自增/自减**: `age = age + 1`
- **字段过滤**: 排除敏感字段
- **仅更新非空字段**: 只更新非null字段

**接口示例**:
- `PUT /updateById/{id}` - 根据ID更新
- `PUT /updateWithLock/{id}` - 乐观锁更新
- `PUT /updateAdd/{id}` - 字段自增
- `PUT /updateNotNull/{id}` - 仅更新非空字段

##### 5. 删除操作（Delete）

支持的删除特性：
- **物理删除**: 真正删除数据
- **逻辑删除**: 设置删除标记，不真正删除
- **条件删除**: 根据条件删除
- **批量删除**: 批量删除多条记录

**接口示例**:
- `DELETE /deleteById/{id}` - 物理删除
- `DELETE /logicallyDelete/{id}` - 逻辑删除
- `DELETE /logicallyDeleteByIds?ids=1,2,3` - 批量逻辑删除

##### 6. 数据库管理（DbManage）

支持的管理功能：
- **表结构操作**: 创建表、删除表、修改表结构
- **数据备份**: 备份表数据到新表
- **数据复制**: 复制数据到其他表
- **Schema管理**: 创建、删除Schema
- **表信息查询**: 查询表列表、字段信息

**接口示例**:
- `POST /createTable` - 创建表
- `POST /backup` - 备份表数据
- `POST /copy?newName=new_table` - 复制数据
- `GET /getTableList` - 查询表列表
- `GET /getColumnInfoList` - 查询字段信息

##### 7. 事务管理

使用 `@DbTransactional` 注解管理事务：

```java
@DbTransactional
public void batchSaveWithTransaction(List<User> users) {
    for (User user : users) {
        insert(user);
    }
}

@DbTransactional(timeout = 30)
public void batchSaveWithTimeout(List<User> users) {
    // 事务超时时间为30秒
}

@DbTransactional(readOnly = true)
public int countByStatus(UserStatus status) {
    // 只读事务，适用于查询
}
```

#### 枚举类型支持

实体类中可以直接使用枚举类型，只需实现 `SqlEnum` 接口：

```java
public enum UserStatus implements SqlEnum<Integer> {
    DISABLE(0, "禁用"),
    NORMAL(1, "正常");
    
    private Integer code;
    private String desc;
    
    @Override
    public Integer getCode() {
        return this.code;
    }
    
    @Override
    public String getDesc() {
        return this.desc;
    }
}
```

#### 自动生成的常量类

编译项目后，FlexSQL会自动为每个实体类生成对应的常量类（命名规则：`实体类名$`）：

```java
public class User$ {
    public static final String _tableName = "t_user";
    public static final Column id$ = new Column(true, "user", "id", "", "唯一标识");
    public static final Column userName$ = new Column(true, "user", "user_name", "", "用户名");
    // ... 其他字段常量
}
```

使用示例：
```java
Select select = new Select();
select.column(User$.userName$, User$.age$);
select.where().eq(User$.id$, 1L);
```

#### 多数据库支持

FlexSQL支持多种数据库类型，只需修改配置文件即可切换：

| 数据库 | 配置文件 |
| :--- | :--- |
| SQLite | `application-sqlite.yml` |
| MySQL | `application-mysql.yml` |
| PostgreSQL | `application-postgre.yml` |
| Oracle | `application-oracle.yml` |
| SQL Server | `application-sqlserver.yml` |
| H2 | `application-h2.yml` |
| DB2 | `application-db2.yml` |
| Derby | `application-derby.yml` |
| HSQL | `application-hsql.yml` |

#### 核心设计理念

1. **零SQL**: 通过API构建SQL，无需手写SQL语句
2. **类型安全**: 使用方法引用和常量类，编译时检查
3. **自动映射**: 实体类与数据库表自动映射
4. **智能生成**: 自动生成字段常量类
5. **多数据源**: 支持多数据源配置
6. **事务管理**: 声明式事务支持

#### 许可证

MIT License