JavaFX MongoDB Student Manager

English · 教学参考应用 · 当前版本 0.1.0

这是一个面向 Java 桌面开发与数据库课程学习者的 JavaFX + MongoDB 分层 CRUD 教学参考应用。它展示从 JavaFX/WebView 界面、业务校验、Repository/DAO 分层到 MongoDB 持久化、统计与 Excel 导出的完整路径。

本项目不是可直接部署到学校的生产系统。它没有登录认证、角色权限、审计、加密、备份与合规控制，也不会附带真实学生数据。

为什么值得看

用一套可运行的小型应用理解 UI、Service、Repository 与 MongoDB 的职责边界；
学习学号唯一性、表单校验、错误转换、统计聚合和 Excel 导出；
使用不依赖 MongoDB 的内存仓库测试核心业务，降低本地贡献门槛；
观察桌面应用如何通过 JavaFX WebView 复用 HTML/CSS/JavaScript 界面。

适合 JavaFX 初学者、MongoDB Java Driver 学习者、课程设计人员和希望练习分层重构的贡献者。

核心能力

新增、查询、修改和删除学生记录；
按学号、姓名、专业或班级搜索；
校验必填项、学号、日期、手机号和邮箱格式；
统计性别、专业、班级和年龄分布；
导出 .xlsx，文本字段保持为字符串；
数据库为空时生成 200 条确定性的虚构演示数据；
通过环境变量或 JVM 系统属性提供 MongoDB 配置；
对界面状态中的 MongoDB 密码进行遮盖。

能力边界

仅用于教学、原型和本地实验；不提供身份认证或权限控制。
连接串会由本地进程使用；不要把含凭据的 URI 写入代码、Issue 或日志。
首次连接空数据库时会自动写入虚构数据。请使用独立的本地数据库。
当前自动化测试覆盖领域逻辑和 Excel 导出，不会连接真实 MongoDB。
package 生成的是普通 Maven JAR，不是包含依赖和 JavaFX 运行时的独立可执行包；请使用 javafx:run 启动。

快速开始

前置条件

JDK 17 或更高版本；
可访问的 MongoDB 实例，建议 MongoDB 6.0 或更高版本；
图形桌面环境。

仓库已包含 Maven Wrapper，无需预装 Maven。MongoDB 需要由你自行启动；项目不会修改系统服务或固定磁盘目录。

1. 获取并验证项目

git clone <repository-url>
cd javafx-mongodb-student-manager
./mvnw --batch-mode verify

Windows PowerShell：

git clone <repository-url>
Set-Location javafx-mongodb-student-manager
.\mvnw.cmd --batch-mode verify

2. 配置 MongoDB（可选）

默认连接 mongodb://127.0.0.1:27017，数据库名为 student_management。可以在启动后的连接页修改，也可以预先设置：

$env:STUDENT_MONGO_URI = "mongodb://127.0.0.1:27017"
$env:STUDENT_MONGO_DATABASE = "student_management"

Linux/macOS：

export STUDENT_MONGO_URI='mongodb://127.0.0.1:27017'
export STUDENT_MONGO_DATABASE='student_management'

也可以使用 JVM 系统属性，优先级高于环境变量：

./mvnw -Dstudent.mongo.uri=mongodb://127.0.0.1:27017 \
  -Dstudent.mongo.database=student_management javafx:run

3. 启动

./mvnw javafx:run

Windows：

.\mvnw.cmd javafx:run

也可以双击 快速启动.bat；它只是 Windows 可选入口，内部仍优先调用 Maven Wrapper。

4. 验证

在连接页确认 URI 与数据库名；
点击“连接并进入”；
若目标数据库为空，界面将出现 200 条名称为“示例学生xxx”的虚构数据；
新增一条记录，按专业搜索，再导出到临时目录；
不再需要数据时，手动删除测试数据库或使用受确认保护的 清理数据库.bat。

配置

环境变量	系统属性	默认值	用途
`STUDENT_MONGO_URI`	`student.mongo.uri`	`mongodb://127.0.0.1:27017`	MongoDB 连接 URI
`STUDENT_MONGO_DATABASE`	`student.mongo.database`	`student_management`	数据库名称
`STUDENT_MONGO_SHELL_URI`	无	本地演示库 URI	仅供可选清库脚本使用

系统属性优先于环境变量。.env.example 仅是配置参考；Java 应用不会自动读取 .env 文件。

架构

flowchart LR
    UI["JavaFX + WebView UI"] --> Service["StudentService"]
    Service --> Port["StudentRepository"]
    Port --> DAO["StudentDAO"]
    DAO --> Mongo[(MongoDB)]
    UI --> Exporter["StudentExcelExporter"]
    Exporter --> XLSX["Local XLSX file"]

src/main/java/com/student/management/
├─ config/       # 环境配置与连接串遮盖
├─ controller/   # JavaFX/FXML 与 WebView 桥接
├─ service/      # 校验、CRUD 协调和统计
├─ repository/   # 持久化端口
├─ dao/          # MongoDB 实现
├─ database/     # 连接生命周期
├─ export/       # 可独立测试的 XLSX 导出
├─ model/        # 领域对象与验证结果
└─ util/         # 虚构数据初始化等工具

更多说明见架构文档、演示数据说明和配置说明。

测试与构建

./mvnw --batch-mode test
./mvnw --batch-mode package
./mvnw --batch-mode verify

测试使用 JUnit 5 和临时目录，不访问真实 MongoDB、不写入仓库中的 Excel 文件。CI 从全新检出执行 verify；秘密扫描位于独立工作流。

数据与隐私

仓库不应提交真实学生表格、导出文件、日志、课程报告或数据库文件；
自动生成的数据使用 example.invalid、虚构地址和“示例学生”名称；
若你自行录入真实数据，必须自行评估适用的认证、授权、加密、审计、保留与删除义务；
发现意外提交的个人数据或凭据时，请按安全策略私下报告。

Roadmap

使用 Testcontainers 增加可选 MongoDB 集成测试；
使用 jlink/jpackage 生成经过验证的桌面分发包；
将数据库迁移与样例数据初始化改为显式命令；
增加可访问性与多语言 UI 测试。

参与贡献

欢迎修正文档、补测试和改善错误提示。提交前请阅读 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md。安全问题不要提交公开 Issue，请遵循 SECURITY.md。

项目由课程型原型演化而来；当前目标是提供诚实、可复现的教学参考，而不是把课程作品包装成生产产品。

许可证

代码以 MIT License 提供。公开发布前，仓库所有者仍需在发布审计中确认其对全部代码和素材具有授权权利。第三方组件见 THIRD_PARTY_NOTICES.md。