wk-backend/codestable/refactors/2026-04-25-backend-cleanup/2026-04-25-backend-cleanup-scan.md

doc_type, refactor, status, scope, summary

doc_type	refactor	status	scope	summary
refactor-scan	2026-04-25-backend-cleanup	pending-user-selection	后端 Go 代码全部（internal/、pkg/、cmd/），21 文件 ~2485 行	发现 12 条优化点：结构 4 / 性能 3 / 可读性 5，按风险：低 7 / 中 4 / 高 1

backend-cleanup scan

总览

• 扫描范围：后端 Go 代码全部（internal/ckwk、internal/conf、internal/dto、internal/handler、internal/middleware、internal/router、internal/schedule、pkg/common、pkg/log、pkg/request、cmd/），21 文件 ~2485 行
• 发现 12 条优化点：结构 4 / 性能 3 / 可读性 5
• 按风险：低 7 / 中 4 / 高 1
• 建议先做：#1 #2 #3 #5 #6 #7 #10（低风险、纯提取、AI 可用 go vet 自证）
• 建议慎做 / 后做：#8（改并发原语需测试）、#11（跨模块分层需 architecture 同步）
• 前置检查 7 条：第 2 条命中（测试覆盖率为 0），但本次条目多为纯机械提取不改变控制流，风险可控；第 8 条改锁策略为中风险，建议补测试后再做

条目

#1 提取 handler 中 wk_instance 获取的重复代码 ✓

• 位置：internal/handler/ckwk.go:68-74, 98-103, 124-129, 143-148, 170-175
• 分类：结构
• 现状：5 个 handler 方法开头都有相同的 ctx.Get("wk_instance") + 类型断言 + 错误响应，每处 4-5 行
• 问题：同一段代码重复 5 次（25 行→5 行），任何一处错误响应格式变了要改 5 处
• 建议：提取 getWKFromContext(ctx *gin.Context) (*ckwk.WK, bool) 函数，返回 (wk, ok)，调用方统一处理
• 建议映射的方法：M-L2-01（提取函数）
• 风险：低（纯提取，不改变控制流）
• 验证：AI 自证（go vet + go build）
• 范围：约 20 行 / 1 文件

#2 提取验证码重试逻辑为独立函数 ✓

• 位置：internal/ckwk/api.go:159-169, 407-417
• 分类：结构
• 现状：Login() 和 performStudy() 各有一段完全相同的 3 次验证码获取重试循环，含相同的错误日志和"以达到最大重试次数"提示
• 问题：同一段逻辑重复 2 次（14 行×2），且重试次数硬编码在两处；typo "以达到" 在两处都存在
• 建议：提取 retryCode(wk *WK, maxRetries int) (string, error) 函数，Login 和 performStudy 调用它
• 建议映射的方法：M-L2-01（提取函数）
• 风险：低（纯提取，控制流等价）
• 验证：AI 自证（go vet + go build）
• 范围：约 14 行 / 1 文件

#3 提取 SessionManager 的 removeSession 内部方法 ✓

• 位置：internal/ckwk/session_manager.go:97-108, 143-155, 165-177
• 分类：结构
• 现状：Del()、ClearAll()、ClearExpired() 三个方法共享相同逻辑：cancel context → 构建 userKey → 删两个 map → 记日志
• 问题：同一段逻辑重复 3 次（约 8 行×3），任一处 cleanup 逻辑变了要改 3 处
• 建议：提取 removeSession(sessionID string, item SessionItem) 内部方法，三个调用方统一使用
• 建议映射的方法：M-L2-01（提取函数）
• 风险：低（纯提取，不改变控制流）
• 验证：AI 自证（go vet + go build）
• 范围：约 16 行 / 1 文件

#4 提取 userKey 构造为 WK 方法 ✓

• 位置：internal/ckwk/session_manager.go:37, 98, 149, 171
• 分类：可读性
• 现状：wk.Host + ":" + wk.Username 或 item.Instance.Host + ":" + item.Instance.Username 在 4 处手动拼接
• 问题：相同的 key 构造逻辑散布 4 处，如果 key 格式变了要改 4 处；且语义不明确（读代码时不确定 key 是什么格式）
• 建议：在 WK 上添加 UserKey() string 方法返回 wk.Host + ":" + wk.Username，SessionManager 内部统一调用
• 建议映射的方法：M-L2-03（提取变量/查询）
• 风险：低（纯提取，字符串拼接等价）
• 验证：AI 自证（go vet + go build）
• 范围：约 4 行 / 2 文件（session_manager.go + api.go）

#5 SessionManager.Get() 用写锁做读操作 ✓

• 位置：internal/ckwk/session_manager.go:80-91
• 分类：性能
• 现状：Get() 使用 m.mu.Lock()（写锁），但主要操作是读取 session，只更新了 LastValue 字段
• 问题：写锁使所有读操作串行化，在并发请求下成为瓶颈；KeepAlive goroutine 每 2 分钟读一次 + 高频 API 调用读一次，全部互斥
• 建议：改为 RLock 读 + CAS 更新 LastValue，或用 RLock 检查存在性后只在需要更新时加写锁
• 建议映射的方法：M-L4-01（优化锁粒度）
• 风险：低（锁策略改变但语义等价：LastValue 更新丢失不影响正确性，只是保活时间戳偶尔不准）
• 验证：AI 自证（go vet + go build + 并发场景手动确认无死锁）
• 范围：约 8 行 / 1 文件

#6 GetRecords 递归分页改为迭代 ✓

• 位置：internal/ckwk/resp.go:79-92
• 分类：性能
• 现状：GetRecords 在分页获取时递归调用自身 GetRecords[T](wk, rType, courseID, nextPage)
• 问题：如果课程有大量分页（>100 页），递归深度会很大；Go 没有尾调用优化，每层递归占用栈帧；极端情况栈溢出
• 建议：改为 for 循环迭代，逐页追加到 result.List
• 建议映射的方法：M-L2-01（提取函数，改为迭代实现）
• 风险：低（行为等价，输入输出不变）
• 验证：AI 自证（go vet + go build）
• 范围：约 15 行 / 1 文件

#7 prepareRequestClient 不应每次请求都重建配置 ✓

• 位置：internal/ckwk/api.go:89-113
• 分类：性能
• 现状：每次调用 newRequest() 都调用 prepareRequestClient()，重建 Config 对象、解析代理 URL、创建 Transport、设置 Cookie
• 问题：每次 HTTP 请求都重建配置是冗余的（debug 设置在运行期间极少变化）；Transport 创建涉及 TLS 配置，开销不低
• 建议：只在 debug 配置变更时重建配置（可加一个 dirty flag 或在 UpdateDebugConfig 时触发），或缓存 Config 只在参数变化时重建
• 建议映射的方法：M-L4-01（缓存/延迟计算）
• 风险：中（改变了"何时重建配置"的语义，需要确保 debug 开关切换时能立即生效）
• 验证：AI 自证（go vet + go build）+ HUMAN（切换 debug 开关后确认代理/SSL 行为生效）
• 范围：约 20 行 / 1 文件

#8 schedule.go 时区和 cron 表达式不一致 ✓

• 位置：internal/schedule/schedule.go:14, 21
• 分类：可读性
• 现状：时区设为 Asia/Singapore，但 cron 表达式是 0 2 * * *（凌晨 2 点新加坡时间），注释写"每天 6 点执行"
• 问题：注释和代码不一致——如果意图是北京时间 6 点，时区应为 Asia/Shanghai；如果意图是新加坡时间凌晨 2 点清理，注释错误
• 建议：根据业务意图统一：改为 Asia/Shanghai + 0 6 * * *（北京时间 6 点），或改为 Asia/Singapore + 更新注释
• 建议映射的方法：M-L2-03（修正不一致）
• 风险：低（修注释+时区或修 cron 表达式，行为由用户确认意图后决定）
• 验证：HUMAN（确认业务意图：是北京时间 6 点还是其他？）
• 范围：约 2 行 / 1 文件

#9 错误信息 typo "以达到" → "已达到" ✓

• 位置：internal/ckwk/api.go:168, 416
• 分类：可读性
• 现状：两处错误信息写"以达到最大重试次数"，应为"已达到"（"已经达到"的缩写）
• 问题：错别字，影响用户看到的错误提示
• 建议：改为"已达到最大重试次数"
• 建议映射的方法：M-L2-03（修正）
• 风险：低（只改字符串字面量）
• 验证：AI 自证（go build）
• 范围：约 2 行 / 1 文件

#10 删除未使用的 QAList struct ✓

• 位置：internal/ckwk/types.go:52
• 分类：可读性
• 现状：type QAList struct{} 声明但从未使用
• 问题：死代码，增加阅读负担，可能误导后续开发者以为有 QA 功能
• 建议：删除
• 建议映射的方法：M-L2-02（内联/删除空壳）
• 风险：低（无引用）
• 验证：AI 自证（go build 无编译错误）
• 范围：约 3 行 / 1 文件

#11 Handler 层业务逻辑下沉到 Service 层 ✗

• 位置：internal/handler/ckwk.go 全文
• 分类：结构
• 现状：Login() handler 包含 Cookie 构造、WK 实例创建、登录流程编排、Session 存储；AllRecord() handler 包含分页归一化、按类型分发、响应组装
• 问题：Handler 承担了业务逻辑（Login 45 行、AllRecord 60 行），违反分层原则，难以对业务逻辑做单元测试
• 建议：提取 Service 层，Handler 只做参数绑定→调用 Service→组装响应
• 建议映射的方法：M-L3-04（服务层抽取）
• 风险：高（跨多文件、改公开接口、需要 Parallel Change）
• 验证：HUMAN（功能验证）
• 范围：约 100+ 行 / 3+ 文件

#12 bufferHub.append 切片内存泄漏 ✓

• 位置：pkg/log/buffer.go:59
• 分类：性能
• 现状：h.entries = append(h.entries[1:], entry) 在超过 limit 时用 re-slice 淘汰旧条目，但底层数组仍持有对被淘汰 Entry 的引用，阻止 GC 回收
• 问题：环形缓冲区每淘汰一条，底层 array 就泄漏一个 Entry 大小的内存，长期运行后会缓慢增长
• 建议：淘汰时将被移除的位置显式置 nil：h.entries[0] = Entry{} 后再 re-slice，或改用环形索引实现避免 re-slice
• 建议映射的方法：M-L4-01（修复内存泄漏）
• 风险：低（行为等价，只影响 GC 行为）
• 验证：AI 自证（go vet + go build）
• 范围：约 3 行 / 1 文件