暂存提交

2026-07-30 18:01:36 +08:00
commit 2f4e159356
368 changed files with 20370 additions and 0 deletions
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>com.baiyue.firstleg</groupId>
+        <artifactId>baiyue-firstleg-platform</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+    <groupId>com.baiyue.shared</groupId>
+    <artifactId>baiyue-common-web</artifactId>
+    <name>baiyue-common-web</name>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.baiyue.shared</groupId>
+            <artifactId>baiyue-common-core</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.security</groupId>
+            <artifactId>spring-security-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-validation</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>
@@ -0,0 +1,29 @@
+package com.baiyue.common.web;
+
+import jakarta.servlet.http.HttpServletRequest;
+import org.slf4j.MDC;
+
+/**
+ * 请求关联标识上下文工具，从请求属性或日志 MDC 中读取当前请求 ID。
+ */
+public final class CorrelationContext {
+    public static final String REQUEST_ID = "requestId";
+    public static final String TRACE_ID = "traceId";
+    public static final String REQUEST_ID_HEADER = "X-Request-Id";
+    public static final String TRACE_ID_HEADER = "X-Trace-Id";
+
+    private CorrelationContext() {}
+
+    public static String requestId(HttpServletRequest request) {
+        return value(request, REQUEST_ID);
+    }
+
+    public static String traceId(HttpServletRequest request) {
+        return value(request, TRACE_ID);
+    }
+
+    private static String value(HttpServletRequest request, String key) {
+        Object attribute = request.getAttribute(key);
+        return attribute == null ? MDC.get(key) : attribute.toString();
+    }
+}
@@ -0,0 +1,48 @@
+package com.baiyue.common.web;
+
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.slf4j.MDC;
+import org.springframework.core.Ordered;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+import java.io.IOException;
+import java.util.UUID;
+import java.util.regex.Pattern;
+
+/**
+ * 请求关联标识过滤器，校验或生成请求 ID，并同步写入响应头和日志 MDC。
+ */
+@Component
+@Order(Ordered.HIGHEST_PRECEDENCE)
+public class CorrelationIdFilter extends OncePerRequestFilter {
+    private static final Pattern SAFE_ID = Pattern.compile("[A-Za-z0-9._:-]{1,128}");
+
+    @Override
+    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+                                    FilterChain filterChain) throws ServletException, IOException {
+        String requestId = acceptedOrGenerated(request.getHeader(CorrelationContext.REQUEST_ID_HEADER), false);
+        String traceId = acceptedOrGenerated(request.getHeader(CorrelationContext.TRACE_ID_HEADER), true);
+        request.setAttribute(CorrelationContext.REQUEST_ID, requestId);
+        request.setAttribute(CorrelationContext.TRACE_ID, traceId);
+        response.setHeader(CorrelationContext.REQUEST_ID_HEADER, requestId);
+        response.setHeader(CorrelationContext.TRACE_ID_HEADER, traceId);
+
+        try (MDC.MDCCloseable ignoredRequest = MDC.putCloseable(CorrelationContext.REQUEST_ID, requestId);
+             MDC.MDCCloseable ignoredTrace = MDC.putCloseable(CorrelationContext.TRACE_ID, traceId)) {
+            filterChain.doFilter(request, response);
+        }
+    }
+
+    private String acceptedOrGenerated(String candidate, boolean compact) {
+        if (candidate != null && SAFE_ID.matcher(candidate).matches()) {
+            return candidate;
+        }
+        String id = UUID.randomUUID().toString();
+        return compact ? id.replace("-", "") : id;
+    }
+}
@@ -0,0 +1,102 @@
+package com.baiyue.common.web;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.validation.ConstraintViolationException;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.AccessDeniedException;
+import org.springframework.security.core.AuthenticationException;
+import org.springframework.validation.BindException;
+import org.springframework.validation.FieldError;
+import org.springframework.http.converter.HttpMessageNotReadableException;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.MissingServletRequestParameterException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * Servlet Web 全局异常处理器，将业务异常、参数校验异常和系统异常转换为统一 API 响应。
+ */
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
+
+    @ExceptionHandler(BizException.class)
+    public ResponseEntity<ApiResponse<Void>> handleBusiness(BizException exception, HttpServletRequest request) {
+        return failure(exception.getResultCode(), exception.getMessage(), request);
+    }
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ResponseEntity<ApiResponse<Map<String, String>>> handleValidation(
+            MethodArgumentNotValidException exception, HttpServletRequest request) {
+        return validationResponse(fieldErrors(exception.getBindingResult().getFieldErrors()), request);
+    }
+
+    @ExceptionHandler(BindException.class)
+    public ResponseEntity<ApiResponse<Map<String, String>>> handleBinding(
+            BindException exception, HttpServletRequest request) {
+        return validationResponse(fieldErrors(exception.getBindingResult().getFieldErrors()), request);
+    }
+
+    @ExceptionHandler(ConstraintViolationException.class)
+    public ResponseEntity<ApiResponse<Map<String, String>>> handleConstraint(
+            ConstraintViolationException exception, HttpServletRequest request) {
+        Map<String, String> errors = new LinkedHashMap<>();
+        exception.getConstraintViolations().forEach(violation ->
+                errors.put(violation.getPropertyPath().toString(), violation.getMessage()));
+        return validationResponse(errors, request);
+    }
+
+    @ExceptionHandler({HttpMessageNotReadableException.class, MissingServletRequestParameterException.class})
+    public ResponseEntity<ApiResponse<Void>> handleBadRequest(Exception exception, HttpServletRequest request) {
+        return failure(ResultCode.BAD_REQUEST, ResultCode.BAD_REQUEST.message(), request);
+    }
+
+    @ExceptionHandler(AuthenticationException.class)
+    public ResponseEntity<ApiResponse<Void>> handleAuthentication(
+            AuthenticationException exception, HttpServletRequest request) {
+        return failure(ResultCode.UNAUTHORIZED, ResultCode.UNAUTHORIZED.message(), request);
+    }
+
+    @ExceptionHandler(AccessDeniedException.class)
+    public ResponseEntity<ApiResponse<Void>> handleAccessDenied(
+            AccessDeniedException exception, HttpServletRequest request) {
+        return failure(ResultCode.FORBIDDEN, ResultCode.FORBIDDEN.message(), request);
+    }
+
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<ApiResponse<Void>> handleUnexpected(Exception exception, HttpServletRequest request) {
+        log.error("Unhandled request failure requestId={} traceId={}",
+                CorrelationContext.requestId(request), CorrelationContext.traceId(request), exception);
+        return failure(ResultCode.INTERNAL_ERROR, ResultCode.INTERNAL_ERROR.message(), request);
+    }
+
+    private Map<String, String> fieldErrors(Iterable<FieldError> fieldErrors) {
+        Map<String, String> errors = new LinkedHashMap<>();
+        fieldErrors.forEach(error -> errors.putIfAbsent(error.getField(), error.getDefaultMessage()));
+        return errors;
+    }
+
+    private ResponseEntity<ApiResponse<Map<String, String>>> validationResponse(
+            Map<String, String> errors, HttpServletRequest request) {
+        ResultCode code = ResultCode.VALIDATION_FAILED;
+        ApiResponse<Map<String, String>> body = ApiResponse.of(code, code.message(), errors,
+                CorrelationContext.requestId(request), CorrelationContext.traceId(request));
+        return ResponseEntity.status(code.httpStatus()).body(body);
+    }
+
+    private ResponseEntity<ApiResponse<Void>> failure(ResultCode code, String message,
+                                                       HttpServletRequest request) {
+        ApiResponse<Void> body = ApiResponse.failure(code, message,
+                CorrelationContext.requestId(request), CorrelationContext.traceId(request));
+        return ResponseEntity.status(code.httpStatus()).body(body);
+    }
+}
+
@@ -0,0 +1,37 @@
+package com.baiyue.common.web;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.web.MockFilterChain;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.mock.web.MockHttpServletResponse;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class CorrelationIdFilterTest {
+    private final CorrelationIdFilter filter = new CorrelationIdFilter();
+
+    @Test
+    void preservesSafeIncomingIds() throws Exception {
+        MockHttpServletRequest request = new MockHttpServletRequest();
+        request.addHeader(CorrelationContext.REQUEST_ID_HEADER, "req-123");
+        request.addHeader(CorrelationContext.TRACE_ID_HEADER, "trace-123");
+        MockHttpServletResponse response = new MockHttpServletResponse();
+
+        filter.doFilter(request, response, new MockFilterChain());
+
+        assertThat(response.getHeader(CorrelationContext.REQUEST_ID_HEADER)).isEqualTo("req-123");
+        assertThat(request.getAttribute(CorrelationContext.TRACE_ID)).isEqualTo("trace-123");
+    }
+
+    @Test
+    void replacesUnsafeIncomingIds() throws Exception {
+        MockHttpServletRequest request = new MockHttpServletRequest();
+        request.addHeader(CorrelationContext.REQUEST_ID_HEADER, "invalid value\n");
+        MockHttpServletResponse response = new MockHttpServletResponse();
+        filter.doFilter(request, response, new MockFilterChain());
+        assertThat(response.getHeader(CorrelationContext.REQUEST_ID_HEADER))
+                .matches("[0-9a-f-]{36}");
+        assertThat(response.getHeader(CorrelationContext.TRACE_ID_HEADER))
+                .matches("[0-9a-f]{32}");
+    }
+}
@@ -0,0 +1,23 @@
+package com.baiyue.common.web;
+
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.web.MockHttpServletRequest;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class GlobalExceptionHandlerTest {
+    private final GlobalExceptionHandler handler = new GlobalExceptionHandler();
+
+    @Test
+    void businessExceptionKeepsBusinessCodeAndCorrelation() {
+        MockHttpServletRequest request = new MockHttpServletRequest();
+        request.setAttribute(CorrelationContext.REQUEST_ID, "r1");
+        request.setAttribute(CorrelationContext.TRACE_ID, "t1");
+        var response = handler.handleBusiness(new BizException("inventory is locked"), request);
+        assertThat(response.getStatusCode().value()).isEqualTo(400);
+        assertThat(response.getBody().code()).isEqualTo(ResultCode.BUSINESS_ERROR.code());
+        assertThat(response.getBody().requestId()).isEqualTo("r1");
+    }
+}