typescript-functions

函数

在当前任务中应用 TypeScript 风格指南中的函数约定。

工作流

1. 检查使用该代码的仓库约定和配置。
2. 明确的仓库约定优先于这份带有主观倾向的指南。
3. 只应用、审查或说明与任务相关的指南。
4. 当合适的设计取决于上下文或判断时，说明重要的权衡。

边界

• 由 TypeScript 和 ESLint 负责执行它们能够自动检查的事项。
• 不要仅仅因为启用了这项技能，就引入无关的 TypeScript 风格指南约定。

相关指南

函数参数

关于互斥函数参数的详细指南，请在可用时使用 typescript-discriminated-unions。

函数

应尽可能遵循函数约定（其中一些源于函数式编程的基本概念）：

优先编写满足以下条件的函数：

• 只负责一项职责。
• 通过参数明确依赖项。
• 在计算或转换数据时返回值。
• 尽可能避免副作用。

无状态函数不会在调用之间保留数据。确定性函数对于相同输入总是返回相同结果。纯函数既是确定性的，又没有可观察到的副作用，因此更容易理解、测试和复用。

并非所有函数都能是纯函数。网络请求、存储、日志记录和 UI 更新都需要副作用。应让这些函数保持精简，并将副作用与纯业务逻辑隔离。

单个对象参数

当函数接受多个相关参数时，优先使用单个对象参数。命名属性能让调用位置更易理解，也能让函数 API 无需依赖参数顺序即可演进。

当位置参数的含义和顺序一目了然，或者常见签名更清晰时（例如 isNumber(value) 或回调），保留位置参数。

// ❌ Multiple arguments make this call difficult to understand
transformUserInput('client', false, 60, 120, null, true, 2000);

// ✅ An object makes each argument explicit
transformUserInput({
  method: 'client',
  isValidated: false,
  minLines: 60,
  maxLines: 120,
  defaultInput: null,
  shouldLog: true,
  timeout: 2000,
});

必需参数与可选参数

尽量让大多数参数为必需参数，并谨慎使用可选参数。
如果函数变得过于复杂，它很可能应该拆分成更小的函数。
夸张地说，与其实现一个包含 50 个可选参数的“包办一切”函数，不如实现 10 个各司其职、每个包含 5 个必需参数的函数。

当函数参数表示互斥情况时，请使用可辨识联合类型。

返回类型

要求显式声明返回类型可提高安全性、及早发现错误，并有助于长期维护。不过，过于严格会拖慢开发进度，还会增加不必要的冗余。

经验之谈是：对外显式声明，对内隐式推断。例如，构建 API 或库时，始终显式声明所有类型，以避免意外的破坏性变更。对于内部逻辑，让 TypeScript 推断默认类型；这样既能提供强大的类型安全性，又不会增加冗长的声明。

考虑显式定义函数返回类型的优点：

• 提高可读性：明确指定函数返回值的类型，让调用函数的人员更容易理解代码。
• 避免误用：如果函数不打算返回值，可确保调用代码不会意外尝试使用 undefined 值。
• 及早发现类型错误：有助于在开发过程中捕获潜在的类型错误，尤其是在代码变更意外改变返回类型时。
• 简化重构：确保赋值为函数返回值的变量具有正确类型，让重构更安全、更高效。
• 促进设计讨论：与测试驱动开发（TDD）类似，显式定义函数参数和返回类型，有助于在实现之前讨论函数的功能与接口。
• 可能提高编译性能：显式返回类型可以减少 TypeScript 所需的工作量，尤其是在处理复杂的推断类型时。

考虑到具体情况，在显式返回类型能提升清晰度和安全性时使用它们。

<Rule prefix="在模块边界处要求显式声明返回类型" href="https://typescript-eslint.io/rules/explicit-module-boundary-types/"

{"@typescript-eslint/explicit-module-boundary-types": "error"}