java-spring-development

Java Spring 开发最佳实践

核心原则

• 编写整洁、高效且文档完善的 Java 代码，并提供准确的 Spring Boot 示例
• 使用 Spring Boot 3.x 和 Java 17+ 特性（record、密封类、模式匹配）
• 优先使用构造器注入，而非字段注入，以提升可测试性
• 遵循 SOLID 原则和 RESTful API 设计模式
• 设计时应适用于微服务架构

项目结构

使用标准分层模式组织代码：

project/
├── controllers/     # REST controllers
├── services/        # Business logic
├── repositories/    # Data access layer
├── models/          # Domain entities and DTOs
└── configurations/  # Spring configurations

依赖注入

• 对必需的依赖使用构造器注入
• 使用 Lombok 的 @RequiredArgsConstructor，让代码更简洁
• 保持构造器简单，避免在构造器中编写逻辑
• 存在多个实现时使用 @Qualifier

REST API 设计

• 使用恰当的 HTTP 方法（GET、POST、PUT、DELETE、PATCH）
• 返回正确的 HTTP 状态码
• 实现统一的错误响应格式
• 使用 DTO 控制 API 契约
• 必要时对 API 进行版本管理

数据访问

Spring Data JPA

• 正确地定义实体关系（@OneToMany、@ManyToOne 等）
• 适当使用延迟加载，避免 N+1 查询
• 对大型结果集实现分页
• 使用查询方法和 @Query 编写自定义查询

数据库迁移

• 使用 Flyway 或 Liquibase 进行架构迁移
• 正确地管理迁移脚本的版本
• 切勿修改已有迁移
• 在生产环境部署前于开发环境中测试迁移

安全

Spring Security

• 正确实现身份验证和授权
• 使用 BCrypt 进行密码编码
• 适当地配置 CORS
• 根据角色/权限保护端点
• 在生产环境中使用 HTTPS

安全编码

• 验证所有用户输入
• 清理数据，防止注入攻击
• 避免在响应中暴露敏感信息
• 使用参数化查询

测试

单元测试

• 使用 JUnit 5 编写单元测试
• 使用 Mockito 模拟依赖项
• 全面测试业务逻辑
• 遵循 Given-When-Then 模式

集成测试

• 使用 @SpringBootTest 进行集成测试
• 使用 MockMvc 测试 Web 层
• 使用测试容器测试数据库操作
• 测试安全配置

性能

缓存

• 使用 Spring Cache 抽象
• 配置合适的缓存提供程序（Redis、Caffeine）
• 为缓存数据设置合适的 TTL
• 实现缓存失效策略

异步处理

• 使用 @Async 执行非阻塞操作
• 适当地配置线程池
• 处理异步方法中的异常
• 高并发场景下可考虑使用响应式模式

日志与监控

日志

• 使用 SLF4J 和 Logback
• 采用恰当的日志级别
• 添加关联 ID 以便进行链路追踪
• 避免记录敏感数据

监控

• 使用 Spring Boot Actuator 检查健康状况和指标
• 将指标导出到监控系统
• 设置适当的健康检查
• 监控应用性能

API 文档

• 使用 Springdoc OpenAPI 编写 API 文档
• 为所有端点添加描述
• 包含请求/响应示例
• 及时根据代码更新文档