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

该系列源码已开源：micro-shop

1. 概述

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

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

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

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

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

2. API定义

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

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

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

用户服务

主要功能：用户登录、用户注册、用户信息、…

• 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函数入口

首页服务

主要功能：首页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

产品服务

主要功能：产品列表、产品详情、分类列表、…

• 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

订单服务

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

• 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

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

3. 结束语

本篇文章介绍说明了：

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

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

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