refactor(api): 统一 HTTP 200 响应契约

common-web/pom.xml

@@ -31,6 +31,10 @@
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-validation</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.micrometer</groupId>
+            <artifactId>micrometer-core</artifactId>
+        </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-test</artifactId>

common-web/src/main/java/com/baiyue/common/web/CommonWebAutoConfiguration.java

@@ -0,0 +1,25 @@
+package com.baiyue.common.web;
+
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.context.annotation.Bean;
+
+/**
+ * Registers the common servlet response contract even when an application only scans its own
+ * package, such as audit-service and event-bridge-service.
+ */
+@AutoConfiguration
+public class CommonWebAutoConfiguration {
+
+    @Bean
+    @ConditionalOnMissingBean(GlobalExceptionHandler.class)
+    GlobalExceptionHandler globalExceptionHandler() {
+        return new GlobalExceptionHandler();
+    }
+
+    @Bean
+    @ConditionalOnMissingBean(CorrelationIdFilter.class)
+    CorrelationIdFilter correlationIdFilter() {
+        return new CorrelationIdFilter();
+    }
+}

common-web/src/main/java/com/baiyue/common/web/GlobalExceptionHandler.java

@@ -5,9 +5,11 @@ import com.baiyue.common.core.api.ResultCode;
 import com.baiyue.common.core.exception.BizException;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.validation.ConstraintViolationException;
+import io.micrometer.core.instrument.MeterRegistry;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.http.ResponseEntity;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.security.access.AccessDeniedException;
 import org.springframework.security.core.AuthenticationException;
 import org.springframework.validation.BindException;
@@ -29,6 +31,9 @@ import java.util.Map;
 public class GlobalExceptionHandler {
     private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
 
+    @Autowired(required = false)
+    private MeterRegistry meterRegistry;
+
     @ExceptionHandler(BizException.class)
     public ResponseEntity<ApiResponse<Void>> handleBusiness(BizException exception, HttpServletRequest request) {
         return failure(exception.getResultCode(), exception.getMessage(), request);
@@ -91,14 +96,21 @@ public class GlobalExceptionHandler {
         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);
+        recordFailure(code);
+        return ResponseEntity.ok(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);
+        recordFailure(code);
+        return ResponseEntity.ok(body);
+    }
+
+    private void recordFailure(ResultCode code) {
+        if (meterRegistry != null) {
+            meterRegistry.counter("baiyue.api.business.failures", "code", code.code()).increment();
+        }
     }
 }
-

common-web/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

@@ -1 +1,2 @@
 com.baiyue.common.web.LongIdJacksonConfiguration
+com.baiyue.common.web.CommonWebAutoConfiguration

common-web/src/test/java/com/baiyue/common/web/CommonWebAutoConfigurationTest.java

@@ -0,0 +1,31 @@
+package com.baiyue.common.web;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.autoconfigure.AutoConfigurations;
+import org.springframework.boot.test.context.runner.ApplicationContextRunner;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class CommonWebAutoConfigurationTest {
+
+    private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
+            .withConfiguration(AutoConfigurations.of(CommonWebAutoConfiguration.class));
+
+    @Test
+    void registersExceptionHandlerAndCorrelationFilterOutsideComponentScan() {
+        contextRunner.run(context -> {
+            assertThat(context).hasSingleBean(GlobalExceptionHandler.class);
+            assertThat(context).hasSingleBean(CorrelationIdFilter.class);
+        });
+    }
+
+    @Test
+    void backsOffWhenApplicationProvidesItsOwnBeans() {
+        contextRunner.withBean(GlobalExceptionHandler.class, GlobalExceptionHandler::new)
+                .withBean(CorrelationIdFilter.class, CorrelationIdFilter::new)
+                .run(context -> {
+                    assertThat(context).hasSingleBean(GlobalExceptionHandler.class);
+                    assertThat(context).hasSingleBean(CorrelationIdFilter.class);
+                });
+    }
+}

common-web/src/test/java/com/baiyue/common/web/GlobalExceptionHandlerTest.java

@@ -2,11 +2,13 @@ package com.baiyue.common.web;
 
 import com.baiyue.common.core.api.ResultCode;
 import com.baiyue.common.core.exception.BizException;
+import io.micrometer.core.instrument.simple.SimpleMeterRegistry;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
 import org.springframework.mock.web.MockHttpServletRequest;
 import org.springframework.core.MethodParameter;
 import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
+import org.springframework.test.util.ReflectionTestUtils;
 
 import java.lang.reflect.Method;
 
@@ -22,7 +24,7 @@ class GlobalExceptionHandlerTest {
         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.getStatusCode().value()).isEqualTo(200);
         assertThat(response.getBody().code()).isEqualTo(ResultCode.BUSINESS_ERROR.code());
         assertThat(response.getBody().requestId()).isEqualTo("r1");
     }
@@ -37,10 +39,22 @@ class GlobalExceptionHandlerTest {
 
         var response = handler.handleBadRequest(exception, request);
 
-        assertThat(response.getStatusCode().value()).isEqualTo(400);
+        assertThat(response.getStatusCode().value()).isEqualTo(200);
         assertThat(response.getBody().code()).isEqualTo(ResultCode.BAD_REQUEST.code());
     }
 
+    @Test
+    void recordsBusinessFailureMetricByFiniteResultCode() {
+        SimpleMeterRegistry registry = new SimpleMeterRegistry();
+        ReflectionTestUtils.setField(handler, "meterRegistry", registry);
+
+        handler.handleBusiness(new BizException(ResultCode.CONFLICT, "duplicate"),
+                new MockHttpServletRequest());
+
+        assertThat(registry.get("baiyue.api.business.failures")
+                .tag("code", ResultCode.CONFLICT.code()).counter().count()).isEqualTo(1.0);
+    }
+
     private void paging(long page) {
     }
 }