Stooland Docs

Appearance

API 项目代码优化方案 ​

基于 Stooland API 项目的最佳实践指南，对现有代码进行架构优化和重构。

📋 优化概述 ​

优先级问题类型数量状态
🔴 高控制器业务逻辑下沉2待处理
🟡 中Db::name() 改为模型操作1待处理
🟢 低其他优化-待处理

🔴 高优先级优化 ​

1. ApiVolcengine 控制器业务逻辑下沉 ​

问题文件: /api/app/aigc/controller/ApiVolcengine.php

问题描述:

  • imageGenerate() 方法（第 115-172 行）包含了复杂的 Seedream 图片生成逻辑
  • ark() 方法（第 214-314 行）包含了大量 LLM 代理逻辑
  • 违反了"瘦控制器"原则，业务逻辑应该在 Service 层

优化方案:

  1. 在 VolcengineService 中新增 imageGenerate() 方法
  2. 在 VolcengineService 中新增 ark() 方法
  3. 控制器仅保留参数获取、验证和响应

涉及代码:

php
// ApiVolcengine.php - imageGenerate() 方法 (L115-172)
// ApiVolcengine.php - ark() 方法 (L214-314)

2. ApiStoryboard 控制器业务逻辑下沉 ​

问题文件: /api/app/material/controller/ApiStoryboard.php

问题描述:

  • index() 方法（第 70-133 行）包含公式信息预取和数据转换逻辑
  • saveResult() 方法（第 221-273 行）包含视频结果保存逻辑
  • accountDirections()、formulas()、formulaDetail() 方法包含数据转换逻辑

优化方案:

  1. 在 StoryboardService 中新增 getListWithDetails() 方法处理列表数据组装
  2. 在 StoryboardService 中新增 saveVideoResult() 方法处理视频结果保存
  3. 在 StoryboardService 中新增 getAccountDirections() 方法
  4. 在 StoryboardService 中新增 getFormulas() 和 getFormulaDetail() 方法

涉及代码:

php
// ApiStoryboard.php - index() 方法 (L70-133)
// ApiStoryboard.php - saveResult() 方法 (L221-273)
// ApiStoryboard.php - accountDirections() 方法 (L280-326)
// ApiStoryboard.php - formulas() 方法 (L333-351)
// ApiStoryboard.php - formulaDetail() 方法 (L358-383)

🟡 中优先级优化 ​

3. Db::name() 改为模型操作 ​

问题文件: /api/app/aigc/service/VolcengineService.php

问题描述:

  • 第 349 行使用 Db::name('aigc_tasks')->insert() 直接操作数据库
  • 违反最佳实践，应该使用 Model 进行操作

优化方案:

  1. 创建 AigcTasks 模型（/api/app/aigc/model/AigcTasks.php）
  2. 修改 VolcengineService.php 中的代码使用模型操作

涉及代码:

php
// VolcengineService.php - L349
Db::name('aigc_tasks')->insert([...]);

📝 详细优化计划 ​

REF-003: 创建 AigcTasks 模型 ​

优先级: 🟡 中 预计工时: 15 分钟

步骤:

  1. 创建 /api/app/aigc/model/AigcTasks.php 模型文件
  2. 继承 BaseModel
  3. 定义表名和字段
  4. 更新 VolcengineService.php 第 349 行使用模型

REF-004: 下沉 ApiVolcengine 业务逻辑 ​

优先级: 🔴 高 预计工时: 1 小时

步骤:

  1. 在 VolcengineService 中新增 imageGenerate() 方法
    • 复制 ApiVolcengine::imageGenerate() 中的业务逻辑
    • 保留参数处理逻辑
  2. 在 VolcengineService 中新增 ark() 方法
    • 复制 ApiVolcengine::ark() 中的业务逻辑
  3. 修改 ApiVolcengine 控制器
    • 简化 imageGenerate() 方法，仅调用 Service
    • 简化 ark() 方法，仅调用 Service

REF-005: 下沉 ApiStoryboard 业务逻辑 ​

优先级: 🔴 高 预计工时: 1.5 小时

步骤:

  1. 在 StoryboardService 中新增 getListWithDetails() 方法
    • 处理预加载关联
    • 处理公式信息预取
    • 处理 ICE 信息附加
  2. 在 StoryboardService 中新增 saveVideoResult() 方法
    • 处理按 ID 或 job_id 查找分镜
    • 处理视频 keys 和 timeline 保存
  3. 在 StoryboardService 中新增 getAccountDirections() 方法
    • 处理用户 ID 和 device_id 获取
    • 处理数据格式转换
  4. 在 StoryboardService 中新增 getFormulas() 和 getFormulaDetail() 方法
  5. 修改 ApiStoryboard 控制器，调用对应的 Service 方法

📊 优化后的架构对比 ​

优化前 ​

Controller ──┬──> 业务逻辑 (❌ 错误)
             ├──> Validate
             └──> Service

优化后 ​

Controller ──┬──> 参数获取
             ├──> Validate
             └──> Service ──> 业务逻辑 (✅ 正确)
                          └──> Model

🔍 检查清单 ​

  • [ ] 所有控制器方法不超过 20 行
  • [ ] 控制器仅调用 Service 层方法
  • [ ] 所有数据库操作通过 Model 进行
  • [ ] 不使用 Db::name() 直接操作表
  • [ ] 使用 $this->getParams() 获取参数
  • [ ] 使用 $this->sendResponse() 返回响应
  • [ ] 业务异常使用 saas_abort() 抛出

📌 备注 ​

  1. 优化过程中保持现有 API 接口不变，确保前端兼容性
  2. 建议按优先级逐步实施，先完成高优先级任务
  3. 每次优化后进行充分测试
  4. 参考 docs/api/best_practices.md 中的规范