上一节讲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是经常需要修改的，如何确保当前看到的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

最后

protoapi所鼓励的，是划分结果、异常、错误等API风格；即便不使用任何IDL，代码生成，只要一套API对其返回结果做了划分，我们也可以说它是符合protoapi协议的。

后续我会在讲protoapi的代码生成实现（会开源！），以及讨论protoapi与restful、swagger等的关系。