# 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. **高可用**: 完善的监控和异常处理机制

该方案可以作为项目开发的技术指导文档，确保项目的技术实现符合最佳实践。