哪些Java案例适合构建REST API？

本文目录导读：

1. 经典入门案例：Spring Boot + Spring Web + 内存存储
2. 企业级标准案例：Spring Boot + JPA/Hibernate + MySQL/PostgreSQL
3. 安全与认证案例：Spring Security + JWT （JSON Web Token）
4. 文档与调测案例：SpringDoc OpenAPI （Swagger 3）
5. 异常处理与统一响应案例：全局异常处理 + 自定义响应格式
6. 性能与异步案例：Spring WebFlux + R2DBC （响应式编程）
7. 推荐学习路线

Spring Boot + Spring Web + 内存存储

适用场景：新手入门、快速原型、学习REST基础概念（HTTP方法、状态码、JSON序列化）。

• 核心代码：
  • @RestController 定义资源端点。
  • @GetMapping、@PostMapping、@PutMapping、@DeleteMapping 映射HTTP方法。
  • 使用 ConcurrentHashMap 或 ArrayList 作为临时数据存储。
• 案例示例：图书馆图书管理API
  • GET /api/books：获取所有图书。
  • POST /api/books：添加一本新书（请求体包含JSON：{"title": "xxx", "author": "yyy"}）。
  • GET /api/books/{id}：获取单本图书详情。
  • PUT /api/books/{id}：更新指定图书信息。
  • DELETE /api/books/{id}：删除指定图书。
• 关键点：演示完整的CRUD（增删改查）操作，以及如何用 ResponseEntity 返回合适的HTTP状态码（如201 Created, 404 Not Found）。

企业级标准案例：Spring Boot + JPA/Hibernate + MySQL/PostgreSQL

适用场景：实际项目开发，需要持久化数据、数据库事务、复杂查询。

• 改进点：
  • 引入 @Entity 定义数据模型，@Repository 接口继承 JpaRepository。
  • 使用 @Service 层处理业务逻辑，实现 控制层（Controller）、服务层（Service）、数据访问层（Repository） 三层架构。
  • 使用 @Valid 和 @NotBlank 等注解进行参数校验（Bean Validation）。
• 案例示例：用户订单管理系统
  • 定义 User、Order、Product 实体及关联关系（@OneToMany, @ManyToOne）。
  • POST /api/orders 创建订单时，服务层会自动检查用户是否存在、库存是否充足等。
  • 利用JPA的 Pageable 实现分页查询：GET /api/users?page=0&size=10&sort=createdAt,desc。
• 关键点：学会避免N+1查询问题（使用@EntityGraph或FetchType.LAZY）、处理级联操作、使用DTO（数据传输对象）避免暴露实体内部结构。

安全与认证案例：Spring Security + JWT （JSON Web Token）

适用场景：需要保护API接口，实现用户登录/注册、角色权限控制（如管理员、普通用户）。

• 核心实现：
  • 使用Spring Security配置安全过滤链。
  • 实现 UserDetailsService 加载用户信息。
  • 编写JWT工具类（生成Token、验证Token）。
  • 自定义 OncePerRequestFilter 拦截请求，从Header中提取Bearer Token并验证。
• 案例示例：博客平台API
  • POST /api/auth/login：返回JWT Token。
  • 受保护的资源：POST /api/posts（仅登录用户可创建）、DELETE /api/posts/{id}（仅作者或管理员可删除）。
  • 角色控制：@PreAuthorize("hasRole('ADMIN')") 限制管理员才能访问的接口。
• 关键点：理解无状态认证（Sessionless）、Token刷新机制、密码加密（BCryptPasswordEncoder）、CSRF防护（在REST API中通常禁用CSRF）。

文档与调测案例：SpringDoc OpenAPI （Swagger 3）

适用场景：生成清晰的API文档,方便前后端联调及团队协作。

• 改进点：
  • 在pom.xml中添加 springdoc-openapi-starter-webmvc-ui 依赖。
  • 使用 @Operation、@ApiResponse、@Schema 等注解为API添加描述。
• 案例示例：现有API接口的文档化
  • 启动项目后访问 http://localhost:8080/swagger-ui/index.html。
  • 可在线测试 POST 请求，如注册用户、创建订单。
  • 自动生成客户端SDK。
• 关键点：学会定义全局参数（如JWT Header）、分组文档（如按版本v1、v2分组）、隐藏内部接口（@Hidden）。

异常处理与统一响应案例：全局异常处理 + 自定义响应格式

适用场景：规范所有API的返回格式，避免到处写try-catch,提升代码可维护性。

• 核心实现：
  • 自定义统一响应类 ApiResult<T>：包含 code（业务码）、message、data、timestamp。
  • 使用 @RestControllerAdvice + @ExceptionHandler 捕获各类异常（如 MethodArgumentNotValidException、ConstraintViolationException、自定义业务异常BusinessException）。
• 案例示例：对上述所有案例进行改造
  • 当查询ID不存在时，不直接返回500，而是返回 ApiResult.error(404, "用户不存在")。
  • 参数校验失败时,统一收集错误信息返回给前端。
• 关键点：区分HTTP状态码（如400 Bad Request）和业务错误码（如 10001=库存不足）,后者对前端更友好。

性能与异步案例：Spring WebFlux + R2DBC （响应式编程）

适用场景：高并发、I/O密集型应用（如网关、实时数据推送）,需要充分利用服务器资源。

• 技术栈：抛弃传统的Servlet（Tomcat），改用Netty，使用 Mono 和 Flux 处理异步数据流。
• 案例示例：实时股票行情推送API
  • GET /api/stocks/prices：返回 Flux<StockPrice>，服务端持续推送数据（Server-Sent Events，SSE）。
  • 非阻塞数据库查询：使用R2DBC（Reactive Relational Database Connectivity）连接PostgreSQL,避免连接池线程阻塞。
• 关键点：学习背压（Backpressure）机制、Reactive Streams规范、与传统的@Transactional兼容问题（需使用Reactive事务管理器）。

推荐学习路线

1. 初学：案例1（Spring Boot + 内存），理解REST基础,能做通CRUD。
2. 进步：案例2（+ 数据库） + 案例5（异常处理），学会分层设计和规范输出,应对大部分业务需求。
3. 实战：案例3（+ 安全） + 案例4（+ 文档）,完成一个可交付生产环境的API项目。
4. 进阶：案例6（WebFlux），挑战高并发、低延迟场景。

这些案例从简单到复杂，覆盖了REST API开发中的核心痛点（数据持久化、认证安全、文档、异常、性能），建议你可以从案例1和案例2开始动手编码实践。