当前位置：首页 > news >正文

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

news 2025/10/30 11:01:40

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;@GetMappingpublic Flux<UserDTO> getAllUsers() {return userService.getAllUsers();}@PostMappingpublic 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;@Beanpublic 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;@Testvoid 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: 3selector:matchLabels:app: rest-api-demotemplate:metadata:labels:app: rest-api-demospec:containers:- name: rest-api-demoimage: your-registry/rest-api-demo:v1.0.0ports:- containerPort: 8080env:- name: SPRING_DATASOURCE_URLvalueFrom:secretKeyRef:name: db-secretkey: urlresources:requests:memory: "512Mi"cpu: "250m"limits:memory: "1024Mi"cpu: "500m"

9. 性能优化与监控

关键配置：

# application.yml
spring:datasource:hikari:maximum-pool-size: 10connection-timeout: 30000idle-timeout: 300000jpa:properties:hibernate:generate_statistics: trueorder_inserts: trueorder_updates: truebatch_size: 50management:endpoints:web:exposure:include: "*"metrics:export:prometheus:enabled: true