函数设计与实现指南

欢迎参与 Dora Pocket 的代码贡献！本指南旨在为所有函数的设计与实现提供一套统一的、高质量的标准。遵循这些规范，将有助于我们共同维护一个稳定、可预测且易于维护的代码库。

核心设计哲学

在编写任何代码之前，请理解并遵循以下核心哲学：

• @esdora/kit 的纯粹性： kit 包是整个生态的基石，必须严格遵守零依赖原则。任何需要外部依赖的功能，都应考虑创建一个新的独立包。
• 不重复造轮子（但有例外）： 优先考虑社区中经过战斗考验的优秀库。但如果所需功能非常小且稳定，可以考虑“供应商化 (Vendoring)”以保持 kit 的纯粹性。
• 用户体验优先： API 的设计应力求直观、易用，并提供清晰的错误提示。

目录结构规范

函数的存放位置取决于其稳定性和功能分类。

• 稳定函数： 存放于 src/<category>/ 目录下。例如，一个稳定的函数工具应放在 src/function/。
• 实验性函数： 必须存放于顶级的 src/experimental/ 目录下。这能从物理上将它们与稳定代码隔离。

API 稳定性与生命周期管理

我们通过一套明确的机制来管理 API 的稳定性。

1. 实验性 API (@experimental)

对于任何不确定或未来可能变更的 API，必须遵循以下所有规则：

• 存放位置： 必须位于 src/experimental/ 目录下。
• 命名约定： 函数名必须加上 _unstable_ 前缀，例如 _unstable_deepSort。
• TSDoc 注释： 必须在 TSDoc 中添加 @experimental 标签，并明确说明其不稳定性。
• 导出方式： 只能从专门的实验性入口（如 @esdora/kit/experimental）导出。

2. API 的“毕业”

当一个实验性 API 经过充分测试和社区反馈，准备成为稳定版时，需要执行以下步骤：

1. 移动目录： 将其从 src/experimental/ 移动到合适的稳定分类目录。
2. 重构代码： 移除函数名的 _unstable_ 前缀。
3. 更新注释： 移除 @experimental 标签，并更新 TSDoc 为正式文档。
4. 更新导出： 将其从稳定入口（如 @esdora/kit）导出。
5. 记录变更： 在 CHANGELOG 中将此变动标记为新功能 (feat)。

TSDoc 注释规范

高质量的 TSDoc 注释是代码不可或缺的一部分。

• 职责分离原则：
  • 简单函数： 在函数声明上方编写一个完整的、详尽的注释块。
  • 带重载的函数：
    • 在每个重载签名上方，编写简洁的注释（摘要、@param, @returns），服务于 IDE 的智能提示。
    • 在实现签名上方，编写最详尽的注释（@remarks, @example 等），作为技术底稿和文档源。
• 语言： 所有 TSDoc 注释都推荐使用中文编写。
• 示例为王 (@example)： 必须为公开的 API 提供清晰、可运行的示例。

依赖管理策略

• @esdora/kit: 严禁添加任何 dependencies。
• 功能扩展： 当需要集成第三方库时（如颜色转换库 color），应创建一个新的、专注的独立包（如 @esdora/color），并在其中管理依赖。
• 元包 esdora:
  • esdora 包作为所有功能的统一入口。
  • 它通过命名空间导出的方式 (import * as kit from '@esdora/kit') 来聚合所有子包，以避免命名冲突并保持 API 结构清晰。