为了账号安全,请及时绑定邮箱和手机立即绑定
手记 \ 浅谈如何设计API(二)

浅谈如何设计API(二) 原创

2016-12-30 15:53:54 1844浏览 0评论
  • API设计的一些原则
  • 3.1 只公开必须的内容

    在编写API时,肯定会有这样一种思考方式:是不是要多加一个参数呢?可能会有这种用法吧?参数要不要做到很灵活呢?接收一个Object数组吧(而且是不带泛型的)。。。有这样的想法能说明我们在设计API的时候思考了很多,但是这么实现的API是要命的、坑人的。

    那么我们应该怎么做呢?精简、明确、直接。只公开必要的内容,不要为了“以后可能会有”而大伤脑筋,考虑未来的扩展固然是好事,但凡事总要有个度,过犹不及。

  • 3.2 面向接口编程

    面向接口编程,在一些面向对象语言中提及的比较多(比如java)。面向接口编程,就是在参数的传递和返回使用接口而不是实现类,这样可以方便的替换实现方,从而达到程序容易扩展、实现更加灵活的目的。

    比如我们在设计一个API的时候,传入参数使用接口Map就会比使用具体的类如HashMap、TreeMap更加灵活。比如JDBC,我们使用的都是Connection、ResultSet这样的一些接口,具体的实现则由数据库厂商提供,MySql、Oracle等厂商都提供了JDBC的实现。

  • 3.3 方法重载

    方法重载在很多API、SDK中有着广泛的使用,之所有使用重载是因为它为程序实现带来了极大的便利。一个明显的例子是:在不同的地方做相同或类似的事情,重载这种方式的优越性就凸显出来了。我们看下面的例子:
    在JDK的java.util包下的Collections类有两个个排序的静态方法:
    sort(List<T> list);
    sort(List<T> list, Comparator<? super T> c);

    同样的方法名不会让人疑惑,参数的丰富让人一眼就能看到重载方法的区别以及自己该调用哪个。

  • 3.4 返回值

    当API具有返回值时,应该在一组(或同一种类)的API中使用同样规则的返回值。
    下面提供一种参考方式:如返回的结果是单个对象,当没有找到符合条件的结果时,应返回null;如果返回值是List、Map或数组,那么应该返回空的Lisp、Map、数组,而不是null。
    上面的方式不一定是适合所有场景的,也可以使用另外的一种通用规则替代,比如当查询不到符合条件的数据时抛出异常,这也是一种通用的方式,具体使用哪种,根据实际情况而定。

【推荐】
浅谈如何设计API(一)
浅谈如何设计API(二)

本文原创发布于慕课网 ,转载请注明出处,谢谢合作!

相关标签: 设计
20 推荐

    moocer

    JAVA开发工程师 曾混迹于企业应用领域,后转战电商,现奋战于互联网教育行业,转眼间已匆匆数年,喜爱技术甚于自己,至今不悔。感天地之广大,岁月之蹉跎,若能重来,仍代码。

    作者的热门手记

    意见反馈 常见问题 APP下载
    官方微信