NOTE
欢迎来到“从零搭建AI小程序全栈实战”系列文章！
此为本系列的第三篇文章，你可以点击跳转到第一篇文章在系列文章中快速跳转。

一、这篇文章将要做的#

1.1 回顾#

上一篇我们完成了CRUD、图片上传、调用AI推理
当前状态：接口能跑，但返回格式参差不齐，出错时直接500页面

1.2 目标#

让后端”像个正经项目”
四个加固项：
1. 统一响应格式——前端解析不再猜
2. 全局异常处理——错误也返回JSON
3. Swagger接口文档——在线可测试
4. 数据校验——非法参数提前拦截

二、统一响应格式#

2.0 为什么需要统一格式#

先看现在的问题，你现在 ImageController 的返回是这样的：

1
// 返回 ImageRecord 对象
2
@PostMapping
3
public ImageRecord create(@RequestBody ImageRecord record) {
4
    return repository.save(record);
5
}
6

7
// 返回字符串
8
@DeleteMapping("/{id}")
9
public String delete(@PathVariable Long id) {
10
    repository.deleteById(id);
11
    return "deleted";
12
}

前端收到的东西会像这样：

1
// 调用创建接口可能返回：
2
{"id":1, "originalFilename":"test.jpg", "imageUrl":"/uploads/test.jpg", ...}
3

4
// 调用删除接口可能返回：
5
"deleted"

问题来了：

前端同学不知道返回的到底是成功还是失败，只能猜
返回格式不统一，前端要写两套处理逻辑
万一出错，Spring Boot 直接扔个 500 页面的 HTML，前端根本没法解析

统一格式后，无论是创建、查询、删除、所有接口都返回这种结构：

1
{
2
  "code": 200,        // 200=成功，400=参数错误，500=服务器错误
3
  "message": "success", // 给人类看的提示
4
  "data": {            // 真正的数据放在这里
5
    "id": 1,
6
    "originalFilename": "test.jpg"
7
  }
8
}

前端只需要写一套解析逻辑，看 code 就能知道成败。

2.1 创建 Result 类#

在服务器上创建 src/main/java/com/example/demo/common/Result.java：

1
package com.example.demo.common;
2

3
public class Result<T> {
4
    private int code;
5
    private String message;
6
    private T data;
7

8
    // 无参构造（必须，框架反射用）
9
    public Result() {}
10

11
    // 全参构造
12
    public Result(int code, String message, T data) {
13
        this.code = code;
14
        this.message = message;
15
        this.data = data;
16
    }
17

18
    // ========== 静态工厂方法 ==========
19

20
    // 成功，带数据
21
    public static <T> Result<T> success(T data) {
22
        return new Result<>(200, "success", data);
23
    }
24

25
    // 成功，不带数据（比如删除操作）
26
    public static <T> Result<T> success() {
27
        return new Result<>(200, "success", null);
28
    }
29

30
    // 失败，自定义状态码和消息
31
    public static <T> Result<T> error(int code, String message) {
32
        return new Result<>(code, message, null);
33
    }
34

35
    // ========== Getter / Setter ==========
36
    public int getCode() { return code; }
37
    public void setCode(int code) { this.code = code; }
38

39
    public String getMessage() { return message; }
40
    public void setMessage(String message) { this.message = message; }
41

42
    public T getData() { return data; }
43
    public void setData(T data) { this.data = data; }
44
}

代码	什么意思
`Result<T>`	泛型，`T` 可以是 String、ImageRecord、List，复用同一个类
`private T data`	实际返回的数据，类型由调用时决定
`public static <T> Result<T> success(T data)`	静态方法，直接 `Result.success(某对象)` 就能生成一个成功响应
`Result.error(400, "参数错误")`	返回错误时用，前端看到 `code=400` 就知道出问题了

2.2 改造 Controller#

把 ImageController 每个方法的返回值都包一层 Result。

2.2.1 导入 Result 类#

在 ImageController.java 顶部加上：

1
import com.example.demo.common.Result;

2.2.2 新建记录——返回创建好的数据#

原来：

1
@PostMapping
2
public ImageRecord create(@RequestBody ImageRecord record) {
3
    return repository.save(record);
4
}

改后：

1
@PostMapping
2
public Result<ImageRecord> create(@RequestBody ImageRecord record) {
3
    ImageRecord saved = repository.save(record);
4
    return Result.success(saved);
5
}

2.2.3 查询列表——返回数组#

原来：

1
@GetMapping
2
public List<ImageRecord> list() {
3
    return repository.findAll();
4
}

改后：

1
@GetMapping
2
public Result<List<ImageRecord>> list() {
3
    List<ImageRecord> records = repository.findAll();
4
    return Result.success(records);
5
}

2.2.4 查询单个——不存在时返回错误#

原来：

1
@GetMapping("/{id}")
2
public ImageRecord getById(@PathVariable Long id) {
3
    return repository.findById(id).orElse(null);
4
}

改后：

1
@GetMapping("/{id}")
2
public Result<ImageRecord> getById(@PathVariable Long id) {
3
    return repository.findById(id)
4
        .map(Result::success)
5
        .orElse(Result.error(404, "记录不存在"));
6
}

2.2.5 删除——返回成功但不带数据#

原来：

1
@DeleteMapping("/{id}")
2
public String delete(@PathVariable Long id) {
3
    repository.deleteById(id);
4
    return "deleted";
5
}

改后：

1
@DeleteMapping("/{id}")
2
public Result<Void> delete(@PathVariable Long id) {
3
    repository.deleteById(id);
4
    return Result.success();  // data = null
5
}

2.2.6 上传并识别——返回待识别结果的记录#

原来：

1
@PostMapping("/upload-and-recognize")
2
public ImageRecord uploadAndRecognize(@RequestParam("file") MultipartFile file) throws IOException {
3
    // ...上传和调用AI...
4
    return repository.save(record);
5
}

改后：

1
@PostMapping("/upload-and-recognize")
2
public Result<ImageRecord> uploadAndRecognize(@RequestParam("file") MultipartFile file) throws IOException {
3
    // ...上传和调用AI逻辑不变...
4
    ImageRecord saved = repository.save(record);
5
    return Result.success(saved);
6
}

2.3 验证#

继续使用 curl 查看效果：

1
# 创建
2
curl -X POST http://localhost:8080/api/images \
3
  -H "Content-Type: application/json" \
4
  -d '{"originalFilename":"test.jpg", "imageUrl":"/uploads/test.jpg"}'

返回会变成：

1
{
2
  "code": 200,
3
  "message": "success",
4
  "data": {
5
    "id": 1,
6
    "originalFilename": "test.jpg",
7
    "imageUrl": "/uploads/test.jpg",
8
    ...
9
  }
10
}

当我们尝试用一个不存在的编号查找图片时：

1
# 查询
2
curl http://localhost:8080/api/images/999

此时会返回：

1
{
2
  "code": 404,
3
  "message": "记录不存在",
4
  "data": null
5
}

三、全局异常处理#

3.0 为什么我们需要这个#

因为：

即使我们写得再好，运行时总有意想不到的异常
不能让前端收到HTML格式的500错误页面

现在，让所有未捕获的异常和手动抛出的异常都返回统一格式的 Result。

创建 src/main/java/com/example/demo/exception/GlobalExceptionHandler.java：

1
package com.example.demo.exception;
2

3
import com.example.demo.common.Result;
4
import org.springframework.web.bind.annotation.ExceptionHandler;
5
import org.springframework.web.bind.annotation.RestControllerAdvice;
6

7
@RestControllerAdvice
8
public class GlobalExceptionHandler {
9

10
    @ExceptionHandler(Exception.class)
11
    public Result handleException(Exception e) {
12
        // 记录日志（实际项目用 log）
13
        e.printStackTrace();
14
        return Result.error(500, "服务器内部错误：" + e.getMessage());
15
    }
16

17
    // 可以针对性捕获，比如参数校验异常
18
}

之后再故意制造错误（如请求一个不存在的接口），返回的 JSON 会是：

1
{"code":500, "message":"服务器内部错误：...", "data":null}

四、Springdoc 接口文档#

4.0 为什么我们需要这个#

现在你的后端有七八个接口了：健康检查、CRUD、上传、识别等等。你自己写的时候可能记得清清楚楚，但过两周再回来看，或者前端同学来问你”这个接口参数是什么、返回什么”，你大概率要翻半天代码才能答上来。

Springdoc 的作用就是自动生成一份在线接口文档，列出所有接口的地址、参数、返回格式，还能直接在页面上测试。省去了手动写文档的麻烦，也方便前后端联调。

4.1 添加依赖#

在 pom.xml 的 <dependencies> 中添加 SpringDoc（Spring Boot 3.x 对应的 Swagger 实现）：

1
<dependency>
2
    <groupId>org.springdoc</groupId>
3
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
4
    <version>2.3.0</version>
5
</dependency>

springdoc-openapi-starter-webmvc-ui 这个依赖已经内置了 Swagger UI，不需要额外引入任何 UI 包。

4.2 配置类（可选）#

大多数情况下 springdoc 零配置就能跑，但加上配置类可以让文档页面更专业。

新建 src/main/java/com/example/demo/config/SpringDocConfig.java：

1
package com.example.demo.config;
2

3
import io.swagger.v3.oas.models.OpenAPI;
4
import io.swagger.v3.oas.models.info.Info;
5
import org.springframework.context.annotation.Bean;
6
import org.springframework.context.annotation.Configuration;
7

8
@Configuration
9
public class SpringDocConfig {
10
    @Bean
11
    public OpenAPI customOpenAPI() {
12
        return new OpenAPI()
13
                .info(new Info()
14
                        .title("AI 小程序后端 API")
15
                        .version("1.0")
16
                        .description("垃圾分类识别——图像上传、AI推理、记录管理"));
17
    }
18
}

字段	含义
`title`	显示在文档页顶部的标题
`version`	API 版本号
`description`	对整套接口的简要说明

4.3 访问文档#

启动项目后，在浏览器打开：

1
http://localhost:8080/swagger-ui/index.html

你会看到一个可直接交互的 API 文档页面，列出了所有 Controller 的接口，还能在线填入参数、发送请求、查看响应，不需要再开 Postman 或 curl。

五、数据校验#

5.1 添加依赖#

在 pom.xml 的 <dependencies> 中添加 spring-boot-starter-validation

1
<dependency>
2
    <groupId>org.springframework.boot</groupId>
3
    <artifactId>spring-boot-starter-validation</artifactId>
4
</dependency>

5.2 在实体或DTO上加注解#

比如限制文件名不能为空：

1
import jakarta.validation.constraints.NotBlank;
2

3
public class ImageRecord {
4
    // ...
5
    @NotBlank(message = "文件名不能为空")
6
    private String originalFilename;
7
}

5.3 Controller 参数加 `@Valid`#

1
@PostMapping
2
public Result<ImageRecord> create(@Valid @RequestBody ImageRecord record) {
3
    // ...
4
}

此时如果请求不带 originalFilename，会抛出 MethodArgumentNotValidException，但会被我们的 GlobalExceptionHandler 捕获并返回 500 错误。

为了返回更友好的格式，可以在 GlobalExceptionHandler 中单独处理：

1
import org.springframework.web.bind.MethodArgumentNotValidException;
2

3
@ExceptionHandler(MethodArgumentNotValidException.class)
4
public Result handleValidation(MethodArgumentNotValidException e) {
5
    String msg = e.getBindingResult().getAllErrors().get(0).getDefaultMessage();
6
    return Result.error(400, msg);
7
}

六、重新打包部署#

以下演示一次完整的打包部署过程。

6.0 前置条件假设#

Spring Boot 项目根目录位于 G:\DEMO_Project\demo 。
远程 Linux 服务器中 JAVA 项目工作目录为 /opt/app/ 。
Spring Boot 项目中 pom.xml 中为 <version>1.0.0</version>。

6.1 Maven 打包#

打开 Intellij IDEA ，选择侧边栏中的 Maven ，选择 执行Maven项目 。

输入 mvn clean package 。

等待出现如下提示：

1
[INFO] -------------------------------------------
2
[INFO] BUILD SUCCESS
3
[INFO] -------------------------------------------
4
[INFO] Total time:  4.368 s
5
[INFO] Finished at: 2026-05-20T21:39:41+08:00
6
[INFO] -------------------------------------------

此时 Spring Boot 项目中出现新文件夹 target 。

在G:\DEMO_Project\demo\target 文件夹下出现两个文件 demo-1.0.0.jar 和 demo-1.0.0.jar.original 和若干文件夹。

注意，我们只需要 demo-1.0.0.jar ，不需要带 original 版本的文件。

6.2 传送文件#

我们使用 scp 传送我们打包好的 JAR 文件。

首先，让我们在 Windows 上切换我们的 Powershell 工作目录。

打开 Powershell ，输入以下命令：

1
PS C:\Users\TerryC> cd "G:\DEMO_Project\demo"
2
PS G:\DEMO_Project\demo> scp target/demo-1.0.0.jar terryc@1.2.3.4:/opt/app

terryc 此处替换为你在远程服务器的用户名，如 root 。
@1.2.3.4 此处替换为你的服务器外网IP地址，如 @111.111.111.111 。
:/opt/app 此处为你的应用工作目录，你的项目将会在这个目录启动，可替换为其他目录。

6.3 重建软链接，重启服务#

在服务器上关闭 demo 项目：

1
sudo systemctl stop demo

把我们传送到服务器上的 demo-1.0.0.jar 链接到 demo.service 的 demo-current.jar

1
ln -sf /opt/app/demo-1.0.0.jar /opt/app/demo-current.jar

启动并检查 demo 项目的状态：

1
sudo systemctl start demo
2
sudo systemctl status demo

出现 Active: active (running) ，则为成功启动。

1
terryc@i23fFG3edMoPa321Z:~$ sudo systemctl status demo
2
● demo.service - Demo Application
3
     Loaded: loaded (/etc/systemd/system/demo.service; enabled; preset: enabled)
4
     Active: active (running) since Wed 2026-05-20 22:02:11 CST; 1s ago
5
   Main PID: 46722 (java)
6
      Tasks: 14 (limit: 1860)
7
     Memory: 46.6M (peak: 46.9M)
8
        CPU: 1.962s
9
     CGroup: /system.slice/demo.service
10
             └─46722 /usr/bin/java -Xms512m -Xmx1g -jar /opt/app/demo-current.jar

七、验收清单#

所有接口返回统一的 Result 格式（已做）
出错时返回 JSON 而不会出现 500 页面（全局异常处理）
可以访问 doc.html 看到接口文档
提交非法参数时收到 code: 400 和具体错误信息

一、这篇文章将要做的#

1.1 回顾#

1.2 目标#

二、统一响应格式#

2.0 为什么需要统一格式#

2.1 创建 Result 类#

2.2 改造 Controller#

2.2.1 导入 Result 类#

2.2.2 新建记录——返回创建好的数据#

2.2.3 查询列表——返回数组#

2.2.4 查询单个——不存在时返回错误#

2.2.5 删除——返回成功但不带数据#

2.2.6 上传并识别——返回待识别结果的记录#

2.3 验证#

三、全局异常处理#

3.0 为什么我们需要这个#

四、Springdoc 接口文档#

4.0 为什么我们需要这个#

4.1 添加依赖#

4.2 配置类（可选）#

4.3 访问文档#

五、数据校验#

5.1 添加依赖#

5.2 在实体或DTO上加注解#

5.3 Controller 参数加 @Valid#

六、重新打包部署#

6.0 前置条件假设#

6.1 Maven 打包#

6.2 传送文件#

6.3 重建软链接，重启服务#

七、验收清单#

5.3 Controller 参数加 `@Valid`#