API文档管理工具折射出的技术视野

什么是技术视野

网上看到很多关于如何提高技术视野的讨论，但却没有人给出定义，到底什么是技术视野？

所谓技术视野，就是看问题时所能切换的不一样角（维）度。

下面就以API管理工具（如下简称“管理工具”）为例，来探讨背后隐藏的技术视野。

API管理工具

零视角

曾经在一个小型创业公司用到过最简单的管理工具，就是一个开源的文档管理工具，界面功能相似wiki（维基百科）。

这样的工具确实能知足核心需求——API在线文档化，并支持用户管理。

但是深想一层，对于管理工具的使用者——工程师，操做足够友好，功能足够完善吗？

使用这类管理工具不少时候都会出现文档与代码不一致的状况，也就是说工程师都不肯意去维护这个文档。

由于编写修改文档是个耗费时间的事情，短时间来看，维护了既无利益，不维护也无危害~

因此有时候接口的变动经过口头协商而非文档协商。

小结：零视角其实谈不上视野，是大多数工程师的最容易造成的思惟方式，特色就是只关注功能/问题自己。

单一视角

当时为了解决上面的问题，同时为了练手所学的Node.js，我写了初版的管理工具，并参加了线下沙龙分享。

如今看来其实当初的写的项目仍是比较粗糙的，除了展现界面相较于wiki更加美观以外，主要加入了 Mock 功能。

更好的开源项目也有很多，好比阿里的RAP和国外的APIDOC。

之因此把它们归为一类讨论，那是由于它们都体现了开发者的单一视角。

RAP就是典型地站在前端工程师的角度开发的。

好比初版是以页面来对接口进行分组，这种分组方式显然不合理，后端之间的服务调用不涉及页面怎么办呢？因此第二版对此进行了修改。

又好比和 MockJS 深度绑定，为前端工程师提供 Mock 功能。

MockJS 确实很不错，不但支持数据模拟，还支持数据校验，后端也是使用前端工程师所熟悉的 Node.js 编写。

缺点呢后面在讲其余管理工具的时候再对比分析。

APIDOC则是站在后端工程师角度来编写，增长了经过代码注释生成文档的功能。

小结：视角的创建意味着从0到1的质变，技术视野开始造成。此视野的工程师再也不只关注功能实现或问题解决。

多视角

偶然间读到 Martin Fowler大神的一篇关于契约测试的文章很受启发，文中提出了一种构想，经过管理工具来对先后端进行校验，从而保障文档与代码的一致性。

因而开发了第2版的管理工具。这一版同时从先后端两个角度设计。

对于前端不只支持 Mock服务，同时还能对请求参数进行校验，甚至模拟服务端响应异常。
对于后端增长了相似 postman 调试接口功能，同时因为采用 JSON-Schema规范，能够直接将schema移植到后端代码中做为校验规则来校验参数。（RAP的局限性也在于此，MockJS的校验只能用于 Node.js和浏览器端，其它语言编写的服务端则没法使用。同时对于后端来讲也没有如 Mock 服务器般好用的调试功能。）

固然它和一些知名的管理工具 Swagger 、 RAML仍是有些差距，好比工具链不够丰富，不能经过注释生成代码。

小结：多视角的创建是从1到N的量变，而这个过程须要积累更多的经验，最终造成全局视野。

总结

常常看到一些公司在招聘高级前端工程师的时候会要求掌握一门以上后的端语言或者说把掌握后端语言做为加分项，真正的用意不必定会要求前端工程师写后端代码，但掌握后端语言的前端工程师会多一个思考维度，也就是技术视野更丰富。

不少工程师觉得本身和大神的差距是技术，但这种差距只是表象，而实质的差距是思惟方式和技术视野。

技术视野不同工程师，即便是作一样的事情，取得的成就也会不同，这也是为何我会在写书的时候注重帮助读者提高技术视野~

• 一个工程师作事情若是老是只考虑把事情完成，零视角解决问题，最多只能成为中级工程师。
• 能跳出事情自己，站在一个合理的角度进行思考，长久积累下来就能达到高级工程师的水准。
• 考虑事情的来龙去脉以及所在系统中的各类联动关系，已然是架构师的视野了。