aqi/docs/zh-CN.md

Aqi

Aqi是一个Golang Websocket业务框架，支持net/http, gin, chi等，底层整合了viper, gorm, gobwa/ws, gjson, zap, asynq等优秀第三方库，方便快速展开Websocket业务

安装

go get -u github.com/wonli/aqi

使用

第一次运行时会在工作目录下自动生成config-dev.yaml配置文件，你可以配置程序启动端口、数据库等信息。

服务启动后使用 wscat 与服务器建立websocket链接，运行截图如下。

交互协议

输入输出统一使用JSON，其中 Action为路由中注册的名字， Params为JSON格式字符串

type Context struct {
	...
	Action   string
	Params   string
	...
}

响应内容格式:

type Action struct {
	Action string `json:"action"`

	Code int    `json:"code"`
	Msg  string `json:"msg,omitempty"`
	Data any    `json:"data,omitempty"`
}

快速开始

在ahi.Init中通过aqi.ConfigFile指定配置文件，默认使用yaml格式，通过aqi.HttpServer指定服务名称和端口在yaml文件中的路径, 入口文件内容如下：

package main

import (
	"net/http"
	"time"

	"github.com/wonli/aqi"
	"github.com/wonli/aqi/ws"
)

func main() {
	app := aqi.Init(
		aqi.ConfigFile("config.yaml"),
		aqi.HttpServer("Aqi", "port"),
	)

	// 创建路由
	mux := http.NewServeMux()
	// WebSocket Handler
	mux.HandleFunc("/ws", func(w http.ResponseWriter, r *http.Request) {
		ws.HttpHandler(w, r)
	})

	// 注册路由
	wsr := ws.NewRouter()
	wsr.Add("hi", func(a *ws.Context) {
		a.Send(ws.H{
			"hi": time.Now(),
		})
	})

	app.WithHttpServer(mux)

	// 启动应用
	app.Start()
}

与Gin整合

aqi能非常方便的与其他WEB框架整合，只需要正确注册handler和app.WithHttpServer，只要实现了 http.Handler都支持。

package main

import (
	"net/http"
	"time"

	"github.com/gin-gonic/gin"

	"github.com/wonli/aqi"
	"github.com/wonli/aqi/ws"
)

func main() {
	app := aqi.Init(
		aqi.ConfigFile("config.yaml"),
		aqi.HttpServer("Aqi", "port"),
	)

	engine := gin.Default()
	// 注册handler
	engine.GET("/ws", func(c *gin.Context) {
		ws.HttpHandler(c.Writer, c.Request)
	})

	// 注册路由
	wsr := ws.NewRouter()
	wsr.Add("hi", func(a *ws.Context) {
		a.Send(ws.H{
			"hi": time.Now(),
		})
	})

	app.WithHttpServer(engine)
	app.Start()
}

中间件

先定义一个简单的日志中间件，在处理请求前先打印当前接收到的action，在处理完成后打印响应内容。

func logMiddleware() func(a *ws.Context) {
	return func(a *ws.Context) {
		log.Printf("Request action: %s ", a.Action)
		a.Next()
		log.Printf("Reqponse data: %s ", a.Response.Data)
	}
}

使用Use方法将中间件注册到路由中

// 注册WebSocket路由
wsr := ws.NewRouter()
wsr.Use(logMiddleware()).Add("hi", func(a *ws.Context) {
    a.Send(ws.H{
        "hi": time.Now(),
    })
})

当然也可以用路由组的形式

// 注册WebSocket路由
wsr := ws.NewRouter()
r1 := wsr.Use(logMiddleware())
{
    r1.Add("hi", func(a *ws.Context) {
        a.Send(ws.H{
            "hi": time.Now(),
        })
    })

    r1.Add("say", func(a *ws.Context) {
        a.Send(ws.H{
            "say": "hi",
        })
    })
}

这样控制台在每个请求前后都会打印日志

生产模式

直接编译Aqi会以dev模式运行，以生产模式运行请在编译时传入以下参数，详细内容请查看examples/Makefile文件

LDFLAGS = "-X '$(FLAGS_PKG).BuildDate=$(BUILD_DATE)' \
		   -X '$(FLAGS_PKG).Branch=$(GIT_BRANCH)' \
		   -X '$(FLAGS_PKG).CommitVersion=$(GIT_COMMIT)' \
		   -X '$(FLAGS_PKG).Revision=$(GIT_REVISION)' \
		   -extldflags '-static -s -w'"