# 妙果系统服务端架构文档 ## 1. 系统概述 妙果系统服务端是一个基于 Node.js 和 Koa 框架构建的后端服务，提供多种教育相关 API 服务，包括拼音、汉字、数学计算、自然拼读等多个教育领域的功能支持。系统采用模块化设计，支持多种微信小程序应用的后端服务需求。 ## 2. 技术栈 - **运行环境**: Node.js v24.1.0 - **Web 框架**: Koa v2.13.4 - **路由**: @koa/router v13.1.0, koa-router v13.0.1 - **数据库**: MySQL (mysql2 v3.14.1) - **会话管理**: koa-session v7.0.2 - **文件处理**: @koa/multer v3.0.2, multer v1.4.5-lts.1 - **HTTP 客户端**: axios v1.9.0 - **工具库**: lodash v4.17.21, moment v2.30.1 - **云服务集成**: 腾讯云 OCR、腾讯云对象存储 - **其他工具**: pdfkit v0.17.1, gm v1.25.1 (图像处理) ## 3. 系统架构 ### 3.1 目录结构 ``` miaoguo_system_server/ ├── src/ # 源代码目录 │ ├── api/ # API 模块目录 │ │ ├── common/ # 通用 API │ │ ├── hanzi/ # 汉字学习 API │ │ ├── mathcalculate/ # 数学计算 API │ │ ├── mps/ # MPS 相关 API │ │ ├── phonics/ # 自然拼读 API │ │ ├── pinyin/ # 拼音学习 API │ │ ├── web/ # Web 相关 API │ │ └── yjbdc/ # 英语百词斩 API │ ├── config/ # 配置文件目录 │ │ ├── dev.js # 开发环境配置 │ │ ├── env.js # 环境变量配置 │ │ ├── index.js # 主配置文件 │ │ └── prod.js # 生产环境配置 │ ├── middleware/ # 中间件目录 │ │ ├── queryParamSanitizer.js # 查询参数清理中间件 │ │ └── upload.js # 文件上传中间件 │ ├── model/ # 数据模型目录 │ │ ├── BufferMemoryClass.js # 缓存管理类 │ │ ├── commonModel.js # 通用模型 │ │ ├── hanzi.js # 汉字学习模型 │ │ ├── mathcalculate.js # 数学计算模型 │ │ ├── mathstar.js # 数学之星模型 │ │ ├── mps.js # MPS 模型 │ │ ├── phonics.js # 自然拼读模型 │ │ ├── pinyin.js # 拼音学习模型 │ │ └── yjbdc.js # 英语百词斩模型 │ ├── util/ # 工具类目录 │ │ ├── db.js # 数据库工具 │ │ ├── GlobalCache.js # 全局缓存工具 │ │ ├── stringClass.js # 字符串处理工具 │ │ ├── WXBizDataCrypt.js # 微信数据解密工具 │ │ ├── constant/ # 常量定义 │ │ └── crypto/ # 加密解密工具 │ ├── test/ # 测试目录 │ └── app.js # 应用入口文件 ├── public/ # 静态资源目录 ├── scripts/ # 脚本目录 ├── doc/ # 文档目录 └── package.json # 项目依赖配置 ``` ### 3.2 核心组件 #### 3.2.1 应用入口 (app.js) 应用入口文件负责初始化 Koa 应用实例，配置中间件，注册路由，并启动 HTTP 服务器。主要功能包括： - 配置 bodyParser 解析请求体 - 配置静态文件服务 - 设置错误处理中间件 - 配置会话管理 - 注册各模块路由 - 启动服务器监听 #### 3.2.2 API 模块 每个 API 模块通常包含两个主要文件： - **routes.js**: 定义路由和 URL 映射 - **xxxController.js**: 实现具体的业务逻辑和请求处理 API 模块按功能领域划分，包括： - **common**: 通用功能，如文件上传、内容安全检查等 - **hanzi**: 汉字学习相关功能 - **mathcalculate**: 数学计算相关功能 - **mps**: MPS 相关功能 - **phonics**: 自然拼读相关功能 - **pinyin**: 拼音学习相关功能 - **web**: Web 端相关功能 - **yjbdc**: 英语百词斩相关功能 #### 3.2.3 配置管理 配置管理采用环境分离的方式，通过 `process.env.NODE_ENV` 区分开发环境和生产环境： - **dev.js**: 开发环境特定配置 - **prod.js**: 生产环境特定配置 - **index.js**: 主配置文件，包含通用配置和环境特定配置的整合 配置内容包括： - 服务器端口 - 数据库连接参数 - 会话配置 - 微信应用配置（多个小程序的 appid 和 secret） - 云服务配置（腾讯云、百度云等） #### 3.2.4 中间件 系统使用多个中间件增强功能和安全性： - **queryParamSanitizer.js**: 查询参数清理，防止注入攻击 - **upload.js**: 文件上传处理 - **decryptUrlMiddle**: URL 解密中间件（来自 crypto 工具） #### 3.2.5 数据模型 数据模型层负责与数据库交互和业务数据处理： - **BufferMemoryClass.js**: 内存缓存管理 - **commonModel.js**: 通用数据模型 - 各功能模块特定模型（hanzi.js, phonics.js 等） #### 3.2.6 工具类 系统包含多个工具类，提供通用功能： - **db.js**: 数据库连接和操作 - **GlobalCache.js**: 全局缓存管理 - **stringClass.js**: 字符串处理工具 - **WXBizDataCrypt.js**: 微信数据解密 - **crypto/**: 加密解密工具 ## 4. 数据流 1. 客户端发送 HTTP 请求到服务器 2. Koa 中间件链处理请求（body 解析、参数清理、会话管理等） 3. 路由匹配将请求分发到对应的控制器方法 4. 控制器调用模型层处理业务逻辑和数据操作 5. 模型层与数据库或外部 API 交互 6. 控制器接收处理结果，构造响应 7. 中间件链处理响应 8. 响应返回给客户端 ## 5. 安全机制 - 使用 queryParamSanitizer 中间件防止 SQL 注入和 XSS 攻击 - 会话管理使用签名 cookie 和 httpOnly 标志 - 生产环境使用 secure cookie（仅 HTTPS） - 微信数据解密工具保护用户数据安全 - URL 解密中间件增强 API 安全性 ## 6. 扩展性设计 系统采用模块化设计，便于扩展新功能： 1. 创建新的 API 模块目录 2. 实现路由和控制器 3. 创建相应的数据模型 4. 在 app.js 中注册新路由 ## 7. 部署架构 系统支持开发和生产两种环境部署： - 开发环境：使用 `npm run dev` 启动，加载开发配置 - 生产环境：使用 `npm start` 启动，加载生产配置 服务器要求： - Node.js v24.1.0 - MySQL 数据库 - 适当的网络访问权限（用于访问外部 API） ## 8. 依赖服务 - MySQL 数据库：存储应用数据 - 腾讯云 OCR：文字识别服务 - 腾讯云对象存储：文件存储服务 - 微信开放平台：小程序授权和服务 - 百度 AI 平台：AI 相关服务 ## 9. 监控与日志 系统使用 console.log 进行基本日志记录，关键点包括： - 服务器启动信息 - 错误处理和异常捕获 - API 调用错误 ## 10. 未来优化方向 1. 引入专业日志系统，替代 console.log 2. 增强错误处理和监控机制 3. 实现更完善的缓存策略 4. 考虑引入 TypeScript 增强类型安全 5. 增加自动化测试覆盖 6. 优化数据库连接池管理 7. 考虑引入容器化部署