# 关键技术

## 核心框架

SmartClass 后端基于 Spring 生态构建，结合多个框架和库以创建一个稳固的基础。

参考资料：[pom.xml 第7-11行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L7-L11)、[pom.xml 第21-28行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L21-L28)、[pom.xml 第29-32行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L29-L32)、[pom.xml 第34-43行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L34-L43)

### Spring Boot 及相关技术

Spring Boot（版本 2.7.2）作为应用的基础，提供以下功能：

- **依赖管理** 和自动配置
- **嵌入式 Web 服务器**（Tomcat）
- **Spring MVC** 用于实现 REST API
- **Spring AOP** 用于面向切面编程，处理横切关注点
- **应用上下文** 管理和依赖注入

### 数据库技术

系统采用分层的数据库访问方式：

| 技术 | 版本 | 用途 |
|---|---|---|
| MySQL | 8.0 | 主要的关系型数据库 |
| MyBatis | 2.2.2 | ORM 框架，用于 SQL 映射 |
| MyBatis-Plus | 3.5.2 | 在 MyBatis 基础上扩展增强功能 |

数据库连接在应用属性中配置，不同环境（开发、测试、生产）使用不同的配置。

参考资料：[pom.xml 第34-43行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L34-L43)、[application.yml 第18-24行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L18-L24)、[docker-compose.yml 第28-42行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L28-L42)

### 缓存与会话管理

Redis 被用于：

- **分布式会话管理**（会话超时设置为 30 天）
- **应用缓存**
- **临时数据存储**

配置包括数据库选择、连接参数和超时设置。

参考资料：[application.yml 第25-32行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L25-L32)、[pom.xml 第44-52行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L44-L52)、[docker-compose.yml 第44-55行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L44-L55)

## 外部集成

参考资料：[application.yml 第63-83行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L63-L83)、[application.yml 第84-102行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L84-L102)、[application.yml 第114-118行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L114-L118)

### Dify AI 集成

系统通过 Dify AI API 提供人工智能能力：

- 配置定义在 `DifyConfig` 类中
- 基础 URL 和端点可通过属性配置
- 用户标识支持可配置前缀
- 支持流式和阻塞两种响应模式
- HTTP 通信由 OkHttp 客户端处理

参考资料：[DifyConfig.java 第1-34行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/config/DifyConfig.java#L1-L34)、[application.yml 第114-118行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L114-L118)

### 微信集成

微信集成为认证和消息传递提供支持：

- 使用 wx-java-mp-spring-boot-starter 实现微信公众平台（MP）集成
- 可配置 token、appId、secret 和加密设置
- 支持微信开放平台

参考资料：[pom.xml 第58-63行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L58-L63)、[application.yml 第63-83行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L63-L83)

### 云存储集成

腾讯云对象存储（COS）用于文件存储：

- 可配置访问凭证和地区设置
- 支持按类型和大小限制文件上传
- 支持多种内容类型：头像、视频、文档和资料

参考资料：[pom.xml 第70-75行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L70-L75)、[application.yml 第84-102行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L84-L102)

## HTTP 客户端架构

系统实现了自定义的 HTTP 客户端层，用于外部 API 通信，特别是 Dify AI 集成。

参考资料：[OkHttpUtils.java 第1-257行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/util/OkHttpUtils.java#L1-L257)、[DifyStreamChunk.java 第1-44行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/dify/DifyStreamChunk.java#L1-L44)、[pom.xml 第93-98行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L93-L98)

HTTP 客户端架构的关键特性：

- **超时配置** - 标准请求超时 60 秒，流式请求无限制
- **JSON 请求处理** - 专门的方法处理 JSON 数据通信
- **表单提交** - 支持标准和多部分表单数据
- **流式响应** - 特别处理流式 API 响应
- **错误处理** - 统一的异常管理

# 开发与部署工具

## 文档和 API 工具

- **Knife4j** - 增强版 Swagger API 文档
- **Freemarker** - HTML 模板引擎

参考资料：[pom.xml 第64-69行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L64-L69)、[pom.xml 第21-24行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L21-L24)、[application.yml 第103-113行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L103-L113)

## 实用工具和辅助库

| 库 | 用途 |
|---|---|
| Lombok | 通过注解减少样板代码 |
| Hutool | 提供全面的实用方法和工具 |
| Commons Lang3 | 字符串操作和通用工具 |
| EasyExcel | Excel 文件读写 |

参考资料：[pom.xml 第116-119行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L116-L119)、[pom.xml 第87-92行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L87-L92)、[pom.xml 第76-80行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L76-L80)、[pom.xml 第81-86行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L81-L86)

## 容器化与部署

应用使用 Docker 进行容器化，采用多阶段构建流程：

1. **构建阶段** - 使用 Maven 编译和打包应用
2. **运行阶段** - 创建基于最小 JRE 的容器以运行应用

Docker Compose 用于协调应用及其依赖项：

- **应用容器** - 运行 Spring Boot 应用
- **MySQL 容器** - 带持久卷的数据库
- **Redis 容器** - 会话和缓存存储

参考资料：[Dockerfile 第1-72行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/Dockerfile#L1-L72)、[docker-compose.yml 第1-65行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L1-L65)

## 技术栈图示

参考资料：[pom.xml 第1-145行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L1-L145)、[application.yml 第1-125行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L1-L125)、[docker-compose.yml 第1-65行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/docker-compose.yml#L1-L65)

## 环境配置

应用通过 profile-specific 配置支持多种部署环境：

- **开发环境**（默认）- 本地开发设置
- **测试环境** - 自动化和手动测试环境
- **生产环境** - 优化后的线上部署设置

不同环境的关键配置差异：

| 配置 | 开发环境 | 生产环境 |
|---|---|---|
| 日志 | 详细 | 最小（仅错误） |
| 数据库 | 本地 | 容器或外部 |
| API 文档 | 启用、开放访问 | 密码保护 |
| Redis | 本地 | 容器或外部 |

参考资料：[application.yml 第1-125行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L1-L125)、[application-prod.yml 第1-36行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application-prod.yml#L1-L36)、[application-test.yml 第1-25行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application-test.yml#L1-L25)

## 构建工具和依赖

Maven 用于依赖管理和构建自动化：

- 包含 Maven Wrapper 以确保构建环境一致性
- 配置阿里云 Maven 仓库以加快中国地区的下载速度
- JDK 1.8 兼容性设置

参考资料：[pom.xml 第127-142行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/pom.xml#L127-L142)、[mvnw 第1-317行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/mvnw#L1-L317)、[settings.xml 第1-41行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/settings.xml#L1-L41)

应用构建为一个可执行的 JAR 文件，然后进行容器化部署。
