Han 框架

企业级Java快速开发框架

欢迎使用 Han 框架

Han 框架是一个基于 BESP 开发的企业级Java快速开发框架，提供了简洁的API和丰富的功能，帮助开发者快速构建高质量的Web应用。

当前最新版本：1.0.3.4-SNAPSHOT

🚀

快速开发

简化的配置和API，让开发者专注于业务逻辑，提高开发效率。

🛡️

安全可靠

内置安全机制，提供完善的权限控制和数据校验功能。

🔌

插件扩展

灵活的插件机制，支持自定义扩展和第三方集成。

⚡

高性能

优化的底层实现，提供出色的性能表现和响应速度。

1. 快速上手

1.1 创建项目

1.1.1 使用 Maven 创建项目

使用 Maven 创建一个标准的 Java Web 项目：

使用 Maven 创建项目

1.2 引入依赖

创建好 Maven 项目后，需要在 pom.xml 文件中引入 Han 框架的依赖。

当前最新版本为 1.0.3.4-SNAPSHOT，你可以根据需要替换为最新版本。

当前为公司内部使用，未发布到 Maven 中央仓库，因此需要添加公司内部 Maven 仓库的配置。建议使用本地maven仓库，以及增加阿里云maven仓库。

公司内部 Maven 仓库配置：

                    <repositories>
                        <!-- Han 自身的仓库 -->
                        <repository>
                            <id>bespmaven</id>
                            <url>http://172.168.6.101:8081/repository/maven-public</url>
                            <releases>
                                <enabled>true</enabled>
                            </releases>
                            <snapshots>
                                <enabled>true</enabled>
                            </snapshots>
                        </repository>
                        <repository>
                            <id>alimaven</id>
                            <name>aliyun maven</name>
                            <url>https://maven.aliyun.com/repository/public</url>
                        </repository>
                        </repositories>

框架依赖配置：

                    
                        <dependencies>
                            <dependency>
                                <groupId>com.besp</groupId>
                                <artifactId>han-all</artifactId>
                                <version>1.0.3.4-SNAPSHOT</version>
                            </dependency>
                            <!-- MySql 驱动 -->
                            <dependency>
                                <groupId>com.mysql</groupId>
                                <artifactId>mysql-connector-j</artifactId>
                                <version>8.2.0</version>
                            </dependency>
                            <!-- 数据库连接池 -->
                            <dependency>
                                <groupId>com.alibaba</groupId>
                                <artifactId>druid</artifactId>
                                <version>1.2.22</version>
                            </dependency>
                            <!-- Log4j2 核心 API -->
                            <dependency>
                                <groupId>org.apache.logging.log4j</groupId>
                                <artifactId>log4j-api</artifactId>
                                <version>2.17.2</version> <!-- 使用稳定版本 -->
                            </dependency>
                            <!-- Log4j2 核心实现 -->
                            <dependency>
                                <groupId>org.apache.logging.log4j</groupId>
                                <artifactId>log4j-core</artifactId>
                                <version>2.17.2</version>
                            </dependency>
                        </dependencies>

1.3 配置文件

创建 Han 框架的配置文件，通常命名为 HanConfig.java，继承自 HanConfig 类：

                    
                        public class DemoConfig extends HanConfig {
                            @Override
                            public void configRoute(Routes me) {
                                // 配置路由
                                me.add("/", IndexController.class);
                            }

                            @Override
                            public void configPlugin(Plugins me) {
                                // 配置插件
                                DruidPlugin druidPlugin = new DruidPlugin("jdbc:mysql://localhost:3306/demo", "root", "password");
                                me.add(druidPlugin);

                                ActiveRecordPlugin arp = new ActiveRecordPlugin(druidPlugin);
                                me.add(arp);

                                activeRecordPlugin.setShowSql(false);
                                TableAnnotationScanner.scan(activeRecordPlugin,"com.besp.han.entity.model");
                            }
                        }

1.4 启动项目

创建启动类，使用 ServerLauncher.start() 方法启动应用。Han框架提供了多种启动方式，您可以根据需要选择适合的方式：

1.4.1 基础启动方式

最基本的启动方式，只需指定端口号和配置类：

                    
                        public class Main {
                            public static void main(String[] args) {
                                ServerLauncher.start(8088, Config.class);
                            }
                        }

1.4.2 使用配置文件的启动方式

如果需要使用配置文件，可以指定配置文件路径：

                    
                        public class Main {
                            public static void main(String[] args) {
                                ServerLauncher.start(8088, Config.class, "application.properties");
                            }
                        }

使用环境配置文件时，需要在配置文件中配置属性 app.env，例如：

app.env=dev

然后创建对应的环境配置文件，如 application-dev.properties。

1.4.3 高级配置方式

如果需要更精细的控制服务器配置，可以使用回调函数进行高级配置：

                    
                        public class Main {
                            public static void main(String[] args) {
                                ServerLauncher.start(8088, Config.class, "application.properties", server -> {
                                    CommonConfig.setDebug(false);
                                    server.setHost("0.0.0.0"); // 设置服务器绑定的主机地址
                                    server.setDevMode(true); // 设置开发模式
                                    server.setContextPath("webapp"); // 设置Web应用上下文路径
                                    server.setResourcePath("webapp"); // 设置Web应用的资源目录
                                    server.setGzipEnable(true); // 设置是否启用GZIP压缩
                                    server.config(undertowConfig -> {
                                        undertowConfig.setResourcePath("webapp"); // 配置静态资源目录
                                        undertowConfig.setContextPath("/myapp"); // 设置Web应用上下文路径
                                        undertowConfig.setServerName("BESP.Han" + CommonConfig.VERSION);
                                        undertowConfig.setWorkerThreads(20); // 设置工作线程数
                                        undertowConfig.setIoThreads(20); // 设置IO线程数
                                        undertowConfig.setGzipEnable(true); // 设置是否启用GZIP压缩
                                        undertowConfig.setGzipLevel(1); // 设置GZIP压缩级别
                                        undertowConfig.setHttp2Enable(true); // 设置是否启用HTTP/2协议
                                        undertowConfig.setHttpDisable(true); // 设置是否禁用HTTP/1.1协议
                                        undertowConfig.setHttpToHttps(true); // 设置是否将HTTP请求重定向到HTTPS
                                        undertowConfig.setHttpToHttpsStatusCode(301); // 设置HTTP重定向到HTTPS时的状态码
                                        undertowConfig.setSessionTimeout(30); // 设置会话超时时间（单位：秒）
                                        undertowConfig.setSessionHotSwap(true); // 设置是否启用会话热交换
                                        undertowConfig.setHotSwapResolver(new HotSwapResolver(new String[]{"webapp"})); // 设置会话热交换解析器
                                    });
                                });
                            }
                        }

1.5 PropKit 读取配置

PropKit工具类用来读取外部键值对配置文件，PropKit可以极度方便地在系统任意时空使用，配置文件的格式如下：

                    
                        userName=james
                        email=no-reply@jfinal.com
                        devMode=true
基本使用示例

如下是 PropKit 代码示例：

                    
                        String userName = PropKit.get("userName");
                        String email = PropKit.get("email");
                        Boolean devMode = p.getBoolean("devMode");

加载配置文件的方式

PropKit 提供了多种加载配置文件的方式：

1. 在系统任意时空使用
                    
                        // 加载 application.properties 文件
                        Prop p = PropKit.use("application.properties");
2. 启动项目时加载配置文件
                    
                        public static void main(String[] args) {
                            ServerLauncher.start(8088, Config.class, "application.properties");
                        }
3. 分环境配置

在不同环境下，我们可能需要使用不同的配置文件，例如开发环境、测试环境、生产环境等。PropKit 提供了一种简单的方式来实现分环境配置。以下以开发dev环境为例：

  1. 运行项目时加载主配置文件application.properties
                    
                        public static void main(String[] args) {
                            ServerLauncher.start(8088, Config.class, "application.properties");
                        }
  1. 根据环境加载额外的配置文件在主配置文件中配置环境变量app.env
                    
                        # application.properties
                            app.env=dev
  1. 创建环境配置文件application-dev.properties
更多用法
1. 按照功能分类配置文件

PropKit 支持按照功能分类配置文件，例如数据库配置、邮件配置、缓存配置等。我们可以为每个功能创建一个独立的配置文件，例如application-db.properties、application-mail.properties、application-cache.properties（db.properties、mail.properties、cache.properties）等。

以db.properties为例：

                    
                        db.url=jdbc:mysql://localhost:3306/test
                        db.password=123456
                        db.username=root

在配置类中加载：

                    
                        public class Config extends HanConfig {
                            @Override
                            public void configConstant(Constants constants) {
                                PropKit.append("db.properties");//如果使用PropKit.use("db.properties")，则会覆盖主配置文件中的配置
                                super.configConstant(constants);
                            }
                        }
2. 分环境的功能配置文件

如果db.properties也需要分环境配置，我们可以在代码中添加如下判断：

                    
                        public class Config extends HanConfig {
                            @Override
                            public void configConstant(Constants constants) {
                                PropKit.append("db.properties");//如果没有共同配置这行可以省略
                                String configFileName = ServerLauncher.getDynamicConfigFileName("db.properties", PropKit.getEnv());//此处的db.properties主要是为了配合环境变量app.env=dev获取分环境的db-dev.properties文件名
                                PropKit.append(configFileName);
                                super.configConstant(constants);
                            }
                        }

2. HanConfig 配置

2.1 概述

HanConfig 是 Han 框架的核心配置类，负责配置路由、插件、常量等框架核心功能。注意路由自动扫描时，会拖慢项目启动速度

2.2 configRoute 方法 - 路由配置

configRoute 方法用于配置应用的路由规则，决定请求如何映射到控制器。

2.2.1 常用配置

基本路由配置示例：

@Override
public void configRoute(Routes me) {
    // 添加路由，参数分别为：访问路径、控制器类
    me.add("/", IndexController.class);
    me.add("/user", UserController.class);
    me.add("/blog", BlogController.class);
}

2.2.2 路由扫描

Han 框架支持路由自动扫描，简化路由配置：

@Override
public void configRoute(Routes me) {
    // 扫描指定包下的所有控制器类
    me.scan("com.besp.han.controller");
}

2.2.3 手工配置

手工配置路由可以更精确地控制请求映射：

                    
                        @Override
                        public void configRoute(Routes me) {
                            // 添加路由组
                            me.add("/admin", AdminController.class, "/admin");
                            me.add("/api", ApiController.class, "/api");
                        }

2.2.4 极简路由规则

Han 框架支持极简路由配置，自动根据控制器类名生成路由：

                    @Override
                        public void configRoute(Routes me) {
                            // 启用极简路由规则
                            me.setBaseViewPath("/view");
                            me.scan("com.besp.han.controller");
                        }

2.2.5 路由拆分模块化

对于大型项目，可以将路由拆分为多个模块：

                    
                        // 定义后台路由模块
                        public class AdminRoutes extends Routes {
                            @Override
                            public void config() {
                                add("/user", UserController.class);
                                add("/role", RoleController.class);
                            }
                        }

                        // 在主配置中添加模块路由
                        @Override
                        public void configRoute(Routes me) {
                            me.add("/", IndexController.class);
                            me.add(new AdminRoutes());
                        }

2.3 configPlugin 方法 - 插件配置

configPlugin 方法用于配置框架插件，如数据库连接池、ORM 框架等：

                    
                        @Override
                        public void configPlugin(Plugins me) {
                            // 配置数据库连接池插件
                            DruidPlugin druidPlugin = new DruidPlugin("jdbc:mysql://localhost:3306/han", "root", "password");
                            me.add(druidPlugin);

                            // 配置 ActiveRecord 插件
                            ActiveRecordPlugin activeRecordPlugin = new ActiveRecordPlugin(druidPlugin);
                            me.add(activeRecordPlugin);

                            // 配置日志插件
                            Log4jPlugin log4jPlugin = new Log4jPlugin("log4j.properties");
                            me.add(log4jPlugin);
                        }

3. 数据库操作

Han 框架内置了 ActiveRecord 模式，简化数据库操作。

4. 模板引擎

Han 框架支持多种模板引擎，如 JSP、FreeMarker、Velocity 等。

5. 文件上传

Han 框架提供了便捷的文件上传功能。

6. 缓存机制

Han 框架内置了缓存机制，提高应用性能。

7. 安全框架

Han 框架内置了安全机制，提供权限控制和数据校验。

8. 事务管理

Han 框架支持声明式事务管理。

9. 日志系统

Han 框架集成了多种日志框架，方便日志管理。

10. 框架特性

  • 简洁的 API：提供了简洁直观的 API，降低学习成本
  • 强大的路由：支持 RESTful 风格的路由配置
  • 数据库支持：内置 ActiveRecord 模式，支持多种数据库
  • 模板引擎：支持多种模板引擎，如 JSP、FreeMarker、Velocity 等
  • 插件机制：灵活的插件扩展机制，支持自定义插件
  • 安全框架：内置安全机制，提供权限控制和数据校验
  • 文件上传：支持多文件上传和文件管理
  • 缓存支持：内置缓存机制，提高应用性能
  • 事务管理：支持声明式事务管理
  • 日志系统：集成多种日志框架，方便日志管理

11. 文档

详细的框架文档可以帮助你更好地了解和使用 Han 框架。

查看完整文档 下载 PDF 文档

12. API 参考

Han 框架提供了完整的 API 文档，帮助开发者快速了解和使用框架的各项功能。

查看 API 文档