如何设计出优美的Web API？

本系列前序文章索引：

架构师，我们程序员打怪升级的主要方向，它不像某些技能报个培训班就能获得。胜任架构工作需要具备许多技能，既有硬技能还有软技能。俗话说：一口吃不成胖子。从程序员到架构师也无法一蹴而就，它是一个循序渐进、稳步提升的进阶过程，每个阶段都有每个阶段要掌握的技能，多项技能之间还存在先后顺序。如果想尽快转型升级至架构师，那你必须在日常工作中有意识地储备这些技能，接下来老兵哥结合亲身经历来给小伙伴们分享一下：

1. 硬技能

不像产品、管理等条线更加倚重通用技能，从技术条线转产品或管理，入门相对容易一些。但从产品或管理很难转型至架构，架构师必须从开发测试岗做起，在工作中不断提升专业技能和积累实践经验，从一个模块开始，到一个子系统，再到整个系统，最后到多个系统，这是一个循序渐进提升硬技能的过程，也可以看成构建架构师硬技能“点线面”。

1.1 点

老兵哥我刚入行时的岗位就是开发工程师，跟其他几个毕业生一起被安排在自动化测试平台项目组，整个系统由部门资深同事设计的，我们分别负责开发其中某个子系统的几个模块。这个阶段我主要关注函数、类和模块这个粒度，为了做好工作我要钻研编程语言 C/C++，以及熟悉 Visual C++ MFC、Socket 等代码库的使用。每周我们还会举行代码评审会议，邀请同事点评自己写的代码，那时候的自己年轻气盛，不管收到正面或负面的评价都会极大地激励自己。经过这个阶段的历练，我的编程技能得以较大的提升，也养成了较规范的编码习惯，掌握了如何设计好一个函数、类和模块。

这个项目前后做了两年左右时间，后面半年还做了些系统推广培训相关的事情。随后，我们又启动了采用脚本语言 Python 作为自动化测试脚本的自动化测试脚本，在这个项目我负责预研 Python 脚本解释引擎和开发测试代理子系统，这段项目经历让我跃升到子系统这个粒度。我需要考虑这个子系统在整个系统当中需要承担什么职责，以及跟其他子系统或被测系统之间的交互机制。同时，我还要负责这个子系统设计，确定它由哪些模块构成、每个模块内部包含哪些类等。

这个阶段让我具备了构建单个子系统的能力和信心，在后面的工作当中我还使用不同类型的编程语言构建过许许多多不同类型的子系统，但其实都是在强化构建单个点的能力，关联技能树包括：操作系统、编程语言、应用容器、开发框架、多线程等。

1.2 线

对于稍具规模的系统，它都免不了要划分成几个子系统，子系统之间或者与外部系统之间就需要连接通信，这相当于把两个孤立的点连接起来，即连点成线。这个过程跟开发单个子系统所需要的技能有所不同，它需要网络编程相关的知识技能。在老兵哥我刚参加工作的那些年，Web 应用还没有成为主流的应用形态，浏览器/服务器（B/S）架构还没有兴起，HTTP 协议尚未被广泛使用，当时最流行的就是客户端/服务器（C/S）架构，IP/TCP 才是最主要的通信协议，我就是在这个阶段积累下网络编程相关知识技能的。

最早我们要开发客户端或服务器程序，就需要熟悉掌握 Socket 网络编程，包括绑定监听端口、接受连接请求、并发处理请求等，从无到有全部自己编写，这些经验对于我后来理解网络通信机制有非常大帮助。为了满足子系统之间的交互需求，我们要基于 IP/TCP 协议来定制专门的应用层协议，包括制定报文头和报文体两层结构，虽然比 HTTP、FTP、SMTP等协议要简单，但这段经历让我对 HTTP 这类应用层协议的实现原理有了深刻的理解。另外，我们还要考虑报文内容过长时的分包组包、网络发生异常时的丢包重发，以及报文内容的编解码等。

因此，有志于在技术线发展的程序员都有必要补上这块技能。在近十五年的技术从业生涯中，老兵哥我前前后后解决过无数现网问题，其中有许多复杂的问题都跟系统交互通信有关，借助各种网络抓包分析工具抽丝剥茧，最后定位问题的根源都是没有正确使用网络协议，所以我很庆幸自己在过往的工作中有这段经历。

随着互联网的蓬勃发展，Web 应用成了最主要的应用形态，与此同时 HTTP 这种更人性化的网络通信协议成了最受欢迎的交互协议。从开发客户端/服务器（C/S）应用转到开发浏览器/服务器（B/S）应用的过程中，老兵哥我专门花时间学习了 HTTP 协议，了解其运行原理和控制机制，尤其是协议头中每个字段作用，包括请求方法、编码格式、超时机制、缓存机制等。印象最深刻的就是 Roy Thomas Fielding 博士发表了 REST 的论文《Architectural Styles and the Design of Network-based Software Architectures》，即《架构风格与基于网络的软件架构设计》，让我对 HTTP 有了全新的认知，这些知识技能对于理解掌握云计算时代的服务化架构非常有帮助。

除了 IP/TCP、HTTP 这两类协议之外，老兵哥我觉得还需要掌握消息队列（Message Queue）相关的协议，这类型协议更适合构建事件驱动架构的系统，不仅仅支持同步还支持异步。我曾经负责一个移动互联网的系统，其中有个子系统负责维护各种手机终端型号和设备信息，合作伙伴需要从这个子系统及时地获取最新信息，最初我们用 HTTP 协议轮询拉取的方式实现，但随着合作伙伴数量和信息更新频次的增加，这种信息同步机制就遭遇瓶颈了，后来我们通过引入消息队列中间件优雅地化解这个问题。

1.3 面

从点、线开始修炼，随着连线越来越多，最终将会形成平面，即分布式系统，这是我们程序员通往架构师路上必然经过的站点。刚开始我们仅仅利用互联网来发布搜索信息，接着我们的即时通信和社交也搬到了网上，再后来购物差旅等事情也可以通过互联网来完成了，现在跟我们衣食住行相关的所有事物都开始被互联网化了，这相当于虚拟世界被构建的越来越庞大越复杂。原先我们开发的软件系统复杂度还是有限的，它本身顶多被划分成几个子系统，需要关联交互的外部系统数量也非常有限。但随着业务越来越丰富，单个系统的复杂度也急剧增长，与之关联的外部系统也非常多，逐渐演变成一张纵横交错的网，也就是我们所说的“面”。如何在这样复杂的网络当中维护好复杂度，以及确保系统依旧满足易用性、性能、可靠性、稳定性、安全性等质量属性，这就需要程序员修炼分布式系统相关的技能。

老兵哥我在从事移动互联网相关系统研发的过程中遇到了更高复杂的场景，当时我们要构建一个苹果应用商店类似的生态体系，我们负责的系统本身由六七个子系统组成，它还需要跟许多上下游合作伙伴的系统对接交互。如果跟每个外部系统的对接都采用各自不同的标准，随着接入系统的数量越来越多，那对接相关的复杂度最终走向失控。另外，像应用订阅购买等典型业务场景都需要多个系统协作完成，其中涉及到分布式事务，怎样保证数据一致就是很大的挑战。按照常规逻辑，随着系统的复杂度不断提升，那么系统出现问题宕机的概率就会提升，但对于用户来说，他们依旧希望系统可以提供 7*24 小时的服务，不要出现服务超时或失效等异常情况，这就是“面”带来的挑战。

从那个阶段开始，我有了学习和实践分布式架构的机会。最早就是面向服务架构 SOA，即 Web Service、SOAP 等技术标准，站在现在回看那时候，这套技术栈是偏重偏繁琐的，但当时分布式系统对于整个业界都是全新的挑战，这套解决方案是由 Compaq、HP、IBM、Lotus、Microsoft、SAP 这些传统软件巨头们提出的。它通过 Web 服务描述语言 WSDL 来标准化分布式系统中的每个服务，再通过简单对象访问协议 SOAP 来规范服务之间的交互，从某个角度来看，越大规模的协作必须依赖统一的标准和规范。但传统软件巨头很少有在互联网第一线实践的经验，不像 BAT 他们对互联网分布式系统的挑战有那么真切的感受，阿里巴巴就在实践中孵化出了比 Web Service、SOAP 更加轻量化的 Dubbo，它也是依托面向服务架构 SOA 这套理论，只是是线上更加接地气。

这段工作经历让我对分布式架构有了体系化的认知，虽然近些年分布式技术从面向服务架构 SOA 演进至微服务架构 MicroService，技术中间件从 Dubbo 更替为 Spring Cloud，但我依然可以套用这套知识体系去理解新技术。

2. 软技能

软硬技能到底是怎么区分呢？老兵哥我觉得一个人靠哪门手艺吃饭，那么这门手艺相关的技能就是硬技能，而辅助硬技能产生更大价值的技能就是软技能，这跟“T”字型人才的要求类似，既要求有足够精湛拔尖的主攻技艺，也要有各式各样的综合技能。硬技能很重要，这点我相信没有人会反对，但也有不少人意识不到软技能的重要性。对技术人来说，从开发到架构，从架构到 CTO，或者从开发转产品或管理，不管是晋升还是转型，我们都是在加强硬技能的同时提升软技能的比重，甚至原先的硬技能变成了软技能，而原先辅助作用的软技能却成了硬技能。接下来，我将结合个人从开发转型架构的经历来谈一谈哪些软技能很重要：

沟通：相对于开发工程师，架构师的工作职责决定了他需要对接更多上下游客户，对沟通技能的要求就要高很多，毕竟不同角色的思维模式和立场角度各不相同，架构师必须懂得采用不同方式跟这些角色沟通互动，换位思考，从而挖掘到真实的需求，然后利用专业技能平衡好各方需求，最终输出各方都满意的架构方案。
写作：做开发岗时，我的主要输出就是代码。虽然偶尔也要写一些技术文档，但通常是供自己看的技术文档或者凑数用的产品操作使用说明。在转型做架构之后，我写代码的比重降低了，为了让各个干系人理解认可我的架构方案，除了口头说明之外，最主要就是靠技术写作，写给他人看的文档跟纯粹记录的完全不同。
设计：不管是口头沟通还是文档传播，语文或文字功底再好，也抵不过搭配上设计图例，图例中包含的信息是多个维度的，也更加直观易懂。通常，我习惯在写技术文档之前先把设计图画出来，画设计图的过程就是理顺思路的过程，在此基础上再来组织文字或语言变得更加简单容易，相当于是看图说话了。
演讲：权力和非职权影响力，架构师开展工作主要依赖于非职权影响力。架构师跟各个干系人之间不存在上下级关系，要让团队及合作伙伴认可并执行你的架构方案，你必须要靠自己的专业能力让对方信服。在以往学校教育或成长过程中，我本身是缺乏这方面的积累的，为了成功转型架构师我刻意训练提升自己这方面的能力。

总结起来说，为了在架构师这个新平台上做好工作，我们需要提升自己输入、设计和输出等方面的能力。以往我们从外界获取信息主要靠阅读文档，现在还要加强立体多方位的沟通。在输出方面，以往我们的输出形式太过单一，现在我们要掌握文字、演讲等多媒体方式。当然，最核心的还是架构设计的专业技能，这个输入输出的中心。

3. 知识体系

今天先分享到这里，老兵哥后续还会分享程序员到架构师的进阶指南等，包括每个阶段需要掌握的软硬技能图谱（如下图所示），文字提纲可以参考文章《从程序员到架构师，有捷径吗？》。如果你对这个主题感兴趣，千万要记得先关注哦！限于时间和版面，如果你想要下图的高清版，请先关注歪信公主号「 IT老兵哥 」，再发私信告知邮箱，我会尽快分享给你，谢谢！