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的量变，而这个过程需要积累更多的经验，最终形成全局视野。

总结

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

很多工程师以为自己和大神的差距是技术，但这种差距只是表象，而实质的差距是思维方式和技术视野。

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

• 一个工程师做事情如果总是只考虑把事情完成，零视角解决问题，最多只能成为中级工程师。
• 能跳出事情本身，站在一个合理的角度进行思考，长久积累下来就能达到高级工程师的水准。
• 考虑事情的前因后果以及所在系统中的各种联动关系，已然是架构师的视野了。