TinyBase 函数参数优化：从位置参数到对象解构的演进

在 JavaScript/TypeScript 生态中，函数参数的设计直接影响着开发者的使用体验。本文将以 TinyBase 项目中的 useSortedRowIds 函数为例，探讨如何通过引入对象解构参数来优化 API 设计，提升代码的可读性和可维护性。

传统位置参数的问题

TinyBase 是一个轻量级的客户端状态管理库，其 useSortedRowIds 函数原本采用传统的位置参数设计：

useSortedRowIds(
  tableId: string,
  cellId?: string,
  descending?: boolean,
  offset?: number,
  limit?: number,
  storeOrStoreId?: StoreOrStoreId,
): Ids

这种设计存在几个明显问题：

1. 参数顺序依赖性强：开发者必须记住每个可选参数的位置
2. 可读性差：调用时难以直观理解每个参数的含义
3. 灵活性不足：当只需要指定后面的可选参数时，仍需为前面的参数传递 undefined

对象解构方案的优势

通过引入对象解构参数，我们可以将函数改造为：

useSortedRowIds({
  tableId: string,
  cellId?: string,
  descending?: boolean,
  offset?: number,
  limit?: number,
  storeOrStoreId?: StoreOrStoreId,
}): Ids

这种设计带来了多方面改进：

1. 自文档化：每个参数的用途通过属性名一目了然
2. 参数顺序无关：可以按任意顺序指定参数
3. 选择性参数：只需提供必要的参数，无需占位符
4. 类型安全：TypeScript 能提供更好的类型检查和自动补全

实现策略

在 TinyBase 的实现中，可以采用渐进式增强策略：

1. 函数重载：同时支持新旧两种调用方式，保持向后兼容
2. 参数归一化：内部将两种参数格式统一处理
3. 类型定义优化：提供完善的类型提示

示例实现：

function useSortedRowIds(...args: [ParamsObject] | [string, string?, boolean?, number?, number?, StoreOrStoreId?]): Ids {
  const params = typeof args[0] === 'object' ? args[0] : {
    tableId: args[0],
    cellId: args[1],
    descending: args[2],
    offset: args[3],
    limit: args[4],
    storeOrStoreId: args[5],
  };
  // ...原有逻辑
}

开发者收益

这种改进为 TinyBase 用户带来显著好处：

1. 代码更简洁：无需为不关心的参数传递 undefined
2. 维护更方便：参数变更不会影响已有调用
3. 团队协作更高效：代码可读性提升，减少沟通成本
4. IDE 支持更好：现代编辑器能提供更好的参数提示

最佳实践建议

在使用改进后的 API 时，建议：

1. 新项目优先使用对象参数形式
2. 大型项目逐步迁移到新形式
3. 公共库或共享代码保持一致性
4. 利用 TypeScript 类型定义获得最佳开发体验

这种参数设计模式不仅适用于 TinyBase，也可作为其他 JavaScript/TypeScript 库 API 设计的参考范例，体现了现代前端开发中对开发者体验的重视。