这一讲我们来处理一个在前后端项目里最不起眼、但几乎所有模块都会依赖的基础能力：JSON 工具类。项目背景是 SpringBoot + Vue + Uniapp + LangChain4j + SpringAI 组合的智能视频推荐小程序，前几讲已经把工程骨架、用户登录、推荐流程搭起来了，这一讲专门把 JSON 的序列化、反序列化、字段提取、异常兜底这些公共逻辑整理成统一工具，后端不再到处 try/catch 解析数据，前端也不用每次手写 JSON.parse 容错。
先给结论：JSON 工具类的核心价值不是写几个静态方法，而是定一套项目内的统一规范。后端用 Jackson 作为默认序列化框架，封装静态工具类处理对象与 JSON 互转、树节点读取、类型转换，并定义统一返回结构 Result；前端在 Vue 和 Uniapp 侧封装安全解析、请求拦截、缓存读写；同时针对 LangChain4j 和 SpringAI 这类大模型返回结果，专门处理模型输出中的 JSON 字符串解析与容错。本文会给出可直接复制的 Java 和 Javascript 代码、单元测试示例、接口联调注意事项，以及一份常见问题排查清单。适合正在做小程序后端、或者要把 AI 推荐结果稳定接入业务的读者直接收藏。
1. 本讲定位与核心能力速览
| 能力项 | 说明 |
|---|---|
| 项目组成 | SpringBoot 后端 + Vue 管理端 + Uniapp 小程序端 + LangChain4j/SpringAI 接入 |
| 本讲主题 | 统一 JSON 工具类设计、前后端共用规范、AI 返回结果解析 |
| 后端序列化框架 | Jackson（SpringBoot 默认集成，按项目实际引入版本为准） |
| 后端工具类 | JsonUtils：对象转 JSON、JSON 转对象、JsonNode 节点读取、类型转换 |
| 统一返回结构 | Result 泛型类，规范 code / message / data |
| 前端工具 | safeParse、safeStringify、请求响应拦截、缓存读写 |
| AI 场景 | LangChain4j / SpringAI 返回 JSON 字符串后的结构化解析 |
| 测试方式 | JUnit 单元测试 + 前后端联调验证 |
| 适用读者 | 小程序全栈开发、Java 后端开发、对接大模型 API 的开发者 |
这一讲不会引入新框架，也不动推荐算法本身，而是把散落在各业务代码里的 JSON 处理逻辑收敛起来。后面几讲涉及视频列表、用户行为上报、推荐结果渲染时，都会复用这一讲的 JsonUtils 和 Result，所以这篇内容值得先跑通再往下走。
2. 智能视频推荐系统中的 JSON 流转链路
先看清楚 JSON 在整套系统里经过哪些环节。智能视频推荐小程序最基础的交互链路是：用户在 Uniapp 端浏览视频、点击播放、提交搜索关键词，这些请求由 SpringBoot 后端接收；后端根据需要调用 SpringAI 或 LangChain4j 封装的模型接口，让大模型根据用户行为返回推荐候选；后端再把候选视频列表、推荐理由、关联标签组装成统一结构返回给前端；前端解析 JSON 后渲染推荐卡片。整个链路中，任何一次数据交换都依赖 JSON。
具体到业务模块，JSON 至少出现在四个位置：一是 HTTP 请求和响应的 body，前端提交的行为数据、后端返回的推荐列表都是 JSON；二是本地缓存，Uniapp 端把用户信息和历史记录写入 storage 时需要序列化，读取时需要反序列化；三是 AI 模型接口的输入输出，让模型返回结构化 JSON 比返回纯文本更稳定；四是服务端日志，排查推荐结果异常时需要把关键对象序列化后输出。如果每个模块各自实现一套解析逻辑，字段命名风格、异常处理方式、时间日期格式都会不一致，联调时最容易出现"后端给的是 camelCase，前端读的是 snake_case"这类问题。
因此，在设计 JSON 工具类之前，要先定三个约定：字段命名统一采用驼峰 camelCase；时间格式统一为字符串 "yyyy-MM-dd HH:mm:ss"；所有接口响应统一包裹 Result 结构。项目使用 SpringBoot 时，Jackson 是默认的 JSON 处理框架，所以工具类直接基于 Jackson 封装，不额外引入依赖。需要说明的是，这里给出的代码是通用工程实践，具体依赖版本和包名会跟随实际项目环境，接入时按自身目录调整。
3. SpringBoot 后端 JSON 工具类实现
3.1 全局序列化配置
先解决全局配置，避免每个字段单独加注解。SpringBoot 项目中可以通过 application.yml 配置 Jackson 的序列化行为，包括空值处理、时间格式、允许属性命名策略等。下面是一个通用配置模板：
spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT+8 default-property-inclusion: non_null deserialization: fail-on-unknown-properties: false说明一下这几项的作用：date-format 统一时间格式，time-zone 解决服务器时区问题；default-property-inclusion: non_null 表示序列化时忽略 null 字段，响应体不会出现一堆空值；fail-on-unknown-properties: false 表示反序列化时遇到未知字段不报错。实际项目中，是否忽略 null 需要和后端协商，如果前端需要固定字段结构，建议保留 null 字段而不是直接隐藏，否则前端判空逻辑会受影响。这里给的是较常见的小程序接口风格：响应尽量精简。
3.2 JsonUtils 工具类核心方法
在项目中新建 JsonUtils 工具类，集中管理 ObjectMapper 实例。ObjectMapper 是线程安全的，可以定义为静态常量复用，不需要每次序列化都 new 一个。工具类至少应该包含：对象转 JSON 字符串、JSON 字符串转对象、读取 JSON 树节点、节点转对象、格式化 JSON、容错转换等能力。
public class JsonUtils { private static final ObjectMapper MAPPER = new ObjectMapper(); static { MAPPER.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false); MAPPER.configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false); MAPPER.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss")); MAPPER.setTimeZone(TimeZone.getTimeZone("GMT+8")); } private JsonUtils() {} public static String toJson(Object obj) { if (obj == null) { return null; } try { return MAPPER.writeValueAsString(obj); } catch (JsonProcessingException e) { throw new RuntimeException("对象序列化失败: " + obj.getClass(), e); } } public static <T> T parse(String json, Class<T> clazz) { if (json == null || json.isEmpty()) { return null; } try { return MAPPER.readValue(json, clazz); } catch (JsonProcessingException e) { throw new RuntimeException("JSON解析失败: " + e.getMessage(), e); } } public static JsonNode readTree(String json) { if (json == null || json.isEmpty()) { return null; } try { return MAPPER.readTree(json); } catch (JsonProcessingException e) { throw new RuntimeException("JSON树解析失败: " + e.getMessage(), e); } } public static <T> T nodeToObject(JsonNode node, Class<T> clazz) { if (node == null || node.isNull()) { return null; } try { return MAPPER.treeToValue(node, clazz); } catch (JsonProcessingException e) { throw new RuntimeException("JSON节点转换失败: " + e.getMessage(), e); } } public static <T> List<T> parseList(String json, Class<T> clazz) { if (json == null || json.isEmpty()) { return new ArrayList<>(); } try { JavaType type = MAPPER.getTypeFactory() .constructCollectionType(List.class, clazz); return MAPPER.readValue(json, type); } catch (JsonProcessingException e) { throw new RuntimeException("JSON列表解析失败: " + e.getMessage(), e); } } }这个工具类把最常见的四个场景覆盖了：对象转 JSON、字符串转对象、读树节点、解析 List。需要特别注意 parseList，直接使用MAPPER.readValue(json, List.class)只能得到 List，内部元素会变成 LinkedHashMap，所以必须通过 JavaType 构造泛型类型。
3.3 统一返回结构 Result
接口返回结构如果不统一，前端每个页面都要单独处理错误码，排查问题也很痛苦。定义 Result 泛型类，所有 Controller 方法统一返回这个结构。
public class Result<T> { private Integer code; private String message; private T data; public static <T> Result<T> success(T data) { Result<T> result = new Result<>(); result.code = 200; result.message = "success"; result.data = data; return result; } public static <T> Result<T> error(Integer code, String message) { Result<T> result = new Result<>(); result.code = code; result.message = message; return result; } // getter / setter 略 }Controller 中的写法变成：
@PostMapping("/recommend") public Result<RecommendVO> recommend(@RequestBody RecommendRequest request) { RecommendVO vo = recommendService.recommend(request); return Result.success(vo); }这里有几个容易忽略的细节：Result 类不建议直接继承 Map 或者把 data 做成 Object 后强转，泛型能保留类型信息，前端可以根据 data 的实际结构生成类型定义；error 方法要分业务错误和系统错误，业务错误码由各模块定义，系统错误码统一用 500；响应中的 message 不要直接透传异常栈，前后端约定一种通用提示文案即可。
4. LangChain4j 与 SpringAI 场景下的 JSON 解析
4.1 AI 返回结果的 JSON 设计
接入大模型时，一个常见痛点是模型返回格式不稳定，可能多解释一句，也可能把 JSON 包在 markdown 代码块里。因此，在调用 LangChain4j 或 SpringAI 之前，就要在提示词中明确要求输出纯 JSON，并约定字段结构。以视频推荐为例，期望模型返回如下结构：
{ "videos": [ { "videoId": "v1001", "title": "SpringBoot 入门实战", "reason": "用户近期多次搜索 java 相关视频", "score": 0.95 } ], "summary": "根据用户行为，推荐以后端开发为主的学习视频" }后端拿到该 JSON 后，用 JsonUtils.readTree 读取根节点，再通过 nodes("videos") 获取数组，逐条转换为 VideoItem 对象；summary 字段用于前端展示推荐理由。这里的关键是：不要把响应直接映射成某个强类型对象，因为模型可能多返回字段、少了字段、或者嵌套结构变化，借助 JsonNode 先读取再转换，容错空间更大。
一种可行的做法是先定义推荐结果的 Java 记录类型：
public record RecommendResult(List<VideoItem> videos, String summary) {} public record VideoItem(String videoId, String title, String reason, Double score) {}然后写一个统一的解析方法：
public static RecommendResult parseRecommend(String modelOutput) { ModelOutput cleaned = cleanModelOutput(modelOutput); if (cleaned.isJson()) { JsonNode root = readTree(cleaned.getContent()); List<VideoItem> videos = new ArrayList<>(); JsonNode videoArray = root.path("videos"); if (videoArray.isArray()) { for (JsonNode node : videoArray) { videos.add(nodeToObject(node, VideoItem.class)); } } String summary = root.path("summary").asText(""); return new RecommendResult(videos, summary); } return new RecommendResult(new ArrayList<>(), cleaned.getContent()); }4.2 模型输出清洗与容错
模型输出清洗是 AI 接口对接中必要的环节。常见的脏数据有两种：模型把 JSON 放置在json代码块中；模型在 JSON 前后附加说明文字。清洗策略可以这样做：先判断字符串是否以{或[开头，如果不是，则查找第一个{和最后一个}，截取中间内容；如果字符串包含```json标记，直接按代码块边界提取。更稳妥的方式是提示词层面约束输出格式，同时在业务侧保留解析兜底，即使解析失败也返回空列表，不让异常直接打到前端。
SpringAI 和 LangChain4j 的调用方式虽然不同，但返回结果本质上都是字符串或结构化输出对象。如果项目配置了模型输出解析器，可以把 JSON 映射到指定的 POJO；如果没有，就统一走 JsonUtils.parse。这里建议对所有 AI 输出都做一层日志记录，记录原始输出、清洗后内容和解析结果，方便排查推荐质量问题时还原现场。
5. Vue 与 Uniapp 前端 JSON 工具封装
5.1 安全解析与序列化
Uniapp 端处理 JSON 最常见的坑是接口返回的数据已经是对象，前端又做了一次 JSON.parse，结果直接抛异常；以及本地缓存写入对象前忘记序列化，读取时得到 "[object Object]" 这样的字符串。因此前端也需要一个轻量工具模块，专门处理安全转换。
// utils/json.js export function safeParse(data, fallback = null) { if (data === null || data === undefined) return fallback; if (typeof data === 'object') return data; if (typeof data !== 'string') return fallback; try { return JSON.parse(data); } catch (e) { console.warn('[JsonUtils] parse error:', data, e); return fallback; } } export function safeStringify(data, fallback = '') { if (typeof data === 'string') return data; try { return JSON.stringify(data); } catch (e) { console.warn('[JsonUtils] stringify error:', data, e); return fallback; } } export function getField(data, path, fallback = null) { const obj = safeParse(data); if (!obj) return fallback; const keys = path.split('.'); let current = obj; for (const key of keys) { if (current === null || current === undefined) return fallback; current = current[key]; } return current === undefined ? fallback : current; }safeParse 解决重复解析问题，getField 解决深层字段读取问题。小程序渲染推荐列表时，经常要取data.list[0].title这类嵌套字段，用 getField 可以避免每一步都做空值判断。json.js 这个工具文件应该放在项目的 utils 目录，配合 request 封装一起使用。
5.2 请求拦截与缓存读写
Uniapp 的 uni.request 返回的数据结构包含 statusCode 和 data 两层，业务代码里频繁解构容易出错。可以在请求封装层统一处理：当 statusCode 为 200 时，进一步解析 Result 结构中的 code；如果不是 200 或业务 code 不为 200，统一弹 toast 并抛出异常。推荐列表接口的响应是Result<List<VideoItem>>，前端只需要读取res.data.data，这个取值过程很容易把两层 data 搞混，封装后业务侧就不需要关心了。
缓存读写同样依赖安全解析。把用户信息写入 storage 之前调用 safeStringify，读取时调用 safeParse，同时加上过期时间判断。视频推荐小程序中，用户的历史浏览记录、搜索关键词、推荐结果快照都可以缓存，缓存 JSON 的 key 建议加版本号，比如recommend_v1_cache，这样后端数据结构升级时前端可以一键失效旧缓存。
6. 接口联调与批量任务中的 JSON 规范
6.1 请求与响应字段规范
前后端联调时，JSON 规范比工具类本身更重要。下面是一份建议 checklist：
- 字段命名统一使用 camelCase，不混用 snake_case。
- 时间字段统一为字符串，前端不做时区换算。
- 分页接口返回
{ list, total, page, size }固定结构。 - 业务失败时，code 使用自定义错误码，不要复用 HTTP 状态码做业务判断。
- 大字段列表（如视频标签数组）允许为 null，但要保证 data 外层不被 null。
举个例子，如果后端返回：
{ "code": 200, "message": "success", "data": { "list": [ {"videoId": "v1", "title": "JSON 工具类实战"} ], "total": 1, "page": 1, "size": 10 } }前端读取时直接safeParse(res.data)?.list即可，不需要判断 data 是否为 null。
6.2 批量任务中的 JSON 处理
视频推荐中批量任务通常指两种场景：一是运营后台批量导入/更新视频元数据，二是离线批量调用大模型生成推荐候选。针对第一种，后端需要接收一个 JSON 数组，逐条校验并落库；针对第二种，建议把批量输入写成 JSON Lines 格式，每一行是一个独立的推荐文章：
{"userId": "u1001", "keyword": "springboot", "topN": 5} {"userId": "u1002", "keyword": "python", "topN": 8}逐行读取的好处是：某一行 JSON 解析失败不影响整批任务，可定位到具体行号。后端处理批量文件时，避免一次性把大文件读入内存然后整体解析，建议使用流式逐行处理，每处理完一批记录进度，方便断点续跑。
7. 单元测试与效果验证
后端工具类写完必须补单元测试，这是保证后续业务开发不返工的关键。下面是一个针对 JsonUtils 的 JUnit 测试骨架：
public class JsonUtilsTest { @Test public void testObjectToJsonAndBack() { VideoItem item = new VideoItem("v1", "JSON测试", "测试理由", 0.9); String json = JsonUtils.toJson(item); assertNotNull(json); VideoItem parsed = JsonUtils.parse(json, VideoItem.class); assertEquals("v1", parsed.videoId()); } @Test public void testParseList() { String json = "[{\"videoId\":\"v1\"},{\"videoId\":\"v2\"}]"; List<VideoItem> list = JsonUtils.parseList(json, VideoItem.class); assertEquals(2, list.size()); assertEquals("v1", list.get(0).videoId()); } @Test public void testReadTreePath() { String json = "{\"data\":{\"list\":[{\"videoId\":\"v1\"}]}}"; JsonNode node = JsonUtils.readTree(json); assertEquals("v1", node.path("data").path("list").get(0).path("videoId").asText()); } @Test public void testParseInvalidJson() { assertThrows(RuntimeException.class, () -> JsonUtils.parse("not-json", VideoItem.class)); } }测试时要重点关注：时间格式化是否正确、null 字段是否按预期输出、未知字段反序列化是否会抛异常、List 泛型解析是否得到真实对象而不仅仅是 LinkedHashMap。这些是最容易出问题的地方。
前端验证相对简单，在 Uniapp 的开发者工具控制台执行：
const json = '{"code":200,"data":{"list":[]}}'; const obj = safeParse(json); console.log(obj.data.list); // 期望输出 []再把请求封装接上真实后端接口，查看返回的推荐列表是否正常渲染。如果 AI 接口还没完全调试好，可以先 mock 一个固定 JSON 响应，前端链路先行验证。
8. 常见问题与排查方法
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| 前端读取 data 为 undefined | 响应 data 为 null 或嵌套层级不对 | 控制台打印整个响应对象 | 统一走 safeParse 和 getField |
| 后端解析 JSON 抛异常 | 字符串前后有 BOM 或不可见字符 | 打印 json 的字节码 | 解析前 trim 并检查编码 |
| JSON.parse 二次解析报错 | 数据已是对象 | typeof 判断后返回原对象 | 使用 safeParse |
| 时间显示为时间戳 | Jackson 未配置 date-format | 检查 yml 中的 jackson 配置 | 设置日期格式并重启服务 |
| List 元素是 LinkedHashMap | 反序列化未指定泛型类型 | 检查是否用了 JavaType | 改用 parseList 方法 |
| AI 返回 JSON 被反引号包裹 | 模型按 markdown 输出 | 打印原始模型输出 | 增加模型输出清洗逻辑 |
| 缓存读取为 [object Object] | 写入时未序列化 | 检查缓存写入处 | 写入前调用 safeStringify |
这里面最有排查价值的是 AI 返回格式不稳定问题。LangChain4j 和 SpringAI 的客户端通常提供输出解析器，但不同模型的指令遵循能力有差异，不能完全依赖提示词，后端解析必须兼顾容错。推荐做法是：模型输出先按代码块提取，再尝试从首个{截取，最后才交给 JsonNode 解析；解析异常时记录原始输出到日志，并返回空推荐列表，避免推荐接口直接 500。
9. 最佳实践与使用建议
第一，ObjectMapper 全局单例。项目中多个模块共用一个实例，不要在每个方法里 new，避免创建开销和配置不一致。第二，null 字段策略前后端要协商一致。响应里保留 null 字段会让前端判空更简单，但传输体积略大；忽略 null 字段会让响应精简，但前端需要处理字段缺失。小程序场景流量敏感，建议忽略 null，前端统一用 getField 兜底。第三，所有 AI 输出必须做格式清洗和日志留存，方便后面做推荐效果复盘。第四，本地缓存要设计版本号和过期时间，避免后端字段升级后前端仍读取旧缓存。第五，涉及用户行为数据和偏好数据时，JSON 日志中不要打印完整用户信息，推荐服务在记录日志前对 userId 等字段做脱敏处理；调用大模型接口时，也应在请求参数中只传递完成推荐任务所需的最小字段集合，避免不必要地把用户隐私数据发送给外部模型服务。第六，若推荐内容来自模型生成或外部素材，发布前需要做内容审核，确认版权和授权边界。
10. 总结与下一步
这一讲从后端 JsonUtils、统一 Result、AI 输出清洗，到前端 safeParse 和缓存读写，把智能视频推荐小程序里的 JSON 处理链路整理完了。最值得先跑通的是 JsonUtils 的单元测试，它能同时验证序列化配置、泛型解析和时间格式；最容易踩的坑是 AI 返回内容被 markdown 包裹以及前端对 data 的二次 JSON.parse。建议按文中的排查表提前做好防护。
下一讲会进入推荐模块的核心业务逻辑，把本讲的 JSON 工具真正用起来：接收用户行为数据、组装推荐请求、解析模型结果并返回视频列表。建议先把本讲的 JsonUtils、Result 和前端 utils/json.js 在自己的项目里落地，下一讲的代码会直接复用它。
