Debbie 0.6.2-RELEASE

一个从零实现的 Java 微服务框架，包含 IOC、MVC、JDBC、HTTP客户端、HTTP Server、定时任务、Event、终端应用、javafx、测试、其他第三方服务/框架支持等模块。支持 JDK 17+ 运行，兼容 GraalVM Native Image。

一、版本说明

项目	信息
版本号	0.6.2-RELEASE
发布日期	2026-08
Java 版本	17+
许可证	Mulan PSL v2
模块化	全面支持 Java Platform Module System (JPMS)

0.6.x 系列功能

IOC 容器（注解驱动 + SPI 扩展）
依赖注入（@BeanInject、@Inject、@Resource，其他自定义扩展）
服务告警（暂未实现）
MVC 路由（@Router、@HttpRouter、@RestRouter、@GetRouter、@PostRouter、@PutRouter、@DeleteRouter、@PatchRouter、@OptionsRouter、@TraceRouter、@HeadRouter、@RequestParameter、@BodyParameter、@CookieParameter、@HeadParameter、@InnerParameter、@MatrixParameter、@ParamParameter、@PathParameter、@QueryParameter、@SessionParameter、@Filter）
HTTP 客户端（基于 MVC 内核）
多种 Server 支持（Netty、AIO、Undertow为无servlet服务器，Tomcat为servlet服务器）、外部servlet服务器支持
JDBC 操作（@JdbcTransactional、@SqlRepository、@SqlEntity、@SqlColumn、@JdbcTransient）
定时任务（@DebbieTask，支持 fixedRate 和 cron）
Event（@EventBeanListener、EventMethodListener）
配置属性注入（@PropertiesConfiguration）
测试框架（@DebbieApplicationTest）
终端应用（暂未实现）
其他外部服务/框架支持：freemarker、hikari、javafx、kafka、lucene、metrics、mybatis、quartz、spring、swagger

二、模块说明

模块	ArtifactId	说明
core	`debbie-core`	核心 IOC 容器、Bean 管理、配置、定时任务、Event等，无任何我开发之外的第三方依赖
jackson	`debbie-jackson`	JSON 序列化/反序列化
asm	`debbie-asm`	ASM 字节码增强（Bean 代理），暂未完全实现
quartz	`debbie-quartz`	quartz框架支持
jdbc	`debbie-jdbc`	JDBC 封装、ORM 实体映射、简单mock、简单jdbc连接池
mybatis	`debbie-mybatis`	Mybatis 支持
Hikari	`debbie-hikari`	Hikari 支持
mvc	`debbie-mvc`	MVC 路由、请求参数处理、响应处理，无servlet
httpclient	`debbie-httpclient`	HTTP 客户端（基于 MVC 内核）
server	`debbie-server`	Server 抽象层，无servle
netty	`debbie-netty`	Netty 运行时，无servlet
aio	`debbie-aio`	AIO HTTP 运行时，无servlet
tomcat	`debbie-tomcat`	Tomcat 运行时
undertow	`debbie-undertow`	Undertow 运行时，无servle
agent	`debbie-agent`	Java Agent
console	`debbie-console`	控制台支持
javafx	`debbie-javafx`	JavaFx 支持
test	`debbie-test`	测试框架Junit5 支持
kafka	`debbie-kafka`	Kafka 支持
lucene	`debbie-lucene`	Lucene 支持
metrics	`debbie-metrics`	第三方告警支持
freemark	`debbie-freemark`	freemark 支持
swagger	`debbie-swagger`	swagger 支持

三、Maven 依赖

核心

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-core</artifactId>
    <version>0.6.2-RELEASE</version>
</dependency>

Server（选择一种）

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-netty</artifactId>
    <version>0.6.2-RELEASE</version>
</dependency>

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-aio</artifactId>
    <version>0.6.2-RELEASE</version>
</dependency>

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-tomcat</artifactId>
    <version>0.6.2-RELEASE</version>
</dependency>

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-undertow</artifactId>
    <version>0.6.2-RELEASE</version>
</dependency>

Web

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-mvc</artifactId>
    <version>0.6.2-RELEASE</version>
</dependency>

servlet（兼容servlet的场景）

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-servlet</artifactId>
    <version>0.6.2-RELEASE</version>
</dependency>

swagger

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-servlet</artifactId>
    <version>0.6.2-RELEASE</version>
</dependency>

HTTP 客户端

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-httpclient</artifactId>
    <version>0.6.2-RELEASE</version>
</dependency>

JDBC

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-jdbc</artifactId>
    <version>0.6.2-RELEASE</version>
</dependency>

Hikara（替换内置数据库连接池）

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-hikari</artifactId>
    <version>0.6.2-RELEASE</version>
</dependency>

MyBatis

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-mybatis</artifactId>
    <version>0.6.2-RELEASE</version>
</dependency>

测试

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-test</artifactId>
    <version>0.6.2-RELEASE</version>
    <scope>test</scope>
</dependency>

spring生态兼容（非必填，可能兼容性不好）

<dependency>
    <groupId>com.truthbean</groupId>
    <artifactId>debbie-spring</artifactId>
    <version>0.6.2-RELEASE</version>
    <scope>test</scope>
</dependency>

四、框架使用指南

4.1 快速开始

import com.truthbean.debbie.boot.DebbieBootApplication;
import com.truthbean.debbie.boot.DebbieApplication;

@DebbieBootApplication
public class MyApplication {
    public static void main(String[] args) {
        DebbieApplication application = DebbieApplication.run(MyApplication.class, args);
    }
}

4.2 依赖注入

import com.truthbean.debbie.bean.BeanComponent;
import com.truthbean.debbie.bean.BeanInject;

// 定义 Bean
@BeanComponent
public class UserService {
    public String getUserName() {
        return "Alice";
    }
}

// 注入 Bean
@BeanComponent
public class UserController {
    @BeanInject
    private UserService userService;

    public void printUser() {
        System.out.println(userService.getUserName());
    }
}

4.3 MVC 路由

import com.truthbean.debbie.mvc.router.Router;
import com.truthbean.debbie.mvc.router.GetRouter;
import com.truthbean.debbie.mvc.router.PostRouter;
import com.truthbean.debbie.mvc.request.RequestParameter;

@Router
public class HelloController {

    @GetRouter("/hello")
    public String hello(@RequestParameter("name") String name) {
        return "Hello, " + name + "!";
    }

    @PostRouter("/api/user")
    public String createUser(@RequestParameter(value = "name", body = true) String name) {
        return "Created user: " + name;
    }
}

4.4 JDBC / ORM

import com.truthbean.debbie.jdbc.annotation.SqlEntity;
import com.truthbean.debbie.jdbc.annotation.SqlColumn;
import com.truthbean.debbie.jdbc.annotation.SqlRepository;

// 实体类
@SqlEntity(table = "users")
public class User {
    @SqlColumn(id = true)
    private Long id;

    @SqlColumn
    private String name;

    @SqlColumn
    private String email;

    // getters and setters...
}

// 数据访问层
@SqlRepository
public class UserRepository {
    @BeanInject
    private DataSource dataSource;

    public User findById(Long id) {
        // 执行 SQL 查询
    }
}

4.5 定时任务

import com.truthbean.debbie.task.DebbieTask;

@BeanComponent
public class ScheduledTasks {

    // 每 5 秒执行一次
    @DebbieTask(fixedRate = 5000)
    public void runEvery5Seconds() {
        System.out.println("Task executed at " + System.currentTimeMillis());
    }

    // 延迟 10 秒后首次执行，之后每 5 秒执行一次
    @DebbieTask(fixedRate = 5000, initialDelay = 10000)
    public void runWithDelay() {
        System.out.println("Delayed task executed");
    }

    // 使用 cron 表达式：每天中午 12:00 执行
    @DebbieTask(cron = "0 0 12 * * ?")
    public void runAtNoon() {
        System.out.println("Noon task executed");
    }

    // 使用 7 字段 cron：仅在 2026 年，每月 1 号中午执行
    @DebbieTask(cron = "0 0 12 1 * ? 2026")
    public void runIn2026() {
        System.out.println("Task executed in 2026");
    }
}

Cron 表达式说明：

字段	必填	取值范围	特殊字符
second	是	0-59	`*` `-` `,` `/`
minute	是	0-59	`*` `-` `,` `/`
hour	是	0-23	`*` `-` `,` `/`
dayOfMonth	是	1-31	`*` `?` `-` `,` `/`
month	是	1-12	`*` `-` `,` `/`
dayOfWeek	是	0-7 (0 和 7 都表示周日)	`*` `?` `-` `,` `/`
year	否	1970-2199	`*` `-` `,`

常用示例：

0 12 * * ?          每天中午 12:00
0/5 * * * ?         每 5 分钟
0/5 9-17 ? * 1-5    工作日上午 9 点到下午 5 点，每 5 分钟
0 0 1,15 * ?        每月 1 号和 15 号凌晨
0 0 1 1,4,7,10 ?    每季度第一天
0 12 1 * ? 2026-2028  仅在 2026-2028 年，每月 1 号中午

4.6 配置属性

import com.truthbean.debbie.properties.PropertiesConfiguration;

@PropertiesConfiguration(prefix = "app")
public class AppConfig {
    private String name;
    private int port;
    private String[] allowedOrigins;

    // getters and setters...
}

配置文件 application.properties：

# 日志配置
logging.level.root=DEBUG
logging.level.com.truthbean=TRACE

# 服务器配置
debbie.server.port=8080
debbie.web.static-resources-mapping-location=/**=statics/

4.7 测试

import com.truthbean.debbie.test.annotation.DebbieApplicationTest;
import com.truthbean.debbie.bean.BeanInject;
import org.junit.jupiter.api.Test;

@DebbieApplicationTest
public class UserServiceTest {

    @BeanInject
    private UserService userService;

    @Test
    void testGetUserName() {
        String name = userService.getUserName();
        // 验证结果
    }
}

五、已知问题 & TODO

Metric 功能未实现
Cache 功能未实现
迁移到 Java 25
减少反射使用（核心模块多处 TODO 标记）
测试覆盖需补充（agent、asm、httpclient 等模块缺少测试）