go-zero

https://go-zero.dev/
Admin
go-zero is a web and RPC framework that integrates various engineering practices, providing...
Tokens:65,049
Snippets:708
Trust Score:7.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Clone go-zero Examples Repository

Source: https://go-zero.dev/examples

Clones the official go-zero examples repository to your local machine and navigates into the example directory. This provides access to the full suite of sample projects.

```shell
git clone https://github.com/zeromicro/go-zero.git
cd go-zero/example
```

--------------------------------

### Install Go Plugins with goctl

Source: https://go-zero.dev/getting-started/installation/protoc

Automates the installation of `protoc-gen-go` and `protoc-gen-go-grpc` using the goctl command-line tool. This simplifies the setup process for Go gRPC development within the go-zero ecosystem.

```bash
goctl env check --install --verbose
```

--------------------------------

### Install RabbitMQ Plugin

Source: https://go-zero.dev/components/queue/rabbitmq

Install the necessary go-zero contrib package for RabbitMQ support using the go get command.

```shell
go get github.com/zeromicro/zero-contrib/zrpc/rabbitmq
```

--------------------------------

### Setup Logging with Configuration and Exit on Error

Source: https://go-zero.dev/components/log/logc

Sets up the logging system using the provided configuration. If any error occurs during setup, the program will exit. This is a convenient way to ensure logging is correctly initialized.

```go
func MustSetup(c logx.LogConf)
```

```go
config := logx.LogConf{
    ServiceName: "exampleService",
    Mode:        "console",
}
logc.MustSetup(config)
```

--------------------------------

### Display goctl quickstart help

Source: https://go-zero.dev/reference/cli-guide/quickstart

Use this command to view the available flags and usage information for goctl quickstart. The service-type flag supports 'mono' for monolithic services and 'micro' for microservices.

```bash
$ goctl quickstart --help
```

--------------------------------

### Setting Up an MCP Server in Go

Source: https://go-zero.dev/guides/mcp/servers

Demonstrates how to create and start an MCP server using the go-zero framework. It includes loading configuration from a YAML file, disabling statistics logging, and registering the server. The server is started and deferred to stop on exit.

```go
package main


import (
  "github.com/zeromicro/go-zero/core/conf"
  "github.com/zeromicro/go-zero/core/logx"
  "github.com/zeromicro/go-zero/mcp"
)


func main() {
  // Load configuration from YAML file
  var c mcp.McpConf
  conf.MustLoad("config.yaml", &c)


  // Optional: Disable stats logging
  logx.DisableStat()


  // Create MCP server
  server := mcp.NewMcpServer(c)


  // Register tools, prompts, and resources (examples below)


  // Start the server and ensure it's stopped on exit
  defer server.Stop()
  server.Start()
}
```

--------------------------------

### Start Gateway Service

Source: https://go-zero.dev/guides/gateway/grpc

Starts the Go-Zero gateway service. Ensure you are in the correct directory.

```bash
go run gateway.go
```

--------------------------------

### Cache Setup with go-zero

Source: https://go-zero.dev/components/cache/redis-cache

Demonstrates how to set up Redis cache configuration and initialize a model with caching capabilities.

```go
import (
    "github.com/zeromicro/go-zero/core/stores/cache"
    "github.com/zeromicro/go-zero/core/stores/sqlx"
)


// Single Redis node
cacheConf := cache.CacheConf{
    {RedisConf: c.Redis, Weight: 100},
}


// goctl-generated models wire this for you:
conn := sqlx.NewMysql(c.DataSource)
userModel := model.NewUserModel(conn, cacheConf)
```

--------------------------------

### Install Harbor

Source: https://go-zero.dev/guides/deployment/ci-cd

Installs Harbor using the provided installation script after configuration.

```bash
sudo ./install.sh
```

--------------------------------

### Starting Kafka Consumers in main.go

Source: https://go-zero.dev/guides/queue/kafka

Initializes and starts the Kafka consumers within the main application entry point. It loads configuration, sets up the service context, and adds all registered consumers to a `service.ServiceGroup` for concurrent execution.

```go
package main


import (
    "context"
    "flag"
    "github.com/zeromicro/go-zero/core/service"
    "zerodocgo/internal/mqs"
    "zerodocgo/internal/svc"


    "github.com/zeromicro/go-zero/core/conf"
    "github.com/zeromicro/go-zero/rest"
    "zerodocgo/internal/config"
)


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


func main() {
    flag.Parse()


    var c config.Config
    conf.MustLoad(*configFile, &c)


    server := rest.MustNewServer(c.RestConf)
    defer server.Stop()


    svcCtx := svc.NewServiceContext(c)
    ctx := context.Background()
    serviceGroup := service.NewServiceGroup()
    defer serviceGroup.Stop()


    for _, mq := range mqs.Consumers(ctx, svcCtx) {
        serviceGroup.Add(mq)
    }


    serviceGroup.Start()
}
```

--------------------------------

### Install protoc on Linux

Source: https://go-zero.dev/getting-started/installation/protoc

Installs the protobuf compiler (protoc) on Linux by downloading a release zip file, extracting it to a local directory, and adding the binary to the system's PATH. This ensures protoc is available for use.

```bash
# Find the latest release at https://github.com/protocolbuffers/protobuf/releases
PB_VERSION=27.2
wget https://github.com/protocolbuffers/protobuf/releases/download/v${PB_VERSION}/protoc-${PB_VERSION}-linux-x86_64.zip
unzip protoc-${PB_VERSION}-linux-x86_64.zip -d $HOME/.local
export PATH=$PATH:$HOME/.local/bin
```

--------------------------------

### Prepare Harbor Installation

Source: https://go-zero.dev/guides/deployment/ci-cd

Extracts the Harbor offline installer and copies the template configuration file for customization.

```bash
tar -xzf harbor-offline-installer-v2.x.0.tgz
cd harbor
cp harbor.yml.tmpl harbor.yml
```

--------------------------------

### Start gRPC Service

Source: https://go-zero.dev/guides/gateway/grpc

Starts the gRPC server. Ensure you are in the correct directory.

```bash
go run hello.go
Starting rpc server at 0.0.0.0:8080...
```

--------------------------------

### Create Directory and Navigate

Source: https://go-zero.dev/guides/quickstart/api-service

Creates a new directory for the user API project and navigates into it. This is the initial setup step before defining the API.

```bash
mkdir user-api && cd user-api
```

--------------------------------

### Verify Protobuf and Go Plugin Installation

Source: https://go-zero.dev/getting-started/installation/protoc

Verifies the successful installation of the protobuf compiler and its associated Go plugins by checking their versions. This confirms that protoc, protoc-gen-go, and protoc-gen-go-grpc are correctly installed and accessible.

```bash
protoc --version
# libprotoc 27.2

protoc-gen-go --version
# protoc-gen-go v1.34.2

protoc-gen-go-grpc --version
# protoc-gen-go-grpc 1.4.0
```

--------------------------------

### Install Go on macOS

Source: https://go-zero.dev/getting-started/installation/golang

Installs Go using the Homebrew package manager. This is the recommended method for macOS users.

```bash
brew install go
```

--------------------------------

### MustSetup

Source: https://go-zero.dev/components/log/logc

Sets up the logging system with the provided configuration. The program exits if an error occurs during setup.

```APIDOC
## MustSetup

### Description
Sets up logging with the given configuration. Exits on error.

### Function Signature
```go
func MustSetup(c logx.LogConf)
```

### Example
```go
config := logx.LogConf{
    ServiceName: "exampleService",
    Mode:        "console",
}
logc.MustSetup(config)
```
```

--------------------------------

### Run Go-Zero HTTP Service

Source: https://go-zero.dev/guides/quickstart/hello-world

Starts the go-zero HTTP service. Ensure the project has been scaffolded and dependencies are managed. The service will typically start listening on a default port like 8888.

```bash
go run greet.go
```

--------------------------------

### Verify Go Installation

Source: https://go-zero.dev/getting-started/installation/golang

Checks the currently installed version of Go. Ensure the output version is 1.21 or higher.

```bash
go version
```

--------------------------------

### Initial Login Request and Response

Source: https://go-zero.dev/guides/http/server/response-ext

Example `curl` commands demonstrating the request and the default response format before applying extensions.

```bash
$ cd demo
$ go mod tidy
$ go run user.go
# before
curl --location '127.0.0.1:8888/user/login' \
--header 'Content-Type: application/json' \
--data '{
    "username":"go-zero",
    "password":"123456"
}'
{"uid":1,"name":"go-zero"}


# after
curl --location '127.0.0.1:8888/user/login' \
--header 'Content-Type: application/json' \
--data '{
    "username":"go-zero",
    "password":"111111"
}'
code: 1001, msg: invalid username or password
```

--------------------------------

### Install Go on Linux

Source: https://go-zero.dev/getting-started/installation/golang

Downloads and extracts the Go binary distribution to /usr/local. Requires root privileges for directory operations.

```bash
wget https://go.dev/dl/go1.23.4.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.23.4.linux-amd64.tar.gz
```

--------------------------------

### Install goctl Tooling

Source: https://go-zero.dev/examples

Installs the goctl command-line tool, which is required for scaffolding and managing go-zero services. This command fetches the latest version from the official repository.

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

--------------------------------

### Start Pyroscope Locally using Docker

Source: https://go-zero.dev/components/observability/profiling

This snippet shows how to pull the Pyroscope Docker image and run a container to start a local Pyroscope instance. This is the first step to enable continuous profiling.

```bash
docker pull grafana/pyroscope
docker run -it -p 4040:4040 grafana/pyroscope
```

--------------------------------

### Kafka Configuration Example

Source: https://go-zero.dev/guides/queue/kafka

Example of Kafka consumer configuration within the application's YAML configuration file. This includes broker addresses, group ID, topic, and consumer/processor counts.

```yaml
Name: mq
Host: 0.0.0.0
Port: 8888


#kq
KqConsumerConf:
  Name: kqConsumer
  Brokers:
    - 127.0.1:9092
  Group: kqConsumer
  Topic: payment-success
  Offset: first
  Consumers: 8
  Processors: 8
```

--------------------------------

### Install go-queue Dependency

Source: https://go-zero.dev/guides/queue/kafka

Installs the latest version of the go-queue library, which provides Kafka consumer functionality.

```bash
go get github.com/zeromicro/go-queue@latest
```

--------------------------------

### Run the Go-Zero Service

Source: https://go-zero.dev/guides/quickstart/api-service

Starts the generated Go-zero API service. This command should be run from the project's root directory.

```bash
go run user.go
```

--------------------------------

### Install protoc on macOS

Source: https://go-zero.dev/getting-started/installation/protoc

Installs the protobuf compiler (protoc) on macOS using the Homebrew package manager. This is a prerequisite for generating Go types and gRPC stubs from .proto files.

```bash
brew install protobuf
```

--------------------------------

### Run go-zero Service and Generate Load

Source: https://go-zero.dev/components/observability/profiling

This bash script demonstrates how to start the configured go-zero service and then use the 'hey' tool to generate HTTP load against it. This is necessary to trigger and observe the profiling data in Pyroscope.

```bash
# Start the service
go run greet.go -f etc/greet.yaml


# In another terminal — generate load
hey -c 100 -z 60m "http://localhost:8888/ping"
```

--------------------------------

### Configure Direct and Kubernetes Target Connections

Source: https://go-zero.dev/guides/microservice/load-balancing

Provides examples for connecting to a single instance using a direct target or using Kubernetes DNS for service resolution.

```yaml
OrderRpc:
  Target: "direct://127.0.0.1:8080"

OrderRpc:
  Target: "k8s://order-rpc-svc.default:8080"
```

--------------------------------

### API DSL for Route Prefixing

Source: https://go-zero.dev/reference/api-dsl/route-prefix

This example demonstrates how to use the `prefix` keyword in the go-zero API DSL to define route prefixes for different API versions.

```APIDOC
## API DSL for Route Prefixing

### Description
This example demonstrates how to use the `prefix` keyword in the go-zero API DSL to define route prefixes for different API versions.

### Method
N/A (DSL Definition)

### Endpoint
N/A (DSL Definition)

### Parameters
N/A

### Request Example
N/A

### Response
N/A

```go
syntax = "v1"


type UserV1 {
    Name string `json:"name"`
}


type UserV2 {
    Name string `json:"name"`
}


@server (
    prefix: /v1
)
service user-api {
    @handler usersv1
    get /users returns ([]UserV1)
}


@server (
    prefix: /v2
)
service user-api {
    @handler usersv2
    get /users returns ([]UserV2)
}
```
```

--------------------------------

### Request Examples with Uniform Response Format

Source: https://go-zero.dev/guides/http/server/response-ext

Demonstrates `curl` commands and their corresponding outputs for both successful and error cases after implementing the uniform response format using go-zero extensions.

```bash
$ go run user.go
# no error case
curl --location '127.0.0.1:8888/user/login' \
--header 'Content-Type: application/json' \
--data '{
    "username":"go-zero",
    "password":"123456"
}'
{"code":0,"msg":"ok","data":{"uid":1,"name":"go-zero"}}


# error case
curl --location '127.0.0.1:8888/user/login' \
--header 'Content-Type: application/json' \
--data '{
    "username":"go-zero",
    "password":"111111"
}'
{"code":1001,"msg":"invalid username or password"}
```

--------------------------------

### systemd Service Management Commands

Source: https://go-zero.dev/guides/deployment/bare-metal

Commands to enable and start the apicode service using systemctl.

```bash
sudo systemctl enable apicode
sudo systemctl start apicode

```

--------------------------------

### Implement Get User Info Logic

Source: https://go-zero.dev/guides/quickstart/api-service

Implements the business logic for retrieving user information. It returns mock user data based on the provided user ID.

```go
func (l *GetUserInfoLogic) GetUserInfo(req *types.UserInfoReq) (resp *types.UserInfoResp, err error) {
    // In production: query from DB using l.svcCtx.DB
    return &types.UserInfoResp{
        Id:       req.Id,
        Username: "alice",
        Email:    "alice@example.com",
    }, nil
}
```

--------------------------------

### Define User API with go-zero Syntax

Source: https://go-zero.dev/guides/http/server/response-ext

An example API definition file (`user.api`) for a login endpoint, specifying request and response types.

```go
syntax = "v1"

type LoginRequest {
    Username string `json:"username"`
    Password string `json:"password"`
}

type LoginResponse {
    UID int64 `json:"uid"`
    Name string `json:"name"`
}

service user {
    @handler login
    post /user/login (LoginRequest) returns (LoginResponse)
}
```

--------------------------------

### Validate Go Environment

Source: https://go-zero.dev/getting-started/installation/golang

Displays the current Go environment configuration, including GOPATH, GOBIN, and GOMODCACHE, to verify correct setup.

```bash
go env GOPATH GOBIN GOMODCACHE
```

--------------------------------

### Defining API Routes and Path Parameters in go-zero

Source: https://go-zero.dev/reference/api-dsl/route-rule

This example demonstrates how to define various HTTP routes in the go-zero API DSL. It includes static routes, routes with dynamic path parameters, and the corresponding request struct definitions with path tags.

```go-zero-api
syntax = "v1"

type DemoPath3Req {
    Id int64 `path:"id"`
}

type DemoPath4Req {
    Id   int64  `path:"id"`
    Name string `path:"name"`
}

type DemoPath5Req {
    Id   int64  `path:"id"`
    Name string `path:"name"`
    Age  int    `path:"age"`
}

type DemoReq {}
type DemoResp {}

service Demo {
    @handler demoPath1
    get /foo (DemoReq) returns (DemoResp)

    @handler demoPath2
    get /foo/bar (DemoReq) returns (DemoResp)

    @handler demoPath3
    get /foo/bar/:id (DemoPath3Req) returns (DemoResp)

    @handler demoPath4
    get /foo/bar/:id/:name (DemoPath4Req) returns (DemoResp)

    @handler demoPath5
    get /foo/bar/:id/:name/:age (DemoPath5Req) returns (DemoResp)

    @handler demoPath6
    get /foo/bar/baz-qux (DemoReq) returns (DemoResp)

    @handler demoPath7
    get /foo/bar_baz/123 (DemoReq) returns (DemoResp)
}
```

--------------------------------

### Scaffold Go-Zero Project with goctl

Source: https://go-zero.dev/guides/quickstart/hello-world

This command scaffolds a new go-zero HTTP API project. It requires goctl to be installed. The output is a directory structure containing configuration, handlers, logic, and the main entry point.

```bash
goctl api new greet
cd greet
go mod tidy
```

--------------------------------

### Proto file defining multiple services

Source: https://go-zero.dev/reference/proto-dsl/services-group

This proto file defines multiple services and their associated messages. It's used as an example to demonstrate go-zero's service grouping capabilities.

```proto
syntax = "proto3";


package user;


option go_package = "github.com/example/user";


message LoginReq{}
message LoginResp{}
message UserInfoReq{}
message UserInfoResp{}
message UserInfoUpdateReq{}
message UserInfoUpdateResp{}
message UserListReq{}
message UserListResp{}


message UserRoleListReq{}
message UserRoleListResp{}
message UserRoleUpdateReq{}
message UserRoleUpdateResp{}
message UserRoleInfoReq{}
message UserRoleInfoResp{}
message UserRoleAddReq{}
message UserRoleAddResp{}
message UserRoleDeleteReq{}
message UserRoleDeleteResp{}




message UserClassListReq{}
message UserClassListResp{}
message UserClassUpdateReq{}
message UserClassUpdateResp{}
message UserClassInfoReq{}
message UserClassInfoResp{}
message UserClassAddReq{}
message UserClassAddResp{}
message UserClassDeleteReq{}
message UserClassDeleteResp{}


service UserService{
  rpc Login (LoginReq) returns (LoginResp);
  rpc UserInfo (UserInfoReq) returns (UserInfoResp);
  rpc UserInfoUpdate (UserInfoUpdateReq) returns (UserInfoUpdateResp);
  rpc UserList (UserListReq) returns (UserListResp);

  rpc UserRoleList (UserRoleListReq) returns (UserRoleListResp);
  rpc UserRoleUpdate (UserRoleUpdateReq) returns (UserRoleUpdateResp);
  rpc UserRoleInfo (UserRoleInfoReq) returns (UserRoleInfoResp);
  rpc UserRoleAdd (UserRoleAddReq) returns (UserRoleAddResp);
  rpc UserRoleDelete (UserRoleDeleteReq) returns (UserRoleDeleteResp);

  rpc UserClassList (UserClassListReq) returns (UserClassListResp);
  rpc UserClassUpdate (UserClassUpdateReq) returns (UserClassUpdateResp);
  rpc UserClassInfo (UserClassInfoReq) returns (UserClassInfoResp);
  rpc UserClassAdd (UserClassAddReq) returns (UserClassAddResp);
  rpc UserClassDelete (UserClassDeleteReq) returns (UserClassDeleteResp);
}

```

--------------------------------

### Configure Aligned PeriodLimit

Source: https://go-zero.dev/components/resilience/period-limiter

Shows how to use the Align option to synchronize rate limit windows, such as aligning to the start of a day for daily quotas.

```go
package main

import (
	"fmt"
	"github.com/zeromicro/go-zero/core/limit"
	"github.com/zeromicro/go-zero/core/stores/redis"
)

func main() {
	store := redis.MustNewRedis(redis.RedisConf{Host: "localhost:6379"})
	limiter := limit.NewPeriodLimit(86400, 5, store, "sms_limit", limit.Align())

	result, err := limiter.Take("user1")
	if err != nil {
		fmt.Println("Error:", err)
		return
	}

	switch result {
	case limit.Allowed:
		fmt.Println("SMS request allowed")
	case limit.HitQuota:
		fmt.Println("Hit the daily quota")
	case limit.OverQuota:
		fmt.Println("Over the daily quota")
	default:
		fmt.Println("Unknown status")
	}
}
```

--------------------------------

### Gateway Server Main Function

Source: https://go-zero.dev/guides/gateway/grpc

The main function to start the go-zero gRPC gateway server, loading configuration from a file.

```go
package main


import (
    "flag"


    "github.com/zeromicro/go-zero/core/conf"
    "github.com/zeromicro/go-zero/gateway"
)


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


func main() {
    flag.Parse()


    var c gateway.GatewayConf
    conf.MustLoad(*configFile, &c)
    gw := gateway.MustNewServer(c)
    defer gw.Stop()
    gw.Start()
}
```

--------------------------------

### Scaffold Go Zero RPC Service

Source: https://go-zero.dev/guides/quickstart/rpc-service

Initializes a new RPC service using the goctl command-line tool. This command generates the basic project structure, including proto files and server boilerplate. It requires protoc, protoc-gen-go, and protoc-gen-go-grpc to be installed.

```bash
goctl rpc new user
cd user
go mod tidy
```

--------------------------------

### Configure and Run RPC Server

Source: https://go-zero.dev/guides/quickstart/rpc-service

Configures the RPC server by setting the listen address and port in the `user.yaml` configuration file. It then starts the RPC server using the main entrypoint file (`user.go`). The default port is 8080.

```yaml
Name: user.rpc
ListenOn: 0.0.0.0:8080
```

```bash
go run user.go
# Starting rpc server at 0.0.0.0:8080...
```

--------------------------------

### Implement L1/L2 Cache Pattern (Go)

Source: https://go-zero.dev/components/cache/memory-cache

Provides an example of combining an in-process memory cache (L1) with a Redis-backed cache (L2) to reduce read traffic to Redis. It includes methods for getting and invalidating user data across both cache layers.

```Go
import (
	"context"
	"fmt"
	"github.com/zeromicro/go-zero/core/collection"
	"github.com/zeromicro/go-zero/core/stores/cache"
)

type UserRepo struct {
	l1  *collection.Cache   // in-process, 30 s TTL
	l2  cache.Cache         // Redis-backed, 10 min TTL
	db  *model.UserModel
}

func (r *UserRepo) GetUser(ctx context.Context, id int64) (*User, error) {
	key := fmt.Sprintf("user:%d", id)

	// L1 hit?
	if v, ok := r.l1.Get(key); ok {
		return v.(*User), nil
	}

	// L2 hit? (Redis)
	var user User
	err := r.l2.TakeCtx(ctx, &user, key, func(v any) error {
		row, err := r.db.FindOne(ctx, id)
		if err != nil {
			return err
		}
		*v.(*User) = *row
		return nil
	})
	if err != nil {
		return nil, err
	}

	// Populate L1
	r.l1.Set(key, &user)
	return &user, nil
}

func (r *UserRepo) InvalidateUser(ctx context.Context, id int64) error {
	key := fmt.Sprintf("user:%d", id)
	r.l1.Del(key)          // remove from local cache
	return r.l2.Del(key)   // remove from Redis
}
```

--------------------------------

### Test User Service Endpoints with cURL

Source: https://go-zero.dev/guides/quickstart/api-service

Demonstrates how to test the Login and GetUserInfo endpoints of the user service using cURL commands. It shows example requests and their expected responses.

```bash
# Login
curl -s -X POST http://localhost:8888/user/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"secret"}'
# {"token":"mock-jwt-token-for-admin"}


# Get user info
curl http://localhost:8888/user/1
# {"id":1,"username":"alice","email":"alice@example.com"}
```

--------------------------------

### Initialize Go-Zero Project

Source: https://go-zero.dev/guides/http/server/response-ext

Basic commands to create a new Go module for a go-zero project.

```bash
$ mkdir demo && cd demo
$ go mod init demo
```

--------------------------------

### Generic Redis Commands with `DoCtx`

Source: https://go-zero.dev/components/cache/redis-cache

Demonstrates how to execute arbitrary Redis commands using `DoCtx` for commands not covered by the typed helper methods. Includes setting up a Redis client and handling command errors.

```go
import "github.com/zeromicro/go-zero/core/stores/redis"


rdb := redis.MustNewRedis(redis.RedisConf{
    Host: "127.0.0.1:6379",
    Type: redis.NodeType,
})


# Execute any Redis command
cmd := rdb.Do(ctx, "SET", "key", "value", "EX", 3600)
if err := cmd.Err(); err != nil {
    # handle error
}


# Retrieve result
val, err := rdb.Do(ctx, "GET", "key").Text()
```

--------------------------------

### Start GitLab Service

Source: https://go-zero.dev/guides/deployment/ci-cd

Starts the GitLab service in detached mode using Docker Compose.

```bash
docker-compose up -d
```

--------------------------------

### Initialize go module project

Source: https://go-zero.dev/guides/grpc/server/example

Creates a new directory for the project and initializes it as a Go module. This is the first step in setting up a new go-zero project.

```bash
mkdir demo && cd demo
go mod init demo
```

--------------------------------

### Initialize Configuration (With Go Module)

Source: https://go-zero.dev/reference/cli-guide/config

Shows how to initialize a goctl configuration file in a directory that already has a Go module. This adds `goctl.yaml` to the existing directory structure.

```bash
$ ll
total 8
-rw-r--r--  1 ***  staff    29B Apr 10 16:35 go.mod
$ goctl config init
goctl.yaml generated in ~/demo/goctl-config/goctl.yaml
$ ll
total 16
-rw-r--r--  1 ***  staff    29B Apr 10 16:35 go.mod
-rw-r--r--  1 ***  staff   3.3K Apr 10 16:37 goctl.yaml

```

--------------------------------

### Initialize and Use PeriodLimit

Source: https://go-zero.dev/components/resilience/period-limiter

Demonstrates how to instantiate a PeriodLimit with a Redis store and check request eligibility using the Take method.

```go
package main

import (
	"fmt"
	"github.com/zeromicro/go-zero/core/limit"
	"github.com/zeromicro/go-zero/core/stores/redis"
)

func main() {
	store := redis.MustNewRedis(redis.RedisConf{Host: "localhost:6379"})
	limiter := limit.NewPeriodLimit(60, 10, store, "exampleKey")

	result, err := limiter.Take("user1")
	if err != nil {
		fmt.Println("Error:", err)
		return
	}

	switch result {
	case limit.Allowed:
		fmt.Println("Request allowed")
	case limit.HitQuota:
		fmt.Println("Hit the quota")
	case limit.OverQuota:
		fmt.Println("Over the quota")
	default:
		fmt.Println("Unknown status")
	}
}
```

--------------------------------

### Install go-queue Dependency

Source: https://go-zero.dev/guides/queue/beanstalkd

Command to install the latest version of the go-queue library, which provides the necessary components for interacting with Beanstalkd.

```bash
$ go get github.com/zeromicro/go-queue@latest
```

--------------------------------

### Create a Sample go-zero Service

Source: https://go-zero.dev/components/observability/profiling

This command uses goctl to quickly scaffold a new go-zero microservice project. It initializes a monorepo structure and navigates into the API directory.

```bash
goctl quickstart -t mono
cd greet/api
```

--------------------------------

### Initialize Configuration (No Go Module)

Source: https://go-zero.dev/reference/cli-guide/config

Demonstrates initializing a goctl configuration file in a directory without an existing Go module. This creates a `goctl.yaml` file and a `go.mod` file.

```bash
$ ll
total 0
$ goctl config init
goctl.yaml generated in ~/demo/goctl-config/goctl.yaml
$ ls
go.mod     goctl.yaml
$ cat go.mod
module goctl-config

go 1.20

```

--------------------------------

### Prepare to generate a microservice

Source: https://go-zero.dev/reference/cli-guide/quickstart

This command prepares the directory structure for generating a microservice. It involves navigating to the home directory and creating a new project folder.

```bash
# enter user home
$ cd ~


# mkdir
$ mkdir quickstart && cd quickstart


```

--------------------------------

### GET /user/info

Source: https://go-zero.dev/examples/rest-api-jwt

Retrieves information for the currently authenticated user.

```APIDOC
## GET /user/info

### Description
Fetches profile information for the authenticated user. Requires a valid JWT in the Authorization header.

### Method
GET

### Endpoint
http://localhost:8888/user/info

### Headers
- **Authorization** (string) - Required - Bearer <accessToken>

### Response
#### Success Response (200)
- **id** (integer) - User unique identifier
- **username** (string) - User username
- **role** (string) - User role

#### Response Example
{
  "id": 1,
  "username": "alice",
  "role": "user"
}
```

--------------------------------

### Implementing and Registering Server-Wide Middleware

Source: https://go-zero.dev/guides/http/server/middleware

Demonstrates how to create a custom middleware function and register it globally using the server instance. This approach ensures the middleware executes for every incoming request.

```go
func LogMiddleware(next http.HandlerFunc) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        log.Printf("-> %s %s", r.Method, r.URL.Path)
        next(w, r)
    }
}

server := rest.MustNewServer(c.RestConf)
server.Use(LogMiddleware)
```

--------------------------------

### GET /user/:id

Source: https://go-zero.dev/guides/quickstart/api-service

Retrieves the information for a specific user by their ID.

```APIDOC
## GET /user/:id

### Description
Retrieves the information for a specific user by their ID.

### Method
GET

### Endpoint
/user/:id

### Parameters
#### Path Parameters
- **id** (int64) - Required - The unique identifier of the user.

### Response
#### Success Response (200)
- **id** (int64) - The user's ID.
- **username** (string) - The user's username.
- **email** (string) - The user's email address.

#### Response Example
```json
{
  "id": 1,
  "username": "alice",
  "email": "alice@example.com"
}
```
```

--------------------------------

### Generate and Build Go-Zero Project

Source: https://go-zero.dev/guides/deployment/bare-metal

Commands to generate the go-zero project structure and build the application.

```bash
cd apicode && goctl api go -api *.api -dir ./ 
go mod tidy

```

--------------------------------

### Customizing CORS Origins

Source: https://go-zero.dev/community/faq/http/cors

Example of how to restrict allowed origins for cross-origin requests.

```APIDOC
## rest.WithCors

### Description
Restricts cross-origin requests to specific allowed domains.

### Usage
```go
server := rest.MustNewServer(c, rest.WithCors("example.com"))
```
```

--------------------------------

### Customizing CORS Headers

Source: https://go-zero.dev/community/faq/http/cors

Example of how to restrict allowed headers for cross-origin requests.

```APIDOC
## rest.WithCorsHeaders

### Description
Configures the server to accept specific custom headers in cross-origin requests.

### Usage
```go
server := rest.MustNewServer(c, rest.WithCorsHeaders("UserHeader1", "UserHeader2"))
```
```

--------------------------------

### Supervisor Service Management Commands

Source: https://go-zero.dev/guides/deployment/bare-metal

Commands to update supervisor configuration and start the apicode service.

```bash
sudo supervisorctl update
sudo supervisorctl start apicode

```

--------------------------------

### Complex CORS Settings

Source: https://go-zero.dev/community/faq/http/cors

Example of how to implement advanced CORS logic using custom middleware functions.

```APIDOC
## rest.WithCustomCors

### Description
Allows full control over CORS headers by providing a custom middleware function.

### Usage
```go
server := rest.MustNewServer(c, rest.WithCustomCors(func(header http.Header) {
  header.Set("Access-Control-Allow-Origin", "*")
  header.Add("Access-Control-Allow-Headers", "UserHeader1, UserHeader2")
}, nil, "*"))
```
```

--------------------------------

### GET /foo/bar/:id

Source: https://go-zero.dev/reference/api-dsl/route-rule

Defines a route with a single path parameter mapping to a request body field.

```APIDOC
## GET /foo/bar/:id

### Description
Defines a route that captures a path parameter 'id' and maps it to the request body.

### Method
GET

### Endpoint
/foo/bar/:id

### Parameters
#### Path Parameters
- **id** (int64) - Required - The identifier captured from the URL path.

### Request Example
N/A (Path parameter used)

### Response
#### Success Response (200)
- **DemoResp** (object) - The standard response object for the demo service.

#### Response Example
{
  "message": "success"
}
```

--------------------------------

### Business Logic Implementation (Go)

Source: https://go-zero.dev/guides/grpc/server/example

This Go code demonstrates how to implement the business logic for a gRPC service method. It shows the structure of the logic handler and how to process requests and return responses.

```go
package logic


import (
    "context"

    "demo/greet"
    "demo/internal/svc"

    "github.com/zeromicro/go-zero/core/logx"
)


type PingLogic struct {
    ctx    context.Context
    svcCtx *svc.ServiceContext
    logx.Logger
}

func NewPingLogic(ctx context.Context, svcCtx *svc.ServiceContext) *PingLogic {
    return &PingLogic{
        ctx:    ctx,
        svcCtx: svcCtx,
        Logger: logx.WithContext(ctx),
    }
}

func (l *PingLogic) Ping(in *greet.Request) (*greet.Response, error) {
    return &greet.Response{
        Pong: "pong",
    }, nil
}
```

--------------------------------

### Configure Service Discovery with Etcd

Source: https://go-zero.dev/guides/microservice/load-balancing

Demonstrates how to enable automatic P2C load balancing by configuring an etcd service discovery target in the go-zero configuration file.

```yaml
OrderRpc:
  Etcd:
    Hosts:
      - 127.0.0.1:2379
    Key: order.rpc
```

--------------------------------

### Generated Code-Message Format Example

Source: https://go-zero.dev/reference/cli-guide/swagger

Illustrates the structure of the response body when the code-message format is enabled for Swagger generation.

```json
{
  "code": 0,
  "msg": "OK",
  "data": {original response body}
}
```

--------------------------------

### Manual Read-Through Cache Operation with `TakeCtx`

Source: https://go-zero.dev/components/cache/redis-cache

Demonstrates manual implementation of the read-through pattern using `cache.TakeCtx`. It includes setting up stats, cache instance, and a custom loader function.

```go
stats := cache.NewStat("user")         # named stat group for metrics
c := cache.New(cacheConf, nil, stats, model.ErrNotFound)


var user User
er := c.TakeCtx(ctx, &user, fmt.Sprintf("user:%d", id), func(v any) error {
    row, err := db.FindOne(ctx, id)
    if err != nil {
        return err
    }
    *v.(*User) = *row
    return nil
})
```

--------------------------------

### GET /foo/bar/:id/:name

Source: https://go-zero.dev/reference/api-dsl/route-rule

Defines a route with multiple path parameters mapping to request body fields.

```APIDOC
## GET /foo/bar/:id/:name

### Description
Defines a route that captures 'id' and 'name' as path parameters.

### Method
GET

### Endpoint
/foo/bar/:id/:name

### Parameters
#### Path Parameters
- **id** (int64) - Required - The identifier.
- **name** (string) - Required - The name parameter.

### Request Example
N/A

### Response
#### Success Response (200)
- **DemoResp** (object) - The standard response object.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### Scaffold go-zero Project

Source: https://go-zero.dev/examples/rest-api-jwt

Command to initialize a new go-zero API project using the goctl tool based on an existing API definition file.

```bash
goctl api go -api user.api -dir .
```

--------------------------------

### Batch Cache Invalidation

Source: https://go-zero.dev/components/cache/redis-cache

Example of atomically deleting multiple cache keys, including primary and secondary index keys.

```go
# Delete multiple keys atomically
er := c.DelCtx(ctx,
    fmt.Sprintf("user:%d", id),
    fmt.Sprintf("user:name:%s", username),  # also delete secondary index key
)
```

--------------------------------

### Configure and Run the RPC Server

Source: https://go-zero.dev/guides/quickstart/rpc-service

Configure the RPC server by editing the configuration file and then run the server using the Go command.

```APIDOC
## Configure and Run the RPC Server

### Description
Configure the RPC server by editing the configuration file and then run the server using the Go command.

### Configuration File
`etc/user.yaml`

### Example Configuration
```yaml
Name: user.rpc
ListenOn: 0.0.0.0:8080
```

### Run Command
```bash
go run user.go
```

### Output
```
Starting rpc server at 0.0.0.0:8080...
```
```

--------------------------------

### Write-Through Cache Update

Source: https://go-zero.dev/components/cache/redis-cache

Example of a write-through cache operation where an updated object is immediately written to Redis after a database update.

```go
# After updating the DB record:
er := c.SetWithExpire(fmt.Sprintf("user:%d", user.Id), &user, time.Hour)
```

--------------------------------

### Clone Go-Zero Repository

Source: https://go-zero.dev/community

Instructions for cloning the go-zero repository to your local machine. This is a prerequisite for making contributions.

```bash
git clone https://github.com/<you>/go-zero.git
```

--------------------------------

### Hello Proto Definition

Source: https://go-zero.dev/guides/gateway/grpc

Defines a simple gRPC service 'Hello' with a 'Ping' method for demonstration purposes.

```protobuf
syntax = "proto3";


package hello;


option go_package = "./hello";


message Request {
}


message Response {
  string msg = 1;
}


service Hello {
  rpc Ping(Request) returns(Response);
}
```

--------------------------------

### Implement File Server in go-zero

Source: https://go-zero.dev/community/faq/http/fileserver

This snippet demonstrates how to configure a go-zero REST server to serve files from a local directory using the rest.WithFileServer option. It maps a URL path prefix to a physical directory on the filesystem.

```go
package main

import (
	"net/http"
	"github.com/zeromicro/go-zero/rest"
)

func main() {
	server := rest.MustNewServer(rest.RestConf{
		Host: "localhost",
		Port: 4000,
	}, rest.WithFileServer("/static", http.Dir("html")))
	defer server.Stop()

	server.AddRoute(rest.Route{
		Method:  http.MethodGet,
		Path:    "/hello",
		Handler: helloHandler,
	})

	server.Start()
}

func helloHandler(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
	w.Write([]byte("Hello, World!"))
}
```

--------------------------------

### Test Service with Curl

Source: https://go-zero.dev/reference/cli-guide/docker

Sends an HTTP GET request to the running service at http://localhost:8888/from/you and displays the response headers and body.

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

--------------------------------

### Manual Circuit Breaker Implementation

Source: https://go-zero.dev/components/resilience/circuit-breaker

Shows how to instantiate a manual breaker using breaker.NewBreaker and execute protected calls with basic error tracking.

```go
import "github.com/zeromicro/go-zero/core/breaker"

b := breaker.NewBreaker(breaker.WithName("payment-gateway"))

err := b.Do(func() error {
    return callPaymentAPI(req)
})
```

--------------------------------

### Read-Through Cache Operation (Generated Model)

Source: https://go-zero.dev/components/cache/redis-cache

Example of how a goctl-generated model uses the `Take` operation internally to fetch data from the cache or database.

```go
var user model.User
er := userModel.FindOne(ctx, userId) # goctl model calls Take internally
```

--------------------------------

### Run Go-Zero Service Locally

Source: https://go-zero.dev/guides/deployment/bare-metal

Command to run the go-zero service locally and the URL to test the API.

```bash
go run apicode.go
# Visit http://127.0.0.1:8888/hello?msg=world

```

--------------------------------

### Configure Beanstalkd for Consumer in go-zero

Source: https://go-zero.dev/guides/queue/beanstalkd

Example configuration for the Beanstalkd queue when used as a consumer. It includes the DqConf with Beanstalks endpoints and Redis configuration for deduplication.

```yaml
Name: dq
Host: 0.0.0.0
Port: 8889


.....


#dq
DqConf:
  Beanstalks:
    - Endpoint: 127.0.0.1:7771
      Tube: tube1
    - Endpoint: 127.0.0.1:7772
      Tube: tube2
  Redis:
    Host: 127.0.0.1:6379
    Type: node
```

--------------------------------

### Get Jenkins Public SSH Key

Source: https://go-zero.dev/guides/deployment/bare-metal

Command to display the Jenkins server's public SSH key, needed for GitLab and deployment server access.

```bash
# On the Jenkins server — copy its public key
cat /root/.ssh/id_rsa.pub

```

--------------------------------

### Upload File to Cloud Storage

Source: https://go-zero.dev/guides/http/file-upload

Example of integrating AWS S3 SDK to upload file streams directly to cloud object storage instead of the local disk.

```go
func (l *UploadFileLogic) uploadToS3(file multipart.File, key string) (string, error) {
    _, err := l.svcCtx.S3.PutObject(l.ctx, &s3.PutObjectInput{
        Bucket: aws.String(l.svcCtx.Config.S3Bucket),
        Key:    aws.String(key),
        Body:   file,
    })
    if err != nil {
        return "", err
    }
    return fmt.Sprintf("https://%s.s3.amazonaws.com/%s", l.svcCtx.Config.S3Bucket, key), nil
}
```

--------------------------------

### Generate a monolithic HTTP service

Source: https://go-zero.dev/reference/cli-guide/quickstart

This command generates a minimized HTTP service and starts it. Ensure you are in the desired project directory before running. The service will be accessible at http://127.0.0.1:8888/ping.

```bash
# enter user home
$ cd ~


# mkdir
$ mkdir quickstart && cd quickstart


# generate mono service
$ goctl quickstart --service-type mono
go: creating new go.mod: module greet
>> Generating quickstart api project...
Done.
>> go mod tidy
go: finding module for package github.com/zeromicro/go-zero/core/logx
go: finding module for package github.com/zeromicro/go-zero/rest
go: finding module for package github.com/zeromicro/go-zero/rest/httpx
go: finding module for package github.com/zeromicro/go-zero/core/conf
go: found github.com/zeromicro/go-zero/core/conf in github.com/zeromicro/go-zero v1.4.3
go: found github.com/zeromicro/go-zero/rest in github.com/zeromicro/go-zero v1.4.3
go: found github.com/zeromicro/go-zero/rest/httpx in github.com/zeromicro/go-zero v1.4.3
go: found github.com/zeromicro/go-zero/core/logx in github.com/zeromicro/go-zero v1.4.3
>> Ready to start an API server...
>> Run 'curl http://127.0.0.1:8888/ping' after service startup...
Starting server at 127.0.0.1:8888...

```

--------------------------------

### File Server Configuration

Source: https://go-zero.dev/community/faq/http/fileserver

This snippet demonstrates how to configure a go-zero REST server to serve static files from a specified directory.

```APIDOC
## Configure File Server

### Description
This configuration sets up a REST server to serve static files. The `rest.WithFileServer` option maps a URL path prefix to a local directory, allowing files within that directory to be accessed via the specified URL path.

### Method
N/A (Configuration)

### Endpoint
N/A (Configuration)

### Parameters
N/A

### Request Body
N/A

### Request Example
N/A

### Response
N/A

### Code Example
```go
package main

import (
  "net/http"

  "github.com/zeromicro/go-zero/rest"
)

func main() {
  // Configure the server to serve files from the 'html' directory under the '/static' URL path.
  server := rest.MustNewServer(rest.RestConf{
    Host: "localhost",
    Port: 4000,
  }, rest.WithFileServer("/static", http.Dir("html")))
  defer server.Stop()

  // Example of another route
  server.AddRoute(rest.Route{
    Method:  http.MethodGet,
    Path:    "/hello",
    Handler: helloHandler,
  })

  server.Start()
}

func helloHandler(w http.ResponseWriter, r *http.Request) {
  w.WriteHeader(http.StatusOK)
  w.Write([]byte("Hello, World!"))
}
```

### Notes
- This approach is suitable for simple use cases. For production environments, consider using dedicated solutions like Nginx or cloud storage for file serving.
- Requires go-zero version >= v1.7.0.
```

--------------------------------

### Implementing and Registering Route-Specific Middleware

Source: https://go-zero.dev/guides/http/server/middleware

Provides the implementation logic for a generated middleware stub and demonstrates how to register it within the ServiceContext to be used by the application.

```go
func (m *CheckHeaderMiddleware) Handle(next http.HandlerFunc) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        if r.Header.Get("X-App-Version") == "" {
            httpx.Error(w, errors.New("missing X-App-Version header"))
            return
        }
        next(w, r)
    }
}

func NewServiceContext(c config.Config) *ServiceContext {
    return &ServiceContext{
        Config:      c,
        CheckHeader: middleware.NewCheckHeaderMiddleware().Handle,
    }
}
```

--------------------------------

### Example Log Line with Trace IDs

Source: https://go-zero.dev/components/observability/tracing

Log entries automatically include trace and span IDs when telemetry and logx are configured, enabling direct correlation between traces and logs.

```json
{"level":"info","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7","msg":"order created","orderId":"ord_123"}
```

--------------------------------

### Create and Use Basic In-Process Cache (Go)

Source: https://go-zero.dev/components/cache/memory-cache

Demonstrates how to create a new in-process cache with a default TTL and maximum entry limit, then set and retrieve values. The cache is thread-safe and uses LRU eviction.

```Go
import (
	"github.com/zeromicro/go-zero/core/collection"
	"time"
)

// Create a cache with 1-minute default TTL and max 10 000 entries
c := collection.NewCache(
	time.Minute,
	collection.WithLimit(10000),
)

// Set a value (uses default TTL)
c.Set("user:42", user)

// Get
val, ok := c.Get("user:42")
if ok {
	return val.(*User), nil
}
// if expired or missing, ok == false
```

--------------------------------

### Create GitLab Directory

Source: https://go-zero.dev/guides/deployment/ci-cd

Create a directory for GitLab and navigate into it before setting up the Docker Compose configuration.

```bash
mkdir gitlab && cd gitlab
```
Tokens:
Raw