我所理解的 JavaScript 最佳实践(20):会演进的函数用对象参数
- 使用现代化工具
- 尽量去掉只用一次的中间变量
- 遍历的起点决定按 ID 取数的顺序
- 不用 reduce
- 按遍历任务选择循环和数组方法
- 异步遍历按任务依赖选择并发或串行
- 卫语句让主流程保持平直
- 用函数给可复用的业务规则命名
- 让顺序无关的代码按名称排列
- 正确写注释
- 一行代码只做一件事
- 给函数起合适的名字
- 用空值合并运算符更好地控制默认值生效逻辑
- 用队列串行处理偏好更新,避免修改互相覆盖
- 确认弹窗关闭时,让等待中的 Promise 得到结果
- 用独立的预期值捕获实现错误
- 控制文件行数
- 控制函数圈复杂度和认知复杂度
- 使用工具函数进行类型判断
- 会演进的函数用对象参数(当前)
- 使用改进的原生 API
- 使用模板字符串优化多行文字展示
- 用查表取值,用 switch 分派动作
- 正确使用纯函数和副作用
- 避免数组空位
- 把条件写在可选元素和字段旁边
- 让独立条件各自表达
订单列表要加一个「显示已取消」筛选项。打开页面,找到 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) 的顺序能表达数值与上下界的关系。业务入口里的几项输入若各自有含义、可以独立省略,而且接下来还会增加,字段名能省去更多猜测。对象里的字段多到需要来回对照时,可以让签名、解构和调用沿用同一排列。见《让顺序无关的代码按名称排列》。