netty-websocket-spring-boot-starter

English Docs

简介

本项目帮助你在spring-boot中使用Netty来开发WebSocket服务器，并像spring-websocket的注解开发一样简单

要求

• jdk版本为1.8或1.8+

快速开始

• 添加依赖:

    <dependency>
        <groupId>org.yeauty</groupId>
        <artifactId>netty-websocket-spring-boot-starter</artifactId>
        <version>0.13.0</version>
    </dependency>

• 在端点类上加上@ServerEndpoint注解，并在相应的方法上加上@BeforeHandshake、@OnOpen、@OnClose、@OnError、@OnMessage、@OnBinary、@OnEvent注解，样例如下：

@ServerEndpoint(path = "/ws/{arg}")
public class MyWebSocket {

    @BeforeHandshake
    public void handshake(Session session, HttpHeaders headers, @RequestParam String req, @RequestParam MultiValueMap reqMap, @PathVariable String arg, @PathVariable Map pathMap){
        session.setSubprotocols("stomp");
        if (!"ok".equals(req)){
            System.out.println("Authentication failed!");
            session.close();
        }
    }

    @OnOpen
    public void onOpen(Session session, HttpHeaders headers, @RequestParam String req, @RequestParam MultiValueMap reqMap, @PathVariable String arg, @PathVariable Map pathMap){
        System.out.println("new connection");
        System.out.println(req);
    }

    @OnClose
    public void onClose(Session session) throws IOException {
       System.out.println("one connection closed"); 
    }

    @OnError
    public void onError(Session session, Throwable throwable) {
        throwable.printStackTrace();
    }

    @OnMessage
    public void onMessage(Session session, String message) {
        System.out.println(message);
        session.sendText("Hello Netty!");
    }

    @OnBinary
    public void onBinary(Session session, byte[] bytes) {
        for (byte b : bytes) {
            System.out.println(b);
        }
        session.sendBinary(bytes); 
    }

    @OnEvent
    public void onEvent(Session session, Object evt) {
        if (evt instanceof IdleStateEvent) {
            IdleStateEvent idleStateEvent = (IdleStateEvent) evt;
            switch (idleStateEvent.state()) {
                case READER_IDLE:
                    System.out.println("read idle");
                    break;
                case WRITER_IDLE:
                    System.out.println("write idle");
                    break;
                case ALL_IDLE:
                    System.out.println("all idle");
                    break;
                default:
                    break;
            }
        }
    }

}

• 打开WebSocket客户端，连接到ws://127.0.0.1:80/ws/xxx

注解

@ServerEndpoint

当ServerEndpointExporter类通过Spring配置进行声明并被使用，它将会去扫描带有@ServerEndpoint注解的类 被注解的类将被注册成为一个WebSocket端点 所有的配置项都在这个注解的属性中 ( 如:@ServerEndpoint("/ws") )

@BeforeHandshake

当有新的连接进入时，对该方法进行回调 注入参数的类型:Session、HttpHeaders...

@OnOpen

当有新的WebSocket连接完成时，对该方法进行回调 注入参数的类型:Session、HttpHeaders...

@OnClose

当有WebSocket连接关闭时，对该方法进行回调 注入参数的类型:Session

@OnError

当有WebSocket抛出异常时，对该方法进行回调 注入参数的类型:Session、Throwable

@OnMessage

当接收到字符串消息时，对该方法进行回调 注入参数的类型:Session、String

@OnBinary

当接收到二进制消息时，对该方法进行回调 注入参数的类型:Session、byte[]

@OnEvent

当接收到Netty的事件时，对该方法进行回调 注入参数的类型:Session、Object

配置

所有的配置项都在这个注解的属性中

属性	默认值	说明
path	"/"	WebSocket的path,也可以用value来设置
host	"0.0.0.0"	WebSocket的host,"0.0.0.0"即是所有本地地址
port	80	WebSocket绑定端口号。如果为0，则使用随机端口(端口获取可见 多端点服务)
bossLoopGroupThreads	0	bossEventLoopGroup的线程数
workerLoopGroupThreads	0	workerEventLoopGroup的线程数
useCompressionHandler	false	是否添加WebSocketServerCompressionHandler到pipeline
optionConnectTimeoutMillis	30000	与Netty的ChannelOption.CONNECT_TIMEOUT_MILLIS一致
optionSoBacklog	128	与Netty的ChannelOption.SO_BACKLOG一致
childOptionWriteSpinCount	16	与Netty的ChannelOption.WRITE_SPIN_COUNT一致
childOptionWriteBufferHighWaterMark	64*1024	与Netty的ChannelOption.WRITE_BUFFER_HIGH_WATER_MARK一致,但实际上是使用ChannelOption.WRITE_BUFFER_WATER_MARK
childOptionWriteBufferLowWaterMark	32*1024	与Netty的ChannelOption.WRITE_BUFFER_LOW_WATER_MARK一致,但实际上是使用 ChannelOption.WRITE_BUFFER_WATER_MARK
childOptionSoRcvbuf	-1(即未设置)	与Netty的ChannelOption.SO_RCVBUF一致
childOptionSoSndbuf	-1(即未设置)	与Netty的ChannelOption.SO_SNDBUF一致
childOptionTcpNodelay	true	与Netty的ChannelOption.TCP_NODELAY一致
childOptionSoKeepalive	false	与Netty的ChannelOption.SO_KEEPALIVE一致
childOptionSoLinger	-1	与Netty的ChannelOption.SO_LINGER一致
childOptionAllowHalfClosure	false	与Netty的ChannelOption.ALLOW_HALF_CLOSURE一致
readerIdleTimeSeconds	0	与IdleStateHandler中的readerIdleTimeSeconds一致，并且当它不为0时，将在pipeline中添加IdleStateHandler
writerIdleTimeSeconds	0	与IdleStateHandler中的writerIdleTimeSeconds一致，并且当它不为0时，将在pipeline中添加IdleStateHandler
allIdleTimeSeconds	0	与IdleStateHandler中的allIdleTimeSeconds一致，并且当它不为0时，将在pipeline中添加IdleStateHandler
maxFramePayloadLength	65536	最大允许帧载荷长度
useEventExecutorGroup	true	是否使用另一个线程池来执行耗时的同步业务逻辑
eventExecutorGroupThreads	16	eventExecutorGroup的线程数
sslKeyPassword	""(即未设置)	与spring-boot的server.ssl.key-password一致
sslKeyStore	""(即未设置)	与spring-boot的server.ssl.key-store一致
sslKeyStorePassword	""(即未设置)	与spring-boot的server.ssl.key-store-password一致
sslKeyStoreType	""(即未设置)	与spring-boot的server.ssl.key-store-type一致
sslTrustStore	""(即未设置)	与spring-boot的server.ssl.trust-store一致
sslTrustStorePassword	""(即未设置)	与spring-boot的server.ssl.trust-store-password一致
sslTrustStoreType	""(即未设置)	与spring-boot的server.ssl.trust-store-type一致
corsOrigins	{}(即未设置)	与spring-boot的@CrossOrigin#origins一致
corsAllowCredentials	""(即未设置)	与spring-boot的@CrossOrigin#allowCredentials一致

通过application.properties进行配置

所有参数皆可使用${...}占位符获取application.properties中的配置。如下：

• 首先在@ServerEndpoint注解的属性中使用${...}占位符

@ServerEndpoint(host = "${ws.host}",port = "${ws.port}")
public class MyWebSocket {
    ...
}

• 接下来即可在application.properties中配置

ws.host=0.0.0.0
ws.port=80

自定义Favicon

配置favicon的方式与spring-boot中完全一致。只需将favicon.ico文件放到classpath的根目录下即可。如下:

src/
  +- main/
    +- java/
    |   + 


    +- resources/
        +- favicon.ico

自定义错误页面

配置自定义错误页面的方式与spring-boot中完全一致。你可以添加一个 /public/error 目录，错误页面将会是该目录下的静态页面，错误页面的文件名必须是准确的错误状态或者是一串掩码,如下：

src/
  +- main/
    +- java/
    |   + 


    +- resources/
        +- public/
            +- error/
            |   +- 404.html
            |   +- 5xx.html
            +- <other public assets>

多端点服务

• 在快速启动的基础上，在多个需要成为端点的类上使用@ServerEndpoint、@Component注解即可
• 可通过ServerEndpointExporter.getInetSocketAddressSet()获取所有端点的地址
• 当地址不同时(即host不同或port不同)，使用不同的ServerBootstrap实例
• 当地址相同,路径(path)不同时,使用同一个ServerBootstrap实例
• 当多个端点服务的port为0时，将使用同一个随机的端口号
• 当多个端点的port和path相同时，host不能设为"0.0.0.0"，因为"0.0.0.0"意味着绑定所有的host

---

更新日志

0.8.0

• 自动装配

0.9.0

• 通过@PathVariable支持RESTful风格中获取参数
• 通过@RequestParam实现请求中query的获取参数
• 移除原来的ParameterMap,用@RequestParam MultiValueMap代替
• 新增 @BeforeHandshake 注解，可在握手之前对连接进行关闭
• 在@BeforeHandshake事件中可设置子协议
• 去掉配置端点类上的 @Component
• 更新Netty版本到 4.1.44.Final

0.9.1

• 修复bug：当使用@RequestParam MultiValueMap时获取的对象为null
• 更新Netty版本到 4.1.45.Final

0.9.2

• 兼容 0.8.0 以下版本，可以手动装配ServerEndpointExporter对象

0.9.3

• 修复bug：当没有 @BeforeHandshake时会出现空指针异常

0.9.4

• 修复bug：当没有 @BeforeHandshake时 OnOpen中的Session为null.

0.9.5

• 修复bug：OnError事件中的Throwable为null.

0.10.0

• 修改bossLoopGroupThreads默认值为1
• 支持通过配置useEventExecutorGroup让同步且耗时的业务逻辑在EventExecutorGroup中执行，防止I/O线程被耗时的任务阻塞
• 支持SSL
• 支持跨域
• 更新Netty版本到 4.1.59.Final

0.11.0

• 当ServerEndpoint类被cglib代理时(如aop增强)，仍能正常运行

0.12.0

• @EnableWebSocket增加scanBasePackages属性
• @ServerEndpoint不再依赖@Component
• 更新Netty版本到 4.1.67.Final

0.13.0

• 修复了无法进行WebSocket压缩的问题
• 升级支持spring-boot3
• 响应头带上前端的Sec-WebSocket-Protocol
• 关闭连接时，会先发送bye命令，而不是直接close
• 更新Netty版本到 4.1.118.Final