自go-zero走进微服务

在我最初看来，go-zero 最核心的价值体现在两点： 1、使用 .api 定义接口协议（Contract First） 2、使用 goctl 自动生成工程骨架，让开发者专注于业务逻辑

但在进一步使用后，我发现 go-zero 的核心并不止于脚手架， 而是一整套围绕“可维护性、可扩展性”的工程化约束体系。

更后来真正进入项目后，我逐渐意识到： RPC（zrpc + etcd）才是 go-zero 支撑微服务架构的第二个关键支点。 而中间件、熔断、限流、链路最终，是第三个核心支点。

参考：go-zero文档

配置环境

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

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

生成代码

方法一：

（这种方式，是直接一键生成） 等环境配置完毕后。 直接进入go编辑器，在命令行中输入！（切记是命令行）

goctl api new firstdemo

然后你就会非常完美的发现。骨架已经搭建完毕。 有了这个，大家可以非常丝滑的将一个框架搭起。

方法二：

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

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、控制器、业务层代码…

然后执行命令：

goctl api go –api demo.api –dir .

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 install github.com/air–verse/air@latest
air –v

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

air

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

作用：

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

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

实现GET/POST/PUT/DELETE

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

get 查询

// 获取用户
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 创建

// 创建用户
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 更新

// 更新用户
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 删除

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

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

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

之后，运行命令：

goctl api go -api firstdemo.api -dir .

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

动态路由

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

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

• 路由路径利用 :变量名：

get /articles/:id

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

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

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

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

• method + handler 正确绑定

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

多个参数

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

GET /users/:userId/articles/:articleId

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

在框架中的位置

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

记住：中间件 ≠ handler ≠ logic 它是作为一个独立层存在的。

中间件的样子

// 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

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

通过运行

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

syntax = "v1"

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

user.api

syntax = "v1"

@server(
group: user
)

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

types.api

syntax = "v1"

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

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

最后命令行一生成：

goctl api go -api auth.api -dir .

RPC服务

首先，我们要先明确： RPC = 远程函数调用（像本地函数一样调用远程服务） 但注意！RPC 的核心不是“远程”，而是：

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

在go-zero里

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

在rpc与go-zero集合的项目中，往往少不了以下这四步： 1、 *.proto → 接口契约（定义有哪些方法、参数、返回值）

2、 goctl rpc new / protoc → 生成 RPC 服务骨架

3、etc/*.yaml → RPC 监听端口、服务名

4、internal/logic → 你真正写业务的地方

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

goctl rpc new

你将会得到：

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

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

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中的，启动函数。

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 更偏缓存、高吞吐

一、下载

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

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

– etcd.exe
– etcdctl.exe

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

etcd

启动！ 四、检测

netstat -ano | findstr :2379

看一看是否在监听！ 此时，你在回去运行一下项目，自然就跑通了。 五、为什么要用这个？ 这是很多人的疑惑！ 看etc内的配置文件：

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接口上，点击调用。

{
"pong": "hello"
}

修改

插入这些， 然后在，service User 里加一条： 方法名：GetUser 请求：GetUserRequest 响应：GetUserResponse 并新增 2 个 message： GetUserRequest { int64 id = 1; } GetUserResponse { int64 id = 1; string name = 2; }

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);
}

最关键的一步：

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

同个这个，生成rpc代码框架。 这里就是微服务中，被远程调用部分。 也是go-zero中的，两个最重要的核心之一！ 而另一个就是api，也就是对外！同时调用rpc的部分！

API

其实这个主要就两个步骤

一、生成 API 项目骨架

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

goctl api new userapi

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

(更新项目时使用)

goctl api go -api userapi.api -dir .

其实api还有很多组件需要掌握： gorm、auth、jwt… 但是这些其实都与gin框架大差不差。

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