public interface HandlerInterceptor {
    
    // 1. Controller 方法執(zhí)行前調(diào)用
    default boolean preHandle(HttpServletRequest request,
                              HttpServletResponse response,
                              Object handler) throws Exception {
        return true; // 返回 true 繼續(xù)執(zhí)行；false 中斷請(qǐng)求
    }

    // 2. Controller 方法執(zhí)行后、視圖渲染前調(diào)用
    default void postHandle(HttpServletRequest request,
                            HttpServletResponse response,
                            Object handler,
                            @Nullable ModelAndView modelAndView) throws Exception {
    }

    // 3. 整個(gè)請(qǐng)求完成（包括視圖渲染）后調(diào)用
    default void afterCompletion(HttpServletRequest request,
                                 HttpServletResponse response,
                                 Object handler,
                                 @Nullable Exception ex) throws Exception {
    }
}

// src/main/java/com/example/demo/interceptor/AuthLogInterceptor.java
package com.example.demo.interceptor;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;

import java.util.concurrent.TimeUnit;

/**
 * 統(tǒng)一認(rèn)證與請(qǐng)求日志攔截器
 * <p>
 * 功能：
 * 1. 記錄請(qǐng)求入口日志（含 Controller 類/方法名）
 * 2. 校驗(yàn)用戶登錄狀態(tài)（Session-based）
 * 3. 統(tǒng)計(jì)請(qǐng)求耗時(shí)并記錄出口日志
 * 4. 清理 ThreadLocal 資源
 */
@Component
public class AuthLogInterceptor implements HandlerInterceptor {

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

    // 使用 ThreadLocal 存儲(chǔ)請(qǐng)求開始時(shí)間（線程安全）
    private final ThreadLocal<Long> requestStartTime = new ThreadLocal<>();

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) throws Exception {

        long startTime = System.currentTimeMillis();
        requestStartTime.set(startTime);

        String uri = request.getRequestURI();
        String method = request.getMethod();
        String clientIp = getClientIpAddress(request);

        // 識(shí)別是否為 Controller 方法
        if (handler instanceof HandlerMethod handlerMethod) {
            String className = handlerMethod.getBeanType().getSimpleName();
            String methodName = handlerMethod.getMethod().getName();
            log.info(">>> [{}] {} from {} -> {}.{}", method, uri, clientIp, className, methodName);
        } else {
            log.info(">>> [{}] {} from {} (Non-controller handler)", method, uri, clientIp);
        }

        // === 登錄狀態(tài)校驗(yàn) ===
        Object userId = request.getSession().getAttribute("user_id");
        if (userId == null) {
            handleUnauthenticated(request, response);
            return false; // 中斷請(qǐng)求
        }

        log.debug("? Authenticated user [{}] accessing [{}]", userId, uri);
        return true;
    }

    @Override
    public void postHandle(HttpServletRequest request,
                           HttpServletResponse response,
                           Object handler,
                           org.springframework.web.servlet.ModelAndView modelAndView) {
        // 示例：向所有 Thymeleaf 頁(yè)面添加服務(wù)器時(shí)間
        if (modelAndView != null) {
            modelAndView.addObject("serverTime", System.currentTimeMillis());
        }
    }

    @Override
    public void afterCompletion(HttpServletRequest request,
                                HttpServletResponse response,
                                Object handler,
                                Exception ex) {
        try {
            Long startTime = requestStartTime.get();
            if (startTime == null) return;

            long duration = System.currentTimeMillis() - startTime;
            String uri = request.getRequestURI();
            int status = response.getStatus();

            if (ex != null) {
                log.error("? Request [{}] failed in {}ms, status: {}, exception: {}", 
                         uri, duration, status, ex.getMessage(), ex);
            } else {
                log.info("<<< Request [{}] completed in {}ms, status: {}", uri, duration, status);
            }
        } finally {
            // ?? 必須清理 ThreadLocal！
            requestStartTime.remove();
        }
    }

    /**
     * 獲取客戶端真實(shí) IP（考慮代理）
     */
    private String getClientIpAddress(HttpServletRequest request) {
        String xForwardedFor = request.getHeader("X-Forwarded-For");
        if (xForwardedFor != null && !xForwardedFor.isEmpty()) {
            return xForwardedFor.split(",")[0].trim();
        }
        return request.getRemoteAddr();
    }

    /**
     * 處理未認(rèn)證請(qǐng)求
     */
    private void handleUnauthenticated(HttpServletRequest request, HttpServletResponse response) throws Exception {
        if (isAjaxRequest(request)) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.setContentType("application/json;charset=UTF-8");
            response.getWriter().write("""
                {"code":401,"message":"Authentication required","timestamp":%d}
                """.formatted(System.currentTimeMillis()));
        } else {
            response.sendRedirect("/login");
        }
    }

    /**
     * 判斷是否為 AJAX 請(qǐng)求
     */
    private boolean isAjaxRequest(HttpServletRequest request) {
        return "XMLHttpRequest".equals(request.getHeader("X-Requested-With")) ||
               (request.getHeader("Accept") != null && 
                request.getHeader("Accept").contains("application/json"));
    }
}

// src/main/java/com/example/demo/config/WebMvcConfig.java
package com.example.demo.config;

import com.example.demo.interceptor.AuthLogInterceptor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * Spring MVC 全局配置類
 */
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Autowired
    private AuthLogInterceptor authLogInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(authLogInterceptor)
                // 攔截需要認(rèn)證的路徑
                .addPathPatterns(
                    "/admin/**",
                    "/api/v1/**",
                    "/user/profile",
                    "/order/**"
                )
                // 排除公開路徑
                .excludePathPatterns(
                    "/",
                    "/login",
                    "/register",
                    "/public/**",
                    "/static/**",
                    "/webjars/**",
                    "/error",
                    // Swagger 文檔（開發(fā)環(huán)境）
                    "/swagger-ui/**",
                    "/v3/api-docs/**",
                    // Actuator 健康檢查（生產(chǎn)環(huán)境）
                    "/actuator/health"
                )
                // 設(shè)置攔截器優(yōu)先級(jí)（數(shù)值越小，優(yōu)先級(jí)越高）
                .order(0);
    }
}

@Component
public class PermissionInterceptor implements HandlerInterceptor {

    @Autowired
    private PermissionService permissionService;

    @Override
    public boolean preHandle(HttpServletRequest req, HttpServletResponse res, Object handler) {
        String uri = req.getRequestURI();
        String userId = (String) req.getSession().getAttribute("user_id");
        
        if (!permissionService.hasAccess(userId, uri)) {
            res.sendError(HttpServletResponse.SC_FORBIDDEN, "Insufficient permissions");
            return false;
        }
        return true;
    }
}

registry.addInterceptor(loggingInterceptor).order(10);   // 后執(zhí)行 preHandle，先執(zhí)行 postHandle
registry.addInterceptor(authInterceptor).order(0);       // 先執(zhí)行 preHandle，后執(zhí)行 postHandle

@Override
public boolean preHandle(HttpServletRequest request, ...) {
    String token = extractToken(request);
    if (token == null || !jwtUtil.validate(token)) {
        response.sendError(HttpServletResponse.SC_UNAUTHORIZED);
        return false;
    }
    // 將用戶信息存入 ThreadLocal 或 SecurityContext
    return true;
}

@Autowired
private RedisTemplate<String, Integer> redis;

@Override
public boolean preHandle(...) {
    String key = "rate_limit:" + getClientIp(request) + ":" + uri;
    Integer count = redis.opsForValue().increment(key);
    if (count == 1) {
        redis.expire(key, 60, TimeUnit.SECONDS); // 1分鐘窗口
    }
    if (count > 10) { // 超過10次/分鐘
        response.sendError(429, "Too Many Requests");
        return false;
    }
    return true;
}

@Override
public boolean preHandle(...) {
    String tenantId = resolveTenantId(request); // 從 Header/域名解析
    TenantContext.setCurrentTenant(tenantId);   // 存入 ThreadLocal
    return true;
}

@Override
public void afterCompletion(...) {
    TenantContext.clear(); // 清理
}

if (handler instanceof HandlerMethod hm) {
    MyAnnotation anno = hm.getMethodAnnotation(MyAnnotation.class);
    if (anno != null) {
        // 處理注解邏輯
    }
}