2947 字
15 分钟
从零实现物集:Spring Boot 商品管理系统开发记录

“物集”是一个围绕商品信息管理开发的全栈练习项目。它的核心需求并不复杂:完成商品的新增、查询、修改和删除,并提供一个可以直接操作这些功能的网页。

真正开始开发后,我发现一个完整的 CRUD 项目远不只是写四个接口。数据应该怎样校验?金额应该使用什么类型?查询如何支持搜索和分页?接口出错时前端如何得到清楚的提示?项目又该怎样连接真实数据库并完成自动验收?这些问题共同决定了项目是否真正可用。

本文记录“物集”从空项目到完整运行的开发过程,以及这次实践中值得保留的经验。

需求与技术选型#

“物集”最终实现了以下功能:

  • 新增、查看、编辑和删除商品;
  • 按商品名称模糊搜索;
  • 分页浏览商品列表并调整每页数量;
  • 显示当前页库存总量、在售商品数和低库存状态;
  • 对名称、价格、库存和描述进行后端校验;
  • 使用统一格式返回参数错误和资源不存在错误;
  • 通过 Swagger UI 查看并调试接口;
  • 将前端页面和后端服务放进同一个可执行 JAR 中。

项目采用的主要技术如下:

模块技术
开发语言Java 21
后端框架Spring Boot 3.5
Web 层Spring MVC
数据访问Spring Data JPA、Hibernate
数据库MySQL 8
参数校验Bean Validation
接口文档springdoc-openapi、Swagger UI
前端HTML、CSS、JavaScript、Fetch API
测试JUnit 5、MockMvc
构建工具Maven

最初我考虑过使用 H2,让项目无需额外配置就能启动。但作业需要体现真实数据库的连接和持久化过程,因此最终选择 MySQL。H2 更适合快速演示,而 MySQL 能让我完整处理数据库创建、连接参数、字符编码和运行环境配置。

从数据模型开始#

商品模型包含五个字段:编号、名称、价格、库存和描述。

字段数据类型约束
idBIGINT主键、自增
nameVARCHAR(100)必填,最长 100 个字符
priceDECIMAL(12,2)必填,不得小于 0
stockINTEGER必填,不得小于 0
descriptionVARCHAR(1000)可选,最长 1000 个字符

金额没有使用 double,而是使用 BigDecimal。二进制浮点数无法精确表示部分十进制小数,直接用于金额计算可能产生误差。BigDecimal 配合数据库的 DECIMAL(12,2),可以明确限制小数位数和取值范围。

接口请求使用独立的 DTO 接收数据,并通过注解声明规则:

public record ProductRequest(
@NotBlank
@Size(max = 100)
String name,
@NotNull
@DecimalMin("0.00")
@Digits(integer = 10, fraction = 2)
BigDecimal price,
@NotNull
@Min(0)
Integer stock,
@Size(max = 1000)
String description
) {}

这样做有两个好处。第一,错误数据会在进入业务逻辑前被拦截;第二,接口能够明确告诉调用者哪个字段不符合规则,而不是等数据库报出难以理解的异常。

用分层结构划清职责#

后端按照 Controller、Service、Repository 三层组织:

HTTP Request
│
▼
Controller ── 解析参数、设置状态码
│
▼
Service ── 处理业务和事务
│
▼
Repository ── 读写 MySQL

Controller 只关心 HTTP 请求和响应,Service 负责商品规则与事务,Repository 负责持久化。这样可以避免把参数解析、业务判断和数据库操作全部堆在同一个类中。

商品列表支持关键词、页码和每页数量。Service 使用 Spring Data JPA 的分页和排序能力,默认按照商品编号倒序展示,让新创建的商品排在前面:

@Service
@Transactional
public class ProductService {
@Transactional(readOnly = true)
public Page<Product> list(String keyword, int page, int size) {
PageRequest pageable = PageRequest.of(
page,
size,
Sort.by("id").descending()
);
return repository.findByNameContainingIgnoreCase(
keyword.trim(),
pageable
);
}
}

只读查询使用 @Transactional(readOnly = true),写操作则放在普通事务中。虽然这个项目的业务不复杂,但明确事务边界能让代码行为更清楚,也为以后增加批量操作等功能打下基础。

REST API 设计#

项目围绕 /api/products 提供五个主要接口:

方法路径功能成功状态码
POST/api/products新增商品201 Created
GET/api/products搜索并分页查询200 OK
GET/api/products/{id}查询商品详情200 OK
PUT/api/products/{id}完整更新商品200 OK
DELETE/api/products/{id}删除商品204 No Content

列表接口的调用示例如下:

GET /api/products?keyword=鼠标&page=0&size=10

新增成功后,接口除了返回 201 Created,还会通过 Location 响应头指出新资源的地址。删除成功则返回 204 No Content。这些细节让接口状态码和实际行为保持一致。

统一处理异常#

只完成正常流程还不够。用户可能提交空名称、负数库存、格式错误的 JSON,也可能访问已经被删除的商品。

项目使用全局异常处理器将这些情况转换成结构统一的响应:

public record ApiError(
int status,
String message,
Map<String, String> errors
) {}

例如,当名称为空且库存小于 0 时,接口返回 400 Bad Request,并在 errors 中分别说明字段问题;查询不存在的商品时返回 404 Not Found。前端只需识别同一种错误结构,就能显示清楚的提示。

这种设计也让我认识到,API 的可用性不仅取决于成功时返回什么,还取决于失败时能否提供稳定、明确的信息。

前端与后端一起交付#

为了让项目启动后即可使用,我没有再引入单独的 Node.js 前端工程,而是把页面放在 Spring Boot 的静态资源目录中:

src/main/resources/static/
├── index.html
├── css/
│ └── app.css
└── js/
└── app.js

浏览器通过 Fetch API 请求后端:

async function loadProducts(page = 0) {
const keyword = searchInput.value.trim();
const params = new URLSearchParams({
keyword,
page: String(page),
size: String(pageSize)
});
const response = await fetch(`/api/products?${params}`);
if (!response.ok) {
throw new Error("商品列表加载失败");
}
const data = await response.json();
renderProducts(data);
}

页面包括搜索栏、统计卡片、商品表格、分页器以及新增和编辑共用的弹窗表单。删除操作必须经过确认,保存和删除期间会禁用按钮,避免重复请求;操作结果则通过轻量提示消息反馈给用户。

在渲染商品名称和描述时,我使用 textContent 写入用户数据,避免把输入内容直接当作 HTML 解析。搜索请求还增加了请求编号:只有最后一次请求可以更新页面,防止用户快速输入时,较慢的旧请求覆盖最新结果。

这些细节虽然不属于 CRUD 本身,却会直接影响实际使用体验。

数据库配置不写死敏感信息#

数据库地址、账号和密码会随运行环境变化,因此配置文件只提供本地默认值,并允许通过环境变量覆盖:

spring.datasource.url=${MYSQL_URL:jdbc:mysql://localhost:3307/product_crud?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai}
spring.datasource.username=${MYSQL_USERNAME:root}
spring.datasource.password=${MYSQL_PASSWORD:}
spring.jpa.hibernate.ddl-auto=update
spring.jpa.open-in-view=false
server.address=127.0.0.1
server.port=8080

启动前可以在终端临时设置变量:

Terminal window
$env:MYSQL_URL = "jdbc:mysql://localhost:3306/product_crud?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai"
$env:MYSQL_USERNAME = "db_user"
$env:MYSQL_PASSWORD = Read-Host "MySQL password" -AsSecureString

实际脚本会在内存中转换密码后启动程序,不把密码保存进源码或提交记录。公开项目中最容易忽视的风险之一,就是为了方便运行而把数据库密码直接写进配置文件。

用 Swagger 检查接口#

接入 springdoc-openapi 后,程序会根据 Controller 和 DTO 自动生成 OpenAPI 文档。启动项目后,可以直接在 Swagger UI 中查看接口、参数和响应,并发送测试请求。

Swagger 的价值不只是生成一张接口页面。它还可以帮助检查接口是否完整暴露、字段约束是否正确,以及状态码和请求结构是否符合设计。相比手工维护一份容易过期的接口说明,从实际代码生成文档更可靠。

测试不只验证“能启动”#

项目使用 MockMvc 测试 Web 层的异常分支,例如:

  • 空商品名称、负数价格和负数库存应返回 400;
  • 非法分页参数应被拒绝;
  • JSON 格式错误时应返回结构化错误;
  • 查询不存在的商品应返回 404;
  • 校验失败时不应继续调用 Service。

除此之外,我还编写了完整的接口验收流程:

  1. 创建一个带随机名称的临时商品,确认返回 201;
  2. 根据编号读取商品详情;
  3. 使用关键词搜索并检查分页结果;
  4. 修改价格、库存和描述;
  5. 提交非法数据,确认返回 400;
  6. 删除商品,确认返回 204;
  7. 再次查询,确认返回 404;
  8. 检查 OpenAPI、Swagger UI 和首页是否能够访问;
  9. 无论中途是否失败,都清理临时测试数据。

这一流程会连接真实的 MySQL,而不是只在模拟环境中运行。最终验证结果包括 Maven 测试通过、应用成功连接 MySQL、Tomcat 在本地端口启动、前端与 Swagger 可访问,以及完整 CRUD 流程通过。

开发中遇到的问题#

CRUD 不只是四个数据库操作#

开始时我把重点放在新增、查询、修改和删除上,但实现页面后才发现,分页边界、输入校验、异常响应、重复提交和空状态同样重要。一个接口“能返回数据”和一个系统“能够稳定使用”之间,还有不少工作。

金额类型必须从一开始选对#

如果先用 double,后期再改成 BigDecimal,DTO、实体、数据库字段和测试都需要一起调整。涉及价格的数据应尽早确定精度,并在 Java 校验和数据库定义中保持一致。

校验应该放在系统边界#

浏览器校验只能改善交互,不能代替后端校验。调用者可以绕过网页直接请求 API,因此真正的数据规则必须由后端执行。前端可以再次校验,但后端才是最终边界。

自动验收比手动点击更可靠#

手动操作适合观察界面,却容易漏掉异常分支。将“新增—查询—修改—非法输入—删除—再次查询”写成可重复的验收脚本后,每次修改都能快速确认主流程没有被破坏。

配置应与代码分离#

数据库密码不属于业务代码。使用环境变量后,同一个 JAR 可以在不同机器上运行,也能避免敏感信息进入版本控制。这个习惯比项目本身的规模更重要。

当前限制与后续方向#

目前“物集”仍是一个单用户的商品管理练习项目,暂未包含登录认证、角色权限、商品图片上传、并发编辑冲突处理和正式的数据库迁移工具。

如果继续完善,我会优先加入以下能力:

  • 使用 Spring Security 实现登录和权限控制;
  • 使用 Flyway 管理数据库版本;
  • 为列表增加分类、价格区间和库存状态筛选;
  • 增加乐观锁,避免多人同时编辑时互相覆盖;
  • 补充容器化配置和生产环境日志;
  • 将接口验收接入持续集成流程。

写在最后#

“物集”让我完整经历了一次小型全栈项目的开发过程:从定义数据模型,到设计 REST API,再到实现前端交互、连接 MySQL 和自动验证功能。

这次实践最重要的收获,是开始把 CRUD 当作一个完整系统来处理。只有正常流程、错误处理、数据安全、交互体验和验证手段能够相互配合,项目才算真正完成。