com.example.app
├── config/        # 配置類(lèi)
├── controller/
│   ├── v1/        # API版本控制
│   │   ├── UserController.java
│   │   ├── ProductController.java
│   ├── v2/        # 新版本API
│   └── admin/     # 管理端接口
├── service/       # 業(yè)務(wù)邏輯層
├── repository/    # 數(shù)據(jù)訪問(wèn)層
└── model/         # 數(shù)據(jù)模型

public class ApiResponse<T> {
    private int code;
    private String message;
    private T data;
    private long timestamp;
    // 成功響應(yīng)
    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>(200, "success", data);
    }
    // 失敗響應(yīng)
    public static <T> ApiResponse<T> fail(int code, String message) {
        return new ApiResponse<>(code, message, null);
    }
    // 構(gòu)造方法、getter、setter省略
}

@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 {
    // v1版本接口
}
@RestController
@RequestMapping("/api/v2/users")
public class UserControllerV2 {
    // v2版本接口
}

@GetMapping(value = "/users", headers = "X-API-VERSION=1")
public ApiResponse<List<User>> getUsersV1() { ... }
@GetMapping(value = "/users", headers = "X-API-VERSION=2")
public ApiResponse<List<UserDto>> getUsersV2() { ... }

@PostMapping("/users")
public ApiResponse<User> createUser(
    @Valid @RequestBody UserCreateRequest request) {
    // 業(yè)務(wù)處理
}
// 請(qǐng)求體定義
public class UserCreateRequest {
    @NotBlank(message = "用戶名不能為空")
    @Size(min = 4, max = 20, message = "用戶名長(zhǎng)度4-20個(gè)字符")
    private String username;
    @Email(message = "郵箱格式不正確")
    private String email;
    @Pattern(regexp = "^(?=.*[A-Za-z])(?=.*\\d)[A-Za-z\\d]{8,}$", 
             message = "密碼至少8位，包含字母和數(shù)字")
    private String password;
    @NotNull(message = "年齡不能為空")
    @Min(value = 18, message = "年齡必須大于18歲")
    private Integer age;
    // getter/setter
}

public class CurrentUserArgumentResolver implements HandlerMethodArgumentResolver {
    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.hasParameterAnnotation(CurrentUser.class);
    }
    @Override
    public Object resolveArgument(MethodParameter parameter, 
                                 ModelAndViewContainer mavContainer,
                                 NativeWebRequest webRequest, 
                                 WebDataBinderFactory binderFactory) {
        HttpServletRequest request = (HttpServletRequest) webRequest.getNativeRequest();
        String token = request.getHeader("Authorization");
        return authService.getUserByToken(token);
    }
}
// 注冊(cè)解析器
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(new CurrentUserArgumentResolver());
    }
}
// 使用示例
@GetMapping("/profile")
public ApiResponse<UserProfile> getProfile(@CurrentUser User user) {
    return ApiResponse.success(userService.getProfile(user.getId()));
}

@RestControllerAdvice
public class ResponseWrapper implements ResponseBodyAdvice<Object> {
    @Override
    public boolean supports(MethodParameter returnType, 
                          Class<? extends HttpMessageConverter<?>> converterType) {
        return !returnType.getParameterType().equals(ApiResponse.class);
    }
    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType,
                                MediaType selectedContentType,
                                Class<? extends HttpMessageConverter<?>> selectedConverterType,
                                ServerHttpRequest request, ServerHttpResponse response) {
        if (body instanceof String) {
            // 特殊處理String類(lèi)型返回值
            return JsonUtils.toJson(ApiResponse.success(body));
        }
        return ApiResponse.success(body);
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {
    private static final Logger logger = LoggerFactory.getLogger(GlobalExceptionHandler.class);
    // 處理業(yè)務(wù)異常
    @ExceptionHandler(BusinessException.class)
    public ApiResponse<Void> handleBusinessException(BusinessException e) {
        logger.warn("業(yè)務(wù)異常: {}", e.getMessage());
        return ApiResponse.fail(e.getCode(), e.getMessage());
    }
    // 處理參數(shù)校驗(yàn)異常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ApiResponse<Void> handleValidationException(MethodArgumentNotValidException e) {
        String message = e.getBindingResult().getAllErrors().stream()
            .map(DefaultMessageSourceResolvable::getDefaultMessage)
            .collect(Collectors.joining("; "));
        return ApiResponse.fail(400, message);
    }
    // 處理系統(tǒng)異常
    @ExceptionHandler(Exception.class)
    public ApiResponse<Void> handleException(Exception e) {
        logger.error("系統(tǒng)異常", e);
        return ApiResponse.fail(500, "系統(tǒng)繁忙，請(qǐng)稍后再試");
    }
}

@GetMapping("/export")
public ResponseEntity<Resource> exportData(@RequestParam String type) {
    String filename = "data." + type;
    Resource resource = exportService.exportData(type);
    return ResponseEntity.ok()
        .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + filename + "\"")
        .contentType(MediaType.APPLICATION_OCTET_STREAM)
        .body(resource);
}

@Aspect
@Component
@Slf4j
public class RequestLogAspect {
    @Around("@annotation(org.springframework.web.bind.annotation.RequestMapping)")
    public Object logRequest(ProceedingJoinPoint joinPoint) throws Throwable {
        HttpServletRequest request = ((ServletRequestAttributes) 
            RequestContextHolder.getRequestAttributes()).getRequest();
        long startTime = System.currentTimeMillis();
        Object result = joinPoint.proceed();
        long elapsedTime = System.currentTimeMillis() - startTime;
        log.info("[{}] {} {} - {}ms (params: {})", 
                request.getMethod(),
                request.getRequestURI(),
                request.getRemoteAddr(),
                elapsedTime,
                getParamsString(joinPoint.getArgs()));
        return result;
    }
    private String getParamsString(Object[] args) {
        return Arrays.stream(args)
            .filter(arg -> !(arg instanceof HttpServletRequest || arg instanceof HttpServletResponse))
            .map(Object::toString)
            .collect(Collectors.joining(", "));
    }
}

@Aspect
@Component
@Slf4j
public class SlowRequestAspect {
    @Value("${app.slow-request-threshold:5000}")
    private long threshold;
    @Around("@annotation(org.springframework.web.bind.annotation.RequestMapping)")
    public Object monitorSlowRequest(ProceedingJoinPoint joinPoint) throws Throwable {
        long startTime = System.currentTimeMillis();
        Object result = joinPoint.proceed();
        long elapsedTime = System.currentTimeMillis() - startTime;
        if (elapsedTime > threshold) {
            MethodSignature signature = (MethodSignature) joinPoint.getSignature();
            log.warn("慢接口警告: {} 執(zhí)行時(shí)間: {}ms", 
                    signature.getMethod().getName(), elapsedTime);
        }
        return result;
    }
}

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/api/public/**").permitAll()
            .antMatchers("/api/admin/**").hasRole("ADMIN")
            .antMatchers("/api/user/**").hasAnyRole("USER", "ADMIN")
            .anyRequest().authenticated()
            .and()
            .addFilter(new JwtAuthenticationFilter(authenticationManager()))
            .addFilter(new JwtAuthorizationFilter(authenticationManager()));
    }
}

@RestController
@RequestMapping("/api/admin/users")
@PreAuthorize("hasRole('ADMIN')")
public class UserAdminController {
    @DeleteMapping("/{id}")
    @PreAuthorize("hasAuthority('user:delete')")
    public ApiResponse<Void> deleteUser(@PathVariable Long id) {
        userService.deleteUser(id);
        return ApiResponse.success();
    }
}

@WebMvcTest(UserController.class)
@AutoConfigureMockMvc(addFilters = false) // 禁用安全過(guò)濾器
public class UserControllerTest {
    @Autowired
    private MockMvc mockMvc;
    @MockBean
    private UserService userService;
    @Test
    public void testGetUserById() throws Exception {
        User mockUser = new User(1L, "testUser", "user@test.com");
        when(userService.getUserById(1L)).thenReturn(mockUser);
        mockMvc.perform(get("/api/v1/users/1")
                .contentType(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.code").value(200))
            .andExpect(jsonPath("$.data.username").value("testUser"));
    }
}

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureTestDatabase
public class UserControllerIntegrationTest {
    @Autowired
    private TestRestTemplate restTemplate;
    @Test
    public void testCreateUser() {
        UserCreateRequest request = new UserCreateRequest("newUser", "new@test.com", "password123", 25);
        ResponseEntity<ApiResponse> response = restTemplate.postForEntity(
            "/api/v1/users", 
            request, 
            ApiResponse.class);
        assertEquals(HttpStatus.OK, response.getStatusCode());
        assertNotNull(response.getBody().getData());
    }
}

@RestController
@RequestMapping("/api/async")
public class AsyncController {
    @GetMapping("/data")
    public Callable<ApiResponse<String>> getAsyncData() {
        return () -> {
            Thread.sleep(3000); // 模擬耗時(shí)操作
            return ApiResponse.success("異步處理完成");
        };
    }
    @GetMapping("/deferred")
    public DeferredResult<ApiResponse<String>> getDeferredResult() {
        DeferredResult<ApiResponse<String>> result = new DeferredResult<>(5000L);
        CompletableFuture.runAsync(() -> {
            try {
                Thread.sleep(3000);
                result.setResult(ApiResponse.success("延遲結(jié)果返回"));
            } catch (InterruptedException e) {
                result.setErrorResult(ApiResponse.fail(500, "處理失敗"));
            }
        });
        return result;
    }
}

@GetMapping("/cached")
@ResponseCache(duration = 3600) // 自定義注解
public ApiResponse<List<Product>> getProducts() {
    return ApiResponse.success(productService.getAllProducts());
}
// 自定義緩存注解實(shí)現(xiàn)
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ResponseCache {
    int duration() default 60; // 緩存時(shí)間(秒)
}