# TurboWeb-SpringBoot

**Repository Path**: turboweb/turboweb-springboot

## Basic Information

- **Project Name**: TurboWeb-SpringBoot
- **Description**: 该仓库是 TurboWeb 与 SpringBoot 整合的起步依赖包，通过引入该包，开发者可以在 SpringBoot 项目中轻松使用 TurboWeb 提供的高性能 HTTP/HTTPS 服务、路由管理、中间件、网拦截器、WebSocket 和嵌入式网关功能。它实现了自动装配，支持注解式控制器和声明式路由，让开发者无需手动启动服务器或注册组件，即可在 SpringBoot 环境下快速构建高性能
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/turboweb/turboweb-springboot
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2025-07-29
- **Last Updated**: 2025-11-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
 <img src="logo.png" alt="">
</p>

## 快速开始

### 引入相关依赖

首先创建一个SpringBoot工程，并在项目的`pom.xml`中引入TurboWeb的起步依赖。该依赖将自动集成TurboWeb的核心功能，并支持与SpringBoot的无缝整合。

```xml
<dependency>
    <groupId>io.gitee.turboweb</groupId>
    <artifactId>turboweb-spring-boot-starter</artifactId>
    <version>2.2.0</version>
</dependency>
```

> **说明**：通过该起步依赖，开发者无需手动配置TurboWeb的服务启动、路由管理器、中间件等核心组件，SpringBoot容器会自动装配并管理。

### 编写一个Controller接口

TurboWeb整合SpringBoot之后，控制器的使用非常类似于Spring MVC，只需在类上添加 `@TurboController` 注解即可被框架自动扫描并注册。

```java
package top.heimi.controller;

import top.turboweb.boot.anno.TurboController;
import top.turboweb.commons.anno.Get;
import top.turboweb.commons.anno.RequestPath;

@TurboController
@RequestPath
public class HelloController {

    @Get
    public String hello() {
        return "hello world";
    }
}
```

启动SpringBoot应用后，通过浏览器访问对应的URL即可看到 `"hello world"` 输出。

> **说明**：
>
> - `@TurboController`：标识控制器类，将其纳入TurboWeb路由管理。
> - `@RequestPath`：用于定义路由前缀，可省略，默认为类路径名。
> - `@Get`：声明HTTP GET请求方法。

## TurboWeb的配置项

TurboWeb整合SpringBoot后，绝大部分配置项保持一致，同时新增了针对SpringBoot的配置项，开发者可以通过`application.yaml`或`application.properties`进行统一配置。

例如禁用请求日志：

```yaml
turboweb:
  show-request-log: false
```

新增的配置项包括：

```
turboweb:
  host: 0.0.0.0          # 服务器绑定的IP地址
  port: 8080             # 服务器监听端口
  io-thread: 1           # Netty IO线程数，默认单线程足以处理高并发请求
  anno-param-auto-bind: true  # 当使用声明式路由时，是否自动将请求参数绑定到方法参数
```

> **说明**：
>
> - `host` 和 `port` 配置直接影响服务启动的监听接口。
> - `io-thread` 仅影响IO事件的分发线程，TurboWeb默认采用轻量IO模型，单线程即可高效处理事件分发。
> - `anno-param-auto-bind` 可减少手动提取请求参数的步骤，提高开发效率。

## TurboWeb的路由管理器

整合SpringBoot后，TurboWeb默认采用声明式路由管理器，开发者无需手动注册控制器，框架会自动扫描带有 `@TurboController` 注解的类并注册到路由表中。

```java
@TurboController
@RequestPath
public class HelloController {

    @Get
    public String hello() {
        return "hello world";
    }
}
```

### 替换路由管理器

如果需要自定义路由策略，可以替换默认的路由管理器为 `LambdaRouterManager`：

```java
@Bean
public SpringLambdaRouterManager springLambdaRouterManager(ApplicationContext applicationContext) {
    return new SpringLambdaRouterManager(applicationContext);
}
```

使用 `LambdaRouterManager` 时：

- 控制器不再强制需要 `@TurboController` 注解。
- 只要 `LambdaRouterGroup` 被SpringBoot扫描到，即可自动注册路由。

```java
@Component
public class HelloController extends LambdaRouterGroup {

    @Override
    protected void registerRoute(RouterRegister routerRegister) {
        routerRegister.get(ctx -> "Hello World");
    }
}
```

## 自动配置类

TurboWeb提供了自动配置类，允许开发者通过继承 `TurboWebConfiguration` 自定义服务器行为。

```java
@Configuration
public class WebConfig extends TurboWebConfiguration {   
}
```

> **说明**：继承 `TurboWebConfiguration` 后，可通过覆盖内部方法进行中间件注册、拦截器、跨域设置、监听器等操作。

### 注册中间件

中间件在TurboWeb中用于处理请求链的前置或后置逻辑。注册顺序与调用顺序一致：

```java
@Override
protected void registerMiddleware(MiddlewareContainer container) {
    container.register(new Middleware() {
        @Override
        public Object invoke(HttpContext httpContext) {
            System.out.println("Middleware");
            return next(httpContext);
        }
    });
}
```

### 拦截器

默认情况下，TurboWeb拦截器是关闭的，需手动开启：

```java
@Override
protected boolean openInterceptorManager() {
    return true;
}
```

注册拦截器示例：

```java
@Override
protected void registerInterceptor(InterceptorManager manager) {
    manager.addInterceptionHandler("/**", new InterceptorHandler() {

        @Override
        public boolean preHandler(HttpContext ctx) {
            System.out.println("Interceptor Pre");
            return true;
        }

        @Override
        public Object postHandler(HttpContext ctx, Object result) {
            System.out.println("Interceptor Post");
            return result;
        }

        @Override
        public void afterCompletion(Throwable exception) {
            System.out.println("Interceptor Com");
        }

        @Override
        public int order() {
            return 0;
        }
    });
}
```

### 跨域设置

通过覆盖 `cors` 方法配置CORS策略：

````java
@Override
public void cors(CorsProcessor.Config config) {
    config.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "DELETE"));
}
````

### 添加监听器

监听器用于在服务器生命周期的关键节点执行自定义逻辑：

```java
@Override
protected void registerListener(ListenerContainer container) {
    container.addListener(new TurboWebListener() {
        @Override
        public void beforeServerInit() {
            System.out.println("Listener beforeServerInit");
        }

        @Override
        public void afterServerStart() {
            System.out.println("Listener afterServerStart");
        }
    });
}
```

### 添加Netty处理器

通过覆盖 `registerNettyHandler` 方法，可在TurboWeb内部处理链的前后增加自定义Netty处理器：

```java
@Override
protected void registerNettyHandler(NettyHandlerContainer container) {
    // 在TurboWeb核心处理器之前添加自定义逻辑
    container.addHandlerBeforeTurboWeb(...);
    // 在TurboWeb核心处理器之后添加自定义逻辑
    container.addHandlerAfterTurboWeb(...);
}
```

## 异常处理器

整合SpringBoot后，TurboWeb异常处理器可通过注解自动装配，无需手动注册：

```java
@TurboExceptionHandler
public class GlobalExceptionHandler {
    
    @ExceptionHandler(Exception.class)
    public String doException(Exception e) {
        return "error";
    }
}
```

> **说明**：
>
> - `@TurboExceptionHandler`：标识全局异常处理类。
> - `@ExceptionHandler`：指定异常类型和处理逻辑，可返回自定义响应或视图。

## WebSocket

在原生TurboWeb WebSocket基础上，通过添加 `@TurboWebSocket` 注解即可被SpringBoot自动装配：

```java
@TurboWebSocket
public class MyWebSocketHandler extends AbstractWebSocketHandler {
    @Override
    public void onText(WebSocketSession webSocketSession, String s) {
        System.out.println("接收到文本消息：" + s);
    }

    @Override
    public void onBinary(WebSocketSession webSocketSession, ByteBuf byteBuf) {
        System.out.println("接收到二进制消息：" + byteBuf);
    }
}
```

## 嵌入式网关

TurboWeb与SpringBoot整合中，默认只整合了同步风格的嵌入式网关，如果开发者需要使用响应式风格的嵌入式网关需要自己注入一个Bean，但是在性能上这俩几乎没有差距，大多数使用同步风格的嵌入式网关已经足够满足需求了。

接下来我们一起来使用TurboWeb的嵌入式网关。

首先，我们创建两个服务，并配置不同的端口：

```java
@TurboController
@Route("/order")
public class OrderController {
    @Get
    public String orderIndex() {
        return "order index";
    }
}
```

```yaml
turboweb:
  port: 8081
```

```java
@TurboController
@Route("/user")
public class UserController {
    @Get
    public String userIndex() {
        return "user index";
    }
}
```

```yaml
turboweb:
  port: 8080
```

其中一个是User服务，一个是Order服务，User服务配置的端口号是8080，而Order的端口号是8081。

这个时候假设我们要选择User服务不仅仅负责业务功能，也让他可以作为一个网关，我们就可以在User服务中如下配置：

```yaml
turboweb:
  port: 8080
  gateway:
    enable: true  # 开启网关
    local-pre: true  # 本地优先
    # 配置节点
    node:
      - service-name: order-service  # 配置服务的名称，用于在规则中使用
        urls:
          - localhost:8081  # 配置服务地址，注意不要携带协议
    # 配置服务的规则
    rule:
      - pattern: /order/**  # 所有以/order开头的请求
        service-expression: http://order-service  # 配置表达式，用服务名占位地址
      - pattern: /user/**
        service-expression: http://local  # 固定写法，代理到本地就用local这个服务名
```

之后我们就可以在user服务上访问/user或者/order了，都可以成果访问到。

### 动态注册

有的时候我们可能需要实现动态路由，即根据注册中心或者配置中心动态的更改路由规则，我们可以前取消配置文件中的配置：

```yaml
turboweb:
  port: 8080
  gateway:
    enable: true  # 开启网关
    local-pre: true  # 本地优先
```

仅保留开启网关和本地优先执行，接下来我们动态注册网关节点和规则：

```java
@Configuration
public class GatewayConfig extends TurboWebGatewayConfiguration {

    @Override
    protected void afterGatewayInit(DynamicConfig dynamicConfig) {
        // 重设节点
        dynamicConfig.resetServices(
                Map.of(
                        "order-service", Set.of("localhost:8081")
                )
        );
        // 创建规则管理器
        NodeRuleManager ruleManager = new NodeRuleManager();
        ruleManager.addRule("/order/**", "http://order-service");
        ruleManager.addRule("/user/**", "http://local");
        // 重设路由
        dynamicConfig.resetRule(ruleManager);
    }
}
```

之后重启服务器和之前配置文件配置的效果一样。

通过该扩展可以实现动态的扩展，当网关被初始化结束之后，会自动调用 `afterGatewayInit(..)` 方法，并传入一个可配置对象，因此可以在该方法中开启定时任务等去动态拉取配置中心或者注册中心的节点信息和配置信息实现动态更新，`DynamicConfig` 是可以多线程共享的，但是在重置规则的时候会有短暂的脏读，但是概率很低。

### 过滤器

TurboWeb的网关还有一个功能是过滤器，通过配置类可以很方便的注册过滤器，实现网关鉴权。

定义一个过滤器：

```java
public class TestListener implements GatewayFilter<Boolean> {
    @Override
    public Boolean filter(FullHttpRequest request, ResponseHelper responseHelper) {
        System.out.println(request.uri() + ": " + request.method());
        return true;
    }
}
```

之后在配置类中注册即可：

```java
@Override
protected void registerFilter(GatewayFilterContainer container) {
    container.addFilter(new TestListener());
}
```

顺序和注册顺序一致，由于TurboWeb默认采用的同步风格，因此泛型是Boolean类型。

### 替换IO引擎

TurboWeb的网关默认复用TurboWeb的服务器的IO循环组，如果开发者不想让网关和TurboWeb的服务器复用IO循环组，可以自己注册一个客户端，如下代码：

```java
@Override
protected HttpClient getHttpClient() {
    return HttpClient.create();
}
```

当返回值不为null时，TurboWeb会将该客户端设置进入网关底层的转发引擎，TurboWeb就不会将自己的IO循环组交给网关了。

## 启用HTTPS

当TurboWeb和SpringBoot整合之后，HTTPS的配置非常简单，仅操作配置文件即可完成，如下代码：

```yaml
turboweb:
  port: 8080
  ssl:
    enable: true
    server-key-path: E://temp/key.pem
    server-cert-path: E://temp/cert.pem
```

只需要开启https并配置上密钥和证书即可。

现在只能通过https访问服务器了。

## 启用HTTP2.0

TurboWeb启用HTTP2.0在与SpringBoot整合中非常方便，在开启HTTPS的基础上打开HTTP2.0的开关即可：

```yaml
turboweb:
  port: 8080
  ssl:
    enable: true
    server-key-path: E://temp/key.pem
    server-cert-path: E://temp/cert.pem
  h2: true
```

之后再次请求TurboWeb，打开开发者工具可以看到协议是h2了。