Skip to content

Commit

Permalink
readme fix
Browse files Browse the repository at this point in the history
  • Loading branch information
axiaoxin committed Jun 7, 2021
1 parent 52b2330 commit 9e04acf
Showing 1 changed file with 76 additions and 8 deletions.
84 changes: 76 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,74 @@
# 开发环境搭建
# pink-lady

## 安装 swagger api 文档生成工具 [swag](https://github.com/swaggo/swag)
![proj-icon](./misc/pics/logo.png)

[![Build Status](https://travis-ci.org/axiaoxin-com/pink-lady.svg?branch=master)](https://travis-ci.org/axiaoxin-com/pink-lady)
[![go report card](https://goreportcard.com/badge/github.com/axiaoxin-com/pink-lady)](https://goreportcard.com/report/github.com/axiaoxin-com/pink-lady)
[![version-badge](https://img.shields.io/github/release/axiaoxin-com/pink-lady.svg)](https://github.com/axiaoxin-com/pink-lady/releases)
[![license](https://img.shields.io/github/license/axiaoxin-com/pink-lady.svg)](https://github.com/axiaoxin-com/pink-lady/blob/master/LICENSE)
[![issues](https://img.shields.io/github/issues/axiaoxin-com/pink-lady.svg)](https://github.com/axiaoxin-com/pink-lady/issues)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/axiaoxin-com/pink-lady/pulls)

> Pinklady is a template project of gin app, which encapsulates mysql, redis, logging, viper, swagger, middlewares and other common components.
pink-lady 是基于 Golang web 开发框架 [gin](https://github.com/gin-gonic/gin)
来进行 HTTP API 开发的示例项目,新建项目时可以使用它作为项目模板。

之所以叫 pink-lady 首先字面意思就是红粉佳人或则粉红女郎,有这个性感的名字相信你更会好好对你的代码负责。
其次,因为 gin 就是国外六大类烈酒之一的金酒,是近百年来调制鸡尾酒时最常使用的基酒,其配方多达千种以上,
而 pink lady 是以 gin 作 base 的国标鸡尾酒之一,在这里 pink-lady 则是以 gin 作 base 的代码骨架模板之一

## 使用 pink-lady 模板创建项目

点击 <https://github.com/axiaoxin-com/pink-lady/generate> 创建你的 github 项目

或者手动本地创建:

```
bash <(curl -s https://raw.githubusercontent.com/axiaoxin-com/pink-lady/master/misc/scripts/new_project.sh)
```

## 特性

- 使用 viper 加载配置,支持配置热更新,服务所有特性都通过配置文件控制
- 支持生成 swagger api 文档
- 封装数据库连接实例池,通过读取配置文件可以直接在代码中使用 gorm 和 sqlx 快速连接 mysql、sqlite3、postgresql、sqlserver
- 封装 redis, redis sentinel, redis cluster 连接实例池
- 封装统一的 JSON 返回结构
- 集成 sentry 搜集错误
- 内置 GinLogger 中间件打印详细的访问日志,支持不同的 http 状态码使用不同的日志级别,通过配置开关打印请求头,请求餐宿,响应体等调试信息
- 内置 GinRecovery 中间件,异常服务默认按状态码返回 JSON 错误信息,panic 错误统一交由 GinLogger 打印,支持自定义输出格式
- 使用 logging 打印日志,支持 trace id,error 以上级别自动上报到 sentry
- 支持 prometheus metrics exporter
- 支持 ratelimiter 请求限频
- 通过配置集成 go html template,可自由注册 template funcs map
- embed 静态资源编译进二进制文件中

## 使用 `pink-lady/webserver` 3 步组装一个 WEB 应用

1. 确认配置文件正确。
配置文件必须满足能解析出指定的内容,复制或修改 [config.default.toml](./src/config.default.toml) 中的配置项
2. 创建自定义中间件的 gin app `NewGinEngine` (可选)
3. 运行 web 应用服务器 `Run`
需传入 gin app 和在该 app 上注册 URL 路由注册函数

实现代码在`src`路径下,在 pink-lady 模板项目下,你只需关注如何实现你的业务逻辑,不用考虑如何组织项目结构和集成一些通用功能,比如数据库的连接封装,配置文件的读取,swagger 文档生成,统一的 JSON 返回结果,错误码定义,集成 Sentry 等等。

你可以在`routes`路径下实现你的 api,并在 `routes/routes.go``Routes` 函数中注册 URL 即可。外部第三方服务放在 `services` 包中进行加载或初始化。数据库模型相关定义放到 `models` 包中便于复用。

## 关于 gin

### gin 框架源码图解

![gin arch](./misc/pics/gin_arch.svg)

### gin 中间件原理解析

<https://github.com/axiaoxin/axiaoxin/issues/17>

## 开发环境搭建

### 安装 swagger api 文档生成工具 [swag](https://github.com/swaggo/swag)

```
go get -u github.com/swaggo/swag/cmd/swag
Expand All @@ -19,7 +87,7 @@ api 文档地址: <http://localhost:4869/x/apidocs/index.html>

swag 中文文档: <https://github.com/swaggo/swag/blob/master/README_zh-CN.md>

## 使用 [air](https://github.com/cosmtrek/air) 可以根据文件变化自动编译运行服务
### 使用 [air](https://github.com/cosmtrek/air) 可以根据文件变化自动编译运行服务

安装:

Expand All @@ -29,15 +97,15 @@ go get -u github.com/cosmtrek/air

在项目根目录中执行 `air -c .air.toml` 即可运行服务,代码修改后会自动更新 api 文档并重新编译运行

## 根据 mysql 表自动生成结构体:[table2struct](https://github.com/axiaoxin-com/table2struct)
### 根据 mysql 表自动生成结构体:[table2struct](https://github.com/axiaoxin-com/table2struct)

安装:

```
go get -u github.com/axiaoxin-com/table2struct
```

## 依赖的外部 HTTP 服务的 Mock 工具: [httplive](https://github.com/gencebay/httplive)
### 依赖的外部 HTTP 服务的 Mock 工具: [httplive](https://github.com/gencebay/httplive)

安装:

Expand All @@ -53,7 +121,7 @@ httplive -d `pwd`/httplive.db -p 5003

打开浏览器访问: `http://localhost:5003` 页面上编辑 url 和对应的返回结果保存,请求对应地址就会返回你设置的返回结果

# 配置文件
## 配置文件

服务通过 [viper](https://github.com/spf13/viper) 加载配置文件, viper 支持的配置文件格式都可以使用。

Expand All @@ -69,13 +137,13 @@ httplive -d `pwd`/httplive.db -p 5003

**建议**:在开发自己的服务时,复制当前目录的 toml 配置创建一份新的配置,再在其上进行修改或新增配置,然后通过指定参数加载自己的配置。

# 日志打印
## 日志打印

使用 [logging](https://github.com/axiaoxin-com/logging) 的方法打印带 trace id 的日志,可通过配置文件中 `[logging]` 下的配置项进行相关设置。

配置 sentry dsn 后,`Error` 级别以上的日志会被自动采集到 Sentry 便于错误发现与定位。

# API 开发
## API 开发

使用 [pink-lady](http://github.com/axiaoxin-com/pink-lady) 开发 web api 服务,你只需实现 gin 的 `HandlerFunc` 并在 `routes/routes.go``Routes` 函数中注册到对应的 URL 上即可。

Expand Down

0 comments on commit 9e04acf

Please sign in to comment.