SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场code-quality

code-quality

编程与开发

查看项目

更新于 10-15 16:54

技能介绍

用途

code-quality 是编码和重构时的质量约束技能，作为代码质量 SSOT，目标是确保代码可维护、可测试、适度扩展。它适用于用户正在编写新代码或重构现有代码、需要 Code Review 检查清单，或提到 MTE 原则、代码质量、命名、注释、避免过度设计等场景。系统性重构执行建议使用 refactor。

核心原则：MTE

所有代码必须遵循 MTE 原则：

  • Maintainability（可维护性）：职责单一、依赖清晰、命名/注释/日志/错误处理合规、易于理解。
  • Testability（可测试性）：核心逻辑可单元测试、依赖可 Mock。
  • Extensibility（可扩展性）：预留合理扩展点、接口抽象。

核心阈值表

全仓唯一权威阈值源。谓词语义统一：≤ 建议值 = 合规；> 建议值且 ≤ 最大值 = [Suggestion]；> 最大值 = [Blocker]；无建议值的指标（重复代码 / 单类行数）只有两档——≤ 最大值 = 合规，> 最大值 = [Blocker]。

指标 建议值 最大值 超最大值的重构方向
函数长度 30 行 50 行 提取函数
参数数量 3 个 5 个 参数对象
嵌套深度 2 层 3 层 早返回、提取函数
重复代码 — 3 处（Rule of Three） 提取公共逻辑（<3 处禁止提前抽象）
单类/单文件行数 — 500 行 拆分职责（上帝类）

模块设计

单一职责：一个类/函数只做一件事（UserService 业务 / UserRepository 数据访问 / UserValidator 校验分开；反例：UserManager 全包）。

依赖方向：外层依赖内层（Interface → Service → Domain → Infrastructure）；依赖接口，不依赖实现。

命名规范

总原则：精确优先（减长度靠删冗词，禁止截短单词）；调用点清晰（名字在调用处读起来像自然短语）；项目一致性（同概念同名，沿用项目既有大小写惯例，引入新名词前先 grep 项目既有词表）。

分类规则：

  • 类/接口：名词短语，描述角色而非实现；禁 Manager/Helper/Util/Processor/Info/Data 等空泛后缀收尾。
  • 方法/函数：有副作用用动词短语、纯查询用名词；全库同一动作只用一个动词；get* 禁副作用。
  • 变量：长度与作用域成正比；导出符号默认 ≥2 词自含上下文。
  • 布尔：读作断言（isEmpty/hasChildren/canEdit）；is*/has* 必须返回布尔；禁否定式名。
  • 常量：魔法数字按含义命名（MAX_RETRIES 而非 FIVE）。

接口/协议命名细则：能力型用 -able/-ible 后缀（Comparable、Iterable、Closeable）；单方法接口（Go 惯例）用动作 + -er（Reader、Formatter）；角色型用名词短语（Repository、PaymentGateway）；禁 I 前缀（IFoo）等类型编码，除非项目既有惯例。业务抽象接口不暴露可替换实现技术（UserRepository 而非 MySQLUserRepoInterface，禁 Impl 后缀）。

命名黑名单（本次 diff 新增/修改命中即 [Blocker]；存量未触碰为 [Suggestion]）：误导名、泛化名作完整名、同概念多名漂移、类型编码、不可发音自造缩写均为 [Blocker]；无意义区分、大作用域单字母为 [Suggestion]。

注释规范

信息归宿三分法：源码注释 = 面向未来读者的稳定事实；commit message = 本轮变更说明；traceability/任务文档 = 过程追溯。注释唯一合法用途是承载代码无法表达的信息。

白名单：公共契约、非显然 why、不变量/风险约束、复杂 what + 出处、抑制类、临时脚手架（仅限 S2/S3 骨架阶段）。

黑名单：变更日志式、对审查者说话、来源记录式/注释式追溯、复述代码、注释掉的代码、过量注释。

分级：[Blocker] 为本次 diff 新增/修改黑名单注释、抑制类注释无理由、S4/S6/S7 后残留骨架脚手架注释、注释与代码当前语义不符；[Suggestion] 为存量坏注释、public API 缺契约注释。

日志规范

日志唯一目标是让线上失败被快速排查 / 审计 / 观测。六条硬规则：目的门槛、级别纪律、最小上下文、异常纪律、安全红线、事实优先。

级别准入：ERROR 为当前请求/任务/事务失败，用户或系统可感知；WARN 为异常但已处理、系统可继续；INFO 为低频且长期有价值的里程碑；DEBUG/TRACE 为默认生产关闭的诊断细节。

分级：[Blocker] 为本次 diff 新增/修改命中安全红线、log-and-throw 重复堆栈 / 吞异常只 log、把推测写成事实；[Suggestion] 为级别误用、上下文不足、占位日志、存量坏日志。

不写死（留给项目规范）：日志格式、字段大小写、每业务事件清单、采样率、保留周期、脱敏或截断后的 SQL/HTTP payload 策略。

错误处理（编码级）

不吞异常；保留 cause；错误有语义；边界 fail-fast；对外不泄露内部；可恢复 vs 不可恢复分流。分级：吞异常 / 丢 cause / 对外泄露内部 = [Blocker]；其余为 [Suggestion]。

安全编码红线

输入不可信；鉴权在服务端；密钥与敏感数据不硬编码、不入日志、不进版本库；最小权限；错误信息不泄露；依赖安全。

类型与数据契约

外部数据先校验为领域类型/形状再入域；null / optional 显式建模；避免 stringly-typed；不绕编译器；DTO 与 domain 分离。分级：stringly-typed、为绕编译器滥用宽类型、类型/形状校验缺失 = [Suggestion]。

状态与副作用

核心逻辑优先纯函数；副作用集中边界；共享可变状态须有主；异步须善后。

设计原则（代码级）

SRP 单一职责、OCP 开闭、LSP 里氏替换、LoD 迪米特、ISP 接口隔离、DIP 依赖倒置。分级：DIP 违反为 [Blocker]；其余五条为 [Suggestion]。

可测试性设计

可测试代码三要素：依赖可注入、纯函数优先、边界分离。

避免过度设计

YAGNI；Rule of Three（3 个以上实现才建接口，例外：跨模块边界 / 外部依赖 / 可测试性边界）；简单方案优先。

设计模式使用

必要时才用；说明理由；保持一致。

重构指导

安全约束：重构前必须有测试覆盖；每步重构后运行测试，小步前进；不在重构中添加新功能，不在添加功能时重构；单次重构只改一类问题。系统性重构工作流用 /refactor。

Code Review

反馈分级：[Blocker] 必须修复才能合并；[Suggestion] 建议修改但不阻塞；[Question] 需要作者解释；[Nice] 写得好的地方。

最小审查清单涵盖核心阈值表、命名、注释、设计原则、依赖注入、过度设计、错误处理、类型与数据契约、日志、安全编码红线。反馈必须分级并说明理由；安全问题必须 [Blocker]。

参考资料

  • references/mte-examples.md：模块/函数/可测试性/YAGNI 正反例代码
  • references/naming-examples.md：命名正反例、大小写惯例、命名空间例外
  • references/refactor-signals.md：Code Smells 信号、重构流程、风险评估
  • references/review-rubric.md：Review 详细清单与输出格式