Arity指函数定义时形参个数，如add(a,b)的arity为2、log(...args)为0；它影响API设计、类型推导、函数组合及向后兼容性。

函数的“arity”指它定义时声明的参数个数，不是调用时传入多少个，而是形参列表里写了几个。比如 function add(a, b) 的 arity 是 2，function log(...args) 的 arity 是 0（因为 rest 参数不计入）。这个看似简单的数字，在 API 设计中其实牵一发而动全身。

arity 决定调用方式是否自然

用户调用一个函数时，直觉来自它的参数数量和顺序。arity 过高（比如 5 个以上必需参数）会迫使使用者查文档、记顺序，容易出错；过低（如全靠对象解构）又可能掩盖关键输入。设计时应让核心逻辑所需参数刚好暴露在最外层：

• 把真正不可省略的参数放在前面，保持低 arity（通常 ≤3）
• 可选配置统一收进最后一个对象参数，避免 arity 波动
• 避免混合位置参数和关键字参数——这会让 TypeScript 类型推导变弱，也增加调用记忆负担

arity 影响类型系统与工具支持

TypeScript 和编辑器依赖函数的 length 属性（即 arity）做参数提示、自动补全和错误检查。如果用 ...args 或动态代理抹平 arity，IDE 就无法准确提示该传什么。例如：

typescript-dev

使用 Vite 8、React 19、Tailwind CSS v4、shadcn/ui、Biome、Vitest 和 Hono 构建全栈 TypeScript 应用，涵盖前端（Vite/Rolldown 构建 + 开发）...

下载

• fetch(url, options)（arity=2）→ 编辑器能分别提示 url 类型和 options 结构
• fetch(...args)（arity=0）→ 补全失效，类型检查退化为 any
• Lodash 的 _.ary(fn, 2) 可强制截断参数，但会丢失后续参数语义，慎用于公共 API

arity 与函数组合、柯里化强相关

在函数式风格的 API 中（如 Ramda、Redux Toolkit 的 createAsyncThunk），低且稳定的 arity 是可组合的前提。一个 arity 为 2 的函数才能被 R.curry 安全地转成支持部分应用的形式：

• arity=1 的函数适合管道（pipe）、映射（map）等单入单出场景
• arity=2 的函数天然适配 reduce、filter、some 等数组方法的回调签名
• arity 不固定（如接受任意多参数）的函数很难参与 compose，除非先用 _.unary 或 _.binary 显式约束

arity 是向后兼容的隐形边界

修改函数 arity（比如从 2 个参数加到 3 个）属于破坏性变更：所有调用处都需更新，即使新增的是可选参数。JS 不报错，但运行时可能因 undefined 导致逻辑异常。安全做法是：

• 新增能力优先通过新函数暴露，而非扩展现有函数 arity
• 若必须扩展，用对象参数承载新字段，并保持旧调用方式仍有效
• 在 JSDoc 和类型定义中标明每个参数的用途和是否必需，比只看 arity 更可靠