codex-proxy-rs/docs/code-quality-audit.md

代码质量审计与改造计划

日期：2026-06-14

范围：当前仓库 src/、tests/，不包含 designs/。

目标：确认 /tmp/code_quality_audit.md 的结论，并基于当前代码给出后续改造顺序。项目处于早期阶段，不需要保留低质量兼容层；改造应以清晰边界、可测试、可维护为目标。

审计原则

1. 不为了“拆小文件”而拆文件。文件大小本身不是问题，问题是职责混杂、变更理由混在一起、审查和定位成本过高。
2. 不用“兼容历史”掩盖坏设计。内部 API 可以在测试保护下重构，外部行为必须由测试证明未回退。
3. Rust 代码遵循本项目的 $rust-best-practices：明确错误类型、少 clone、少分配、少隐式 panic，但性能优化要有证据。
4. 日志输出使用中文，保留必要英文专业术语，例如 WebSocket、SSE、OAuth、quota、token。
5. 每个改造切片先写或补齐测试，再改生产代码，最后跑目标测试、cargo fmt --check、cargo clippy --all-targets --all-features --locked -- -D warnings。

审计时量化事实

审计开始时 src/ + tests/ 约 37,055 行。生产代码里最需要关注的文件：

文件	行数	判断
src/codex/serving/dispatch/mod.rs	1474	已有子模块，但主文件仍承担请求编排、上游调用、stream audit、fallback、限流处理等多种职责
src/codex/gateway/transport/websocket.rs	1175	WebSocket pool、连接建立、请求编码、SSE 转发、错误分类、rate limit 捕获混在同一文件
src/codex/accounts/repository.rs	1103	账号 CRUD、token 更新、quota、usage、lease、pool read model 混在同一存储文件
src/codex/gateway/transport/client.rs	783	上游 transport 编排较重，但当前还可接受
src/codex/accounts/pool.rs	627	调度策略集中，复杂度主要来自业务策略，不是首要拆分对象

Claude 审计确认

1. update_tokens / update_from_claims 重复

结论：成立。

当前 AccountRepository::update_tokens 和 AccountRepository::update_from_claims 都重复处理：

• Utc::now().to_rfc3339()
• access token 加密
• refresh token 可选加密
• expires_at 格式化
• “没有新 refresh_token 时保留旧值”的分支

需要修复，但不建议照搬报告里的 QueryBuilder 方案。当前只有几个固定 SQL 形态，动态构建 SQL 会把绑定顺序变成新的维护风险。更合适的第一步是：

• 补测试：update_from_claims 省略 refresh_token 时必须保留旧 refresh_token。
• 提取私有 token 写入准备 helper。
• 将 UPDATE SQL 改成命名多行常量。
• 保持 disabled / banned 不被 update_tokens 重新激活的现有语义。

2. SQL 字符串地狱

结论：部分成立。

报告里的状态已经有些过期：LIST_POOL_ACCOUNTS_SQL、RECORD_USAGE_SQL、GET_USAGE_SQL 等已是多行常量。但问题仍存在：

• insert/get/list/list_metadata/update_tokens/update_from_claims/quota/lease/AccountUsageRepository::list/summary 仍有较多长单行 SQL。
• 一部分 SQL 的业务语义不容易在 review 时看清，例如 token 更新时的状态保护、quota cooldown 的最大值保留、refresh lease 的抢占条件。

建议先使用命名多行常量。sqlx::query_file! 不是当前第一选择，因为项目当前使用运行时 sqlx::query，切换到宏式编译期校验会引入额外数据库元数据/离线缓存约束，改造面比可读性收益更大。

3. AccountRepository God Class

结论：部分成立。

AccountUsageRepository 已经存在，说明项目已经开始拆 usage 读模型；但 AccountRepository 里仍混有：

• 账号 CRUD
• token 更新
• pool read model
• quota JSON 与 cooldown
• usage record/get/window sync
• refresh lease

这确实不是理想边界。后续可以拆，但不应机械拆成很多小文件。推荐按变更理由拆：

• account 基础读写
• token 写入
• quota 状态
• usage 统计写入与窗口同步
• refresh lease
• pool read model

是否暴露多个 repository 类型，需要看调用侧是否真的收益明显。可以先做内部模块拆分，再决定是否调整服务层依赖。

4. 超大文件

结论：成立，但“拆文件”不是目标。

三个文件已经大到影响定位和审查：

• dispatch/mod.rs
• websocket.rs
• repository.rs

但文件拆分必须跟职责边界一致：

• websocket.rs 适合按 pool、connection、request codec、SSE forwarding、error classification 拆。
• dispatch/mod.rs 适合把 stream audit、fallback/rate-limit 应用、上游请求执行拆到更明确的模块。
• repository.rs 适合先把 SQL 与行映射收拢，再拆 token/quota/usage/lease。

不建议为了把每个文件压到某个行数而过度碎片化。

5. Account clone 性能开销

结论：部分成立，不是第一优先级。

AccountPool 确实会 clone Account，而 Account 包含 token 字符串。这个成本存在，但当前设计也有合理性：AccountPool 在 Mutex 后面，返回 owned Account 可以避免把锁生命周期带入 async 上游调用。

直接改成 Arc<Account> 不是无成本优化，会牵涉：

• pool 内账号状态更新如何替换 snapshot
• 调度策略如何避免共享可变状态
• token 刷新和 cooldown 更新如何保持一致

建议先完成结构性重构。性能优化应结合 profile 或压测数据，再考虑 immutable snapshot + Arc<Account>。

6. 字符串分配过度

结论：审计过泛，暂不作为直接改造项。

.to_string() / .clone() 数量本身不能证明问题。当前很多转换来自：

• JSON/SSE 协议需要 owned String
• secret 解密后写入运行时 pool
• header、metadata、测试数据构造
• async 任务跨 await / spawn 的所有权要求

后续可以用 Clippy、profile 和热点路径 review 定点优化，不能按数量批量替换成 Cow 或引用。

我的补充审计

P0：token 更新重复和测试缺口

update_tokens 已有测试覆盖“没有新 refresh_token 时保留旧值”，但 update_from_claims 缺同类测试。由于导入已有账号时会走 update_from_claims，这是第一批代码改造前必须补齐的行为测试。

改造目标：

• 增加 update_from_claims 保留 refresh_token 测试。
• 提取 token 写入准备逻辑。
• 将对应 UPDATE SQL 改为命名多行常量。
• 保持现有行为，不顺手重构调用层。

P0：Repository SQL 可读性

repository.rs 的 SQL 可读性是当前最明显的维护问题。建议第一阶段只处理账号 repository 内的长 SQL，不扩散到全项目。

改造目标：

• 账号表常用 SELECT 语句提取为常量。
• token/quota/lease/usage summary 的长 SQL 改成多行常量。
• SQL 常量命名表达业务语义，例如 UPDATE_TOKENS_PRESERVING_DISABLED_STATUS_SQL。

P1：Repository 边界

存储层已经有一些 DDD 边界，但 AccountRepository 仍承载太多变更理由。推荐在 SQL 可读性改善后再拆，避免一边搬文件一边改 SQL。

推荐顺序：

1. 先把 SQL 常量和 row mapper 收拢。
2. 再拆 token/quota/lease/usage 内部模块。
3. 最后评估是否需要多个 public repository。

P1：WebSocket transport 边界

websocket.rs 当前实现已经覆盖原版核心链路，但职责过密：

• pool lifecycle
• idle probe / GC
• handshake request 构造
• request body 转换
• WS -> SSE 转发
• rate limit 内部事件捕获
• WS 错误分类

建议后续按“协议转换”和“连接池”先拆，不改变行为：

• websocket/pool.rs
• websocket/connection.rs
• websocket/codec.rs
• websocket/stream.rs
• websocket/error.rs

这个拆分是为了边界清楚，不是为了追求小文件。

P1：Dispatch 编排边界

dispatch/mod.rs 已有 affinity/fallback/refresh/routing/stream/usage 子模块，但主文件仍过重。建议把以下逻辑迁出：

• 上游 HTTP SSE / WebSocket stream audit
• quota/rate-limit header 应用
• fallback account retry 决策
• 上游请求执行 wrapper

目标是让 mod.rs 更像编排入口，而不是承载所有细节。

P1：日志一致性

当前日志大部分已经是中文，且不少已使用结构化字段。但仍需继续统一：

• 非中文日志消息需要改成中文，例如 UpdateChecker 相关日志。
• error = %e、account_id = %account_id 这类结构化字段应保持。
• 不把 token、cookie、refresh_token 放进日志。
• HTTP trace 日志已存在中文入口，应继续检查是否有 request_id/span 传播缺口。

P2：生产代码里的 unwrap()

大多数 unwrap() 位于测试模块。生产路径中发现 usage_snapshots.rs 的时间桶对齐使用 and_hms_opt(...).unwrap()。逻辑上这些时间值可证明有效，但风格上仍建议改成有语义的 helper 或 expect 文案，避免以后被复制到不可证明场景。

P2：测试文件过大

tests/codex_gateway/websocket.rs 约 1436 行，已经接近生产大文件的认知成本。测试拆分应按场景拆，而不是一个 endpoint 一个文件：

• WebSocket pool 复用/淘汰
• WebSocket fallback
• WS -> SSE 转换
• rate limit internal event
• error classification

P2：注释质量

项目里已有中文注释，但后续应保持“解释为什么”，避免解释显而易见的代码行为。适合保留的注释包括：

• token/refresh_token 保留策略
• SSE 响应头已发出后不能回滚 HTTP 状态
• 原版协议兼容的非显然参数
• 安全链路中的指纹/安装 ID/turn state 传递原因

推荐改造顺序

Phase 1：账号 repository P0

目标：先处理最确定、最小风险的问题。

1. 补 update_from_claims refresh_token 保留测试。
2. 提取 token 更新准备 helper。
3. UPDATE token/claims SQL 改命名多行常量。
4. 账号 repository 的明显长 SQL 改命名常量。
5. 跑 cargo test codex_accounts::repository 或对应过滤测试，再跑 fmt/clippy。

验收条件：

• update_tokens 和 update_from_claims 不再各自重复 token 加密、expires_at 格式化和 updated_at 生成逻辑。
• update_from_claims 省略 refresh_token 时保留旧 refresh_token，有测试覆盖。
• update_tokens 仍保持现有保护：disabled / banned 账号不会因为 token 更新被重新激活。
• token/claims/quota/lease/usage summary 的长 UPDATE/SELECT SQL 不再以内联单行字符串形式散落在方法体里。
• 不引入 QueryBuilder，除非实际需要动态字段集合。当前固定 SQL 形态优先使用命名多行常量，降低绑定顺序风险。
• 不调整调用层、不拆 public repository API、不改数据库 schema。
• 验证命令至少包括：
  • cargo test --test codex_accounts repository --locked
  • cargo fmt --check
  • cargo clippy --all-targets --all-features --locked -- -D warnings

Phase 1 不包含：

• AccountRepository public API 拆分。
• WebSocket/Dispatch 文件拆分。
• Account 改 Arc<Account>。
• 全局 .clone() / .to_string() 批量替换。
• 日志系统重构。

Phase 1 状态：已完成。

已完成内容：

• 增加 update_from_claims 省略 refresh_token 时保留旧 refresh token 的测试。
• 提取 token 写入准备逻辑，统一 access token 加密、可选 refresh token 加密、expires_at 格式化和 updated_at 生成。
• 将 token/claims 更新 SQL 改为命名多行常量，并保留 disabled / banned 不被 token 更新重新激活的语义。
• 将账号 repository 内 usage、quota、refresh lease 的长 SQL 和实现迁出到内部模块，public API 保持不变。

验证结果：

• cargo test --test codex_accounts repository --locked：13 passed。
• cargo test prepare_token_write_should_encrypt_tokens_and_format_timestamps --locked：1 passed。
• cargo fmt --check：通过。
• cargo clippy --all-targets --all-features --locked -- -D warnings：通过。

Phase 2：WebSocket transport 边界

目标：在不改变 WebSocket 行为的前提下，按职责拆分 src/codex/gateway/transport/websocket.rs。

建议顺序：

1. 先拆错误类型和协议编解码 helper。
2. 再拆连接建立、握手请求构造、消息发送。
3. 最后拆连接池生命周期和 stream 转发。

验收条件：

• WebSocket pool 的 55 分钟 max age、25 秒 ping、串行复用语义保持不变。
• WS -> SSE 输出格式保持不变。
• rate limit internal event、turn state、set-cookie、rate-limit header 捕获保持不变。
• HTTP SSE fallback 行为保持不变。
• 不引入 IP proxy/VPN 相关能力。

Phase 2 状态：已完成。

已完成内容：

• 新增 websocket/pool.rs，集中 WebSocket pool key、pool config、55 分钟 max age、keepalive、GC、shutdown、account cap、busy key bypass 等池化生命周期逻辑。
• 新增 websocket/codec.rs，集中 upstream request body 转换、WS frame 文本提取、WS event 分类、WS error frame 分类、retry-after/header 提取。
• websocket.rs 保留对外入口、连接建立、active connection 归还/丢弃、WS -> SSE stream 编排。
• 没有引入 IP proxy/VPN 能力。

验证结果：

• cargo test --test codex_gateway websocket --locked：20 passed。
• cargo fmt --check：通过。
• cargo clippy --all-targets --all-features --locked -- -D warnings：通过。

Phase 3：Dispatch 编排边界

目标：让 src/codex/serving/dispatch/mod.rs 更像请求编排入口，把可独立变化的细节迁到已有子模块或新的内部模块。

建议顺序：

1. 先确认已有 affinity/fallback/refresh/routing/stream/usage 子模块职责。
2. 优先迁出 stream audit 和 upstream response 转换逻辑。
3. 再评估 fallback/retry 决策、quota/rate-limit 应用是否需要继续迁出。

验收条件：

• 外部 API、SSE 输出、fallback 语义、quota cooldown、session affinity 保持不变。
• dispatch/mod.rs 不再同时承载所有 stream 细节。
• 每个迁移切片都有目标测试覆盖。

Phase 3 状态：已完成。

已完成内容：

• 新增 dispatch/audit.rs，集中 HTTP SSE / WebSocket stream 的审计、usage 记录、上游失败识别和账户 slot 释放。
• 扩展 dispatch/fallback.rs，将 fallback retry 的副作用迁入同一模块，包括 quota cooldown、Cloudflare cooldown、ban/quota 状态更新和备用账户获取。
• 新增 dispatch/limits.rs，集中 rate-limit header 解析、quota 缓存同步、window 同步和被动 cooldown 应用。
• dispatch/mod.rs 保留服务入口、请求编排和上游 client request 构造。上游 request 构造暂不硬拆，避免为了降行数引入复杂 lifetime/owned context 设计。

验证结果：

• cargo test --test codex_serving --locked：57 passed。
• cargo fmt --check：通过。
• cargo clippy --all-targets --all-features --locked -- -D warnings：通过。

Phase 4：日志、panic 点和测试组织收尾

目标：处理不会改变业务行为但影响长期维护质量的问题。

检查项：

1. 日志消息使用中文，保留 WebSocket/SSE/OAuth/quota/token 等专业术语。
2. 生产代码中避免无语义的 unwrap() / expect()。
3. 测试文件按场景组织，不为了拆小而过度拆分。
4. 继续避免 token、cookie、refresh token 等敏感信息进入日志。

Phase 4 状态：已完成。

已完成内容：

• 将 fingerprint 更新检查器日志中的 UpdateChecker 英文前缀改为中文表达，保留 fingerprint 专业术语。
• 清理 usage_snapshots.rs 生产路径中的时间桶对齐 unwrap()，改为无 panic 的 helper；测试代码中的 unwrap 保留。
• 将 tests/codex_gateway/websocket.rs 中 WebSocket pool 场景迁到 tests/codex_gateway/websocket/pool.rs，保留共享 helper 和非 pool 场景测试在父文件。
• 不继续拆更细的测试文件，避免把一个协议场景拆成过多小模块。

验证结果：

• cargo test usage_snapshots --locked：4 passed。
• cargo test --test codex_gateway websocket --locked：20 passed。
• cargo fmt --check：通过。
• cargo clippy --all-targets --all-features --locked -- -D warnings：通过。

改造后边界

本轮改造没有追求小文件数量，而是按变更理由拆分。当前关键文件规模如下：

文件	行数	当前职责
src/codex/accounts/repository.rs	705	账号基础读写、row mapper、pool read model
src/codex/accounts/repository/token.rs	203	token/claims 写入和 refresh_token 保留策略
src/codex/accounts/repository/quota.rs	125	quota JSON、quota cooldown、Cloudflare cooldown
src/codex/accounts/repository/usage.rs	403	usage 累计、window 同步、usage 列表和汇总
src/codex/accounts/repository/lease.rs	51	refresh lease 抢占和释放
src/codex/gateway/transport/websocket.rs	506	WebSocket 对外入口、连接建立、WS -> SSE 编排
src/codex/gateway/transport/websocket/pool.rs	492	WebSocket pool 生命周期、keepalive、GC、shutdown
src/codex/gateway/transport/websocket/codec.rs	206	upstream body 转换、frame/event/error/header 解析
src/codex/serving/dispatch/mod.rs	1013	服务入口、请求编排、上游 request 构造
src/codex/serving/dispatch/audit.rs	329	HTTP SSE/WebSocket stream 审计和账户 slot 释放
src/codex/serving/dispatch/fallback.rs	255	fallback retry 分类和副作用应用
src/codex/serving/dispatch/limits.rs	80	rate-limit header、quota 缓存、window/cooldown 同步
tests/codex_gateway/websocket.rs	880	WebSocket 非 pool 协议场景和共享测试 helper
tests/codex_gateway/websocket/pool.rs	559	WebSocket pool 复用、淘汰、cap、keepalive、shutdown 场景

dispatch/mod.rs 仍然偏大，但当前保留的是请求主流程和上游 request 构造。继续硬拆需要引入额外 context 类型或更复杂的生命周期设计，收益暂时低于风险。

后续观察项

性能优化

目标：只优化有证据的热点。

1. 跑压测或 profile，确认 clone/string 分配是否是瓶颈。
2. 如果 Account clone 是热点，再设计 immutable account snapshot 或 Arc<Account>。
3. 不做无证据的全局 Cow/引用替换。

后续日志治理

本轮只处理审计中确认的日志消息一致性问题，没有重构日志系统。后续如果继续做日志最佳实践，应单独落地 HTTP/span/request_id 字段治理，避免和结构重构混在一起。