ssot-reuse:一处定义,处处引用
何时用
准备写 const / def / class / interface / 配置项,或复制粘贴一段代码时。
硬规则
- MUST 新增定义前搜索代码库:同名、同义、同结构。找到就引用,不新建。
- NEVER 同一事实存在于两处(常量、枚举值、URL、schema、业务规则);第二处必须引用第一处。
- MUST 相似代码出现第二次即抽象。
- MUST 新方法先问"接口还是一次性用法":会被两处以上调用的定义为接口(明确输入、输出、错误),不写调用方专用逻辑。
- NEVER 用复制加小改代替参数化。
- MUST 抽象后删除原重复,不留旧版本;新结构里值得完全理解的部分指出位置。
审问清单
- 这个名字 / 值 / 结构已经有了吗?搜过哪些关键词?
- 它属于哪一层?放进那层的现有模块还是新建?
- 两个相似函数的差异能否变成参数?
- 这是接口(稳定契约)还是实现细节(可随时改)?
- 删掉重复后,谁还依赖旧位置?
反模式
- 错误:
MAX_RETRY = 3在三个文件各写一遍。→ 正确:config.MAX_RETRY一处定义,其余引用。 - 错误:
fetchUserById、fetchUserByEmail各自拼查询、各自处理错误。→ 正确:fetchUser(where)一个接口,调用方传条件。 - 错误:接口返回类型在前端、后端、文档各手写一份。→ 正确:schema 单一来源(OpenAPI / zod / pydantic),其余生成。
输出要求
新增定义时说明:搜了什么、为何无可复用项、放在哪一层。抽象时列出被替换的重复位置。