免费注册 查看新帖 |

Chinaunix

  平台 论坛 博客 文库
最近访问板块 发新帖
楼主: crazyhadoop

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

论坛徽章:
208
巨蟹座
日期:2013-09-02 09:16:36卯兔
日期:2013-09-02 20:53:59酉鸡
日期:2013-09-05 21:21:45戌狗
日期:2013-10-15 20:51:17寅虎
日期:2013-10-18 21:13:16白羊座
日期:2013-10-23 21:15:19午马
日期:2013-10-25 21:22:48技术图书徽章
日期:2013-11-01 09:11:32双鱼座
日期:2013-11-01 20:29:44丑牛
日期:2013-11-01 20:40:00卯兔
日期:2013-11-11 09:21:32酉鸡
日期:2013-12-04 19:56:39
发表于 2015-02-02 09:34 |显示全部楼层
我的了解是:
1)确保接口稳定
2)隐藏内部机制
3)尽量降低约束性限制
4)隔离平台和系统差异

论坛徽章:
0
发表于 2015-02-05 17:56 |显示全部楼层
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-08 23:33 |显示全部楼层
API提供了对某个问题的抽象,以及用户与解决该问题的软件组件之间进行交互的方式。API定义了一些可复用的模块,使得各个模块化功能块可以嵌入到最终用户的应用程序中去。
关于API设计的书不是很多,个人看过的推荐两本:
(1) 《软件框架设计的艺术》,看名字这本书似乎和API设计八竿子打不着,其实这本书核心内容是如何设计优秀的API,适合Java程序员。
(2) 《C++ API设计》,看书名这本书适合C++程序员,^_^书中有一部分内容是如何通过设计模式来设计API。

论坛徽章:
32
CU大牛徽章
日期:2013-05-20 10:45:13每日论坛发贴之星
日期:2015-09-07 06:20:00每日论坛发贴之星
日期:2015-09-07 06:20:00数据库技术版块每日发帖之星
日期:2015-12-13 06:20:0015-16赛季CBA联赛之江苏
日期:2016-03-03 11:56:13IT运维版块每日发帖之星
日期:2016-03-06 06:20:00fulanqi
日期:2016-06-17 17:54:25IT运维版块每日发帖之星
日期:2016-07-23 06:20:0015-16赛季CBA联赛之佛山
日期:2016-08-11 18:06:41JAVA
日期:2016-10-25 16:09:072017金鸡报晓
日期:2017-01-10 15:13:292017金鸡报晓
日期:2017-02-08 10:33:21
发表于 2015-02-09 23:37 |显示全部楼层
1. API设计的特殊之处在哪里?
API即应用编程接口,主要用于实现组件与组件之间、系统与系统之间的交互功能,它提供了对某个问题的抽象,以及客户与解决该问题的软件组件之间进行交互的方式。
API定义了一些可复用的模块,实现了模块间的松耦合。
API是一个明确定义的接口,可以为其他软件提供特定服务。
API是软件组件的逻辑接口,隐藏了实现这个接口所需的内部细节。

2. 如何评价API设计的好坏?
API设计应当遵循一些原则:
1)API应该对程序员友好
2)API应该简单、直观、优雅、易用、语义清晰
3)API应该保持足够的灵活性
4)API接口文档应该尽可能详细
5)API需要进行合理的版本化管理
6)API的发布应该经过了充分的测试,以保证其健壮性

3. 总结一下自己设计API的一些经验。
我长期做Java Web开发,写API多年了。尤其是这些年做互联网应用,写API文档那是家常便饭。
不过近几年转作架构设计了,API文档虽然也在写,但经常是交给手下写,我自己做质量把关,审核API文档内容。
以移动互联网应用为例,通常都是这样的架构:后端平台应用对外提供RESTful Web服务,前端Android本地应用或iOS本地应用直接通过接口调用连接后端。
后端的构造可以是Spring Framework+MyBatis+MySQL之类的架构,也可以采用相似的技术,比如Ruby on Rails框架。这些都是大同小异。
整个系统要实现稳定、健壮,就要求前后端必须能有效地协同工作,那么API的设计就非常重要了。
正如我在第二个问题的回答中所说,API设计应当遵循一些原则,只要遵守规则,就能开发出好的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-09 23:45 |显示全部楼层
回复 18# jieforest

同意API应该经过充分的测试,最好的方法是建立自动化测试机制,在API更新时进行自动化回归测试。

   

论坛徽章:
1
2015年辞旧岁徽章
日期:2015-03-03 16:54:15
发表于 2015-02-12 14:04 |显示全部楼层
1. API设计的特殊之处在哪里?
没有界面设计那么直观,好用不好用,容易不容易使用都需要经过检测或者时间来验证。

2. 如何评价API设计的好坏?
我理解需要3方面
1 是否符合逻辑思维
2 是否好用
3 是否容易使用
4 是否容易扩展

3. 总结一下自己设计API的一些经验。
结合我上面给的4点谈点浅显的经验吧
1 是否符合逻辑思维
某文档管理系统,需要带入
Add_Doc(DocID, DocType, Author_ID)等一系列参数,但是DocID是系统自动生成的唯一值,这样每次传入的参数都是未可知的,这种API设计就是反人类的
后来修改为
*DocID Add_Doc(this, DocType, Author_ID),每次带入的都是本次加入的文档,而且将生成的唯一ID作为返回参数。

2是否好用
搜索已知的文档
Search_Doc(DocID)这个是最基础的函数,但是每次带入都不方便
做多态
Search_Doc_ByTitle(this, Doc_Title)
Search_Doc_ByAuthor(this, Author_ID)
Search_Doc_ByType(this, DocType)
其实内部都是调用Search_Doc(DocID)

3是否容易使用
曾经见过一个高度复用的API,有3个参数,每个都可以互换的,结果简直成了Bug的温床
可以复用但是不能过度复用。

4 是否容易扩展
打个比方:A产品是基产品,B是A的衍生物,直接在A提供的API上面扩展。然后C又是B的衍生物,又在B的基础上衍生。
保持分层,每层keep simple and stupid,Unix的哲学思想得到应用。

以上....

评分

参与人数 1可用积分 +2 收起 理由
crazyhadoop + 2 很给力!

查看全部评分

论坛徽章:
1
2015年迎新春徽章
日期:2015-03-04 09:56:11
发表于 2015-02-26 11:44 |显示全部楼层
提示: 作者被禁止或删除 内容自动屏蔽

论坛徽章:
1
2015年迎新春徽章
日期:2015-03-04 09:48:00
发表于 2015-03-01 16:56 |显示全部楼层
提示: 作者被禁止或删除 内容自动屏蔽

论坛徽章:
1
2015年迎新春徽章
日期:2015-03-04 09:49:45
发表于 2015-03-02 11:59 |显示全部楼层
提示: 作者被禁止或删除 内容自动屏蔽

论坛徽章:
6
2015年辞旧岁徽章
日期:2015-03-05 16:13:092015年迎新春徽章
日期:2015-03-05 16:13:092015小元宵徽章
日期:2015-03-06 15:58:1815-16赛季CBA联赛之浙江
日期:2016-11-05 14:38:4115-16赛季CBA联赛之新疆
日期:2016-11-11 18:38:06
发表于 2015-03-03 16:12 |显示全部楼层
用十几二十年
您需要登录后才可以回帖 登录 | 注册

本版积分规则 发表回复

  

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

清除 Cookies - ChinaUnix - Archiver - WAP - TOP