程序员小乔

V1

2022/09/14阅读:27主题:雁栖湖

go-zero 成长之路—微服务电商实战系列(四、API定义)

Part11. 概述

前面文章说到:表结构划分,共8个表,分别对应以下版块:

  • 用户服务版块:user
  • 产品服务版块:productcategory
  • 购物车服务版块:cart
  • 订单服务版块:ordersorder_recordorder_address
  • 支付服务版块:pay_info

总共5个服务。在咱们原先的构想中,远不止远不止以上这 5 个服务版块。 但是对于电商系统来说,这5个版块是重中之重的,是必不可少的。所以咱们该篇文章就针对重中之重的5个版块进行API的定义,用于后续的开发。

如果以上设计构想不是很清楚的,可通过如下传送门查看该系列其他文章:

Part22. API定义

不同的微服务间需要做数据的隔离,每个微服务独占数据库资源,通过RPC调用来获取数据依赖,整体架构如下图所示:

image
image

通过以上对API的定义我们大致了解了需要定义哪些服务的API,下面开始API的定义。

这里采用 api.api 文件的形式进行构建API服务。

1用户服务

主要功能:用户登录、用户注册、用户信息、...

  • user.api 文件如下:
syntax = "v1"  // 版本号

// 接口信息
info (
 title: "microShop/user.api" 
 author: "jobhandsome"
 version: "1.0.0"
)

type (
 RegisterReq {
  UserName  string `json:"UserName"`  // 用户名
  PassWord  string `json:"PassWord"`  // 用户密码,MD5加密
  UserNick  string `json:"UserNick"`  // 用户昵称
  UserFace  string `json:"UserFace"`  // 用户头像地址
  UserSex   int64  `json:"UserSex"`   // 用户性别:0男,1女,2保密
  UserEmail string `json:"UserEmail"` // 用户邮箱
 }

 LoginReq {
  UserName string `json:"UserName"` // 用户名
  PassWord string `json:"PassWord"` // 用户密码,MD5加密
 }

 userInfoReq {
  UserIdentity string `json:"UserIdentity"` // 用户唯一标识
 }

 CommonResply {
  Code    int64  `json:"Code"`
  Message string `json:"Message"`
  Data    string `json:"Data"`
 }
)

// 接口地址前缀
@server(
 prefix: account
)

// 接口路由
service user-api{
 @doc (
  summary: "用户注册"
 )
 @handler Register
 post /register (RegisterReq) returns (CommonResply)
 
 @doc (
  summary: "用户登录"
 )
 @handler Login
 post /login (LoginReq) returns (CommonResply)

 @doc (
  summary: "用户信息"
 )
 @handler UserInfo
 post /userinfo (LoginReq) returns (CommonResply)
}
  • 生成命令如下:
goctl api go -api user.api -dir . -style go-zero  

#
 合并同一个分组下的handler,并生成对应的文件
# goctl-go-compact 需要手动安装一下才能使用
goctl api plugin -p goctl-go-compact -api user.api -dir . -style go-zero
  • 生成后的目录结构:
├── api.api                                 // api描述文件
├── etc
│   └── user-api.yaml                       // 配置文件
├── internal
│   ├── config
│   │   └── config.go                       // 配置声明type
│   ├── handler                             // 路由及handler转发
│   │   ├── handlers.go
│   │   └── routes.go
│   ├── logic                               // 业务逻辑
│   │   ├── login-logic.go
│   │   └── register-logic.go
│   ├── svc                                 // logic所依赖的资源池
│   │   └── service-context.go
│   └── types
│       └── types.go                            // request、response的struct,根据api自动生成,不建议编辑
├── model
│   ├── user_model.go
│   ├── user_model_gen.go
│   ├── user_receive_address_model.go
│   ├── user_receive_address_model_gen.go
│   └── vars.go
├── sql
│   └── user.sql
└── user.go                                 // main函数入口

2首页服务

主要功能:首页banner图、排行榜、人气推荐、商品推荐列表、...

  • api.api 文件如下:
syntax = "v1"

info (
 title: "microShop/home.api"
 author: "jobhandsome"
 version: "1.0.0"
)

type (
 // banner
 BannerReq {}

 // 人气推荐
 RecommendReq {}

 // 排行榜
 RankingListReq {}

 // 统一返回
 CommonResply {
  Code    int64                     `json:"Code"`
  Message string                    `json:"Message"`
  Data    map[int]map[string]string `json:"Data"`
 }
)

@server(
 prefix: home
)

service home-api{
 @doc (
  summary: "首页Banner图"
 )
 @handler Banner
 get /banner (BannerReq) returns (CommonResply)
 
 @doc (
  summary: "人气推荐"
 )
 @handler Recommend
 get /recommend (RecommendReq) returns (CommonResply)
 
 @doc (
  summary: "排行榜"
 )
 @handler RankingList
 get /ranking-list (RankingListReq) returns (CommonResply)
}
  • 生成命令如下:
goctl api go -api api.api -dir . -style go-zero  

#
 合并同一个分组下的handler,并生成对应的文件
# goctl-go-compact 需要手动安装一下才能使用
goctl api plugin -p goctl-go-compact -api api.api -dir . -style go-zero
  • 生成后的目录结构:
├── api.api
├── etc
│   └── home-api.yaml
├── home.go
└── internal
    ├── config
    │   └── config.go
    ├── handler
    │   ├── handlers.go
    │   └── routes.go
    ├── logic
    │   ├── banner-logic.go
    │   ├── ranking-list-logic.go
    │   └── recommend-logic.go
    ├── svc
    │   └── service-context.go
    └── types
        └── types.go

3产品服务

主要功能:产品列表、产品详情、分类列表、...

  • product.api 文件如下:
syntax = "v1"

info (
 title: "microShop/product.api"
 author: "jobhandsome"
 version: "1.0.0"
)

type (
 // 商品列表
 ProductListReq {
  page int64  `json:"page"`
  pageSize int64 `json:"pageSize"`
  productName string  `json:"productName"`
 }

 // 商品列表返回
 ProductListResply {
  Code    int64                     `json:"Code"`
  Message string                    `json:"Message"`
  Page    int64                     `json:"Page"`
  PageSize    int64                 `json:"PageSize"`
  TotalCount    int64               `json:"TotalCount"`
  Data    map[int]map[string]string `json:"Data"`
 }

 // 商品详情
 ProductDetailReq {
  porductId int64  `json:"porductId"`
 }

 // 分类列表
 CateListReq {
  Pid int64  `json:"pid"`
 }

 // 统一返回
 CommonResply {
  Code    int64                     `json:"Code"`
  Message string                    `json:"Message"`
  Data    map[int]map[string]string `json:"Data"`
 }
)

@server(
 prefix: product
)

service product-api{
 @doc (
  summary: "商品列表"
 )
 @handler ProductList
 get /list (ProductListReq) returns (ProductListResply)

 @doc (
  summary: "商品详情"
 )
 @handler ProductDetail
 get /detail (ProductDetailReq) returns (CommonResply)
 
 @doc (
  summary: "分类列表"
 )
 @handler cateList
 get /cate-list (CateListReq) returns (CommonResply)


}
  • 生成命令如下:
goctl api go -api product.api -dir . -style go-zero  

#
 合并同一个分组下的handler,并生成对应的文件
# goctl-go-compact 需要手动安装一下才能使用
goctl api plugin -p goctl-go-compact -api product.api -dir . -style go-zero
  • 生成后的目录结构:
├── etc
│   └── product-api.yaml
├── internal
│   ├── config
│   │   └── config.go
│   ├── handler
│   │   ├── handlers.go
│   │   └── routes.go
│   ├── logic
│   │   ├── cate-list-logic.go
│   │   ├── product-detail-logic.go
│   │   └── product-list-logic.go
│   ├── svc
│   │   └── service-context.go
│   └── types
│       └── types.go
├── product.api
└── product.go

4订单服务

主要功能:订单列表、订单详情、物流跟踪、取消订单、创建订单、提交订单、...

  • orders.api 文件如下:
syntax = "v1"

info (
 title: "microShop/orders.api"
 author: "jobhandsome"
 version: "1.0.0"
)

type (
 // 订单列表
 OrdersListReq {
  Page        int64  `json:"page"`
  PageSize    int64  `json:"pageSize"`
 }

 // 订单列表返回
 OrdersListResply {
  Code       int64                     `json:"Code"`
  Message    string                    `json:"Message"`
  Page       int64                     `json:"Page"`
  PageSize   int64                     `json:"PageSize"`
  TotalCount int64                     `json:"TotalCount"`
  Data       map[int]map[string]string `json:"Data"`
 }

 // 订单详情
 OrderReq {
  orderId int64 `json:"orderId"`
 }
 // 统一返回
 CommonResply {
  Code    int64                     `json:"Code"`
  Message string                    `json:"Message"`
  Data    map[int]map[string]string `json:"Data"`
 }
)

@server(
 prefix: orders
)

service orders-api{
 @doc (
  summary: "订单列表"
 )
 @handler OrderList
 get /list (OrdersListReq) returns (OrdersListResply)
 
 @doc (
  summary: "订单详情"
 )
 @handler OrderDetail
 get /detail (OrderReq) returns (CommonResply)
 
 @doc (
  summary: "订单物流"
 )
 @handler OrderLogistics
 get /logistics (OrderReq) returns (CommonResply)
 
}
  • 生成命令如下:
goctl api go -api orders.api -dir . -style go-zero  

#
 合并同一个分组下的handler,并生成对应的文件
# goctl-go-compact 需要手动安装一下才能使用
goctl api plugin -p goctl-go-compact -api orders.api -dir . -style go-zero
  • 生成后的目录结构:
├── etc
│   └── orders-api.yaml
├── internal
│   ├── config
│   │   └── config.go
│   ├── handler
│   │   ├── handlers.go
│   │   └── routes.go
│   ├── logic
│   │   ├── order-detail-logic.go
│   │   ├── order-list-logic.go
│   │   └── order-logistics-logic.go
│   ├── svc
│   │   └── service-context.go
│   └── types
│       └── types.go
├── orders.api
└── orders.go

说到这里:剩下的两个服务咱们就暂时不说了,有兴趣的朋友可以自行补齐:购物车服务支付服务 这两个版块。

Part33. 结束语

本篇文章介绍说明了:

  • 如何构建一个api服务?
  • 如何编写 api.api 文件?
  • 构建后的每个目录和文件是做什么的?

另外,如果你感兴趣,非常欢迎你加入,我们一起来完成这个项目,为社区献出自己的一份力。

希望本篇文章对你有所帮助,谢谢。

分类:

后端

标签:

Golang

作者介绍

程序员小乔
V1

一个喜爱编程技术的非著名码农人士