Part11. 概述

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

• 用户服务版块：user 表
• 产品服务版块：product、category 表
• 购物车服务版块：cart 表
• 订单服务版块：orders、order_record、order_address 表
• 支付服务版块：pay_info 表

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

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

• go-zero 成长之路—微服务电商实战系列（三、表结构篇）
• go-zero 成长之路—微服务电商实战系列（二、划分篇）
• go-zero 成长之路—微服务电商实战系列（一、需求篇）

Part22. API定义

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

通过以上对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 文件？
• 构建后的每个目录和文件是做什么的？

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

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