自go-zero走进微服务

在我最初看来，go-zero 最核心的价值体现在两点：

1、使用 .api 定义接口协议（Contract First）

2、使用 goctl 自动生成工程骨架，让开发者专注于业务逻辑

但在进一步使用后，我发现 go-zero 的核心并不止于脚手架，

而是一整套围绕"可维护性、可扩展性"的工程化约束体系。

更后来真正进入项目后，我逐渐意识到：

RPC（zrpc + etcd）才是 go-zero 支撑微服务架构的第二个关键支点。

而中间件、熔断、限流、链路最终，是第三个核心支点。

参考：go-zero文档

配置环境

安装 goctl（go-zero 的脚手架）

go 复制代码

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

生成代码

方法一：

（这种方式，是直接一键生成）

等环境配置完毕后。

直接进入go编辑器，在命令行中输入！（切记是命令行）

go 复制代码

goctl api new firstdemo

然后你就会非常完美的发现。骨架已经搭建完毕。

有了这个，大家可以非常丝滑的将一个框架搭起。

方法二：

你首先创建一个.api文件：

go 复制代码

syntax = "v1"

info (
  title: "gozero-demo"
  desc: "first api"
  author: "you"
  version: "1.0"
)

type (
  PingReq {
    name string `form:"name,optional"`
  }

  PingResp {
    message string `json:"message"`
  }

  CreateReq {
    title string `json:"title"`
    content string `json:"content"`
  }

  CreateResp {
    id int64 `json:"id"`
  }
)

service demo-api {
  @handler Ping
  get /ping (PingReq) returns (PingResp)

  @handler CreatePost
  post /posts (CreateReq) returns (CreateResp)
}

我简洁的解释一下
get/ping ：GET 参数通常用 form:""（对应 query）
post /posts ：POST JSON 用 json:""
@handler Xxx：生成的 handler/logic 名字，也就是生成对应的router、控制器、业务层代码...

然后执行命令：

go 复制代码

goctl api go -api demo.api -dir .

go 复制代码

go_zero_project/
├── demo.api                  #  API 协议定义（接口契约，最核心）
│
├── demo-api.go               # 程序入口（main）
│   └── main()
│       └── 启动 HTTP Server
│
├── etc/
│   └── demo-api.yaml         # 配置文件（端口 / DB / Redis / JWT 等）
│
├── internal/
│   │
│   ├── handler/              # HTTP 层（参数 → 逻辑）
│   │   ├── pinghandler.go
│   │   └── createposthandler.go
│   │
│   ├── logic/                # 业务逻辑层（核心代码写这里）
│   │   ├── pinglogic.go
│   │   └── createpostlogic.go
│   │
│   ├── types/                # 请求 / 响应结构体（由 .api 生成）
│   │   ├── ping.go
│   │   └── createpost.go
│   │
│   └── svc/
│       └── servicecontext.go # 依赖注入（DB / Redis / RPC Client）
│
└── go.mod                    # Go Module 定义

热加载

咱们这里，先在命令行中下载：

go 复制代码

go install github.com/air-verse/air@latest
air -v

下载完成之后，再次输入：

go 复制代码

air

你会在命令行中发现漂亮的：

作用：

这里重点说一下 air 起到作用的3个点：

监听文件变化
自动 go build
杀掉旧进程 → 启动新进程

实现GET/POST/PUT/DELETE

现在把目录清空。

然后新创建一个first.api的文件，并依次把下方四种不同类型的粘贴进去。

get 查询

api 复制代码

// 获取用户
type GetUserReq {
	id int64 `form:"id"`
}

type GetUserResp {
	id   int64  `j    son:"id"`
	name string `json:"name"`
}

service demo-api {
	@handler GetUser
	get /user (GetUserReq) returns (GetUserResp)
}

post 创建

api 复制代码

// 创建用户
type CreateUserReq {
	name string `json:"name"`
	age  int    `json:"age"`
}

type CreateUserResp {
	id int64 `json:"id"`
}

service demo-api {
	@handler CreateUser
	post /user (CreateUserReq) returns (CreateUserResp)
}

put 更新

api 复制代码

// 更新用户
type UpdateUserReq {
	id   int64  `path:"id"`
	name string `json:"name"`
}

type UpdateUserResp {
	ok bool `json:"ok"`
}

service demo-api {
	@handler UpdateUser
	put /user/:id (UpdateUserReq) returns (UpdateUserResp)
}

delete 删除

api 复制代码

// 删除用户
type DeleteUserReq {
	id int64 `path:"id"`
}

type DeleteUserResp {
	ok bool `json:"ok"`
}

service demo-api {
	@handler DeleteUser
	delete /user/:id (DeleteUserReq) returns (DeleteUserResp)
}

之后，运行命令：

cmd 复制代码

 goctl api go -api firstdemo.api -dir .

之后，你就会得到这样一个帅气的目录，拥有基础的增删改查

动态路由

在我看来，只要仅操作一个资源的，都可以考虑用动态路由。

动态路由很简单，只需要简单的3步走即可。

路由路径利用 :变量名：

api 复制代码

get /articles/:id

:id 表示这里是一个占位符

请求体里用 path:"变量名"

api 复制代码

type GetArticleReq {
  id int64 `path:"id"`
}

切记 path:"id" 必须和 :id 一模一样！否则解析不到值。

method + handler 正确绑定

api 复制代码

@handler GetArticle
get /articles/:id (GetArticleReq) returns (GetArticleResp)

多个参数

可能就会有人问了，多个参数了怎么办？

简直太好办了

api 复制代码

GET /users/:userId/articles/:articleId

api 复制代码

type GetUserArticleReq {
  userId    int64 `path:"userId"`
  articleId int64 `path:"articleId"`
}

中间件

1、首先你要了解什么是中间件？

2、go-zero中的中件长什么样？

3、如何挂在到路由上？

4、他的职责是什么？

请带着这些疑问来阅读接下来的内容。

无中间件：

一条没有中间件的访问路径大致是这样：

复制代码

HTTP Request
   ↓
handler
   ↓
logic
   ↓
response

但现实项目里，你经常要做些和业务无关、但每个接口都要 的事：

比如：

1、校验登录态 / Token

2、打日志

3、统一鉴权（验证权限）

4、限流（限制并发的）

5、统计耗时

等等...

如果你把这些都写进 logic 或 handler，结果是：

造成的后果，不仅是每个接口重复写 、业务逻辑被污染，

更是使后期根本维护不动！

挂载上中间件

中间件 = 在请求进入 handler 之前 / 返回响应之前，插一段统一逻辑。

如下：

复制代码

HTTP Request
   ↓
Middleware（Auth / Log / RateLimit）
   ↓
handler
   ↓
logic
   ↓
response

在框架中的位置

go 复制代码

internal/
├── middleware/        ← 中间件目录
│   └── authmiddleware.go
│
├── handler/           ← HTTP 参数解析
├── logic/             ← 业务逻辑
├── svc/
│   └── servicecontext.go  ← 依赖注入（中间件从这拿资源）

记住：中间件 ≠ handler ≠ logic

它是作为一个独立层存在的。

中间件的样子

go 复制代码

// Code scaffolded by goctl. Safe to edit.
// goctl 1.9.2

package middleware

import "net/http"

type AuthMiddleware struct {
}

func NewAuthMiddleware() *AuthMiddleware {
	return &AuthMiddleware{}
}

func (m *AuthMiddleware) Handle(next http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		// TODO generate middleware implement function, delete after code implementation

		// Passthrough to next handler if need
		next(w, r)
	}
}

如何生成？

我新建了一个文件：auth.api

api 复制代码

syntax = "v1"

type GetUserReq {
	id int64 `path:"id"`
}

type GetUserResp {
	id int64 `json:"id"`
}

@server (
	group:      user
	middleware: Auth // 这里
)
service user-api {
	@handler GetUser
	get /users/:id (GetUserReq) returns (GetUserResp)
}

通过运行

cmd 复制代码

goctl api go -api auth.api -dir .

@doc与import

@doc是什么？

@doc 是写在路由上的"接口说明元数据"，用于生成文档/让接口更可读。

复制代码

@doc "获取文章详情"
@handler GetArticle
get /articles/:id (GetArticleReq) returns (GetArticleResp)

import 是什么？

当你的项目接口多了，一个 .api 文件会越来越大，变成"几千行的屎山"。

import 的作用是：

把 api 文件拆分成多个小文件，再由一个入口 api 汇总。

如下的布局方式：

复制代码

api/
├── auth.api          # 入口（import 其它 api）
├── user.api          # 用户相关
└── types.api         # 公共 type（可选）

auth.api

api 复制代码

syntax = "v1"

import "types.api"
import "user.api"

user.api

api 复制代码

syntax = "v1"

@server(
  group: user
)

service user-api {
  @doc "获取用户详情"
  @handler GetUser
  get /users/:id (GetUserReq) returns (GetUserResp)
}

types.api

api 复制代码

syntax = "v1"

type GetUserReq {
  id int64 `path:"id"`
}

type GetUserResp {
  id   int64  `json:"id"`
  name string `json:"name"`
}

最后命令行一生成：

api 复制代码

 goctl api go -api auth.api -dir .

RPC服务

首先，我们要先明确：
RPC = 远程函数调用（像本地函数一样调用远程服务）

但注意！RPC 的核心不是"远程"，而是：

强接口约束（proto）
高性能（HTTP/2 + protobuf）
面向服务而不是面向资源

在go-zero里

go 复制代码

API 服务  ------(rpc client)------>  RPC 服务  ------>  业务逻辑 / DB

在rpc与go-zero集合的项目中，往往少不了以下这四步：

1、 *.proto

→ 接口契约（定义有哪些方法、参数、返回值）

2、 goctl rpc new / protoc

→ 生成 RPC 服务骨架

3、etc/*.yaml

→ RPC 监听端口、服务名

4、internal/logic

→ 你真正写业务的地方

大家可以手动创建一个user的包，输入：

cmd 复制代码

goctl rpc new

你将会得到：

pgsql 复制代码

user/
├── user.proto
├── user.go
├── etc/
│   └── user.yaml
├── internal/
│   ├── config/
│   ├── logic/
│   ├── server/
│   └── svc/
└── go.mod

这样一个骨架。

此时你会看到，这样一份协议。

proto 复制代码

syntax = "proto3";

package user;
option go_package="./user";

message Request {
  string ping = 1;
}

message Response {
  string pong = 1;
}

service User {
  rpc Ping(Request) returns(Response);
}

与user.go中的，启动函数。

go 复制代码

package main

import (
	"flag"
	"fmt"

	"go_zero_project/gozero-rpc-demo/user/internal/config"
	"go_zero_project/gozero-rpc-demo/user/internal/server"
	"go_zero_project/gozero-rpc-demo/user/internal/svc"
	"go_zero_project/gozero-rpc-demo/user/user"

	"github.com/zeromicro/go-zero/core/conf"
	"github.com/zeromicro/go-zero/core/service"
	"github.com/zeromicro/go-zero/zrpc"
	"google.golang.org/grpc"
	"google.golang.org/grpc/reflection"
)

var configFile = flag.String("f", "etc/user.yaml", "the config file")

func main() {
	flag.Parse()

	var c config.Config
	conf.MustLoad(*configFile, &c)
	ctx := svc.NewServiceContext(c)

	s := zrpc.MustNewServer(c.RpcServerConf, func(grpcServer *grpc.Server) {
		user.RegisterUserServer(grpcServer, server.NewUserServer(ctx))
		if c.Mode == service.DevMode || c.Mode == service.TestMode {
			reflection.Register(grpcServer)
		}
	})
	defer s.Stop()

	fmt.Printf("Starting rpc server at %s...\n", c.ListenOn)
	s.Start()
}

请你点开的小手。

在终端中输入go mod tidy，更新拉取一下。

run一下，即可启动！

什么？你说你运行失败了？

etcd

如果运行失败了，大概率是 etcd 尚未启动 ，这是新手最常见的问题之一。

因为你没有安装etdc。

什么是etdc？

etcd 你可以将其当成一个高可用的分布式 KV 存储（Key-Value），核心用途在微服务里是：

服务发现：服务启动把自己的地址写进去（注册）

配置中心/开关：把配置、feature flag 放进去

分布式协调：租约、锁、选主....

如果你是第一次接触 etcd，可以先"功能上"把它理解为：

一个专门给微服务用的「注册中心 / 配置中心」

！！但要注意：

etcd ≠ Redis
etcd 具有强一致（Raft）
Redis 更偏缓存、高吞吐

一、下载

txt 复制代码

https://github.com/etcd-io/etcd/releases

二、配置

把你含有以下，两个文件的cmd路径，配置到全局PATH路径内。

复制代码

 - etcd.exe
 - etcdctl.exe

三、运行

直接在cmd内，输入以下四个英文单词。

cmd 复制代码

etcd

启动！

四、检测

复制代码

netstat -ano | findstr :2379

看一看是否在监听！

此时，你在回去运行一下项目，自然就跑通了。
五、为什么要用这个？

这是很多人的疑惑！

看etc内的配置文件：

yaml 复制代码

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

小傻蛋们，因为配置文件用到了etcd。

调用rpc服务

初步调用

首先启动服务。

之后在apifox中操作的，创建基于grpc的接口管理！

（当然你换成其他也操作函数）

然后把我的.proto文件放置进去。

在user.User /Ping接口上，点击调用。

json 复制代码

{
    "pong": "hello"
}

修改

插入这些，

然后在，service User 里加一条：

方法名：GetUser
请求：GetUserRequest
响应：GetUserResponse

并新增 2 个 message：

GetUserRequest { int64 id = 1; }

GetUserResponse { int64 id = 1; string name = 2; }

proto 复制代码

syntax = "proto3";

package user;
option go_package="./user";

message Request {
  string ping = 1;
}

message Response {
  string pong = 1;
}

message GetUserRequest {
  int64 id = 1;
}
message GetUserResponse {
  int64 id = 1;
  string name = 2;
}

service User {
  rpc Ping(Request) returns(Response);
  rpc GetUser(GetUserRequest) returns(GetUserResponse);
}

最关键的一步：

cmd 复制代码

goctl rpc protoc user.proto --go_out=. --go-grpc_out=. --zrpc_out=.

同个这个，生成rpc代码框架。

这里就是微服务中，被远程调用部分。

也是go-zero中的，两个最重要的核心之一！

而另一个就是api，也就是对外！同时调用rpc的部分！

API

其实这个主要就两个步骤

一、生成 API 项目骨架

(一般，新启一个项目时用)

cmd 复制代码

goctl api new userapi

二、写 .api 协议后生成代码

(更新项目时使用)

cmd 复制代码

goctl api go -api userapi.api -dir .

其实api还有很多组件需要掌握：

gorm、auth、jwt...

但是这些其实都与gin框架大差不差。

这次就先记录到这里，如果想要了解更多、更详细的，可以直接到官网了解，文档写的还是非常简洁通透的：
go-zero文档