优秀API设计的十大原则
英文原文： Ten Rules for Good API Design
每个软件开发人员都使用 API。“优秀”的 API 设计就像魔法。不过，我不知道有多少人可以解释为什么有的 API 很复杂、很难学，而有的则干净、简单、使用起来堪称是一种快乐。关于这个问题，我将在文中回答，并提供优秀 API 设计的十条法则。
1. 只做你今天需要的
这是最顶级的规则。只解决今天必须解决的问题，最小化需要完成的答案。解决明天的问题的诱惑力是巨大的。但是一定要顶住诱惑！不要提前发布代码，重点是注重缩小发布周期。如果需要花几个小时的时间来回答新问题，那么就不用再猜测明天会出现什么问题了。
2. API 模块化
将大型问题转化为规模较小的、可单独解决的问题。模块化 API 更容易学习，并且可以随时间而改变。你可以用新模块替代旧模块。可以一个一个地教导模块。也可以将 API 的实验部分从稳定或传统的部分中单独分出来。
3. 使用结构化语法
使用结构化的 API 语法：用 thing.action 或 thing.property 代替 do_action_with_thing。语法将自然而然地适应模块化的方法，其中每个模块是一个类。
4. 使用自然语义
不要发明新概念。只使用开发人员众所周知的概念，作为类系统的基础。如果你发现自己需要解释概念，那说明你出错了：要么你在解决以后的问题，要么你正在错误地构建 API。
5. API 的自我约定
每个类都要严格使用相同的样式和约定。一致性是指当一个人学会这一个类时，他就能够融会贯通地掌握全部的类。文档化约定，让它们成为贡献者必须的标准。
6. API 的可扩展性
易扩展性有许多好处，并不仅仅在于受到贡献者的欢迎。它还可以让你延缓实现功能，因为“如果需要的话，后面再添加也很方便”。不需要的功能就不添加，这也是一种双赢。
7. 完全测试
每个类和方法必须经过恶意代码的完全测试。要像写代码一样写测试，然后像 API 提供给外界约定文档一样使用测试。每当代码改变的时候就运行这些测试。不要担心代码覆盖率。重要的是外部约定。也可以考虑使用约定生命周期。
8. 分层式成长
保持 API 突出重点，然后在顶部将新的 API 分层，以便于它们能随着时间的推移成长。可扩展性并不意味着无限期的成长。明确 API 的范围，并在范围内执行。
9. 保持简单易用
最终的测试要看 API 的简单易用程度。你写的例子，能不能让你的代码看起来更简单？你是不是强迫用户说明他们不在乎的选项？有没有毫无价值的额外步骤？要注重约减少 API 的可视面积。
10. 保持可移植性
不要让系统概念泄漏到 API。整洁有目的地抽象：这个 API 可以运行在任何操作系统上。API 必须能够隐藏实现，但要注意第 4 条规则，以及要使用自然抽象。
欢迎大家说说自己的看法。
-
译文链接： http://www.codeceo.com/article/10-rules-good-api-design.html
翻译作者： 码农网 – 小峰
正文到此结束
热门推荐
相关文章
近期评论
-
文章和留言都翻到11页了 没有OOM
-
-
朋友，翻页到11页，及以后，会出现OOM，无法访问
-
-
搞个gitee的项目
-
-
版本号是多少，你可以下载哪个代码仓库，jdk选1.8 直接跑就行
-
-
-
Loading...
![[HBLOG]公众号](https://www.liuhaihua.cn/img/qrcode_gzh.jpg)
