微信小程序Java名片管理系统源码部署与前后端联调实战

简介：这是一套面向高校学生与Java初学者的小程序名片管理系统完整项目，适用于课程设计、毕业设计及小程序开发练手场景。项目采用前后端分离思路，前端为微信小程序，后端基于SSM或SpringBoot框架，配套MySQL数据库脚本，开发环境涉及IDEA、微信开发者工具、Navicat与Maven，部署可选用Tomcat 7.x或8.x。压缩包共736个文件，约11.2MB，涵盖71个Java源文件、74个class编译文件、103个js脚本、95个xml配置、60个html页面、42个css与36个wxss样式，以及28个wxml模板、32个json配置和1个sql脚本，前后端代码与数据库结构一应俱全。系统围绕企业信息、注册用户、客户名片、联系人名片、新闻通知、留言板等模块展开，功能完善、界面美观、操作简单，且经过严格调试可稳定运行。目前已有201人学习下载，适合需要完整项目参考、快速搭建名片管理应用或进行二次开发的读者。

1. 从一份能跑通的 Java 名片管理系统说起

前阵子帮一个学弟看他毕设，题目是「基于微信小程序的名片管理系统」，他手里那份压缩包解压出来一堆文件夹，第一反应是「这玩意儿到底能不能跑」。我花了一个下午把源码、SQL 脚本和教程文档过了一遍，结论是：这套东西结构完整、依赖清晰，属于那种照着教程走一遍就能在本地跑起来的课程设计级项目，适合拿来做毕业设计底稿、Java 后端练手，或者当成微信小程序前后端联调的第一个完整案例。它解决的核心问题很具体——把「名片」这种线下场景搬到小程序里，实现录入、列表、搜索、详情、编辑、删除这一整套增删改查闭环，后端用 Java 写接口，数据库存结构化数据，前端用微信小程序做交互。如果你正在找一份带源码、带数据库、带教程的完整交付物，而不是零散的代码片段，这份资源值得往下看。

2. 拆开压缩包：目录结构、技术栈与运行前置条件

2.1 解压后你会看到什么

拿到微信小程序-基于小程序的名片管理系统(java)（包括源码，数据库，教程）.zip之后，先别急着双击运行。我一般会先看目录树，确认三件事：后端工程在哪、小程序端在哪、数据库脚本在哪。典型的结构长这样（不同版本可能略有出入，但核心目录不会差太多）：

名片管理系统/ ├── backend/ # Java 后端工程 │ ├── src/main/java/ # 控制器、服务、实体类 │ ├── src/main/resources/ # application.yml、mapper 映射 │ └── pom.xml # Maven 依赖清单 ├── miniprogram/ # 微信小程序端 │ ├── pages/ # 页面目录：index、add、detail、edit │ ├── utils/ # request 封装、工具函数 │ └── app.json # 全局配置、页面路由 ├── sql/ # 数据库脚本 │ └── card_system.sql # 建库建表 + 初始数据 └── 教程文档.pdf / .docx # 部署说明、截图步骤

这个结构的好处是职责分离清楚：后端只管接口和数据，小程序端只管页面和请求，数据库脚本独立成文件。你不需要在一堆混杂文件里猜哪个是入口。

2.2 技术栈选型与版本要求

这套项目的技术栈属于「课程设计标准配置」，不花哨但够用。后端是 Java + Spring Boot + MyBatis，数据库用 MySQL，前端是原生微信小程序（WXML + WXSS + JS），请求走wx.request。为什么用这套而不是别的？因为对课程设计和毕设来说，Spring Boot 的自动配置能省掉大量 XML 配置，MyBatis 的 SQL 映射对新手友好，MySQL 几乎每台开发机上都装过。常见做法是 JDK 1.8 或 11、Maven 3.6+、MySQL 5.7 或 8.0、微信开发者工具稳定版。这里有个容易翻车的点：MySQL 8.0 的驱动类名和连接 URL 跟 5.7 不一样，如果你本地是 8.0 但脚本按 5.7 写的，启动就会报连接错误。我一般会先确认版本再动手。

2.3 运行前置条件清单

在动手之前，把下面这些准备好，能省掉后面一半的排查时间：

• JDK 已安装并配置JAVA_HOME，命令行执行java -version能看到版本号
• Maven 已安装，mvn -v能正常输出
• MySQL 已启动，且你知道 root 密码（或有一个可用账号）
• 微信开发者工具已安装并登录，能创建或导入小程序项目
• 后端工程能联网下载 Maven 依赖（第一次跑会拉不少 jar 包）

提示：如果你的网络环境拉 Maven 依赖很慢，可以提前在settings.xml里配好国内镜像源，这一步不做的话第一次mvn clean install可能要等很久。

3. 数据库先落地：建库建表与字段设计逻辑

3.1 导入 SQL 脚本的正确姿势

数据库是整个系统的地基，地基没打好，后端启动就会报「Table doesn't exist」。我一般用命令行导入，比图形化工具更可控：

# 登录 MySQL（把 root 换成你的账号） mysql -u root -p # 创建数据库并指定字符集，避免中文乱码 CREATE DATABASE card_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; # 切换到该数据库 USE card_system; # 导入 SQL 脚本（路径换成你解压后的实际路径） source /path/to/sql/card_system.sql;

执行完之后用SHOW TABLES;确认表建出来了，再用SELECT * FROM 名片表 LIMIT 5;看看初始数据在不在。字符集这一步千万别省，utf8mb4才能存下完整的 Unicode 字符，用默认的 latin1 存中文名片会出现问号。

3.2 名片表的核心字段与设计取舍

这套系统的核心表通常叫card或business_card，字段设计直接决定了后端接口和小程序页面能展示什么。典型字段如下：

这里有个新手常犯的错：手机号用 INT 存。手机号是 11 位，INT 最大约 21 亿，勉强能放下，但一旦有前导零或者要存带区号的座机号就会出问题。用 VARCHAR 是更稳妥的选择。另外create_time设默认值能让插入语句少写一个字段，减少出错概率。

3.3 验证数据库连通性

建完表之后，别急着去启动后端。先用一条最简单的查询确认账号权限没问题：

-- 确认当前用户能访问该库 SELECT COUNT(*) FROM card; -- 手动插一条测试数据，验证写入权限 INSERT INTO card (name, phone, company) VALUES ('测试用户', '13800000000', '测试公司'); -- 查出来再删掉，保持数据干净 SELECT * FROM card WHERE name = '测试用户'; DELETE FROM card WHERE name = '测试用户';

这三步走完，数据库层面基本就没坑了。如果INSERT报权限错误，说明你的 MySQL 账号只有读权限，需要换一个有写权限的账号，或者让管理员授权。

4. 后端跑起来：Spring Boot 配置、接口与联调

4.1 改配置：数据库连接与端口

后端工程的核心配置文件在src/main/resources/application.yml（或.properties）。拿到项目后第一件事就是改数据库连接信息，否则启动必失败：

server: port: 8080 # 后端服务端口，后面小程序请求要用 spring: datasource: url: jdbc:mysql://localhost:3306/card_system?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root # 换成你的 MySQL 账号 password: 123456 # 换成你的密码 driver-class-name: com.mysql.cj.jdbc.Driver # MySQL 8.0 用 cj，5.7 用 com.mysql.jdbc.Driver mybatis: mapper-locations: classpath:mapper/*.xml # XML 映射文件位置 type-aliases-package: com.example.card.entity # 实体类包路径

几个参数值得单独说：serverTimezone=Asia/Shanghai不加的话，MySQL 8.0 可能报时区错误；characterEncoding=utf8保证中文不乱码；driver-class-name是最容易搞错的地方，8.0 和 5.7 的驱动类名不同，写错了启动就报ClassNotFoundException。

4.2 启动后端并验证接口

配置改完，在backend目录下执行：

# 清理并打包，第一次会下载依赖 mvn clean package -DskipTests # 启动 Spring Boot 应用 mvn spring-boot:run

看到控制台输出Started Application in x.x seconds就说明启动成功了。接下来用浏览器或 Postman 验证接口是否正常：

# 查询名片列表（GET 请求） curl http://localhost:8080/card/list # 新增名片（POST 请求，JSON 格式） curl -X POST http://localhost:8080/card/add \ -H "Content-Type: application/json" \ -d '{"name":"张三","phone":"13900000000","company":"某某科技"}'

如果list返回了 JSON 数组，add返回了成功状态码，说明后端和数据库已经打通。常见问题是返回 404，那多半是 Controller 的@RequestMapping路径跟你的请求路径对不上，去代码里搜一下注解确认。

4.3 小程序端请求封装与域名配置

小程序端不能直接写http://localhost:8080，因为微信开发者工具有域名校验。开发阶段我一般这样做：

// utils/request.js —— 统一请求封装 const BASE_URL = 'http://localhost:8080'; // 开发阶段用本地地址 function request(url, method = 'GET', data = {}) { return new Promise((resolve, reject) => { wx.request({ url: BASE_URL + url, method: method, data: data, header: { 'Content-Type': 'application/json' }, success: (res) => { if (res.statusCode === 200) { resolve(res.data); } else { reject(res); } }, fail: reject }); }); } module.exports = { request };

然后在微信开发者工具里勾选「不校验合法域名」，否则localhost会被拦截。这个选项在「详情 → 本地设置」里，开发阶段必开，上线前再换成正式域名并配置服务器域名白名单。

4.4 页面与接口的对应关系

小程序端的页面通常有四个：列表页（index）、新增页（add）、详情页（detail）、编辑页（edit）。每个页面对应后端的一组接口：

这张表建议贴在显示器旁边，联调的时候对着看，哪个页面数据不对就查对应接口。我见过有人列表页能显示但详情页空白，最后发现是详情接口的参数名写成了cardId而前端传的是id，这种参数名不一致的问题在前后端分离项目里特别常见。

5. 避坑与排查：那些让你卡半天的常见问题

5.1 后端启动报数据库连接失败

现象：启动时抛Communications link failure或Access denied for user。原因：要么 MySQL 没启动，要么application.yml里的账号密码跟实际不一致，要么端口不是默认的 3306。解决：先命令行mysql -u root -p手动登录一次，确认账号密码和端口；再检查配置文件里的url是否写对了库名card_system。如果 MySQL 装在 Docker 里，端口映射也要确认。

5.2 小程序请求返回 404 或跨域报错

现象：小程序控制台显示request:fail或状态码 404。原因：一是没勾选「不校验合法域名」，二是请求路径跟后端 Controller 映射不一致，三是后端没启动。解决：先确认后端curl能通，再检查小程序request.js里的BASE_URL和接口路径。路径大小写敏感，/card/list和/Card/List是两个不同的地址。

5.3 中文数据显示成问号或乱码

现象：数据库里存进去的中文，在小程序端显示为???或乱码。原因：建库时字符集用了latin1，或者连接 URL 里没加characterEncoding=utf8。解决：重建数据库时指定utf8mb4，连接 URL 补上useUnicode=true&characterEncoding=utf8。已经建好的库可以用ALTER DATABASE card_system CHARACTER SET utf8mb4;补救，但已有数据可能需要重新导入。

5.4 Maven 依赖下载失败或版本冲突

现象：mvn clean package报Could not resolve dependencies。原因：网络问题导致拉不到中央仓库的包，或者项目里 Spring Boot 版本跟某个依赖不兼容。解决：配置国内镜像源，删掉本地.m2/repository里对应的失败目录重新拉。如果是版本冲突，看报错里提到的类在哪个 jar 里，去pom.xml里排除掉冲突的传递依赖。

5.5 删除后列表没刷新

现象：点了删除，数据库里确实没了，但列表页还显示那条数据。原因：删除成功后没有重新调用列表接口，或者用了缓存数据。解决：在删除成功的回调里重新执行一次loadList()，或者在onShow生命周期里刷新列表。小程序的页面栈缓存很容易让人误以为数据没删掉，其实是视图没更新。

6. 进阶玩法：把课程设计改成能写进简历的项目

6.1 加一层登录与用户隔离

原始项目大概率没有登录模块，所有人看到的是同一份名片列表。这在课程设计里没问题，但如果你想让它更像一个真实产品，可以加一层微信登录。思路是：小程序端调用wx.login拿到 code，传给后端换 openid，后端用 openid 作为用户标识，在名片表里加一个user_id字段，所有查询都带上这个条件。这样每个用户只能看到自己的名片。常见做法是用 Spring Boot 拦截器校验请求头里的 token，token 可以用 JWT 生成，也可以简单点用 openid 做 key 存 Redis。这一步做完，项目就从「单机 CRUD」变成了「多用户系统」，面试时也有的聊。

6.2 搜索从 LIKE 升级到多字段匹配

原始搜索可能只匹配姓名，实际用起来你会发现用户想按公司搜、按手机号搜。改法很简单，在 MyBatis 的 XML 里把WHERE name LIKE CONCAT('%',#{keyword},'%')扩展成多个字段的OR条件：

<select id="searchCards" resultType="Card"> SELECT * FROM card WHERE user_id = #{userId} AND ( name LIKE CONCAT('%', #{keyword}, '%') OR company LIKE CONCAT('%', #{keyword}, '%') OR phone LIKE CONCAT('%', #{keyword}, '%') ) ORDER BY create_time DESC </select>

注意CONCAT的写法，不同数据库函数名不一样，MySQL 用CONCAT，Oracle 用||。另外字段多了之后要考虑索引，name和company上加普通索引能明显提升搜索速度，但LIKE '%xx%'这种前置通配符用不上索引，数据量大了要换全文索引或搜索引擎，这是后话。

6.3 用 Postman 做一轮完整回归

改完代码别只点两下页面就完事。我一般会用 Postman 建一个集合，把增删改查搜索五个接口按顺序跑一遍，每个请求带上断言检查返回码和关键字段。这样每次改完代码，点一下「Run Collection」就能知道有没有改坏东西。这个习惯是从一次血泪经验来的：有次改搜索逻辑，顺手动了公共的 SQL 片段，结果新增接口也受了影响，但页面上没测到，直到演示前才发现。从那以后我每次改完后端接口，都强制走一遍 Postman 回归，哪怕只改了一行。

6.4 打包部署时要注意的事

如果要把后端部署到服务器上，application.yml里的数据库地址要改成服务器实际地址，端口要确认防火墙放行。打包用mvn clean package生成 jar 文件，然后用java -jar xxx.jar启动。小程序端则要在微信公众平台配置服务器域名，把https://你的域名加进 request 合法域名列表。本地开发用的localhost和「不校验合法域名」选项在正式环境统统不能用，这一步没有后悔药，必须提前配好。

注意：部署到公网前，确认数据库账号不是 root，且密码足够复杂。课程设计项目里经常把 root 密码硬编码在配置文件里，这个习惯带到生产环境就是事故。

这套名片管理系统本身不复杂，但麻雀虽小五脏俱全，从数据库设计到后端接口再到小程序联调，整条链路都覆盖到了。把它跑通一遍，你对微信小程序 + Java 前后端分离的开发流程会有具体的体感，而不是停留在看教程的层面。希望帮到你。

本文还有配套的精品资源，点击获取