# LazyCat

**Repository Path**: leavingme/lazycat

## Basic Information

- **Project Name**: LazyCat
- **Description**: 极简、 IOC、AOP、WEB、启动快、高性能、好维护，核心代码仅 500 KB。
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 31
- **Forks**: 0
- **Created**: 2025-07-01
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# 懒王猫（Lazycat）

## 介绍
不是为了超越谁, 只想做更好的自己。
Lazycat (懒王猫) 是一个基于 Java 的轻量级 Web 框架，支持 IOC、AOP、事务管理、数据库操作、HTTP 服务、静态资源服务等功能。
代码轻量、简单、启动快、高性能、好维护, 程序打包15M以内, 却拥有完整的Web功能。
此外，本项目还包含了一个完整的 **内网穿透 (Lazycat Netpipe)** 解决方案。

## 软件架构
Lazycat 采用模块化设计，核心模块包括：

**核心基础模块：**
- **lazycat-aop**：基于 AOP 的拦截器支持，提供方法级别的切面编程能力。
- **lazycat-core**：框架核心，提供基础配置、插件系统、事件监听、异常处理等。
- **lazycat-utility**：通用工具类模块，包含 IO、字符串、反射、资源扫描等实用工具。

**数据处理模块：**
- **lazycat-datasource**：数据源模块，集成 HikariCP 数据库连接池。
- **lazycat-jdbc**：JDBC 操作封装，提供数据库访问模板和工具类。
- **lazycat-mybatisflex**：集成 MyBatis-Flex ORM 框架，简化数据库操作。
- **lazycat-tx**：事务管理模块，支持声明式事务和编程式事务。

**Web 服务模块：**
- **lazycat-jdkhttp**：HTTP 服务模块，基于 JDK 自带的 `HttpServer` 提供 Web 服务。
- **lazycat-web**：WEB 模块，提供路由定义、控制器支持、静态资源管理等功能。

**应用模块：**
- **lazycat-netpipe**：轻量级内网穿透解决方案，包含服务端、客户端及可视化桌面管理端。

## 安装教程

1. **Maven 依赖**  
   在 `pom.xml` 中添加 Lazycat 的依赖。例如：

   ```xml
   <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>xyz.lwm</groupId>
                <artifactId>lazycat-parent</artifactId>
                <version>1.0-SNAPSHOT</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
   
   <dependencies>
        <dependency>
            <groupId>xyz.lwm</groupId>
            <artifactId>lazycat-web</artifactId>
        </dependency>
        ....
   </dependencies>
   ```

   根据需要添加其他模块，如 `lazycat-aop`, `lazycat-jdbc`, `lazycat-jdkhttp` 等。

2. **配置文件**  
   在 `resources` 目录下创建 `application.yml` 或 `application.properties` 文件，配置数据库连接、Web 端口等信息。

3. **启动应用**  
   创建主类并调用 `Application.start()` 启动框架：

```java
@MapperScan("com.example.mapper")
public class App {

    public static void main(String[] args) {
        Application.start();
    }

}
```

## 使用说明

### 1. 路由定义

使用 `get`, `post`, `put`, `delete` 等注解或 `Router` 原始用法定义路由：

```java
@Controller("example")
public class ExampleController implements Controllable {

   @Inject
   private ExampleService exampleService;

   @Override
   public void control(Router router) {
      // 原始用法定义路由
      router.get("teachers", ctx -> {
         List<Teacher> teachers = exampleService.getTeacherList();
         ctx.json(R.ok(teachers));
      });
      router.get("teachers/{teacherId}", ctx -> {
         String teacherId = ctx.req().getPathParam("teacherId");
         Long id = Convert.to(teacherId, Long.class);
         Teacher teacher = exampleService.getTeacherById(id);
         ctx.json(R.ok(teacher));
      });
      // 前置拦截器
      router.before("example/students/**", ctx -> {
         System.out.println("before students");
      });
   }

   // 注解定义路由
   @Get("students")
   public R<List<Student>> getStudents() {
      return R.ok(exampleService.getStudentList());
   }

   @Get("students/{id}")
   public R<Student> getStudentById(@PathParam("id") Long id) {
      return R.ok(exampleService.getStudentById(id));
   }

   @Post("students")
   public R<List<StudentVo>> getStudentsBy(@Form StudentParam param) {
      return R.ok(exampleService.getStudentsBy(param));
   }

}
```

### 2. AOP 切面

通过实现 `Aspect` 接口定义切面逻辑，并使用 `@Order` 控制执行顺序。

### 3. 数据库操作

使用 `JdbcTemplate` 进行数据库操作：

```java
@Autowired
private JdbcTemplate jdbcTemplate;

List<Map<String, Object>> users = jdbcTemplate.queryListForMap("SELECT * FROM users");
```

### 4. 事务管理

使用 `@Transactional` 注解开启事务：

```java
@Transactional
public void createUser(String name) {
    jdbcTemplate.update("INSERT INTO users(name) VALUES(?)", name);
}
```

### 5. 静态资源服务

在配置文件中注册静态资源目录：

```yaml
web:
   static:
      # 网页路径, classpath: 为 jar 包内部路径, file: 为外部路径
      location: classpath:public/
      # 网页首页
      index: index.html
```

### 6. 三方包整合

通过容器管理整合, 参考 datasource 和 mybatis flex 模块的 `Configuration` 实现。

## 扩展应用：内网穿透 (Lazycat Netpipe)

Lazycat 项目包含了一个独立的内网穿透应用 **Lazycat Netpipe**，无需复杂的穿透服务部署，程序打包极小，适合快速实现内外网穿透。

**主要特性：**
- **服务端 (Server)**：基于 Netty 实现的高性能代理服务端，管理客户端连接，转发 HTTP/TCP 数据报文，内置 Web 管理界面。
- **客户端 (Client)**：支持令牌登录服务端，建立加密隧道，支持 HTTP 和 TCP 类型的本地端口映射。
- **桌面端 (Desktop)**：基于 JavaFX 的图形化管理界面，支持账号登录、代理配置、日志查看等功能。

### 快速启动

1. **服务端部署**
   - 导入数据库脚本 `init_mysql_maria.sql`。
   - 修改 `application.yml` 配置数据库连接信息。
   - 运行 `NetpipeConsole` 主类启动服务。

2. **客户端部署**
   - 修改 `application.yml` 配置控制台地址 (`consoleAddress`) 和隧道地址 (`netpipeAddress`)。
   - 运行 `NetpipeClientApp` 启动客户端。

## 示例
[lazycat-example](lazycat-samples/lazycat-example)

初始化数据库并启动 App 后：
- API 测试: `GET http://127.0.0.1:8080/@/example/students`
- 浏览器访问: `http://127.0.0.1:8080`

## 参与贡献

欢迎参与 Lazycat 的开发和改进！你可以：

- 提交 Issue 报告 Bug 或提出建议。
- Fork 项目并提交 Pull Request。
- 编写文档或测试用例。
- 参与讨论并帮助解答问题。

请遵循 [贡献指南](.gitee/PULL_REQUEST_TEMPLATE.zh-CN.md) 提交代码。

## 特技

- **模块化设计**：各模块可独立使用，也可组合构建完整 Web 应用。
- **高性能**：基于 JDK 自带的 `HttpServer` 和 HikariCP 数据库连接池，性能优异。
- **IOC 支持**：支持插件扩展，方便集成第三方功能。
- **AOP 支持**：提供灵活的切面编程能力，支持方法拦截、注解匹配等。
- **事务管理**：支持声明式事务和编程式事务，简化事务控制。
- **MyBatis-Flex 集成**：无缝集成 MyBatis-Flex，提升数据库操作效率。
- **自动配置**：通过 `Setting` 模块实现自动配置加载，支持 YAML、Properties 等格式。
- **异常处理**：提供统一的异常处理机制，支持自定义异常处理器。
- **内网穿透**：内置 Netty 实现的轻量级内网穿透应用，满足远程办公、调试需求。

## 许可证

本项目基于 **Apache License 2.0** 协议开源。请查看 [LICENSE](LICENSE) 文件获取详细信息。

如需了解更多，请参考 [Gitee 项目页面](https://gitee.com/lwm/lazycat)。