重构 Web 模块边界

zhoutaoo · zhoutaoo · commit 6e3a5e3bc28d · 2026-06-05T22:42:52.000+08:00
diff --git a/opensabre-starter-boot/src/main/java/io/github/opensabre/boot/config/OpensabreBootConfig.java b/opensabre-starter-boot/src/main/java/io/github/opensabre/boot/config/OpensabreBootConfig.java
@@ -1,16 +1,12 @@
 package io.github.opensabre.boot.config;
 
-import io.github.opensabre.common.web.exception.DefaultGlobalExceptionHandlerAdvice;
-import io.github.opensabre.common.web.rest.RestResponseBodyAdvice;
 import org.springframework.boot.autoconfigure.AutoConfiguration;
-import org.springframework.context.annotation.Import;
 import org.springframework.context.annotation.PropertySource;
 
 /**
- * 初使化全局报文和全局异常配置
+ * 初使化 Boot 通用配置
  */
 @AutoConfiguration
 @PropertySource(value = "classpath:opensabre-boot.properties", encoding = "UTF8")
-@Import({DefaultGlobalExceptionHandlerAdvice.class, RestResponseBodyAdvice.class})
 public class OpensabreBootConfig {
 }
diff --git a/opensabre-starter-boot/src/main/java/io/github/opensabre/boot/config/OpensabreWebConfiguration.java b/opensabre-starter-boot/src/main/java/io/github/opensabre/boot/config/OpensabreWebConfiguration.java
diff --git a/opensabre-starter-boot/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports b/opensabre-starter-boot/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
@@ -1,5 +1,4 @@
 io.github.opensabre.boot.config.OpensabreSwaggerConfig
 io.github.opensabre.boot.config.OpensabreBootConfig
-io.github.opensabre.boot.config.OpensabreWebConfiguration
 io.github.opensabre.boot.config.OpensabreServiceConfig
 io.github.opensabre.boot.config.OpensabreSensitiveConfig
diff --git a/opensabre-starter-webflux/pom.xml b/opensabre-starter-webflux/pom.xml
@@ -39,16 +39,6 @@
         <dependency>
             <groupId>io.github.opensabre</groupId>
             <artifactId>opensabre-web</artifactId>
-            <exclusions>
-                <exclusion>
-                    <groupId>org.springframework</groupId>
-                    <artifactId>spring-webmvc</artifactId>
-                </exclusion>
-                <exclusion>
-                    <groupId>jakarta.servlet</groupId>
-                    <artifactId>jakarta.servlet-api</artifactId>
-                </exclusion>
-            </exclusions>
         </dependency>
         <dependency>
             <groupId>org.springframework</groupId>
diff --git a/opensabre-starter-webmvc/pom.xml b/opensabre-starter-webmvc/pom.xml
@@ -73,6 +73,10 @@
             <groupId>org.springframework</groupId>
             <artifactId>spring-webmvc</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-autoconfigure</artifactId>
+        </dependency>
         <!--常用工具包-->
         <dependency>
             <groupId>org.apache.commons</groupId>
diff --git a/opensabre-starter-webmvc/readme.md b/opensabre-starter-webmvc/readme.md
@@ -3,7 +3,7 @@ WEBMVC公共包
 
 ## 简介
 
-主要封装spring-webmvc WEB开发用到的通用公共类、工具类，如公共web拦截器、web统一异常定义等。
+主要封装 Spring MVC Web 开发用到的 Servlet/MVC 特性能力，如 MVC 自动装配、MVC 全局异常处理、MVC 统一响应包装、Servlet 用户上下文拦截器等。
 
 ## 使用
 
@@ -23,6 +23,6 @@ pom.xml
 <dependency>
     <groupId>io.github.opensabre</groupId>
     <artifactId>opensabre-starter-webmvc</artifactId>
-    <version>0.1.1</version>
+    <version>0.3.0</version>
 </dependency>
-```
+```
diff --git a/opensabre-starter-webmvc/src/main/java/io/github/opensabre/webmvc/config/OpensabreWebMvcConfig.java b/opensabre-starter-webmvc/src/main/java/io/github/opensabre/webmvc/config/OpensabreWebMvcConfig.java
@@ -0,0 +1,16 @@
+package io.github.opensabre.webmvc.config;
+
+import io.github.opensabre.webmvc.exception.DefaultWebMvcExceptionHandlerAdvice;
+import io.github.opensabre.webmvc.rest.RestResponseBodyAdvice;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
+import org.springframework.context.annotation.Import;
+
+/**
+ * Opensabre WebMvc auto-configuration.
+ */
+@AutoConfiguration
+@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
+@Import({DefaultWebMvcExceptionHandlerAdvice.class, RestResponseBodyAdvice.class})
+public class OpensabreWebMvcConfig {
+}
diff --git a/opensabre-starter-webmvc/src/main/java/io/github/opensabre/webmvc/exception/DefaultWebMvcExceptionHandlerAdvice.java b/opensabre-starter-webmvc/src/main/java/io/github/opensabre/webmvc/exception/DefaultWebMvcExceptionHandlerAdvice.java
@@ -3,6 +3,7 @@
 import io.github.opensabre.common.core.entity.vo.Result;
 import io.github.opensabre.common.core.exception.SystemErrorType;
 import jakarta.servlet.ServletException;
+import io.github.opensabre.common.core.exception.BaseException;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.core.annotation.Order;
 import org.springframework.http.HttpStatus;
@@ -40,7 +41,7 @@ public Result<?> argumentInvalidException(MethodArgumentNotValidException ex) {
     }
 
     @ExceptionHandler(value = {HttpMessageNotReadableException.class, MethodArgumentTypeMismatchException.class})
-    public Result<?> httpMessageConvertException(HttpMessageNotReadableException ex) {
+    public Result<?> httpMessageConvertException(Exception ex) {
         log.warn("http message convert exception:{}", ex.getMessage());
         return Result.fail(SystemErrorType.ARGUMENT_NOT_VALID, "数据解析错误：" + ex.getMessage());
     }
@@ -71,4 +72,17 @@ public Result<?> notSupportedMethodException(HttpMediaTypeNotSupportedException
         log.warn("http request media not supported exception {}", ex.getMessage());
         return Result.fail(SystemErrorType.METHOD_NOT_SUPPORTED);
     }
-}
+
+    @ExceptionHandler(value = {BaseException.class})
+    public Result<?> baseException(BaseException ex) {
+        log.warn("base exception:{}", ex.getMessage());
+        return Result.fail(ex.getErrorType());
+    }
+
+    @ExceptionHandler(value = {Exception.class, Throwable.class})
+    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
+    public Result<?> exception(Throwable ex) {
+        log.error("exception: ", ex);
+        return Result.fail();
+    }
+}
diff --git a/opensabre-starter-webmvc/src/main/java/io/github/opensabre/webmvc/interceptor/UserInterceptor.java b/opensabre-starter-webmvc/src/main/java/io/github/opensabre/webmvc/interceptor/UserInterceptor.java
@@ -1,4 +1,4 @@
-package io.github.opensabre.common.web.interceptor;
+package io.github.opensabre.webmvc.interceptor;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.github.opensabre.common.core.util.UserContextHolder;
@@ -8,7 +8,6 @@
 import org.springframework.lang.Nullable;
 import org.springframework.web.servlet.HandlerInterceptor;
 
-
 import java.util.Map;
 
 /**
@@ -29,6 +28,7 @@ public class UserInterceptor implements HandlerInterceptor {
     public static final String X_CLIENT_TOKEN = "x-client-token";
 
     @Override
+    @SuppressWarnings("unchecked")
     public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
         //从网关获取并校验,通过校验就可信任x-client-token-user中的信息
         checkToken(request.getHeader(X_CLIENT_TOKEN));
@@ -47,7 +47,7 @@ private void checkToken(String token) {
     }
 
     @Override
-    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, @Nullable Exception ex) throws Exception {
+    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, @Nullable Exception ex) {
         UserContextHolder.getInstance().clear();
     }
 }
diff --git a/opensabre-starter-webmvc/src/main/java/io/github/opensabre/webmvc/rest/RestResponseBodyAdvice.java b/opensabre-starter-webmvc/src/main/java/io/github/opensabre/webmvc/rest/RestResponseBodyAdvice.java
@@ -1,4 +1,4 @@
-package io.github.opensabre.common.web.rest;
+package io.github.opensabre.webmvc.rest;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.github.opensabre.common.core.entity.vo.Result;
@@ -27,12 +27,12 @@ public class RestResponseBodyAdvice implements ResponseBodyAdvice<Object> {
     /**
      * 框架中不需要包装为Result对象的包名
      */
-    @Value("${opensabre.rest.result.framework.excludes}")
+    @Value("${opensabre.rest.result.framework.excludes:org.springdoc}")
     private String excludeFrameworkPackageStr;
     /**
      * 应用中不需要包装为Result对象的包名
      */
-    @Value("${opensabre.rest.result.excludes}")
+    @Value("${opensabre.rest.result.excludes:}")
     private String excludePackageStr;
 
     @Override
@@ -77,4 +77,4 @@ public Object beforeBodyWrite(Object body,
         }
         return Result.success(body);
     }
-}
+}
diff --git a/opensabre-starter-webmvc/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports b/opensabre-starter-webmvc/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
@@ -0,0 +1 @@
+io.github.opensabre.webmvc.config.OpensabreWebMvcConfig
diff --git a/opensabre-starter-webmvc/src/test/java/io/github/opensabre/webmvc/exception/DefaultWebMvcExceptionHandlerAdviceTest.java b/opensabre-starter-webmvc/src/test/java/io/github/opensabre/webmvc/exception/DefaultWebMvcExceptionHandlerAdviceTest.java
@@ -1,4 +1,4 @@
-package io.github.opensabre.common.web.exception;
+package io.github.opensabre.webmvc.exception;
 
 import io.github.opensabre.common.core.entity.vo.Result;
 import io.github.opensabre.common.core.exception.BaseException;
@@ -14,57 +14,56 @@
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
-public class DefaultGlobalExceptionHandlerAdviceTest {
+class DefaultWebMvcExceptionHandlerAdviceTest {
 
-    private DefaultGlobalExceptionHandlerAdvice defaultGlobalExceptionHandlerAdvice;
+    private DefaultWebMvcExceptionHandlerAdvice advice;
 
     @BeforeEach
-    public void before() {
-        this.defaultGlobalExceptionHandlerAdvice = new DefaultGlobalExceptionHandlerAdvice();
+    void before() {
+        this.advice = new DefaultWebMvcExceptionHandlerAdvice();
     }
 
     @Test
-    public void testMissingServletRequestParameterException() {
-        Result result = defaultGlobalExceptionHandlerAdvice
+    void missingServletRequestParameterExceptionShouldReturnArgumentInvalid() {
+        Result<?> result = advice
                 .missingServletRequestParameterException(new MissingServletRequestParameterException("test", "string"));
         assertEquals(SystemErrorType.ARGUMENT_NOT_VALID.getCode(), result.getCode());
     }
 
     @Test
-    public void testUploadFileLimitException() {
-        Result result = defaultGlobalExceptionHandlerAdvice.uploadFileLimitException(new MultipartException("test"));
+    void uploadFileLimitExceptionShouldReturnUploadLimit() {
+        Result<?> result = advice.uploadFileLimitException(new MultipartException("test"));
         assertEquals(SystemErrorType.UPLOAD_FILE_SIZE_LIMIT.getCode(), result.getCode());
     }
 
     @Test
-    public void testServiceException() throws NoSuchMethodException {
-        //准备数据
+    void methodArgumentNotValidExceptionShouldReturnFieldMessage() throws NoSuchMethodException {
         MethodParameter methodParameter = new MethodParameter(Object.class.getMethod("toString"), -1);
         BindException bindingResult = new BindException(new Object(), "test");
         bindingResult.addError(new FieldError("test", "test", "testmessage"));
         MethodArgumentNotValidException exception = new MethodArgumentNotValidException(methodParameter, bindingResult);
-        //调用
-        Result result = defaultGlobalExceptionHandlerAdvice.argumentInvalidException(exception);
-        //验证
+
+        Result<?> result = advice.argumentInvalidException(exception);
+
         assertEquals(SystemErrorType.ARGUMENT_NOT_VALID.getCode(), result.getCode());
         assertEquals("testmessage", result.getData());
     }
 
     @Test
-    public void testBaseException() {
-        Result result = defaultGlobalExceptionHandlerAdvice.baseException(new BaseException(SystemErrorType.SYSTEM_BUSY));
+    void baseExceptionShouldReturnOriginalErrorType() {
+        Result<?> result = advice.baseException(new BaseException(SystemErrorType.SYSTEM_BUSY));
         assertEquals(SystemErrorType.SYSTEM_BUSY.getCode(), result.getCode());
     }
 
     @Test
-    public void testException() {
-        Result result = defaultGlobalExceptionHandlerAdvice.exception(new Exception("error"));
+    void exceptionShouldReturnSystemError() {
+        Result<?> result = advice.exception(new Exception("error"));
         assertEquals(SystemErrorType.SYSTEM_ERROR.getCode(), result.getCode());
     }
 
     @Test
-    public void testThrowable() {
-        Result result = defaultGlobalExceptionHandlerAdvice.exception(new Throwable("error"));
+    void throwableShouldReturnSystemError() {
+        Result<?> result = advice.exception(new Throwable("error"));
         assertEquals(SystemErrorType.SYSTEM_ERROR.getCode(), result.getCode());
     }
 }
diff --git a/opensabre-starter-webmvc/src/test/java/io/github/opensabre/webmvc/interceptor/UserInterceptorTest.java b/opensabre-starter-webmvc/src/test/java/io/github/opensabre/webmvc/interceptor/UserInterceptorTest.java
@@ -1,7 +1,7 @@
 package io.github.opensabre.webmvc.interceptor;
 
 import io.github.opensabre.common.core.util.UserContextHolder;
-import io.github.opensabre.common.web.interceptor.UserInterceptor;
+import io.github.opensabre.webmvc.interceptor.UserInterceptor;
 import org.junit.jupiter.api.Test;
 import org.springframework.mock.web.MockHttpServletRequest;
 import org.springframework.mock.web.MockHttpServletResponse;
diff --git a/opensabre-web/pom.xml b/opensabre-web/pom.xml
@@ -78,10 +78,10 @@
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-api</artifactId>
         </dependency>
-        <!--spring web相关包-->
+        <!--spring beans utility-->
         <dependency>
             <groupId>org.springframework</groupId>
-            <artifactId>spring-webmvc</artifactId>
+            <artifactId>spring-beans</artifactId>
         </dependency>
         <!--常用工具包-->
         <dependency>
@@ -119,18 +119,6 @@
             <groupId>jakarta.validation</groupId>
             <artifactId>jakarta.validation-api</artifactId>
         </dependency>
-        <!--开发相关-->
-        <dependency>
-            <groupId>jakarta.servlet</groupId>
-            <artifactId>jakarta.servlet-api</artifactId>
-            <scope>provided</scope>
-        </dependency>
-        <!--测试框架-->
-        <dependency>
-            <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-test</artifactId>
-            <scope>test</scope>
-        </dependency>
         <!--junit单元测试-->
         <dependency>
             <groupId>org.junit.jupiter</groupId>
diff --git a/opensabre-web/readme.md b/opensabre-web/readme.md
@@ -1,9 +1,9 @@
-WEB公共包
+WEB通用公共包
 ----------
 
 ## 简介
 
-主要封装一些WEB开发用到的通用公共类、工具类，如公共web拦截器、web统一异常定义等。
+主要封装 Web 开发中与 Spring MVC、Spring WebFlux 无关的通用公共类、工具类，如统一返回模型、通用异常定义、基础表单/VO、校验注解和用户上下文等。
 
 ## 使用
 
@@ -22,7 +22,7 @@ pom.xml
 ```
 <dependency>
     <groupId>io.github.opensabre</groupId>
-    <artifactId>common-web</artifactId>
-    <version>0.0.1</version>
+    <artifactId>opensabre-web</artifactId>
+    <version>0.3.0</version>
 </dependency>
-```
+```
diff --git a/opensabre-web/src/main/java/io/github/opensabre/common/web/exception/DefaultGlobalExceptionHandlerAdvice.java b/opensabre-web/src/main/java/io/github/opensabre/common/web/exception/DefaultGlobalExceptionHandlerAdvice.java
diff --git a/opensabre-web/src/test/java/io/github/opensabre/common/web/interceptor/UserInterceptorTest.java b/opensabre-web/src/test/java/io/github/opensabre/common/web/interceptor/UserInterceptorTest.java
