上一节讲API的错误处理时，是java定义为例，讲述了正常结果、异常结果、常见异常、错误四种层次的划分，我把使用这种返回划分的风格的API叫做：protoapi。
protoapi适用于同一语言、同一进程内的API接口定义；同时也会适用于跨语言、跨进程的API接口，比方说常见的http + json的API。
在单一语言内，我们在设计类库，提供接口的时候，会使用语言提供的接口 interface对API做严格的定义。
我们使用类库的时候，看其接口，便可以对其提供的API有准确的认知，有多少个API，每个API需要的参数是什么，返回的结果是什么，异常是什么等等，都可以准确的知道；我们调用的时候，也会有编译器确保我们的调用API的方式是正确的。
当对于http + json的API时，API文档往往是以网页甚至word、excel的文件来提供文本描述。
这是糟糕的做法：
- 协议不明确
- API究竟有哪些？结果的属性有哪些？什么类型？
文本描述是非常容易含糊其事的，特别是对于那些直接粘贴返回结果json结构的文档。
- API究竟有哪些？结果的属性有哪些？什么类型？
- 难以版本化管理
- API是经常需要修改的，如何确保当前看到的excel文件里面记录的是最新的API？
- 调用不便
- 每个调用者都需要去自己开发一套“SDK”，重复定义文档中的结构是属于重复劳动
IDL
科学的做法，应该是引入一个IDL - Interface Definition Language对API做严格的定义。
thrift、protobuf/gRPC等都是优秀、成熟的IDL。
我曾经使用过thrift多年，在thrift的基础上做了各种二次开发，但这两年则逐渐切换为protobuf上，主要因为：
-
protobuf语法提供了一定的扩展能力 - 编译器
protoc有很好的插件机制，二次开发更加便利
还是以登陆为例，我们使用grpc作为为IDL的话，会是：
syntax = "proto3";
import "protoapi.proto";
package account_api;
message CommonError {
enum ErrorTypes {
UNKNOWN = 0;
INVALID_TOKEN = 1;
INVALID_PARAMETER = 2;
}
}
message LoginReq {
string username = 1 [(required) = true, (format) = "email"];
string password = 2 [(required) = true];
}
message User {
string username = 1;
int user_level = 2;
string nick = 3;
bool has_avatar = 3;
}
message AccountBalance {
uint64 amount_available = 1;
uint64 amount_due = 2;
}
message LoginResp {
User user = 1;
AccountBalance = 2;
}
message LoginError {
enum ErrorTypes {
UNKNOWN = 0;
INVALID_LOGIN = 1;
ACCOUNT_BANNED = 2;
}
ErrorTypes error = 1;
}
service Account {
option (CommonError) = FOO;
rpc login (LoginReq) returns (LoginError) {
option (BizError) = "LoginError";
}
}
HTTP + JSON
使用protobuf作为IDL，不意味着我们一定需要使用它默认绑定的http2以及二进制的序列化。
我们使用IDL，首先是要解决文本描述的文档的各种问题；然后，我们可以通过自行实现protobuf的插件，来实现包括服务器端API提供方，不同语言调用方SDK的代码生成。
而既然代码是我们自行生成出来，我们当然可以去实现使用 http + json。
具体到HTTP，protoapi推荐使用以下风格的实现：
URL
每个服务对应一个API endpoint，比方说：gateway.mydomian.TLD/api
在URL endpoint添加PATH，区分service以及method，比方说：
gateway.mydomian.TLD/api/Account/login
HTTP Method
- 所有API默认使用HTTP POST
- 特效场景下可以使用GET，但不鼓励
- 因为query string无法很好的对复杂请求对象做序列化
返回结果
使用以下不同的HTTP statuscode来区分不同的返回结果：
- 正常结果
Response：200 - 业务异常
BizError：400 - 框架异常
CommonError：420 - 错误
Error：HTTP 500- 当HTTP返回超时，或者遇到其它的序列化、传输问题时，也都应该认为是遇到错误
Error
- 当HTTP返回超时，或者遇到其它的序列化、传输问题时，也都应该认为是遇到错误
最后
protoapi所鼓励的，是划分结果、异常、错误等API风格；即便不使用任何IDL，代码生成，只要一套API对其返回结果做了划分，我们也可以说它是符合protoapi协议的。
后续我会在讲protoapi的代码生成实现（会开源！），以及讨论protoapi与restful、swagger等的关系。
