# webflux-rocksdb-running **Repository Path**: coderwing/webflux-rocksdb-running ## Basic Information - **Project Name**: webflux-rocksdb-running - **Description**: rocksdb项目 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-10-25 - **Last Updated**: 2025-10-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # WebFlux + RocksDB 学习项目 > 作者：coderwing > 项目简介：基于Spring Boot WebFlux和RocksDB的响应式用户管理系统 ## 📋 项目概述 本项目是一个学习型项目，演示如何在Spring Boot WebFlux响应式应用中集成RocksDB嵌入式数据库。通过实现一个完整的用户管理系统，帮助开发者理解响应式编程和RocksDB的核心概念。 ## 🎯 核心技术栈 - **Spring Boot 3.2.0** - 现代化的Java应用框架 - **Spring WebFlux** - 响应式Web框架 - **RocksDB 8.6.7** - 高性能嵌入式键值数据库 - **Project Reactor** - 响应式编程库 - **Lombok** - 简化Java代码 - **Jackson** - JSON序列化/反序列化 - **Maven** - 项目构建管理 ## ✨ 项目特性 ### 核心功能 - ✅ 完整的用户CRUD操作（创建、读取、更新、删除） - ✅ 响应式编程实践（Mono/Flux） - ✅ RESTful API设计 - ✅ 全局异常处理 - ✅ 参数校验 - ✅ 详细的代码注释 - ✅ 完善的日志记录 ### RocksDB高级特性 ⭐ - ✅ **列族（Column Family）完整使用** - 6个列族展示不同场景（users、orders、products、cache、logs） - 每个列族独立配置（压缩算法、缓冲区、缓存） - 列族统计和监控 - ✅ **二级索引（Secondary Index）** ⭐ 新增 - 支持username、email、phone索引查询（O(1)复杂度） - 自动维护索引（增删改时同步更新） - 唯一性校验 - 前缀模糊查询 - 非唯一索引（如status） - ✅ **批量操作** - WriteBatch批量写入 - 跨列族原子操作 - ✅ **高级查询** - 前缀查询（prefix scan） - 快照读取（snapshot） - 迭代器操作 - ✅ **性能优化** - 多种压缩算法（SNAPPY、LZ4、ZSTD） - 布隆过滤器 - 块缓存配置 - 写放大优化 ## 📁 项目结构 ``` webflux-rocksdb-running/ ├── src/ │ └── main/ │ ├── java/com/running/rocksdb/ │ │ ├── RocksDBApplication.java # 应用启动类 │ │ ├── config/ │ │ │ └── RocksDBConfig.java # RocksDB配置（支持多列族）⭐ │ │ ├── controller/ │ │ │ ├── UserController.java # 用户控制器 │ │ │ ├── UserIndexController.java # 索引查询控制器 ⭐ │ │ │ └── ColumnFamilyController.java # 列族演示控制器 ⭐ │ │ ├── entity/ │ │ │ ├── User.java # 用户实体 │ │ │ └── Order.java # 订单实体 ⭐ │ │ ├── index/ │ │ │ └── IndexManager.java # 索引管理器 ⭐ │ │ ├── repository/ │ │ │ ├── RocksDBRepository.java # RocksDB通用仓储（高级API）⭐ │ │ │ ├── UserRepository.java # 用户仓储（使用users列族） │ │ │ └── OrderRepository.java # 订单仓储（使用orders列族）⭐ │ │ ├── service/ │ │ │ └── UserService.java # 用户服务 │ │ └── exception/ │ │ └── GlobalExceptionHandler.java # 全局异常处理 │ └── resources/ │ ├── application.yml # 应用配置 │ └── logback-spring.xml # 日志配置 ├── data/ # RocksDB数据目录（自动创建） ├── logs/ # 日志目录（自动创建） ├── pom.xml # Maven配置 ├── README.md # 项目说明 ├── ROCKSDB_LEARNING.md # RocksDB学习文档（含压缩和写放大）⭐ ├── 列族使用指南.md # 列族使用指南 ⭐ ├── 索引使用指南.md # 二级索引使用指南 ⭐ ├── API_TEST.md # API测试文档 ├── INDEX_API_TEST.md # 索引API测试文档 ⭐ ├── 快速启动指南.md # 快速上手 └── 配置说明.md # 配置详解 ``` **⭐ 标记为v2.0新增或增强的内容** ## 🚀 快速开始 ### 环境要求 - JDK 17 或更高版本 - Maven 3.6+ - 操作系统：Linux、macOS 或 Windows ### 构建项目 ```bash # 克隆或下载项目后，进入项目目录 cd webflux-rocksdb-running # 使用Maven编译项目 mvn clean install ``` ### 运行项目 ```bash # 方式1：使用Maven运行 mvn spring-boot:run # 方式2：运行打包后的JAR java -jar target/webflux-rocksdb-running-1.0.0-SNAPSHOT.jar ``` 启动成功后，访问：http://localhost:8080 ## 📝 API接口说明 ### 用户管理API #### 1. 创建用户 **接口：** `POST /api/users` **请求体示例：** ```json { "username": "张三", "email": "zhangsan@example.com", "age": 25, "phone": "13800138000", "address": "北京市朝阳区" } ``` **响应示例：** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "username": "张三", "email": "zhangsan@example.com", "age": 25, "phone": "13800138000", "address": "北京市朝阳区", "status": "ACTIVE", "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ``` #### 2. 查询用户 **接口：** `GET /api/users/{id}` **响应示例：** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "username": "张三", "email": "zhangsan@example.com", "age": 25, "phone": "13800138000", "address": "北京市朝阳区", "status": "ACTIVE", "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ``` #### 3. 查询所有用户 **接口：** `GET /api/users` **响应示例：** ```json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "username": "张三", "email": "zhangsan@example.com", ... }, { "id": "550e8400-e29b-41d4-a716-446655440001", "username": "李四", "email": "lisi@example.com", ... } ] ``` #### 4. 更新用户 **接口：** `PUT /api/users/{id}` **请求体示例：** ```json { "phone": "13900139000", "address": "上海市浦东新区" } ``` #### 5. 删除用户 **接口：** `DELETE /api/users/{id}` **响应：** 204 No Content #### 6. 检查用户是否存在 **接口：** `GET /api/users/{id}/exists` **响应示例：** `true` 或 `false` ### 索引查询API ⭐ 新增 #### 1. 通过username查询用户 **接口：** `GET /api/users/by-username/{username}` **示例：** `GET /api/users/by-username/张三` **特点：** O(1)复杂度，无需全表扫描 #### 2. 通过email查询用户 **接口：** `GET /api/users/by-email/{email}` **示例：** `GET /api/users/by-email/zhangsan@example.com` #### 3. 通过phone查询用户 **接口：** `GET /api/users/by-phone/{phone}` **示例：** `GET /api/users/by-phone/13800138000` #### 4. username前缀模糊查询 **接口：** `GET /api/users/by-username-prefix/{prefix}` **示例：** `GET /api/users/by-username-prefix/zhang` **返回：** 所有username以"zhang"开头的用户列表 #### 5. 按状态查询用户 **接口：** `GET /api/users/by-status/{status}` **示例：** `GET /api/users/by-status/ACTIVE` #### 6. 检查email是否可用 **接口：** `GET /api/users/check-email/{email}` **响应：** ```json { "email": "test@example.com", "exists": false, "available": true } ``` #### 7. 检查username是否可用 **接口：** `GET /api/users/check-username/{username}` #### 8. 检查phone是否可用 **接口：** `GET /api/users/check-phone/{phone}` ### 列族管理API ⭐ #### 1. 列出所有列族 **接口：** `GET /api/cf/list` **响应示例：** ```json { "columnFamilies": ["default", "users", "orders", "products", "cache", "logs"], "count": 6 } ``` #### 2. 查看列族统计信息 **接口：** `GET /api/cf/{name}/stats` **示例：** `GET /api/cf/users/stats` **响应示例：** ```json { "columnFamily": "users", "estimatedKeys": 1250, "stats": "** Compaction Stats [users] **\nLevel Files Size..." } ``` #### 3. 创建演示数据 **接口：** `POST /api/cf/demo` 创建示例用户和订单数据到不同列族 #### 4. 跨列族批量操作 **接口：** `POST /api/cf/batch` **请求体：** ```json { "username": "王五", "email": "wangwu@example.com", "age": 28, "productName": "测试商品", "amount": 199.99 } ``` 同时在users和orders列族创建数据（原子操作） #### 5. 列族汇总统计 **接口：** `GET /api/cf/summary` 查看所有列族的数据量汇总 ## 🧪 测试示例 使用curl命令测试API： ```bash # 1. 创建用户 curl -X POST http://localhost:8080/api/users \ -H "Content-Type: application/json" \ -d '{ "username": "张三", "email": "zhangsan@example.com", "age": 25, "phone": "13800138000", "address": "北京市朝阳区" }' # 2. 查询所有用户 curl http://localhost:8080/api/users # 3. 查询指定用户（替换{id}为实际ID） curl http://localhost:8080/api/users/{id} # 4. 更新用户（替换{id}为实际ID） curl -X PUT http://localhost:8080/api/users/{id} \ -H "Content-Type: application/json" \ -d '{ "phone": "13900139000" }' # 5. 删除用户（替换{id}为实际ID） curl -X DELETE http://localhost:8080/api/users/{id} # 6. 检查用户是否存在（替换{id}为实际ID） curl http://localhost:8080/api/users/{id}/exists ``` ## 📚 学习资源 ### 项目文档 - **[ROCKSDB_LEARNING.md](./ROCKSDB_LEARNING.md)** - RocksDB详细学习文档（含压缩算法和写放大优化） - **[列族使用指南.md](./列族使用指南.md)** - 列族完整使用指南 ⭐ - **[索引使用指南.md](./索引使用指南.md)** - 二级索引使用指南 ⭐ 新增 - **[API_TEST.md](./API_TEST.md)** - 完整的API测试文档 - **[INDEX_API_TEST.md](./INDEX_API_TEST.md)** - 索引API测试文档 ⭐ 新增 - **[快速启动指南.md](./快速启动指南.md)** - 零基础快速上手 - **[配置说明.md](./配置说明.md)** - 详细的配置说明 ### 官方文档 - [Spring WebFlux官方文档](https://docs.spring.io/spring-framework/reference/web/webflux.html) - [RocksDB官方Wiki](https://github.com/facebook/rocksdb/wiki) - [Project Reactor文档](https://projectreactor.io/docs) - [RocksDB Column Families](https://github.com/facebook/rocksdb/wiki/Column-Families) ## 🔧 配置说明 ### application.yml主要配置项 ```yaml server: port: 8080 # 服务端口 rocksdb: path: ./data/rocksdb # RocksDB数据存储路径 logging: level: com.running.rocksdb: DEBUG # 应用日志级别 ``` ### RocksDB配置参数 在`RocksDBConfig.java`中可以调整以下参数： - **writBufferSize**: 写缓冲区大小（默认64MB） - **maxBackgroundJobs**: 后台任务线程数（默认4） - **compressionType**: 压缩算法（默认SNAPPY） - **blockSize**: 数据块大小（默认16KB） ## 📊 性能优化建议 1. **适当增加写缓冲区大小** - 提高写入性能 2. **启用布隆过滤器** - 提高读取性能 3. **合理设置后台线程数** - 根据CPU核心数调整 4. **使用合适的压缩算法** - 平衡压缩率和性能 5. **定期执行compaction** - 保持数据文件整洁 ## 🐛 常见问题 ### 1. RocksDB启动失败 **问题：** 提示找不到本地库文件 **解决：** 确保Maven正确下载了rocksdbjni依赖，并且操作系统兼容 ### 2. 数据丢失 **问题：** 重启后数据消失 **解决：** 检查rocksdb.path配置，确保路径正确且有写权限 ### 3. 性能问题 **问题：** 写入或读取速度慢 **解决：** 调整RocksDB配置参数，参考性能优化建议 ## 🤝 贡献 欢迎提交Issue和Pull Request来完善这个学习项目！ ## 📄 许可证 本项目仅供学习使用，可自由修改和分发。 ## 👨‍💻 作者 **coderwing** 如有问题或建议，欢迎交流学习！ --- ⭐ 如果这个项目对你有帮助，请给个Star支持一下！