一个基于 Vert.x 的轻量级 Java 框架，专注 JSON API 服务，核心打包 30MB 以内；提供类似 Spring Boot 的开发体验，集成了代码生成器、jOOQ DSL、WebSocket、反向代理等企业级功能。相比于Quarkus可以带来更高性能、更友好的开发体验。
VXCore（微克） 主打轻量：只做 JSON API 服务，核心体积控制在 30MB 以内，不铺功能面。它是高性能、响应式的 Java 框架，专为构建现代化 Web API 而设计，结合 Vert.x 的异步编程模型、jOOQ 的类型安全数据库操作与丰富注解，提供简洁而强大的开发体验。
VXCore 的设计哲学是"简单而不失优雅"：
- 简单: 降低学习成本，提供直观的 API 设计，让开发者能够快速上手
- 优雅: 在简单的基础上，提供强大的功能和良好的扩展性，满足复杂业务需求
- 平衡: 在简单性和功能性之间找到最佳平衡点，既不过度设计，也不功能缺失
这一设计思想使 VXCore 既适合新手快速上手，也能满足专家级用户的复杂需求。
- ✅ 版本号升级: 1.2.2 → 1.2.3
- ✅ 依赖漏洞修复: 升级 Vert.x 4.5.25（内置 Netty 4.1.130.Final，修复 CVE-2025-67735 CRLF 注入漏洞）、Jackson 2.18.3、Logback 1.5.17、PostgreSQL 42.7.10
- ✅ 版本统一管理: 消除子模块硬编码版本，统一由父 POM 管理
- ✅ AOP 代理修复: 修复 ServiceRegistry 中服务实例未应用 AOP 代理的问题
- ✅ JaCoCo 启用: 恢复 core/core-database 模块的测试覆盖率报告
- ✅ 文档版本同步: 统一所有文档中的版本引用
- ✅ DI 依赖注入修复: ServiceRegistry 支持按类型查找，接口注入和具体类注入均正常工作
- ✅ 注解包名修正:
annotaions→annotations全项目统一修正 - ✅ AOP 切面框架: 基于 Byte Buddy 的 @Aspect/@Before/@After 切面支持
- ✅ 异常处理增强: 内置全局异常处理器，统一 JSON 错误响应
- ✅ 配置管理: YAML 配置加载、合并、SharedData 访问
- ✅ 路由注解增强: 支持 {id} 路径变量自动转换、@RequestBody JSON 绑定
- ✅ 全量文档验证: 新增 vxcore-demo 项目（7 个子模块）验证所有文档示例
详细问题报告请参考 验证报告
VXCore 构建在 Vert.x 的事件驱动、非阻塞 I/O 模型之上，从根本上区别于传统框架的线程-请求模型。
传统框架（线程-请求模型） VXCore / Vert.x（事件循环模型）
───────────────────────────── ──────────────────────────────────────
请求1 ──► 线程1（等待 DB） 阻塞 请求1 ──┐
请求2 ──► 线程2（等待 DB） 阻塞 请求2 ──┤
请求3 ──► 线程3（等待 I/O） 阻塞 请求3 ──┤──► Event Loop ──► 注册回调，立即返回
请求N ──► 线程N（OOM 风险） 阻塞 请求N ──┘ │
│ DB 响应 ──► 执行回调
每连接 ~1MB 线程栈内存 │ I/O 完成 ──► 执行回调
并发上限受线程池大小限制 单线程处理数万并发，内存占用极低
| 特性 | 传统框架（Spring MVC） | VXCore（Vert.x） |
|---|---|---|
| 并发模型 | 线程池（每请求一线程） | 事件循环（非阻塞） |
| 每连接内存 | ~1 MB（线程栈） | 几 KB |
| 万并发内存 | ~10 GB | ~数百 MB |
| I/O 等待 | 线程阻塞，资源浪费 | 异步回调，零阻塞 |
| 吞吐量（QPS） | 受线程数上限制约 | 硬件 I/O 上限 |
| 延迟 | 线程调度开销 | 微秒级事件分发 |
// 多个异步操作串联/并行，全程非阻塞
public Future<OrderResult> placeOrder(OrderRequest req) {
return userDao.findById(req.getUserId()) // 1. 异步查询用户
.compose(user -> inventoryService.lock(req)) // 2. 异步锁库存
.compose(locked -> paymentService.charge(req)) // 3. 异步扣款
.compose(paid -> orderDao.create(req, paid)) // 4. 异步创建订单
.onSuccess(order -> eventBus.publish("order.created", order))
.recover(e -> {
inventoryService.unlock(req); // 失败时自动回滚
return Future.failedFuture(e);
});
// 以上所有操作均不阻塞任何线程
}- Vert.x 4.5+: 基于事件驱动的异步非阻塞 I/O，内置 Netty 高性能网络层
- Verticle 架构: 轻量级并发单元，每个 Verticle 在独立事件循环上运行
- Future/Promise: 可组合的异步编程模型，支持链式调用、并行聚合、错误恢复
- 高并发处理: 单 JVM 实例可处理 50,000+ QPS，支持数万并发 WebSocket 连接
- 内存优化: 零拷贝 I/O、对象池、数据库连接池，内存利用率远优于传统框架
- jOOQ DSL: 编译时类型检查，完全防止 SQL 注入
- Lambda 查询: 类似 MyBatis-Plus 的 Lambda 表达式查询
- 无参构造函数DAO: 自动初始化，无需手动传递参数
- 多数据源支持: 支持动态数据源切换和事务隔离
- 批量操作: 高性能批量 CRUD 操作
- 注解式路由: 类似 Spring MVC 的
@RouteMapping注解 - 参数绑定: 支持方法重载、类型转换、自定义转换器
- 异常处理: 全局和局部异常处理机制
- WebSocket: 注解式 WebSocket 路由和代理支持
- 代码生成器: 根据数据库表结构自动生成三层架构代码
- 反向代理: 支持 HTTP/WebSocket 代理，类似 Nginx
- 配置管理: YAML 配置，支持 IDE 自动提示和验证
- SPI 扩展: 支持第三方数据库驱动和功能扩展
- 监控审计: SQL 审计、性能监控、错误追踪
- core: 核心框架模块（路由、注解、DI、AOP、配置）
- core-database: 数据库操作模块（DSL、Lambda、多数据源）
- core-generator: 代码生成器模块（根据数据库表结构生成代码）
- core-example: 示例和演示模块
- vxcore-demo: 文档验证项目（7 个独立子模块）
vxcore/
├── core/ # 核心框架模块
│ ├── src/main/java/ # 核心 Java 源码
│ │ ├── cn/qaiu/vx/core/ # 核心包
│ │ │ ├── annotations/ # 注解定义
│ │ │ ├── handlerfactory/ # 处理器工厂
│ │ │ ├── proxy/ # 反向代理
│ │ │ ├── util/ # 工具类
│ │ │ └── verticle/ # Verticle 实现
│ │ └── resources/ # 资源文件
│ ├── src/test/java/ # 测试代码
│ └── pom.xml # 核心模块配置
├── core-database/ # 数据库操作模块
│ ├── src/main/java/ # 数据库相关源码
│ │ ├── cn/qaiu/db/ # 数据库包
│ │ │ ├── dsl/ # DSL 框架
│ │ │ │ ├── lambda/ # Lambda 查询
│ │ │ │ └── core/ # 核心组件
│ │ │ ├── datasource/ # 多数据源支持
│ │ │ └── spi/ # SPI 扩展
│ │ └── resources/ # 资源文件
│ ├── src/test/java/ # 测试代码
│ ├── docs/ # 文档
│ └── pom.xml # 数据库模块配置
├── core-example/ # 示例模块
│ ├── src/main/java/ # 示例代码
│ ├── src/main/resources/ # 配置文件
│ └── pom.xml # 示例模块配置
├── docs/ # 项目文档
│ ├── README.md # 文档索引
│ ├── VXCORE_OPTIMIZATION_PLAN.md # 优化计划
│ └── *.md # 各种指南文档
└── pom.xml # 根项目配置
- Java 17+: 支持现代 Java 特性
- Maven 3.8+: 现代化构建工具
- 数据库: H2/MySQL/PostgreSQL（可选）
VXCore 已发布到 Maven 中央仓库，可直接在项目中引入：
<properties>
<vxcore.version>1.2.3</vxcore.version>
</properties>
<dependencies>
<!-- VXCore 核心模块 -->
<dependency>
<groupId>cn.qaiu</groupId>
<artifactId>core</artifactId>
<version>${vxcore.version}</version>
</dependency>
<!-- VXCore 数据库模块 -->
<dependency>
<groupId>cn.qaiu</groupId>
<artifactId>core-database</artifactId>
<version>${vxcore.version}</version>
</dependency>
<!-- VXCore 代码生成器（可选） -->
<dependency>
<groupId>cn.qaiu</groupId>
<artifactId>core-generator</artifactId>
<version>${vxcore.version}</version>
<scope>provided</scope>
</dependency>
</dependencies>方式一：使用 Maven 依赖（推荐）
# 创建新的 Maven 项目
mvn archetype:generate -DgroupId=com.example -DartifactId=my-app
# 在 pom.xml 中添加上述依赖方式二：克隆源码
git clone https://github.com/qaiu/vxcore.git
cd vxcore
mvn clean compile@RouteHandler("/api")
public class UserController {
@RouteMapping(value = "/hello", method = RouteMethod.GET)
public Future<JsonResult<String>> hello(@RequestParam("name") String name) {
return Future.succeededFuture(
JsonResult.data("Hello, " + name + "!")
);
}
@RouteMapping(value = "/users", method = RouteMethod.POST)
public Future<JsonResult<User>> createUser(@RequestBody User user) {
return userService.createUser(user)
.map(createdUser -> JsonResult.data(createdUser));
}
}@DdlTable("users")
public class User extends BaseEntity {
@DdlColumn("user_name")
private String name;
@DdlColumn("user_email")
private String email;
// getters and setters...
}
// 最简单的DAO - 连构造函数都没有
public class UserDao extends AbstractDao<User, Long> {
// 完全空的类，框架自动处理所有初始化
// 1. 自动通过泛型获取User类型
// 2. 自动初始化SQL执行器
// 3. 自动获取表名和主键信息
}
// 使用方式
UserDao userDao = new UserDao(); // 无需传递任何参数！
// Lambda 查询示例
public class UserService {
public Future<List<User>> findActiveUsers() {
return userDao.lambdaQuery()
.eq(User::getStatus, "ACTIVE")
.like(User::getName, "张%")
.orderBy(User::getCreateTime, SortOrder.DESC)
.list();
}
public Future<List<User>> findUsersWithOrders() {
return userDao.lambdaQuery()
.leftJoin(Order.class, (user, order) ->
user.getId().eq(order.getUserId()))
.eq(User::getStatus, "ACTIVE")
.list();
}
}# application.yml
datasources:
primary:
url: jdbc:mysql://localhost:3306/main_db
username: root
password: password
driver: com.mysql.cj.jdbc.Driver
secondary:
url: jdbc:postgresql://localhost:5432/log_db
username: postgres
password: password
driver: org.postgresql.Driver@DataSource("primary")
public class UserDao extends AbstractDao<User> {
@DataSource("secondary")
public Future<List<Log>> findUserLogs(Long userId) {
return logDao.lambdaQuery()
.eq(Log::getUserId, userId)
.list();
}
}@WebSocketHandler("/ws/chat")
public class ChatHandler {
@OnOpen
public void onOpen(ServerWebSocket ws) {
System.out.println("用户连接: " + ws.remoteAddress());
}
@OnMessage
public void onMessage(String message, ServerWebSocket ws) {
// 广播消息给所有连接的客户端
ws.writeTextMessage("Echo: " + message);
}
@OnClose
public void onClose(ServerWebSocket ws) {
System.out.println("用户断开: " + ws.remoteAddress());
}
}- 用途: 开发、测试、演示
- 特点: 内存数据库，零配置
- 优势: 快速启动，支持完整 SQL 语法
- 用途: 生产环境推荐
- 特点: 高性能、高可用
- 优势: 支持事务、索引、复杂查询
- 用途: 企业级应用
- 特点: 功能丰富、标准兼容
- 优势: 支持 JSON、数组、自定义类型
- WebSocket指南 - WebSocket开发指南
- 反向代理 - 反向代理配置
- 路由注解 - 路由注解使用
项目包含完整的测试套件，覆盖率达到 80%+：
# 运行所有测试
mvn test
# 运行特定模块测试
mvn test -pl core
mvn test -pl core-database
# 运行特定数据库测试
mvn test -Dtest=*H2*
mvn test -Dtest=*MySQL*
mvn test -Dtest=*PostgreSQL*
# 生成测试覆盖率报告
mvn test jacoco:report- 并发处理: 支持数万并发连接
- 响应时间: 微秒级响应延迟
- 内存使用: 低内存占用，高效对象池
- CPU 利用率: 单线程事件循环，CPU 友好
- HTTP 请求: 50,000+ QPS
- WebSocket 连接: 10,000+ 并发连接
- 数据库查询: 10,000+ QPS
- 批量操作: 1000 条记录 < 100ms
我们欢迎社区贡献！请查看：
- Fork 项目 - 点击右上角 Fork 按钮
- 创建分支 -
git checkout -b feature/AmazingFeature - 提交更改 -
git commit -m 'Add some AmazingFeature' - 推送分支 -
git push origin feature/AmazingFeature - 创建 PR - 在 GitHub 上创建 Pull Request
- Java 规范: 遵循阿里巴巴 Java 开发规范
- 注释要求: 所有 public 方法必须有 JavaDoc
- 测试要求: 新功能必须包含单元测试
- 提交信息: 使用清晰的提交信息
- 覆盖率: 新代码测试覆盖率 > 80%
- 测试类型: 单元测试 + 集成测试
- 测试数据: 使用 H2 内存数据库
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
- 作者: QAIU
- 邮箱: qaiu@qq.com
- 网站: https://qaiu.top
- GitHub: https://github.com/qaiu
- ✅ 依赖漏洞修复: 升级 Vert.x 4.5.25（内置 Netty 4.1.130.Final，修复 CVE-2025-67735 CRLF 注入漏洞）、Jackson 2.18.3、Logback 1.5.17、PostgreSQL 42.7.10
- ✅ 版本统一管理: 消除子模块硬编码版本，统一由父 POM 管理
- ✅ AOP 代理修复: 修复 ServiceRegistry 中服务实例未应用 AOP 代理的问题
- ✅ JaCoCo 启用: 恢复 core/core-database 模块的测试覆盖率报告
- ✅ DI 依赖注入修复: ServiceRegistry 按类型查找，接口/具体类注入均可用
- ✅ 注解包名修正:
annotaions→annotations，全项目统一修正 - ✅ AOP 切面框架: 基于 Byte Buddy 的 @Aspect/@Before/@After/@AfterThrowing
- ✅ 异常处理增强: ExceptionHandlerManager 内置全局异常处理
- ✅ 配置管理完善: YAML 合并加载、SharedData 配置访问
- ✅ 路由增强: {id} 路径变量自动转换、@RequestBody/@RequestParam 完善
- ✅ vxcore-demo 验证项目: 7 个独立子模块验证全部文档示例
- ✅ 无参构造函数DAO: 自动初始化，无需手动传递参数
- ✅ 代码生成器: 根据数据库表结构自动生成三层架构代码
- ✅ Lambda 查询增强: 支持 Join、聚合查询、子查询
- ✅ 批量操作: batchInsert、batchUpdate、batchDelete
- ✅ 多数据源支持: 动态数据源切换和事务隔离
- ✅ 注解式路由: 类似 Spring MVC 的路由注解
- ✅ WebSocket 支持: 注解式 WebSocket 路由
- ✅ 反向代理: HTTP/WebSocket 代理支持
- ✅ 配置元数据: IDE 自动提示和验证
- ✅ SPI 扩展: 支持第三方数据库驱动扩展
- ✅ 初始版本发布
- ✅ 支持 H2、MySQL、PostgreSQL
- ✅ 完整的 DSL 框架
- ✅ 集成 jOOQ 支持
- 🔄 @ControllerAdvice: 全局异常处理器扫描注册
- 🔄 Jackson JavaTimeModule: 自动注册 Java 8 时间类型支持
- 🔄 安全框架完善: JWT 认证 + @Authenticated/@RequiresRoles
- 🔄 文档示例修正: 统一 API 用法与文档描述
- 📋 微服务支持: 服务发现、配置中心
- 📋 监控集成: Prometheus、Grafana
- 📋 云原生: Docker、Kubernetes 支持
- 📋 HTML 模板引擎: 视图渲染支持
🎯 VXCore - 让 Java Web 开发更简单、更高效、更现代！