netty-websocket-spring-boot-starter

中文文档 (Chinese Docs)

About

netty-websocket-spring-boot-starter поможет вам разработать сервер WebSocket с использованием Netty в spring-boot. Разрабатывать легко, используя аннотации, подобные spring-websocket.

Требования

• jdk версии 1.8 или 1.8+.

Быстрый старт

• Добавьте зависимости:

    <dependency>
        <groupId>org.yeauty</groupId>
        <artifactId>netty-websocket-spring-boot-starter</artifactId>
        <version>0.12.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, сканирует конечные точки WebSocket, которые аннотируются с помощью @ServerEndpoint. Бины, аннотированные с помощью @ServerEndpoint, регистрируются как конечная точка WebSocket. Все конфигурации находятся внутри этой аннотации (например, @ServerEndpoint("/ws"))

@BeforeHandshake

Когда соединение принято, метод, аннотированный с помощью @BeforeHandshake, будет вызван. Классы, которые внедряются в метод: Session, HttpHeaders...

@OnOpen

Когда подключение к WebSocket завершено, метод, аннотированный с помощью @OnOpen, будет вызван. Классы, которые вводятся в метод: Session, HttpHeaders...

@OnClose

Когда соединение WebSocket закрыто, метод, аннотированный с помощью @OnClose, будет вызван. Класс, который вводится в метод: Session.

@OnError

Когда соединение WebSocket выбрасывает Throwable, метод, аннотированный с помощью @OnError, будет вызван. Классы, которые вводятся в метод: Session, Throwable.

@OnMessage

Когда соединение WebSocket получает сообщение, вызывается метод, аннотированный с @OnMessage.

В этот метод будут внедрены следующие классы: Session, String.

@OnBinary

Когда соединение WebSocket получает двоичные данные, вызывается метод, аннотированный с @OnBinary.

В этот метод будут внедрены следующие классы: Session, byte[].

@OnEvent

Когда соединение WebSocket получает событие Netty, вызывается метод, аннотированный с @OnEvent.

В этот метод будут внедрены следующие классы: Session, Object.

Конфигурация

Все конфигурации настраиваются в свойствах @ServerEndpoint.

Настройка через 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

Пользовательская настройка Фавикон

Настройка фавикона происходит так же, как и в spring-boot. Если файл favicon.ico находится в корне пути к классам, он будет автоматически использоваться в качестве фавикона приложения. Пример:

src/
  +- main/
      +- java/
      |   + исходный код
      +- resources/
          +- favicon.ico

Пользовательские страницы ошибок

Настроить фавикон можно так же, как в spring-boot. Можно добавить файл в папку /public/error. Имя страницы ошибки должно соответствовать точному коду состояния или маске серии. Пример:

src/
  +- main/
      +- java/
      |   + <исходный код>
      +- resources/
          +- public/
              +- error/
              |   +- 404.html
              |   +- 5xx.html
              +- другие публичные активы

Несколько конечных точек

• На основе Quick-Start используйте аннотации @ServerEndpoint и @Component в классах, которые должны стать конечной точкой.
• Вы можете получить все адреса сокетов в ServerEndpointExporter.getInetSocketAddressSet().
• Когда есть разные адреса (разные хосты или разные порты) в WebSocket, они будут использовать разные экземпляры ServerBootstrap.
• Если адреса совпадают, но путь отличается, они будут использовать один и тот же экземпляр ServerBootstrap.
• При нескольких портах конечной точки, равных нулю, они будут использовать один и тот же случайный порт.
• При одинаковых портах нескольких конечных точек нельзя установить хост как «0.0.0.0», поскольку это означает привязку ко всем адресам.

Журнал изменений

0.8.0

• Автоконфигурация.

0.9.0

• Поддержка RESTful с помощью @PathVariable.
• Получение параметра с помощью @RequestParam из запроса.
• Удаление ParameterMap, вместо @RequestParam MultiValueMap.
• Добавление аннотации @BeforeHandshake, вы можете закрыть соединение перед рукопожатием.
• Установка подпротокола в событии @BeforeHandshake.
• Удаление @Component на классе конечной точки.
• Обновление версии Netty до 4.1.44.Final.

0.9.1

• Исправлена ошибка: было значение null при использовании @RequestParam MultiValueMap для получения значения.
• Обновлена версия Netty до 4.1.45.Final.

0.9.2

• Существуют совместимые версии ниже 0.8.0, которые могут настраивать ServerEndpointExporter вручную.

0.9.3

• Исправлена ошибка: при отсутствии @BeforeHandshake появлялось исключение NullPointerException.

0.9.4

• Исправлена ошибка: при отсутствии @BeforeHandshake Session в OnOpen был равен нулю.

0.9.5

• Исправлена ошибка: Throwable в событии OnError был нулевым.

0.10.0

• Изменено значение по умолчанию bossLoopGroupThreads на 1.
• Поддерживается настройка useEventExecutorGroup для запуска синхронной и ресурсоёмкой бизнес-логики в EventExecutorGroup, чтобы поток ввода-вывода не блокировался ресурсоёмкими задачами.
• Поддерживается SSL.
• Поддерживается CORS.
• Обновлено Netty до версии 4.1.49.Final.

0.11.0

• Когда класс ServerEndpoint проксируется CGLIB (как при улучшении AOP), он всё ещё работает.

0.12.0

• В @enableWebSocket добавлен атрибут scanBasePackages.
• @serverEndpoint больше не зависит от @Component.
• Обновлено Netty до версии 4.1.67.Final.