如何正确合理的设计一个接口项目

标签: 正确 设计 接口 | 发表时间:2013-09-29 01:15 | 作者:wangpeng047
出处:http://blog.csdn.net

首先,我这里说明接口,不是代码里的接口,而是接口项目,如果想错了就不用往下看了。

在手机广泛流行的今天,手机应用也随之越来越多,而且成长的速度也非常快。手机应用软件开发实现方式同普通PC软件一样,也分为BS和CS方式。而采用CS方式,在服务器端大多采用接口的形式提供数据交互(主流数据交互方式有:Json、WebService等),今天要说的就是如何设计接口。

接口作为连通客户端与数据库进行数据流通的桥梁,起着举足轻重的作用,直接影响着程序的效率性、稳定性、可靠性以及数据的正确性、完整性。客户端注重的是界面美观,操作方便顺畅,是用户最直接的感受体验,而接口则是所有数据的提供者,是用户深层的内涵体验。

因次,设计接口在一个项目中,是非常重要的。那么我就目前的经验总结下如何合理设计接口。

一、 设计原理

1. 深入了解需求

除了设计数据库的人最了解需求外,其次就是设计接口的人了,甚至有时接口开发人员还要参与到数据库设计中。从“客户端-接口-数据库”的层次上看,接口明显扮演着承上启下的角色,一方面要明白接口要什么数据,另一方面要考虑如何从数据库获取、组织数据。所以如果不了解需求,你就无法正确抽象对象来组织数据给客户端,也无法验证数据库的数据结构能否满足需求。数据库设计者要了解需求中的数据结构,而接口则更多的要了解需求中的逻辑结构以及由此衍生出的逻辑数据结构。

2. 了解数据库结构

既然接口要明白如何从数据库获取、组织数据,就当然要了解数据库结构啦。

3. 了解客户端原型

了解原型,其实更多是为了帮助你设计接口时需要提供的数据和结构。但有时当你设计时并没有原型,所以此条并不是必须要求的。但假如设计完接口后原型出来了,我们也可以拿原型还验证接口设计是否正确、合理。

二、设计原则

1. 充分理由

不是随便一个功能就要有个接口,也不是随便一个需求就要加个接口。每新建一个接口,就要有充分的理由和考虑,即这个接口的存在是十分有意义额价值的,无意义的接口不仅增加了维护的难度,更重要是对于程序的可控性的大大降低,接口也会十分臃肿。因此我放在了第一条。

2. 职责明确

一个接口只负责一个业务功能,它与设计模式里的职责单一原则类似但却不同,因为一个业务功能里可能会包含多个操作,比如查询会员,可能除了查询会员表外还要获取该会员的其他必要信息,但不要在查询会员的同时还有修改权限等类似的其他业务功能,应该分成两个接口还做。

3. 高内聚低耦合

一个接口要包含完整的业务功能,而不同接口之间的业务关联要尽可能的小。还是查询会员的例子,有时查询会员的同时,可能该会员的相关信息要随之发生变化(如状态),如果这时一条完整的业务流水线,那么就应该在一个接口里完成,而不应再单独设立接口去操作完成。就是说一个接口不应该随着另一个变化而变化或以某几个接口为前提而存在。

4. 分析角度明确

设计接口分析的角度要统一明确。否则会造成接口结构的混乱。例如,不要一会以角色的角度设计,一会儿就要以功能的角度设计。

5. 入参格式统一

所有接口的参数格式要求及风格要统一,不要一个接口参数是逗号分隔,另一个就是数组;不要一个接口日期参数是x年x月x日风格,另一个就是x-x-x。

6. 状态及消息

提供必要的接口调用状态信息。调用是否成功?如果失败,那么失败的原因是什么。这些必要的信息必须要告诉给客户端。

7. 控制数据量

一个接口返回不应该包含过多的数据量,过多的数据量不仅处理复杂,对数据传输的压力也非常大,会导致客户端反应缓慢。过多的数据量很多时候都是接口划分不明确。

8. 禁止随意拓展参数

与第1条类似,只不过是针对参数而言了。日后拓展接口可能是难以避免的,但是不要随意就加参数,加参数一定是必要且有意义的,需求改变前首先应考虑现有接口内部维护是否能满足需求,而不要通过加个参数来方便自己实现需求的难度,因为参数的更变会直接导致客户端调用的变化,容易产生版本兼容性问题。

三、设计方法

1. 抽象业务

相比抽象对象而言,抽象业务更宏观,我觉得相对也容易一些,但抽象尺度往往不太好把握。

2. 数据格式

接口定义的数据格式必须都经过充分考虑,否则会出现数据转换失败或超出长度等错误。如果无法确定,直接设置成字符串是最合适的。

3. 有意义的命名

无论是接口还是参数,名称都应该是有意义的,让人能看明白的。

 

总之,接口设计是一个细致的工作,设计时也会有很多矛盾,但个人倾向于粗粒度设计方向(即内聚性更高一些),这样不仅给客户端浏览接口方便明确,维护也轻松些,这么做的缺点就是某一接口扩展时不是很灵活,但可以通过重新定义一个接口来弥补,但正如上所说,新增接口还是要三思而后行的。以上很多虽然都是理论性讲解,但牢牢记住这些,并结合实际工作,就会慢慢深刻的体会到其中的含义。即理论指导实践,实践来验证理论。

作者:wangpeng047 发表于2013-9-28 17:15:26 原文链接
阅读:106 评论:1 查看评论

相关 [正确 设计 接口] 推荐:

如何正确合理的设计一个接口项目

- - CSDN博客架构设计推荐文章
首先,我这里说明接口,不是代码里的接口,而是接口项目,如果想错了就不用往下看了. 在手机广泛流行的今天,手机应用也随之越来越多,而且成长的速度也非常快. 手机应用软件开发实现方式同普通PC软件一样,也分为BS和CS方式. 而采用CS方式,在服务器端大多采用接口的形式提供数据交互(主流数据交互方式有:Json、WebService等),今天要说的就是如何设计接口.

API 接口设计规范

- - 掘金后端
这篇文章分享 API 接口设计规范,目的是提供给研发人员做参考. 规范是死的,人是活的,希望自己定的规范,不要被打脸. url?后面的参数,存放请求接口的参数数据. 请求头,存放公共参数、requestId、token、加密字段等. Body 体,存放请求接口的参数数据. 调用方需向服务方申请 appKey(请求时使用) 和 secretKey(加密时使用).

接口设计评审规范 - 简书

- -
本接口设计规范,参考了restfull的部分设计理念. Restful API的核心元素,所有的操作都是针对特定资源进行的. 任何事物,只要有被引用到的必要,它就是一个资源. 资源可以是实体(例如手机号码),也可以只是一个抽象概念(例如价值). Github 可以说是这方面的典范,下面我们就拿. 资源分为单个文档和集合,尽量使用复数来表示资源,单个资源通过添加 id 或者 name 等来表示.

设计好接口的36个锦囊

- - 掘金后端本月最热
大家好,我是捡田螺的小男孩. 作为后端开发,不管是什么语言, Java、 Go还是 C++,其背后的后端思想都是类似的. 后面打算出一个后端思想的技术专栏,主要包括后端的一些设计、或者后端规范相关的,希望对大家日常工作有帮助哈. 我们做后端开发工程师,主要工作就是: 如何把一个接口设计好. 所以,今天就给大家介绍,设计好接口的36个锦囊.

API设计新思维:用流畅接口构造内部DSL

- 风子 - 酷壳 - CoolShell.cn
感谢@weidagang (Todd)向酷壳投递本文. 程序设计语言的抽象机制包含了两个最基本的方面:一是语言关注的基本元素/语义;另一个是从基本元素/语义到复合元素/语义的构造规则. 在C、C++、Java、C#、Python等通用语言中,语言的基本元素/语义往往离问题域较远,通过API库的形式进行层层抽象是降低问题难度最常用的方法.

[原]增量接口的设计及实现

- - 高爽|Coder
在应用开发过程中,我们总会碰到这样的场景:某系统需要同步我们系统的数据去做一些业务逻辑,当数据量较小的时候,可以全量的提供,但当数据量很大时,全量提供就显得很笨重,不仅耗时而且做了很多无用功,这时我们需要一种提供增量数据的机制,只告诉对方变化的数据. 提供增量数据大致可分为两种方式:MQ和接口提供,MQ的优点是及时,缺点是丢失、重复、回溯复杂等等问题(依赖于具体MQ实现),这里不过多赘述;接口提供不限于RPC或HTTP等方式,接口提供的优缺点正好和MQ反过来,及时性取决于调用周期.

从 Feign 使用注意点到 RESTFUL 接口设计规范 - ImportNew

- -
最近项目中大量使用了Spring Cloud Feign来对接http接口,踩了不少坑,也产生了一些对RESTFUL接口设计的想法,特此一篇记录下. SpringMVC的请求参数绑定机制. 了解Feign历史的朋友会知道,Feign本身是Netflix的产品,Spring Cloud Feign是在原生Feign的基础上进行了封装,引入了大量的SpringMVC注解支持,这一方面使得其更容易被广大的Spring使用者开箱即用,但也产生了不小的混淆作用.

API接口设计之token、timestamp、sign具体实现

- - 企业架构 - ITeye博客
Token:访问令牌access token, 用于接口中, 用于标识接口调用者的身份、凭证,减少用户名和密码的传输次数. 一般情况下客户端(接口调用方)需要先向服务器端申请一个接口调用的账号,服务器会给出一个appId和一个key, key用于参数签名使用,注意key保存到客户端,需要做一些安全处理,防止泄露.

API 接口设计之 token+sign 具体架构与实现

- - 小决的专栏
在实际的业务中,难免会跟第三方系统进行数据的交互与传递,那么如何保证数据在传输过程中的安全呢(防窃取). 除了 https 的协议之外,能不能加上通用的一套算法以及规范来保证传输的安全性呢. Token:访问令牌 access token, 用于接口中,用于标识接口调用者的身份、凭证,减少用户名和密码的传输次数.

聊聊接口设计的36个小技巧

- - IT瘾-dev
作为后端开发,不管是什么语言, Java、 Go还是 C++,其背后的后端思想都是类似的. 后面打算出一个后端思想的技术专栏,主要包括后端的一些设计、或者后端规范相关的,希望对大家日常工作有帮助哈. 我们做后端开发工程师,主要工作就是: 如何把一个接口设计好. 所以,今天就给大家介绍,设计好接口的36个锦囊.