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

Lagrange1736str

422人浏览 · 2026-04-26 16:20:35

Lagrange1736str · 2026-04-26 16:20:35 发布

一、项目背景

在前几篇博客中，我已经记录了本项目的后端从基础框架搭建，到大模型接入，再到视频检测链路升级的一些开发过程。到目前为止，后端已经具备了文件上传、音视频检测服务调用、大模型文本分析、多模态综合分析、模拟诈骗对话、视频抽帧与人脸裁剪等核心能力。

但是，随着代码不断增加，我逐渐发现一个问题：功能虽然能跑，但代码质量也需要及时维护。尤其是在课程项目开发过程中，开发者可能更关注“功能有没有实现”，而容易忽视“代码后面还能不能维护”。如果一直只往前堆功能，后续联调、排错、答辩讲解都会变得比较吃力。

因此，本轮我专门对后端代码进行了一轮保守的优化。这里所谓“保守”，指的是：不改变接口行为、不改变业务流程、不引入大规模架构调整，只在现有代码基础上做代码简化、重复逻辑整理、接口契约检查和测试补强。

二、本轮优化目标

本轮优化的目标可以概括为以下几点：

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 Result<String> 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() {
    Result<String> success = Result.success("ok");
    assertEquals(200, success.getCode());
    assertEquals("success", success.getMessage());
    assertEquals("ok", success.getData());

    Result<String> 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