项目实训：后端的保守重构与质量优化

目录一、项目背景二、本轮优化目标三、优化思路四、具体优化内容1. Controller层重复逻辑整理2. Service层结构小幅优化3. DTO与配置类瘦身4. 视频链路外围清理5. 接口契约与异常处理检查6. 最小测试补充7. 配置安全性优化五、优化过程中遇到的问题与思考六、本轮成果一、项目背景在前几篇博客中我已经记录了本项目的后端从基础框架搭建到大模型接入再到视频检测链路升级的一些开发过程。到目前为止后端已经具备了文件上传、音视频检测服务调用、大模型文本分析、多模态综合分析、模拟诈骗对话、视频抽帧与人脸裁剪等核心能力。但是随着代码不断增加我逐渐发现一个问题功能虽然能跑但代码质量也需要及时维护。尤其是在课程项目开发过程中开发者可能更关注“功能有没有实现”而容易忽视“代码后面还能不能维护”。如果一直只往前堆功能后续联调、排错、答辩讲解都会变得比较吃力。因此本轮我专门对后端代码进行了一轮保守的优化。这里所谓“保守”指的是不改变接口行为、不改变业务流程、不引入大规模架构调整只在现有代码基础上做代码简化、重复逻辑整理、接口契约检查和测试补强。二、本轮优化目标本轮优化的目标可以概括为以下几点1. 降低代码重复度例如文件上传逻辑、请求校验逻辑、异常返回逻辑等如果多处重复出现就会增加后续维护成本。2. 清理冗余注释和样板代码前期开发时为了记录思路我在很多类中写了大量说明性注释。但随着代码结构稳定下来一些注释已经变成了“解释代码字面意思”的冗余需要适当清理。3. 保持核心链路可读性优化不等于无脑压缩代码。某些业务判断如果被压缩成三元表达式虽然行数变少了但阅读成本反而会变高。因此本轮也做了一次“是否优化过头”的回看。4. 补强接口契约与异常处理对Controller层接口做了一次检查确认哪些请求体需要空值校验哪些异常处理风格需要后续统一规划。5. 增加最小测试当前项目之前只有一个contextLoads测试证明Spring上下文能启动。本轮补充了一些不依赖外部Flask服务和大模型API的本地测试。三、优化思路1. 不推进功能只提高代码质量本轮优化中我刻意避免新增业务功能。例如没有新增数据库、没有新增知识库接口、没有新增全局异常处理器也没有改变视频检测链路的执行方式。这样做的原因是当前阶段后端核心链路还需要继续与音频组、视频组、前端组联调。如果在这个时候大幅调整接口契约或业务流程很容易造成联调方调用方式变化反而带来不必要的风险。2. 先保守优化再回看可读性优化开始时我先对重复逻辑进行了提取例如文件上传保存逻辑、检测服务选择逻辑等。但后来也发现一个问题有些“优化”虽然结构更统一但代码行数不一定减少有些表达式虽然更短但并不一定更清晰。因此后续我又做了一次回看把一些过度压缩的地方恢复成更直观的if判断。比如视频新旧链路的选择作为一个业务分支保留清晰的if写法比压成三元表达式更合适。3. 只处理明确收益的重构点对于一些看似重复的地方比如multipart请求构造、临时目录路径、检测结果对象组装我没有全部抽成工具类。原因是这些重复目前只出现两三处而且业务语义并不完全一样。如果为了消除少量重复而新增过多抽象反而会让项目更复杂。本轮真正做的小重构主要集中在低风险位置例如LLMService中大模型返回格式异常时的重复处理。四、具体优化内容1. Controller层重复逻辑整理首先优化的是文件上传入口FileUploadController。原本普通上传接口和上传后立即检测接口中都包含了文件校验、类型校验、临时目录创建、UUID文件名生成、文件保存等逻辑。优化后将这些逻辑拆成了几个私有方法(1)validateRequest统一校验文件和type参数(2)isSupportedType判断type是否为audio或video(3)saveToTemp统一保存上传文件到临时目录(4)extractExtension提取原始文件扩展名(5)buildUploadResponse组装文件上传响应(6)detectByType根据audio/video调用对应检测逻辑这样Controller中两个接口本身就更加清楚只负责“接收请求、调用方法、返回结果”。文件保存细节不再在两个接口中重复展开。部分核心代码如下private String validateRequest(MultipartFile file, String type) { if (file null || file.isEmpty()) { return 文件不能为空; } if (!isSupportedType(type)) { return type必须为audio或video; } return null; } private SavedFile saveToTemp(MultipartFile file) throws IOException { File tempDir new File(TEMP_DIR); if (!tempDir.exists() !tempDir.mkdirs()) { throw new IOException(无法创建临时目录: tempDir.getAbsolutePath()); } String originalName file.getOriginalFilename(); String extension extractExtension(originalName); String fileId UUID.randomUUID().toString(); File destFile new File(tempDir, fileId extension); file.transferTo(destFile); return new SavedFile(fileId, originalName, destFile); }2. Service层结构小幅优化DetectionService中保留了音频检测和视频检测两个入口。其中视频检测根据配置决定走旧链路还是新链路。这里我没有过度重构只是把判断逻辑收束到了shouldUseVideoPreprocess方法中使detectVideo的业务含义更明确。public VideoDetectionResult detectVideo(String filePath) { if (shouldUseVideoPreprocess()) { return videoImagePipelineService.detectFromVideoFile(filePath); } return callDetection(filePath, videoServiceUrl, VideoDetectionResult.class); } private boolean shouldUseVideoPreprocess() { return videoProperties.getPreprocess() ! null videoProperties.getPreprocess().isEnabled(); }对于LLMService我提取了大模型返回格式异常时的统一处理方法。原本extractContent中多处重复出现记录日志并返回固定错误提示。优化后统一为invalidLLMResponse。private String invalidLLMResponse(Object responseBody) { log.error(大模型返回格式异常: {}, responseBody); return LLM_ERROR_MESSAGE; }这样后续如果要统一修改大模型返回异常提示只需要改一个地方。3. DTO与配置类瘦身前期为了说明字段含义很多DTO中都有较多注释例如AudioDetectionResult、VideoDetectionResult、ChatRequest、Message、KnowledgeItem等。随着字段已经比较清晰这些注释继续保留反而显得臃肿。本轮对DTO做了瘦身只保留字段和必要注解。例如AudioDetectionResult现在更加简洁Data public class AudioDetectionResult { private String type audio; private Double fakeProbability; private Double confidence; private String fakeType; private String details; }同时对LLMConfig、VideoProperties、WebConfig、RestTemplateConfig等配置类也删除了冗余说明使其更接近配置本身。4. 视频链路外围清理视频检测链路是项目中比较关键的部分我没有大幅拆分只做了保守的清理。VideoFrameExtractorService中补充了ImageIO.write的返回值判断避免图片写入失败时仍然加入结果列表。if (!ImageIO.write(bi, png, png)) { throw new IOException(帧图片写入失败: png.getAbsolutePath()); } out.add(png);FaceCropService中保留了一条必要注释// 人脸检测是可选预处理步骤失败时由上层回退为整帧送检。 if (faceClassifier null) { return false; }这条注释在于说明设计意图。因为在人脸检测链路中检测不到人脸并不代表整个视频检测失败上层会回退为整帧送检这是一个很重要的容错设计。5. 接口契约与异常处理检查本轮还对Controller层接口做了一次契约检查并新增了接口契约与异常处理规划文档。当前接口主要包括(1)POST /api/upload(2)POST /api/upload/detect(3)POST /api/llm/analyze(4)POST /api/llm/analyze/multi(5)POST /api/llm/scam/chat文档中记录了每个接口的用途、请求参数、成功返回、失败返回以及后续异常处理统一规划。这样做的好处是后续与前端联调时不需要每次都去翻 Controller 代码确认接口格式。同时LLMController补充了空请求体和空消息校验。例如PostMapping(/scam/chat) public ResultString scamChat(RequestBody ChatRequest request) { if (request null || request.getMessage() null || request.getMessage().trim().isEmpty()) { return Result.error(消息不能为空); } return Result.success(llmService.scamSimulation( request.getMessage(), request.getHistory(), DEFAULT_SCENARIO )); }这样如果前端传入空body或空消息不会直接导致空指针而是返回统一的错误结构。6. 最小测试补充之前测试类中只有contextLoads这个测试只能说明Spring应用上下文可以启动不能说明业务类的局部逻辑是否正确。本轮补充了几个不依赖外部服务的测试(1)Result.success / Result.error 测试(2)KnowledgeService 搜索测试(3)VideoImageInferenceResponse 默认概率测试(4)PromptLoader 模板变量替换测试例如Result工厂方法测试Test void resultFactoriesBuildExpectedResponses() { ResultString success Result.success(ok); assertEquals(200, success.getCode()); assertEquals(success, success.getMessage()); assertEquals(ok, success.getData()); ResultString error Result.error(failed); assertEquals(500, error.getCode()); assertEquals(failed, error.getMessage()); assertNull(error.getData()); }测试全部通过目前结果为Tests run: 5, Failures: 0, Errors: 0, Skipped: 0。7. 配置安全性优化原本application.yml中的大模型API Key占位值是api-key: ${DEEPSEEK_API_KEY:我的api_key}虽然这不是真正的密钥但从规范性上看“我的api_key”这种占位写法不太合适。因此改成了api-key: ${DEEPSEEK_API_KEY:please_set_env}这样既不会泄露真实密钥也能提醒运行环境需要配置DEEPSEEK_API_KEY。五、优化过程中遇到的问题与思考1. 代码变短不一定等于更好一开始我倾向于把一些if判断压缩成三元表达式比如type校验、视频新旧链路选择等。但回看时发现有些业务判断展开写反而更清楚。因此本轮优化中我逐渐形成了一个原则简单字段可以简化核心业务分支不要为了少几行代码牺牲可读性。2. 抽方法不一定等于简化文件上传逻辑中抽方法是有价值的因为重复明显而且两个接口都用到。但像multipart请求构造、临时目录路径这类重复目前只出现两三处如果贸然抽成公共工具类反而会增加新的理解成本。所以本轮没有强行把所有看起来相似的代码都抽象出去。3. 联调阶段不适合大改接口契约检查异常处理时我发现一个问题LLMService调用大模型失败时目前会返回错误文本然后Controller仍然包装为Result.success。这从严格意义上看不够统一。但如果现在改成抛异常并返回Result.error就会改变接口响应结构可能影响前端或联调。因此本轮只把这个问题记录到“后续异常处理统一规划”中没有直接大改。4. 测试比继续压缩代码更有价值当低风险代码清理完成后继续压缩代码的收益已经很低。相比之下补充一些本地测试更有价值。它不仅可以防止后续误改还能让项目在答辩或验收时显得更可靠。六、本轮成果本轮优化完成后主要成果如下·FileUploadController上传相关重复逻辑已提取·DetectionService视频新旧链路判断更加清楚·DTO、配置类和工具类完成瘦身·视频链路外围清理完成保留核心线性流程·LLMController增加空请求体和空消息校验·LLMService提取大模型返回异常处理方法·新增接口契约与异常处理规划文档·application.yml中API Key占位值规范化·补充最小测试测试数量从1个增加到5个·Maven测试通过BUILD SUCCESS实际是代码太丑被喷了...