WebJars

本文档介绍如何在 Tio-Boot 中配置 WebJars 资源访问及 Swagger UI 页面访问的实现方式。通过 Tio-Boot 内置的 WebjarHandler 类和自定义的 SwaggerUiHandler，我们可以实现对 WebJars 静态资源和 doc.html Swagger 页面文件的访问。

WebJars 规范

WebJars 是一种将前端库打包成 JAR 文件并放入 Java 项目中的方式。它的目的是在 Java 项目中方便地引入前端静态资源，比如 JavaScript、CSS 文件等。WebJars 资源被存放在 META-INF/resources/webjars 目录下，该目录符合 Java 和 Servlet 规范，这样的组织方式使得应用服务器能够直接从类路径中加载这些资源。

WebJars 资源目录规范

• 标准路径：WebJars 资源应放在 META-INF/resources/webjars 下。Java Web 应用服务器会自动将 META-INF/resources 下的内容作为 Web 根路径来提供静态资源，因此 META-INF/resources/webjars 下的文件可以通过 /webjars/ 路径访问。
• 便于管理和升级：使用 WebJars 可以通过依赖管理工具（如 Maven 或 Gradle）自动引入和管理前端库，避免手动复制文件，并且易于版本更新。

示例：假设使用了 swagger-ui 的 WebJar 依赖，swagger-ui 的静态文件会放在 META-INF/resources/webjars/swagger-ui 下。在 Web 服务器中，可以通过 /webjars/swagger-ui 访问它们。

配置 WebJars 资源访问

步骤 1：定义 WebHelloConfig 配置类

在 WebHelloConfig 配置类中，通过 TioBootServer 的 HttpRequestRouter 来注册 WebjarHandler 和 SwaggerUiHandler。这样可以定义访问路径 /webjars/** 和 /doc.html，分别用于访问 WebJars 资源和 Swagger UI 页面。

package nexus.io.tio.web.hello.config;

import nexus.io.annotation.AConfiguration;
import nexus.io.annotation.Initialization;
import nexus.io.tio.boot.http.handler.common.WebjarHandler;
import nexus.io.tio.boot.server.TioBootServer;
import nexus.io.tio.http.server.router.HttpRequestRouter;
import nexus.io.tio.web.hello.controller.SwaggerUiHandler;
import nexus.io.tio.web.hello.handler.HelloHandler;

@AConfiguration
public class WebHelloConfig {

  @Initialization
  public void config() {
    TioBootServer server = TioBootServer.me();
    HttpRequestRouter requestRouter = server.getRequestRouter();
    if (requestRouter != null) {
      SwaggerUiHandler swaggerUiHandler = new SwaggerUiHandler();
      requestRouter.add("/doc.html", swaggerUiHandler::html);

      WebjarHandler webjarHandler = new WebjarHandler();
      requestRouter.add("/webjars/**", webjarHandler::index);

      HelloHandler helloHandler = new HelloHandler();
      requestRouter.add("/hello", helloHandler::hello);
    }
  }
}

步骤 2：使用 WebjarHandler 加载 WebJars 静态资源

WebjarHandler 是 Tio-Boot 内部提供的一个处理器，用于读取 META-INF/resources/webjars 下的资源文件。下面是 WebjarHandler 的源码：

package nexus.io.tio.boot.http.handler.common;

import java.net.URL;

import nexus.io.tio.boot.http.TioRequestContext;
import nexus.io.tio.http.common.HttpRequest;
import nexus.io.tio.http.common.HttpResponse;
import nexus.io.tio.http.server.util.Resps;
import nexus.io.tio.utils.hutool.FileUtil;
import nexus.io.tio.utils.hutool.ResourceUtil;

public class WebjarHandler {
  public HttpResponse index(HttpRequest request) {
    HttpResponse response = TioRequestContext.getResponse();
    String uri = request.getRequestURI();
    String path = "META-INF/resources" + uri;
    URL resource = ResourceUtil.getResource(path);

    if (resource != null) {
      byte[] bytes = FileUtil.readUrlAsBytes(resource);
      String extName = FileUtil.extName(uri);
      return Resps.bytes(response, bytes, extName);
    } else {
      response.setStatus(404);
      return response;
    }
  }
}

该处理器会根据请求的 URI 自动从 META-INF/resources 路径下读取文件并返回。如果请求的文件不存在，则返回 404 状态码。

测试 WebJars 资源访问

启动项目后，访问以下 URL 以测试 WebJars 资源的加载情况：

http://localhost/webjars/bycdao-ui/ext/i18n.js

配置 Swagger UI 页面访问

为了实现对 Swagger UI 的访问，我们可以定义一个 SwaggerUiHandler 类，手动读取 META-INF/resources/doc.html 文件并返回其内容。

SwaggerUiHandler 实现代码

package nexus.io.tio.web.hello.controller;

import java.net.URL;

import nexus.io.tio.boot.http.TioRequestContext;
import nexus.io.tio.http.common.HttpRequest;
import nexus.io.tio.http.common.HttpResponse;
import nexus.io.tio.http.server.util.Resps;
import nexus.io.tio.utils.hutool.FileUtil;
import nexus.io.tio.utils.hutool.ResourceUtil;

import lombok.extern.slf4j.Slf4j;

@Slf4j
public class SwaggerUiHandler {

  public HttpResponse html(HttpRequest request) throws Exception {
    // 定义 doc.html 文件的路径
    String path = "META-INF/resources/doc.html";
    URL resource = ResourceUtil.getResource(path);
    HttpResponse response = TioRequestContext.getResponse();

    String html;
    if (resource == null) {
      log.error("资源不存在: {}", path);
      html = "资源不存在";
    } else {
      html = FileUtil.readString(resource).toString();
    }
    return Resps.html(response, html);
  }
}

测试 Swagger UI 页面访问

启动项目后，访问以下 URL 以测试 Swagger UI 页面加载情况：

http://localhost/doc.html

代码解释

• SwaggerUiHandler 类负责从 META-INF/resources/doc.html 读取 Swagger UI 的 HTML 文件内容。
• 如果资源文件存在，使用 FileUtil.readString(resource) 将其内容读取为字符串并返回给客户端。
• 如果资源不存在，返回 "资源不存在" 的提示信息，并在日志中记录错误。

通过以上配置，您可以在 Tio-Boot 中顺利加载 WebJars 资源和 Swagger UI 页面。