Go microservice project based multiple technology stacks | Recommended open source projects
Tags: webdev, beginners, programming, go
Published: 2023-01-23 13:57:43

## FreeCar

FreeCar is a full-stack microservice project based on Hertz and Kitex, welcome Star.

Project address: [CyanAsterisk/FreeCar](https://github.com/CyanAsterisk/FreeCar)

## Hertz

[Hertz](https://github.com/cloudwego/hertz) is an ultra-large-scale enterprise-level microservice HTTP framework, featuring high ease of use, easy expansion, and low latency etc.

Hertz uses the self-developed high-performance network library Netpoll by default. In some special scenarios, Hertz has certain advantages in QPS and latency compared to go net.

In internal practice, some typical services, such as services with a high proportion of frameworks, gateways and other services, after migrating Hertz, compared to the Gin framework, the resource usage is significantly reduced, **CPU** **usage is reduced by 30%-60% with the size of the traffic**.

> For more details, see [cloudwego/hertz](https://github.com/cloudwego/hertz).

## technology stack

| Function | Implementation |
| ------------ | --------------------- |
| HTTP Framework | Hertz |
| RPC Framework | Kitex |
| Database | MongoDB, MySQL |
| Configuration Center | Nacos |
| Service Discovery Center | Nacos |
| Message Queue | RabbitMQ |
| Link Tracking | Jaeger |
| Cluster Monitoring | Prometheus |
| Current limiting middleware | hertz-contrib/limiter |
| Deployment | docker-compose |
| Object Storage | Tencent Cloud COS |
| CI | GitHub Actions |

## Project Architecture

### Call relationship

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/oi9fbwoh14v9ornslzn2.png)

### Technology Architecture

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3mttc297pomo6twfl4jm.png)


### Service Relationship

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/usksk67tc354o2c98wqw.png)


## Display


![image.png](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/679c51fedbf642ff8fc8c2a6fa6153e9~tplv-k3u1fbpfcp-watermark.image?)

## Directory Introduction

| Catalog | Introduction |
| ------ | ------------ |
| Server | Core part of the project |
| Shared | Reusable Code |
| Static | WeChat applet code  |

## Service Introduce

| Catalog | Introduce                                          |
|---------|----------------------------------------------------|
| API     | Hertz-based Gateway Service                        |
| Auth    | User Authentication Service                        |
| Blob    | Services Related to Pictures and Tencent Cloud COS |
| Car     | Car Service                                        |
| Profile | Profile and Picture Recognition Services           |
| Trip    | Trip Service                                       |

## Quick Start

### Start dependence

```shell
make start
```

### Configure Nacos

> Access `http://127.0.0.1:8848/nacos/index.html#/login` on the browser to log in.
>
> For the default namespace and configuration groups, please refer to each `config.yaml` configuration file.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bu9fvpgq4mnqrseqlbo4.png)

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/j7bzhkx32fbtdydy2nsu.png)

For detailed configuration of the configuration center, [see](https://github.com/CyanAsterisk/FreeCar/blob/dev/static/docs/NACOS_CONFIG.md).

### Generate data table

```shell
make migrate
```

### Start HTTP service

```shell
make api
```

### Start the microservice

```shell
make auth
make blobs
make a car
make profile
make a trip
```

### Jaeger

> Visit `http://127.0.0.1:16686/` on your browser

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ml47lg8e5kymxjg6oheu.png)

### Prometheus

> Visit `http://127.0.0.1:3000/` on your browser

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8l7khq2wjxvk85yajzn4.png)


## API requests

The project's API request example [see details](https://github.com/CyanAsterisk/FreeCar/blob/dev/static/docs/API_REQUEST.md).

## Development Guide

It is very difficult to understand this project by directly reading the source code. Here is a development guide for developers to quickly understand and get started with this project, including frameworks such as Kitex and Hertz.

### Preparation

Use the commands in the quick start to quickly start the required tools and environment. If you need special customization, please modify the contents of `docker-compose.yaml` and Nacos configuration.

###IDL

Before development, we need to define the IDL file, where hz
Provides developers with many customized [api annotations](https://www.cloudwego.io/zh/docs/hertz/tutorials/toolkit/toolkit/#%E6%94%AF%E6%8C%81% E7%9A%84-api-%E6%B3%A8%E8%A7%A3).

Sample code:

```thrift
namespace go auth

struct LoginRequest {
     1: string code
}

struct LoginResponse {
     1: i64 accountID
}

service AuthService {
     LoginResponse Login(1: LoginRequest req)
}
```

### Code Generation

#### Kitex

Execute under the new service directory, only need to change the service name and IDL path each time.

##### Server

```shell
kitex -service auth -module github.com/CyanAsterisk/FreeCar ./../../idl/auth.thrift
```

##### client

```shell
kitex -module github.com/CyanAsterisk/FreeCar ./../../idl/auth.thrift
```

Note:

- Use `-module github.com/CyanAsterisk/FreeCar` This parameter is used to specify the Go module to which the generated code belongs to avoid path problems.
- When the current service needs to call other services, a client file needs to be generated.

#### Hertz

##### Initialization

```shell
hz new -idl ./../../idl/api.proto -mod github.com/CyanAsterisk/FreeCar/server/cmd/api
```

##### renew

```shell
hz update -I -idl ./../../idl/api.proto
```

Note:

- Use `-module github.com/CyanAsterisk/FreeCar/server/cmd/api` This parameter is used to specify the Go module to which the generated code belongs to avoid path problems.

### Business Development

After the code is generated, some necessary components need to be added to the project. Since the api layer does not need to be added again, the following mainly explains about Kitex-Server
section, the code is located under `server/cmd`.

#### Config

Refer to `server/cmd/auth/config` for the configuration structure of microservices.

#### Global

Refer to `server/cmd/auth/global` to provide globally callable methods for microservices.

#### Initialize

Refer to `server/cmd/auth/initialize` to provide the initialization function of the necessary components, among which `nacos.go` `flag.go` `logger.go` are required.

#### Tool

Refer to `server/cmd/auth/tool` to provide tool functions for microservices, where `port.go` is required.

#### API

When writing the business logic of the gateway layer, you only need to update the IDL and the new microservice client code each time. If you need to add new components, you can add them directly. The project is highly pluggable, and the architecture is similar to the microservice layer.

The business logic of the gateway layer is under `server/cmd/api/biz`, and most of the code will be automatically generated. If you need to add a new route separately, you need to go to `server/cmd/api/router.go`.

Regarding the use of middleware, you only need to add middleware logic in `server/cmd/api/biz/router/api/middleware.go`.

## License

FreeCar is open source under the GNU General Public License version 3.0.

## Summarize

This project still takes a lot of time, everyone is welcome to learn, if Star is our greatest encouragement!

## Reference

- [CyanAsterisk/FreeCar](https://github.com/CyanAsterisk/FreeCar)
- [cloudwego/hertz](https://github.com/cloudwego/hertz)
- [cloudwego/kitex](https://github.com/cloudwego/kitex)