探微通讯录管理系统 · Spring Boot 4 + Vue 3 前后端分离实战

项目简介

通讯录是典型的"小而全"业务：数据量不大，但鉴权、数据隔离、检索、导入导出、统计与留痕一个都不能少。

本项目以通讯录为载体，完整实现一套企业级后台的前后端分离流程：后端 40 个 Java 类、约 2300 行代码、28 个 REST 接口；前端基于 Vue 3 组合式 API，约 4800 行代码，覆盖 PC 与移动端。

技术栈

层次	选型
后端框架	Spring Boot 4.0.7、Java 17
持久层	MyBatis-Plus 3.5.16（分页插件、字段自动填充）
数据库	MySQL 8（db_addressbook，4 张表）
鉴权	JJWT 0.12.6 + 登录拦截器
导入导出	FastExcel 1.2.0
前端框架	Vue 3.5 + Vite 6
UI / 状态	Element Plus 2.9、Pinia 2.3
图表	ECharts 5.6

功能模块

• 工作台：联系人数、分组数、收藏数、本月新增四个指标卡；分组分布饼图、月度新增柱状图、近期生日提醒、最近添加列表
• 联系人管理：分页查询、关键字搜索、按分组 / 收藏筛选、新增编辑删除、批量删除、收藏切换、头像上传、Excel 导入导出
• 分组管理：增删改查、名称唯一性校验、排序号；删除分组时组内联系人自动转为未分组，不丢数据
• 用户管理（管理员）：账号增删改、角色与启用状态切换、一键重置密码
• 操作日志（管理员）：关键操作全量留痕（操作人、内容、路径、IP、时间），支持检索与清空
• 个人中心：资料修改、头像更换、密码修改

关键实现

1. JWT 统一鉴权

登录成功后签发 Token，LoginInterceptor 在 preHandle 中校验并解析出 userId / username / role 写入 ThreadLocal，afterCompletion 统一清理，避免线程复用导致的上下文串号；OPTIONS 预检请求直接放行。

2. 数据权限隔离

普通用户的查询条件自动拼接 user_id = 当前用户，管理员则不限制；新增、修改、删除前均做归属校验，越权直接返回 403。给联系人挂载分组时还会校验分组归属，防止"挂到别人分组下"。

3. Excel 批量导入

导入前先加载当前用户的分组列表构建 名称 → ID 映射，逐行解析并按分组名自动落位；生日字段兼容 yyyy-MM-dd、yyyy/M/d、yyyy.MM.dd、yyyyMMdd 及中文"年月日"共 6 种写法，解析失败降级为空而非整批失败；最终 saveBatch 批量入库。

4. 统计看板

GET /api/stat/dashboard 一次性返回指标卡、分组分布、月度趋势、生日提醒与最近联系人五组数据，SQL 层用 CASE WHEN 完成按月聚合与"距今天数"计算，前端 ECharts 按需渲染并在主题切换时重建实例。

5. 界面与交互

浅色 / 深色双主题（CSS 变量驱动，localStorage 持久化）、侧边栏折叠、移动端抽屉式导航与卡片列表降级，统一 8px 间距体系与墨绿主色。

运行说明

项	值
JDK / Maven	17+ / 3.8+
Node.js	18+
数据库	MySQL 8，执行 数据库脚本/db_addressbook.sql
后端地址	http://localhost:8080
前端地址	http://localhost:5173
管理员账号	tanwei / 123456
普通账号	chenyu / 123456

交付内容

完整源码（server + client）、数据库脚本、依赖清单、启动说明文档，开箱即可运行。

源码为探微编程原创，仅供学习交流使用。