1. 什么是 RESTful APIRESTRepresentational State Transfer表述性状态转移是一种软件架构风格由 Roy Fielding 博士在 2000 年提出。RESTful API 是基于 REST 原则设计的 Web API它使用 HTTP 协议的标准方法GET、POST、PUT、DELETE 等来操作资源并通过统一的接口进行通信。RESTful API 的核心特征包括无状态Stateless每次请求都包含处理该请求所需的全部信息。统一接口Uniform Interface使用标准的 HTTP 方法和资源标识符URI。资源导向Resource-Oriented将数据和功能抽象为资源通过 URI 进行访问。可缓存Cacheable响应应明确标识是否可缓存。分层系统Layered System客户端无需了解是与服务器直接通信还是通过中间层。2. RESTful API 设计原则2.1 使用名词而非动词资源使用名词表示操作通过 HTTP 方法表达。❌/getUsers,/deleteUser/123✅GET /users,DELETE /users/1232.2 使用复数形式集合资源通常使用复数名词。✅/users,/articles,/products2.3 使用合适的 HTTP 方法HTTP 方法操作幂等性安全性GET获取资源是是POST创建资源否否PUT更新或创建资源是否PATCH部分更新资源否否DELETE删除资源是否2.4 使用合适的 HTTP 状态码2xx 成功200 OK, 201 Created, 204 No Content4xx 客户端错误400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found5xx 服务器错误500 Internal Server Error, 503 Service Unavailable3. 实战使用 Spring Boot 构建 RESTful API3.1 项目初始化使用 Spring Initializr 创建项目添加 Web、JPA、H2 依赖。!-- pom.xml 依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId /dependency dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency3.2 定义实体类// User.java Entity Table(name users) public class User { Id GeneratedValue(strategy GenerationType.IDENTITY) private Long id; NotBlank(message 用户名不能为空) private String username; Email(message 邮箱格式不正确) private String email; // 构造方法、getter、setter 省略 }3.3 创建 Repository// UserRepository.java Repository public interface UserRepository extends JpaRepositoryUser, Long { OptionalUser findByUsername(String username); boolean existsByEmail(String email); }3.4 实现 Controller// UserController.java RestController RequestMapping(/api/users) public class UserController { Autowired private UserService userService; // GET /api/users - 获取所有用户 GetMapping public ResponseEntityListUser getAllUsers() { ListUser users userService.getAllUsers(); return ResponseEntity.ok(users); } // GET /api/users/{id} - 根据ID获取用户 GetMapping(/{id}) public ResponseEntityUser getUserById(PathVariable Long id) { return userService.getUserById(id) .map(ResponseEntity::ok) .orElse(ResponseEntity.notFound().build()); } // POST /api/users - 创建用户 PostMapping public ResponseEntityUser createUser(Valid RequestBody User user) { User savedUser userService.createUser(user); return ResponseEntity .created(URI.create(/api/users/ savedUser.getId())) .body(savedUser); } // PUT /api/users/{id} - 更新用户 PutMapping(/{id}) public ResponseEntityUser updateUser( PathVariable Long id, Valid RequestBody User user) { return ResponseEntity.ok(userService.updateUser(id, user)); } // DELETE /api/users/{id} - 删除用户 DeleteMapping(/{id}) public ResponseEntityVoid deleteUser(PathVariable Long id) { userService.deleteUser(id); return ResponseEntity.noContent().build(); } }3.5 实现 Service 层// UserService.java Service public class UserService { Autowired private UserRepository userRepository; public ListUser getAllUsers() { return userRepository.findAll(); } public OptionalUser getUserById(Long id) { return userRepository.findById(id); } public User createUser(User user) { if (userRepository.existsByEmail(user.getEmail())) { throw new RuntimeException(邮箱已存在); } return userRepository.save(user); } public User updateUser(Long id, User userDetails) { User user userRepository.findById(id) .orElseThrow(() - new RuntimeException(用户不存在)); user.setUsername(userDetails.getUsername()); user.setEmail(userDetails.getEmail()); return userRepository.save(user); } public void deleteUser(Long id) { userRepository.deleteById(id); } }4. 高级特性与最佳实践4.1 分页与排序// 分页查询 GetMapping(/paged) public ResponseEntityPageUser getUsersPaged( RequestParam(defaultValue 0) int page, RequestParam(defaultValue 10) int size, RequestParam(defaultValue id,desc) String[] sort) { Pageable pageable PageRequest.of(page, size, Sort.by(sort)); PageUser users userRepository.findAll(pageable); return ResponseEntity.ok(users); }4.2 全局异常处理ControllerAdvice public class GlobalExceptionHandler { ExceptionHandler(RuntimeException.class) public ResponseEntityErrorResponse handleRuntimeException( RuntimeException ex) { ErrorResponse error new ErrorResponse( HttpStatus.BAD_REQUEST.value(), ex.getMessage(), System.currentTimeMillis() ); return ResponseEntity.badRequest().body(error); } ExceptionHandler(MethodArgumentNotValidException.class) public ResponseEntityErrorResponse handleValidationException( MethodArgumentNotValidException ex) { ListString errors ex.getBindingResult() .getFieldErrors() .stream() .map(error - error.getField() : error.getDefaultMessage()) .collect(Collectors.toList()); ErrorResponse error new ErrorResponse( HttpStatus.BAD_REQUEST.value(), 验证失败, System.currentTimeMillis(), errors ); return ResponseEntity.badRequest().body(error); } } // ErrorResponse.java public class ErrorResponse { private int status; private String message; private long timestamp; private ListString errors; // 构造方法、getter、setter 省略 }4.3 API 版本控制常见的版本控制策略URI 路径版本/api/v1/users,/api/v2/users查询参数版本/api/users?version1请求头版本Accept: application/vnd.api.v1json4.4 使用 HATEOAS// 添加超媒体链接 GetMapping(/{id}) public ResponseEntityEntityModelUser getUserById(PathVariable Long id) { User user userService.getUserById(id) .orElseThrow(() - new RuntimeException(用户不存在)); EntityModelUser resource EntityModel.of(user); resource.add(linkTo(methodOn(UserController.class).getUserById(id)).withSelfRel()); resource.add(linkTo(methodOn(UserController.class).getAllUsers()).withRel(users)); return ResponseEntity.ok(resource); }5. 测试 RESTful API5.1 使用 Postman 测试创建以下请求集合GEThttp://localhost:8080/api/usersGEThttp://localhost:8080/api/users/1POSThttp://localhost:8080/api/usersBody: JSONPUThttp://localhost:8080/api/users/1Body: JSONDELETEhttp://localhost:8080/api/users/15.2 使用 JUnit 单元测试SpringBootTest AutoConfigureMockMvc class UserControllerTest { Autowired private MockMvc mockMvc; Test void shouldReturnAllUsers() throws Exception { mockMvc.perform(get(/api/users)) .andExpect(status().isOk()) .andExpect(jsonPath($, hasSize(2))); } Test void shouldCreateUser() throws Exception { String userJson { \username\: \test\, \email\: \testexample.com\ }; mockMvc.perform(post(/api/users) .contentType(MediaType.APPLICATION_JSON) .content(userJson)) .andExpect(status().isCreated()) .andExpect(jsonPath($.username).value(test)); } }5.3 使用 Swagger/OpenAPI 文档// 添加依赖 dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.3.0/version /dependency // 访问地址http://localhost:8080/swagger-ui.html6. 性能优化与安全6.1 缓存策略// 使用 Spring Cache Cacheable(value users, key #id) GetMapping(/{id}) public User getUserById(PathVariable Long id) { return userRepository.findById(id).orElse(null); } CacheEvict(value users, key #id) DeleteMapping(/{id}) public void deleteUser(PathVariable Long id) { userRepository.deleteById(id); }6.2 限流与防刷// 使用 Resilience4j 限流 RateLimiter(name userApi) GetMapping(/{id}) public User getUserById(PathVariable Long id) { return userRepository.findById(id).orElse(null); }6.3 安全防护使用 HTTPS实施身份认证JWT、OAuth2输入验证与 SQL 注入防护CORS 配置API 密钥管理7. 总结设计良好的 RESTful API 应该遵循以下原则使用合适的 HTTP 方法和状态码保持接口简洁、一致提供清晰的错误信息考虑版本控制和向后兼容实施适当的安全措施提供完整的文档和测试通过本文的实践示例你可以快速掌握 RESTful API 的设计与实现。在实际项目中还需要根据业务需求调整架构并持续优化 API 的性能和安全性。