Java接口规范升级 —— 给你的 Java 接口 “穿西装”（参数不瞎填，返回不乱码）

咱们实现了 “添加图书” 功能，但你有没有发现一个问题？—— 用户可以随便传数据：书名空着能加、价格填负数能加、出版时间填 “2025-13-32” 这种不存在的日期也能加，就像奶茶店不问你 “要几分糖、加不加珍珠”，直接给你做一杯 “苦到齁的珍珠奶茶”，客人肯定不满意。

更麻烦的是，接口返回格式还乱：成功时返回图书列表，失败时返回 “添加失败” 字符串，前端开发要对着两种格式写两套逻辑，像收到奶茶时，有时候是 “正常杯子装”，有时候是 “塑料袋裹着”，整理起来超麻烦。

今天这篇，咱们就给接口做 “规范化改造”：用参数校验让用户 “按规矩传数据”（书名不能为空、价格必须正数），用统一返回格式让接口 “说话一个调”（成功失败都返回 JSON，结构一致），改造完的接口就像穿了西装的奶茶店店员 —— 专业、整齐、不翻车。

一、先搞懂：为什么要做接口规范？（奶茶店的 “标准化服务” analogy）

咱们先拿奶茶店举个例子，你就懂接口规范的重要性了：

• 没规范的奶茶店：客人说 “要一杯奶茶”，店员不问甜度、冰度、加不加料，直接做了杯 “全糖冰饮加珍珠”，客人可能不喝甜的，直接差评；
• 有规范的奶茶店：客人点单时，店员会问 “几分糖（3/5/7 分）、什么温度（冰 / 温 / 热）、加什么料（珍珠 / 椰果 / 布丁）”，确认清楚再做，客人满意度拉满。

接口规范也是一个道理：

• 参数校验 = 店员问清需求，避免 “瞎做”（比如书名不能为空、价格必须 > 0）；
• 统一返回格式 = 奶茶统一用 “带 logo 的杯子装”，不管是珍珠奶茶还是果茶，包装一致，客人拿得顺手（前端解析方便）。

改造前后的接口对比，一眼就能看出差别：

场景	改造前（不规范）	改造后（规范）
书名空着添加	成功添加，数据库存 “空书名”	返回 “图书名称不能为空”，拒绝添加
价格填 - 50	成功添加，数据库存 “-50”	返回 “价格必须大于 0”，拒绝添加
接口返回格式	成功：[{id:1, bookName:"Java"}]；失败："添加失败"	成功：{code:200, msg:"操作成功", data:[...]}；失败：{code:400, msg:"图书名称不能为空", data:null}

二、实操 1：参数校验 —— 让用户 “按规矩传数据”（Spring Validation 上手）

参数校验用 Spring Boot 自带的spring-boot-starter-validation，不用自己写 if 判断（比如if (bookName == null) return "书名不能为空"），像给接口装了个 “自动安检机”，不符合规矩的数据直接拦下来。

步骤 1：加依赖（给安检机 “通电”）

打开pom.xml，添加参数校验的依赖，就像给奶茶店装 “点单系统”：

xml

<!-- 参数校验依赖：Spring Boot自带，不用记版本，和Spring Boot版本一致 -->
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId>
</dependency>

加完点 IDEA 右下角的 “Import Changes”，依赖下载完，安检机就通电了。

步骤 2：实体类加校验注解（定 “点单规矩”）

打开entity/Book.java，给需要校验的字段加注解，比如 “书名不能为空”“价格必须正数”，这些注解就是 “点单规矩”：

java

运行

package com.example.bookmanage.entity;import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
import javax.validation.constraints.*; // 导入校验注解
import java.math.BigDecimal;
import java.util.Date;@Data
@TableName("book")
public class Book {@TableId(type = IdType.AUTO)private Long id;//