如何理解Node.js官方文档中的API签名标注格式？

这套方括号标注是技术文档里通用的语法约定，不是Node.js独有，核心规则非常明确：

• 所有未被方括号包裹的参数都是必填参数，调用API时必须按顺序传入，缺失会触发报错。
• 被方括号[]整体包裹的内容是可选参数，调用时可以根据需求选择传或者不传。
• 方括号存在嵌套关系时，代表参数的传递顺序依赖：如果要传入内层嵌套的可选参数，必须先把它外层所有嵌套层级的可选参数按顺序传完，不能跳过外层参数直接传内层参数。

结合给出的两个API示例拆解 #

1. fs.writeFile(file, data[, options], callback)

• 无括号包裹的file、data、callback为必填项，任何调用都必须传入这三个参数。
• 方括号包裹的options是一级可选参数，没有嵌套依赖，可以选择传或者不传：
  • 不传options的标准写法：

    fs.writeFile('./test.txt', 'hello world', (err) => {
      // 回调逻辑
    })
    

  • 传options时，必须放在data和callback的中间位置：

    fs.writeFile('./test.txt', 'hello world', { encoding: 'utf8' }, (err) => {
      // 回调逻辑
    })
    

2. fs.writeSync(fd, buffer[, offset[, length[, position]]])

这个API的可选参数是多层嵌套结构，传递时必须严格遵循从外到内的顺序：

• 无括号包裹的fd、buffer为必填项，必须传入。
• 第一层方括号内的offset是一级可选参数：可以只传fd和buffer，后面的可选参数全不传。
• 第二层方括号内的length是二级可选参数：如果要传length，必须先传入offset，不能跳过offset直接传length。
• 第三层方括号内的position是三级可选参数：如果要传position，必须先传入offset和length，不能跳过前两个直接传position。

对应的合法/非法调用参考：

合法调用：

• 仅传必填参数：fs.writeSync(1, Buffer.from('test'))
• 传必填+offset：fs.writeSync(1, Buffer.from('test'), 0)
• 传必填+offset+length：fs.writeSync(1, Buffer.from('test'), 0, 4)
• 传全量参数：fs.writeSync(1, Buffer.from('test'), 0, 4, 0)

非法调用（跳传参数会导致参数识别错误）：

• 跳过offset直接传length：fs.writeSync(1, Buffer.from('test'), 4) （此处传入的4会被引擎识别为offset参数，不会按预期识别为length）
• 跳过offset、length直接传position：fs.writeSync(1, Buffer.from('test'), 0) （此处传入的0同样会被识别为offset参数）

补充说明：少数文档里会出现平级的方括号写法，比如func(a[, b][, c])，这种写法代表b和c是互相独立的可选参数，没有传递依赖，可以选传任意一个；但Node.js官方文档的API几乎不会用这种写法，绝大多数可选参数都是按顺序嵌套的，按位置从外到内传即可。

内容的提问来源于stack exchange，提问作者Primer Cielo