Java RESTful 接口开发最佳实践

Java RESTful 接口开发最佳实践 | 极客日志

@RestController
@RequestMapping("/api/v1/users")
public class UserController {
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        User user = userService.findById(id);
        return ResponseEntity.ok(user);
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public User createUser(@Valid @RequestBody UserDTO userDTO) {
        return userService.create(userDTO);
    }

    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @Valid @RequestBody UserDTO userDTO) {
        return userService.update(id, userDTO);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteUser(@PathVariable Long id) {
        userService.delete(id);
    }
}

// 好的 RESTful 设计示例
@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {
    // GET /api/v1/orders - 获取所有订单
    @GetMapping
    public List<Order> getAllOrders(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        return orderService.getOrders(page, size);
    }

    // GET /api/v1/orders/{id} - 获取特定订单
    @GetMapping("/{id}")
    public Order getOrderById(@PathVariable Long id) {
        return orderService.getById(id);
    }

    // GET /api/v1/orders/{id}/items - 获取订单项（子资源）
    @GetMapping("/{id}/items")
    public List<OrderItem> getOrderItems(@PathVariable Long id) {
        return orderService.getOrderItems(id);
    }

    // POST /api/v1/orders - 创建订单
    @PostMapping
    public ResponseEntity<Order> createOrder(@Valid @RequestBody OrderDTO dto) {
        Order created = orderService.create(dto);
        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
                .path("/{id}").buildAndExpand(created.getId()).toUri();
        return ResponseEntity.created(location).body(created);
    }
}

// 1. 多条件查询参数处理
@GetMapping("/search")
public List<User> searchUsers(
        @RequestParam(required = false) String name,
        @RequestParam(required = false) String email,
        @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate startDate,
        @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate endDate,
        @RequestParam(defaultValue = "createdAt") String sortBy,
        @RequestParam(defaultValue = "desc") String direction) {
    Specification<User> spec = UserSpecifications.search(name, email, startDate, endDate);
    Sort sort = direction.equalsIgnoreCase("desc") ? Sort.by(sortBy).descending() : Sort.by(sortBy).ascending();
    return userService.search(spec, sort);
}

// 2. 文件上传处理
@PostMapping("/upload")
public ResponseEntity<String> uploadFile(
        @RequestParam("file") MultipartFile file,
        @RequestParam("category") String category) {
    if (file.isEmpty()) {
        throw new BadRequestException("文件不能为空");
    }
    String filePath = fileStorageService.store(file, category);
    return ResponseEntity.ok("文件上传成功：" + filePath);
}

// 3. 请求/响应体压缩
@PostMapping("/compress")
public ResponseEntity<byte[]> handleCompressedData(@RequestBody byte[] compressedData) throws IOException {
    byte[] decompressed = CompressionUtils.decompress(compressedData);
    // 处理数据...
    byte[] responseData = "处理成功".getBytes();
    byte[] compressedResponse = CompressionUtils.compress(responseData);
    return ResponseEntity.ok().header("Content-Encoding", "gzip").body(compressedResponse);
}

// 1. 基础服务接口
public interface UserService {
    UserDTO createUser(UserCreateDTO dto);
    UserDTO updateUser(Long id, UserUpdateDTO dto);
    UserDTO getUserById(Long id);
    Page<UserDTO> getUsers(UserQueryDTO query, Pageable pageable);
    void deleteUser(Long id);
}

// 2. 服务实现（使用@Transactional）
@Service
@Transactional
@Slf4j
public class UserServiceImpl implements UserService {
    private final UserRepository userRepository;
    private final UserMapper userMapper;
    private final CacheService cacheService;
    private final EmailService emailService;

    // 构造器注入（推荐方式）
    public UserServiceImpl(UserRepository userRepository, UserMapper userMapper, CacheService cacheService, EmailService emailService) {
        this.userRepository = userRepository;
        this.userMapper = userMapper;
        this.cacheService = cacheService;
        this.emailService = emailService;
    }

    @Override
    public UserDTO createUser(UserCreateDTO dto) {
        log.info("创建用户：{}", dto.getEmail());
        // 验证逻辑
        if (userRepository.existsByEmail(dto.getEmail())) {
            throw new BusinessException("邮箱已存在");
        }
        // DTO 转实体
        User user = userMapper.toEntity(dto);
        user.setStatus(UserStatus.ACTIVE);
        user.setCreatedAt(LocalDateTime.now());
        // 保存到数据库
        User savedUser = userRepository.save(user);
        // 清理缓存
        cacheService.evict("users", savedUser.getId());
        // 发送欢迎邮件（异步）
        emailService.sendWelcomeEmail(savedUser.getEmail());
        // 返回 DTO
        return userMapper.toDTO(savedUser);
    }

    @Override
    @Transactional(readOnly = true)
    public UserDTO getUserById(Long id) {
        // 先尝试从缓存获取
        String cacheKey = "user:" + id;
        UserDTO cached = cacheService.get(cacheKey, UserDTO.class);
        if (cached != null) {
            return cached;
        }
        // 缓存未命中，查询数据库
        User user = userRepository.findById(id).orElseThrow(() -> new ResourceNotFoundException("用户不存在"));
        UserDTO dto = userMapper.toDTO(user);
        // 放入缓存
        cacheService.put(cacheKey, dto, Duration.ofMinutes(30));
        return dto;
    }

    @Override
    @Transactional(readOnly = true)
    public Page<UserDTO> getUsers(UserQueryDTO query, Pageable pageable) {
        // 构建查询条件
        Specification<User> spec = buildSpecification(query);
        // 执行分页查询
        Page<User> userPage = userRepository.findAll(spec, pageable);
        // 转换为 DTO
        return userPage.map(userMapper::toDTO);
    }

    private Specification<User> buildSpecification(UserQueryDTO query) {
        return (root, criteriaQuery, criteriaBuilder) -> {
            List<Predicate> predicates = new ArrayList<>();
            if (StringUtils.hasText(query.getName())) {
                predicates.add(criteriaBuilder.like(root.get("name"), "%" + query.getName() + "%"));
            }
            if (query.getStatus() != null) {
                predicates.add(criteriaBuilder.equal(root.get("status"), query.getStatus()));
            }
            if (query.getStartDate() != null) {
                predicates.add(criteriaBuilder.greaterThanOrEqualTo(root.get("createdAt"), query.getStartDate()));
            }
            if (query.getEndDate() != null) {
                predicates.add(criteriaBuilder.lessThanOrEqualTo(root.get("createdAt"), query.getEndDate()));
            }
            return criteriaBuilder.and(predicates.toArray(new Predicate[0]));
        };
    }
}

// 复杂业务事务管理示例
@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository orderRepository;
    private final InventoryService inventoryService;
    private final PaymentService paymentService;
    private final NotificationService notificationService;

    /**
     * 创建订单的复杂业务流程
     * 使用@Transactional 管理事务边界
     */
    @Transactional(rollbackFor = Exception.class)
    public OrderDTO createOrder(OrderCreateDTO dto) {
        // 1. 验证库存
        inventoryService.checkStock(dto.getItems());
        // 2. 扣减库存（独立事务）
        inventoryService.deductStock(dto.getItems());
        try {
            // 3. 创建订单
            Order order = createOrderEntity(dto);
            order = orderRepository.save(order);
            // 4. 调用支付（外部系统，需要补偿机制）
            paymentService.processPayment(order);
            // 5. 更新订单状态
            order.setStatus(OrderStatus.PAID);
            orderRepository.save(order);
            // 6. 发送通知（异步，不影响主事务）
            notificationService.sendOrderConfirmation(order);
            return convertToDTO(order);
        } catch (PaymentException e) {
            // 支付失败，恢复库存
            inventoryService.restoreStock(dto.getItems());
            throw new BusinessException("支付失败：" + e.getMessage());
        }
    }

    /**
     * 使用编程式事务处理特殊场景
     */
    public void batchUpdateOrderStatus(List<Long> orderIds, OrderStatus status) {
        TransactionTemplate transactionTemplate = new TransactionTemplate(transactionManager);
        transactionTemplate.execute(statusParam -> {
            for (Long orderId : orderIds) {
                Order order = orderRepository.findById(orderId).orElseThrow(() -> new ResourceNotFoundException("订单不存在"));
                // 记录状态变更历史
                order.addStatusHistory(order.getStatus(), status, "批量更新");
                // 更新状态
                order.setStatus(status);
                orderRepository.save(order);
                // 每处理 100 条记录提交一次，防止事务过大
                if (orderIds.indexOf(orderId) % 100 == 0) {
                    entityManager.flush();
                    entityManager.clear();
                }
            }
            return null;
        });
    }
}

// 1. 请求 DTO（验证注解）
@Data
public class UserCreateDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 2, max = 50, message = "用户名长度必须在 2-50 之间")
    private String username;

    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;

    @NotBlank(message = "密码不能为空")
    @Pattern(regexp = "^(?=.*[A-Za-z])(?=.*\\d)[A-Za-z\\d@$!%*#?&]{8,}$", message = "密码必须至少 8 位，包含字母和数字")
    private String password;

    @NotNull(message = "角色不能为空")
    private UserRole role;

    @PhoneNumber // 自定义验证注解
    private String phone;
}

// 2. 响应 DTO（嵌套对象）
@Data
@Builder
public class UserDetailDTO {
    private Long id;
    private String username;
    private String email;
    private UserStatus status;
    private LocalDateTime createdAt;
    private List<UserAddressDTO> addresses;
    private UserProfileDTO profile;
}

// 3. 查询参数 DTO
@Data
public class UserQueryDTO {
    private String username;
    private String email;
    private UserStatus status;
    private LocalDateTime startDate;
    private LocalDateTime endDate;
    private String sortField;
    private Sort.Direction sortDirection;

    public Pageable toPageable() {
        if (sortField != null && sortDirection != null) {
            return PageRequest.of(0, 20, Sort.by(sortDirection, sortField));
        }
        return PageRequest.of(0, 20);
    }
}

// 1. 映射器接口
@Mapper(componentModel = "spring", uses = {AddressMapper.class, ProfileMapper.class}, unmappedTargetPolicy = ReportingPolicy.IGNORE)
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    // 简单映射
    User toEntity(UserCreateDTO dto);
    UserDTO toDTO(User entity);

    // 更新映射（忽略空值）
    @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
    void updateEntity(UserUpdateDTO dto, @MappingTarget User entity);

    // 列表映射
    List<UserDTO> toDTOList(List<User> entities);

    // 分页映射
    default Page<UserDTO> toDTOPage(Page<User> page) {
        return page.map(this::toDTO);
    }

    // 自定义映射方法
    @AfterMapping
    default void afterMapping(UserCreateDTO dto, @MappingTarget User user) {
        if (user.getPassword() != null) {
            user.setPassword(passwordEncoder.encode(user.getPassword()));
        }
        user.setCreatedAt(LocalDateTime.now());
    }
}

// 2. 复杂映射配置
@Mapper(componentModel = "spring")
public interface OrderMapper {
    @Mapping(source = "customer.id", target = "customerId")
    @Mapping(source = "customer.name", target = "customerName")
    @Mapping(source = "items", target = "orderItems")
    @Mapping(target = "totalAmount", expression = "java(calculateTotal(order))")
    OrderDTO toDTO(Order order);

    default BigDecimal calculateTotal(Order order) {
        return order.getItems().stream()
                .map(item -> item.getPrice().multiply(BigDecimal.valueOf(item.getQuantity())))
                .reduce(BigDecimal.ZERO, BigDecimal::add);
    }
}

@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {
    // 处理验证异常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationException(MethodArgumentNotValidException ex) {
        List<String> errors = ex.getBindingResult().getFieldErrors().stream()
                .map(error -> error.getField() + ": " + error.getDefaultMessage())
                .collect(Collectors.toList());
        ErrorResponse response = ErrorResponse.builder()
                .timestamp(LocalDateTime.now())
                .status(HttpStatus.BAD_REQUEST.value())
                .error("验证失败")
                .message("请求参数无效")
                .errors(errors)
                .path(getRequestPath())
                .build();
        return ResponseEntity.badRequest().body(response);
    }

    // 处理业务异常
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ErrorResponse> handleBusinessException(BusinessException ex, HttpServletRequest request) {
        ErrorResponse response = ErrorResponse.builder()
                .timestamp(LocalDateTime.now())
                .status(HttpStatus.CONFLICT.value())
                .error("业务错误")
                .message(ex.getMessage())
                .path(request.getRequestURI())
                .build();
        return ResponseEntity.status(HttpStatus.CONFLICT).body(response);
    }

    // 处理资源不存在异常
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFoundException(ResourceNotFoundException ex, HttpServletRequest request) {
        ErrorResponse response = ErrorResponse.builder()
                .timestamp(LocalDateTime.now())
                .status(HttpStatus.NOT_FOUND.value())
                .error("资源未找到")
                .message(ex.getMessage())
                .path(request.getRequestURI())
                .build();
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(response);
    }

    // 处理所有未捕获的异常
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleAllExceptions(Exception ex, HttpServletRequest request) {
        log.error("未处理的异常：", ex);
        ErrorResponse response = ErrorResponse.builder()
                .timestamp(LocalDateTime.now())
                .status(HttpStatus.INTERNAL_SERVER_ERROR.value())
                .error("服务器内部错误")
                .message("系统繁忙，请稍后重试")
                .path(request.getRequestURI())
                .build();
        return ResponseEntity.internalServerError().body(response);
    }

    private String getRequestPath() {
        RequestAttributes attributes = RequestContextHolder.getRequestAttributes();
        if (attributes instanceof ServletRequestAttributes) {
            return ((ServletRequestAttributes) attributes).getRequest().getRequestURI();
        }
        return null;
    }
}

// 错误响应 DTO
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class ErrorResponse {
    private LocalDateTime timestamp;
    private int status;
    private String error;
    private String message;
    private List<String> errors;
    private String path;
}

// 基础业务异常
public abstract class BaseException extends RuntimeException {
    private final String code;
    private final Map<String, Object> data;

    public BaseException(String code, String message) {
        super(message);
        this.code = code;
        this.data = new HashMap<>();
    }

    public BaseException(String code, String message, Throwable cause) {
        super(message, cause);
        this.code = code;
        this.data = new HashMap<>();
    }

    public BaseException withData(String key, Object value) {
        this.data.put(key, value);
        return this;
    }

    public abstract HttpStatus getHttpStatus();
}

// 具体业务异常
public class BusinessException extends BaseException {
    public BusinessException(String message) {
        super("BUSINESS_ERROR", message);
    }

    public BusinessException(String code, String message) {
        super(code, message);
    }

    @Override
    public HttpStatus getHttpStatus() {
        return HttpStatus.CONFLICT;
    }
}

public class ValidationException extends BaseException {
    public ValidationException(String message) {
        super("VALIDATION_ERROR", message);
    }

    @Override
    public HttpStatus getHttpStatus() {
        return HttpStatus.BAD_REQUEST;
    }
}

public class AuthenticationException extends BaseException {
    public AuthenticationException(String message) {
        super("AUTH_ERROR", message);
    }

    @Override
    public HttpStatus getHttpStatus() {
        return HttpStatus.UNAUTHORIZED;
    }
}

// 1. 自定义注解
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = PhoneNumberValidator.class)
@Documented
public @interface PhoneNumber {
    String message() default "手机号码格式不正确";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
    String region() default "CN"; // 支持不同地区
}

// 2. 验证器实现
public class PhoneNumberValidator implements ConstraintValidator<PhoneNumber, String> {
    private String region;
    private static final Map<String, Pattern> REGION_PATTERNS = new HashMap<>();

    static {
        // 中国大陆手机号
        REGION_PATTERNS.put("CN", Pattern.compile("^1[3-9]\\d{9}$"));
        // 美国手机号
        REGION_PATTERNS.put("US", Pattern.compile("^\\(?([0-9]{3})\\)?[-.\\s]?([0-9]{3})[-.\\s]?([0-9]{4})$"));
        // 香港手机号
        REGION_PATTERNS.put("HK", Pattern.compile("^[569]\\d{3}\\d{4}$"));
    }

    @Override
    public void initialize(PhoneNumber constraintAnnotation) {
        this.region = constraintAnnotation.region();
    }

    @Override
    public boolean isValid(String phoneNumber, ConstraintValidatorContext context) {
        if (phoneNumber == null) {
            return true; // 使用@NotNull 处理空值
        }
        Pattern pattern = REGION_PATTERNS.get(region);
        if (pattern == null) {
            throw new IllegalArgumentException("不支持的地区：" + region);
        }
        return pattern.matcher(phoneNumber).matches();
    }
}

// 3. 使用自定义注解
@Data
public class ContactDTO {
    @NotBlank(message = "姓名不能为空")
    private String name;

    @PhoneNumber(region = "CN", message = "请输入有效的中国大陆手机号")
    private String phone;

    @Email(message = "邮箱格式不正确")
    private String email;

    // 跨字段验证
    @AssertTrue(message = "至少提供一种联系方式")
    public boolean isContactInfoProvided() {
        return StringUtils.hasText(phone) || StringUtils.hasText(email);
    }
}

// 1. 定义验证组
public interface ValidationGroups {
    interface Create {}
    interface Update {}
    interface Patch {}
}

// 2. 在 DTO 中使用分组
@Data
public class UserDTO {
    @Null(groups = Create.class, message = "ID 必须为空")
    @NotNull(groups = {Update.class, Patch.class}, message = "ID 不能为空")
    private Long id;

    @NotBlank(groups = Create.class, message = "用户名不能为空")
    @Size(min = 3, max = 50, groups = {Create.class, Update.class})
    private String username;

    @Email(groups = {Create.class, Update.class})
    private String email;

    @NotBlank(groups = Create.class, message = "密码不能为空")
    @Pattern(regexp = "^(?=.*[A-Za-z])(?=.*\\d).{8,}$", groups = Create.class)
    private String password;

    @NotNull(groups = Create.class)
    private UserRole role;
}

// 3. 在控制器中使用分组验证
@RestController
@RequestMapping("/api/users")
public class UserController {
    @PostMapping
    public ResponseEntity<UserDTO> createUser(@Validated(ValidationGroups.Create.class) @RequestBody UserDTO userDTO) {
        // 创建逻辑
    }

    @PutMapping("/{id}")
    public ResponseEntity<UserDTO> updateUser(@PathVariable Long id, @Validated(ValidationGroups.Update.class) @RequestBody UserDTO userDTO) {
        // 更新逻辑
    }

    @PatchMapping("/{id}")
    public ResponseEntity<UserDTO> patchUser(@PathVariable Long id, @Validated(ValidationGroups.Patch.class) @RequestBody UserDTO userDTO) {
        // 部分更新逻辑
    }
}

@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
@RequiredArgsConstructor
public class SecurityConfig {
    private final JwtAuthenticationFilter jwtAuthenticationFilter;
    private final UserDetailsService userDetailsService;
    private final AuthenticationEntryPoint authenticationEntryPoint;
    private final AccessDeniedHandler accessDeniedHandler;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // 禁用 CSRF（REST API 通常不需要）
            .csrf().disable()
            // 会话管理（无状态）
            .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS).and()
            // 异常处理
            .exceptionHandling().authenticationEntryPoint(authenticationEntryPoint).accessDeniedHandler(accessDeniedHandler).and()
            // 授权配置
            .authorizeHttpRequests(auth -> auth
                // 公开接口
                .requestMatchers("/api/auth/**", "/swagger-ui/**", "/v3/api-docs/**", "/actuator/health").permitAll()
                // 需要认证的接口
                .requestMatchers("/api/users/**").hasAnyRole("USER", "ADMIN")
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                // 其他接口需要认证
                .anyRequest().authenticated())
            // 添加 JWT 过滤器
            .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class)
            // 记住我功能（可选）
            .rememberMe().tokenRepository(persistentTokenRepository()).tokenValiditySeconds(86400) // 24 小时
            .and()
            // 安全头配置
            .headers(headers -> headers
                .contentSecurityPolicy("default-src 'self'")
                .frameOptions().sameOrigin());
        return http.build();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }

    @Bean
    public AuthenticationManager authenticationManager(AuthenticationConfiguration config) throws Exception {
        return config.getAuthenticationManager();
    }

    @Bean
    public PersistentTokenRepository persistentTokenRepository() {
        JdbcTokenRepositoryImpl tokenRepository = new JdbcTokenRepositoryImpl();
        tokenRepository.setDataSource(dataSource);
        return tokenRepository;
    }
}

@Component
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {
    private final JwtTokenProvider tokenProvider;
    private final UserDetailsService userDetailsService;

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        try {
            // 从请求头获取 Token
            String token = extractToken(request);
            if (token != null && tokenProvider.validateToken(token)) {
                // 从 Token 中获取用户名
                String username = tokenProvider.getUsernameFromToken(token);
                // 加载用户详情
                UserDetails userDetails = userDetailsService.loadUserByUsername(username);
                // 创建认证对象
                UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(
                        userDetails, null, userDetails.getAuthorities());
                // 设置详情
                authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
                // 设置安全上下文
                SecurityContextHolder.getContext().setAuthentication(authentication);
            }
        } catch (Exception ex) {
            logger.error("无法设置用户认证", ex);
        }
        filterChain.doFilter(request, response);
    }

    private String extractToken(HttpServletRequest request) {
        String bearerToken = request.getHeader("Authorization");
        if (StringUtils.hasText(bearerToken) && bearerToken.startsWith("Bearer ")) {
            return bearerToken.substring(7);
        }
        return null;
    }
}

@Component
public class JwtTokenProvider {
    @Value("${app.jwt.secret}")
    private String secret;

    @Value("${app.jwt.expiration}")
    private Long expiration;

    public String generateToken(Authentication authentication) {
        UserDetails userDetails = (UserDetails) authentication.getPrincipal();
        Date now = new Date();
        Date expiryDate = new Date(now.getTime() + expiration);
        return Jwts.builder()
                .setSubject(userDetails.getUsername())
                .setIssuedAt(now)
                .expiration(expiryDate)
                .signWith(SignatureAlgorithm.HS512, secret)
                .compact();
    }

    public String getUsernameFromToken(String token) {
        Claims claims = Jwts.parser().setSigningKey(secret).parseClaimsJws(token).getBody();
        return claims.getSubject();
    }

    public boolean validateToken(String token) {
        try {
            Jwts.parser().setSigningKey(secret).parseClaimsJws(token);
            return true;
        } catch (SignatureException ex) {
            logger.error("无效的 JWT 签名");
        } catch (MalformedJwtException ex) {
            logger.error("无效的 JWT 令牌");
        } catch (ExpiredJwtException ex) {
            logger.error("JWT 令牌已过期");
        } catch (UnsupportedJwtException ex) {
            logger.error("不支持的 JWT 令牌");
        } catch (IllegalArgumentException ex) {
            logger.error("JWT claims 字符串为空");
        }
        return false;
    }
}

@RestController
@RequestMapping("/api/products")
public class ProductController {
    // 基于角色的访问控制
    @PreAuthorize("hasRole('ADMIN')")
    @PostMapping
    public ProductDTO createProduct(@Valid @RequestBody ProductCreateDTO dto) {
        return productService.create(dto);
    }

    // 基于权限的访问控制
    @PreAuthorize("hasAuthority('PRODUCT_READ')")
    @GetMapping("/{id}")
    public ProductDTO getProduct(@PathVariable Long id) {
        return productService.getById(id);
    }

    // 基于表达式的复杂权限控制
    @PreAuthorize("hasRole('ADMIN') or @productSecurity.isOwner(#id, authentication)")
    @PutMapping("/{id}")
    public ProductDTO updateProduct(@PathVariable Long id, @Valid @RequestBody ProductUpdateDTO dto) {
        return productService.update(id, dto);
    }

    // 方法调用后权限检查
    @PostAuthorize("returnObject.status != 'DELETED'")
    @GetMapping("/secure/{id}")
    public ProductDTO getSecureProduct(@PathVariable Long id) {
        return productService.getById(id);
    }

    // 基于过滤器的权限控制
    @PreFilter("filterObject.ownerId == authentication.principal.id")
    @PostMapping("/batch")
    public List<ProductDTO> createProducts(@RequestBody List<ProductCreateDTO> products) {
        return productService.createBatch(products);
    }

    // 方法调用后过滤
    @PostFilter("filterObject.price > 100")
    @GetMapping("/expensive")
    public List<ProductDTO> getExpensiveProducts() {
        return productService.getAll();
    }
}

// 自定义安全表达式处理器
@Component("productSecurity")
public class ProductSecurity {
    private final ProductRepository productRepository;

    public boolean isOwner(Long productId, Authentication authentication) {
        if (authentication == null || !authentication.isAuthenticated()) {
            return false;
        }
        String username = authentication.getName();
        Optional<Product> product = productRepository.findById(productId);
        return product.isPresent() && product.get().getCreatedBy().equals(username);
    }

    public boolean canView(Product product, Authentication authentication) {
        // 复杂的业务逻辑判断
        if (product.isPublic()) {
            return true;
        }
        if (authentication == null) {
            return false;
        }
        UserDetails userDetails = (UserDetails) authentication.getPrincipal();
        return product.getOwners().contains(userDetails.getUsername()) ||
                userDetails.getAuthorities().stream().anyMatch(a -> a.getAuthority().equals("ROLE_ADMIN"));
    }
}

@Configuration
@EnableCaching
public class SecurityCacheConfig {
    @Bean
    public CacheManager cacheManager() {
        ConcurrentMapCacheManager cacheManager = new ConcurrentMapCacheManager();
        cacheManager.setCacheNames(Arrays.asList("userDetails", "permissions", "aclCache"));
        return cacheManager;
    }
}

@Service
public class CachingUserDetailsService implements UserDetailsService {
    private final UserDetailsService delegate;
    private final CacheManager cacheManager;

    @Cacheable(value = "userDetails", key = "#username")
    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        return delegate.loadUserByUsername(username);
    }

    @CacheEvict(value = "userDetails", key = "#username")
    public void evictUserCache(String username) {
        // 缓存清除
    }
}

// 权限缓存服务
@Service
public class PermissionCacheService {
    @Cacheable(value = "permissions", key = "#userId + ':' + #resource")
    public boolean hasPermission(Long userId, String resource, String action) {
        // 从数据库查询权限
        return permissionRepository.existsByUserIdAndResourceAndAction(userId, resource, action);
    }

    @CacheEvict(value = "permissions", allEntries = true)
    public void clearAllPermissionCache() {
        // 清除所有权限缓存
    }
}

@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "订单管理系统 API",
                version = "1.0.0",
                description = "订单管理系统 REST API 文档",
                contact = @Contact(
                        name = "技术支持",
                        email = "[email protected]",
                        url = "https://example.com"
                ),
                license = @License(
                        name = "Apache 2.0",
                        url = "https://www.apache.org/licenses/LICENSE-2.0"
                ),
                termsOfService = "https://example.com/terms"
        ),
        servers = {
                @Server(url = "http://localhost:8080", description = "开发环境"),
                @Server(url = "https://api.example.com", description = "生产环境")
        },
        security = @SecurityRequirement(name = "bearerAuth")
)
@SecurityScheme(
        name = "bearerAuth",
        type = SecuritySchemeType.HTTP,
        bearerFormat = "JWT",
        scheme = "bearer"
)
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .components(new Components()
                        .addSchemas("ErrorResponse", new Schema<ErrorResponse>()
                                .type("object")
                                .addProperty("timestamp", new Schema<String>().type("string").format("date-time"))
                                .addProperty("status", new Schema<Integer>().type("integer"))
                                .addProperty("error", new Schema<String>().type("string"))
                                .addProperty("message", new Schema<String>().type("string"))
                                .addProperty("path", new Schema<String>().type("string")))
                        .addSecuritySchemes("bearerAuth", new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")
                                .bearerFormat("JWT")))
                .externalDocs(new ExternalDocumentation()
                        .description("更多文档")
                        .url("https://docs.example.com"));
    }

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public")
                .pathsToMatch("/api/**")
                .build();
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("admin")
                .pathsToMatch("/api/admin/**")
                .build();
    }
}

@RestController
@RequestMapping("/api/orders")
@Tag(name = "订单管理", description = "订单相关操作")
public class OrderController {
    @Operation(
            summary = "获取订单列表",
            description = "分页获取订单列表，支持多种查询条件",
            parameters = {
                    @Parameter(name = "page", description = "页码，从 0 开始", example = "0"),
                    @Parameter(name = "size", description = "每页大小", example = "20"),
                    @Parameter(name = "status", description = "订单状态"),
                    @Parameter(name = "startDate", description = "开始日期", example = "2024-01-01"),
                    @Parameter(name = "endDate", description = "结束日期", example = "2024-12-31")
            }
    )
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "成功获取订单列表", content = @Content(
                    mediaType = "application/json",
                    array = @ArraySchema(schema = @Schema(implementation = OrderDTO.class)))),
            @ApiResponse(responseCode = "401", description = "未授权访问"),
            @ApiResponse(responseCode = "403", description = "权限不足")
    })
    @GetMapping
    @PreAuthorize("hasRole('USER')")
    public Page<OrderDTO> getOrders(@ParameterObject Pageable pageable, @ParameterObject OrderQueryDTO query) {
        return orderService.getOrders(query, pageable);
    }

    @Operation(
            summary = "创建订单",
            description = "创建新订单，需要商品信息和收货地址"
    )
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public ResponseEntity<OrderDTO> createOrder(
            @io.swagger.v3.oas.annotations.parameters.RequestBody(
                    description = "订单创建信息",
                    required = true,
                    content = @Content(schema = @Schema(implementation = OrderCreateDTO.class)))
            @Valid @RequestBody OrderCreateDTO dto) {
        OrderDTO created = orderService.createOrder(dto);
        URI location = ServletUriComponentsBuilder.fromCurrentRequest().path("/{id}").buildAndExpand(created.getId()).toUri();
        return ResponseEntity.created(location).body(created);
    }

    @Operation(summary = "获取订单详情", description = "根据 ID 获取订单详细信息")
    @GetMapping("/{id}")
    public OrderDTO getOrder(@Parameter(description = "订单 ID", required = true, example = "123") @PathVariable Long id) {
        return orderService.getOrderById(id);
    }

    @Operation(summary = "更新订单状态", description = "更新订单状态，支持取消、完成等操作")
    @PatchMapping("/{id}/status")
    public OrderDTO updateOrderStatus(@Parameter(description = "订单 ID", required = true) @PathVariable Long id, @RequestBody OrderStatusUpdateDTO dto) {
        return orderService.updateStatus(id, dto);
    }

    @Operation(summary = "导出订单", description = "导出订单数据为 Excel 文件")
    @GetMapping("/export")
    public void exportOrders(@ParameterObject OrderQueryDTO query, HttpServletResponse response) throws IOException {
        List<OrderDTO> orders = orderService.exportOrders(query);
        response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
        response.setHeader("Content-Disposition", "attachment; filename=orders.xlsx");
        exportService.exportToExcel(orders, response.getOutputStream());
    }
}

@ExtendWith(MockitoExtension.class)
class UserServiceTest {
    @Mock
    private UserRepository userRepository;

    @Mock
    private PasswordEncoder passwordEncoder;

    @Mock
    private EmailService emailService;

    @InjectMocks
    private UserServiceImpl userService;

    private UserMapper userMapper = Mappers.getMapper(UserMapper.class);

    @Test
    void createUser_ShouldReturnUserDTO_WhenValidInput() {
        // 准备测试数据
        UserCreateDTO createDTO = new UserCreateDTO();
        createDTO.setUsername("testuser");
        createDTO.setEmail("[email protected]");
        createDTO.setPassword("password123");
        User user = new User();
        user.setId(1L);
        user.setUsername("testuser");
        user.setEmail("[email protected]");

        // 设置 Mock 行为
        when(userRepository.existsByEmail(anyString())).thenReturn(false);
        when(passwordEncoder.encode(anyString())).thenReturn("encodedPassword");
        when(userRepository.save(any(User.class))).thenReturn(user);

        // 执行测试
        UserDTO result = userService.createUser(createDTO);

        // 验证结果
        assertNotNull(result);
        assertEquals(1L, result.getId());
        assertEquals("testuser", result.getUsername());
        assertEquals("[email protected]", result.getEmail());

        // 验证交互
        verify(userRepository).existsByEmail("[email protected]");
        verify(passwordEncoder).encode("password123");
        verify(userRepository).save(any(User.class));
        verify(emailService).sendWelcomeEmail("[email protected]");
    }

    @Test
    void createUser_ShouldThrowException_WhenEmailExists() {
        // 准备测试数据
        UserCreateDTO createDTO = new UserCreateDTO();
        createDTO.setEmail("[email protected]");

        // 设置 Mock 行为
        when(userRepository.existsByEmail("[email protected]")).thenReturn(true);

        // 执行测试并验证异常
        BusinessException exception = assertThrows(BusinessException.class, () -> userService.createUser(createDTO));
        assertEquals("邮箱已存在", exception.getMessage());
    }

    @Test
    @DisplayName("根据 ID 获取用户 - 用户存在")
    void getUserById_ShouldReturnUser_WhenUserExists() {
        // 准备测试数据
        Long userId = 1L;
        User user = new User();
        user.setId(userId);
        user.setUsername("testuser");

        // 设置 Mock 行为
        when(userRepository.findById(userId)).thenReturn(Optional.of(user));

        // 执行测试
        UserDTO result = userService.getUserById(userId);

        // 验证结果
        assertNotNull(result);
        assertEquals(userId, result.getId());
        assertEquals("testuser", result.getUsername());
    }

    @Test
    @DisplayName("根据 ID 获取用户 - 用户不存在")
    void getUserById_ShouldThrowException_WhenUserNotFound() {
        // 设置 Mock 行为
        when(userRepository.findById(anyLong())).thenReturn(Optional.empty());

        // 执行测试并验证异常
        ResourceNotFoundException exception = assertThrows(ResourceNotFoundException.class, () -> userService.getUserById(1L));
        assertEquals("用户不存在", exception.getMessage());
    }

    @ParameterizedTest
    @CsvSource({"1, admin, ADMIN", "2, user, USER", "3, manager, MANAGER"})
    void getUserById_WithDifferentUsers_ShouldReturnCorrectUser(Long id, String username, UserRole role) {
        User user = new User();
        user.setId(id);
        user.setUsername(username);
        user.setRole(role);
        when(userRepository.findById(id)).thenReturn(Optional.of(user));

        UserDTO result = userService.getUserById(id);
        assertEquals(id, result.getId());
        assertEquals(username, result.getUsername());
        assertEquals(role, result.getRole());
    }

    @Test
    void updateUser_ShouldUpdateAndReturnUser() {
        // 准备测试数据
        Long userId = 1L;
        UserUpdateDTO updateDTO = new UserUpdateDTO();
        updateDTO.setUsername("updateduser");
        updateDTO.setEmail("[email protected]");
        User existingUser = new User();
        existingUser.setId(userId);
        existingUser.setUsername("olduser");
        existingUser.setEmail("[email protected]");
        User updatedUser = new User();
        updatedUser.setId(userId);
        updatedUser.setUsername("updateduser");
        updatedUser.setEmail("[email protected]");

        // 设置 Mock 行为
        when(userRepository.findById(userId)).thenReturn(Optional.of(existingUser));
        when(userRepository.save(any(User.class))).thenReturn(updatedUser);

        // 执行测试
        UserDTO result = userService.updateUser(userId, updateDTO);

        // 验证结果
        assertEquals("updateduser", result.getUsername());
        assertEquals("[email protected]", result.getEmail());

        // 验证交互
        verify(userRepository).findById(userId);
        verify(userRepository).save(existingUser);
        assertEquals("updateduser", existingUser.getUsername());
        assertEquals("[email protected]", existingUser.getEmail());
    }
}

@SpringBootTest
@AutoConfigureMockMvc
@Testcontainers
@Transactional
class UserControllerIntegrationTest {
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15")
            .withDatabaseName("testdb")
            .withUsername("test")
            .withPassword("test");

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private ObjectMapper objectMapper;

    @Autowired
    private UserRepository userRepository;

    @BeforeEach
    void setUp() {
        userRepository.deleteAll();
    }

    @Test
    void createUser_ShouldReturnCreatedUser() throws Exception {
        // 准备测试数据
        UserCreateDTO createDTO = new UserCreateDTO();
        createDTO.setUsername("integrationtest");
        createDTO.setEmail("[email protected]");
        createDTO.setPassword("Password123!");
        createDTO.setRole(UserRole.USER);

        // 执行请求
        mockMvc.perform(post("/api/users")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(objectMapper.writeValueAsString(createDTO)))
                // 验证响应
                .andExpect(status().isCreated())
                .andExpect(header().exists("Location"))
                .andExpect(jsonPath("$.id").exists())
                .andExpect(jsonPath("$.username").value("integrationtest"))
                .andExpect(jsonPath("$.email").value("[email protected]"))
                .andExpect(jsonPath("$.role").value("USER"));

        // 验证数据库
        Optional<User> savedUser = userRepository.findByEmail("[email protected]");
        assertTrue(savedUser.isPresent());
        assertEquals("integrationtest", savedUser.get().getUsername());
    }

    @Test
    void createUser_ShouldReturnBadRequest_WhenInvalidInput() throws Exception {
        // 准备无效的测试数据
        UserCreateDTO createDTO = new UserCreateDTO();
        createDTO.setEmail("invalid-email");

        mockMvc.perform(post("/api/users")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(objectMapper.writeValueAsString(createDTO)))
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.errors").exists());
    }

    @Test
    void getUser_ShouldReturnUser_WhenUserExists() throws Exception {
        // 准备测试数据
        User user = new User();
        user.setUsername("testuser");
        user.setEmail("[email protected]");
        user.setPassword("encodedPassword");
        user.setRole(UserRole.USER);
        user = userRepository.save(user);

        // 执行请求
        mockMvc.perform(get("/api/users/{id}", user.getId()))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.id").value(user.getId()))
                .andExpect(jsonPath("$.username").value("testuser"))
                .andExpect(jsonPath("$.email").value("[email protected]"));
    }

    @Test
    void getUser_ShouldReturnNotFound_WhenUserNotExists() throws Exception {
        mockMvc.perform(get("/api/users/{id}", 999))
                .andExpect(status().isNotFound());
    }

    @Test
    void updateUser_ShouldUpdateUser() throws Exception {
        // 创建测试用户
        User user = new User();
        user.setUsername("olduser");
        user.setEmail("[email protected]");
        user.setPassword("encodedPassword");
        user.setRole(UserRole.USER);
        user = userRepository.save(user);

        // 准备更新数据
        UserUpdateDTO updateDTO = new UserUpdateDTO();
        updateDTO.setUsername("updateduser");
        updateDTO.setEmail("[email protected]");

        // 执行更新请求
        mockMvc.perform(put("/api/users/{id}", user.getId())
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(objectMapper.writeValueAsString(updateDTO)))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.username").value("updateduser"))
                .andExpect(jsonPath("$.email").value("[email protected]"));

        // 验证数据库更新
        Optional<User> updatedUser = userRepository.findById(user.getId());
        assertTrue(updatedUser.isPresent());
        assertEquals("updateduser", updatedUser.get().getUsername());
        assertEquals("[email protected]", updatedUser.get().getEmail());
    }

    @Test
    void deleteUser_ShouldDeleteUser() throws Exception {
        // 创建测试用户
        User user = new User();
        user.setUsername("tobedeleted");
        user.setEmail("[email protected]");
        user.setPassword("encodedPassword");
        user = userRepository.save(user);

        // 执行删除请求
        mockMvc.perform(delete("/api/users/{id}", user.getId()))
                .andExpect(status().isNoContent());

        // 验证用户已删除
        assertFalse(userRepository.existsById(user.getId()));
    }

    @Test
    void getUsers_ShouldReturnPaginatedUsers() throws Exception {
        // 创建测试数据
        for (int i = 1; i <= 25; i++) {
            User user = new User();
            user.setUsername("user" + i);
            user.setEmail("user" + i + "@example.com");
            user.setPassword("password" + i);
            userRepository.save(user);
        }

        // 执行分页查询
        mockMvc.perform(get("/api/users")
                        .param("page", "0")
                        .param("size", "10")
                        .param("sort", "username,asc"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.content").isArray())
                .andExpect(jsonPath("$.content.length()").value(10))
                .andExpect(jsonPath("$.totalPages").value(3))
                .andExpect(jsonPath("$.totalElements").value(25))
                .andExpect(jsonPath("$.first").value(true))
                .andExpect(jsonPath("$.last").value(false));
    }

    @Test
    @WithMockUser(username = "admin", roles = {"ADMIN"})
    void adminEndpoint_ShouldBeAccessible_ForAdminUser() throws Exception {
        mockMvc.perform(get("/api/admin/users"))
                .andExpect(status().isOk());
    }

    @Test
    @WithMockUser(username = "user", roles = {"USER"})
    void adminEndpoint_ShouldBeForbidden_ForNonAdminUser() throws Exception {
        mockMvc.perform(get("/api/admin/users"))
                .andExpect(status().isForbidden());
    }
}

# 构建阶段
FROM maven:3.8.4-openjdk-17-slim AS build
# 设置工作目录
WORKDIR /app
# 复制项目文件
COPY pom.xml .
COPY src ./src
# 下载依赖并构建（利用 Docker 层缓存）
RUN mvn dependency:go-offline
RUN mvn clean package -DskipTests

# 运行时阶段
FROM openjdk:17-jdk-slim
# 安装必要的工具
RUN apt-get update && apt-get install -y \ curl \ tzdata \ && rm -rf /var/lib/apt/lists/*
# 设置时区
ENV TZ=Asia/Shanghai
# 创建非 root 用户
RUN groupadd -r spring && useradd -r -g spring spring
USER spring:spring
# 设置工作目录
WORKDIR /app
# 从构建阶段复制 JAR 文件
COPY --from=build /app/target/*.jar app.jar
# 暴露端口
EXPOSE 8080
# JVM 参数
ENV JAVA_OPTS="-Xms512m -Xmx1024m -XX:+UseG1GC -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp"
# 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=30s --retries=3 \ CMD curl -f http://localhost:8080/actuator/health || exit 1
# 启动命令
ENTRYPOINT ["sh", "-c", "java ${JAVA_OPTS} -Djava.security.egd=file:/dev/./urandom -jar /app/app.jar"]

version: '3.8'
services:
  # 主应用服务
  app:
    build: .
    container_name: spring-app
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=prod
      - SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/appdb
      - SPRING_DATASOURCE_USERNAME=appuser
      - SPRING_DATASOURCE_PASSWORD=${DB_PASSWORD}
      - SPRING_REDIS_HOST=redis
      - SPRING_REDIS_PORT=6379
      - JWT_SECRET=${JWT_SECRET}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - backend
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  # PostgreSQL 数据库
  postgres:
    image: postgres:15-alpine
    container_name: app-postgres
    environment:
      - POSTGRES_DB=appdb
      - POSTGRES_USER=appuser
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init-db:/docker-entrypoint-initdb.d
    ports:
      - "5432:5432"
    networks:
      - backend
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Redis 缓存
  redis:
    image: redis:7-alpine
    container_name: app-redis
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"
    networks:
      - backend
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Nginx 反向代理
  nginx:
    image: nginx:alpine
    container_name: app-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./ssl:/etc/nginx/ssl
    depends_on:
      - app
    networks:
      - backend
    restart: unless-stopped

  # 监控系统 (Prometheus + Grafana)
  prometheus:
    image: prom/prometheus:latest
    container_name: app-prometheus
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    ports:
      - "9090:9090"
    networks:
      - backend
    restart: unless-stopped

  grafana:
    image: grafana/grafana:latest
    container_name: app-grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    volumes:
      - grafana_data:/var/lib/grafana
      - ./grafana/provisioning:/etc/grafana/provisioning
    ports:
      - "3000:3000"
    networks:
      - backend
    restart: unless-stopped

networks:
  backend:
    driver: bridge

volumes:
  postgres_data:
  redis_data:
  prometheus_data:
  grafana_data:

# application-prod.yml
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
      base-path: /actuator
      cors:
        allowed-origins: "*"
        allowed-methods: GET,POST
  endpoint:
    health:
      show-details: when_authorized
      roles: ADMIN
      probes:
        enabled: true
      groups:
        liveness: include: livenessState
        readiness: include: readinessState
  metrics:
    enabled: true
    prometheus:
      enabled: true
      export:
        prometheus:
          enabled: true
          step: 1m
    distribution:
      percentiles-histogram: "[http.server.requests]": true
      sla: "[http.server.requests]": 10ms, 50ms, 100ms, 200ms, 500ms, 1s, 2s
  info:
    env:
      enabled: true
    java:
      enabled: true
    os:
      enabled: true
  tracing:
    sampling:
      probability: 0.1
server:
  port: 8081 # 单独的监控端口

@Component
public class DatabaseHealthIndicator implements HealthIndicator {
    private final DataSource dataSource;
    private final JdbcTemplate jdbcTemplate;

    public DatabaseHealthIndicator(DataSource dataSource) {
        this.dataSource = dataSource;
        this.jdbcTemplate = new JdbcTemplate(dataSource);
    }

    @Override
    public Health health() {
        try {
            // 检查数据库连接
            Integer result = jdbcTemplate.queryForObject("SELECT 1", Integer.class);
            if (result != null && result == 1) {
                // 检查数据库性能
                Map<String, Object> details = new HashMap<>();
                // 获取连接池信息
                if (dataSource instanceof HikariDataSource) {
                    HikariDataSource hikari = (HikariDataSource) dataSource;
                    details.put("activeConnections", hikari.getHikariPoolMXBean().getActiveConnections());
                    details.put("idleConnections", hikari.getHikariPoolMXBean().getIdleConnections());
                    details.put("totalConnections", hikari.getHikariPoolMXBean().getTotalConnections());
                }
                return Health.up().withDetails(details).build();
            }
            return Health.down().withDetail("error", "数据库查询返回异常结果").build();
        } catch (Exception e) {
            return Health.down().withException(e).withDetail("error", "数据库连接失败：" + e.getMessage()).build();
        }
    }
}

@Component
public class CacheHealthIndicator implements HealthIndicator {
    private final CacheManager cacheManager;

    public CacheHealthIndicator(CacheManager cacheManager) {
        this.cacheManager = cacheManager;
    }

    @Override
    public Health health() {
        Map<String, Object> details = new HashMap<>();
        for (String cacheName : cacheManager.getCacheNames()) {
            Cache cache = cacheManager.getCache(cacheName);
            if (cache != null && cache.getNativeCache() instanceof com.github.benmanes.caffeine.cache.Cache) {
                @SuppressWarnings("unchecked")
                com.github.benmanes.caffeine.cache.Cache<Object, Object> caffeineCache = (com.github.benmanes.caffeine.cache.Cache<Object, Object>) cache.getNativeCache();
                Map<String, Object> cacheStats = new HashMap<>();
                cacheStats.put("estimatedSize", caffeineCache.estimatedSize());
                cacheStats.put("stats", caffeineCache.stats());
                details.put(cacheName, cacheStats);
            }
        }
        return Health.up().withDetails(details).build();
    }
}

@Component
public class ExternalServiceHealthIndicator extends AbstractHealthIndicator {
    private final RestTemplate restTemplate;
    private final String serviceUrl;

    public ExternalServiceHealthIndicator(RestTemplateBuilder restTemplateBuilder) {
        this.restTemplate = restTemplateBuilder
                .setConnectTimeout(Duration.ofSeconds(5))
                .setReadTimeout(Duration.ofSeconds(10))
                .build();
        this.serviceUrl = "https://api.external-service.com/health";
    }

    @Override
    protected void doHealthCheck(Health.Builder builder) throws Exception {
        try {
            ResponseEntity<String> response = restTemplate.getForEntity(serviceUrl, String.class);
            if (response.getStatusCode().is2xxSuccessful()) {
                builder.up().withDetail("status", response.getStatusCode().value()).withDetail("responseTime", "正常");
            } else {
                builder.down().withDetail("status", response.getStatusCode().value()).withDetail("error", "外部服务返回异常状态码");
            }
        } catch (ResourceAccessException e) {
            builder.down().withException(e).withDetail("error", "连接外部服务超时");
        } catch (Exception e) {
            builder.down().withException(e).withDetail("error", "检查外部服务健康状态时发生异常");
        }
    }
}

# application-prod.yml
spring:
  datasource:
    hikari:
      # 连接池配置
      maximum-pool-size: 20
      minimum-idle: 10
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000
      # 性能优化
      auto-commit: false
      connection-test-query: SELECT 1
      validation-timeout: 5000
      leak-detection-threshold: 60000
      # 连接属性
      data-source-properties:
        prepStmtCacheSize: 250
        prepStmtCacheSqlLimit: 2048
        cachePrepStmts: true
        useServerPrepStmts: true
        useLocalSessionState: true
        rewriteBatchedStatements: true
        cacheResultSetMetadata: true
        cacheServerConfiguration: true
        elideSetAutoCommits: true
        maintainTimeStats: false

@Configuration
@EnableJpaRepositories(basePackages = "com.example.repository", repositoryBaseClass = CustomJpaRepositoryImpl.class)
@EnableTransactionManagement
public class JpaConfig {
    @Bean
    public LocalContainerEntityManagerFactoryBean entityManagerFactory(EntityManagerFactoryBuilder builder, DataSource dataSource) {
        Map<String, Object> properties = new HashMap<>();
        properties.put("hibernate.jdbc.batch_size", 50);
        properties.put("hibernate.order_inserts", true);
        properties.put("hibernate.order_updates", true);
        properties.put("hibernate.batch_versioned_data", true);
        properties.put("hibernate.query.in_clause_parameter_padding", true);
        properties.put("hibernate.default_batch_fetch_size", 16);
        properties.put("hibernate.max_fetch_depth", 3);
        properties.put("hibernate.jdbc.fetch_size", 100);
        // 生产环境禁用 DDL 自动更新
        properties.put("hibernate.hbm2ddl.auto", "validate");
        return builder
                .dataSource(dataSource)
                .packages("com.example.entity")
                .persistenceUnit("default")
                .properties(properties)
                .build();
    }

    @Bean
    public JpaTransactionManager transactionManager(EntityManagerFactory emf) {
        return new JpaTransactionManager(emf);
    }
}

// 自定义 Repository 实现
@NoRepositoryBean
public class CustomJpaRepositoryImpl<T, ID> extends SimpleJpaRepository<T, ID> implements CustomJpaRepository<T, ID> {
    private final EntityManager entityManager;

    public CustomJpaRepositoryImpl(JpaEntityInformation<T, ?> entityInformation, EntityManager entityManager) {
        super(entityInformation, entityManager);
        this.entityManager = entityManager;
    }

    @Override
    @Transactional(readOnly = true)
    public List<T> findAllWithPagination(int offset, int limit, Sort sort) {
        CriteriaBuilder cb = entityManager.getCriteriaBuilder();
        CriteriaQuery<T> query = cb.createQuery(getDomainClass());
        Root<T> root = query.from(getDomainClass());
        query.select(root);
        if (sort != null) {
            List<Order> orders = new ArrayList<>();
            sort.forEach(order -> {
                if (order.isAscending()) {
                    orders.add(cb.asc(root.get(order.getProperty())));
                } else {
                    orders.add(cb.desc(root.get(order.getProperty())));
                }
            });
            query.orderBy(orders);
        }
        return entityManager.createQuery(query).setFirstResult(offset).setMaxResults(limit).getResultList();
    }

    @Override
    @Transactional
    public int batchInsert(List<T> entities) {
        int batchSize = 50;
        int count = 0;
        for (int i = 0; i < entities.size(); i++) {
            entityManager.persist(entities.get(i));
            if (i % batchSize == 0 && i > 0) {
                entityManager.flush();
                entityManager.clear();
                count += batchSize;
            }
        }
        entityManager.flush();
        entityManager.clear();
        return count + (entities.size() % batchSize);
    }
}

@Configuration
@EnableCaching
public class CacheConfig {
    @Bean
    public CacheManager cacheManager() {
        CaffeineCacheManager cacheManager = new CaffeineCacheManager();
        // 全局缓存配置
        cacheManager.setCaffeine(Caffeine.newBuilder()
                .expireAfterWrite(Duration.ofMinutes(30))
                .maximumSize(10000)
                .recordStats());

        // 自定义缓存配置
        Map<String, Caffeine<Object, Object>> cacheConfigs = new HashMap<>();
        // 用户缓存 - 较短时间，高频访问
        cacheConfigs.put("users", Caffeine.newBuilder()
                .expireAfterWrite(Duration.ofMinutes(10))
                .maximumSize(1000)
                .recordStats());
        // 商品缓存 - 较长时间，低频更新
        cacheConfigs.put("products", Caffeine.newBuilder()
                .expireAfterWrite(Duration.ofHours(2))
                .maximumSize(5000)
                .recordStats());
        // 配置缓存 - 永不过期，手动刷新
        cacheConfigs.put("config", Caffeine.newBuilder()
                .maximumSize(100)
                .recordStats());
        cacheManager.setCacheSpecification(cacheConfigs);
        return cacheManager;
    }

    @Bean
    public CacheManager redisCacheManager(RedisConnectionFactory factory) {
        RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
                .entryTtl(Duration.ofHours(1))
                .disableCachingNullValues()
                .serializeKeysWith(RedisSerializationContext.SerializationPair.fromSerializer(new StringRedisSerializer()))
                .serializeValuesWith(RedisSerializationContext.SerializationPair.fromSerializer(new GenericJackson2JsonRedisSerializer()));

        // 不同缓存不同配置
        Map<String, RedisCacheConfiguration> cacheConfigs = new HashMap<>();
        cacheConfigs.put("users", config.entryTtl(Duration.ofMinutes(30)));
        cacheConfigs.put("products", config.entryTtl(Duration.ofHours(2)));
        return RedisCacheManager.builder(factory)
                .cacheDefaults(config)
                .withInitialCacheConfigurations(cacheConfigs)
                .transactionAware()
                .build();
    }

    @Bean
    public CacheManager multiLevelCacheManager(CacheManager localCacheManager, CacheManager redisCacheManager) {
        return new MultiLevelCacheManager(localCacheManager, redisCacheManager);
    }
}

// 多级缓存实现
public class MultiLevelCacheManager implements CacheManager {
    private final CacheManager localCacheManager; // L1: Caffeine
    private final CacheManager redisCacheManager; // L2: Redis

    public MultiLevelCacheManager(CacheManager localCacheManager, CacheManager redisCacheManager) {
        this.localCacheManager = localCacheManager;
        this.redisCacheManager = redisCacheManager;
    }

    @Override
    public Cache getCache(String name) {
        Cache localCache = localCacheManager.getCache(name);
        Cache remoteCache = redisCacheManager.getCache(name);
        return new MultiLevelCache(name, localCache, remoteCache);
    }

    @Override
    public Collection<String> getCacheNames() {
        Set<String> names = new HashSet<>();
        names.addAll(localCacheManager.getCacheNames());
        names.addAll(redisCacheManager.getCacheNames());
        return names;
    }
}

class MultiLevelCache implements Cache {
    private final String name;
    private final Cache localCache;
    private final Cache remoteCache;

    public MultiLevelCache(String name, Cache localCache, Cache remoteCache) {
        this.name = name;
        this.localCache = localCache;
        this.remoteCache = remoteCache;
    }

    @Override
    public String getName() {
        return name;
    }

    @Override
    public Object getNativeCache() {
        return remoteCache.getNativeCache();
    }

    @Override
    public ValueWrapper get(Object key) {
        // 先查本地缓存
        ValueWrapper value = localCache.get(key);
        if (value != null) {
            return value;
        }
        // 本地缓存未命中，查 Redis
        value = remoteCache.get(key);
        if (value != null) {
            // 回写到本地缓存
            localCache.put(key, value.get());
        }
        return value;
    }

    @Override
    public <T> T get(Object key, Class<T> type) {
        // 实现类似 get 方法
        T value = localCache.get(key, type);
        if (value != null) {
            return value;
        }
        value = remoteCache.get(key, type);
        if (value != null) {
            localCache.put(key, value);
        }
        return value;
    }

    @Override
    public void put(Object key, Object value) {
        // 同时写入两级缓存
        localCache.put(key, value);
        remoteCache.put(key, value);
    }

    @Override
    public void evict(Object key) {
        // 同时清除两级缓存
        localCache.evict(key);
        remoteCache.evict(key);
    }

    @Override
    public void clear() {
        localCache.clear();
        remoteCache.clear();
    }
}

# application.yml (基础配置)
spring:
  application:
    name: order-service
  profiles:
    active: @spring.profiles.active@
  # 日志配置
logging:
  level:
    com.example: INFO
    org.springframework.web: INFO
    org.hibernate.SQL: WARN
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
  file:
    name: logs/application.log
  logback:
    rollingpolicy:
      max-file-size: 10MB
      max-history: 30

# application-dev.yml (开发环境)
server:
  port: 8080
spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
    username: sa
    password:
  jpa:
    hibernate:
      ddl-auto: update
      show-sql: true
      properties:
        hibernate:
          format_sql: true
    h2:
      console:
        enabled: true
        path: /h2-console
logging:
  level:
    com.example: DEBUG
    org.springframework.web: DEBUG

# application-prod.yml (生产环境)
server:
  port: 8080
  compression:
    enabled: true
    mime-types: text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json
    min-response-size: 1024
  tomcat:
    max-connections: 10000
    max-threads: 200
    min-spare-threads: 10
    connection-timeout: 5000
spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 10
  jpa:
    hibernate:
      ddl-auto: validate
      show-sql: false
  redis:
    host: ${REDIS_HOST:localhost}
    port: ${REDIS_PORT:6379}
    password: ${REDIS_PASSWORD:}
    timeout: 2000ms
    lettuce:
      pool:
        max-active: 20
        max-idle: 10
        min-idle: 5
# 生产环境日志配置
logging:
  level:
    com.example: INFO
    org.springframework.web: WARN
    org.hibernate: WARN
  logstash:
    enabled: true
    host: ${LOGSTASH_HOST}
    port: ${LOGSTASH_PORT}

# prometheus.yml
global:
  scrape_interval: 15s
  evaluation_interval: 15s
alerting:
  alertmanagers:
    - static_configs:
        - targets:
            - alertmanager:9093
rule_files:
  - "alert_rules.yml"
scrape_configs:
  - job_name: 'spring-boot-app'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['app:8080']
    labels:
      application: 'order-service'
      environment: 'production'
  - job_name: 'postgres'
    static_configs:
      - targets: ['postgres-exporter:9187']
  - job_name: 'redis'
    static_configs:
      - targets: ['redis-exporter:9121']

# alert_rules.yml
groups:
  - name: spring_boot_alerts
    rules:
      - alert: HighErrorRate
        expr: rate(http_server_requests_seconds_count{status=~"5..",uri!~".*actuator.*"}[5m]) > 0.05
        for: 2m
        labels:
          severity: critical
          team: backend
        annotations:
          summary: "高错误率报警"
          description: "{{ $labels.instance }}的错误率超过 5% (当前值：{{ $value }})"

      - alert: HighResponseTime
        expr: histogram_quantile(0.95, rate(http_server_requests_seconds_bucket[5m])) > 1
        for: 5m
        labels:
          severity: warning
          team: backend
        annotations:
          summary: "高响应时间报警"
          description: "{{ $labels.instance }}的 95% 响应时间超过 1 秒 (当前值：{{ $value }}s)"

      - alert: ServiceDown
        expr: up{job="spring-boot-app"} == 0
        for: 1m
        labels:
          severity: critical
          team: backend
        annotations:
          summary: "服务宕机报警"
          description: "{{ $labels.instance }}服务已宕机"

      - alert: HighMemoryUsage
        expr: (sum(jvm_memory_used_bytes{area="heap"}) / sum(jvm_memory_max_bytes{area="heap"})) > 0.8
        for: 5m
        labels:
          severity: warning
          team: backend
        annotations:
          summary: "高内存使用率报警"
          description: "{{ $labels.instance }}内存使用率超过 80% (当前值：{{ $value }})"

      - alert: HighCPULoad
        expr: system_cpu_usage > 0.8
        for: 5m
        labels:
          severity: warning
          team: backend
        annotations:
          summary: "高 CPU 使用率报警"
          description: "{{ $labels.instance }}CPU 使用率超过 80% (当前值：{{ $value }})"

Java RESTful 接口开发最佳实践

Java RESTful 接口开发最佳实践

一、为什么选择 Spring Boot：极速开发的秘密

二、极速启动：三步创建第一个 REST 接口

2.1 项目初始化

2.2 基础代码示例

三、Spring Boot RESTful 核心详解

3.1 控制器层最佳实践

3.1.1 RESTful 资源设计原则

3.1.2 高级请求处理技巧

3.2 服务层设计与实现

3.2.1 服务层架构模式

3.2.2 业务逻辑与事务管理

3.3 数据传输对象设计

3.3.1 DTO 模式实现

3.3.2 MapStruct 映射器

四、全局处理与高级特性

4.1 全局异常处理机制

4.1.1 统一异常处理器

4.1.2 自定义异常体系

4.2 数据验证高级技巧

4.2.1 自定义验证注解

4.2.2 分组验证

五、安全与认证授权

5.1 Spring Security 集成

5.1.1 安全配置

5.1.2 JWT 认证实现

5.2 方法级安全控制

5.2.1 基于注解的权限控制

5.2.2 权限缓存与性能优化

六、API 文档与测试

6.1 OpenAPI/Swagger 集成

6.1.1 Springdoc OpenAPI 配置

6.1.2 控制器文档注解

6.2 全面测试策略

6.2.1 单元测试

6.2.2 集成测试

七、部署与监控

7.1 Docker 容器化部署

7.1.1 Dockerfile 配置

7.1.2 Docker Compose 配置

7.2 性能监控与指标

7.2.1 Spring Boot Actuator 配置

7.2.2 自定义健康检查

八、性能优化与最佳实践

8.1 数据库性能优化

8.1.1 连接池配置

8.1.2 JPA 性能优化

8.2 缓存策略优化

8.2.1 多级缓存配置

九、生产环境最佳实践

9.1 应用配置管理

9.1.1 多环境配置

9.2 监控告警配置

9.2.1 Prometheus 监控配置

9.2.2 告警规则配置

十、学习路径规划

10.1 初学者入门路径（1-2 周）

10.2 进阶提升路径（3-4 周）

10.3 专家精通路径（2-3 个月）

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具