HServer文档

序言

HServer是什么

HServer是一个简单高效的web库基于Netty开发.它不遵循servlet规范.可以理解为mini版本的springboot的版本.使用它开发可以在初期获得很大的QPS。会随着业务变化QPS慢慢降低.它给我们的起点很高,剩下就是我们自己高效运用即可. 如果你正在使用该框架建议加入QQ群,我们可以更好的交流 QQ交流群:1065301527

Hserver的理念

极简、高性能、分布式

极简 代码只有200多KB 更多的案例会在gitee.com/Hserver 的组下给出案例源码.

高性能 使用Netty网络库作为核心,比起传统的web容器性能高数十倍.

分布式 支持RPC模式,可以实现分布式调用.

使用该框架的公司

深圳市快读科技,深圳市聚美良品科技,广州家庭医生在线,上海互软集团,深圳市巨和网络...

原理与流程

原理

注解认识

根据上面的例子,大家应该理解是非常容易的,和springboot很相似。接下我们了解下注解这里,注解只是做简单描述,具体使用在后面的章节会演示出来

注解描述信息
@Bean将当前类加入IOC中,类似spring的@Component注解,可以名字放入ioc 如@Bean("Test")
@Autowired将ioc里的某个对象注入给某个字段,和spring用法类似,可以名字注入ioc 如@Autowired("Test")
@RequestMapping这个和springmvc的注解很相似
@GET请求类型注解类似@GetMapping
@POST请求类型注解
@PUT请求类型注解
@HEAD请求类型注解
@PATCH请求类型注解
@DELETE请求类型注解
@OPTIONS请求类型注解
@CONNECT请求类型注解
@TRACE请求类型注解
@Order排序注解 值越小,优先级越高 (FilterAdapter, GlobalException, InitRunner,ReInitRunner, ResponseAdapter,ProtocolDispatcherAdapter,RpcAdapter,ServerCloseAdapter) 这些子类支持排序
@Configuration配置注解,这个和springboot有相似之处(这个类中可以注入 @NacosClass,@NacosValue,@Value,@ConfigurationProperties这些注解产生的对象)
@ConfigurationProperties配置类,和springboot相似 将Properties转为对象放入IOC
@Controller标记类为控制器 @Controller 参数可以指定一个URL 和 一个名字
@HookAOP操作使用
@RequiresPermissions权限注解
@RequiresRoles角色注解
@ResourceRPC对象的注入使用.可以按名字注入
@RpcService标记一个Service是一个RPC服务,可以给一个名字
@Sign作用在控制器方法上.可以根据他来实现sign检查当然你可以用拦截器自己处理
@Task定时器使用,具体看例子
@Track链路跟踪注解,如果你想检查某些方法的耗时或者其他监控,可以用这个注解,具体看下面的介绍
@Value用来把Properties字段注入到类的字段里
@WebSocketwebsocket注解,具体看下面的介绍
@QueueListener标记一个类为队列处理类
@QueueHandler标记一个方法为队列处理方法
@AssertFalse字段为必须为false
@AssertTrue字段为必须为true
@Length字段CharSequence 类型的长度必须是 length 长
@Max字段值必须大于这个值,number
@Min字段值必须小于这个值,number
@NotBlank字段不能为null同时不是 ""
@NotEmptyCharSequence 集合 map 数组 不是null 长度或者size 大于0
@NotNull字段不能为Null
@Null字段必须为Null
@Pattern字段CharSequence 必须满足这个正则
@Size字段 CharSequence 集合 map 数组必须在这范围内
@ApiImplicitParamsAPI生成标记
@ApiImplicitParamAPI生成标记

 

常见用例

 

 

快速开始

1.建立一个maven项目,导入依赖

 

2.建立一个java包,如 com.test

3.建立一个主函数

4.建立一个控制器

5.运行主函数,访问8888端口即可

文件上传下载

全局request,response获取

Hook操作

提供hook注解,它只能Hook在ioc中存在的bean对象. hook功能除了hook指定的类所有方法,还能hook注解,只要包含这个注解的类都会被hook.

 

上面测试例子都是HServer Test包里的Test1文件中,有兴趣的可以去运行体验哈

Filter拦截器

拦截器的使用主要是用在跨域等操作,或者其他拦截,

接口可以实现多个 ,但是得只要有输出将会中断链式调用.

 

响应拦截器

 

定时器

 

WebSocket

需要被@WebSocket标注同时给一个连接地址,最后实现WebSocketHandler接口, Ws类定义了简单的发送方法,如果有其他的业务操作,可以获取ChannelHandlerContext,进行操作

ws类提供了Netty原始的HttpRequest对象,你可以自由处理,同时提供了 query 函数,帮助你快速查找到websocket URL的参数

Mqtt

请继承MqttAdapter类 并用@Bean 标记 其他操作可以重写父类的一些方法

全局异常处理

类必须要被@Bean注解,同时实现GlobalException接口.

异常接口可以实现多个 ,但是得只要有输出将会中断链式调用.

服务器启动完成执行的方法

类必须要被@Bean注解,同时实现InitRunner接口,

服务器IOC重新初始化执行的方法

类必须要被@Bean注解,同时实现ReInitRunner接口,

服务器关闭回调执行的方法

类必须要被@Bean注解,同时实现ServerCloseAdapter接口,

鉴权认证相关操作

@RequiresPermissions

@RequiresRoles

@Sign

请使用相关注解对控制器的方法做标记,这样在执行到被注解标记的方法就会执行下面的相关方法 List routerPermissions = PermissionAdapter.getRouterPermissions(); 通过上面的代码可以获取到所有标记的注解,他可以干嘛? 同步后台数据库里面的权限,后台管理面里面可以动态给角色分配权限。 自己做一个下拉选择列表,创建角色分配权限时,多选即可。

RPC调用

hserver 提供了RpcAdapter类,详细看代码里的实现 支持自定义注册中心完成RPC 目前提供了两种模式 第一种默认模式不需要注册中心 第二种模式是需要Nacos注册中心. 编码过程中没有什么差异 主要差异是在配置上. 文档我怕讲不清楚,详情看 test-rpc-*

ApiDoc生成功能

关于这个api文档生成目前只是一个简洁版,在未来日子里相信会变得更好

第一步

第二步

第三步

HServer提供了一个叫ApiDoc的类,对他进行实例化,就可以获取到生成文档的对象,你可以进行自己的文档生成定制,

或者使用HServer提供 的简洁版本的文档模板 hserver_doc.ftl 需要将依赖里的这个文件copy到你的模板里面.

下面就是例子,ApiDoc的构造器可以传入class类型,或者传入String类型,主要目的是进行扫包,可以直接传入包名,或者传入class,然后获取包名

AB测试

 

消息队列的使用

队列核心技术使用的是disruptor

生产者

消费者定义

我们在使用该注解时,会考虑到队列的数据 重复消费还是不重复消费。我们可以指定 type类型就可以了,默认是不重复消费的

消费方法定义,消费者数量默认是1,我们可以定义多个,通过size参数处理

level级别,当里面出现两个 我们指定级别实现 顺序消费.

我们可以通过消费类型和消费级别可以自由组合,多种方案

 

动态Queue使用方法

 

Track跟踪

使用动态字节码技术,在初始化对需要跟踪的方法进行,字节码处理,可以跟踪任意方法 1.在任意方法上添加,@Track 注解:例如

2.实现TrackAdapter接口,并在类上用 @Bean标识

自定义JSON序列化

 

自定义协议

HServer实现的是同端口多协议处理方式,如果有需要还可以构建其他协议。 构建协议特点,需要包含包头用于区分协议,选择对应的解码器处理。 HServer默认集成 websocket http rpc mqtt websocketmqtt协议, 如果你还有更多的需求,可以在加协议。或者重写HServer提供的协议。 headers字节,最多提取头512个字节,所以定义头一定不要过长,不要过线.

比如重写Http协议;

这里需要注意一点的是@Order(3)注解,由于WebSocketMqtt是基于Http协议的,所以先判断的WebSocketMqtt协议,WebSocketMqtt为@Order(2),返回true者不向下执行。 Order值越越小,优先级越高。

如何自定义协议呢?比如实现一个MQTT或者其他自定义的协议

这里需要注意他的头包含GET 但是http协议也是包含GET,所以这个协议一定要优先于HTTP检查。自己在定义协议的时候,尽量采用特殊字符作为消息头,用来区分协议。 剩下的操作就和Netty原生开发方案类似了,定义编码解码器,最后到自己的Handler处理器里。 非常重要一点,一定不要在这里面有阻塞操作,不然会卡的批爆。切记切记。

 

单元测试

  1. web 服务测试
  1. 非web服务测试

 

自定义Banner

resources文件夹里存放一个banner.txt 里面放入你图标就可以了.

app.properties配置文件说明

环境切换

在app.properties文件中添加,env=dev

配置文件app-dev.properties也会加载在里面

或者java -jar -Denv=dev xxx.jar 启动参数指定env

SSL支持

在app.properties配置文件添加

#举例:nginx版本的证书下载可能会得到 (xxx.pem或者xxx.cert) xxx.key #注意下载的证书中 key文件需要转换成 pk8 文件 #因为netty4不支持pkcs12格式的私钥, 所以需要将私钥转换成pkcs8格式. #openssl pkcs8 -in my.key -topk8 -out my.pk8 #转换过程需要你设置一个密码.

方案一:

 

方案二:

 

然后监听443端口,你就能https 访问了。

定时器线程数

 

BOSS线程组大小

 

worker线程组大小

日志设置

全局流量整形

业务线程数

提示:使用了业务线程,整体QPS会有降低、 优点:可以处理更多的并发耗时任务 缺点:增加线程切换

消息体大小,可以用于文件上传限制大小

EPOLL模式

配置中心

配置类注解

  1. app.properties文件内容
  1. 配置
  1. 使用

##

 

参数校验器

注解描述
@AssertFalse字段为必须为false
@AssertTrue字段为必须为true
@Length字段CharSequence 类型的长度必须是 length 长
@Max字段值必须大于这个值,number
@Min字段值必须小于这个值,number
@NotBlank字段不能为null同时不是 ""
@NotEmptyCharSequence 集合 map 数组 不是null 长度或者size 大于0
@NotNull字段不能为Null
@Null字段必须为Null
@Pattern字段CharSequence 必须满足这个正则
@Size字段 CharSequence 集合 map 数组必须在这范围内

 

插件开发

  1. 添加POM依赖 scope 设置为 provided
  1. 实现接口PluginAdapter
  1. spi处理
  1. 参考插件 https://gitee.com/HServer/hserver-plugs-beetlsql,或者在厂库里去找关于Plugin的代码。后期的插件会越来越多

细节和注意事项

在Controller层中定义的方法

参数可以是基础数据类型或者bean对象,或者HttpRequest,HttpResponse,(需要是这个包下面的top.hserver.core.interfaces.的对象)当不是表单提交时,可以通过httpRequest.getRawData(),获取到请求的数据。默认也会尝试将内容转成对象

打包jar

Main函数类上添加@HServerBoot 注解用于标记是启动类。 只需要在pom.xml 添加打包命令即可,打包之前记得 clean

静态资源路径

模板路径

查看相关实例代码