前言

今天继续做我的开源 AI 项目 KnowFlow Agent。

这个项目的目标是做一个面向企业智能客服和售后支持场景的 AI 平台，整体架构是：

Spring Boot + FastAPI + RAG + Agent

Day 1 主要完成了项目骨架、README、文档、GitHub 仓库。

Day 2 的重点是：搭建 Spring Boot 后端基础工程，让后端真正启动起来，并返回统一格式的 JSON。

一开始我以为 Day 2 的目标只是看到浏览器里返回一段 JSON，后来才理解，JSON 只是结果，真正重要的是：后端服务已经有了最小可运行基础。

---

Day 2 的主要目标

今天的目标可以总结成一句话：

让 backend-spring 从一个空目录，变成一个可以启动、可以访问、可以测试的 Spring Boot 后端工程。

具体做了这些事情：

1. 创建 Spring Boot 项目
2. 配置 Maven 依赖
3. 编写 Spring Boot 启动类
4. 编写第一个接口 /api/health
5. 设计统一返回格式 ApiResponse
6. 添加业务异常类 BusinessException
7. 添加全局异常处理 GlobalExceptionHandler
8. 添加基础配置文件 application.yml
9. 编写接口测试
10. 启动服务并在浏览器访问成功

最终访问：

http://localhost:8080/api/health

返回了：

{
  "code": 0,
  "message": "ok",
  "data": {
    "service": "backend-spring",
    "status": "UP",
    "time": "2026-06-28T11:02:50"
  }
}

这说明后端服务已经成功运行。

---

今天学到的第一个概念：backend-spring 是什么

backend-spring 不是启动命令，而是项目里的一个目录。

它代表：

KnowFlow Agent 的 Spring Boot 业务后端

以后它会负责：

• 用户管理
• 权限管理
• 知识库管理
• 文档管理
• 工单管理
• 问答记录
• MySQL 数据存储
• Redis 缓存
• 给前端提供接口
• 调用 AI 服务获取智能结果

也就是说，backend-spring 是整个项目里的业务核心。

真正启动它的命令是：

cd D:\Code\knowflow-agent\backend-spring
mvn spring-boot:run

---

今天学到的第二个概念：什么是 API 接口

API 接口可以理解成：

前端或者其他服务和后端沟通的入口

比如今天访问的：

GET /api/health

就是一个后端接口。

它的作用是告诉调用方：

后端服务现在是否正常运行

以后项目里还会有很多接口，例如：

GET /api/tickets
POST /api/tickets
GET /api/knowledge-bases
POST /api/qa/ask

这些接口分别会负责查询工单、创建工单、查询知识库、发起智能问答等功能。

---

今天学到的第三个概念：什么是 GET 请求

GET 是 HTTP 请求方式的一种。

我今天先记住了一个简单规则：

GET = 查询数据
POST = 提交或新增数据
PUT = 修改数据
DELETE = 删除数据

所以：

GET /api/health

表示查询后端健康状态。

它不会修改数据，只是获取服务当前状态。

---

今天学到的第四个概念：为什么接口要统一返回格式

今天项目里设计了统一返回格式：

{
  "code": 0,
  "message": "ok",
  "data": {}
}

这样做的原因是：前端需要稳定地处理后端返回。

如果每个接口格式都不一样，前端就会很难写。

比如一个接口返回：

{
  "success": true,
  "result": {}
}

另一个接口返回：

{
  "code": 200,
  "data": {}
}

再另一个接口返回：

{
  "status": "ok"
}

这样项目一大就会很乱。

统一格式以后，前端只需要判断：

code 是否等于 0

如果 code = 0，说明成功，读取 data。

如果 code != 0，说明失败，显示 message。

---

code、message、data 分别代表什么

今天重点理解了这三个字段：

{
  "code": 0,
  "message": "ok",
  "data": {}
}

code

code 是业务状态码。

0 表示成功
其他数字表示失败或特殊情况

比如：

{
  "code": 400,
  "message": "参数错误",
  "data": null
}

message

message 是提示信息。

成功时可以是：

ok

失败时可以是：

知识库不存在
无权限访问
参数错误
服务器内部错误

data

data 是真正返回的数据。

比如健康检查接口里：

{
  "service": "backend-spring",
  "status": "UP",
  "time": "2026-06-28T11:02:50"
}

这部分就是接口真正想返回的信息。

---

今天读懂的几个核心文件

1. pom.xml

pom.xml 是 Maven 项目的配置文件。

它告诉项目：

• 用哪个 Spring Boot 版本
• 用哪个 Java 版本
• 需要哪些依赖
• 怎么构建项目

今天项目用的是：

Spring Boot 2.7.18
Java 11

主要依赖有：

spring-boot-starter-web
spring-boot-starter-validation
spring-boot-starter-test

其中：

• web：让项目可以写接口
• validation：以后做参数校验
• test：用来写测试

---

2. KnowFlowBackendApplication

这是 Spring Boot 的启动类。

可以理解为：

整个后端项目的开机按钮

代码核心是：

SpringApplication.run(KnowFlowBackendApplication.class, args);

运行它以后，Spring Boot 会启动整个后端服务。

---

3. HealthController

这是今天写的第一个接口类。

它负责处理：

GET /api/health

当浏览器访问：

http://localhost:8080/api/health

Spring Boot 就会找到这个 Controller，然后执行里面的 health() 方法，最后返回 JSON。

---

4. ApiResponse

ApiResponse 是统一响应格式类。

它规定以后所有接口都尽量返回：

{
  "code": 0,
  "message": "ok",
  "data": {}
}

这样整个项目会更规范，也方便前端处理。

---

5. GlobalExceptionHandler

GlobalExceptionHandler 是全局异常处理类。

它的作用是：

当后端接口出错时，不直接把 Java 报错返回给前端，而是统一包装成 JSON 返回。

比如以后出现业务错误，可以返回：

{
  "code": 400,
  "message": "知识库不存在",
  "data": null
}

这样前端和用户看到的信息会更清楚。

---

今天对 Spring Boot 后端的理解

今天以前，我可能只知道 Spring Boot 是后端框架。

今天之后，我对它有了一个更清楚的理解：

Spring Boot 可以启动一个后端服务。
后端服务运行后，可以对外提供 API 接口。
前端、浏览器或其他服务可以调用这些接口。
接口返回 JSON 数据。

今天的完整流程是：

浏览器访问 /api/health
        ↓
Spring Boot 接收到请求
        ↓
找到 HealthController
        ↓
执行 health() 方法
        ↓
生成 service/status/time 数据
        ↓
用 ApiResponse 包装
        ↓
返回统一 JSON

这就是一个最小后端接口的完整过程。

---

今天也意识到：写出来不等于学会

今天有一个很真实的感受：AI 很快就把代码生成出来了，我会觉得“好像我什么都没干”。

但后来我意识到，真正重要的不是代码是谁敲出来的，而是我能不能理解它。

今天真正需要学会的是：

• 这个文件为什么存在
• 这段代码解决什么问题
• 浏览器为什么能看到返回值
• 接口为什么要统一格式
• 如果以后增加接口，该放在哪里
• 如果接口报错，应该怎么返回

所以今天不只是“生成了代码”，而是开始学习一个后端项目的基本结构。

---

Day 2 的收获

今天的收获主要有这些：

1. 知道了 backend-spring 是 Spring Boot 业务后端
2. 知道了什么是 API 接口
3. 知道了什么是 GET 请求
4. 知道了为什么后端要返回 JSON
5. 知道了为什么接口需要统一返回格式
6. 理解了 code、message、data 的含义
7. 知道了 Spring Boot 启动类的作用
8. 知道了 Controller 是处理接口请求的地方
9. 知道了全局异常处理的意义
10. 成功让后端服务启动并返回结果

---

Day 2 的项目成果

今天完成后，KnowFlow Agent 的后端已经具备了最小可运行能力。

可以这样总结：

Day 1：项目从无到有，完成开源仓库和文档
Day 2：后端从无到有，完成 Spring Boot 基础骨架

现在项目已经不是只有目录和文档了，而是有了一个真正能启动的后端服务。

---

下一步计划

接下来可以继续做后端基础能力。

下一步可能会做：

• 后端基础包结构
• 用户模块
• 知识库模块
• 文档模块
• 工单模块
• 数据库表设计
• MySQL 配置
• Redis 配置

不过在继续写功能之前，我需要先把今天这些基础概念搞懂。

尤其是：

API 是什么
GET 请求是什么
统一返回格式是什么
Controller 是什么
Spring Boot 怎么启动

这些是后面所有功能的基础。

---

总结

今天完成了 KnowFlow Agent 的 Day 2：Spring Boot 后端基础工程。

今天看到的 JSON 返回，不只是一个简单页面，而是证明：

后端服务已经启动成功
接口已经可以访问
统一返回格式已经生效
项目开始具备真实后端工程结构

后面所有复杂功能，比如知识库、工单、RAG、Agent，都会建立在今天这个后端基础之上。

Day 2 的核心一句话是：

让 backend-spring 活起来。