重要提示

1. 因官网重新改版，本文是基于官网最新版本的文档并整合旧文档重新进行全面总结、归纳。
2. 本文主要对官网 快速开始 进行提炼总结，未涉及部分将在后续章节陆续补充完善。

1 相关命令

待补充。。。

2 参考文档

1. 官方文档：go-zero

3 架构图

4 go-zero环境搭建

go-zero的是基于go的，所以首先需要安装配置go环境，go的安装配置可参考：Golang安装配置、GoLand安装配置 ，此处不再赘述。

4.1 注意事项

注意：如果是更新go-zero相关组件的版本，建议先备份原来的组件，防止最新版本的组件出现不兼容的问题。

4.2 go-zero 需要安装的组件

• goctl
• protoc
• protoc-gen-go
• protoc-gen-go-grpc

4.3 自动安装 和 4.4 手动安装 均能安装go-zero的环境，如果按照4.3 自动安装某个组件失败，可按4.4 手动安装 来安装缺失的组件。

4.3 自动安装

1. 先下载 goctl

go install github.com/zeromicro/go-zero/tools/goctl@latest

2. 验证goctl的安装结果：goctl -v

D:\Software\Golang\GOPATH\bin>goctl -v
goctl version 1.5.3 windows/amd64

2. goctl一键安装 protoc、protoc-gen-go、protoc-gen-go-grpc

goctl env check --install --verbose --force

4.4 手动安装

1. goctl 安装

go install github.com/zeromicro/go-zero/tools/goctl@latest

2. Protobuf下载安装
   需要先下载protoc执行器

• 到 https://github.com/protocolbuffers/protobuf/releases 分别下载Windows和Linux环境的执行器
• 选择最新版本的protoc下载
  
• 将下载的文件解压，将解压后的bin目录加入到环境变量的path下。
• 查看安装是否成功：protoc --version

Protobuf下Go、GRPC插件的安装

protoc-gen-go：Go专用的protoc的编译器插件，安装后会在GOPATH的bin目录下生成一个protoc-gen-go.exe
protoc-gen-go-grp：Go调用grpc的插件，安装后会在GOPATH的bin目录下生成一个protoc-gen-go-grpc.exe

go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.26

go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.1

至此使用Protobuf的准备工作就做完了。

5 单体服务

5.1 简单入门

参考文档：api demo 代码生成

1. 快速生成api服务，api服务就是网关服务，如果不与Service端【RPC端】交互，则可以独立成一个单独的服务。

goctl api new greet

2. 目录结构：

.
│  go.mod
│  greet.api
│  greet.go
│
├─etc
│      greet-api.yaml
│
└─internal
    ├─config
    │      config.go
    │
    ├─handler
    │      greethandler.go
    │      routes.go
    │
    ├─logic
    │      greetlogic.go
    │
    ├─svc
    │      servicecontext.go
    │
    └─types
            types.go

3. 启动服务：

cd greet
go mod init
go mod tidy
go run greet.go -f etc/greet-api.yaml

4. 默认侦听在 8888 端口（可以在配置文件里修改端口），请求：

curl -i http://localhost:8888/from/you

返回如下：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Traceparent: 00-0c577bd0a5d96c7b9669d3bba60d6b09-5f4e42e62eb6a79e-00
Date: Mon, 19 Jun 2023 14:25:01 GMT
Content-Length: 4

null

5.2 api语法

参考：api语法

5.3 api 文件格式化

参考：api 文件格式化

在 api 文件编写完之后，我们的 api 内容参差不齐，就有如下内容：

# 格式化前
syntax = "v1"

type User {
    Id int64 `json:"id"`
    Name string `json:"name"`
    Age int `json:"age"`
    Description string `json:"description"`
}

type Student {
    Id int64 `json:"id"`
    No int64 `json:"no"`
    Name string `json:"name"`
    Age int `json:"age"`
    Description string `json:"description"`
}

service User {
    @handler ping
    get /ping
}

这样的 api 文件不够美观，不便于阅读，可以使用 goctl api format 命令对 api 文件进行格式化。

# 格式化后
syntax = "v1"

type User {
	Id          int64  `json:"id"`
	Name        string `json:"name"`
	Age         int    `json:"age"`
	Description string `json:"description"`
}

type Student {
	Id          int64  `json:"id"`
	No          int64  `json:"no"`
	Name        string `json:"name"`
	Age         int    `json:"age"`
	Description string `json:"description"`
}

service User {
	@handler ping
	get /ping
}

6 微服务

6.1 简单入门

参考文档：gRPC demo 代码生成

1. 快速生成rpc服务。

goctl rpc new demo

2. 目录结构：

.
│  demo.go
│  demo.proto
│  go.mod
│
├─demo
│      demo.pb.go
│      demo_grpc.pb.go
│
├─democlient
│      demo.go
│
├─etc
│      demo.yaml
│
└─internal
    ├─config
    │      config.go
    │
    ├─logic
    │      pinglogic.go
    │
    ├─server
    │      demoserver.go
    │
    └─svc
            servicecontext.go

3. 编写简单的逻辑代码：

• 找到 /demo/internal/logic/demologic.go 文件，编辑该文件，将 29 行替换为如下代码：

return &demo.Response{
    Pong:"pong",
}, nil

• 修改配置文件 /demo/etc/demo.yaml，删除 3 至 7 行使用Etcd注册服务的内容，然后在追加内容 Mode: dev 至末尾：

goctl 生成最小化 gRPC 服务默认启动会向 ETCD 注册中心注册当前服务的信息，本次演示就不需要注册中心，所以删除了配置文件中的注册中心配置。

原始配置：

Name: demo.rpc
ListenOn: 0.0.0.0:8080
Etcd:
  Hosts:
  - 127.0.0.1:2379
  Key: demo.rpc

更改后的配置：

Name: demo.rpc
ListenOn: 0.0.0.0:8080
Mode: dev

4. 启动服务：

# 进入服务目录
$ cd /demo
# 整理依赖文件
$ go mod tidy
# 启动 go 程序
$ go run demo.go

当控制台有如下输出 Starting rpc server at 0.0.0.0:8080...，说明服务已经启动成功，接着我们来访问一下该 gRPC 服务。

5. 访问 gRPC 服务
   使用Postman访问测试，注意这是访问GRPC服务，所以需要创建grpc类型的请求。
   

---

---

当在 Postman 中看到如下输出内容时，代表你的服务已经启动，并能成功访问。

{
  "pong": "pong"
}

6.2 proto 语法

参考：proto 语法

7 目录结构介绍

1. 目录结构

example
├── etc
│   └── example.yaml
├── main.go
└── internal
    ├── config
    │   └── config.go
    ├── handler
    │   ├── xxxhandler.go
    │   └── xxxhandler.go
    ├── logic
    │   └── xxxlogic.go
    ├── svc
    │   └── servicecontext.go
    └── types
        └── types.go

2. 各文件介绍

• example：单个服务目录，一般是某微服务名称。
• etc：静态配置文件目录。
• main.go：程序启动入口文件。
• internal：单个服务内部文件，其可见范围仅限当前服务。
• config：静态配置文件对应的结构体声明目录。
• handler：handler 目录，可选，一般 http 服务会有这一层做路由管理，handler 为固定后缀。
• logic：业务目录，所有业务编码文件都存放在这个目录下面，logic 为固定后缀。
• svc：依赖注入目录，所有 logic 层需要用到的依赖都要在这里进行显式注入。
• types：结构体存放目录。