跳到正文

我所理解的 JavaScript 最佳实践(20):会演进的函数用对象参数

我所理解的 JavaScript 最佳实践

  1. 使用现代化工具
  2. 尽量去掉只用一次的中间变量
  3. 遍历的起点决定按 ID 取数的顺序
  4. 不用 reduce
  5. 按遍历任务选择循环和数组方法
  6. 异步遍历按任务依赖选择并发或串行
  7. 卫语句让主流程保持平直
  8. 用函数给可复用的业务规则命名
  9. 让顺序无关的代码按名称排列
  10. 正确写注释
  11. 一行代码只做一件事
  12. 给函数起合适的名字
  13. 用空值合并运算符更好地控制默认值生效逻辑
  14. 用队列串行处理偏好更新,避免修改互相覆盖
  15. 确认弹窗关闭时,让等待中的 Promise 得到结果
  16. 用独立的预期值捕获实现错误
  17. 控制文件行数
  18. 控制函数圈复杂度和认知复杂度
  19. 使用工具函数进行类型判断
  20. 会演进的函数用对象参数(当前)
  21. 使用改进的原生 API
  22. 使用模板字符串优化多行文字展示
  23. 用查表取值,用 switch 分派动作
  24. 正确使用纯函数和副作用
  25. 避免数组空位
  26. 把条件写在可选元素和字段旁边
  27. 让独立条件各自表达

订单列表要加一个「显示已取消」筛选项。打开页面,找到 loadOrders(userId, true, 5000)。第二个参数是「包含已取消」还是「只查已取消」?第三个参数是超时还是条数上限?即使知道函数叫 loadOrders,也得跳到定义里才能确认这次请求的含义。

把布尔值的含义和数字的单位写在调用处

const orders = await loadOrders({
  accountId,
  includeCanceled: true,
  timeoutMs: 5000,
});

accountId 说明订单归属哪个账号,includeCanceled 说明打开了什么行为,timeoutMs 说明数字以毫秒为单位。改筛选条件时,可以只看这段调用就知道它会影响哪一项。业务函数即使暂时只接收一个参数,如果下一步已经有独立的配置要加,我也会优先给它一个有名字的字段。

加一个可选项时,旧调用可以沿用

订单列表接着要支持翻页,只有加载下一页时才传 cursor。

const nextPage = await loadOrders({
  accountId,
  cursor: nextCursor,
  includeCanceled: true,
  timeoutMs: 5000,
});

已有调用可以省略 cursor,前提是省略它仍然请求第一页,其他选项的默认行为也保持一致。以后若把某个字段改成必填,或让省略 includeCanceled 的含义变化,就得检查旧调用。字段有名字,只解决了参数如何表达和组合的问题。false、空字符串和缺省值各代表什么,仍由函数的契约决定。见《用空值合并运算符更好地控制默认值生效逻辑》。

Vue composable 和 React Hook 用一个对象接收依赖

侧栏调宽需要两样东西。一个是当前外观中保存的宽度,另一个是提交新宽度的动作。以前 Marker 在调用 useSidebarWidth() 时传了两个函数,扫一眼签名还要判断哪个只是读值。现在调用处把这两种依赖分开写。

// 侧栏持续读取当前外观中已保存的宽度。
const preferredSidebarWidth = computed(() => appearance.value.sidebarWidth);
const { sidebarWidth, startSidebarDrag } = useSidebarWidth({ preferredSidebarWidth, saveSidebarWidth });

preferredSidebarWidth 随外观更新,composable 在计算当前宽度时读取它。saveSidebarWidth 只在完成一次拖动或键盘调宽时调用。派生值和保存动作各有名字,调用处就能用对象简写接线。React Hook 也可以传当前 render 得到的派生值和具名动作。组件内给函数起名只改变代码的组织位置。需要跨 render 保持同一引用时,再按订阅或缓存契约决定是否用 React 的 useCallback。

自有 composable 或 Hook 即使只需要一个依赖,也可以先给它命名。有额外配置时就加字段。没有外部依赖时,直接写 useReadingViews() 就够了。共享预设里的 @sheng/project-require-hook-options 检查自有组合函数的定义与可辨认的调用,框架内置函数沿用各自的签名。

下游只接收用到的返回字段

工作台的「刷新」命令只需要知道当前有没有打开文档。从 useReadingViews() 解构出 current,再把它传给命令 composable,调用处就写明了这个依赖。阅读标签的新增、移除和历史管理仍留在原来的模块。以后给标签增加一个动作,命令 composable 的参数也无需跟着变化。

如果把 useReadingViews() 的返回值整个传入,即使给参数标了 Pick<ReturnType<typeof useReadingViews>, 'current'>,调用时传的仍是同一个 JavaScript 对象。真正缩小依赖需要选出字段,定义侧的 Params 也逐项声明下游需要的值和动作。像 current 这样的 ref 或一个完整的文档快照,本身就可以作为一个选项传递。

共享预设的 @sheng/project-prefer-named-hook-bindings 会在确认来源是自有组合函数的对象返回值时,提示把整份透传改为逐项接线。

独立 Vue composable 用 Params 声明本地入参

把十来个字段的对象类型内联在函数签名里,同一组字段会先出现在解构中,再出现在类型里。这个 composable 独有的字段可以用同文件的 interface Params 集中声明,函数入口只留下解构和 : Params。某项依赖的用途也可以写在对应字段旁。

// 侧栏调宽需要已保存的宽度偏好,以及提交新宽度的动作。
interface Params {
  // 已保存的侧栏宽度,单位为 CSS 像素,空值使用默认宽度。
  preferredSidebarWidth: ComputedRef<number | null>;
  // 拖动完成后持久化侧栏宽度。
  saveSidebarWidth: (width: number) => void;
}

这个类型留在 use-sidebar-width.ts,所以 Params 的归属由文件和函数一起说明。多个模块确实共用一个上下文时,共享类型继续用能表达业务含义的名称。共享预设用 @sheng/project-require-hook-options 检查独立 Vue composable 的本地入参声明,再由 @sheng/ts-require-definition-comment 检查接口及每个直属字段的说明。

自有字段在定义和调用处使用同一个名字

侧栏原先返回通用的 width,工作台还要写一遍 width: sidebarWidth 才能让后面的模板读懂。批注草稿的选项也有过 maxWidth: noteCardMaxWidth。既然这些接口由项目自己维护,而且字段表示的是同一个值,就让 sidebarWidth 和 noteCardMaxWidth 分别贯穿定义与调用。搜索一个名字便能看清它从哪里来、传给了谁。第三方 Hook 的字段遵循库的公开契约,同一 Hook 的多个实例也可以用各自的结果对象区分。

Vue 子组件需要处理同名 prop 时,两个名字分别对应原始输入和派生值。下面左侧的 width 是 prop 的键,widthFromProps 是本地绑定。子组件后续都用 width 表示处理后的宽度,原始 prop 的变化仍能通过 Vue 的 toRefs 传进来。

const { width: widthFromProps } = toRefs(props);
const width = computed(() => normalizeWidth(widthFromProps.value));

共享预设的 @sheng/project-prefer-named-hook-bindings 检查自有组合函数的内联回调和直属字段换名。改名要同步选项类型、实现、调用和测试,Lint 提示后由维护者确认契约。调用处为什么值得保留只用一次的函数名,见《尽量去掉只用一次的中间变量》。

结果也会长出独立字段

只返回订单时,数组就够了。分页入口还要交付下一页游标,可以从一开始就返回 { orders, nextCursor },让列表解构 orders,翻页逻辑再读取 nextCursor。以后结果里添加新字段,已有的解构通常可以原样使用。已被调用方当成数组的旧 API 则需要明确迁移,因为 .map()、下标访问和直接传递数组都依赖原来的返回形状。

位置参数也有合适的场景。clamp(value, min, max) 的顺序能表达数值与上下界的关系。业务入口里的几项输入若各自有含义、可以独立省略,而且接下来还会增加,字段名能省去更多猜测。对象里的字段多到需要来回对照时,可以让签名、解构和调用沿用同一排列。见《让顺序无关的代码按名称排列》。