背景

为了更方便的书写和阐述问题,文章中按照第一人称的角度书写。作为一个以java为主要开发语言的工程师,我所描述的都是java相关的编码和设计。

工程师的静态输出就是代码和文档,动态的就是各种应用程序(app,h5站点,微信公众号,小程序)。动态的先不讨论,主要讨论静态的。
随意查看一个代码库,可以看到代码的编写过程,某些代码可能在现在看来实现很低效和可笑,但是在当时的技术和时间场景下,肯定是最优的输出。
也可以在gitlab上看看每次的pull request ,看看当时对这些代码的codeReview ;
反馈出的问题就是程序的设计非常重要。而接口是功能的抽象,相对比较稳定,对团队来说影响比较大。

**

API设计原则


先给接口来个简单的定义:即协议,约定了请求和响应的参数和格式。

接口设计要求是:
1.简洁;
2.考虑到向后兼容;

业界有一些基本的原则:

1 restfull

restfull是一种设计风格,一切接口皆是资源。

目前是设计的主流,思想也非常先进。

2 参数结构化

请求和响应中的参数要结构化,好处是易读易用。

3 安全

这个怎么重要都不为过,接口设计必须考虑认证和授权,保证特定的人只能访问特定的资源。

同时需要注意在日志中不能含有用户和系统的敏感信息。

4 客户端无关

也就是接口要通用,可以处理不同客户端的请求。一般在接口设计的时候,可以带入透传参数,比如时区,位置(省市区),系统类型,系统版本,应用类型,应用版本等;

5 幂等

即接口的第一次请求的结果和后面N次的重试结果要不变,需要结合场景来保证。

API设计实践


接口框架选型

有了接口设计的原则,可以挑选一个可靠的接口框架来支持自己的工作,

一个好的接口框架应该有如下特点:

  1. 对访问控制的支持;
  2. 自动测试的支持;
  3. 请求响应格式和序列化的支持;
  4. 日志和日志过滤的支持;
  5. 自动生成文档的支持;
  6. 对架构和性能的影响较小;

我一般选的springmvc,因为平时工作跟spring贴合的比较紧,而且spring有各种生态,适合在不同的行业和公司使用。jersey也用,虽然灵活,但是不具备普遍适用性;

设计中的平衡

1 设定团队的API设计和实现模式

api太自由,会影响团队的协作,而共同约定api的设计模式和实现模式可以解决这个问题。

2 避免过度设计

要综合考虑向后的兼容性,但是只实现当前软件当前阶段必须的功能点。

3 谨慎使用AOP

面向切面编程可以在跟业务无关的垂直领域处理问题,比如日志,监控,解析等;可以提高代码的重用性和规范性;

但是也有缺点,比如,增加了测试和分析的难度,也对研发人员要求比较高。

所以需要综合考虑。

4 可维护性和性能之间要平衡

接口实现进行封装可以提高可维护性,但是也会带来性能开销,所以也是需要综合考虑的。

**

小结


通过本篇文章你可以学到如下内容:

  • [ ] 接口设计的原则
  • [ ] 接口设计框架选型要点
  • [ ] 接口设计过程中的设计实践问题

设计良好的接口,可以提高软件的复用性,提高团队的输出效率和质量。

原创不易,转载请注明出处。

0226 rest接口设计的更多相关文章

  1. 数据仓储之DLL层接口设计

    一.接口设计 1.1. IBaseRepository.cs public interface IBaseRepository<T> { T Add(T entity); bool Upd ...

  2. RESTful接口设计原则/最佳实践(学习笔记)

    RESTful接口设计原则/最佳实践(学习笔记) 原文地址:http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api 1 ...

  3. Web API接口设计经验总结

    在Web API接口的开发过程中,我们可能会碰到各种各样的问题,我在前面两篇随笔<Web API应用架构在Winform混合框架中的应用(1)>.<Web API应用架构在Winfo ...

  4. Verilog学习笔记简单功能实现(七)...............接口设计(并行输入串行输出)

    利用状态机实现比较复杂的接口设计: 这是一个将并行数据转换为串行输出的变换器,利用双向总线输出.这是由EEPROM读写器的缩减得到的,首先对I2C总线特征介绍: I2C总线(inter integra ...

  5. 优秀的API接口设计原则及方法(转)

    一旦API发生变化,就可能对相关的调用者带来巨大的代价,用户需要排查所有调用的代码,需要调整所有与之相关的部分,这些工作对他们来说都是额外的.如果辛辛苦苦完成这些以后,还发现了相关的bug,那对用户的 ...

  6. atitit.基于http json api 接口设计 最佳实践 总结o7

    atitit.基于http  json  api 接口设计 最佳实践 总结o7 1. 需求:::服务器and android 端接口通讯 2 2. 接口开发的要点 2 2.1. 普通参数 meth,p ...

  7. App接口设计

    关于APP接口设计 http://blog.csdn.net/gebitan505/article/details/37924711/

  8. App接口设计原则-b

    1.记住密码不是真的让你记住密码,这里仅仅指的是一种自动登录的手段.不管在任何地方,明文存储的密码都是安全隐患,是必须尽量避免的.你可以采用某种方式对用户名.密码以及时间戳(重要)进行签名,再次登录时 ...

  9. 蓝牙(BLE)应用框架接口设计和应用开发——以TI CC2541为例

    本文从功能需求的角度分析一般蓝牙BLE单芯片的应用框架(SDK Framework)的接口设计过程,并以TI CC2541为例说明BLE的应用开发方法. 一.应用框架(Framework) 我们熟知的 ...

随机推荐

  1. Nginx作为静态web服务器——缓存原理

    浏览器缓存 ​ 客户端无缓存的情况下 ​ 客户端有缓存的情况下 ​ 校验过期机制 ​ 本地客户端会检查Cache-Control(max-age)缓存是否过期,(max-age)为过期时间 Last- ...

  2. java面试题-spring篇

    这次是关于spring的面试题,和上次一样依旧挑了几个具有代表性的. 一.  谈谈你对 Spring 的理解 Spring 是一个开源框架,为简化企业级应用开发而生.Spring 可以是使简单的 Ja ...

  3. poj-1753题题解思路

    今天天气很好! 首先题意是这样的:: 翻盖游戏是在一个长方形的4x4场上进行的,其16个方格中的每一个都放置了双面的棋子.每一块的一边是白色的,另一边是黑色的,每一块都是躺着的,要么是黑色的,要么是白 ...

  4. 现在啊还不太清楚 nodejs和coffeescript 的关系

    我怎么会思考这个问题,今天看到用coffeescript做的一个服务引导 挺好 看博客里提 安装node之后 呢 npm 可以安装coffeescript 难道 coffee 是 node的 一个方言 ...

  5. selenium + PhantomJS使用时 PhantomJS报错解决

    selenium + PhantomJS使用时 PhantomJS报错解决 在做动态网页爬虫时用到了selenium + PhantomJS,安装好之后运行时报错: UserWarning: Sele ...

  6. Day6-Python3基础-面向对象编程

    面向过程 VS 面向对象 编程范式 编程是 程序 员 用特定的语法+数据结构+算法组成的代码来告诉计算机如何执行任务的过程 , 一个程序是程序员为了得到一个任务结果而编写的一组指令的集合,正所谓条条大 ...

  7. HDS协议介绍

    一.什么是HTTP Dynamic Streaming 使用传统的HTTP协议进行在线播放叫做“渐进下载”,所有的视频内容从头到尾必须从服务器传输到客户端,用户只能在传输完的视频长度中选择播放点,而不 ...

  8. Web自动化测试项目(三)用例的组织与运行

    一.Unittest用例组织 在test_case目录下创建test*.py,组织测试用例 ├── test_case │   ├── __init__.py │   └── test_login.p ...

  9. CTF--HTTP服务--路径遍历(提升root用户权限)

    开门见山 1. 在上次实验取的靶机低用户权限,查看该系统的内核版本 2. 查看该系统的发行版本 3. 查看该内核版本是否存在内核溢出漏洞,并没有 如果有内核溢出漏洞,则可以 4. 在靶机查看/etc/ ...

  10. redis5.0 Cluster集群搭建

    安装redis sudo apt update sudo apt install build-essential tcl cd ~ mkdir document/ cd document/ curl ...