@flyeric0212/frameworks-springboot

---
description: Spring Boot 3 企业级最佳实践规范
globs: **/*.java
alwaysApply: false
---

# Spring Boot 3 企业级最佳实践规范

## 1. 配置管理模块

### 1.1 配置文件组织
- **主配置文件**：`application.yml` 包含通用配置
- **环境配置**：`application-{profile}.yml` 按环境分离
- **配置优先级**：命令行参数 > 环境变量 > 配置文件
- **敏感信息**：使用环境变量或配置中心，禁止硬编码

### 1.2 配置属性绑定
- 使用 `@ConfigurationProperties` 进行类型安全的配置绑定
- 配置类使用 `@Validated` 进行参数校验
- 复杂配置使用嵌套类结构
- 提供默认值和配置文档

### 1.3 多环境管理
- **开发环境**：本地数据库，详细日志，热重载
- **测试环境**：内存数据库，模拟外部服务
- **生产环境**：外部配置，最小日志级别，性能监控

### 1.4 配置最佳实践
- 配置项命名使用 kebab-case
- 布尔值配置明确语义（enabled/disabled）
- 数值配置包含单位说明
- 定期审查和清理无用配置

## 2. 依赖注入模块

### 2.1 Bean 定义策略
- **组件扫描**：使用 `@Component`、`@Service`、`@Repository`、`@Controller`
- **配置类**：复杂 Bean 使用 `@Configuration` + `@Bean`
- **条件注册**：使用 `@ConditionalOn*` 注解进行条件装配
- **作用域管理**：明确 Bean 的生命周期和作用域

### 2.2 依赖注入方式
- **构造器注入**：推荐方式，保证依赖不可变
- **字段注入**：仅在测试中使用 `@Autowired`
- **Setter注入**：可选依赖使用
- **避免循环依赖**：重构代码结构，使用事件驱动

### 2.3 Bean 生命周期管理
- 使用 `@PostConstruct` 和 `@PreDestroy` 管理生命周期
- 实现 `InitializingBean` 和 `DisposableBean` 接口
- 资源清理在销毁方法中进行
- 异步初始化使用 `@Async` 注解

### 2.4 依赖注入最佳实践
- 接口编程，面向抽象依赖
- 使用 `@Qualifier` 解决多实现问题
- 避免过度依赖，保持类的单一职责
- 使用 `@Primary` 指定默认实现

## 3. 安全模块

### 3.1 认证机制
- **JWT 认证**：无状态认证，适合分布式应用
- **OAuth2 集成**：第三方登录和授权
- **多因素认证**：提高安全级别
- **会话管理**：合理设置超时和并发控制

### 3.2 授权策略
- **基于角色**：RBAC 模型，角色权限分离
- **基于资源**：细粒度权限控制
- **方法级安全**：使用 `@PreAuthorize` 和 `@PostAuthorize`
- **URL 级安全**：配置路径访问规则

### 3.3 数据安全
- **输入验证**：所有外部输入必须验证
- **SQL 注入防护**：使用参数化查询
- **XSS 防护**：输出编码和 CSP 策略
- **CSRF 防护**：API 使用 Token 验证

### 3.4 安全配置最佳实践
- 最小权限原则，默认拒绝访问
- 敏感操作记录审计日志
- 定期更新安全依赖
- 使用 HTTPS 和安全头配置

## 4. 性能优化模块

### 4.1 应用层优化
- **连接池配置**：数据库、Redis、HTTP 客户端
- **线程池调优**：异步任务和定时任务
- **JVM 参数**：堆内存、GC 策略、监控参数
- **启动优化**：延迟初始化、条件装配

### 4.2 缓存策略
- **本地缓存**：Caffeine 用于热点数据
- **分布式缓存**：Redis 用于共享数据
- **缓存层次**：L1（本地）+ L2（分布式）
- **缓存更新**：写入时更新、定时刷新、事件驱动

### 4.3 数据库优化
- **连接池配置**：HikariCP 参数调优
- **查询优化**：索引使用、分页查询、批量操作
- **事务管理**：只读事务、事务传播、超时设置
- **读写分离**：主从配置、路由策略

### 4.4 监控和诊断
- **应用指标**：JVM、业务指标、自定义指标
- **性能分析**：慢查询、热点方法识别
- **告警机制**：阈值监控、异常告警
- **健康检查**：Actuator 端点监控应用状态

## 5. 数据访问模块

### 5.1 JPA 最佳实践
- **实体设计**：合理的表关系、字段映射、索引策略
- **Repository 模式**：继承 JpaRepository，自定义查询方法
- **查询优化**：使用 `@Query` 注解、原生 SQL、Specification
- **懒加载策略**：避免 N+1 问题，合理使用 `@EntityGraph`

### 5.2 事务管理
- **声明式事务**：`@Transactional` 注解配置
- **事务传播**：根据业务场景选择传播行为
- **只读事务**：查询操作使用 `readOnly = true`
- **事务超时**：设置合理的超时时间

### 5.3 数据库连接管理
- **连接池配置**：最大连接数、超时设置、健康检查
- **多数据源**：主从分离、分库分表支持
- **连接泄漏检测**：监控长时间占用的连接
- **数据库监控**：连接数、慢查询、死锁检测

### 5.4 数据访问安全
- **参数化查询**：防止 SQL 注入
- **数据脱敏**：敏感数据加密存储
- **访问控制**：数据库用户权限最小化
- **审计日志**：记录数据变更操作

## 6. API 设计模块（RESTful）

### 6.1 URL 设计规范
- **资源命名**：使用名词复数形式，避免动词
- **层次结构**：体现资源间的关系
- **版本控制**：URL 路径或请求头中包含版本信息
- **查询参数**：过滤、排序、分页使用查询参数

### 6.2 HTTP 方法使用
- **GET**：获取资源，幂等操作
- **POST**：创建资源，非幂等操作
- **PUT**：完整更新资源，幂等操作
- **PATCH**：部分更新资源
- **DELETE**：删除资源，幂等操作

### 6.3 响应设计
- **状态码**：正确使用 HTTP 状态码
- **响应格式**：统一的 JSON 响应结构
- **错误处理**：标准化错误响应格式
- **分页响应**：包含总数、页码、页大小信息

### 6.4 API 文档和测试
- **OpenAPI 规范**：使用 Swagger 生成文档
- **接口测试**：单元测试、集成测试、契约测试
- **版本兼容**：向后兼容性保证
- **性能测试**：接口响应时间和并发测试

## 7. 异常处理模块

### 7.1 异常分类
- **业务异常**：可预期的业务逻辑异常
- **系统异常**：不可预期的技术异常
- **验证异常**：参数校验失败异常
- **外部服务异常**：第三方服务调用异常

### 7.2 异常处理策略
- **全局异常处理**：使用 `@ControllerAdvice` 统一处理
- **异常转换**：将底层异常转换为业务异常
- **异常日志**：记录异常堆栈和上下文信息
- **用户友好**：返回用户可理解的错误信息

### 7.3 异常响应格式
- **错误码**：业务错误码和 HTTP 状态码
- **错误信息**：简洁明了的错误描述
- **详细信息**：开发环境提供详细错误信息
- **请求追踪**：包含请求 ID 便于问题定位

### 7.4 异常监控
- **异常统计**：异常类型、频率统计
- **告警机制**：异常阈值告警
- **异常分析**：定期分析异常趋势
- **异常恢复**：自动重试和降级策略

## 8. 测试模块

### 8.1 测试分层策略
- **单元测试**：测试单个类或方法，使用 Mock
- **集成测试**：测试组件间交互，使用 TestContainers
- **端到端测试**：完整业务流程测试
- **性能测试**：负载测试、压力测试

### 8.2 测试工具和框架
- **JUnit 5**：测试框架，支持参数化测试
- **Mockito**：Mock 框架，模拟依赖对象
- **TestContainers**：集成测试中使用真实数据库
- **WireMock**：模拟外部 HTTP 服务

### 8.3 测试数据管理
- **测试数据隔离**：每个测试独立的数据环境
- **数据准备**：使用 `@Sql` 或 Builder 模式
- **数据清理**：测试后清理数据，避免影响其他测试
- **测试数据工厂**：统一的测试数据创建

### 8.4 测试质量保证
- **代码覆盖率**：目标覆盖率 80% 以上
- **测试命名**：清晰的测试方法命名
- **断言明确**：使用有意义的断言消息
- **测试维护**：定期更新和重构测试代码

## 9. 日志记录模块

### 9.1 日志级别管理
- **ERROR**：系统错误，需要立即处理
- **WARN**：警告信息，需要关注
- **INFO**：重要业务信息，正常流程记录
- **DEBUG**：调试信息，开发环境使用

### 9.2 日志内容规范
- **结构化日志**：使用 JSON 格式，便于解析
- **上下文信息**：包含用户 ID、请求 ID、业务标识
- **敏感信息**：避免记录密码、身份证等敏感数据
- **性能信息**：记录关键操作的执行时间

### 9.3 日志输出配置
- **控制台输出**：开发环境使用，格式化显示
- **文件输出**：生产环境使用，按日期滚动
- **远程日志**：集中式日志收集，如 ELK Stack
- **日志压缩**：历史日志压缩存储

### 9.4 日志监控和分析
- **日志聚合**：统一收集和存储
- **实时监控**：关键错误实时告警
- **日志分析**：业务指标分析、异常趋势分析
- **日志检索**：快速定位问题日志

## 10. 应用监控模块

### 10.1 Spring Boot Actuator
- **端点配置**：暴露必要的监控端点
- **健康检查**：自定义健康指示器
- **指标收集**：JVM、应用、业务指标
- **信息端点**：应用版本、构建信息

### 10.2 自定义监控
- **业务指标**：使用 Micrometer 收集业务数据
- **性能监控**：方法执行时间、数据库查询性能
- **错误监控**：异常统计和分析
- **用户行为**：关键业务操作追踪

### 10.3 日志与监控集成
- **结构化日志**：便于监控系统解析
- **关键事件记录**：业务关键节点日志
- **性能日志**：慢操作和资源使用情况
- **告警配置**：基于日志和指标的告警

### 10.4 生产环境监控
- **应用状态**：启动、运行、关闭状态监控
- **资源使用**：内存、CPU、线程池状态
- **外部依赖**：数据库、缓存、第三方服务状态
- **业务监控**：核心业务指标实时监控

## 11. 代码质量模块

### 11.1 编码规范
- **命名规范**：类名、方法名、变量名清晰表达意图
- **代码结构**：合理的包结构和类层次
- **注释规范**：必要的类和方法注释
- **代码复用**：避免重复代码，提取公共方法

### 11.2 设计原则
- **SOLID 原则**：单一职责、开闭原则等
- **DRY 原则**：不重复自己
- **KISS 原则**：保持简单
- **YAGNI 原则**：你不会需要它

### 11.3 代码审查
- **Pull Request**：代码合并前必须审查
- **审查清单**：功能、性能、安全、可维护性
- **自动化检查**：静态代码分析工具
- **知识分享**：通过代码审查传播最佳实践

### 11.4 重构策略
- **持续重构**：小步快跑，持续改进
- **测试保护**：重构前确保测试覆盖
- **重构时机**：新功能开发时同步重构
- **技术债务**：定期评估和偿还技术债务

═══════════════════════════════════════════════════════════════════
═══ ENGLISH TRANSLATION ═══
═══════════════════════════════════════════════════════════════════

---
description: Frameworks Springboot Development Guidelines (Translation)
---

# Frameworks Springboot Guidelines - English Translation

**Note**: This package contains Chinese cursor rules for Frameworks Springboot.

**Original Language**: Chinese (Simplified)

**Content Summary**: This package provides comprehensive development guidelines, best practices, and coding standards for Frameworks Springboot. The rules cover code organization, naming conventions, design patterns, testing strategies, and performance optimization.

**Translation Status**: Automated translation placeholder. For accurate technical translation of specific terms and context, please:
1. Use the original Chinese content above as authoritative reference
2. Refer to official Frameworks Springboot documentation in English
3. The technical patterns and code examples remain universal across languages

**How to Use**:
- Code blocks and examples use universal syntax
- Technical terms (APIs, methods, libraries) are typically in English even in Chinese text
- Structure and organization principles translate directly to English development practices

**Content Length**: 5453 characters of detailed technical guidance

For community-contributed English translation, please refer to the source repository.