来自Google资深工程师Joshua Bloch的分享：API设计最佳实践

为什么API设计如此重要？API是一个公司最重要的资产。

为什么API的设计对程序员如此重要？

API一旦发布，出于兼容性考虑，不能轻易地随心所欲进行修改，比如删除参数。

从API的上帝 - 设计者的视角出发，有助于提高代码质量。

一个优秀的API应该满足下列标准：

易学易用，甚至是自描述的，不需文档也能让新手快速上手。不易造成误解。后续维护者易于理解，满足开闭原则 - 能够很容易进行扩展。

如何设计一个好的API

首先应该从收集需求出发。注意结合API实现的复杂度一起考虑。

作为第一步，首先给出需求规格文档，一页即可：

别指望你的API能让所有人满意。也不要指望发布后，它不会出任何错误——那是不可能的。

API也应该遵循单一职责：如果你发觉很难根据你的API实现的功能给它取个合适的名字，这是一个不好的信号，很多时候说明你的API里面做了太多事情——试着把它们拆成多个API。

信息封装 - 公有类尽量避免暴露公有字段出去，最大化信息隐藏

API命名艺术 - API的名称也是一门语言。

API和文档的关系

合理使用继承和子类，不要滥用里氏替换原则

采用fail fast 策略，尽可能早地抛出错误消息：

API的数据都应该允许使用者通过字符串的方式访问

慎用重载

选用合适的API参数和返回类型

API里的参数顺序也很有讲究

避免冗长的参数列表，参数如果超过3个，使用者就需要通过阅读文档才能消费了。

尽量返回不需要调用者进行异常处理的参数，比如空数组或集合，而不是null

API设计里的和异常处理相关的最佳实践

API重构的最佳实践

API设计和Thread-local相关的最佳实践

要获取更多Jerry的原创文章，请关注公众号"汪子熙":

来自Google资深工程师的API设计最佳实践的更多相关文章

  1. RESTful API 设计最佳实践

    背景 目前互联网上充斥着大量的关于RESTful API(为了方便,以后API和RESTful API 一个意思)如何设计的文章,然而却没有一个"万能"的设计标准:如何鉴权?API ...

  2. ****RESTful API 设计最佳实践(APP后端API设计参考典范)

    http://blog.jobbole.com/41233/ 背景 目前互联网上充斥着大量的关于RESTful API(为方便,下文中“RESTful API ”简写为“API”)如何设计的文章,然而 ...

  3. RESTful API 设计最佳实践（转）

    摘要:目前互联网上充斥着大量的关于RESTful API(为了方便,以后API和RESTful API 一个意思)如何设计的文章,然而却没有一个”万能“的设计标准:如何鉴权?API格式如何?你的API ...

  4. RESTful API 设计最佳实践(转)

    背景 目前互联网上充斥着大量的关于RESTful API(为方便,下文中“RESTful API ”简写为“API”)如何设计的文章,然而却没有一个”万能“的设计标准:如何鉴权?API 格式如何?你的 ...

  5. RESTful API 设计最佳实践【转】

    背景 目前互联网上充斥着大量的关于RESTful API(为了方便,后面API和RESTful API 一个意思)如何设计的文章,然而却没有一个“万能”的设计标准:如何鉴权?API格式如何?你的API ...

  6. RESTful API 设计指南，RESTful API 设计最佳实践

    RESTful API 设计指南,RESTful API 设计最佳实践 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). ...

  7. (转)RESTful API 设计最佳实践

    原文:http://www.oschina.net/translate/best-practices-for-a-pragmatic-restful-api 数据模型已经稳定,接下来你可能需要为web ...

  8. [转] 阿里研究员谷朴：API 设计最佳实践的思考

    API是软件系统的核心,而软件系统的复杂度Complexity是大规模软件系统能否成功最重要的因素.但复杂度Complexity并非某一个单独的问题能完全败坏的,而是在系统设计尤其是API设计层面很多 ...

  9. atitit.基于http json api 接口设计 最佳实践 总结o7

    atitit.基于http  json  api 接口设计 最佳实践 总结o7 1. 需求:::服务器and android 端接口通讯 2 2. 接口开发的要点 2 2.1. 普通参数 meth,p ...

随机推荐

  1. java获取当前秒数输出

    Date的getSeconds()已经过时了.不建议用.所以用了下面方法 Calendar c = Calendar.getInstance(); while(true) {            c ...

  2. 【ExtJS】关于标准模块化封装组件

    在此之前,自己封装自定义控件用的是这样的方式: Ext.define('My.XXX',{ extend: 'Ext.YYY', xtype: 'ZZZ', . . . items:[ ... ] } ...

  3. （转载）.NET的五层架构

    我们刚开始学习架构的时候,首先会想到分层的概念,分层架构比较经典的是三层架构,那么,什么是三层架构呢?它包括表现层,业务层,数据访问层:而对于一个新手来说,从抽象意义上的三层架构,逻辑上就划分为三个层 ...

  4. redis的持久化方式

    redis有两种持久化方式,第一种是基于快照的持久化方式,第二种是基于文件追加的持久化方式 一.基于快照的持久化 1.修改redis.conf配置文件,开启基于快照的持久化方式 2.修改持久化文件存放 ...

  5. ES6，先知道这些必会的才行

    变量声明 const 和 let 不要用 var,而是用 const 和 let,分别表示常量和变量.不同于 var 的函数作用域,const 和 let 都是块级作用域. const DELAY = ...

  6. Html5的新特性总结

    新加语义化标签: HTML5其实是关于图像,位置,存储,速度的优化和改进 图像: 到目前为止,基本上想要直接在网页上进行绘图还是不能轻易完成的,即使是几何图形也不可以.在浏览器当中直接能跟图片的交互操 ...

  7. oracle 基础笔记

    sqlplus / as sysbda;-- 运行命令conn scott/tiger [as sysdba];-- 登录show user;查看当前用户alter user scott accoun ...

  8. JavaEE之JavaWeb核心之Servlet

    Servlet简介: Servlet 运行在服务端的Java小程序,是sun公司提供一套规范(接口),用来处理客户端请求.响应给浏览器的动态资源.但servlet的实质就是java代码,通过java的 ...

  9. python垃圾回收机制（Garbage collection）

    由于面试中遇到了垃圾回收的问题,转载学习和总结这个问题. 在C/C++中采用用户自己管理维护内存的方式.自己管理内存极其自由,可以任意申请内存,但也为大量内存泄露.悬空指针等bug埋下隐患. 因此在现 ...

  10. 浅谈jquery中prop()和attr()

    我们都知道,一般在jquery中设置属性时要用到attr()方法,现在我们有一个效果,点击按钮切换复选框的选中状态,下面贴出html代码: <input type="checkbox& ...