go-gin-gee

Gee is a project that provides several services for everyday work. The project is based on Gin [1], and follows the ProjectLayout [3] structure. In addition, some daily scripts in the folder scripts depend on Script [4], which can be used by the command run directly.

Table of Contents

• Download
• Script Examples
• API Examples
  • Generate Short Link
  • Save Data
  • Get Data
• Build
• Deploy
  • Supervisor
  • Docker
    • Build Image
    • Run
• Document
• Contributing
• References

Download

git clone https://github.com/mazeyqian/go-gin-gee.git

Script Examples

1. Change Git name and email for different projects.

go run scripts/change-git-user/main.go -path="/Users/X/Web" -username="Your Name" -useremail="your@email.com"

Usage: English | 简体中文

2. git pull all projects in a folder.

go run scripts/batch-git-pull/main.go -path="/Users/X/Web"

Usage: English | 简体中文

3. Consolidate designated files/folders and execute customized ESLint commands.

go run scripts/eslint-files/main.go -files="file1.js,file2.js" -esConf="custom.eslintrc.js" -esCom="--fix"

Usage: English | 简体中文

4. Convert TypeDoc comments to Markdown.

go run scripts/convert-typedoc-to-markdown/main.go

Usage: English | 简体中文

5. Convert Markdown to TypeDoc comments.

go run scripts/convert-markdown-to-typedoc/main.go

Usage: English | 简体中文

6. Transfer Apple note table to Markdown table.

go run scripts/transfer-notes-to-md-table/main.go

More in folder scripts.

API Examples

The base URL for this API is an environment variate ${BASE_URL}, such as https://example.com/path.

Generate Short Link

Description:

Generate the short link for the original link.

Path: /api/gee/generate-short-link

Method: POST

Params:

Params	Type	Description	Required
ori_link	string	Original Link	Yes

Example:

curl --location --request POST '${BASE_URL}/api/gee/generate-short-link' \
--header 'Content-Type: application/json' \
--data-raw '{
  "ori_link": "https://blog.mazey.net/tiny?ts=654321-221467-f22c24-493220-228e97-d90c73"
}'

Returns:

Params	Type	Description	Required
tiny_link	string	Short Link	Yes

Example:

Success: Status Code 201

{
  "tiny_link": "${BASE_URL}/t/b"
}

Failure: Status Code 400

{
  "code": 400
}

Save Data

Description:

Save the data for searching.

Path: /api/gee/create-alias2data

Method: POST

Params:

Params	Type	Description	Required
alias	string	Alias	Yes
data	string	Data	Yes
public	bool	Public	Yes

Example:

curl --location --request POST '${BASE_URL}/api/gee/create-alias2data' \
--header 'Content-Type: application/json' \
--data-raw '{
  "alias": "alias example",
  "data": "data example",
  "public": true
}'

Returns:

Params	Type	Description	Required
id	int	ID	Yes
alias	string	Alias	Yes
data	string	Data	Yes

Example:

Success: Status Code 201

{
  "id": 2,
  "created_at": "2023-01-07T11:14:24.572495702+08:00",
  "updated_at": "2023-01-07T11:14:24.57882362+08:00",
  "alias": "alias example",
  "data": "data example"
}

Failure: Status Code 400

{
  "code": 400,
  "message": "data exist"
}

Get Data

Description:

Get the data.

Path: /api/gee/get-data-by-alias

Method: GET

Params:

Params	Type	Description	Required
alias	string	Alias	Yes

Example:

curl --location '${BASE_URL}/api/gee/get-data-by-alias?alias=alias%20example'

Returns:

Params	Type	Description	Required
id	int	ID	Yes
alias	string	Alias	Yes
data	string	Data	Yes

Example:

Success: Status Code 200

{
  "data": {
    "id": 5,
    "created_at": "2023-05-16T13:46:10.518769+08:00",
    "updated_at": "2023-05-16T13:46:10.520977+08:00",
    "alias": "alias example",
    "data": "data example",
    "public": true
  }
}

Failure: Status Code 404

{
  "code": 404,
  "message": "data not found"
}

Build

Default:

go build cmd/api/main.go

Linux:

It's usually helpful to run the command chmod u+x script-name-linux-amd64 if the permission error happens.

GOOS=linux GOARCH=amd64 go build -o dist/api-linux-amd64 cmd/api/main.go

macOS:

GOOS=darwin GOARCH=amd64 go build -o dist/api-mac-darwin-amd64 cmd/api/main.go

Windows:

GOOS=windows GOARCH=amd64 go build -o dist/api-windows-amd64 cmd/api/main.go

Deploy

Environment Variates:

• ${WECOM_ROBOT_CHECK}: WeCom Robot Key.
• ${BASE_URL}: The Base URL for this Service.

Supervisor

[program:api]
directory=/web/go-gin-gee
command=/web/go-gin-gee/dist/api-linux-amd64 --config-path="/web/go-gin-gee/data/config.json"
autostart=true
autorestart=true
environment=WECOM_ROBOT_CHECK="b2lsjd46-7146-4nv2-8767-86cb0cncjdbe",BASE_URL="https://example.com/path"

Docker

Build Image

Run bash ./scripts/docker-build.sh -h to see the help message.

Usage: docker-build.sh [OPTIONS] [ENV_VARS...]
Build and run a Docker container for the go-gin-gee API.

Options:
  -r, --run     Run the Docker container after building (default)
  -b, --build   Build the Docker image but do not run it
  -h, --help    Print this help message and exit

Environment variables:
  Any additional arguments passed to the script will be passed as environment variables to the Docker container.

Usage:

${RUN_FLAG} is optional, default is -r("RUN"). ${WECOM_ROBOT_CHECK} is optional. If you don't want to send the message to WeCom Robot, just remove it. ${BASE_URL} is required. It's the Base URL for this Service.

bash ./scripts/docker-build.sh ${RUN_FLAG} \
  "WECOM_ROBOT_CHECK=${WECOM_ROBOT_CHECK}" \
  "BASE_URL=${BASE_URL}"

Examples:

Example 1: Build and Push

bash ./scripts/docker-build.sh -b

Example 2: Build and Run

bash ./scripts/docker-build.sh -r \
  "WECOM_ROBOT_CHECK=b2lsjd46-7146-4nv2-8767-86cb0cncjdbe" \
  "BASE_URL=https://example.com/path"

Run

Run bash ./scripts/docker-run.sh -h to see the help message.

Usage: docker-run.sh [OPTIONS] IMAGE_TAG [ENV_VARS...]
Run a Docker container from the specified IMAGE_TAG with the specified environment variables.

Options:
  -h, --help    Print this help message and exit

Environment variables:
  Any additional arguments passed to the script will be passed as environment variables to the Docker container.

Note:
  The first argument (IMAGE_TAG) must be the tag name of the Docker image to run.

Find the latest image tag name: Tags

Usage:

bash ./scripts/docker-run.sh "${DOCKER_HUB_REPOSITORY_TAGNAME}" \
  "WECOM_ROBOT_CHECK=${WECOM_ROBOT_CHECK}" \
  "BASE_URL=${BASE_URL}"

Example:

bash ./scripts/docker-run.sh "docker.io/mazeyqian/go-gin-gee:v20230615221222-api" \
  "WECOM_ROBOT_CHECK=b2lsjd46-7146-4nv2-8767-86cb0cncjdbe" \
  "BASE_URL=https://example.com/path"

Document

Download swag:

go install github.com/swaggo/swag/cmd/swag@v1.8.12

Generate:

swag init --dir cmd/api --parseDependency --output docs

Make sure your GO Path is on the PATH environment variable export PATH=$(go env GOPATH)/bin:$PATH if the following error occurs command not found: swag.

Run and visit: http://localhost:3000/docs/index.html

Contributing

Download modules:

go mod download

If i/o timeout, run the command to replace the proxy:

go env -w GOPROXY=https://goproxy.cn

It's necessary to run the command go run scripts/init/main.go when serving the project first.

Serve:

go run cmd/api/main.go --config-path="data/config.dev.json"

Restart:

go run scripts/restart/main.go

Visit: http://127.0.0.1:3000/api/ping.

pong/v1.0.0/2022-09-29 04:52:43

References

1. Gin Web Framework
2. lo - Iterate over slices, maps, channels...
3. Standard Go Project Layout
4. script
5. go-rest-template