Spring Boot RESTful 接口开发实战指南

三、Spring Boot RESTful 核心详解

3.1 控制器层最佳实践

3.1.1 RESTful 资源设计原则

设计资源时，应遵循统一的路径规范和语义化动词。例如，获取订单列表用 GET，创建用 POST，更新用 PUT。对于子资源，如订单项，可以使用嵌套路径 /orders/{id}/items。

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

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

3.1.2 高级请求处理技巧

在实际业务中，我们经常需要处理多条件查询、文件上传或压缩数据传输。利用 @RequestParam 和自定义注解可以灵活应对这些场景。

// 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.2 服务层设计与实现

3.2.1 服务层架构模式

服务层是业务逻辑的核心。推荐使用构造器注入代替字段注入，这样有利于不可变性和测试。同时，结合缓存策略可以显著提升读取性能。

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

3.2.2 业务逻辑与事务管理

复杂业务往往涉及多个步骤，需要合理控制事务边界。对于支付等外部调用，建议采用补偿机制或异步处理，避免长事务阻塞主线程。

@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) {
        // 1. 验证库存
        inventoryService.checkStock(dto.getItems());
        try {
            // 2. 扣减库存
            inventoryService.deductStock(dto.getItems());
            // 3. 创建订单
            Order order = createOrderEntity(dto);
            order = orderRepository.save(order);
            // 4. 调用支付
            paymentService.processPayment(order);
            order.setStatus(OrderStatus.PAID);
            orderRepository.save(order);
            return convertToDTO(order);
        } catch (PaymentException e) {
            // 支付失败，恢复库存
            inventoryService.restoreStock(dto.getItems());
            throw new BusinessException("支付失败：" + e.getMessage());
        }
    }
}

3.3 数据传输对象设计

3.3.1 DTO 模式实现

为了隔离内部实体与外部接口，建议使用 DTO。配合 Bean Validation 注解可以在 Controller 层自动校验入参。

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

3.3.2 MapStruct 映射器

手动转换 DTO 和 Entity 非常繁琐且容易出错。MapStruct 是一个编译时的映射库，能生成高效且类型安全的代码。

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

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

四、全局处理与高级特性

4.1 全局异常处理机制

统一异常处理器能让 API 返回一致的错误格式，提升前端对接体验。通过 @RestControllerAdvice 捕获不同层级的异常。

@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);
        ErrorResponse response = ErrorResponse.builder()
                .timestamp(LocalDateTime.now())
                .status(HttpStatus.INTERNAL_SERVER_ERROR.value())
                .error("服务器内部错误")
                .message("系统繁忙，请稍后重试")
                .path(request.getRequestURI())
                .build();
        return ResponseEntity.internalServerError().body(response);
    }
}

4.2 数据验证高级技巧

除了标准注解，还可以根据业务需求自定义验证规则，例如手机号格式校验或跨字段验证。

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

五、安全与认证授权

5.1 Spring Security 集成

REST API 通常是无状态的，因此禁用 CSRF 并使用 JWT 进行身份验证是标准做法。

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

5.1.2 JWT 认证实现

JWT 过滤器负责解析 Token 并设置 Spring Security 上下文，确保后续请求拥有正确的权限信息。

@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
            throws ServletException, IOException {
        String token = extractToken(request);
        if (token != null && tokenProvider.validateToken(token)) {
            String username = tokenProvider.getUsernameFromToken(token);
            UserDetails userDetails = userDetailsService.loadUserByUsername(username);
            UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(
                    userDetails, null, userDetails.getAuthorities());
            SecurityContextHolder.getContext().setAuthentication(authentication);
        }
        filterChain.doFilter(request, response);
    }
}

5.2 方法级安全控制

利用 @PreAuthorize 等注解可以实现细粒度的权限控制，甚至基于 SpEL 表达式动态判断。

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

六、API 文档与测试

6.1 OpenAPI/Swagger 集成

使用 Springdoc OpenAPI 可以自动生成符合规范的 API 文档，方便前后端协作。

@Configuration
@OpenAPIDefinition(
    info = @Info(title = "订单管理系统 API", version = "1.0.0"),
    servers = {@Server(url = "http://localhost:8080", description = "开发环境")},
    security = @SecurityRequirement(name = "bearerAuth")
)
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI().components(new Components());
    }
}

6.2 全面测试策略

单元测试关注业务逻辑，集成测试则验证整个请求链路。使用 Testcontainers 可以轻松在本地启动数据库进行测试。

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

七、部署与监控

7.1 Docker 容器化部署

将应用打包为 Docker 镜像，配合 Nginx 反向代理和数据库容器，可实现一键部署。

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"]

7.2 性能监控与指标

启用 Actuator 暴露健康检查和指标端点，配合 Prometheus 和 Grafana 构建可视化监控面板。

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

八、性能优化与最佳实践

8.1 数据库性能优化

合理配置连接池参数，如最大连接数、空闲超时时间等，能有效防止连接泄露。JPA 层面可以通过批量插入和优化查询语句来提升效率。

8.2 缓存策略优化

引入多级缓存（本地 Caffeine + 远程 Redis）可以显著降低数据库压力。注意缓存一致性问题，及时清理过期数据。

九、生产环境最佳实践

9.1 应用配置管理

通过多环境配置文件区分开发、测试和生产环境，敏感信息（如密码、密钥）应通过环境变量注入，避免硬编码。

9.2 监控告警配置

配置 Prometheus 告警规则，当错误率升高、响应时间过长或服务宕机时，及时通知运维人员。

十、学习路径规划

1. 初学者入门路径（1-2 周）
   • 理解 Spring Boot 自动配置原理
   • 掌握 RESTful API 设计原则
   • 完成第一个 CRUD 项目
2. 进阶提升路径（3-4 周）
   • 深入学习 Spring Security 安全控制
   • 掌握 Spring Data JPA 高级特性
   • 添加 API 文档和单元测试
3. 专家精通路径（2-3 个月）
   • JVM 调优与数据库查询优化
   • 微服务架构与分布式事务
   • CI/CD 流水线搭建与监控告警建设