diff --git a/README.md b/README.md index db4a868..c41aa22 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,73 @@ -# @go/gateway +# @go/gateway (高性能动态网关) -基于 `@go/service` 和 Redis 的高性能、事件驱动的动态 API 网关。 +基于 `@go/service` 实现的微服务 API 网关。专注于作为“配置下发搬运工”,将繁重的路由转发交由底层 `service` 核心无锁处理。 -`gateway` 专注于充当配置下发的搬运工,将路由匹配、转发等所有繁重工作剥离给底层的 `service` 核心。支持通过 Redis 进行 0 延迟、0 丢包的路由级全量/局部热更新。 +详细路由语法与基础服务配置请参考:[https://apigo.cc/go/service](https://apigo.cc/go/service) -## 功能特性 +--- -- **极致性能**:基于 `service` 包的 Copy-on-Write (写时复制) 原语,无锁构建,转发阶段无锁等待。 -- **事件驱动热更新**:摒弃轮询,监听 Redis Pub/Sub,精准下发变更配置,旧连接不受影响。 -- **服务发现原生集成**:与 `@go/discover` 无缝集成,支持基于服务名的直连与负载均衡。 -- **生命周期接管**:由 `@go/starter` 接管,支持通过 `kill -SIGHUP` 触发本地全量重新同步。 - -## 配置模型 (Redis Hash) - -Gateway 将配置存储在 Redis 的 Hash 结构中,并按照 **Host (域名)** 进行字段隔离,提升拉取效率和管理粒度。 - -- **`gateway:proxies`** 代理规则 -- **`gateway:rewrites`** 重写规则 -- **`gateway:statics`** 静态目录服务 - -### 结构示例 - -假设配置的 Host 为 `api.example.com`: - -```json -// HSET gateway:proxies "api.example.com" -[ - { "Path": "^/user/(.*)$", "AuthLevel": 0, "ToApp": "user-service", "ToPath": "/$1" }, - { "Path": "/direct", "AuthLevel": 0, "ToApp": "http://10.0.0.1:8080", "ToPath": "/hello" } -] - -// HSET gateway:rewrites "api.example.com" -[ - { "Path": "^/old-api/(.*)$", "ToPath": "/api/$1" } -] - -// HSET gateway:statics "www.example.com" -{ - "/ui": "/var/www/html" -} -``` - -## 动态热更新 API (Pub/Sub) - -无需重启进程,向 Redis 的 `gateway:channel` 频道发布 JSON 消息,网关会在收到消息后仅拉取变化的那一部分(局部全量更新): - -```json -{ - "action": "update", - "type": "proxy", // 可选: "proxy", "rewrite", "static" - "host": "api.example.com" -} -``` - -## 启动与管理 - -```bash -# 以后台进程启动 -./gateway start - -# 查看服务状态 (通过 IPC) -./gateway status - -# 平滑重启 / 重载兜底 -./gateway restart -./gateway reload # 触发底层 service 的 OnReload,全量同步 Redis -``` - -## 环境变量配置 - -支持通过环境变量或 `env.yml` 覆盖。 +## 1. 基础配置 (env.yml) ```yaml gateway: - Redis: "127.0.0.1:6379" - Prefix: "gateway" - Channel: "gateway:channel" + Redis: "127.0.0.1:6379" # 配置中心 Redis + Prefix: "gateway" # 键名前缀 (默认为 gateway) + +service: + Listen: ":80,http" # 监听端口 + Register: "127.0.0.1:6379" # 服务发现注册中心 ``` + +--- + +## 2. 动态路由管理 (Redis 示例) + +网关以 **Host (域名)** 为单元管理配置,通过向频道发送“域名字符串”触发该域名的局部热更新。 + +### A. 配置存储 (HSET) +```bash +# 1. 添加 Host 到索引集 (必须) +SADD gateway:hosts "api.example.com" + +# 2. 设置代理/重写/静态规则 (JSON 格式) +HSET gateway:host:api.example.com \ + proxies '[ + {"Path": "/user/*", "ToApp": "user-service", "ToPath": "/v1/*"}, + {"Path": "/legacy", "ToApp": "http://10.0.0.1:8080", "ToPath": "/old"} + ]' \ + rewrites '[ + {"Path": "^/api/([0-9]+)$", "ToPath": "/v2/api?id=$1"} + ]' \ + statics '{ + "/ui": "/var/www/html" + }' +``` + +### B. 发布更新 (PUBLISH) +```bash +# 运维仅需发布一条域名消息,网关秒级无损更新 +PUBLISH gateway:channel "api.example.com" +``` + +--- + +## 3. 命令行操作 (CLI) + +```bash +./gateway start # 后台启动 +./gateway status # 查看各域名健康状态与 IPC 信息 +./gateway reload # 重载本地 YAML 配置并全量刷入 Redis 配置 +./gateway stop # 优雅停止 +``` + +## 4. 路由匹配速查 + +| 匹配模式 | 示例路径 (Path) | 说明 | +| :--- | :--- | :--- | +| **精确匹配** | `/login` | 必须完全一致 | +| **高性能前缀** | `/api/*` | **必须带 `/*` 结尾**,自动剥离前缀转发 | +| **正则匹配** | `^/user/(.*)$` | 包含 `(` 即视为正则,支持 `$1` 替换 | + +--- + +*更多高级特性如 SSL、负载均衡超时、自动探测应用名等,请查阅 [service 文档](https://apigo.cc/go/service)。* diff --git a/app_test.go b/app_test.go index 8d6bce2..d79e3cf 100644 --- a/app_test.go +++ b/app_test.go @@ -35,6 +35,9 @@ func TestGateway(t *testing.T) { service.Host("*").GET("/hello", func(req *service.Request) string { return "hello from backend, path: " + req.RequestURI }) + service.Host("*").GET("/hello/world", func(req *service.Request) string { + return "hello from backend, path: " + req.RequestURI + }) asBackend := service.AsyncStart() defer asBackend.Stop() @@ -48,6 +51,7 @@ func TestGateway(t *testing.T) { proxyRules := []service.ProxyRule{ {Path: "^/api/(.*)$", ToApp: "test-backend", ToPath: "/$1"}, {Path: "/direct", ToApp: "test-backend", ToPath: "/hello"}, + {Path: "/v2/*", ToApp: "test-backend", ToPath: "/hello/*"}, } rewriteRules := []service.RewriteRule{ {Path: "^/old-api/(.*)$", ToPath: "/api/$1"}, @@ -130,6 +134,22 @@ func TestGateway(t *testing.T) { t.Fatalf("Proxy regexp failed, got: %s", body) } + // ============================================ + // 测试 2.1: 极速通配符前缀匹配 (Discover) + // ============================================ + req, _ = gohttp.NewRequest("GET", "http://127.0.0.1:"+gwPort+"/v2/world?x=2", nil) + req.Host = "gw.test" + res, err = client.Do(req) + body = "" + if err == nil && res != nil { + b, _ := io.ReadAll(res.Body) + res.Body.Close() + body = string(b) + } + if err != nil || !strings.Contains(body, "hello from backend, path: /hello/world?x=2") { + t.Fatalf("Proxy wildcard failed, got: %s", body) + } + // ============================================ // 测试 3: Rewrite 后再 Proxy // ============================================ diff --git a/main.go b/main.go index 5a5e35c..39af498 100644 --- a/main.go +++ b/main.go @@ -12,7 +12,23 @@ func main() { _ = config.Load(&GatewayConf, "gateway") // 2. 初始化 Starter 信息 - starter.SetAppInfo("gateway", "2.0.0") + starter.SetAppInfo("gateway", "1.0.0") + starter.SetUsage(`High-performance API gateway based on apigo.cc/go/service. +Full Guide: https://apigo.cc/go/service + +Example Config (env.yml): + gateway: + Redis: "127.0.0.1:6379" # Configuration Center + service: + Listen: ":80,http" # HTTP Port + +Dynamic Route Update (via redis-cli): + PUBLISH gateway:channel "api.example.com" + +Matching Logic: + - Exact: "/login" (Literal string) + - Prefix: "/api/*" (Matches start, requires suffix "/*") + - Regex: "^/v1/(.*)$" (Matches pattern if "(" is present)`) // 3. 注册 Gateway 服务 // GatewayApp 自身实现了 starter.Service 和 starter.Reloader 接口