Spring Boot RESTful 接口开发实战指南

RESTful 核心设计详解

控制器层最佳实践

资源设计要遵循 REST 规范，避免在 URL 中使用动词。例如，获取订单项应设计为子资源 /orders/{id}/items。

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

    @GetMapping
    public List<Order> getAllOrders(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        return orderService.getOrders(page, size);
    }

    @GetMapping("/{id}")
    public Order getOrderById(@PathVariable Long id) {
        return orderService.getById(id);
    }

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

对于高级请求处理，比如多条件查询，可以利用 Specification 构建动态查询，同时支持分页排序。

服务层架构与事务管理

服务层负责业务逻辑编排。推荐使用构造器注入，配合 @Transactional 管理事务边界。注意区分读写事务，避免不必要的锁竞争。

@Service
@Transactional
@Slf4j
public class UserServiceImpl implements UserService {
    private final UserRepository userRepository;
    private final UserMapper userMapper;

    public UserServiceImpl(UserRepository userRepository, UserMapper userMapper) {
        this.userRepository = userRepository;
        this.userMapper = userMapper;
    }

    @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);
        return userMapper.toDTO(savedUser);
    }

    @Override
    @Transactional(readOnly = true)
    public UserDTO getUserById(Long id) {
        User user = userRepository.findById(id)
                .orElseThrow(() -> new ResourceNotFoundException("用户不存在"));
        return userMapper.toDTO(user);
    }
}

复杂业务场景下，可能需要编程式事务或分布式事务补偿机制，确保数据一致性。

数据传输对象（DTO）设计

使用 DTO 隔离内部实体与外部接口，避免直接暴露数据库结构。结合 MapStruct 进行高效映射。

@Data
public class UserCreateDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 2, max = 50)
    private String username;

    @NotBlank(message = "邮箱不能为空")
    @Email
    private String email;
}

@Mapper(componentModel = "spring")
public interface UserMapper {
    User toEntity(UserCreateDTO dto);
    UserDTO toDTO(User entity);
}

全局处理与高级特性

统一异常处理

定义全局异常处理器，捕获特定业务异常和系统异常，返回统一的错误响应格式。

@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, HttpServletRequest request) {
        log.error("未处理的异常：", ex);
        // ... 构建通用错误响应
        return ResponseEntity.internalServerError().body(new ErrorResponse());
    }
}

自定义验证与分组校验

除了标准注解，可以编写自定义校验器（如手机号格式），并利用分组验证实现不同场景下的规则差异（如创建 vs 更新）。

安全与认证授权

Spring Security 集成

配置无状态会话，禁用 CSRF（REST API 通常不需要），并集成 JWT 过滤器。

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @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();
    }
}

JWT 令牌生成与解析需保证安全性，建议设置合理的过期时间并使用强密钥。

API 文档与测试策略

OpenAPI/Swagger 集成

使用 Springdoc OpenAPI 自动生成文档，标注 Controller 方法描述、参数及响应类型，方便前端对接。

全面测试覆盖

• 单元测试：利用 Mockito 模拟依赖，验证 Service 层逻辑。
• 集成测试：使用 @SpringBootTest 和 Testcontainers 启动真实数据库，验证完整链路。

@SpringBootTest
@Testcontainers
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
COPY --from=build /app/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["sh", "-c", "java ${JAVA_OPTS} -jar /app/app.jar"]

性能监控

启用 Actuator 暴露指标，集成 Prometheus 收集 JVM 及 HTTP 请求数据，配置 Grafana 可视化面板。自定义健康检查指示器监控数据库连接池状态。

性能优化与最佳实践

数据库与缓存

• 连接池：合理配置 HikariCP 的最大/最小连接数及超时时间。
• JPA 优化：开启批量插入，禁用 DDL 自动更新，使用 Fetch Size 优化大查询。
• 多级缓存：本地 Caffeine 缓存热点数据，Redis 作为共享缓存，兼顾速度与一致性。

生产环境实践

配置管理与告警

通过多环境配置文件区分 Dev、Prod 设置，敏感信息使用环境变量注入。配置 Prometheus 告警规则，针对高错误率、慢响应及内存溢出发送通知。

学习路径建议

1. 入门：掌握 Spring Boot 自动配置原理，完成 CRUD 项目。
2. 进阶：深入 Security、JPA 高级特性，集成第三方服务。
3. 专家：关注 JVM 调优、微服务架构及 CI/CD 流水线建设。

通过以上实践，你可以构建出稳定、高效且易于维护的企业级 RESTful 服务。