47 KiB
C1 · 后端代码精简空间(重复代码 / 死代码 / 过度设计)
审计范围(实际逐行 Read 过的文件):
main.pybackend/route_registry.py、backend/routes/common.py、backend/routes/params.py、backend/routes/wardrobe_routes.py、backend/routes/branch_routes.py、backend/routes/job_routes.py、backend/routes/node_routes.py、backend/routes/material_routes.py、backend/routes/profile_routes.py、backend/routes/workflow_routes.py、backend/routes/web_routes.py、backend/routes/image_routes.py、backend/routes/profile_card_routes.py、backend/routes/round_routes.py、backend/routes/advanced_material_routes.pybackend/dto/common.py、backend/dto/material_dto.py、backend/dto/workflow_round_dto.py、backend/dto/chat_command_dto.py(+ 全 dto 目录 AST 扫描)backend/services/event_stream_service.py、backend/services/web_hosting_service.py、backend/services/advanced_material_worker_runtime.py、backend/services/workflow_round_worker_runtime.py、backend/services/settings_service.py(尾部)、backend/services/workflow_service.py(事件发布部分)、backend/services/advanced_style_set_service.py(尾部工具函数)、backend/services/material_service.py(工厂)、backend/services/queue_service.py(尾部)core/db_helper→database/db_helper.py、core/config_service.py、core/identity.py、core/security.py、core/audit_service.py、core/event_bus.py、core/queue_manager.py、core/interop.py、core/webhook.py、core/interactions.py、core/fsm.pydatabase/repositories/profile_repository.py、workflow_repository.py、wardrobe_repository.py、advanced_material_repository.py、workflow_cross_review_repository.py、job_repository.py(+ 全 repositories 目录 grep 交叉验证)engines/image_provider.py、engines/vision_provider.pyadapters/webui_adapter.py、adapters/wechat_adapter.py、adapters/onebot11_adapter.py
摘要
后端真实源码约 54,551 行(main.py + backend/ + core/ + database/ + engines/ + adapters/)。系统性扫描后确认存在三类可量化冗余:(1) 复制粘贴型工具函数——_optional_text 被独立定义 30 次、_string_list 18 次、_json_or_none 12 次,且部分同名函数语义已经悄悄分叉(_string_list 至少有 6 种不同行为),这已经不只是冗余而是语义地雷;(2) 仓储层连接样板——conn = self.database.connect() / try / finally: conn.close() 在 13 个 repository + core/audit_service.py 中出现 131 次,完全可由一个 contextmanager 收敛;(3) 确证死代码——core/queue_manager.py 整文件(112 行)无任何模块引用,EventBus.subscribe/unsubscribe 从未被调用导致 publish 的 handler 分发链路整体空转,另有 29 个函数/类/方法全仓引用数为 0。
更值得注意的是,复制粘贴已经造成两处真实行为差异:backend/routes/branch_routes.py 的 _create_workflow_service() 漏掉了 event_bus=,导致分支创建/切换事件永远不进 SSE;engines/vision_provider.py 的 endpoint_url() 缺少 image 版本里的 /v1 去重逻辑,会拼出 /v1/v1/chat/completions。
保守估算(不含高风险的路由装饰器改造)可削减 约 1,800 行,约占后端 3.3%;含路由层改造约 2,100 行。以下按投入产出比排序。
发现
[P1-严重] 仓储层连接样板重复 131 次,可用一个上下文管理器收敛(削减 ≈390 行)
- 位置:
database/repositories/wardrobe_repository.py:84、database/repositories/workflow_repository.py:100、database/repositories/advanced_material_repository.py:346、core/audit_service.py:83等共 131 处(grep -c 'conn.close()' database/repositories/*.py core/audit_service.py= 132,finally:= 131) - 问题:每个仓储方法都手写
conn = self.database.connect()/try:/finally: conn.close(),写方法再额外手写except Exception: _rollback(conn); raise。_rollback本身还被独立定义了 3 次(advanced_material_repository.py:2119、workflow_cross_review_repository.py:1464、workflow_round_repository.py:1378)。 - 代码(
database/repositories/advanced_material_repository.py:346-366,三个方法的样板一模一样):def get_import(self, import_id: str) -> AdvancedMaterialImport | None: conn = self.database.connect() try: row = conn.execute( f"SELECT {IMPORT_COLUMNS} FROM advanced_material_imports WHERE import_id = {self.placeholder}", (import_id,), ).fetchone() finally: conn.close() return _row_to_import(row) if row else None def get_import_by_idempotency_key(self, idempotency_key: str) -> AdvancedMaterialImport | None: conn = self.database.connect() try: row = conn.execute( f"SELECT {IMPORT_COLUMNS} FROM advanced_material_imports WHERE idempotency_key = {self.placeholder}", (idempotency_key,), ).fetchone() finally: conn.close() return _row_to_import(row) if row else None - 影响:131 处样板 ≈ 520 行纯噪音;更严重的是"忘记 rollback"只能靠人工 review 保证(
profile_repository.update就没有 rollback 分支,advanced_material_repository.update_import有)。任何连接策略变更(连接池 / WAL / 超时)需要改 131 处。 - 修复建议:在
database/repositories/__init__.py建BaseRepository:
上例的class BaseRepository: def __init__(self, database: Database) -> None: self.database = database @property def placeholder(self) -> str: return self.database._placeholder @contextmanager def _connect(self, *, write: bool = False): conn = self.database.connect() try: yield conn if write: conn.commit() except Exception: if write: _rollback(conn) raise finally: conn.close() def _fetch_one(self, sql: str, params: tuple, mapper): ... def _fetch_all(self, sql: str, params: tuple, mapper): ...get_import塌缩成 3 行。预计削减 ≈390 行,并顺带消除 13 份重复的__init__+placeholder属性(profile_repository.py:121-127、wardrobe_repository.py:41-47等 13 处)。
[P1-严重] _optional_text 被独立定义 30 次,且 backend/routes/params.py 已有的同名别名却无人使用(削减 ≈145 行)
- 位置:30 个定义点,包括
backend/services/queue_service.py:713、backend/services/generation_service.py:2112、backend/services/workflow_round_service.py:1592、database/repositories/workflow_round_repository.py:1343、engines/single_flow.py:241、engines/vision_provider.py:450、core/astrbot_provider_bridge.py:349、adapters/wechat_adapter.py:77、adapters/onebot11_adapter.py:96… - 问题:同一 5 行函数被复制 30 份;而
backend/routes/params.py:22早就提供了optional_text = optional_str别名,并且注释宣称"两个名字在后端都在用"——实际grep显示optional_text从未被任何模块 import,注释是错的。 - 代码:
# backend/routes/params.py:20-22 # Both names are used for this coercion across the backend. Keep the alias so # route and service code can use the vocabulary that best fits the field. optional_text = optional_str
但另外 3 份语义不同:# backend/services/queue_service.py:713 —— 与另外 26 份逐字节相同 def _optional_text(value: Any) -> str | None: if value is None: return None text = str(value).strip() return text or None# core/astrbot_provider_bridge.py:349 / adapters/wechat_adapter.py:77 / adapters/onebot11_adapter.py:96 def _optional_text(value: Any) -> str | None: text = str(value or "").strip() # 0 / False / [] 会被当成 None,主流版本不会 return text or None - 影响:150 行冗余;且
str(value or "")变体对0/False的处理与主流版本不一致,跨模块搬运代码时会静默改变行为。 - 修复建议:新建
core/coerce.py(或复用backend/routes/params.py,但要把它从routes包挪到core,因为database/repositories和engines依赖 routes 包是层级倒置),导出optional_text/optional_int/optional_float/as_bool/string_list/mapping;30 处改为from core.coerce import optional_text as _optional_text。删掉params.py:22的死别名及其错误注释。预计削减 ≈145 行。
[P1-严重] _string_list 定义 18 次且至少有 6 种不同语义——同名不同义的语义地雷(削减 ≈90 行 + 消除隐患)
- 位置:
backend/services/composition_builder.py:279、backend/services/generation_service.py:2417、backend/services/prompt_expansion_service.py:257、backend/services/workflow_round_service.py:1544、backend/services/advanced_style_set_service.py:4288、backend/services/material_normalization_service.py:368、core/astrbot_provider_bridge.py:344、engines/vision_provider.py:432、engines/review_flow.py:430等共 18 处 - 问题:同名函数在不同模块行为完全不同——是否对逗号字符串切分、是否去重、是否排序、是否接受
tuple/set,四个维度自由组合。 - 代码(同名,四种不同结果):
# core/astrbot_provider_bridge.py:344 —— 逗号切分 + 去重 + 排序 def _string_list(value: Any) -> list[str]: values = value.split(",") if isinstance(value, str) else value if isinstance(value, list) else [] return sorted({str(item).strip() for item in values if str(item).strip()}) # backend/services/generation_service.py:2417 —— 逗号切分 + 不去重 + 不排序 def _string_list(value: Any) -> list[str]: if isinstance(value, str): values = value.split(",") elif isinstance(value, (list, tuple, set)): values = value else: return [] return [str(item).strip() for item in values if str(item).strip()] # backend/services/workflow_round_service.py:1544 —— 不接受字符串(字符串直接返回 [])+ 去重保序 def _string_list(value: Any) -> list[str]: values = value if isinstance(value, list) else [] return list(dict.fromkeys(str(item).strip() for item in values if str(item).strip())) # backend/services/prompt_expansion_service.py:257 —— 字符串整体作为单元素,不切分 def _string_list(value: Any) -> list[str]: if isinstance(value, str): return [value] if value.strip() else [] ... - 影响:tags / prompt_parts 这类字段在 service 间流转时,同一份数据经过不同模块会得到顺序不同、元素数不同的列表。已经导致 prompt 片段顺序在
advanced_style_set_service(保序去重)与astrbot_provider_bridge(排序)之间不可预测。任何人跨模块复制一行调用都会踩坑。 - 修复建议:在
core/coerce.py定义三个语义显式命名的函数替代:csv_tags(value)(切分+去重+保序)、prompt_parts(value)(不切分+去重+保序)、sorted_tags(value)(切分+去重+排序),18 处按实际语义各自替换。预计削减 ≈90 行,并把语义分叉从隐式变成显式。
[P1-严重] core/queue_manager.py 整文件死代码(112 行,零引用)
- 位置:
core/queue_manager.py:1-112 - 问题:
QueueManager/QueueItem是一套完整的内存队列实现(enqueue / dequeue / complete / fail / retry / summary + FSM 校验),但全仓(含tests/)没有任何模块 importcore.queue_manager,也没有任何地方引用QueueManager或QueueItem。真实队列走的是backend/services/queue_service.py+database/repositories/job_repository.py的持久化实现。 - 代码:
验证:# core/queue_manager.py:42-70 class QueueManager: def __init__(self): self._pending: deque[str] = deque() self._items: dict[str, QueueItem] = {} self._idempotency_index: dict[str, str] = {} def enqueue(self, payload: dict[str, Any], *, idempotency_key: str | None = None) -> QueueItem: ...grep -rn "queue_manager|QueueItem" --include=*.py .的全部命中都落在core/queue_manager.py自身。 - 影响:112 行需要维护的"影子队列实现",与真实队列的状态机语义并行存在,新人极易误用;且它单独依赖
core.fsm.task_transition,让fsm看起来比实际有更多消费者。 - 修复建议:整文件删除。削减 112 行。
[P1-严重] 复制粘贴造成的真实行为差异:branch_routes 漏配 event_bus,分支事件永不推送
- 位置:
backend/routes/branch_routes.py:62-68(对比backend/routes/node_routes.py:305-312、backend/routes/workflow_routes.py:143-150、backend/routes/profile_routes.py:174-181) - 问题:
_create_workflow_service()在 4 个 route 模块里各复制了一份,其中branch_routes那份漏掉了event_bus=get_default_event_bus()。 - 代码:
而# backend/routes/branch_routes.py:62-68 ← 缺 event_bus def _create_workflow_service() -> WorkflowService: database = Database(load_database_settings()) return WorkflowService( workflow_repository=WorkflowRepository(database), profile_repository=ProfileRepository(database), audit_service=AuditService(database), ) # backend/routes/workflow_routes.py:143-150 ← 有 event_bus def _create_workflow_service() -> WorkflowService: database = Database(load_database_settings()) return WorkflowService( workflow_repository=WorkflowRepository(database), profile_repository=ProfileRepository(database), audit_service=AuditService(database), event_bus=get_default_event_bus(), )WorkflowService._publish是空守卫:# backend/services/workflow_service.py:1012-1014 def _publish(self, event_type: str, payload: dict[str, Any]) -> None: if self.event_bus: self.event_bus.publish(event_type, payload)create_branch(workflow_service.py:514)与switch_branch(workflow_service.py:640)都调用了_publish。 - 影响:走 HTTP
POST /workflows/{id}/branches和POST /workflows/{id}/switch-branch创建/切换分支时,事件被静默吞掉,前端 SSE(backend/routes/event_routes.py)永远看不到分支变更,且不报错——典型的"复制粘贴少复制一行"缺陷。 - 修复建议:把 22 个
_create_*_service()工厂集中到backend/services/factory.py(或backend/container.py),每种 service 只保留一份构造。同时解决另一个层级倒置问题:backend/services/workflow_round_worker_runtime.py:10反向from backend.routes.node_routes import create_generation_service,而node_routes.py:393-396的create_generation_service()只是return _create_generation_service()的纯转发壳。削减 ≈20 行 + 修一个功能缺陷 + 消除 service→routes 反向依赖。
[P2-中等] 复制粘贴造成的第二个行为差异:VisionProviderConfig.endpoint_url 缺 /v1 去重
- 位置:
engines/vision_provider.py:40-43(对比engines/image_provider.py:51-56) - 问题:两个
endpoint_url()是明显的复制关系,但 image 版本有/v1去重规则,vision 版本没有。 - 代码:
# engines/image_provider.py:51-56 def endpoint_url(self) -> str: base = self.base_url.rstrip("/") endpoint = self.image_endpoint if self.image_endpoint.startswith("/") else f"/{self.image_endpoint}" if base.lower().endswith("/v1") and endpoint.lower().startswith("/v1/"): endpoint = endpoint[3:] # ← 去重 return f"{base}{endpoint}" # engines/vision_provider.py:40-43 ← 没有去重 def endpoint_url(self) -> str: base = self.base_url.rstrip("/") endpoint = self.vision_endpoint if self.vision_endpoint.startswith("/") else f"/{self.vision_endpoint}" return f"{base}{endpoint}"vision_endpoint的默认值是"/v1/chat/completions"(vision_provider.py:35)。backend/services/model_provider_runtime.py:210-216和:297-303拼 URL 时同样没有去重。 - 影响:用户在配置里填
base_url: https://api.example.com/v1(这是 OpenAI 兼容服务最常见的写法,也是_conf_schema.json里 provider base_url 的自然填法)时,视觉识别请求会打到https://api.example.com/v1/v1/chat/completions→ 404,而生图请求正常。用户很难定位。 - 修复建议:把
endpoint_url提到engines/_provider_base.py的共享函数join_endpoint(base_url, endpoint),image / vision /model_provider_runtime三处共用。削减 ≈10 行 + 修一个配置陷阱。
[P2-中等] DTO 中 15 个 to_dict() 是纯字段镜像,可由一个 mixin 替代(削减 ≈220 行)
- 位置:
backend/dto/workflow_round_dto.py:29、:69、:103;backend/dto/workflow_dto.py:24、:61、:109、:137;backend/dto/profile_dto.py:32;backend/dto/material_dto.py:80、:108;backend/dto/image_dto.py:32;backend/dto/job_dto.py:27;backend/dto/wardrobe_dto.py:25;backend/dto/profile_card_dto.py:19;backend/dto/workflow_feedback_dto.py:16 - 问题:AST 扫描确认这 15 个
to_dict()的 key 列表与 value 表达式逐项等于 dataclass 字段声明顺序,没有任何重命名或转换,共 234 行。 - 代码:
# backend/dto/workflow_round_dto.py:9-47 字段声明 17 个,to_dict 原样抄一遍 @dataclass(frozen=True) class WorkflowGenerationRound: round_id: str workflow_id: str node_id: str ... def to_dict(self) -> dict[str, Any]: return { "round_id": self.round_id, "workflow_id": self.workflow_id, "node_id": self.node_id, ... } - 影响:新增字段必须改两处,漏改会静默导致 API 少字段(这类 bug 没有任何类型检查能拦住)。234 行零信息量代码。
- 修复建议:在
backend/dto/common.py加
15 个类改为继承class DictMixin: def to_dict(self) -> dict[str, Any]: return {f.name: getattr(self, f.name) for f in dataclasses.fields(self)}DictMixin并删除各自的to_dict(另 18 个有转换逻辑的保持手写,可继续覆写)。预计削减 ≈220 行。
[P2-中等] main.py 50 个 /yp 短别名命令是纯转发壳(削减 ≈140 行)
- 位置:
main.py:1300-1463(164 行) - 问题:
imagestudio_short_command命令组下的 49 个方法,每一个都只是把参数原样转给同名长命令。 - 代码:
代码风格还不统一——前 8 个用两行# main.py:1304-1317 @imagestudio_short_command.command("帮助") async def imagestudio_short_help(self, event: AstrMessageEvent): async for result in self.imagestudio_help(event): yield result @imagestudio_short_command.command("状态") async def imagestudio_short_status(self, event: AstrMessageEvent, workflow_id: str = ""): async for result in self.imagestudio_status(event, workflow_id): yield result @imagestudio_short_command.command("快速角色") async def imagestudio_short_quick_profile(self, event: AstrMessageEvent, description: str = ""): async for result in self.imagestudio_quick_profile(event, description): yield resultasync for/yield,后 41 个压成一行async for result in ...: yield result(main.py:1345起),说明是分批粘贴出来的。 - 影响:164 行样板;新增一条命令必须记得在两个地方注册,漏掉短别名不会报错只会"短命令不存在"。
imagestudio_command与imagestudio_short_command的命令名映射表散落在 100 个装饰器里,无法一眼审计。 - 修复建议:把命令名与处理方法的映射抽成一张表,在类体末尾用循环生成短别名:
(若 AstrBot 装饰器要求签名内省,则退化为保留装饰器但由代码生成脚本维护。)预计削减 ≈140 行。_SHORT_ALIASES = {"帮助": "imagestudio_help", "状态": "imagestudio_status", ...} def _bind_short_aliases(cls): for zh_name, target in _SHORT_ALIASES.items(): async def _forward(self, event, *args, _target=target, **kwargs): async for result in getattr(self, _target)(event, *args, **kwargs): yield result setattr(cls, f"_short_{target}", cls.imagestudio_short_command.command(zh_name)(_forward)) return cls
[P2-中等] EventBus 的订阅分发链路全空转——subscribe/unsubscribe 零调用(过度设计)
- 位置:
core/event_bus.py:31-49 - 问题:
EventBus实现了 handler 注册 + 分发,但subscribe/unsubscribe在全仓(含tests/、前端)零调用,self._handlers永远是空 defaultdict,publish里的分发循环永远迭代 0 次。唯一消费者EventStreamService.recent_events(backend/services/event_stream_service.py:22)只读history()。 - 代码:
# core/event_bus.py:31-49 class EventBus: def __init__(self, *, history_limit: int = 200): self._handlers: DefaultDict[str, list[EventHandler]] = defaultdict(list) self._history: deque[Event] = deque(maxlen=max(int(history_limit), 1)) def subscribe(self, event_type, handler) -> None: # 零调用 ... def unsubscribe(self, event_type, handler) -> None: # 零调用 ... def publish(self, event_type, payload=None) -> Event: event = Event(...) self._history.append(event) for handler in [*self._handlers.get(event.event_type, []), *self._handlers.get("*", [])]: handler(event) # 永远不执行 return event - 影响:
EventBus实际只是一个有界环形缓冲,却按发布/订阅总线的形态被到处注入(WorkflowService、GenerationService、QueueService都接受event_bus参数),误导读者以为存在事件驱动链路——这正是branch_routes漏配event_bus一直没被发现的原因。 - 修复建议:删除
subscribe/unsubscribe与publish中的分发循环、_handlers字段、EventHandler类型别名(≈14 行),把类改名为EventLog或保留名字但在 docstring 明确"仅记录,不分发"。若确实计划做订阅,则应先接一个真实订阅方。
[P2-中等] _json_or_none / _json_loads / _json_object 在仓储层重复 20 次(削减 ≈75 行)
- 位置:
_json_or_none12 处:advanced_material_repository.py:2072、capability_repository.py:150、image_repository.py:298、integration_repository.py:103、job_repository.py:562、material_repository.py:313、model_provider_repository.py:371、profile_repository.py:348、wardrobe_repository.py:184、workflow_cross_review_repository.py:1442、workflow_repository.py:703、workflow_round_repository.py:1318、core/audit_service.py:113;_json_loads6 处;_json_object2 处 - 问题:13 份
_json_or_none逐字节相同;_json_loads(capability/image/integration/job/material/model_provider/workflow_repository)与_json_object(advanced_material/workflow_round)是同一功能的两个名字,后者多了isinstance(parsed, dict)保护,前者没有——JSON 列被写成数组时前者会返回 list,调用方dict[str, Any]类型标注是假的。 - 代码:
# 13 份完全相同 def _json_or_none(value: Any | None) -> str | None: if value is None: return None return json.dumps(value, ensure_ascii=False, sort_keys=True) # capability_repository.py:156 —— 无 dict 保护,类型标注撒谎 def _json_loads(value: str | None) -> dict[str, Any]: if not value: return {} return json.loads(value) # advanced_material_repository.py:2078 —— 有 dict 保护 def _json_object(value: str | None) -> dict[str, Any]: if not value: return {} parsed = json.loads(value) return parsed if isinstance(parsed, dict) else {} - 影响:≈100 行冗余;
_json_loads的 6 个使用点在遇到非 dict JSON 时会把 list 当 dict 返回,下游.get()直接 AttributeError。 - 修复建议:
database/repositories/_json.py导出dump_json(=_json_or_none)与load_object(带 dict 保护的版本),删除全部 20 个本地定义,_json_loads的调用点统一切到有保护的版本。预计削减 ≈75 行 + 消除一类运行时 AttributeError。
[P2-中等] update 赋值构建块在 workflow_repository 内复制 4 次(削减 ≈85 行)
- 位置:
database/repositories/workflow_repository.py:141-176、:180-227、:280-321、:324-379;同型代码另见profile_repository.py:242-283、image_repository.py:185 - 问题:
update_workflow/update_workflow_if_status用同一份 7 键allowed集合 + 同一段赋值循环;update_node/update_node_if_status用同一份 13 键allowed集合 + 同一段循环。四段循环体逐字节相同。 - 代码:
# workflow_repository.py:295-303 与 :348-356 完全相同 assignments: list[str] = [] params: list[Any] = [] placeholder = self.placeholder for key in allowed: if key not in payload: continue column = "metadata_json" if key == "metadata" else key value = _json_or_none(payload[key]) if key == "metadata" else payload[key] assignments.append(f"{column} = {placeholder}") params.append(value)allowed集合本身也各复制两遍(:281-294与:333-346的 13 个键完全相同)。 - 影响:给 node 加一个可更新字段要改 2 个
allowed集合,漏改会导致"普通更新生效、CAS 更新静默丢字段",且无任何测试能覆盖到这种不对称。 - 修复建议:模块级常量
WORKFLOW_UPDATABLE = frozenset({...})/NODE_UPDATABLE = frozenset({...}),加共享函数
(def _assignments(payload, allowed, placeholder, json_keys=frozenset({"metadata"})) -> tuple[list[str], list[Any]]:advanced_material_repository.py:2042已有更通用的_update_assignments(payload, placeholder, columns),直接把它提升到database/repositories/_sql.py并让 workflow/profile/image/job 四个仓储共用即可。job_repository.py:568是它的第二个分叉实现。)预计削减 ≈85 行。
[P2-中等] _signed_url 复制 7 份,其中 3 份的异常捕获范围不一致(削减 ≈41 行)
- 位置:
backend/routes/advanced_material_routes.py:428、backend/routes/image_routes.py:226、backend/routes/material_routes.py:317、backend/routes/profile_card_routes.py:90、backend/routes/round_routes.py:192、backend/services/workflow_round_worker_runtime.py:257、backend/services/dashboard_service.py:89 - 问题:同一个"签名失败就返回 None"的包装函数复制了 7 份,签名和异常范围各不相同。
- 代码:
# backend/routes/image_routes.py:226-232 —— 只吞 ApiError def _signed_url(media_service: MediaService, uri: str | None) -> str | None: if not uri: return None try: return media_service.sign_media(uri)["url"] except ApiError: return None # backend/routes/advanced_material_routes.py:428-435 —— 吞所有异常,且每次调用新建 MediaService() def _signed_url(uri: Any) -> str | None: text = str(uri or "").strip() if not text: return None try: return MediaService().sign_media(text)["url"] except Exception: return None # backend/services/workflow_round_worker_runtime.py:257-263 —— 吞所有异常 + .get("url") - 影响:49 行冗余;
advanced_material_routes版本在列表序列化时每张图新建一次MediaService()(内部会ConfigService()读盘),列表页 N 张图 = N 次配置加载。 - 修复建议:在
MediaService上加实例方法def signed_url(self, uri: Any) -> str | None:,7 处全部改为media_service.signed_url(uri)。预计削减 ≈41 行 + 消除 advanced_material 列表页的 N 次配置读盘。
[P2-中等] 分页/限流工具函数 _page / _page_size / _limit 重复 10 次且默认值不一致(削减 ≈48 行)
- 位置:
_page/_page_size:job_repository.py:609/617、material_repository.py:319/327、profile_repository.py:354/362、advanced_material_repository.py:2111/2115;_limit:integration_repository.py:109、job_repository.py:601、backend/services/log_service.py:293、backend/services/event_stream_service.py:35、backend/services/settings_service.py:659 - 问题:三份
_page逐字节相同(try/except → max(page,1)),第四份advanced_material_repository.py:2111写成max(int(value or 1), 1)——传入非数字字符串时前三份返回 1、第四份抛ValueError。_limit的默认值/上限在 5 处各不相同(50/200、50/200、…)。 - 代码:
# job_repository.py:609 / material_repository.py:319 / profile_repository.py:354 —— 三份相同 def _page(value: Any) -> int: try: page = int(value) except (TypeError, ValueError): page = 1 return max(page, 1) # advanced_material_repository.py:2111 —— 不吞异常 def _page(value: int) -> int: return max(int(value or 1), 1) - 影响:60 行冗余;高级素材列表接口对畸形
page参数会 500,而其他列表接口降级为第 1 页——同一套 API 的错误语义不一致。 - 修复建议:
core/coerce.py提供page(value)/page_size(value, *, default, maximum)/clamp_limit(value, *, default, maximum),10 处替换。预计削减 ≈48 行 + 统一 API 参数容错语义。
[P2-中等] 确证死代码:29 个函数/类/方法全仓零引用(削减 ≈263 行)
-
位置与规模(均已用
grep -rn在main.py + backend + core + database + engines + adapters + tests + frontend/src全范围交叉验证,引用数为 1,即只有定义处):文件:行 符号 行数 database/repositories/workflow_round_repository.py:488update_pool_preferences60 backend/dto/material_dto.py:10RawAnalysis19 backend/dto/material_dto.py:32NormalizedAssetProfile19 backend/services/worker_service.py:148QueueWorker.run_batch15 core/interactions.py:49normalize_action14 backend/dto/material_dto.py:54GenerationCapsule13 core/interop.py:14PluginRequest13 core/interop.py:29normalize_plugin_request13 core/interop.py:49daily_outfit_request12 backend/dto/chat_command_dto.py:21SingleImageCommand.to_payload10 database/repositories/profile_card_repository.py:266next_version10 database/repositories/advanced_material_repository.py:357get_import_by_idempotency_key10 backend/services/queue_service.py:539requeue_dead_letters10 core/secret_service.py:57env_ref5 core/runtime_paths.py:28get_runtime_data_root4 core/event_bus.py:36/41subscribe/unsubscribe7 core/webhook.py:33/40sign_event/verify_signature6 backend/services/web_hosting_service.py:42/50/54三个 asset 解析方法 9 core/interop.py:44is_allowed_plugin3 core/audit_service.py:109create_audit_service2 backend/services/media_service.py:33fetch_media_metadata2 backend/services/queue_service.py:277is_cancelled2 database/models.py:21/24column_names/sensitive_columns4 engines/image_provider.py:92ImageGenerationResult.has_images2 core/secret_service.py:34SecretResolution.to_public_dict2 backend/services/settings_service.py:884_dump_yaml = dump_yaml兼容别名3 backend/routes/params.py:22optional_text = optional_str别名3 backend/services/advanced_material_service.py:71IMPORT_REVIEW_STATUSES1 core/image_formats.py:22SUPPORTED_IMAGE_MIME_TYPES1 -
代码(几个值得单独说明的):
# backend/services/settings_service.py:882-884 —— 注释说"为已有测试保留",但 grep 显示没有任何测试引用 # Compatibility alias for existing tests and services that imported the # previous private serializer. New code should import core.config_writer. _dump_yaml = dump_yaml# core/interop.py —— 整个模块只有 PRIVATE_COMPANION 常量被 integration_token_service.py:16 引用, # 其余 PluginRequest / normalize_plugin_request / is_allowed_plugin / daily_outfit_request / ALLOWED_PLUGINS # 组成一条完全无人调用的调用链(daily_outfit_request 是唯一入口,而它自己零引用)# backend/services/queue_service.py:539 —— 死信重入队能力已实现但无路由、无 CLI、无测试触发 def requeue_dead_letters(self, ctx, *, limit: int = 50) -> dict[str, Any]: -
影响:263 行需要被 review、被 grep 命中、被误认为"有人在用"的代码。
requeue_dead_letters和update_pool_preferences尤其危险——它们看起来是产品功能(死信恢复、候选池偏好),实际从未接线,容易让人误以为功能已交付。 -
修复建议:全部删除(
core/interop.py保留PRIVATE_COMPANION常量,其余删掉;或把常量挪到integration_token_service.py后整文件删除,可再减 ≈45 行)。若requeue_dead_letters/update_pool_preferences是计划中的功能,应转成 issue 并删代码,不要留半成品。预计削减 ≈263 行(含 interop 整清理约 300 行)。
[P3-轻微] EventStreamService._event_to_webhook 造两次对象再丢弃一次(过度设计)
- 位置:
backend/services/event_stream_service.py:42-49,配合core/webhook.py:48-49 - 问题:
event_from_bus()造一个带随机event_id和当前时间的WebhookEvent,紧接着_event_to_webhook把这两个字段全部丢掉、用 bus event 的值重建一个新对象。中间对象完全是浪费。 - 代码:
# backend/services/event_stream_service.py:42-49 def _event_to_webhook(event: Event) -> WebhookEvent: webhook_event = event_from_bus(event.event_type, event.payload) # 造一个 return WebhookEvent( # 立刻丢掉重造 event_type=webhook_event.event_type, data=webhook_event.data, event_id=event.event_id, created_at=event.created_at, ) # core/webhook.py:48-49 def event_from_bus(event_type: str, payload: dict[str, Any]) -> WebhookEvent: return WebhookEvent(event_type=event_type, data=dict(payload)) - 影响:每条 SSE 事件多一次
uuid4()+datetime.now()(WebhookEvent的default_factory)。recent_events默认 limit 50、上限 200,即每次拉取浪费 50~200 次 UUID 生成。可读性上更糟:读者会以为event_from_bus有转换逻辑。 - 修复建议:
def _event_to_webhook(event: Event) -> WebhookEvent: return WebhookEvent( event_type=event.event_type, data=dict(event.payload), event_id=event.event_id, created_at=event.created_at, )core/webhook.py:48-49的event_from_bus随之成为死代码(唯一调用点消失),一并删除。削减 ≈6 行。
[P3-轻微] ImageProviderError 与 VisionProviderError 逐字节相同;_post_json 的 urllib 分支重复 40 行
- 位置:
engines/image_provider.py:96-110vsengines/vision_provider.py:72-86;engines/image_provider.py:272-303vsengines/vision_provider.py:295-337 - 问题:两个异常类的
__init__与全部字段完全一致,只有类名不同;_post_json的 urllib 回退分支(HTTPError / URLError / RemoteFetchError 三个 except 块)也只差异常类和错误文案里的image/vision前缀。 - 代码:
# engines/image_provider.py:96-110 / engines/vision_provider.py:72-86 —— 除类名外完全相同 class ImageProviderError(RuntimeError): def __init__(self, message: str, *, provider_id: str, status_code: int | None = None, error_type: str = "provider_error", details: dict[str, Any] | None = None): super().__init__(message) self.provider_id = provider_id self.status_code = status_code self.error_type = error_type self.details = details or {} - 影响:≈55 行冗余。真正的代价是分叉:image 版
_post_json已经加了 httpx 流式读取 + 长度上限(image_provider.py:231-271),vision 版还停留在纯 urllib,所以视觉调用没有 httpx 的超时/重定向控制,也没有_provider_json_limit动态上限。 - 修复建议:新建
engines/_provider_http.py,提供
两个 provider 各传class ProviderError(RuntimeError): ... # 两个子类只留 `pass` + 文案前缀 def post_json(url, payload, headers, timeout_seconds, *, error_cls, label, max_bytes) -> JsonDict: ...error_cls=ImageProviderError, label="image"。削减 ≈55 行 + 让 vision 自动获得 httpx 路径。
[P3-轻微] core/config_service.py 的存储默认值在同文件写了两遍
- 位置:
core/config_service.py:24-31(dataclass 默认值)与:74-83(load()里的.get(key, 默认值)) - 问题:7 条存储路径的默认值在同一个文件里硬编码两次。
- 代码:
# core/config_service.py:24-31 @dataclass(frozen=True) class StorageConfig: images_path: str = "data/images" thumbnails_path: str = "data/thumbnails" ... # core/config_service.py:74-83 —— 同样的字面量再写一遍 storage=StorageConfig( images_path=str(storage.get("images_path", "data/images")), thumbnails_path=str(storage.get("thumbnails_path", "data/thumbnails")), ... ) - 影响:改默认路径必须改两处,漏改后"未配置时"和"配置为空字符串时"会落到不同目录。
- 修复建议:
削减 ≈12 行。同类问题:_STORAGE_FIELDS = {f.name for f in dataclasses.fields(StorageConfig)} storage=StorageConfig(**{k: str(v) for k, v in storage.items() if k in _STORAGE_FIELDS and v})PLUGIN_VERSION = "1.0.72"在core/config_service.py:13、config.yaml:4、metadata.yaml:5三处硬编码,而config_service.load()的注释(:68-70)明确说会忽略config.yaml里的值——config.yaml的plugin.version是纯误导,应删除。
[P3-轻微] _optional_text 之外的其他小工具重复:_now ×6、_mapping ×4、_rollback ×3
- 位置:
_now:backend/services/advanced_style_set_service.py:4279、generation_job_retry_service.py:493、queue_service.py:709、worker_service.py:476、core/queue_manager.py:14(另integration_token_service.py:178返回datetime非str);_mapping:backend/services/history_service.py:313、model_provider_bootstrap.py:353、workflow_round_service.py:1196、database/repositories/workflow_cross_review_repository.py:1429;_rollback:见上文 - 问题:
_now()的 5 份return datetime.now(timezone.utc).isoformat()完全相同。_mapping()已经被抽出 4 次却没有共享,而它对应的内联写法x.get("y") if isinstance(x.get("y"), dict) else {}在后端出现 291 次(advanced_style_set_service.py47 次、generation_service.py37 次、advanced_material_service.py24 次)。 - 代码:
# backend/routes/node_routes.py:329-335 —— 一个函数里连着 5 行同款 generation_config = config_payload.get("generation") if isinstance(config_payload.get("generation"), dict) else {} model_assignments = config_payload.get("model_assignments") if isinstance(config_payload.get("model_assignments"), dict) else {} governance_config = config_payload.get("prompt_governance") if isinstance(config_payload.get("prompt_governance"), dict) else {} translation_config = governance_config.get("translation") if isinstance(governance_config.get("translation"), dict) else {} moderation_config = governance_config.get("moderation") if isinstance(governance_config.get("moderation"), dict) else {} - 影响:
_now≈15 行冗余;291 处内联写法虽然不减行数,但每处都把 key 名写两遍,是"改 key 名漏改一半"的高发点(写成config.get("a") if isinstance(config.get("b"), dict) else {}不会有任何工具报错)。 - 修复建议:
core/coerce.py提供utc_now_iso()与mapping(value);291 处内联改为mapping(config_payload.get("generation")),key 名只出现一次。削减 ≈30 行 + 消除一类 key 名不一致隐患。
[P3-轻微] 两个源文件带 UTF-8 BOM,导致标准 AST 工具解析失败
- 位置:
backend/routes/job_routes.py:1、backend/services/profile_document_import_service.py:1 - 问题:文件以
\xef\xbb\xbf开头。ast.parse(path.read_text(encoding="utf-8"))直接抛SyntaxError: invalid non-printable character U+FEFF。 - 代码:
$ python -c "import pathlib; print(pathlib.Path('backend/routes/job_routes.py').read_bytes()[:6])" b'\xef\xbb\xbf"""' - 影响:Python 解释器自身能处理(
tokenize会跳过 BOM),但任何自建的 AST 分析、代码生成、lint 插件、批量重构脚本都会在这两个文件上失败。本次审计的死代码扫描就漏掉了这两个文件。 - 修复建议:
python -c "p=...; p.write_bytes(p.read_bytes()[3:])"去掉 BOM,并在.gitattributes/ pre-commit 加检查。
[P3-轻微] 148 个路由处理器的 def action() 闭包样板(可选,高风险)
- 位置:
backend/routes/*.py共 148 处def action()+ 157 处return handle_request(ctx, action)+ 147 处service or _create_xxx() - 问题:每个路由处理器固定四段式:
xxx_service = service or _create_xxx()→def action():→require_xxx(ctx)→return handle_request(ctx, action)。 - 代码:
同文件# backend/routes/wardrobe_routes.py:57-70 —— 与另外 147 个处理器同构 def delete_wardrobe_item(ctx, profile_id, wardrobe_item_id, service=None) -> dict: wardrobe_service = service or _create_wardrobe_service() def action() -> dict[str, Any]: require_permission(ctx, "can_manage_materials") return wardrobe_service.delete_item(profile_id, wardrobe_item_id, ctx) return handle_request(ctx, action):86-107已经出现了绕过闭包的"元组下标"写法,说明作者本人也觉得样板烦:return handle_request(ctx, lambda: (require_permission(ctx, "can_manage_materials"), wardrobe_service.save_template(profile_id, payload, ctx))[1]) - 影响:≈450 行样板;权限声明散落在闭包第一行,无法从
route_registry.ROUTES静态核对(RouteSpec.permission与require_xxx(ctx)是两份独立真相,branch_routes的 event_bus 缺失就是这种双真相结构的产物)。 - 修复建议(改动面大,建议单独立项):引入装饰器让权限声明与
RouteSpec单一化:
并在启动时断言装饰器声明的 permission 与@route_handler(permission="materials", service_factory=_create_wardrobe_service) def delete_wardrobe_item(ctx, profile_id, wardrobe_item_id, *, service) -> dict[str, Any]: return service.delete_item(profile_id, wardrobe_item_id, ctx)route_registry.ROUTES一致。预计削减 ≈300 行 + 权限矩阵可静态校验。风险:148 个处理器的测试注入点(service=参数)需同步调整,建议分模块灰度。
削减总计
| # | 项目 | 位置规模 | 预计削减 | 风险 |
|---|---|---|---|---|
| 1 | 仓储连接样板 → BaseRepository._connect() |
131 处 | ≈390 | 中 |
| 2 | DTO to_dict 纯镜像 → DictMixin |
15 个类 | ≈220 | 低 |
| 3 | 死代码清理(29 符号 + queue_manager.py + interop 残链) |
30+ 处 | ≈375 | 低 |
| 4 | _optional_text ×30 → core/coerce |
30 处 | ≈145 | 低 |
| 5 | main.py 短别名 ×50 → 映射表 |
164 行 | ≈140 | 中 |
| 6 | _string_list ×18 → 三个语义化函数 |
18 处 | ≈90 | 中 |
| 7 | update 赋值构建块 ×6 → _update_assignments |
6 处 | ≈85 | 低 |
| 8 | _json_or_none / _json_loads / _json_object ×20 |
20 处 | ≈75 | 低 |
| 9 | engines ProviderError + _post_json 提取 |
2 文件 | ≈55 | 低 |
| 10 | _page / _page_size / _limit ×10 |
10 处 | ≈48 | 低 |
| 11 | _signed_url ×7 → MediaService.signed_url |
7 处 | ≈41 | 低 |
| 12 | _now ×6 + _mapping ×4 + 291 处内联 dict 守卫 |
300+ 处 | ≈30 | 低 |
| 13 | _create_*_service 工厂集中(顺带修 branch_routes 缺陷) |
22 处 | ≈20 | 中 |
| 14 | EventBus 空转分发链路 |
1 处 | ≈14 | 低 |
| 15 | config_service 默认值重复 + config.yaml 死版本号 |
2 处 | ≈12 | 低 |
| 16 | _event_to_webhook 双次造对象 + event_from_bus |
2 处 | ≈6 | 低 |
| 小计(不含路由层改造) | ≈1,746 行 | |||
| 17 | 路由 action 闭包 → @route_handler 装饰器(建议单独立项) |
148 处 | ≈300 | 高 |
| 合计 | ≈2,046 行 / 后端 54,551 行 ≈ 3.8% |
推荐执行顺序(投入产出比降序):
- 第一批(零风险,纯删):#3 死代码、#14 EventBus、#16 event_from_bus、#15 config 默认值 → 约 400 行,无行为变更。
- 第二批(低风险,机械替换):#2 DictMixin、#4/#8/#10/#11/#12 工具函数统一 → 约 560 行,配合现有
tests/回归即可。 - 第三批(需谨慎,有行为差异要对齐):#6
_string_list语义拆分、#13 工厂集中(修 branch_routes 事件缺陷)、#9 provider 提取(修 vision/v1拼接缺陷) → 约 165 行,但同时消灭 3 个真实缺陷,价值最高。 - 第四批(大改动):#1 BaseRepository、#5 main.py 别名、#7 update 块 → 约 615 行。
- 单独立项:#17 路由装饰器。