{"id":15095911,"url":"https://github.com/wonli/aqi","last_synced_at":"2026-02-03T08:03:39.488Z","repository":{"id":244927555,"uuid":"816735212","full_name":"wonli/aqi","owner":"wonli","description":"A Golang Websocket business framework","archived":false,"fork":false,"pushed_at":"2025-10-17T02:13:00.000Z","size":503,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-18T05:42:47.168Z","etag":null,"topics":["gin","golang","websocket"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wonli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-06-18T09:56:47.000Z","updated_at":"2025-10-17T02:12:06.000Z","dependencies_parsed_at":"2024-06-21T22:02:08.988Z","dependency_job_id":"5753cb91-5ee2-444f-b884-f7336e8c122a","html_url":"https://github.com/wonli/aqi","commit_stats":null,"previous_names":["wonli/aqi"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/wonli/aqi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wonli%2Faqi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wonli%2Faqi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wonli%2Faqi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wonli%2Faqi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wonli","download_url":"https://codeload.github.com/wonli/aqi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wonli%2Faqi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29037749,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T06:39:36.383Z","status":"ssl_error","status_checked_at":"2026-02-03T06:39:32.787Z","response_time":96,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gin","golang","websocket"],"created_at":"2024-09-25T15:43:39.704Z","updated_at":"2026-02-03T08:03:39.482Z","avatar_url":"https://github.com/wonli.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aqi\n\nAqi is a Golang Websocket business framework that supports net/http, gin, chi, etc. It integrates underlying third-party libraries such as viper, gorm, gobwa/ws, gjson, zap, asynq, which facilitates the rapid development of Websocket applications.\n\n### Quick Start\n\nInstall the `aqi` CLI and create a project in three steps:\n\n```bash\n# 1. Install aqi\ngo install github.com/wonli/aqi/cmd/aqi@latest\n\n# 2. Generate project\naqi new myapp \u0026\u0026 cd myapp\n\n# 3. Run\ngo run . api\n```\n\nOn first run, `config-dev.yaml` is auto-generated. The API and WebSocket server start on port `2015` (configurable in the config file). Use [wscat](https://github.com/websockets/wscat) to connect to `ws://localhost:2015/ws` and test the built-in `hi` action.\n\n[简体中文](./docs/zh-CN.md)\n\n### Usage\n\nOn the first run, a `config-dev.yaml` configuration file will be automatically generated in the working directory. You can configure the application start port, database, and other settings.\n\nAfter the service starts, use [wscat](https://github.com/websockets/wscat) to establish a websocket connection with the server. Here is a screenshot of the operation.\n\n\n\n![img](./docs/assets/img.png)\n\n\n\n### Interaction Protocol\n\nInput and output uniformly use `JSON`. Here, `Action` is the name registered in the routing, and `Params` are in JSON string format.\n\n```go\n\ntype Context struct {\n\t...\n\tAction   string\n\tParams   string\n\t...\n}\n```\n\n\n\nResponse Format:\n\n```go\ntype Action struct {\n\tAction string `json:\"action\"`\n\n\tCode int    `json:\"code\"`\n\tMsg  string `json:\"msg,omitempty\"`\n\tData any    `json:\"data,omitempty\"`\n}\n```\n\n\n\n### Quick Start\n\nIn `ahi.Init`, specify the configuration file via `aqi.ConfigFile`, which defaults to `yaml` format. The service name and port are specified in the `yaml` file path through `aqi.HttpServer`. The contents of the entry file are as follows:\n\n```go\npackage main\n\nimport (\n\t\"net/http\"\n\t\"time\"\n\n\t\"github.com/wonli/aqi\"\n\t\"github.com/wonli/aqi/ws\"\n)\n\nfunc main() {\n\tapp := aqi.Init(\n\t\taqi.ConfigFile(\"config.yaml\"),\n\t\taqi.HttpServer(\"Aqi\", \"port\"),\n\t)\n\n\t// Create router\n\tmux := http.NewServeMux()\n\t// WebSocket Handler\n\tmux.HandleFunc(\"/ws\", func(w http.ResponseWriter, r *http.Request) {\n\t\tws.HttpHandler(w, r)\n\t})\n\n\t// Register router\n\twsr := ws.NewRouter()\n\twsr.Add(\"hi\", func(a *ws.Context) {\n\t\ta.Send(ws.H{\n\t\t\t\"hi\": time.Now(),\n\t\t})\n\t})\n\n\tapp.WithHttpServer(mux)\n\n\t// 启动应用\n\tapp.Start()\n}\n```\n\n\n\n### With Gin\n\n`aqi` can be very conveniently integrated with other WEB frameworks. You just need to correctly register `handler` and `app.WithHttpServer`. It supports any implementation of `http.Handler`.\n\n\n\n```go\npackage main\n\nimport (\n\t\"net/http\"\n\t\"time\"\n\n\t\"github.com/gin-gonic/gin\"\n\n\t\"github.com/wonli/aqi\"\n\t\"github.com/wonli/aqi/ws\"\n)\n\nfunc main() {\n\tapp := aqi.Init(\n\t\taqi.ConfigFile(\"config.yaml\"),\n\t\taqi.HttpServer(\"Aqi\", \"port\"),\n\t)\n\n\tengine := gin.Default()\n\t// Handler\n\tengine.GET(\"/ws\", func(c *gin.Context) {\n\t\tws.HttpHandler(c.Writer, c.Request)\n\t})\n\n\t// Router\n\twsr := ws.NewRouter()\n\twsr.Add(\"hi\", func(a *ws.Context) {\n\t\ta.Send(ws.H{\n\t\t\t\"hi\": time.Now(),\n\t\t})\n\t})\n\n\tapp.WithHttpServer(engine)\n\tapp.Start()\n}\n```\n\n\n\n### Middlewares\n\nFirst, define a simple logging middleware that prints the received `action` before processing the request and prints the response content after processing.\n\n```go\nfunc logMiddleware() func(a *ws.Context) {\n\treturn func(a *ws.Context) {\n\t\tlog.Printf(\"Request action: %s \", a.Action)\n\t\ta.Next()\n\t\tlog.Printf(\"Reqponse data: %s \", a.Response.Data)\n\t}\n}\n```\n\nRegister the middleware to the router using the `Use` method.\n\n```go\n// 注册WebSocket路由\nwsr := ws.NewRouter()\nwsr.Use(logMiddleware()).Add(\"hi\", func(a *ws.Context) {\n    a.Send(ws.H{\n        \"hi\": time.Now(),\n    })\n})\n```\n\nYou can also use the form of router groups.\n\n```go\n// Router\nwsr := ws.NewRouter()\nr1 := wsr.Use(logMiddleware())\n{\n    r1.Add(\"hi\", func(a *ws.Context) {\n        a.Send(ws.H{\n            \"hi\": time.Now(),\n        })\n    })\n\n    r1.Add(\"say\", func(a *ws.Context) {\n        a.Send(ws.H{\n            \"say\": \"hi\",\n        })\n    })\n}\n```\n\nThis way, the console will print logs before and after each request.\n\n\n\n### Production Mode\n\nCompiling `Aqi` directly will run in `dev` mode. To run in production mode, pass the following parameters during compilation. For more details, please refer to the `examples/Makefile` file.\n\n\n\n```shell\nLDFLAGS = \"-X '$(FLAGS_PKG).BuildDate=$(BUILD_DATE)' \\\n\t\t   -X '$(FLAGS_PKG).Branch=$(GIT_BRANCH)' \\\n\t\t   -X '$(FLAGS_PKG).CommitVersion=$(GIT_COMMIT)' \\\n\t\t   -X '$(FLAGS_PKG).Revision=$(GIT_REVISION)' \\\n\t\t   -extldflags '-static -s -w'\"\n```\n\n### API Documentation\n\nGenerate API docs from your router files with `aqi docgen init`:\n\n```bash\n# In project root (e.g. myapp/)\naqi docgen init\n```\n\nThis creates a `docs/` directory with:\n- `doc-config.yaml` – doc config and categories\n- `api_viewer.html` – web viewer for API docs\n- `docgen.go` – embeddable doc server\n- `cmd_api_*.json` – parsed action docs from `internal/router`\n\nOptions: `-r` router dir (default `./internal/router`), `-f` format (`json` or `markdown`), `-p` package name.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwonli%2Faqi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwonli%2Faqi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwonli%2Faqi/lists"}