免费注册 查看新帖 |

Chinaunix

  平台 论坛 博客 文库
123下一页
最近访问板块 发新帖
查看: 22080 | 回复: 20

[分享] 如何设计好软件的API [复制链接]

论坛徽章:
1
天蝎座
日期:2013-12-06 18:23:58
发表于 2015-01-27 12:56 |显示全部楼层
获奖名单已公布http://bbs.chinaunix.net/thread-4171401-1-1.html

话题背景:


团队合作过程中免不了需要和别人合作,对于软件开发人员来说,API可能是最直接,最有效的沟通方式。但是,现实很骨感,你发现别人提供的API要么不能很好的满足你的需求,要么功能不能保持一致性。对每个人来说,API的一致性都是最大的问题。原因不只是处在开发人员的身上,他们其实也是想保持一致的。自己知道如何做某件事,可能就是无法和别人讲清楚。那么API设计到底有什么特殊的地方呢?API 也是软件和外界交互的门面,间接的表达了软件内部的设计。可能API不适当的一个表达,就反映了内部架构上的问题。

本期话题:

1. API设计的特殊之处在哪里?
2. 如何评价API设计的好坏?
3. 总结一下自己设计API的一些经验。

活动时间:

2015-1-27~2015-2-27

活动奖励:
程序员必读之软件架构

作者: (英)Simon Brown   
丛书名: 图灵程序设计丛书
出版社:人民邮电出版社
ISBN:9787115371072
上架时间:2014-11-5
出版日期:2015 年1月

求职 : 机器学习
论坛徽章:
79
2015年亚洲杯纪念徽章
日期:2015-05-06 19:18:572015七夕节徽章
日期:2015-08-21 11:06:172015亚冠之阿尔纳斯尔
日期:2015-09-07 09:30:232015亚冠之萨济拖拉机
日期:2015-10-21 08:26:3915-16赛季CBA联赛之浙江
日期:2015-12-30 09:59:1815-16赛季CBA联赛之浙江
日期:2016-01-10 12:35:21技术图书徽章
日期:2016-01-15 11:07:2015-16赛季CBA联赛之新疆
日期:2016-02-24 13:46:0215-16赛季CBA联赛之吉林
日期:2016-06-26 01:07:172015-2016NBA季后赛纪念章
日期:2016-06-28 17:44:45黑曼巴
日期:2016-06-28 17:44:4515-16赛季CBA联赛之浙江
日期:2017-07-18 13:41:54
发表于 2015-01-27 13:45 |显示全部楼层
沙发啊,谷歌一个工程师制作了一个PPT,讲述如何设计API,感兴趣的大家可以搜索 《How to Design a Good API and Why it Matters》

论坛徽章:
40
水瓶座
日期:2013-08-15 11:26:422015年辞旧岁徽章
日期:2015-03-03 16:54:152015年亚洲杯之乌兹别克斯坦
日期:2015-03-27 14:01:172015年亚洲杯之约旦
日期:2015-03-31 15:06:442015亚冠之首尔
日期:2015-06-16 23:24:37IT运维版块每日发帖之星
日期:2015-07-01 22:20:002015亚冠之德黑兰石油
日期:2015-07-08 09:32:07IT运维版块每日发帖之星
日期:2015-08-29 06:20:00IT运维版块每日发帖之星
日期:2015-08-29 06:20:00IT运维版块每日发帖之星
日期:2015-10-10 06:20:00IT运维版块每日发帖之星
日期:2015-10-11 06:20:00IT运维版块每日发帖之星
日期:2015-11-10 06:20:00
发表于 2015-01-29 10:12 |显示全部楼层
这个靠谱 做接口还是挺有技术含量的

论坛徽章:
18
卯兔
日期:2013-09-27 17:41:0615-16赛季CBA联赛之佛山
日期:2016-07-09 17:34:45操作系统版块每周发帖之星
日期:2015-12-02 15:01:04IT运维版块每日发帖之星
日期:2015-12-02 06:20:00IT运维版块每日发帖之星
日期:2015-10-07 06:20:00IT运维版块每日发帖之星
日期:2015-10-03 06:20:00IT运维版块每日发帖之星
日期:2015-10-01 06:20:00羊年新春福章
日期:2015-04-01 17:56:06拜羊年徽章
日期:2015-04-01 17:56:062015年迎新春徽章
日期:2015-03-04 09:49:452015年辞旧岁徽章
日期:2015-03-03 16:54:15天秤座
日期:2015-01-14 06:39:28
发表于 2015-01-29 10:43 |显示全部楼层
地板上了!!!

论坛徽章:
0
发表于 2015-01-29 18:50 |显示全部楼层
菜鸟一只,不知道以后能不能接触到这些目前够不到的地方

论坛徽章:
1
天蝎座
日期:2013-12-06 18:23:58
发表于 2015-01-30 16:34 |显示全部楼层
回复 3# forgaoqiang


    相当有技术含量,尤其是新旧版本兼容,不小心就被人喷死了,关键是会造成重大事故

论坛徽章:
1
天蝎座
日期:2013-12-06 18:23:58
发表于 2015-01-30 16:36 |显示全部楼层
回复 5# NumberOneFrog


    写程序,就会写API,怎么会说是距离自己很远呢?

论坛徽章:
4
CU大牛徽章
日期:2013-04-17 11:48:26CU大牛徽章
日期:2013-04-17 11:48:40CU大牛徽章
日期:2013-04-17 11:48:45摩羯座
日期:2013-12-06 18:10:04
发表于 2015-01-31 22:44 |显示全部楼层
实际上,API设计并不程序员的职责(至少大部分不是),而是主程序员、架构师的责任,API反映了架构和业务流程,所以,除了需要与其它程序员沟通之外,还需要和各业务部门沟通,除了确保按架构师的意图完成工作之外,还需要确保业务流程的正确、清晰地实现。

1. API设计的特殊之处在哪里?
体现架构与流程,确保至少较长时间内的稳定性。

2. 如何评价API设计的好坏?
是否体现架构意图,是否有良好的软件工程原则体现。

3. 总结一下自己设计API的一些经验。
良好的软件工程原则,良好的业务体现,良好的架构理解,良好的沟通。

论坛徽章:
1
白羊座
日期:2013-08-22 17:30:33
发表于 2015-02-01 19:12 |显示全部楼层
1. API设计的特殊之处在哪里?
    api设计最最特殊的地方也是最需要设计者考虑的地方,就是它的稳定性及易用性。
    所以设计者在更新api设计时总是以一种向下兼容的方式来做。
2. 如何评价API设计的好坏?
    1).不标新立异,这一点可以参考C++语言,它允许使用者重载操作符,但是如果你
        将operator+重载成operator*的语义,那么往往预示着你建造了一个滋生bug的温床
     2).把握好api的粒度,不要一味地讲究大而全,最好以8020原则正交的提供好一个最基本的
       操作集,剩下的功能留给使用者去实现,或者在更高的层次上去实现多一个层
     3).  简单易用,尽量减少使用者的学习成本      
3. 总结一下自己设计API的一些经验。
    1). 这是一个需要反复琢磨的迭代过程,你基本上无法一次性做好,你需要自己试着去写一些使用自己
         设计的api的代码,去感受它的实用性
    2).参考类似的api设计,发现自己考虑的欠缺,让其他同事试着来使用并评价你的api

论坛徽章:
19
处女座
日期:2014-07-18 14:50:5415-16赛季CBA联赛之北京
日期:2019-09-16 15:39:1415-16赛季CBA联赛之上海
日期:2019-09-15 15:29:0415-16赛季CBA联赛之山西
日期:2017-03-09 10:58:232017金鸡报晓
日期:2017-02-08 10:33:212017金鸡报晓
日期:2017-01-10 15:13:2915-16赛季CBA联赛之深圳
日期:2016-12-15 17:55:53C
日期:2016-10-25 16:00:1515-16赛季CBA联赛之新疆
日期:2016-07-21 14:02:0415-16赛季CBA联赛之江苏
日期:2016-06-30 12:15:04shanzhi
日期:2016-06-17 17:59:31平安夜徽章
日期:2015-12-26 00:06:30
发表于 2015-02-01 23:54 |显示全部楼层
本帖最后由 shenlanyouyu 于 2015-02-08 23:28 编辑

1.API设计的特殊之处在哪里?
      在工作中,一人完成整个项目的单打独斗的时代已经过去。在工作中很多时候我们都是承担的一部分模块功能的开发,最后将多个模块整合起来,模块间的通信是通过定义好的API来完成,不必要了解其他模块的内部实现细节,只需要阅读API使用说明,就可以使用其他模块提供的功能。
      毫无疑问的是,API是给用户使用的,无论用户是公司内部团队还是外部用户。要设计好的API,满足用户的需求是最重要的。因此需要站到用户的角度来思考,面向用例来设计API,才能保证API设计的合理性。
      API的特殊之处在于API是开发者所编写的最重要的代码。因为比起相关的实现代码出现问题,修复API的出现的问题代价要大得多。如果一个特定的应用程序代码出现了错误,只会影响到该应用程序本身,而如果API的代码中出现了错误,就会影响到所有使用该API的应用程序。

2. 如何评价API设计的好坏?
判断API设计好坏可以从以下几个方面出发:
(1) 一致性,一致性是API设计的重要的评价标准。一致性包括两个方面,API应该在版本间保持一致,其次是API对外提供的功能一致。
(2) 可理解性,API易于学习,用户能够理解API的用法。
(3) 可维护性,API支持后续的维护,添加新的需求。
(4) 功能的内聚性,一个API提供的功能应该只包括用例中说明的功能。

3. 总结一下自己设计API的一些经验。
     在工作中主要用C/C++编程语言,所以只能说说C/C++相关内容。设计API是给内部team使用,因此在设计之前会根据自己承担部分模块的功能,和上下层模块复杂人沟通,商定了好通信流程,维护一份API文档。如果在开发过程中需要修改,及时将信息反馈,并及时更新文档。API必须有使用说明和完善的文档记录。由于C++允许同名函数,因此在设计之初,对于函数参数一定要把握好。其次,对于同一个功能实现进行扩展,需要提出新的API时,保持API的一致性,可以参考Microsoft的做法提供新的API,例如CreateThread和CreateThreadEx;使用设计模式,提供API的灵活性。例如基于C语言的callback函数实现观察者模式,qsort函数也是一个使用callback实现的功能强大的排序函数。其次可以从开源项目宝库中学习经验,Glibc、Linux、Android等都是学习API设计的宝库,学习里面良好的设计。例如在C标准库里面getchar函数就是一个糟糕API设计例子。建立API的审查机制,团队对API设计进行Review,团队中每个人根据自己经验给出评价。
您需要登录后才可以回帖 登录 | 注册

本版积分规则 发表回复

DTCC2020中国数据库技术大会

【架构革新 高效可控】2020年12月21日-23日第十一届中国数据库技术大会将在北京隆重召开。

大会设置2大主会场,20+技术专场,将邀请超百位行业专家,重点围绕数据架构、AI与大数据、传统企业数据库实践和国产开源数据库等内容展开分享和探讨,为广大数据领域从业人士提供一场年度盛会和交流平台。

http://dtcc.it168.com


大会官网>>
  

北京盛拓优讯信息技术有限公司. 版权所有 16024965号-6 北京市公安局海淀分局网监中心备案编号:11010802020122
中国互联网协会会员  联系我们:huangweiwei@it168.com
感谢所有关心和支持过ChinaUnix的朋友们 转载本站内容请注明原作者名及出处

清除 Cookies - ChinaUnix - Archiver - WAP - TOP