全栈工程师修炼指南
熊燚(四火)
Oracle首席软件工程师
立即订阅
2286 人已学习
课程目录
已更新 43 讲 / 共 40 讲
0/4登录后,你可以任选4讲全文学习。
课前必读 (3讲)
开篇词 | 从成长角度看,为什么你应该成为全栈工程师?
免费
学习路径 | 怎样成为一名优秀的全栈工程师?
导读 | 如何学习这个专栏?
第一章 网络协议和 Web 接口 (6讲)
01 | 网络互联的昨天、今天和明天:HTTP 协议的演化
02 | 为HTTP穿上盔甲:HTTPS
03 | 换个角度解决问题:服务端推送技术
04 | 工整与自由的风格之争:SOAP和REST
05 | 权衡的艺术:漫谈Web API的设计
06 | 特别放送:北美大厂如何招聘全栈工程师?
第二章 欢迎来到 MVC 的世界 (7讲)
07 | 解耦是永恒的主题:MVC框架的发展
08 | MVC架构解析:模型(Model)篇
09 | MVC架构解析:视图(View)篇
10 | MVC架构解析:控制器(Controller)篇
11 | 剑走偏锋:面向切面编程
12 | 唯有套路得人心:谈谈Java EE的那些模式
13 | 特别放送:选择比努力更重要
第三章 从后端到前端 (7讲)
14 | 别有洞天:从后端到前端
15 | 重剑无锋,大巧不工:JavaScript面向对象
16 | 百花齐放,百家争鸣:前端MVC框架
17 | 不一样的体验:交互设计和页面布局
18 | 千言万语不及一幅画:谈谈数据可视化
19 | 打开潘多拉盒子:JavaScript异步编程
20 | 特别放送:全栈团队的角色构成
第四章 数据持久化 (7讲)
21 | 赫赫有名的双刃剑:缓存(上)
22 | 赫赫有名的双刃剑:缓存(下)
23 | 知其然,知其所以然:数据的持久化和一致性
24 | 尺有所短,寸有所长:CAP和数据存储技术选择
25 | 设计数据持久层(上):理论分析
26 | 设计数据持久层(下):案例介绍
27 | 特别放送:聊一聊代码审查
第五章 寻找最佳实践 (6讲)
28 | Ops三部曲之一:配置管理
29 | Ops三部曲之二:集群部署
30 | Ops三部曲之三:测试和发布
31 | 防人之心不可无:网站安全问题窥视
32 | 和搜索引擎的对话:SEO的原理和基础
33 | 特别放送:聊一聊程序员学英语
第六章 专题 (7讲)
34 | 网站性能优化(上)
35 | 网站性能优化(下)
36 | 全栈开发中的算法(上)
37 | 全栈开发中的算法(下)
38 | 分页的那些事儿
39 | XML、JSON、YAML比较
40 | 全栈衍化:让全栈意味着更多
全栈工程师修炼指南
登录|注册

05 | 权衡的艺术:漫谈Web API的设计

四火 2019-09-20
你好,我是四火。
今天,我们该根据之前所学,来谈谈具体怎样设计 Web API 接口了。我们围绕的核心,是“权衡”(trade-off)这两个字,事实上,它不只是 Web API 接口设计的核心,还是软件绝大多数设计问题的核心。
我们说“没有银弹”,是因为没有一种技术可以百搭,没有一种解决方案是完美的,但一个优秀的全栈工程师,是可以从琳琅满目的同类技术中,因地制宜地选择出最适合的那一个。

概念

在一切开始之前,我们先来明确概念。什么是 Web API?
你应该很熟悉 API,即 Application Programming Interface,应用程序的接口。它指的就是一组约定,不同系统之间的沟通必须遵循的协议。使用者知道了 API,就知道该怎样和它沟通,使用它的功能,而不关心它是怎么实现的。
Web API 指的依然是应用程序接口,只不过它现在暴露在了 Web 的环境里。并且,我们通常意义上讲 Web API 的时候,无论是在 B/S(浏览器 / 服务器)模型还是 C/S(客户端 / 服务器)模型下,往往都心照不宣地默认它在服务端,并被动地接受请求消息,返回响应。
通常一个 Web API 需要包括哪些内容呢?
回答这个问题前,让我们先闭上眼想一想,如果没有“Web”这个修饰词,普通的 API 要包括哪些内容呢?嗯,功能、性能、入参、返回值……它们都对,看起来几乎是所有普通 API 的特性,在 Web API 中也全都存在。而且,因为 Web 的特性,它还具备我们谈论普通 API 时不太涉及的内容:
取消
完成
0/1000字
划线
笔记
复制
© 版权归极客邦科技所有,未经许可不得传播售卖。 页面已增加防盗追踪,如有侵权极客邦将依法追究其法律责任。
该试读文章来自付费专栏《全栈工程师修炼指南》,如需阅读全部文章,
请订阅文章所属专栏。
立即订阅
登录 后留言

精选留言(11)

  • panlatent 置顶
    结合上一讲内容,想问问老师对 graphql 的看法,以及如何权衡 graphql / rest 两种api 。

    作者回复: 这其实是个很好的问题。

    我对 GraphQL 的理解简单来说是这样的,仅供参考。它本质上是一种声明式的 DSL,把接口逻辑从服务端拿到客户端来,客户端来决定做什么查询,执行什么操作,资源的概念被彻底弱化了。

    和基于资源的 REST 相比,因为可以更加细粒度地控制需要什么数据,减少了多次调用或者是不需要的数据返回造成的开销。当然,它也有许多弱点,比如复杂性更高(客户端需要理解复杂的业务数据模型),不容易使用缓存等等。

    我觉得它应该是 REST 风格的一种补充,而不是绝对的替代。有很多场景,比如复杂的数据查询,使用 GraphQL 可以做得很灵活,且有比较高的效率。而多数业务场景,REST 确是更好的选择。

    2019-09-21
    4
  • tt 置顶
    1、突然有个想法,通过路径传递参数相当于非web系统设计的定长报文或固定分隔符报文,可读性比较差,可以更多的实现对外部的信息隐藏。

    而通过query参数传递相当于URL承载的键值对报文,可读性比较好。

    实现上,通过路径传递的话,在后端实现url解析即请求路由的时候需要完成参数的判断,使用一些开发框架可能更简单,但是这个过程不是完全由实现业务的人来控制,是不是会影响整个系统的扩展性以及处理效率呢?

    所以我觉得通过路径传递参数适合参数种类及个数比较少的情况,


    2、对于银行转账如何用rest风格设计接口,我觉得可以用“变换”的思维,把转账这个动作“变换”或“视作”为一个创建一笔“转账”业务对象的操作,这个业务对象有若干属性,比如收付款账号、金额等,从而继续使用rest风格。

    此外,老师有没有关于web api鉴权和授权方面的参考链接呢?

    作者回复: 感谢回答。
    关于 1,我觉得你说得很好。路径传递“隐含”了这个 key,而使用 Query String 的键值对的方式,则显式指定了 key。从这个角度来说,确实后者更为“明确”。

    但是,“可读性”并不一定是指定了 key 的更好,可读性毕竟是一个和个人理解密切相关的判断。通常在路径层次较短,且路径的定义符合人的认知的时候(比如“资源/分类/唯一ID”,这样由大到小的递进),路径传递参数的方式也具有很高的可读性。

    在使用框架处理的难度方面,我认为这两种方式并没有太大区别。

    另外,使用 Query String 的方式灵活性上要更高,比如可以通过合理的配置自动构造和注入一个复杂的参数对象,这方面我们会在下一章学到。

    关于 2,说得非常好,这种把一个复杂行为转变为可进行 CRUD 的“资源”,就是一种很有效的处理方法。

    对于你最后关于鉴权和授权的问题,我计划在第 5 章谈到。

    2019-09-20
    4
  • alan
    老师,为啥说204是最常见的返回码?不是200吗?

    作者回复: 看场景了。对于 Web API 来说,如果是一个命令接口,常常见到返回 204,表示操作成功,但不需要消息体。

    2019-09-22
    2
  • huihui
    四火老师推荐的Any API 这个很不错,很赞!
    2019-10-10
  • 邢浩锋
    老师好,文中提到的web API ,构建这样的API需要学习哪些技术?
    2019-10-03
  • pyhhou
    1. 感觉有点类似大接口和小接口,把 category 放在路径上相当于小接口,因为我们可以分开考虑并实现不同 category 的 API 组,优点是从 URL 上面看比较直观;如果把 category 放在参数中,那么必须要先对 category 进行判断后,再进行逻辑的拆分。对于参数值的种类不多,参数之间联系不多的情况,可以将参数放在路径上面,参数值的种类多的情况可以考虑放在 query_string 上,实际设计的话可以两者搭配使用

    2. 如果要使用 REST 也是可以使用的,可以考虑将这个转账的行为进行抽象,比如用一个 unique ID 表示用户执行的操作是 “转账”,然后带上相关数据。总之是让客户端和服务器达成一个共识

    API 设计经验不多,说的不好的地方还请老师指出

    这一章学完,了解了很多自己之前没有接触过的概念,感觉这一章总体来说理论偏多一些,想要学得更加透彻肯定还是需要自己下去多动手尝试,可能现在学的东西只是一些知识点,需要跟完整个专栏,然后有一定经验后才能横向对比,对某些层面的东西才会有更深的认识,这也是一个过程,慢慢来吧

    作者回复: 👍

    2019-10-01
  • jxs1211
    sql建议使用pk进行查询,如果使用name这样的业务相关的字段进行查询,可以提高理解性,是否也应该加索引,提高查询效率
    2019-09-23
  • leslie
    问题、技术、风格和定义:这个似乎不止在web api的设计中会有这个问题,我觉得在现在的数据系统/存储中间件 的设计中其实现在典型的出现了;毕竟现在一旦设计软件就不是过去传统的C/S或B/S。
          昨天一个同行问我一个问题:我们有前端开发,我们需要架构师;我就反问了一句“你们需要的是什么架构?”分析"问题"、寻找“技术"、选择“风格”、定义"需求"。架构师这个已经有点泛泛了:就像全栈一样,好的全栈其实才是一个好的架构师-他能权衡从前端-开发-数据系统-网络设计。各种模块的权衡才是最困难的事情;老师觉得呢?其实很多架构师都是有明显的缺陷的。
           老师说权衡的艺术:其实好的全栈才能成为一个好的架构师,否则我们只能去说软件架构、数据系统架构、网络及安全架构;老师怎么看?

    作者回复: 这个问题太大,不是很好回答。个人觉得这两个概念基本上还是在两个不同维度上,不是很适合放到一起比较。:)

    2019-09-23
  • 饭团
    我感觉路径选择不够灵活,因为他默认了各级参数所对应的含义!在需要加入参数或者调整参数顺序的时候就会带来诸多不便!我看到的大部分对外接口都是在指定到特定目录后(应该是该功能的功能模块),参数通过或则query_string的形式传输过来!
    也就是说如果一个接口使用纯路径选择,是不是就适合于功能较为简单,参数偏少的情况!而大部分情况都是混合使用

    作者回复: 👍,说得很好。

    2019-09-21
  • anginiit
    一直只关心技术 对于设计思想层面的考虑为0,这篇文章对我来说读的一头雾水。学习,学习。。。
    2019-09-20
  • 编程爱好者
    全栈工程师不是技术方面的问题,而是灵魂是否有趣的问题,很喜欢作者结尾分享的链接,这门课程是告诉我们如何成为一个有趣的程序员

    作者回复: 感谢评价!

    2019-09-20
收起评论
11
返回
顶部