disallow: /api.php,API的设计(5) - 细节与填坑

(我认为开放源码还称不上是开源；一个项目需要有社区、有成功的第三方使用案例等等，才能称得上开源。)

目前protoapi的实现代码仍显粗糙；很多地方还需要长期的打磨甚至不排除推倒重来；但现在目前的版本应该是可以先放出来给大家玩玩了；开源的这个版本go/ts的两个gen应该能够使用；而最早实现的Java跟最后实现的php则未经过测试。

我对于protoapi的设计目标是这样：

推崇强类型的API，即尽可能拒绝弱类型、动态类型甚至是无类型

强调错误处理；业务应该充分考虑异常流程

开发效率优先；即如果工程师使用protoapi去处理API，他开发效率应该是提升的

这篇我想先写写实现protoapi时的一些具体小细节，以及填的一些坑。

proto文件编辑

推荐使用VS Code编辑proto文件，并且安装vscode-proto3插件，这样，在编辑proto文件的时候，可以有很好的语法高亮、自动补全以及自动格式化：

vsproto.gif

注意，proto文件的自动格式化依赖于clang-format

模板编辑

protoapi使用了大量的代码生成技术；代码模板则都是使用go内置的text/template库实现。

自go 1.6开始，text/template库增强了空白字符的控制之后，我便认为这是用于代码生成的最佳模板引擎之一。

使用VS Code编辑对于go模板也有非常不错的插件支持：gotemplate-syntax

gotemplate-syntax插件的作者也是go-swagger的主程，可能大家都想到一块去；这次我搞protoapi，就顺手给gotemplate-syntax提了PR，增加对Java / Go / TypeScript / PHP这四个语言的支持；我的PR已经被合并在了gotemplate-syntax 0.3.0版中，直接使用VS Code安装即可用。

.gots的TypeScript模板文件语法高亮

前端错误处理 与 Promise

axios是流行的HTTP js客户端库，特别是很多基于vue的项目会选择axios作为跟服务器端通讯的底层库。axios默认是假设调用的是服务器端的JSON API，它对服务端返回的json格式的错误处理方式却相当粗暴：

axios直接忽略JSON parse异常

axios的作者对这个问题在15年初就自己提了个issue，但至今没有close。

我会认为，调用服务器端JSON API时，如果返回的JSON不合法，是需要被显示处理的，比方说，调用服务器的登陆API：

axios.post('/login', {

username: 'abc',

password: 'xyz'

})

.then(function (resp) {

console.log(resp);

})

.catch(function (error) {

console.log(error);

});

登陆成功后，服务器端返回的是一个包含用户profile信息的JSON对象。而如果这个JSON信息不合法，程序应该直接进入到.catch的函数中；而不是.then；但axios库的默认做法，则是进入会进入到.then中。

根据Promise的规范，then函数是会返回一个新的Promise对象，也就是说，如果then里面的函数如果对resp进行操作，引发异常，也是会被后面的catch捕获。

但与此同时，如果在then里面返回Promise.reject，亦同样会被紧跟着catch捕获；这会使得错误处理非常麻烦。

甚至！更麻烦的是，如果这里使用的还是jQuery，jQuery 1.X或2.X版本的promise实现并没有遵循上述规范，关于jQuery的这个天坑具体可以参考Promises/A+以及ES6规范作者Domenic Denicola的博文：You're Missing the Point of Promises

jQuery 3.0才终于对此做了修改。

当然，更彻底的做法是干脆不用Promise，使用async / await风格的API；后续protoapi会提供async风格的ts gen支持。

服务器端校验

服务器端对于传入的json数据严谨性也往往被忽视，比方说，一个API接受的JSON对象参数是：

{

"username":"XXX",

"password":"XXX",

}

但客户端调用的时候，却传成了：

{

"user_name":"XXX",

"pass":"XXX",

}

几乎所有的服务器端框架都不会报错，而是默默的认为收到空的用户名、密码；然后返回用户名、密码错误。

这样的错误往往非常难以debug；但在日常开发中却很容易发生。

protoapi认为，如果一个接口收到的参数属性与协议不一致的时候，应该直接报错。

go 1.10对内置的JSON decoder增加了DisallowUnknownFields选项；protoapi的go gen使用的web框架是echo，默认启用更加严谨的json API binder。

总结

proto文件、模板文件的自动格式化、语法高亮实际上也是为了让我们在编辑的时候如果有错误，可以通过排版、高亮快速定位到错误。

所有这些，都是希望让我们的代码可以有更加严谨的错误处理规范，日常开发中我们不怕程序出错，而是怕程序出错的时候我们无法知道；进而提(jian)高(shao)开(jia)发(ban)效率。

后面我会继续讲protoapi的实际使用。