配置 API

Config 结构体定义了 API Gateway 的主配置。

类型定义

type Config struct {
    Port     int64          `config:"port"`
    BaseURI  string         `config:"baseuri"`
    Backend  route.Backend  `config:"backend"`
    Routes   []route.Route  `config:"routes"`
    Cache    Cache          `config:"cache"`
    HealthCheck HealthCheck `config:"healthcheck"`
    RateLimit RateLimit     `config:"rate_limit"`
}

字段

Port

Port int64

网关监听的端口。默认值：8080

BaseURI

BaseURI string

所有路由的基础 URI 前缀。设置后，只接受以此前缀开头的请求。

Backend

Backend route.Backend

默认后端服务。当没有路由匹配时使用。

Routes

Routes []route.Route

路由定义数组。有关详细信息，请参阅路由 API。

Cache

Cache Cache

缓存配置。请参阅缓存配置。

HealthCheck

HealthCheck HealthCheck

健康检查配置。请参阅健康检查配置。

RateLimit

RateLimit RateLimit

限流策略（根配置与各路由 rate_limit 共用同一结构）。计数器仅通过 zoox.Application.Cache() 持久化；字段语义、默认值、用法与 YAML 示例见限流插件 — 字段详解。亦可直接查看限流配置下的字段表。

缓存配置

type Cache struct {
    Host     string `config:"host"`
    Port     int64  `config:"port"`
    Username string `config:"username"`
    Password string `config:"password"`
    DB       int64  `config:"db"`
    Prefix   string `config:"prefix"`
}

字段

• Host (string): Redis 主机。默认值：127.0.0.1
• Port (int64): Redis 端口。默认值：6379
• Username (string): Redis 用户名（可选）
• Password (string): Redis 密码（可选）
• DB (int64): Redis 数据库编号。默认值：0
• Prefix (string): 键前缀。默认值：gozoox-api-gateway:

健康检查配置

type HealthCheck struct {
    Outer HealthCheckOuter `config:"outer"`
    Inner HealthCheckInner `config:"inner"`
}

外部健康检查

type HealthCheckOuter struct {
    Enable bool   `config:"enable"`
    Path   string `config:"path"`
    Ok     bool   `config:"ok"`
}

• Enable (bool): 启用外部健康检查端点
• Path (string): 健康检查端点路径。默认值：/healthz
• Ok (bool): 始终返回 OK。默认值：true

内部健康检查

type HealthCheckInner struct {
    Enable   bool `config:"enable"`
    Interval int64 `config:"interval"`
    Timeout  int64 `config:"timeout"`
}

• Enable (bool): 启用内部服务健康检查
• Interval (int64): 检查间隔（秒）。默认值：30
• Timeout (int64): 请求超时（秒）。默认值：5

限流配置

type RateLimit struct {
    Enable    bool              `config:"enable"`
    Algorithm string            `config:"algorithm,default=token-bucket"`
    KeyType   string            `config:"key_type,default=ip"`
    KeyHeader string            `config:"key_header"`
    Limit     int64             `config:"limit"`
    Window    int64             `config:"window"`
    Burst     int64             `config:"burst"`
    Message   string            `config:"message,default=Too Many Requests"`
    Headers   map[string]string `config:"headers"`
}

计数器仅通过 zoox.Application.Cache() 存储（顶层配置 cache 指向 Redis 等；未配置时使用框架默认）。根配置的 rate_limit 与各路由上的 rate_limit 覆盖项均使用上述结构体。

字段

YAML 键为 snake_case（如 key_type）；下表列为 Go 字段名。是否必须表示一项有效策略是否必填该字段；默认值表示可省略时的取值。简要说明仅作索引；各键的含义、默认值、用法与 YAML 示例见 限流插件 — 字段详解。

字段	Go 类型	是否必须	默认值	简要说明
Limit	int64	是	—	YAML limit，每窗口配额。详细说明
Window	int64	是	—	YAML window，窗口长度（秒）。详细说明
Enable	bool	否	false	YAML enable，作用域开关。详细说明
Algorithm	string	否	token-bucket	YAML algorithm。详细说明
KeyType	string	否	ip	YAML key_type。详细说明
KeyHeader	string	否	（空）	YAML key_header。详细说明
Burst	int64	否	0	YAML burst。详细说明
Message	string	否	Too Many Requests	YAML message。详细说明
Headers	map[string]string	否	（空）	YAML headers。详细说明

示例

cfg := &config.Config{
    Port: 8080,
    BaseURI: "/v1",
    Cache: config.Cache{
        Host: "127.0.0.1",
        Port: 6379,
        DB: 0,
    },
    HealthCheck: config.HealthCheck{
        Outer: config.HealthCheckOuter{
            Enable: true,
            Path: "/healthz",
        },
        Inner: config.HealthCheckInner{
            Enable: true,
            Interval: 30,
            Timeout: 5,
        },
    },
    Routes: []route.Route{
        // ... 路由
    },
}

另请参阅

• 路由 API - 路由配置
• 配置指南 - 配置指南
• 限流插件 - 限流字段详解与 YAML 示例