398 lines
10 KiB
Markdown
398 lines
10 KiB
Markdown
# SpringBoot单体后端服务技术方案
|
||
|
||
## 1. 技术选型
|
||
|
||
### 1.1 核心框架
|
||
- **Spring Boot**: 3.2.0 (最新稳定版本)
|
||
- **Java版本**: JDK 21 (LTS版本)
|
||
- **Spring AI**: 0.8.0 (最新稳定版本)
|
||
- **WebSocket**: Spring WebSocket 6.1.0
|
||
|
||
### 1.2 数据存储
|
||
- **数据库**: MySQL 8.0+
|
||
- **缓存**: Redis 7.0+
|
||
- **ORM框架**: MyBatis-Plus 3.5.4 (最新稳定版本)
|
||
|
||
### 1.3 其他组件
|
||
- **连接池**: HikariCP (Spring Boot默认)
|
||
- **JSON处理**: Jackson
|
||
- **API文档**: SpringDoc OpenAPI 3
|
||
- **安全框架**: Spring Security 6.1.0
|
||
- **日志**: Log4j2 + SLF4J
|
||
- **测试**: JUnit 5 + Mockito
|
||
|
||
## 2. 项目架构设计
|
||
|
||
### 2.1 分层架构
|
||
```
|
||
src/main/java/com/emotionmuseum/
|
||
├── config/ # 配置类
|
||
├── controller/ # 控制器层（只负责接收请求、参数校验、调用Service、返回结果）
|
||
├── service/ # 服务层（所有业务逻辑都在这里实现）
|
||
│ ├── impl/ # 服务实现
|
||
├── mapper/ # 数据访问层
|
||
├── entity/ # 实体类
|
||
├── dto/ # 数据传输对象
|
||
│ ├── request/ # 请求对象
|
||
│ ├── response/ # 响应对象
|
||
├── common/ # 公共组件
|
||
│ ├── base/ # 基础类
|
||
│ ├── exception/ # 异常处理
|
||
│ ├── result/ # 统一返回结果
|
||
│ ├── util/ # 工具类
|
||
├── websocket/ # WebSocket相关
|
||
└── EmotionMuseumApplication.java
|
||
```
|
||
|
||
### 2.2 分层职责规范
|
||
- **Controller层**: 只负责接收HTTP请求、参数校验、调用Service层方法、返回HTTP响应
|
||
- **Service层**: 负责所有业务逻辑，包括数据校验、业务规则判断、数据处理、事务管理
|
||
- **Mapper层**: 只负责数据库操作，不包含业务逻辑
|
||
- **Entity层**: 数据库实体类，对应数据库表结构
|
||
- **DTO层**: 数据传输对象，用于前后端数据交互
|
||
|
||
### 2.3 包结构规范
|
||
- 按功能模块分包
|
||
- 每个模块包含完整的MVC层次
|
||
- 公共组件独立包管理
|
||
|
||
## 3. 核心配置设计
|
||
|
||
### 3.1 多环境配置
|
||
- `application.yml` - 主配置文件
|
||
- `application-dev.yml` - 开发环境
|
||
- `application-test.yml` - 测试环境
|
||
- `application-prod.yml` - 生产环境
|
||
|
||
### 3.2 异步配置
|
||
- 使用`@EnableAsync`启用异步
|
||
- 配置自定义线程池
|
||
- 支持异步方法调用
|
||
|
||
### 3.3 数据库配置
|
||
- 主从分离支持
|
||
- 连接池优化配置
|
||
- 事务管理配置
|
||
|
||
## 4. 代码规范
|
||
|
||
### 4.1 命名规范
|
||
- **类名**: 大驼峰命名法 (PascalCase)
|
||
- **方法名**: 小驼峰命名法 (camelCase)
|
||
- **常量**: 全大写+下划线 (UPPER_SNAKE_CASE)
|
||
- **包名**: 全小写+点分隔 (com.emotionmuseum)
|
||
|
||
### 4.2 注解规范
|
||
- 控制器类使用`@RestController`
|
||
- 服务类使用`@Service`
|
||
- 数据访问类使用`@Mapper`
|
||
- 异步方法使用`@Async`
|
||
|
||
### 4.3 异常处理规范
|
||
- 统一使用全局异常处理器
|
||
- 自定义业务异常类
|
||
- 异常信息国际化支持
|
||
|
||
## 5. 核心组件设计
|
||
|
||
### 5.1 BaseEntity设计
|
||
```java
|
||
@MappedSuperclass
|
||
@Data
|
||
public abstract class BaseEntity {
|
||
@TableId(type = IdType.ASSIGN_ID)
|
||
private Long id;
|
||
|
||
@TableField(fill = FieldFill.INSERT)
|
||
private LocalDateTime createTime;
|
||
|
||
@TableField(fill = FieldFill.INSERT_UPDATE)
|
||
private LocalDateTime updateTime;
|
||
|
||
@TableField(fill = FieldFill.INSERT)
|
||
private String createBy;
|
||
|
||
@TableField(fill = FieldFill.INSERT_UPDATE)
|
||
private String updateBy;
|
||
|
||
@TableLogic
|
||
private Integer deleted;
|
||
}
|
||
```
|
||
|
||
### 5.2 统一返回结果设计
|
||
```java
|
||
@Data
|
||
public class Result<T> {
|
||
private Integer code;
|
||
private String message;
|
||
private T data;
|
||
private Long timestamp;
|
||
|
||
public static <T> Result<T> success(T data) {
|
||
// 成功返回
|
||
}
|
||
|
||
public static <T> Result<T> error(String message) {
|
||
// 错误返回
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.3 请求响应封装
|
||
- 所有Controller入参使用Request对象封装
|
||
- 所有Controller出参使用Response对象封装
|
||
- 统一使用Result包装返回结果
|
||
|
||
### 5.4 分层职责严格规范
|
||
**重要原则：严格遵循分层架构，各层职责明确，禁止跨层调用。**
|
||
|
||
- **Controller层职责**：
|
||
- 接收HTTP请求
|
||
- 参数校验（使用@Valid注解）
|
||
- 调用Service层方法
|
||
- 返回HTTP响应
|
||
- **严禁在Controller层编写任何业务逻辑代码**
|
||
|
||
- **Service层职责**：
|
||
- 所有业务逻辑实现
|
||
- 数据校验和业务规则判断
|
||
- 数据处理和转换
|
||
- 事务管理
|
||
- 调用Mapper层进行数据操作
|
||
- 异常处理和日志记录
|
||
|
||
- **Mapper层职责**：
|
||
- 数据库CRUD操作
|
||
- SQL语句编写
|
||
- 数据查询和映射
|
||
- **严禁在Mapper层编写业务逻辑**
|
||
|
||
## 6. Spring AI + Coze集成方案
|
||
|
||
### 6.1 Coze平台集成
|
||
- 使用Spring AI的ChatClient接口
|
||
- 配置Coze API密钥和端点
|
||
- 实现自定义ChatClient适配器
|
||
|
||
### 6.2 WebSocket实时通信
|
||
- 使用STOMP协议
|
||
- 支持一对一和广播消息
|
||
- 实现消息持久化
|
||
|
||
### 6.3 对话管理
|
||
- 对话历史记录存储
|
||
- 上下文管理
|
||
- 用户会话隔离
|
||
|
||
## 7. 缓存策略
|
||
|
||
### 7.1 Redis缓存设计
|
||
- 用户会话缓存
|
||
- 对话历史缓存
|
||
- 热点数据缓存
|
||
- 分布式锁实现
|
||
|
||
### 7.2 缓存更新策略
|
||
- 写入时更新
|
||
- 定时刷新
|
||
- 失效策略
|
||
|
||
## 8. 安全设计
|
||
|
||
### 8.1 Spring Security认证授权
|
||
- **JWT Token认证**: 基于JWT的无状态认证机制
|
||
- **角色权限控制**: 基于RBAC的权限模型
|
||
- **API访问控制**: 细粒度的接口权限控制
|
||
- **密码加密**: 使用BCrypt加密算法
|
||
- **会话管理**: 支持无状态和有状态会话
|
||
- **CSRF防护**: 跨站请求伪造防护
|
||
- **CORS配置**: 跨域资源共享配置
|
||
|
||
### 8.2 安全组件设计
|
||
- **SecurityConfig**: Spring Security主配置类
|
||
- **JwtAuthenticationFilter**: JWT认证过滤器
|
||
- **JwtTokenProvider**: JWT令牌提供者
|
||
- **UserDetailsService**: 用户详情服务
|
||
- **AuthenticationEntryPoint**: 认证失败处理
|
||
- **AccessDeniedHandler**: 访问拒绝处理
|
||
|
||
### 8.3 数据安全
|
||
- 敏感数据加密
|
||
- SQL注入防护
|
||
- XSS防护
|
||
- 输入验证和过滤
|
||
|
||
## 9. 性能优化
|
||
|
||
### 9.1 数据库优化
|
||
- 索引优化
|
||
- 查询优化
|
||
- 分页查询
|
||
|
||
### 9.2 缓存优化
|
||
- 多级缓存
|
||
- 缓存预热
|
||
- 缓存穿透防护
|
||
|
||
### 9.3 异步处理
|
||
- 消息队列
|
||
- 异步任务
|
||
- 批量处理
|
||
|
||
## 10. 监控和日志
|
||
|
||
### 10.1 应用监控
|
||
- 健康检查
|
||
- 性能监控
|
||
- 业务监控
|
||
|
||
### 10.2 Log4j2日志管理
|
||
- **日志框架**: Log4j2 + SLF4J
|
||
- **日志级别**: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
|
||
- **日志输出**: 控制台、文件、数据库、远程服务器
|
||
- **日志格式**: JSON格式结构化日志
|
||
- **日志轮转**: 按大小和时间自动轮转
|
||
- **日志过滤**: 基于MDC的日志过滤
|
||
- **性能优化**: 异步日志记录
|
||
- **日志聚合**: ELK Stack集成支持
|
||
|
||
### 10.3 日志配置策略
|
||
- **开发环境**: 控制台输出，DEBUG级别
|
||
- **测试环境**: 文件输出，INFO级别
|
||
- **生产环境**: 文件+远程输出，WARN级别
|
||
- **安全日志**: 独立的审计日志文件
|
||
- **业务日志**: 按模块分离的日志文件
|
||
|
||
## 11. 部署方案
|
||
|
||
### 11.1 容器化部署
|
||
- Docker镜像构建
|
||
- Docker Compose编排
|
||
- 环境变量配置
|
||
|
||
### 11.2 CI/CD流程
|
||
- 自动化构建
|
||
- 自动化测试
|
||
- 自动化部署
|
||
|
||
## 12. 开发规范
|
||
|
||
### 12.1 代码提交规范
|
||
- 使用Conventional Commits
|
||
- 分支管理策略
|
||
- 代码审查流程
|
||
|
||
### 12.2 测试规范
|
||
- 单元测试覆盖率 > 80%
|
||
- 集成测试
|
||
- 端到端测试
|
||
|
||
### 12.3 文档规范
|
||
- API文档自动生成
|
||
- 代码注释规范
|
||
- 技术文档维护
|
||
|
||
## 13. 项目依赖管理
|
||
|
||
### 13.1 Maven依赖
|
||
```xml
|
||
<properties>
|
||
<java.version>21</java.version>
|
||
<spring-boot.version>3.2.0</spring-boot.version>
|
||
<spring-ai.version>0.8.0</spring-ai.version>
|
||
<mybatis-plus.version>3.5.4</mybatis-plus.version>
|
||
<spring-security.version>6.1.0</spring-security.version>
|
||
<log4j2.version>2.20.0</log4j2.version>
|
||
<jwt.version>0.11.5</jwt.version>
|
||
</properties>
|
||
```
|
||
|
||
### 13.2 依赖版本管理
|
||
- 统一版本管理
|
||
- 依赖冲突解决
|
||
- 安全漏洞检查
|
||
|
||
### 13.3 核心依赖配置
|
||
```xml
|
||
<!-- Spring Security -->
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-security</artifactId>
|
||
</dependency>
|
||
|
||
<!-- JWT -->
|
||
<dependency>
|
||
<groupId>io.jsonwebtoken</groupId>
|
||
<artifactId>jjwt-api</artifactId>
|
||
<version>${jwt.version}</version>
|
||
</dependency>
|
||
<dependency>
|
||
<groupId>io.jsonwebtoken</groupId>
|
||
<artifactId>jjwt-impl</artifactId>
|
||
<version>${jwt.version}</version>
|
||
<scope>runtime</scope>
|
||
</dependency>
|
||
<dependency>
|
||
<groupId>io.jsonwebtoken</groupId>
|
||
<artifactId>jjwt-jackson</artifactId>
|
||
<version>${jwt.version}</version>
|
||
<scope>runtime</scope>
|
||
</dependency>
|
||
|
||
<!-- Log4j2 -->
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-log4j2</artifactId>
|
||
</dependency>
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-web</artifactId>
|
||
<exclusions>
|
||
<exclusion>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-logging</artifactId>
|
||
</exclusion>
|
||
</exclusions>
|
||
</dependency>
|
||
```
|
||
|
||
## 14. 开发工具配置
|
||
|
||
### 14.1 IDE配置
|
||
- IntelliJ IDEA推荐配置
|
||
- 代码格式化规则
|
||
- 代码检查规则
|
||
|
||
### 14.2 构建工具配置
|
||
- Maven配置优化
|
||
- 插件配置
|
||
- 构建脚本
|
||
|
||
## 15. 质量保证
|
||
|
||
### 15.1 代码质量
|
||
- SonarQube代码检查
|
||
- 代码规范检查
|
||
- 性能检查
|
||
|
||
### 15.2 测试质量
|
||
- 测试用例设计
|
||
- 测试数据管理
|
||
- 测试环境管理
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
本技术方案提供了一个完整的SpringBoot单体后端服务架构，涵盖了从技术选型到部署运维的各个方面。方案注重：
|
||
|
||
1. **技术先进性**: 使用最新稳定版本的技术栈
|
||
2. **架构合理性**: 分层清晰，职责明确
|
||
3. **可扩展性**: 支持水平扩展和功能扩展
|
||
4. **可维护性**: 统一的代码规范和开发流程
|
||
5. **高性能**: 多级缓存和异步处理
|
||
6. **高可用**: 完善的监控和异常处理机制
|
||
|
||
该方案可以作为项目开发的技术指导文档，确保项目的技术实现符合最佳实践。
|