在 Web 系统中，前端通过 HTTP 请求给后端传递参数有四种方式，可以将参数放在请求路径、Query 参数、HTTP 协议头、HTTP 协议体中。而放在协议体中的参数又有很多格式，比如 json、form 表单等。当然，前端也可能选择其他协议，比如 Websocket、gRPC-Web 等，具体的参数形式跟 HTTP 又不一样。
面对这么多种技术实现方式，当我们要设计一套 Web 系统时，该如何选择呢？应当遵守什么样的规范呢？这就是我接下来要给你详细介绍的。
RESTful 解决什么问题？
首先，我们来看下三个时间点：
1991 年 HTTP 0.9 诞生
1996 年 5 月 HTTP 1.0 诞生
1997 年 1 月 HTTP 1.1 诞生
在 HTTP 1.0 出现以前，也就是 HTTP 0.9 时代，HTTP 协议只支持 GET 请求，所有参数只能通过 URL 传递。比如一个获取动态网页的请求可能是这样的 GET /index.php?page=hello&user=1234&action=view 。
在 HTTP 1.0 出现后，开始有了 POST 请求和 HEAD 请求，支持从 HTTP 协议头和协议体传参数。但 HTTP 1.0 并没有解决每次请求都需要建立新连接的问题，然后 HTTP 1.1 很快就出现了。
HTTP 1.1 除了能保持连接外，还新增了多种方法，如 PUT、DELETE、PATCH、OPTIONS。虽然功能更强大，体验更丰富了，却带来了新的问题：这些方法该如何选择呢？比如我要上传数据，到底是用 POST 、PUT 还是 PATCH 呢？这无疑增加了选择成本。
随后，REST（ Representational State Transfer，表现层状态转移） 出现了，简单来说它就是一组架构约束条件和原则，而符合 REST 规则的设计便是 RESTful。
因为 HTTP 协议本身是无状态的，但后端数据是有状态的，如何用无状态的协议来操作有状态的数据就比较有挑战。比如，当只用 GET 请求的时候，你无法从请求参数上直观判断到底是对数据做什么操作，因为大家对 GET 请求参数命名没有统一规范。在前面的例子中，action=view 也有可能被定义成 a=v。
RESTful 是如何解决这个问题的呢？它充分利用了各种 HTTP 请求方法的特点，来表达对数据的具体操作方式。比如当你要新增数据时，应当用 POST 方法；要整个替换数据时，应当用 PUT 方法；仅仅是替换数据的部分字段时，应当用 PATCH 方法；如果是删除数据，应当用 DELETE 方法。这样一来，对数据的操作就清晰明了。
RPC 解决什么问题？
RPC 的全称叫 Remote Procedure Call，也就是远程过程调用。它和 REST 都是客户端向服务端发起请求的技术手段。
前面提到了 RESTful 能解决很多问题，但为何还需要 RPC 呢？
首先，前面提到了从 HTTP 1.0 开始，HTTP 协议增加了很多功能。在 HTTP2 出现前，HTTP 协议内容都是文本格式，功能越来越多导致协议内容变得越来越臃肿。在一些高性能场景下，特别是系统内部服务之间频繁请求的时候，臃肿的协议会带来不少网络开销，影响服务性能。而 RPC 在底层协议可以选择直接使用 TCP 这种长连接，协议内容可以做到比较精简。RPC 还可以对数据进行压缩后再传输，性能要比 HTTP 好很多。
其次，RESTful 只是一种约定，而不是一种强制规范，你可以遵守，也可以不遵守。这就导致不同技术水平的人，实现出来的接口风格和行为不一致。
比如，新手程序员在用 HTTP 协议实现 API 的时候，可能不小心给客户端多返回一些额外的数据，客户端也不一定会报错，但却存在数据泄漏的风险。而 RPC 通常利用像 protobuf 这种 IDL （Interactive Data Language ，交互式数据语言）来定义接口规范，并生成客户端和服务端的框架代码。
其中，IDL的作用是定义客户端和服务端之间的数据交互方式，利用生成的框架代码，在双方开发代码时形成强约束，是契约式编程的一种体现。在使用 RPC 的时候，服务端只能返回 IDL 中定义的数据，否则使用框架代码时会报错。
目前，主流跨平台 RPC 协议主要有 Thrift 和 gRPC。Thrift 是由 Facebook 开源的，底层主要基于 TCP 传输数据。而 gRPC 是由谷歌开源的，底层基于 HTTP2 协议。gRPC 由于支持丰富的中间件以及双向流模式，具有很强的易用性，应用越来越广泛。比如，ETCD 就提供了 gRPC 接口。
秒杀 API 设计
**秒杀系统中的 API 主要有两大块：API 服务、Admin 服务。**接下来，我将给你介绍下 RESTful 和 gRPC 在这两个服务中的应用。
API 服务 API 设计
根据我们之前做的需求分析，秒杀 API 服务主要给用户提供活动信息和抢购商品的功能。那么，秒杀 API 服务的 API 应当分为活动信息和抢购这两组，我们分别用 event 和 shop 来表示。
在 event 功能中，我们需要提供三个接口给前端：
第一个是 /event/list ，采用 GET 方法，用于获取所有正在进行或者即将进行的活动列表；
第二个是 /event/info，采用 GET 方法，用于查询某个商品当前的秒杀活动信息，参数是商品 ID；
第三个是 /event/subscribe，采用 POST 方法，用于订阅某商品的活动开始通知，参数是活动场次 ID 、商品 ID、设备 ID。
在 shop 功能中，我们只需要提供一个抢购接口即可：/shop/cart/add，具体可采用 PUT 方法，也就是将商品加到购物车，参数为商品 ID。这里之所以用 PUT 方法，是因为用户的购物车是一直存在的，用 PUT 方法是遵循 RESTful。
这些接口，都会返回一些相同的信息，比如：错误号、提示信息、用户是否已登录、数据等。它们可以用 Go 语言中的结构体定义，如下所示：
type Response struct {
Code int `json:"code"` // 业务错误码
Data interface{} `json:"data"` // 数据
Msg string `json:"msg"` // 提示信息
}
需要注意的是，为了支持返回多种类型的数据，需要将结构体中的 Data 字段定义为 interface 类型。另外，登录状态 Login-Status 将放到 HTTP Header 中返回给前端。为了让 admin 也能复用这个结构体定义，我们需要将它放在 infrastructure/utils/response.go 里。
接下来，我们在 application/api 中定义 Event 和 Shop 这两个应用，并定义与前面接口对应的处理函数，代码如下：
type Event struct{
type Shop struct{
func (e *Event) List(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("event list")
ctx.JSON(status, resp)
}
func (e *Event) Info(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("event info")
ctx.JSON(status, resp)
}
func (e *Event) Subscribe(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("event subscribe")
ctx.JSON(status, resp)
}
func (s *Shop) AddCart(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("shop add cart")
ctx.JSON(status, resp)
}
接下来，我们实现一个 initRouters 函数，将前面实现的接口函数注册到 Gin 框架的路由中。代码在 interfaces/api 目录下的 routers.go 文件中，如下所示：
func initRouters(g *gin.Engine) {
logrus.Info("init api routers")
event := g.Group("/event")
eventApp := api.Event{}
event.GET("/list", eventApp.List)
event.GET("/info", eventApp.Info)
event.POST("/subscribe", eventApp.Subscribe)
shop := g.Group(“/shop”)
shopApp := api.Shop{}
shop.PUT(“/cart/add”, shopApp.AddCart)
}
然后我们就可以在 api.go 文件的 Run 函数中调用 initRouters 函数，以便将路由注册到 Gin 框架中。
除了需要实现给浏览器请求的 API 接口外，我们还需要实现一个给 admin 请求的 RPC 服务，用于同步活动配置，主要提供专题、场次的上线和下线功能。代码在 application/api/rpc 目录下的 event.proto， 定义如下：
syntax = "proto3";
package rpc;
message Goods {
int32 id = 1;
string desc = 2;
string img = 3;
string price = 4;
string event_price = 5;
int32 event_stock = 6;
}
message Event {
int32 id = 1;
int32 topic_id = 2;
int64 start_time = 3;
int64 end_time = 4;
int32 limit = 5;
repeated Goods goods_list = 6;
}
message Topic {
int32 id = 1;
string title = 2;
string desc = 3;
string banner = 4;
int64 start_time = 5;
int64 end_time = 6;
}
message Response {
int32 code = 1;
string msg = 2;
}
service EventRPC {
rpc EventOnline(Event) returns(Response);
rpc EventOffline(Event) returns(Response);
rpc TopicOnline(Topic) returns(Response);
rpc TopicOffline(Topic) returns(Response);
}
你可以看到，我在该 protobuf 文件中定义了一个名为 EventRPC 的 RPC 服务，以及对应的参数和返回值类型，这些将会在后面生成服务端和客户端的 Go 代码。
我们要如何使用这个 protobuf 文件呢？让我们在 Makefile 中添加编译 protobuf 的指令 proto，如下所示：
proto: application/api/rpc/event.proto
protoc --go_out=plugins=grpc:./ application/api/rpc/event.proto
通过执行 make proto，我们就可以在 application/api/rpc 目录下编译出一个 event.pb.go 文件。这个文件里面就是 RPC 接口的 Go 定义，包括服务端和客户端的定义，它便是秒杀 Admin 服务与 API 服务通信的契约。具体的定义如下：
// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.
type EventRPCClient interface {
EventOnline(ctx context.Context, in *Event, opts ...grpc.CallOption) (*Response, error)
EventOffline(ctx context.Context, in *Event, opts ...grpc.CallOption) (*Response, error)
TopicOnline(ctx context.Context, in *Topic, opts ...grpc.CallOption) (*Response, error)
TopicOffline(ctx context.Context, in *Topic, opts ...grpc.CallOption) (*Response, error)
}
// EventRPCServer is the server API for EventRPC service.
type EventRPCServer interface {
EventOnline(context.Context, *Event) (*Response, error)
EventOffline(context.Context, *Event) (*Response, error)
TopicOnline(context.Context, *Topic) (*Response, error)
TopicOffline(context.Context, *Topic) (*Response, error)
}
然后，我们还需要按照 event.pb.go 的定义实现 RPC 服务。具体代码在 application/api/rpc.go 中，如下所示：
type EventRPCServer struct {
}
func (s *EventRPCServer) EventOnline(ctx context.Context, evt *rpc.Event) (*rpc.Response, error) {
logrus.Info("event online ", evt)
resp := &rpc.Response{}
return resp, nil
}
func (s *EventRPCServer) EventOffline(ctx context.Context, evt *rpc.Event) (*rpc.Response, error) {
logrus.Info("event offline ", evt)
resp := &rpc.Response{}
return resp, nil
}
func (s *EventRPCServer) TopicOnline(ctx context.Context, t *rpc.Topic) (*rpc.Response, error) {
logrus.Info("topic online ", t)
resp := &rpc.Response{}
return resp, nil
}
func (s *EventRPCServer) TopicOffline(ctx context.Context, t *rpc.Topic) (*rpc.Response, error) {
logrus.Info("topic offline ", t)
resp := &rpc.Response{}
return resp, nil
}
同样地，我们也要像 API 服务那样提供启动和退出相关的函数，代码在 interfaces/rpc 目录下的 rpc.go 文件中，如下所示：
var grpcS *grpc.Server
func Run() error {
bind := viper.GetString("api.rpc")
logrus.Info("run RPC server on ", bind)
lis, err := utils.Listen("tcp", bind)
if err != nil {
return err
}
grpcS = grpc.NewServer()
eventRPC := &api.EventRPCServer{}
rpc.RegisterEventRPCServer(grpcS, eventRPC)
// 支持 gRPC reflection，方便调试
reflection.Register(grpcS)
return grpcS.Serve(lis)
}
func Exit() {
grpcS.GracefulStop()
logrus.Info("rpc server exit")
}
接下来，我们还需要在启动命令中加上启动 RPC 服务的代码。具体代码你可以看代码仓库中的 cmd/api.go。
最后，我们编译出可执行程序并运行，效果如下：
你可以看到，当请求 /event/list 接口时，服务输出了 "event list" 日志。使用 grpcurl 工具请求 EventRPC 的 EventOnline 接口时，服务输出了 "event online" 日志。
Admin 服务 API 设计
首先，我们回顾下需求分析时介绍的管理后台功能需求，主要有这几块：专题管理、场次管理、商品管理。每个模块分别有：列表、创建、查看、修改、删除等功能。其中，专题和场次还有上线、下线这两个功能。那么，我们需要实现的接口清单如下所示：
# 创建专题
POST /topic
# 获取专题列表
GET /topic?page=1&size=10
# 查看某个专题
GET /topic/{id}
# 修改某个专题
PUT /topic/{id}
# 上线/下线某个专题
PUT /topic/{id}/{status}
# 删除某个专题
DELETE /topic/{id}
# 创建场次
POST /event
# 获取场次列表
GET /eventpage=1&size=10
# 查看某个场次
GET /event/{id}
# 修改某个场次
PUT /event/{id}
# 上线/下线某个场次
PUT /event/{id}/{status}
# 删除某个场次
DELETE /event/{id}
# 创建商品
POST /goods
# 获取商品列表
GET /goods?page=1&size=10
# 查看某个商品
GET /goods/{id}
# 修改某个商品
PUT /goods/{id}
# 删除某个商品
DELETE /goods/{id}
由于接口比较多，我们在 application/admin 目录下新建三个文件，分别是 topic.go、event.go、goods.go，用于实现 admin 的 API 代码。
topic.go 中定义了 Topic 这个应用，它包含 4 个方法，分别是Post、Get、Put、Delete，代码如下：
type Topic struct{
func (t *Topic) Post(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("topic post")
ctx.JSON(status, resp)
}
func (t *Topic) Get(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("topic get")
ctx.JSON(status, resp)
}
func (t *Topic) Put(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("topic put")
ctx.JSON(status, resp)
}
func (t *Topic) Delete(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("topic delete")
ctx.JSON(status, resp)
}
event.go 中定义了 Event 这个应用，它的 4 个方法命名跟 topic 的一样，代码如下：
type Event struct{}
func (t *Event) Post(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("event post")
ctx.JSON(status, resp)
}
func (t *Event) Get(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("event get")
ctx.JSON(status, resp)
}
func (t *Event) Put(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("event put")
ctx.JSON(status, resp)
}
func (t *Event) Delete(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("event delete")
ctx.JSON(status, resp)
}
goods.go 中主要是定义了 Goods 这个应用，代码如下：
type Goods struct{}
func (t *Goods) Post(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("goods post")
ctx.JSON(status, resp)
}
func (t *Goods) Get(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("goods get")
ctx.JSON(status, resp)
}
func (t *Goods) Put(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("goods put")
ctx.JSON(status, resp)
}
func (t *Goods) Delete(ctx *gin.Context) {
resp := &utils.Response{
Code: 0,
Data: nil,
Msg: "ok",
}
status := http.StatusOK
logrus.Info("goods delete")
ctx.JSON(status, resp)
}
接下来，我们需要参考前面 api 命令的实现，将应用关联到路由并注入框架中，也就是在 interfaces/admin/routers.go 中实现 initRouters 函数。代码如下：
func initRouters(g *gin.Engine) {
topic := g.Group("/topic")
topicApp := admin.Topic{}
topic.POST("/", topicApp.Post)
topic.GET("/", topicApp.Get)
topic.GET("/:id", topicApp.Get)
topic.PUT("/:id", topicApp.Put)
topic.PUT("/:id/:status", topicApp.Put)
topic.DELETE("/:id", topicApp.Delete)
event := g.Group(“/event”)
eventApp := admin.Event{}
event.POST(“/”, eventApp.Post)
event.GET(“/”, eventApp.Get)
event.GET(“/:id”, eventApp.Get)
event.PUT(“/:id”, eventApp.Put)
event.PUT(“/:id/:status”, eventApp.Put)
event.DELETE(“/:id”, eventApp.Delete)
goods := g.Group(“/goods”)
goodsApp := admin.Goods{}
goods.POST(“/”, goodsApp.Post)
goods.GET(“/”, goodsApp.Get)
goods.GET(“/:id”, goodsApp.Get)
goods.PUT(“/:id”, goodsApp.Put)
goods.DELETE(“/:id”, goodsApp.Delete)
}
除此之外，我们还需要启动 admin 服务，以及处理服务退出时关闭连接的问题。这里我将 interfaces/api 目录下的 api.go 做了适当调整，把关于接口重用和程序更新的代码放到了 infrastructure/utils 目录下的 proc.go 和 listen.go 中，以便给 admin 复用。最终，我们在 interfaces/admin 目录下实现的 admin.go 代码如下：
var lis net.Listener
func Run() error {
var err error
bind := viper.GetString("admin.bind")
lis, err = utils.Listen("tcp", bind)
if err != nil {
return err
}
g := gin.New()
// 更新程序，给老版本发送信号
go utils.UpdateProc("admin")
// 初始化路由
initRouters(g)
// 运行服务
return g.RunListener(lis)
}
func Exit() {
lis.Close()
// TODO: 等待请求处理完
// time.Sleep(10 * time.Second)
}
接下来，我们就可以在 cmd/admin.go 中解析命令并启动 admin 了。代码如下：
var adminCmd = &cobra.Command{
Use: "admin",
Short: "Seckill admin server.",
Long: `Seckill admin server.`,
Run: func(cmd *cobra.Command, args []string) {
onExit := make(chan error)
go func() {
if err := admin.Run(); err != nil {
logrus.Error(err)
onExit <- err
}
close(onExit)
}()
onSignal := make(chan os.Signal)
signal.Notify(onSignal, syscall.SIGINT, syscall.SIGTERM)
select {
case sig := <-onSignal:
logrus.Info("exit by signal ", sig)
admin.Exit()
case err := <-onExit:
logrus.Info("exit by error ", err)
}
},
}
func init() {
rootCmd.AddCommand(adminCmd)
}
最终编译出来的程序运行效果如下：
你可以看到，我在命令行下同时运行了 admin 和 api 服务，并且分别给它们发送请求都能正常接收。
到这里，秒杀系统的 API 就设计完毕，并实现了最基础的框架。你可以看到，在整个过程中，我并不是一次性将某个功能开发完毕，而是从外到内逐渐深入，并随时验证功能正确性。这个过程叫渐进式开发，是软件开发中常用的方法。
小结
这一讲我主要给你介绍了 RESTful 和 RPC 解决的问题，以及通过渐进式开发来设计并搭建好秒杀系统的框架。通过代码实战，希望你能掌握 RESTful、RPC 以及渐进式开发的技巧，并能应用到实际工作中。
前后端的技术日益发展，它们之间的交互方式也一直是个需要持续关注的事情。作为开发人员或者架构师，需要学会从众多技术中选出适合自己业务的技术，以便兼顾开发效率、维护成本、用户体验。
接下来你可以思考下：如果将秒杀 API 服务的 HTTP 接口也用 RPC 实现，应该怎么设计呢？
好了，这一讲就到这里了，下一讲我将给你介绍“如何使用 etcd 存储配置信息”。到时见！
源码地址：https://github.com/lagoueduCol/MiaoSha-Yiletian