依赖复用优先开发规范

在实现新功能前，先做一次可复用依赖调研。只有在现成方案不合适时才自研。目标是减少重复造轮子、降低维护成本，并让实现建立在当前生态已经验证过的能力之上。

核心原则

• 先查现成方案，再写自定义实现。
• 优先级默认是：标准库或平台内置能力 -> 官方 SDK -> 仓库里已存在的依赖或内部包 -> 主流社区库 -> 自研。
• 不要凭记忆断言某个包“很流行”或“没人维护”；需要用当前注册表、官方文档、源码仓库和发布记录验证。
• 自定义代码只保留在业务差异化部分、适配层或确实没有合适现成方案的场景里。

标准流程

1. 拆清需求边界。

   • 写清目标能力、输入输出、运行环境、性能约束、安全和合规要求、是否允许新增依赖。
   • 区分哪些是通用基础能力，哪些才是业务独特逻辑。

2. 枚举候选复用路径。

   • 先看标准库、框架内置能力和云平台原生能力。
   • 再看项目当前已经安装的依赖、monorepo 内部包、团队已有基础设施。
   • 再查当前生态里的官方 SDK 与主流社区包。
   • 尽量形成 2 到 5 个候选；如果一个都找不到，再说明为什么需要自研。

3. 用统一标准筛选候选。

   • 评估采用度：下载量、依赖方数量、GitHub 活跃度、文档和社区讨论热度。
   • 评估维护度：最近发布时间、变更日志、issue/PR 活跃度、维护者是否稳定。
   • 评估兼容性：语言和运行时版本、框架版本、模块系统、浏览器或服务端环境、类型支持、打包体积、原生依赖。
   • 评估风险：许可证、已知安全问题、传递依赖复杂度、API 稳定性、锁定风险。
   • 评估集成成本：学习成本、迁移成本、适配工作量、是否需要大面积侵入现有代码。

4. 做出依赖还是自研的决策。

   • 优先选择满足需求的最小可行依赖，不要因为功能“大而全”就默认引入重型方案。
   • 如果多个候选都可用，优先选择文档清晰、社区稳定、与当前栈兼容性更好的方案。
   • 如果决定自研，明确写出放弃现成依赖的原因，不要只写“更灵活”或“更可控”这种空话。

5. 以可替换方式落地。

   • 把第三方依赖隔离在薄适配层后面，不要把外部 API 直接散落到整个代码库。
   • 遵循仓库现有的包管理、版本声明和锁文件规范。
   • 为适配层和关键集成路径补测试，验证最小成功路径和主要失败路径。

6. 在编码前给出简短结论。

   • 说明推荐采用的依赖或平台能力。
   • 说明至少一个备选方案以及不选它的原因。
   • 说明哪些部分复用依赖，哪些部分仍然需要自己实现。

允许自研的常见条件

• 没有活跃维护且兼容当前栈的现成方案。
• 现成方案的许可证、安全要求或合规要求不满足约束。
• 引入依赖的体积、复杂度或运行时开销明显高于收益。
• 需求本身是业务核心差异化能力，通用库只能覆盖很小一部分。
• 平台原生能力加一层很薄的封装就足够，没有必要再加第三方依赖。

避免的反模式

• 不要因为“实现起来很快”就忽略依赖调研。
• 不要在没有对比现有依赖的情况下再引入同类库，导致能力重叠。
• 不要只看 star 数；长期不发版、issue 堆积或兼容性差的包同样不应引入。
• 不要把短期 PoC 用的实验性依赖直接扩散到正式实现里。
• 不要把“以后也许用得到”当作引入大型依赖的理由。

默认输出格式

在开始编码前，先给出一个简短结论，至少覆盖以下内容：

• 需求拆解：哪些是通用能力，哪些是业务逻辑。
• 候选依赖：列出 2 到 5 个方案。
• 推荐方案：说明为什么选它。
• 放弃理由：说明为什么不选其他方案或为什么最终自研。
• 落地边界：哪些代码交给依赖，哪些代码自己写。

生态补充检查

按当前语言或平台读取 references/ecosystem-sources.md，再补充对应生态的检查点与资料来源。