当前位置：首页 > 开源项目 > 微服务电商 > 正文内容

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

3年前 (2022-09-13)微服务电商5202

# 1. 概述

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

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

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

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

- [go-zero 成长之路—微服务电商实战系列（三、表结构篇）](https://juejin.cn/post/7139717722782466084)
- [go-zero 成长之路—微服务电商实战系列（二、划分篇）](https://juejin.cn/post/7138610986612686856)
- [go-zero 成长之路—微服务电商实战系列（一、需求篇）](https://juejin.cn/post/7137280656912384036)

# 2. API定义

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

![image](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/c0cf40744c0841c882d88426f528d101~tplv-k3u1fbpfcp-zoom-in-crop-mark:3024:0:0:0.awebp?)

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

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

## 用户服务

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

* `user.api` 文件如下：

```go
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)
}
```

* 生成命令如下：

```shell
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
```

* 生成后的目录结构：

```text
├── 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` 文件如下：

```go
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)
}
```

* 生成命令如下：

```shell
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
```

* 生成后的目录结构：

```shell
├── 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` 文件如下：

```go
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)

}
```

* 生成命令如下：

```shell
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
```

* 生成后的目录结构：

```shell
├── 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` 文件如下：

```go
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)
	
}
```

* 生成命令如下：

```shell
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
```

* 生成后的目录结构：

```shell
├── 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 文件？
- 构建后的每个目录和文件是做什么的？

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

希望本篇文章对你有所帮助，谢谢。 [micro-shop](https://gitee.com/jobhandsome/micro-shop)

随机文章
热门文章
热评文章

扫描二维码推送至手机访问。

本文链接：https://www.qsjob.fun/post/32.html

分享给朋友：

返回列表

上一篇：go-zero 成长之路—微服务电商实战系列（三、表结构篇）

下一篇：go-zero 成长之路—微服务电商实战系列（五、RPC定义）

“go-zero 成长之路—微服务电商实战系列（四、API定义）” 的相关文章

go-zero 成长之路—微服务电商实战系列（一、需求篇）3年前 (2022-08-19)

go-zero 成长之路—微服务电商实战系列（二、划分篇）3年前 (2022-09-02)

go-zero 成长之路—微服务电商实战系列（三、表结构篇） 3年前 (2022-09-05)

go-zero 成长之路—微服务电商实战系列（五、RPC定义）3年前 (2022-10-08)

go-zero 成长之路—微服务电商实战系列（六、条件查询）3年前 (2022-10-18)

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

“go-zero 成长之路—微服务电商实战系列（四、API定义）” 的相关文章

京ICP备2021021334号

Powered By Z-BlogPHP. Theme by TOYEAN.

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

“go-zero 成长之路—微服务电商实战系列（四、API定义）” 的相关文章

京ICP备2021021334号var _hmt = _hmt || [];(function() { var hm = document.createElement("script"); hm.src = "https://hm.baidu.com/hm.js?b63854c12c937e8f0e109978f0f10b08"; var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(hm, s);})();

Powered By Z-BlogPHP. Theme by TOYEAN.

京ICP备2021021334号