# ameba-spring-boot-starter

**Repository Path**: ITEater/ameba-spring-boot-starter

## Basic Information

- **Project Name**: ameba-spring-boot-starter
- **Description**: spring-boot扩展工具项目，用于快速开发jpa相关、redis相关等组件
- **Primary Language**: Java
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2018-04-29
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ameba-spring-boot-starter 一个神奇的去SQL化的数据库隔离工具

[![Java版本](https://img.shields.io/badge/java-21%2B-red.svg?style=for-the-badge&logo=appveyor)](https://img.shields.io/badge/java-21%2B-red.svg?style=for-the-badge&logo=appveyor) [![Maven版本](https://img.shields.io/badge/maven-3.2.5%2B-red.svg?style=for-the-badge&logo=appveyor)](https://img.shields.io/badge/maven-3.2.5%2B-red.svg?style=for-the-badge&logo=appveyor) [![Spring Boot](https://img.shields.io/badge/spring%20boot-4.0.3%2B-red.svg?style=for-the-badge&logo=appveyor)](https://img.shields.io/badge/spring%20boot-4.0.3%2B-red.svg?style=for-the-badge&logo=appveyor)

## 当前版本

![版本](https://img.shields.io/badge/version-0.7.0-green.svg?style=for-the-badge&logo=appveyor)

## 项目简介

基于 Spring Boot 开发 JavaWeb 项目，最常用的功能无外乎一个写 Controller 的 Spring MVC 与数据库相关框架。本框架主要基于 Spring Data JPA、Spring Data Redis 和 Spring Web 三个模块进行了工具化封装，主要作用是**减少重复代码量，提高工作效率**，可以让开发者更多精力聚焦到业务中。

本项目目前支持 **Spring Boot 4.0.3+** 和 **Java 21+**，采用现代化的开发实践和 API 设计。

## 项目引入

```xml
<dependency>
    <groupId>top.codef</groupId>
    <artifactId>ameba-spring-boot-starter</artifactId>
    <version>0.7.0</version>
</dependency>
```

## 核心功能

### 1. JPA 数据访问工具

- **通用数据访问**：提供 `CommonDao` 类，支持基于 Criteria API 的动态查询
- **基础 CRUD**：提供 create、merge、delete、get、flush、refresh、lock 等操作
- **分页查询**：内置 `Pageable` 和 `Page` 模型，支持复杂条件的分页查询，自动计算总数和页数
- **动态条件构建**：通过 `CommonFilter` 和 `QueryBuilder` 构建复杂的查询条件
- **批量操作**：支持批量更新和删除操作（update、updateWithNull、delete）
- **HQL 支持**：提供 `getListByHql`、`getSingleByHql`、`updateByHql` 方法
- **关联查询**：支持通过 `@JoinColumn` 和 `@ManyToOne` 等注解进行多表关联查询
- **聚合函数**：支持 count、avg、max、min、sum 等聚合函数操作
- **动态插入/更新**：支持 `@DynamicInsert` 和 `@DynamicUpdate` 注解

### 2. Redis 操作模块

- **多种数据结构支持**：支持 Hash、List、Set、ZSet 和 Value 等 Redis 数据结构
- **键命名约定**：`CDao` 系列（键固定）和 `DDao` 系列（键不固定）
- **通用 Redis DAO**：提供抽象类和接口，简化 Redis 操作
- **批量操作**：支持批量获取和存储数据
- **过期时间设置**：支持为不同类型的 Redis 数据结构设置过期时间

### 3. Web 约定功能

- **全局异常处理**：`HaveReasonException` 返回 HTTP 417 状态码，其他异常返回 HTTP 418 状态码
- **Feign 客户端异常处理**：`FeignErrorDecoder` 实现微服务间异常透传
- **统一响应模型**：`StatusResultModel` 和 `ResponseStatusEnum` 提供统一响应格式
- **配置开关**：`ameba.enable-error-advice` 控制异常处理启用

## 快速开始

### 1. 创建 Entity

```java
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import lombok.Getter;
import lombok.Setter;

@Entity
@Getter
@Setter
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String phone;
    private String password;
    private String username;
}
```

### 2. 创建 DAO

```java
import org.springframework.stereotype.Repository;
import top.codef.dao.BaseDao;

@Repository
public class UserDao extends BaseDao {
}
```

### 3. 创建 Service

```java
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import top.codef.dao.UserDao;
import jakarta.transaction.Transactional;

@Service
@Transactional
public class UserService {
    @Autowired
    private UserDao userDao;

    public User create(User user) {
        userDao.create(user);
        return user;
    }

    public User get(Long id) {
        return userDao.get(User.class, id);
    }
}
```

### 4. 配置数据源

```yaml
spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/have_fun?useSSL=false&serverTimezone=GMT%2b8
    username: your username
    password: your pwd
    driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    database: mysql
    show-sql: true
    properties:
      hibernate:
        format_sql: true
        default_batch_fetch_size: 10
```

## 查询示例

### 基本查询

```java
// 创建查询条件
CommonFilter filter = QueryBuilder.createFilter()
    .eq("name", "test")
    .like("description", "%test%");

// 执行查询
List<User> users = commonDao.getList(User.class, filter);
User user = commonDao.getSingle(User.class, filter);
```

### 分页查询

```java
Pageable pageable = new Pageable();
pageable.setPageNo(1);
pageable.setEachPageSize(10);

CommonFilter filter = QueryBuilder.createFilter()
    .eq("status", 1)
    .orderByDesc("createTime");

Page<User> page = commonDao.getPage(User.class, pageable, filter);
Long totalCount = page.getPageable().getTotalCount();
```

### 更新和删除

```java
// 更新操作（忽略 null 值）
CommonFilter updateFilter = QueryBuilder.createFilter()
    .eq("id", 1L)
    .update("name", "new name")
    .update("status", 2);
int count = commonDao.update(User.class, updateFilter);

// 删除操作
CommonFilter deleteFilter = QueryBuilder.createFilter().eq("id", 1L);
int deleted = commonDao.delete(User.class, deleteFilter);
```

### 关联查询

```java
// 通过 User 中的 phone 查询 UserAuth 中的 authName
List<String> authNames = commonDao.getList(String.class, UserAuth.class,
    QueryBuilder.createFilter()
        .eq("user.phone", phone)
        .select("authName"));
```

### 分组和聚合

```java
List<AuthCount> countList = commonDao.getList(AuthCount.class, UserAuth.class,
    QueryBuilder.createFilter()
        .select(Selectors.select("user.username"), Selectors.count("id"))
        .groupBy("user"));
```

## 高级特性

### 注解驱动查询

```java
public class UserQuery {
    @WhereCondition(condition = FilterSymbol.EQ)
    private String phone;

    @WhereCondition(condition = FilterSymbol.LIKE)
    private String username;

    @Limit
    private Integer limit;
}

UserQuery query = new UserQuery();
query.setPhone("13800138000");
CommonFilter filter = QueryBuilder.forQuery(query);
List<User> users = commonDao.getList(User.class, filter);
```

### 函数式查询

```java
List<User> users = commonDao.getList(QueryBuilder.createFilter(User.class)
    .select(User::getPhone, User::getUsername)
    .eq(User::getPhone, phone));
```

### 全局供应商 (GlobalSupplier)

```java
GlobalSupplier globalSupplier = () -> QueryBuilder.createFilter()
    .eq("status", 1)
    .ge("createTime", LocalDateTime.now().minusDays(30));

CommonFilter filter = QueryBuilder.createFilter(globalSupplier);
List<User> users = commonDao.getList(User.class, filter);
```

### Redis 操作

```java
public class UserInfoHashDao extends AbstractHashCDao {
    @Override
    public String getKey() {
        return "user:info";
    }

    @Override
    public StringRedisTemplate getStringRedisTemplate() {
        return stringRedisTemplate;
    }
}

// 使用
userInfoHashDao.put("1001", userInfoJson);
String info = userInfoHashDao.get("1001");
```

## 项目结构

### 主要包结构

- `top.codef.config`：自动配置类
- `top.codef.dao`：JPA 数据访问层
- `top.codef.redisdao`：Redis 数据访问层
- `top.codef.sqlfilter`：SQL 查询构建工具
- `top.codef.controllers`：全局异常处理
- `top.codef.models`：数据模型
- `top.codef.exceptions`：异常定义
- `top.codef.feign`：Feign 客户端异常处理
- `top.codef.properties`：配置属性
- `top.codef.enums`：枚举定义

### 核心类

- **CommonDao**：通用数据访问类，提供基本的 CRUD 操作
- **BaseDao**：基础 DAO，包含 getSingle、getList、getPage、count、update、delete 等方法
- **AbstractDao**：DAO 抽象基类，提供 EntityManager 和 Session 访问
- **CommonFilter**：查询条件构建器，支持 where、order、group、join 等
- **QueryBuilder**：查询构建工具，提供 createFilter、typeFilter、subQuery、join 等方法

## 配置说明

```yaml
ameba:
  enable-error-advice: true  # 启用全局异常处理
```

## 参考文档

- [core-classes.md](references/core-classes.md)：核心类参考
- [query-examples.md](references/query-examples.md)：查询示例
- [annotation-driven-queries.md](references/annotation-driven-queries.md)：注解驱动查询
- [functional-queries.md](references/functional-queries.md)：函数式查询
- [advanced-queries.md](references/advanced-queries.md)：高级查询
- [update-and-delete.md](references/update-and-delete.md)：更新和删除
- [redis-usage.md](references/redis-usage.md)：Redis 操作
- [exception-handling.md](references/exception-handling.md)：异常处理

## 代码生成

### 生成查询代码

```bash
python scripts/generate_filter.py User id name email
```

### 生成 Redis DAO

```bash
python scripts/generate_redis_dao.py UserInfoDao user:info hash
python scripts/generate_redis_dao.py UserValueDao user:value value
python scripts/generate_redis_dao.py UserLogListDao user:logs list
```

## 注意事项

- 该项目依赖 Spring Boot 4.0.3+ 和 Java 21+
- 使用 JPA 功能时需要配置数据库连接
- 使用 Redis 功能时需要配置 Redis 连接
- `CommonFilter` 条件值为 null 时自动忽略该条件

## 版本历史

- **0.7.0**：支持 Spring Boot 4.0.3 和 Java 21+
- **0.4.0**：支持 Spring Boot 3.0

## 许可证

[LICENSE](LICENSE)