来自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. Nginx几个简单命令

    • 启动nginx服务 sudo brew services start nginx 利用http://localhost:8080进行访问, 如果出现如下界面,说明启动成功. • 查看nginx版本 ...

  2. 阿里云API公共参数的获取

    阿里云公共参数API  https://help.aliyun.com/document_detail/50284.html?spm=5176.10695662.1996646101.searchcl ...

  3. jenkins启动脚本

    [root@localhost system]# cat /etc/init.d/jenkins #!/bin/sh # # SUSE system statup script for Jenkins ...

  4. 【分布式消息队列-MQ】

    http://www.cnblogs.com/itfly8/p/5155983.html

  5. alpine 上部署netcore 项目

    1 Alpine部署 注:以下教程是以Alpine v3.7.0系统部署:其他Linux系统部署也基本相同 1.1 .NET Core环境包下载 .net core下载地址:https://dotne ...

  6. .net core 部署到IIS上 HTTP Error 502.5 - ANCM Out-Of-Process Startup Failure

    安装AspNetCoreModule托管模块后执行 1.net stop was /y 2.net start w3svc

  7. vue中添加swiper轮播插件

    网上找了很多,最后还是官网最完整. https://github.com/surmon-china/vue-awesome-swiper 安装: 1.npm install vue-awesome-s ...

  8. CSS3——transform2D的应用

    前言: 关于CSS3,我想最让人感到有意思的就是2D和3D的技术,这让我们的网页立马丰富起来,可以让我们完成一些很酷很炫的效果,比如旋转木马.经过一段时间的学习,让我对CSS3有了更近一步的了解,在此 ...

  9. maven filter不起作用

    遇到的一个坑, spring boot + maven maven fileter没有起作用.spring boot把默认占位符改了 参考:https://blog.csdn.net/mn960mn/ ...

  10. flask 简易注册登陆

    db.py import MySQLdb conn = MySQLdb.connect(', 'test1') cur = conn.cursor() def addUser (username,pa ...