课程大纲 第 67 课,共 148 课 · 没人能误用的 API
没人能误用的 API

被设计出来的误用

为什么重要 发生在 API 边界上的大多数缺陷并不在 API 里。它们在某个调用者那里,这个调用者用了一种看起来没问题、却悄悄做错了事的方式。你没法修好每一个调用者;但你可以让错误的用法变得不可能,或者变得很响亮。

一个编写 API 的助手往往很乐于助人:如果你在连接之前就发送,它会替你连接;如果你在需要字节的地方传了一个字符串,它会帮你编码;如果你忘了某个选项,就有一个默认值。每一份好意都会把一个错误隐藏起来,直到它在很远的地方冒出来。

及早失败,大声失败:在恰好出错的那次调用上抛出一个错误,在任何东西被改变之前,并带有一条说明期望什么的消息。

四种工具

  • 明确的状态:一个知道自己是新建的、打开的还是关闭的对象,并拒绝不合适的调用。
  • 具名的选项,不用布尔值:mode="dry_run" 不会意外地和另一个标志互换;copy(a, b, True, False) 却会。
  • 对于弄错就很危险的选择,不设无声的默认值:让调用者自己说出来。
  • 携带含义的类型:知道自己币种的钱,不能和另一种币种的钱相加。

在这个模块里,隐藏的误用脚本会错误地调用你的 API,并期望在出错的那次调用上得到一个错误,而且什么都没被改变。正确用法的脚本则期望它直接正常工作。每道题都会列出需要防范的误用。

回顾 乐于助人的猜测会隐藏缺陷。在出错的那次调用上、在产生任何效果之前,拒绝错误的用法。

发现这节课有问题?报告它 · 就这节课提问

这个练习即将开放

完成它前面的那一课,这一课就会解锁。整门课程免费,无需账号,而且你现在就可以阅读这节课。