“物集”是一个围绕商品信息管理开发的全栈练习项目。它的核心需求并不复杂:完成商品的新增、查询、修改和删除,并提供一个可以直接操作这些功能的网页。
真正开始开发后,我发现一个完整的 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 能让我完整处理数据库创建、连接参数、字符编码和运行环境配置。
从数据模型开始
商品模型包含五个字段:编号、名称、价格、库存和描述。
| 字段 | 数据类型 | 约束 |
|---|---|---|
id | BIGINT | 主键、自增 |
name | VARCHAR(100) | 必填,最长 100 个字符 |
price | DECIMAL(12,2) | 必填,不得小于 0 |
stock | INTEGER | 必填,不得小于 0 |
description | VARCHAR(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 ── 读写 MySQLController 只关心 HTTP 请求和响应,Service 负责商品规则与事务,Repository 负责持久化。这样可以避免把参数解析、业务判断和数据库操作全部堆在同一个类中。
商品列表支持关键词、页码和每页数量。Service 使用 Spring Data JPA 的分页和排序能力,默认按照商品编号倒序展示,让新创建的商品排在前面:
@Service@Transactionalpublic 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=updatespring.jpa.open-in-view=false
server.address=127.0.0.1server.port=8080启动前可以在终端临时设置变量:
$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。
除此之外,我还编写了完整的接口验收流程:
- 创建一个带随机名称的临时商品,确认返回
201; - 根据编号读取商品详情;
- 使用关键词搜索并检查分页结果;
- 修改价格、库存和描述;
- 提交非法数据,确认返回
400; - 删除商品,确认返回
204; - 再次查询,确认返回
404; - 检查 OpenAPI、Swagger UI 和首页是否能够访问;
- 无论中途是否失败,都清理临时测试数据。
这一流程会连接真实的 MySQL,而不是只在模拟环境中运行。最终验证结果包括 Maven 测试通过、应用成功连接 MySQL、Tomcat 在本地端口启动、前端与 Swagger 可访问,以及完整 CRUD 流程通过。
开发中遇到的问题
CRUD 不只是四个数据库操作
开始时我把重点放在新增、查询、修改和删除上,但实现页面后才发现,分页边界、输入校验、异常响应、重复提交和空状态同样重要。一个接口“能返回数据”和一个系统“能够稳定使用”之间,还有不少工作。
金额类型必须从一开始选对
如果先用 double,后期再改成 BigDecimal,DTO、实体、数据库字段和测试都需要一起调整。涉及价格的数据应尽早确定精度,并在 Java 校验和数据库定义中保持一致。
校验应该放在系统边界
浏览器校验只能改善交互,不能代替后端校验。调用者可以绕过网页直接请求 API,因此真正的数据规则必须由后端执行。前端可以再次校验,但后端才是最终边界。
自动验收比手动点击更可靠
手动操作适合观察界面,却容易漏掉异常分支。将“新增—查询—修改—非法输入—删除—再次查询”写成可重复的验收脚本后,每次修改都能快速确认主流程没有被破坏。
配置应与代码分离
数据库密码不属于业务代码。使用环境变量后,同一个 JAR 可以在不同机器上运行,也能避免敏感信息进入版本控制。这个习惯比项目本身的规模更重要。
当前限制与后续方向
目前“物集”仍是一个单用户的商品管理练习项目,暂未包含登录认证、角色权限、商品图片上传、并发编辑冲突处理和正式的数据库迁移工具。
如果继续完善,我会优先加入以下能力:
- 使用 Spring Security 实现登录和权限控制;
- 使用 Flyway 管理数据库版本;
- 为列表增加分类、价格区间和库存状态筛选;
- 增加乐观锁,避免多人同时编辑时互相覆盖;
- 补充容器化配置和生产环境日志;
- 将接口验收接入持续集成流程。
写在最后
“物集”让我完整经历了一次小型全栈项目的开发过程:从定义数据模型,到设计 REST API,再到实现前端交互、连接 MySQL 和自动验证功能。
这次实践最重要的收获,是开始把 CRUD 当作一个完整系统来处理。只有正常流程、错误处理、数据安全、交互体验和验证手段能够相互配合,项目才算真正完成。