Spring Boot 框架开发 REST API 接口实践

1. 技术选型与环境准备

核心依赖：

• Spring Boot 3.2.2（基于Java 17 LTS）
• Spring Web（RestController + WebFlux）
• Spring Data JPA + Hibernate 6
• Spring Security（OAuth2 + JWT）
• SpringDoc OpenAPI 2.1.0（Swagger 3）
• Docker + Kubernetes（容器化部署）

开发工具：

# 使用Spring Initializr快速创建项目
curl https://start.spring.io/starter.tgz -d dependencies=web,data-jpa,security,validation,actuator,openapi -d javaVersion=17 -d packaging=jar -d name=rest-api-demo | tar -xzvf -

 

 

2. 领域驱动的API设计

示例领域模型（用户管理系统）：

// User.java (实体)
@Entity
@Table(name = "users")
@Getter @Setter @NoArgsConstructor
public class User {
   
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 50)
    private String username;

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

    @JsonIgnore
    @NotBlank
    @Size(min = 8)
    private String password;

    @Enumerated(EnumType.STRING)
    private Role role = Role.USER;

    // 构造方法、自定义业务方法
}

// UserDTO.java (数据传输对象)
@Data @Builder
public class UserDTO {
   
    private Long id;
    private String username;
    private String email;
    private Role role;
}

 

 

3. RESTful控制器实现

// UserController.java
@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor
@Tag(name = "用户管理", description = "用户CRUD操作")
public class UserController {
   
    private final UserService userService;

    @PostMapping
    @Operation(summary = "创建用户")
    public ResponseEntity<UserDTO> createUser(@Valid @RequestBody CreateUserRequest request) {
   
        UserDTO user = userService.createUser(request);
        return ResponseEntity.created(URI.create("/api/v1/users/" + user.getId())).body(user);
    }

    @GetMapping("/{id}")
    @Operation(summary = "根据ID获取用户")
    public ResponseEntity<UserDTO> getUserById(@PathVariable Long id) {
   
        return ResponseEntity.ok(userService.getUserById(id));
    }

    @PutMapping("/{id}")
    @Operation(summary = "更新用户信息")
    public ResponseEntity<UserDTO> updateUser(@PathVariable Long id, @Valid @RequestBody UpdateUserRequest request) {
   
        return ResponseEntity.ok(userService.updateUser(id, request));
    }

    @DeleteMapping("/{id}")
    @Operation(summary = "删除用户")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
   
        userService.deleteUser(id);
        return ResponseEntity.noContent().build();
    }

    // 分页查询、条件查询等方法
}

 

 

4. 响应式编程与异步处理

// ReactiveUserController.java (WebFlux响应式API)
@RestController
@RequestMapping("/api/v2/users")
@RequiredArgsConstructor
public class ReactiveUserController {
   
    private final ReactiveUserService userService;

    @GetMapping
    public Flux<UserDTO> getAllUsers() {
   
        return userService.getAllUsers();
    }

    @PostMapping
    public Mono<ResponseEntity<UserDTO>> createUser(@Valid @RequestBody Mono<UserDTO> userDtoMono) {
   
        return userDtoMono.flatMap(userService::createUser)
                .map(savedUser -> ResponseEntity.created(URI.create("/api/v2/users/" + savedUser.getId())).body(savedUser));
    }
}

 

 

5. 安全认证与授权

JWT认证配置：

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig {
   
    private final JwtAuthenticationFilter jwtAuthFilter;
    private final AuthenticationProvider authenticationProvider;

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
   
        http
            .csrf().disable()
            .authorizeHttpRequests()
                .requestMatchers("/api/v1/auth/**").permitAll()
                .requestMatchers(HttpMethod.GET, "/api/v1/users/**").hasAnyRole("USER", "ADMIN")
                .requestMatchers(HttpMethod.POST, "/api/v1/users").hasRole("ADMIN")
                .anyRequest().authenticated()
                .and()
            .sessionManagement()
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                .and()
            .authenticationProvider(authenticationProvider)
            .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }
}

 

 

6. 数据访问层优化

自定义SQL查询示例：

// UserRepository.java
@Repository
public interface UserRepository extends JpaRepository<User, Long>, JpaSpecificationExecutor<User> {
   
    // 派生查询方法
    Optional<User> findByEmail(String email);

    // 自定义分页查询
    @Query("SELECT u FROM User u WHERE u.username LIKE %:keyword%")
    Page<User> searchByUsername(@Param("keyword") String keyword, Pageable pageable);

    // 原生SQL查询
    @Modifying
    @Query(value = "UPDATE users SET role = :role WHERE id = :id", nativeQuery = true)
    void updateUserRole(@Param("id") Long id, @Param("role") String role);
}

 

 

7. API文档与测试

Swagger UI访问地址：

http://localhost:8080/swagger-ui/index.html

 

 

集成测试示例：

@SpringBootTest
@AutoConfigureMockMvc
class UserControllerIntegrationTest {
   
    @Autowired private MockMvc mockMvc;
    @Autowired private ObjectMapper objectMapper;

    @Test
    void givenValidUser_whenCreateUser_thenReturnCreated() throws Exception {
   
        UserDTO userDTO = UserDTO.builder()
                .username("testuser")
                .email("test@example.com")
                .password("Password123!")
                .build();

        mockMvc.perform(post("/api/v1/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(userDTO)))
                .andExpect(status().isCreated())
                .andExpect(jsonPath("$.username").value("testuser"));
    }
}

 

 

8. 生产环境部署

Dockerfile示例：

# 基础镜像
FROM eclipse-temurin:17-jdk-alpine
VOLUME /tmp
ARG JAR_FILE=target/*.jar
COPY ${JAR_FILE} app.jar
ENTRYPOINT ["java","-jar","/app.jar"]

 

 

Kubernetes部署清单：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: rest-api-demo
spec:
  replicas: 3
  selector:
    matchLabels:
      app: rest-api-demo
  template:
    metadata:
      labels:
        app: rest-api-demo
    spec:
      containers:
      - name: rest-api-demo
        image: your-registry/rest-api-demo:v1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: SPRING_DATASOURCE_URL
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: url
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "1024Mi"
            cpu: "500m"

 

 

9. 性能优化与监控

关键配置：

# application.yml
spring:
  datasource:
    hikari:
      maximum-pool-size: 10
      connection-timeout: 30000
      idle-timeout: 300000
  jpa:
    properties:
      hibernate:
        generate_statistics: true
        order_inserts: true
        order_updates: true
        batch_size: 50

management:
  endpoints:
    web:
      exposure:
        include: "*"
  metrics:
    export:
      prometheus:
        enabled: true

 

 

10. 最佳实践总结

1. API版本控制：通过URL路径（如/api/v1）或请求头实现
2. 异常处理：统一异常处理器（@RestControllerAdvice）
3. 输入验证：结合JSR 380 Bean Validation和自定义验证器
4. 事务管理：@Transactional注解+传播行为配置
5. 缓存策略：集成Redis实现数据缓存
6. 链路追踪：结合Spring Cloud Sleuth和Zipkin