妙果系统服务端架构文档

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. 数据流

客户端发送 HTTP 请求到服务器
Koa 中间件链处理请求（body 解析、参数清理、会话管理等）
路由匹配将请求分发到对应的控制器方法
控制器调用模型层处理业务逻辑和数据操作
模型层与数据库或外部 API 交互
控制器接收处理结果，构造响应
中间件链处理响应
响应返回给客户端

5. 安全机制

使用 queryParamSanitizer 中间件防止 SQL 注入和 XSS 攻击
会话管理使用签名 cookie 和 httpOnly 标志
生产环境使用 secure cookie（仅 HTTPS）
微信数据解密工具保护用户数据安全
URL 解密中间件增强 API 安全性

6. 扩展性设计

系统采用模块化设计，便于扩展新功能：

创建新的 API 模块目录
实现路由和控制器
创建相应的数据模型
在 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. 未来优化方向

引入专业日志系统，替代 console.log
增强错误处理和监控机制
实现更完善的缓存策略
考虑引入 TypeScript 增强类型安全
增加自动化测试覆盖
优化数据库连接池管理
考虑引入容器化部署

arch.md 7.2 KB 文件歷史 原始文件