Core 最佳实践

基于本项目提供的 core 模块（定位为业务解耦的全局通用工具函数库），以及主打 ESM 优先、纯函数优先、契约显式 的设计理念，在开发和使用本模块内容时推荐遵循以下实践：

依赖检测 API 约定

detectDependencies() 会分别返回：

• dependencies
• devDependencies
• peerDependencies
• optionalDependencies
• addonDeps：dependencies + devDependencies + peerDependencies + optionalDependencies
• runtimeDeps：dependencies + peerDependencies + optionalDependencies
• deps：runtimeDeps + devDependencies

其中：

• addonDeps 适合用于 Vite 插件、测试框架、构建工具等 build-time addon 判断。
• runtimeDeps 适合用于运行时能力判断。
• deps 适合用于更宽泛的“项目是否声明过该包”场景。
• 各依赖字段返回的是浅拷贝快照，调用方修改返回值不会影响后续重新读取的结果。

package.json 读取契约

• readPackageJSON() 在以下情况会显式失败：
  • 文件缺失
  • JSON 解析失败
  • 根结构不是对象
  • 依赖字段存在但不是 Record<string, string> 形态
• 该函数不会静默兼容非法 manifest 结构。

deepClone 支持矩阵

已保证支持：

• Primitive 值透传
• Object
• Array
• Date
• RegExp
• Map
• Set
• Symbol 自有属性
• 循环引用
• 自有属性描述符与原型链保留

显式不支持：

• WeakMap
• WeakSet

未声明兼容保证：

• Promise
• Error
• ArrayBuffer / TypedArray / DataView
• DOM 对象
• 依赖内部槽位的特殊内建对象

1. 坚持纯净的 ESModule

• 标准导入导出模型：内部及外部所有的数据流转和模块引入强制使用现代化的 import / export 语法（拒绝历史遗留的 CommonJS require / module.exports 规范）。在 Node 或者浏览器环境中提供原生的加载效率和支持。
• 消除副作用 (Side-Effects)：保证通用工具代码中除了显式的 export 输出外，不在全局空间中做对象挂载、不主动进行立即执行的初始化副作用。并且要在其对应 package.json 内声明 "sideEffects": false，使得打包器可以放心地静态分析。

2. Tree-Shaking 友好与原子化设计

• 按需打包：基于纯正的 ESM 优势，通过 Vite/Rollup 等构建体系在使用该包时，能够配合做到 Tree-Shaking。开发者在使用时，优先使用具名导入 (import { utilsFn } from '@moluoxixi/core')。
• 保持函数的高内聚、低耦合：每个核心函数都保证单一职责，足够细化和原子化。不包含 UI 逻辑依赖或特定框架上下文。

3. 严格的类型推导与测试机制（Type & Test）

• TypeScript First 设计：作为一个核心函数层，向外部输出必须拥有准确的数据结构定义和泛型推导机制，以在编译态拦截不合理的函数调用。
• 用例覆盖 (Coverage)：由于它是下沉到最底部的基础设施，每一次函数加入都应该有对应的单元测试覆盖边界情况，保证整个应用生态的稳定性。