Java RESTful 接口开发实战指南

Spring Boot RESTful 核心详解

控制器层最佳实践

RESTful 资源设计原则

好的 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);
}

服务层设计与实现

服务层架构模式

推荐使用构造器注入，结合 @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("邮箱已存在");
        }
        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());
        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;
    }
}

业务逻辑与事务管理

复杂业务场景下，需明确事务边界。支付失败时恢复库存是典型的补偿机制：

@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository orderRepository;
    private final InventoryService inventoryService;
    private final PaymentService paymentService;

    @Transactional(rollbackFor = Exception.class)
    public OrderDTO createOrder(OrderCreateDTO dto) {
        inventoryService.checkStock(dto.getItems());
        inventoryService.deductStock(dto.getItems());
        try {
            Order order = createOrderEntity(dto);
            order = orderRepository.save(order);
            paymentService.processPayment(order);
            order.setStatus(OrderStatus.PAID);
            orderRepository.save(order);
            notificationService.sendOrderConfirmation(order);
            return convertToDTO(order);
        } catch (PaymentException e) {
            inventoryService.restoreStock(dto.getItems());
            throw new BusinessException("支付失败：" + e.getMessage());
        }
    }
}

数据传输对象设计

DTO 模式实现

请求 DTO 应包含验证注解，响应 DTO 可嵌套对象。查询参数 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;

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

MapStruct 映射器

使用 MapStruct 减少样板代码，支持自定义映射逻辑：

@Mapper(componentModel = "spring", uses = {AddressMapper.class},
        unmappedTargetPolicy = ReportingPolicy.IGNORE)
public interface UserMapper {
    User toEntity(UserCreateDTO dto);
    UserDTO toDTO(User entity);

    @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
    void updateEntity(UserUpdateDTO dto, @MappingTarget User entity);

    default Page<UserDTO> toDTOPage(Page<User> page) {
        return page.map(this::toDTO);
    }
}

全局处理与高级特性

统一异常处理

定义全局异常处理器，区分验证错误、业务错误和资源未找到情况，返回统一的 JSON 结构：

@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)
                .build();
        return ResponseEntity.badRequest().body(response);
    }

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

数据验证高级技巧

自定义验证注解

当标准注解无法满足需求时（如手机号格式），可自定义注解和校验器：

@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = PhoneNumberValidator.class)
@Documented
public @interface PhoneNumber {
    String message() default "手机号码格式不正确";
    String region() default "CN";
}

分组验证

针对创建、更新、部分更新等不同场景，使用验证组控制校验规则：

public interface ValidationGroups {
    interface Create {}
    interface Update {}
    interface Patch {}
}

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

// 在控制器中指定组
@PostMapping
public ResponseEntity<UserDTO> createUser(
        @Validated(ValidationGroups.Create.class) @RequestBody UserDTO userDTO) {
    // 创建逻辑
}

安全与认证授权

Spring Security 集成

配置无状态会话，禁用 CSRF，集成 JWT 过滤器：

@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
@RequiredArgsConstructor
public class SecurityConfig {
    private final JwtAuthenticationFilter jwtAuthenticationFilter;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.csrf().disable()
            .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS).and()
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**", "/swagger-ui/**").permitAll()
                .anyRequest().authenticated())
            .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class);
        return http.build();
    }
}

方法级安全控制

利用 @PreAuthorize 进行基于角色或表达式的权限控制：

@RestController
@RequestMapping("/api/products")
public class ProductController {
    @PreAuthorize("hasRole('ADMIN')")
    @PostMapping
    public ProductDTO createProduct(@Valid @RequestBody ProductCreateDTO dto) {
        return productService.create(dto);
    }

    @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);
    }
}

API 文档与测试

OpenAPI/Swagger 集成

使用 Springdoc OpenAPI 生成标准文档，配置安全方案：

@Configuration
@OpenAPIDefinition(
    info = @Info(title = "订单管理系统 API", version = "1.0.0"),
    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().addSecuritySchemes("bearerAuth",
            new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));
    }
}

全面测试策略

单元测试使用 Mockito 模拟依赖，集成测试使用 Testcontainers 启动真实数据库：

@SpringBootTest
@AutoConfigureMockMvc
@Testcontainers
@Transactional
class UserControllerIntegrationTest {
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15");

    @Autowired
    private MockMvc mockMvc;

    @Test
    void createUser_ShouldReturnCreatedUser() throws Exception {
        mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(createDTO)))
                .andExpect(status().isCreated());
    }
}

部署与监控

Docker 容器化部署

编写优化的 Dockerfile，使用多阶段构建减小镜像体积，配置健康检查：

FROM maven:3.8.4-openjdk-17-slim AS build
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn clean package -DskipTests

FROM openjdk:17-jdk-slim
EXPOSE 8080
ENV JAVA_OPTS="-Xms512m -Xmx1024m"
COPY --from=build /app/target/*.jar app.jar
ENTRYPOINT ["sh", "-c", "java ${JAVA_OPTS} -jar /app/app.jar"]

性能监控与指标

启用 Actuator 暴露 Prometheus 指标，配置自定义健康检查：

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  metrics:
    export:
      prometheus:
        enabled: true

性能优化与最佳实践

数据库连接池配置

调整 HikariCP 参数以适应高并发场景，开启预编译语句缓存：

spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 10
      connection-timeout: 30000
      prepStmtCacheSize: 250

多级缓存策略

结合本地缓存（Caffeine）和分布式缓存（Redis），平衡速度与一致性：

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

生产环境最佳实践

应用配置管理

通过多环境配置文件（dev/prod）隔离配置，敏感信息使用环境变量注入：

# application-prod.yml
server:
  port: 8080
spring:
  profiles:
    active: prod
logging:
  level:
    com.example: INFO

监控告警配置

配置 Prometheus 抓取规则，设置错误率、响应时间等关键指标的告警阈值：

# alert_rules.yml
groups:
  - name: spring_boot_alerts
    rules:
      - alert: HighErrorRate
        expr: rate(http_server_requests_seconds_count{status=~"5.."}[5m]) > 0.05

学习路径建议

1. 入门（1-2 周）：掌握 Spring Boot 自动配置原理，完成 CRUD 项目，理解 RESTful 规范。
2. 进阶（3-4 周）：深入 Spring Security，掌握 JPA 高级特性，集成第三方服务。
3. 精通（2-3 个月）：JVM 调优，微服务架构，CI/CD 流水线搭建及全链路监控。