Spring Boot 404错误全面解析与解决方案

@Controller
public class UserController {

    @RequestMapping("/user")
    public String getUserPage() {
        return "userProfile"; // 对应 templates/userProfile.html
    }
}

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Controller
@ResponseBody
public @interface RestController {
}

@RestController
public class ApiUserController {

    @GetMapping("/api/users")
    public List<User> getUsers() {
        return userService.findAll();
    }
}

graph TD
    A[新建控制器类] --> B{是否主要用于返回JSON/XML?}
    B -- 是 --> C[使用@RestController]
    B -- 否 --> D{是否需要返回HTML页面?}
    D -- 是 --> E[使用@Controller + 模板引擎]
    D -- 否 --> F[考虑是否需@ResponseBody混合使用]
    F --> G[使用@Controller并在方法上加@ResponseBody]

@RestController
@RequestMapping("/users")
public class UserResource {

    private final UserService userService;

    public UserResource(UserService userService) {
        this.userService = userService;
    }

    @GetMapping
    public ResponseEntity<List<User>> getAllUsers() {
        List<User> users = userService.findAll();
        return ResponseEntity.ok(users);
    }

    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        return userService.findById(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    public ResponseEntity<User> createUser(@Valid @RequestBody User user) {
        User saved = userService.save(user);
        return ResponseEntity.status(HttpStatus.CREATED).body(saved);
    }

    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(@PathVariable Long id, @Valid @RequestBody User user) {
        if (!userService.exists(id)) {
            return ResponseEntity.notFound().build();
        }
        user.setId(id);
        User updated = userService.update(user);
        return ResponseEntity.ok(updated);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        if (!userService.exists(id)) {
            return ResponseEntity.notFound().build();
        }
        userService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

@RequestMapping(value = "/data", method = RequestMethod.GET)
// 等价于
@RequestMapping(path = "/data", method = RequestMethod.GET)

@RequestMapping(path = {"/users", "/members"}, method = RequestMethod.GET)
public List<User> getAllEntities() {
    return service.findAll();
}

@RestController
@RequestMapping("/api")
public class ProductController {

    @RequestMapping("/products")  // 实际路径：/api/products
    public List<Product> getProducts() {
        return productService.list();
    }
}

@RequestMapping(path = "/login", method = RequestMethod.POST)
public String login(@RequestBody LoginRequest req) {
    authService.authenticate(req);
    return "success";
}

@PostMapping("/login") // 等价于 @RequestMapping(..., method = POST)

@RequestMapping(
    path = "/data",
    method = RequestMethod.POST,
    consumes = MediaType.APPLICATION_JSON_VALUE,
    produces = MediaType.APPLICATION_XML_VALUE
)
public @ResponseBody UserData processData(@RequestBody UserData input) {
    return transform(input);
}

@GetMapping("/users/new")           // 优先级最高
public String newUserForm() { ... }

@GetMapping("/users/{id}")          // 中等优先级
public User getUser(@PathVariable String id) { ... }

@GetMapping("/users/*")             // 最低优先级
public String matchWildcard() { ... }

graph LR
    A[收到请求: /users/new] --> B{是否存在精确匹配?}
    B -- 是 --> C[执行精确路径方法]
    B -- 否 --> D{是否存在URI变量匹配?}
    D -- 是 --> E[执行模板方法]
    D -- 否 --> F{是否存在通配符匹配?}
    F -- 是 --> G[执行通配符方法]
    F -- 否 --> H[返回404]

@RestController
@RequestMapping(produces = "application/json")
public class OrderController {

    @RequestMapping(path = "/orders", method = RequestMethod.GET)
    public List<Order> listOrders() { ... }
}

@RestController
@RequestMapping("/books")
public class BookController {

    private final Map<Long, Book> bookStore = new ConcurrentHashMap<>();
    private long nextId = 1;

    @GetMapping
    public ResponseEntity<List<Book>> getAllBooks() {
        return ResponseEntity.ok(new ArrayList<>(bookStore.values()));
    }

    @PostMapping
    public ResponseEntity<Book> createBook(@Valid @RequestBody Book book) {
        book.setId(nextId++);
        bookStore.put(book.getId(), book);
        return ResponseEntity.status(HttpStatus.CREATED).body(book);
    }
}

public class Book {
    private Long id;
    private String title;
    private String author;

    // getters and setters...
}

{
  "title": "Spring in Action",
  "author": "Craig Walls"
}

{
  "id": 1,
  "title": "Spring in Action",
  "author": "Craig Walls"
}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@RequestMapping(method = RequestMethod.GET)
public @interface GetMapping {
    @AliasFor(annotation = RequestMapping.class, attribute = "value")
    String[] value() default {};

    @AliasFor(annotation = RequestMapping.class, attribute = "path")
    String[] path() default {};
}

graph TD
    A[启动Spring应用] --> B{扫描@Component类}
    B --> C[发现@Controller或@RestController]
    C --> D[遍历其中的所有public方法]
    D --> E{方法是否标注映射注解?}
    E -- 是 --> F[解析@GetMapping/@PostMapping等]
    F --> G[通过反射获取元注解@RequestMapping]
    G --> H[提取value/path + method组合]
    H --> I[生成RequestCondition实例]
    I --> J[注册至HandlerMapping映射表]
    J --> K[等待DispatcherServlet调用]
    E -- 否 --> L[跳过该方法]

@GetMapping(path = "/users", produces = MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
public List<User> getAllUsers() {
    return userService.findAll();
}

@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    User user = userService.findById(id);
    return user != null ? 
        ResponseEntity.ok(user) : 
        ResponseEntity.notFound().build();
}

@GetMapping("/orders/{orderId}/items/{itemId}")
public Item getItem(
    @PathVariable("orderId") Long orderId,
    @PathVariable("itemId") Long itemId) {
    // ...
}

@GetMapping("/products/{category:[a-z]+}/{productId:\\d+}")
public Product getProduct(
    @PathVariable String category,
    @PathVariable Long productId) {
    return productService.findByCategoryAndId(category, productId);
}

@RestController
public class UserController {

    @GetMapping("/users")
    public String listUsers() {
        return "user list";
    }
}

@GetMapping("/API/Users")  // 注意大写
public String apiUsers() { ... }

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer.setCaseSensitive(false); // 关闭大小写敏感
    }
}

错误：GET /search?keyword=测试
正确：GET /search?keyword=%E6%B5%8B%E8%AF%95

@RestController
@RequestMapping("/api/v1")
public class UserApiController {

    private final UserService userService;

    public UserApiController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/users")
    public ResponseEntity<List<User>> getAllUsers(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "10") int size) {
        List<User> users = userService.paginate(page, size);
        return ResponseEntity.ok(users);
    }

    @PostMapping("/users")
    public ResponseEntity<User> createUser(@RequestBody @Valid UserCreationDto dto) {
        User saved = userService.create(dto);
        return ResponseEntity.status(HttpStatus.CREATED).body(saved);
    }

    @GetMapping("/users/{id}")
    public ResponseEntity<User> getUserById(@PathVariable("id") @Min(1) Long id) {
        return userService.findById(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }

    @PutMapping("/users/{id}")
    public ResponseEntity<User> updateUser(
            @PathVariable Long id,
            @RequestBody @Valid UserUpdateDto dto) {
        if (!userService.exists(id)) {
            return ResponseEntity.notFound().build();
        }
        User updated = userService.update(id, dto);
        return ResponseEntity.ok(updated);
    }

    @DeleteMapping("/users/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        if (!userService.deleteById(id)) {
            return ResponseEntity.notFound().build();
        }
        return ResponseEntity.noContent().build(); // 204
    }
}

Mapped "{[/api/v1/users],methods=[GET]}" onto public ...
Mapped "{[/api/v1/users],methods=[POST]}" onto public ...
Mapped "{[/api/v1/users/{id}],methods=[GET]}" onto public ...

registry.addResourceHandler("/**")
        .addResourceLocations("classpath:/META-INF/resources/",
                              "classpath:/resources/",
                              "classpath:/static/",
                              "classpath:/public/");

src/
 └── main/
     └── resources/
         ├── static/
         │   └── css/
         │       └── style.css
         ├── public/
         │   └── js/
         │       └── app.js
         ├── resources/
         │   └── images/
         │       └── logo.png
         └── META-INF/
             └── resources/
                 └── favicon.ico

flowchart TD
    A[HTTP Request Received] --> B{Has Matching @RequestMapping?}
    B -- Yes --> C[Invoke Controller Method]
    B -- No --> D[Trigger ResourceHttpRequestHandler]
    D --> E[Loop Through Resource Locations]
    E --> F{File Exists in Location?}
    F -- No --> G[Next Location]
    F -- Yes --> H[Check If Modified Since Last Request]
    H --> I{Resource Unchanged?}
    I -- Yes --> J[Return 304 Not Modified]
    I -- No --> K[Read File Stream]
    K --> L[Set Content-Type & Headers]
    L --> M[Write Response Body]
    G --> N{All Locations Checked?}
    N -- No --> E
    N -- Yes --> O[Return 404 Not Found]

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**")
                .addResourceLocations(
                    "classpath:/META-INF/resources/",
                    "classpath:/resources/",
                    "classpath:/static/",
                    "classpath:/public/"
                )
                .setCachePeriod(3600) // 缓存1小时
                .resourceChain(true); // 启用资源链（如gzip压缩）
    }
}

spring:
  resources:
    static-locations: 
      - classpath:/custom-static/
      - file:/var/www/html/
      - classpath:/META-INF/resources/webjars/

Mapped URL path [/webjars/**] onto handler of type [class org.springframework.web.servlet.resource.ResourceHttpRequestHandler]
Mapped URL path [/**] onto handler of type [class org.springframework.web.servlet.resource.ResourceHttpRequestHandler]

spring:
  resources:
    static-locations:
      - classpath:/fallback/
      - classpath:/primary/

@Configuration
@ConditionalOnProperty(prefix = "spring.resources", name = "static-locations")
public class CustomStaticResourceConfig implements WebMvcConfigurer {

    @Value("#{'${spring.resources.static-locations}'.split(',')}")
    private List<String> staticLocations;

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        String[] locations = staticLocations.stream()
                .map(String::trim)
                .toArray(String[]::new);

        registry.addResourceHandler("/**")
                .addResourceLocations(locations)
                .setCachePeriod(60 * 60) // 1小时缓存
                .resourceChain(true);
    }
}

src/main/resources/
├── index.html        ← 错误：不在默认路径内
├── config/
│   └── application.yml
└── static/
    └── css/
        └── main.css

@Component
public class AuthInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        String token = request.getHeader("Authorization");
        if (token == null || !token.startsWith("Bearer ")) {
            response.setStatus(401);
            return false;
        }
        return true;
    }
}

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Autowired
    private AuthInterceptor authInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(authInterceptor)
                .excludePathPatterns("/css/**", "/js/**", "/images/**", "/**/*.ico", "/swagger-ui/**");
    }
}

spring:
  resources:
    static-locations: classpath:/frontend/

com.example.demo
├── DemoApplication.java              // 启动类
├── controller
│   └── UserController.java           // @RestController
├── service
│   └── UserService.java              // @Service
└── model
    └── User.java

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

package com.example.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @GetMapping("/users")
    public String listUsers() {
        return "{'users': ['Alice', 'Bob']}";
    }
}

com.example.controllers.UserController  // 与demo平级

o.s.w.s.handler.SimpleUrlHandlerMapping  : Mapped URL path [/users] onto handler ...

graph TD
    A[启动类 DemoApplication] --> B{所在包路径?}
    B --> C["com.example.demo"]
    C --> D[扫描子包: controller, service, repository]
    D --> E[发现 @RestController -> 注册为Handler]
    F[外部包 com.example.external] --> G[不在扫描范围内]
    G --> H[Controller未注册 → 404错误]

com.example
├── common
│   └── BaseController.java
├── demo
│   └── DemoApplication.java
└── api
    └── UserApiController.java

package com.example.api;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserApiController {

    @GetMapping("/api/users")
    public String getUsers() {
        return "API Users List";
    }
}

package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

@SpringBootApplication
@ComponentScan(basePackages = {
    "com.example.demo",
    "com.example.api",
    "com.example.common"
})
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

@ComponentScan(basePackages = {"com.example.service", "com.example.controller", "com.example.repository"})

parent-project/
├── user-module/
│   └── src/main/java/com/company/user/UserController.java
├── order-module/
│   └── src/main/java/com/company/order/OrderService.java
└── main-app/
    └── src/main/java/com/company/app/DemoApplication.java

@SpringBootApplication
@ComponentScan(basePackages = {
    "com.company.user", 
    "com.company.order", 
    "com.company.app"
})
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

@ComponentScan(basePackageClasses = {UserController.class, OrderService.class})

@ComponentScan(
    basePackages = "com.example",
    excludeFilters = @ComponentScan.Filter(
        type = FilterType.ANNOTATION,
        classes = IgnoreThis.class
    )
)

@RestController
@RequestMapping("/debug")
public class DebugController {
    @GetMapping("/ping")
    public String ping() { return "pong"; }
}

@ConditionalOnProperty(name = "app.debug-mode", havingValue = "false")
@ComponentScan(excludeFilters = @Filter(
    type = FilterType.ASSIGNABLE_TYPE,
    classes = DebugController.class

@SpringBootApplication
@ComponentScan(
    basePackages = "com.example",
    excludeFilters = @ComponentScan.Filter(
        type = FilterType.ASSIGNABLE_TYPE,
        classes = DebugController.class
    )
)
public class DemoApplication { ... }

# application.yml
logging:
  level:
    org.springframework.context.annotation: DEBUG
    org.springframework.web.servlet.mvc.method.annotation: DEBUG

DEBUG [main] AnnotationConfigApplicationContext:657 - Registering component class: class com.example.controller.UserController
DEBUG [main] ClassPathScanningCandidateComponentProvider:258 - Identified candidate component: file [...UserController.class]
INFO  [main] RequestMappingHandlerMapping:288 - Mapped "{[/users],methods=[GET]}" onto public java.lang.String com.example.controller.UserController.listUsers()

<modules>
    <module>user-service</module>
    <module>order-service</module>
    <module>gateway</module>
</modules>

@SpringBootApplication
@ComponentScan({
    "com.company.userservice.controller",
    "com.company.orderservice.controller",
    "com.company.gateway.controller"
})
public class GatewayApplication { ... }

@ComponentScan(basePackageClasses = {
    UserController.class,
    OrderController.class
})

<dependencies>
    <dependency>
        <groupId>com.company</groupId>
        <artifactId>user-service</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

@SpringBootApplication
@ComponentScan(basePackages = {"com.example.app", "com.example.api"})
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

flowchart TD
    A[出现404错误] --> B{检查Controller是否被注册}
    B --> C[查看启动日志是否有Mapped日志]
    C -->|无| D[检查启动类包路径]
    D --> E[Controller是否在子包中?]
    E -->|否| F[方案一: 提升启动类位置]
    E -->|否| G[方案二: 添加@ComponentScan]
    G --> H[指定basePackages或basePackageClasses]
    H --> I[重启应用验证]
    I --> J[成功响应 → 问题解决]
    C -->|有| K[排查其他原因: 路径拼写、method限定等]

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@SpringBootConfiguration
@EnableAutoConfiguration
@ComponentScan(excludeFilters = { @Filter(type = FilterType.CUSTOM, classes = TypeExcludeFilter.class),
        @Filter(type = FilterType.CUSTOM, classes = AutoConfigurationExcludeFilter.class) })
public @interface SpringBootApplication {
    // 可选排除自动配置类
    Class<?>[] exclude() default {};

    String[] excludeName() default {};
}

@Configuration
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

flowchart TD
    A[启动类标注@SpringBootApplication] --> B{解析复合注解}
    B --> C["@Configuration: 标识为配置类"]
    B --> D["@EnableAutoConfiguration: 加载自动配置"]
    B --> E["@ComponentScan: 扫描@Controller等组件"]
    D --> F["读取META-INF/spring.factories"]
    F --> G["条件化加载WebMvcAutoConfiguration"]
    G --> H["注册DispatcherServlet、HandlerMapping等"]
    E --> I["发现UserController等控制器"]
    I --> J["注册@RequestMapping映射关系"]
    H & J --> K[请求可被正确路由]

# META-INF/spring.factories
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration,\
org.springframework.boot.autoconfigure.data.jpa.JpaRepositoriesAutoConfiguration,\
org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration

@Configuration(proxyBeanMethods = false)
@ConditionalOnWebApplication(type = Type.SERVLET)
@ConditionalOnClass({ Servlet.class, DispatcherServlet.class, WebMvcConfigurer.class })
@ConditionalOnMissingBean(WebMvcConfigurationSupport.class)
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE + 10)
public class WebMvcAutoConfiguration {
    // ...
}

$ java -jar myapp.jar --debug

AUTO-CONFIGURATION REPORT

Positive matches:
   DispatcherServletAutoConfiguration matched:
      - @ConditionalOnClass found required class 'org.springframework.web.servlet.DispatcherServlet'

Negative matches:
   WebMvcAutoConfiguration:
      - @ConditionalOnMissingBean (types: org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport; SearchStrategy: all) found beans: customWebConfig

@SpringBootApplication(exclude = {
    DataSourceAutoConfiguration.class,
    HibernateJpaAutoConfiguration.class
})
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

@Configuration
public class CustomWebConfig extends WebMvcConfigurationSupport {
    @Override
    protected void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("*")
                .allowedMethods("GET", "POST");
    }
}

@SpringBootApplication(exclude = { WebMvcAutoConfiguration.class })
// 显式排除，避免条件冲突
public class Application { /* ... */ }

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/**")
            .addResourceLocations("classpath:/static/");
}

@Configuration
public class CustomWebConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**").allowedOrigins("*");
    }

    // 不覆盖其他方法，保留自动配置行为
}

@SpringBootApplication(exclude = {
    EmbeddedWebServerFactoryCustomizerAutoConfiguration.class,
    DispatcherServletAutoConfiguration.class
})

@Autowired
private Environment environment;

@PostConstruct
public void checkEnvironment() {
    System.out.println("Active profiles: " + Arrays.toString(environment.getActiveProfiles()));
    System.out.println("Web application type: " + 
        ((AbstractApplicationContext)applicationContext).getBeanFactory().getTypeConverter());
}

public static void main(String[] args) {
    SpringApplication app = new SpringApplication(MyApplication.class);
    app.setWebApplicationType(WebApplicationType.SERVLET); // 或 REACTIVE / NONE
    app.run(args);
}

@SpringBootApplication(exclude = {
    HttpMessageConvertersAutoConfiguration.class,
    WebMvcAutoConfiguration.class
})
public class BadApplication { }

Mapped "{[/users], methods=[GET]}" onto public java.util.List<...> UserController.getAllUsers()

// module-user/src/main/java/com/example/user/UserApp.java
@SpringBootApplication
public class UserApp { }

// module-order/src/main/java/com/example/order/OrderApp.java
@SpringBootApplication
public class OrderApp { }

Found multiple @SpringBootConfiguration annotated classes

Starting com.example.DemoApplication using Java ...
No active profile set, falling back to 1 default profile: "default"
Registering beans for JMX exposure on startup
Mapped URL path [/api/users] onto method [public User com.example.UserController.getUser(...)]
Tomcat started on port(s): 8080 (http) with context path ''
Started DemoApplication in 3.2 seconds

// ❌ 错误写法
@SpringBootApplication(exclude = WebMvcAutoConfiguration.class)

// ✅ 正确做法
@SpringBootApplication // 保持默认

@Configuration
public class MyWebConfig implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new LoggingInterceptor())
                .addPathPatterns("/api/**");
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/docs/**")
                .addResourceLocations("classpath:/docs/");
    }
}

@RestController
public class TestController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello World!";
    }
}

// BasicErrorController 默认实现片段（简化）
@Controller
@RequestMapping("${server.error.path:${error.path:/error}}")
public class BasicErrorController extends AbstractErrorController {

    @RequestMapping
    public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) {
        Map<String, Object> body = getErrorAttributes(request, isIncludeStackTrace(request, MediaType.ALL));
        HttpStatus status = getStatus(request);
        return new ResponseEntity<>(body, status);
    }
}

@Component
public class CustomErrorController implements ErrorController {

    private static final String ERROR_PATH = "/error";

    @Override
    public String getErrorPath() {
        return ERROR_PATH;
    }

    @RequestMapping(ERROR_PATH)
    public ResponseEntity<ErrorResponse> handleError(HttpServletRequest request) {
        Integer statusCode = (Integer) request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
        String requestUri = (String) request.getAttribute(RequestDispatcher.ERROR_REQUEST_URI);

        ErrorResponse response = new ErrorResponse();
        response.setTimestamp(LocalDateTime.now());
        response.setStatus(statusCode != null ? statusCode : 500);
        response.setError("Resource Not Found");
        response.setMessage("The requested resource '" + requestUri + "' was not found.");
        response.setPath(requestUri);

        // 日志记录
        System.out.println("404 Detected: " + requestUri);

        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(response);
    }
}

// 统一错误响应体
class ErrorResponse {
    private LocalDateTime timestamp;
    private int status;
    private String error;
    private String message;
    private String path;

    // getter/setter 省略
}

{
  "timestamp": "2025-04-05T10:30:00",
  "status": 404,
  "error": "Resource Not Found",
  "message": "The requested resource '/api/v1/nonexist' was not found.",
  "path": "/api/v1/nonexist"
}

src/
 └── main/
     └── resources/
         └── templates/
             └── error/
                 ├── 404.html
                 └── 5xx.html

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head><title>Page Not Found</title></head>
<body>
<h1>Oops! Page Not Found (404)</h1>
<p><strong>Requested URL:</strong> <span th:text="${path}">/unknown</span></p>
<p><strong>Error:</strong> <span th:text="${error}">Not Found</span></p>
<p><strong>Time:</strong> <span th:text="${timestamp}"></span></p>
<a href="/" rel="external nofollow" >← Go Home</a>
</body>
</html>

@ControllerAdvice
public class ErrorHandlingAdvice {

    @ModelAttribute("appName")
    public String appName() {
        return "MySpringBootApp";
    }

    @ExceptionHandler(NoHandlerFoundException.class)
    public String handle404(Model model, HttpServletRequest request) {
        model.addAttribute("path", request.getRequestURI());
        return "error/404";
    }
}

spring:
  mvc:
    throw-exception-if-no-handler-found: true
  web:
    resources:
      add-mappings: true

@Aspect
@Component
public class ErrorLoggingAspect {

    private static final Logger log = LoggerFactory.getLogger(ErrorLoggingAspect.class);

    @AfterThrowing(pointcut = "within(org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler+)", throwing = "ex")
    public void logNotFoundError(JoinPoint jp, Exception ex) {
        ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.currentRequestAttributes();
        HttpServletRequest request = attributes.getRequest();

        if (ex instanceof NoHandlerFoundException || 
            (ex.getCause() instanceof NoHandlerFoundException)) {
            Map<String, Object> logData = new HashMap<>();
            logData.put("timestamp", LocalDateTime.now());
            logData.put("method", request.getMethod());
            logData.put("uri", request.getRequestURI());
            logData.put("remoteAddr", request.getRemoteAddr());
            logData.put("userAgent", request.getHeader("User-Agent"));
            logData.put("exception", ex.getClass().getSimpleName());
            logData.put("stackTrace", Arrays.toString(ex.getStackTrace()).substring(0, 200));

            log.warn("404 Request Intercepted: {}", logData);
        }
    }
}

@RestController
public class MetricsController {

    @Value("${server.error.include-message:false}")
    private boolean includeMessage;

    @GetMapping("/actuator/errors-count")
    public Map<String, Long> getErrorCounts() {
        // 实际应从 MeterRegistry 获取 counter
        return Map.of(
            "404_count", 128L,
            "500_count", 12L,
            "total_errors", 140L
        );
    }
}

graph TD
    A[Client Request /unknown] --> B{Handler Found?}
    B -- No --> C[Forward to /error]
    C --> D{Accept: json?}
    D -- Yes --> E[Return JSON via CustomErrorController]
    D -- No --> F[Render 404.html via Thymeleaf]
    E --> G[Log with AOP & Send to Monitoring]
    F --> G
    G --> H[Response Sent]