简介：本资源是一套基于Java与HTML实现的轻量级CRM客户关系管理系统源码，面向Java初学者、Web开发入门者及中小企业信息化建设人员，聚焦客户信息采集、分类管理、交互记录与基础数据分析等核心需求，助力快速理解企业级客户管理系统的架构逻辑与前后端协同机制。压缩包共38个文件（51KB），含29个Java业务类与工具类源文件（实现用户管理、客户增删改查、数据持久化等）、5个XML配置文件（负责数据库连接、Spring框架配置等）、1个YAML配置文件（简化环境参数管理）、1个HTML前端页面（提供简洁可操作的客户信息录入与展示界面），以及.gitignore和readme.txt等工程规范文件。已有302人学习下载，资源结构清晰、模块职责分明，附带完整Maven构建配置（pom.xml）与标准项目目录结构，便于直接导入IDE运行调试，是掌握Java Web基础开发流程与CRM系统设计思路的实用入门范例。
1. 这不是个“静态HTML页面+Java后台”的玩具项目，而是一套可落地的轻量级CRM骨架
你打开pom.xml看到 Spring Boot 2.7.x 依赖、src/main/resources/application.yml里配置了 H2 内存数据库和 JPA 自动建表、src/main/java/com/example/crm/controller/CustomerController.java中明确标注@RestController并返回ResponseEntity<Customer>——这说明它根本不是用 Servlet 原生写的“Java Web 传统三层”，也不是靠 jQuery 拼 DOM 的老式前端。它是一个前后端分离雏形已成、MVC 结构清晰、具备完整 CRUD 路由与基础权限占位符的可运行系统。37 个文件里，29 个 Java 类覆盖了实体（Customer,Contact,Interaction）、仓库（CustomerRepository）、服务（CustomerService）、控制器（CustomerController）、异常处理器（GlobalExceptionHandler）和配置类（WebConfig,SecurityConfig），5 个 XML 文件中pom.xml是 Maven 构建中枢，logback-spring.xml控制日志输出，applicationContext.xml（若存在）则用于兼容性 Bean 注入，另有两个*.xml很可能是 MyBatis Mapper 或 Spring Security 配置片段。那个唯一的index.html并非首页模板，而是通过Thymeleaf或Spring MVC ViewResolver渲染的入口页，其<head>中已包含<meta charset="utf-8">和<meta name="viewport">标准声明——这意味着它默认支持响应式布局，且编码规范符合现代 HTML5 实践。这套代码适合中小团队快速启动客户数据管理模块，也适合作为 Java 初级工程师理解「从 Controller 到 Entity 全链路」的实操样本，尤其对正在准备java面试八股文中 Spring Boot 生命周期、JPA 关系映射、RESTful 设计原则等考点的人，是比教科书更真实的靶场。
2. 从源码结构反推技术选型逻辑：为什么用 Spring Boot + JPA + Thymeleaf 而非 Spring MVC + MyBatis？
2.1 源码目录树揭示的真实技术栈分层
项目根目录下pom.xml是第一把钥匙。打开后可见<parent>标签指向spring-boot-starter-parent，版本号为2.7.18（Spring Boot 官方维护的最后一个 2.x LTS 版本），这直接锁定了技术底座。依赖项中spring-boot-starter-web提供嵌入式 Tomcat 与 REST 支持，spring-boot-starter-data-jpa表明持久层采用 JPA 规范而非原生 JDBC，h2作为内存数据库出现在<scope>runtime</scope>下，说明开发阶段无需额外安装 MySQL；spring-boot-starter-thymeleaf则证实前端渲染使用 Thymeleaf 模板引擎，而非纯 AJAX 前端框架。再看src/main/resources/目录：application.yml中spring.datasource.url: jdbc:h2:mem:testdb和spring.h2.console.enabled: true是典型 H2 控制台启用配置，spring.jpa.hibernate.ddl-auto: update表示启动时自动同步实体与表结构——这种配置方式大幅降低初学者搭建数据库门槛，但需注意生产环境必须改为validate或none。logback-spring.xml中<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">显示日志按天滚动，路径为logs/app.log，这是企业级日志管理的基本要求。
提示：
pom.xml中若存在<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-security</artifactId></dependency>，但SecurityConfig.java未实现WebSecurityConfigurerAdapter（已被 Spring Boot 2.7 弃用），则说明权限模块尚处占位状态，实际登录校验逻辑需自行补全。此时访问/h2-console不受保护，属开发阶段合理设计，但上线前必须禁用或加鉴权。
2.2 Java 实体类与 JPA 注解的映射关系解析
src/main/java/com/example/crm/entity/下的Customer.java是核心数据载体。其字段定义如下：
@Entity @Table(name = "t_customer") public class Customer { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @Column(name = "customer_name", nullable = false, length = 100) private String customerName; @Column(name = "phone", length = 20) private String phone; @Column(name = "email", unique = true, length = 100) private String email; @Column(name = "status", columnDefinition = "TINYINT DEFAULT 1") private Integer status; // 1: active, 0: inactive @OneToMany(mappedBy = "customer", cascade = CascadeType.ALL, orphanRemoval = true) private List<Interaction> interactions = new ArrayList<>(); // getter/setter 省略 }这段代码揭示三个关键设计决策：第一，@Table(name = "t_customer")显式指定物理表名，避免 Hibernate 自动生成带下划线的表名（如customer→customer），符合国内 DBA 命名习惯；第二，@Column中length和unique属性直接约束数据库字段，columnDefinition用于指定 MySQL 特有类型（如TINYINT），说明开发者预设目标数据库为 MySQL，H2 仅作开发模拟；第三，@OneToMany关联Interaction表，mappedBy指向对方实体中的customer字段，orphanRemoval = true表示删除客户时自动清理其所有交互记录——这是 CRM 业务中强一致性要求的体现，避免出现“孤儿交互”。
2.3 HTML 前端与后端模板的协同机制
唯一 HTML 文件src/main/resources/templates/index.html实际是 Thymeleaf 模板。其关键片段如下：
<!DOCTYPE html> <html lang="zh-cn" xmlns:th="http://www.thymeleaf.org"> <head> <meta charset="utf-8"/> <title>CRM 客户管理系统</title> <link rel="stylesheet" th:href="@{/css/bootstrap.min.css}"/> </head> <body> <div class="container mt-4"> <h1>客户列表</h1> <table class="table table-striped"> <thead> <tr> <th>客户名称</th> <th>联系电话</th> <th>邮箱</th> <th>状态</th> <th>操作</th> </tr> </thead> <tbody> <tr th:each="customer : ${customers}"> <td th:text="${customer.customerName}">示例名称</td> <td th:text="${customer.phone}">138****1234</td> <td th:text="${customer.email}">test@example.com</td> <td th:if="${customer.status == 1}">启用</td> <td th:unless="${customer.status == 1}">停用</td> <td> <a th:href="@{/customer/{id}(id=${customer.id})}" class="btn btn-sm btn-primary">编辑</a> <button type="button" class="btn btn-sm btn-danger" onclick="deleteCustomer([[${customer.id}]], '[[${customer.customerName}]]')">删除</button> </td> </tr> </tbody> </table> </div> <script th:src="@{/js/app.js}"></script> </body> </html>此处th:前缀是 Thymeleaf 语法，${customers}由 Controller 方法model.addAttribute("customers", customerService.findAll())传入，@{/customer/{id}}生成/customer/123路径，[[${customer.id}]]在 JS 中安全输出数值。这种写法将 HTML 变成服务端渲染模板，既保留语义化结构，又避免 XSS 风险（Thymeleaf 默认 HTML 转义）。对比<!doctype html><html lang="zh-cn"><head><meta charset="utf-8">这类纯静态声明，本项目中的 HTML 是动态内容容器，其<head>中lang="zh-cn"和charset="utf-8"已满足中文环境基础要求，无需额外修改。
2.4 XML 配置文件的实际作用与风险点
5 个 XML 文件中，pom.xml是构建核心，其余需逐个验证功能。logback-spring.xml定义日志级别与输出位置，若其中<root level="INFO">被误设为DEBUG，会导致控制台刷屏式日志，影响排查效率；applicationContext.xml若存在，通常用于声明非 Spring Boot 自动配置的 Bean，例如自定义DataSource或TransactionManager，但本项目若已用application.yml配置 H2，则此文件可能为空或仅含注释；两个*.xml文件若命名为security-config.xml和mvc-config.xml，则分别对应 Spring Security 和 MVC 的 XML 配置，但在 Spring Boot 2.7 中，这类配置应优先使用@Configuration类替代，XML 方式属于兼容性遗留。特别注意：pom.xml中若<plugin>包含maven-compiler-plugin且<source>和<target>设为1.8，而本地 JDK 为 17，则编译会失败，必须统一为17并添加<release>17</release>。
3. 本地运行与调试全流程：从 mvn clean package 到 H2 控制台验证数据
3.1 环境准备与依赖检查
确保本地已安装 JDK 17（java -version输出应为17.x.x）和 Maven 3.8.6+（mvn -v验证）。若pom.xml中<properties>定义了<java.version>17</java.version>，则无需额外配置；否则需在~/.m2/settings.xml中设置<profile>指定 JDK 路径。执行mvn clean compile前，先检查src/main/resources/application.yml中数据库配置是否与本地环境匹配：若想切换为 MySQL，需修改为：
spring: datasource: url: jdbc:mysql://localhost:3306/crm_db?useSSL=false&serverTimezone=Asia/Shanghai username: root password: your_password jpa: hibernate: ddl-auto: validate # 生产环境必须禁用 auto-update show-sql: true properties: hibernate: format_sql: true同时在pom.xml中将h2依赖<scope>runtime</scope>改为<scope>compile</scope>，并添加 MySQL 驱动：
<dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <scope>runtime</scope> </dependency>注意：MySQL 8.0+ 驱动类名为
com.mysql.cj.jdbc.Driver，需在application.yml中显式配置spring.datasource.driver-class-name: com.mysql.cj.jdbc.Driver，否则连接失败报No suitable driver。
3.2 启动应用并验证端口与路由
执行mvn spring-boot:run启动应用。控制台输出Tomcat started on port(s): 8080 (http)即表示成功。此时访问http://localhost:8080/h2-console，在 H2 控制台登录界面输入：
- JDBC URL:
jdbc:h2:mem:testdb - Username:
sa - Password: （留空）
点击 Connect 进入数据库控制台，执行SELECT * FROM t_customer;应返回空结果集（因无初始化数据）。若报错Table "T_CUSTOMER" not found，说明 JPA 未自动建表，需检查application.yml中spring.jpa.hibernate.ddl-auto: update是否拼写正确，且Customer.java上@Entity注解是否存在。
3.3 使用 curl 模拟 REST API 测试
系统默认提供 REST 接口，无需启动浏览器即可验证。执行以下命令创建首个客户：
curl -X POST http://localhost:8080/api/customers \ -H "Content-Type: application/json" \ -d '{"customerName":"张三","phone":"13800138000","email":"zhangsan@example.com","status":1}'返回{"id":1,"customerName":"张三",...}表示创建成功。再执行查询：
curl http://localhost:8080/api/customers应返回包含该客户的 JSON 数组。若返回404，检查CustomerController.java中@RequestMapping("/api/customers")是否与@RestController类注解路径一致；若返回405 Method Not Allowed，确认@PostMapping和@GetMapping注解是否正确标注在方法上。
3.4 前端页面访问与交互调试
访问http://localhost:8080/加载index.html。若页面空白，打开浏览器开发者工具（F12），查看 Console 是否报Failed to load resource: the server responded with a status of 404 ()，常见原因有二：一是src/main/resources/static/css/bootstrap.min.css路径错误，应确认文件实际存放于static/css/目录；二是 Thymeleaf 未正确解析${customers}，此时需检查 Controller 方法是否返回String且model.addAttribute("customers", ...)调用是否在return "index";之前。若按钮点击无反应，检查src/main/resources/static/js/app.js中deleteCustomer函数是否正确定义，且onclick事件中[[${customer.id}]]是否被 Thymeleaf 正确替换为数字。
4. 关键参数调优与常见故障定位：解决 H2 数据丢失、JPA 关联失效、Thymeleaf 渲染异常
4.1 H2 数据库重启即失问题的两种解决方案
H2 内存模式（jdbc:h2:mem:testdb）的特点是 JVM 停止后数据清空，这在开发阶段便于测试，但若需保留数据，必须切换为文件模式。修改application.yml：
spring: datasource: url: jdbc:h2:file:./data/crm_db;DB_CLOSE_ON_EXIT=FALSE;DB_CLOSE_DELAY=-1./data/crm_db表示项目根目录下的data子目录，DB_CLOSE_ON_EXIT=FALSE防止应用关闭时数据库关闭，DB_CLOSE_DELAY=-1延迟关闭时间。首次启动会自动创建data/crm_db.mv.db文件。若仍出现数据丢失，检查pom.xml中 H2 依赖版本是否为2.1.214（Spring Boot 2.7 默认），旧版本存在文件锁问题，升级至2.2.222可解决。
4.2 JPA OneToMany 关联不加载的根源与修复
若Customer查询结果中interactions字段始终为空列表，即使数据库t_interaction表中有对应记录，问题必在Interaction.java实体类。检查其@ManyToOne注解：
@Entity @Table(name = "t_interaction") public class Interaction { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @Column(name = "content") private String content; @ManyToOne(fetch = FetchType.LAZY) // 必须为 LAZY，否则 N+1 查询 @JoinColumn(name = "customer_id") // 外键字段名必须与数据库列名一致 private Customer customer; // getter/setter }关键点：@JoinColumn(name = "customer_id")中name值必须与t_interaction表的外键列名完全相同（区分大小写），若数据库列为customer_id而代码写成customerId，则关联失败。此外，fetch = FetchType.LAZY是性能必需，若误设为EAGER，会导致查询单个客户时加载全部交互记录，引发 N+1 查询问题。
4.3 Thymeleaf 模板中中文乱码与资源 404 的联合排查
若index.html中中文显示为??，首先确认application.yml中已配置：
spring: http: encoding: charset: UTF-8 enabled: true force: true其次检查src/main/resources/templates/index.html第一行是否为<!DOCTYPE html>，而非 BOM 头导致的编码识别错误。用 VS Code 打开文件，右下角查看编码是否为UTF-8，若为UTF-8 with BOM，需另存为UTF-8（无 BOM）。对于 CSS/JS 404，确认src/main/resources/static/目录结构是否为static/css/bootstrap.min.css和static/js/app.js，Spring Boot 默认将static作为静态资源根路径，@{/css/bootstrap.min.css}会映射为/css/bootstrap.min.css，因此文件必须放在static/css/下，而非resources/css/。
4.4 Maven 编译失败的高频场景与修复指令
执行mvn clean compile报错package org.springframework.boot does not exist，说明 Maven 未正确下载 Spring Boot 依赖。先执行mvn dependency:resolve强制解析依赖，若卡在Downloading from central: https://repo.maven.apache.org/maven2/...，检查~/.m2/settings.xml中镜像配置是否有效，推荐使用阿里云镜像：
<mirror> <id>aliyunmaven</id> <mirrorOf>*</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror>若报错Cannot resolve symbol 'xxx'（如CustomerRepository），检查CustomerRepository.java是否继承JpaRepository<Customer, Long>，且类路径是否为src/main/java/com/example/crm/repository/CustomerRepository.java，包声明是否为package com.example.crm.repository;。任何路径或包名不匹配都会导致编译器找不到符号。
5. 二次开发实战：为 CRM 系统增加客户等级字段与分级查询接口
5.1 在 Customer 实体中新增枚举类型字段
CRM 业务常需按客户价值分级（如 VIP、普通、潜在），需扩展Customer.java。首先定义枚举类CustomerLevel.java：
package com.example.crm.enums; public enum CustomerLevel { VIP(1, "VIP客户"), NORMAL(2, "普通客户"), POTENTIAL(3, "潜在客户"); private final int code; private final String description; CustomerLevel(int code, String description) { this.code = code; this.description = description; } public int getCode() { return code; } public String getDescription() { return description; } }然后在Customer.java中添加字段：
@Column(name = "level_code", nullable = false, columnDefinition = "TINYINT DEFAULT 2") private Integer levelCode = CustomerLevel.NORMAL.getCode(); // 默认普通客户 @Transient // 非数据库字段，仅用于传输 private String levelDescription; // getter/setter public String getLevelDescription() { return CustomerLevel.values()[levelCode - 1].getDescription(); }@Transient标注levelDescription不映射数据库，避免冗余存储；levelCode用整数存储，比字符串更节省空间且便于排序。
5.2 创建分级查询的 Repository 方法与 Service 封装
在CustomerRepository.java中添加自定义查询方法：
@Repository public interface CustomerRepository extends JpaRepository<Customer, Long> { // 按等级代码查询 List<Customer> findByLevelCode(Integer levelCode); // 按等级代码和名称模糊查询（JPQL） @Query("SELECT c FROM Customer c WHERE c.levelCode = :levelCode AND c.customerName LIKE %:keyword%") List<Customer> findByLevelCodeAndName(@Param("levelCode") Integer levelCode, @Param("keyword") String keyword); // 原生 SQL 查询，支持复杂条件 @Query(value = "SELECT * FROM t_customer WHERE level_code = ?1 AND status = 1 ORDER BY id DESC LIMIT ?2", nativeQuery = true) List<Customer> findActiveByLevel(Integer levelCode, Integer limit); }CustomerService.java中封装业务逻辑：
@Service public class CustomerService { private final CustomerRepository customerRepository; public CustomerService(CustomerRepository customerRepository) { this.customerRepository = customerRepository; } public List<Customer> findCustomersByLevel(Integer levelCode) { return customerRepository.findByLevelCode(levelCode); } public List<Customer> searchByLevelAndKeyword(Integer levelCode, String keyword) { return customerRepository.findByLevelCodeAndName(levelCode, keyword); } public List<Customer> findTopActiveByLevel(Integer levelCode, Integer count) { return customerRepository.findActiveByLevel(levelCode, count); } }5.3 暴露分级查询的 REST 接口并验证
在CustomerController.java中添加新端点：
@RestController @RequestMapping("/api/customers") public class CustomerController { private final CustomerService customerService; public CustomerController(CustomerService customerService) { this.customerService = customerService; } // GET /api/customers/level/1?limit=10 @GetMapping("/level/{levelCode}") public ResponseEntity<List<Customer>> getCustomersByLevel( @PathVariable Integer levelCode, @RequestParam(defaultValue = "10") Integer limit) { List<Customer> customers = customerService.findTopActiveByLevel(levelCode, limit); return ResponseEntity.ok(customers); } // GET /api/customers/search?level=1&keyword=张 @GetMapping("/search") public ResponseEntity<List<Customer>> searchCustomers( @RequestParam Integer level, @RequestParam String keyword) { List<Customer> customers = customerService.searchByLevelAndKeyword(level, keyword); return ResponseEntity.ok(customers); } }启动应用后，执行：
# 查询 VIP 客户前 5 条 curl "http://localhost:8080/api/customers/level/1?limit=5" # 搜索 VIP 客户中姓名含“张”的记录 curl "http://localhost:8080/api/customers/search?level=1&keyword=张"返回结果中每个Customer对象将包含levelCode和levelDescription字段，前端可直接展示“VIP客户”而非数字 1。
5.4 前端模板中动态渲染客户等级
修改index.html的客户列表表格，增加等级列：
<tr th:each="customer : ${customers}"> <td th:text="${customer.customerName}">示例名称</td> <td th:text="${customer.phone}">138****1234</td> <td th:text="${customer.email}">test@example.com</td> <td th:switch="${customer.levelCode}"> <span th:case="1" th:text="'VIP客户'">VIP</span> <span th:case="2" th:text="'普通客户'">普通</span> <span th:case="3" th:text="'潜在客户'">潜在</span> </td> <td> <a th:href="@{/customer/{id}(id=${customer.id})}" class="btn btn-sm btn-primary">编辑</a> </td> </tr>th:switch语句根据levelCode值动态显示中文描述，无需后端额外传levelDescription，减少网络传输量。若需更灵活的国际化支持，可将CustomerLevel枚举与messages.properties关联，但当前方案已满足基础需求。
提示：新增字段后，首次启动应用时
spring.jpa.hibernate.ddl-auto: update会自动为t_customer表添加level_code列，但已有数据该字段值为NULL，需在application.yml中设置columnDefinition = "TINYINT DEFAULT 2"并在Customer构造函数中初始化levelCode = 2，确保历史数据默认为普通客户。
本文还有配套的精品资源，点击获取
