core

package module
v3.1.75 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 93 Imported by: 0

README

Core Web Framework v3 - 完整帮助文档

NewUUID() 可并发调用,使用默认随机源生成 UUID;调用时不会修改 google/uuid 的进程级随机池开关。调用方不得在并发生成期间切换该依赖的随机池配置。

加密配置原子编辑提供 CurrentConfigFile、NewEncryptedConfigFile 及 Snapshot / Prepare / Commit / Discard,支持密文版本 CAS、跨进程锁和重启恢复;拒绝模板、链接与损坏配置,部署目录必须可写。文件提交不代表运行时已应用,完整合同见 原子配置文件。 v3.1.64 修正 Linux monitor 的真实 CPU、FD 软硬限制与未知值语义,增加主机/进程/文件系统/cgroup 资源指标以及只读缓存 Snapshot;默认基础采样 5 秒、慢采样 30 秒。

v3.1.61 新增可配置 MIME 类型的 gzip 响应压缩,以及 Static 系列 API 的可选长缓存配置(默认 7 天、HTML 重新验证、显式 immutable);同时修复静态文件提前返回 404 和已写出响应追加错误文本的问题。用法与接口兼容说明见下文“gzip 压缩与静态文件缓存”。

v3.1.62 修复默认静态无正文状态提交:四种 Static API 不传 StaticConfig 时,目录跳转仍保持 301,条件请求保持 304,HEAD 不发送正文;缓存仍为可选,不会自动添加 Cache-Control。

v3.1.60 起,NSQ 消费者默认继承最近成功 InitNSQ 的 nsq.auth_secret,非空 NSQConsumerConfig.AuthSecret 显式覆盖,CloseNSQ 清空默认凭据;见 NSQ 认证合同。

生产配置可通过 CORE_CONFIG_KEY_FILE 指定含恰好 32 字节原始密钥的普通文件(限制为 root/运行用户可读)。--generate、.dat 加载和保存共用此密钥;配置错误、解密失败或无效 YAML 均拒绝默认回退并使用脱敏错误。未设置时保持旧流程。配置密钥不改变业务 AESKey 和 AES API;切换密钥必须重新生成 .dat。完整约束见 独立配置密钥。

带点协议值可直接进入枚举 values:ToFixed 将点及连字符转换为常量名下划线,原 wire 值保持不变;无需在业务代码追加映射或伪造生成文件。

枚举边界:生成的 Scan 支持 int64/uint8/uint16/uint32/float64/string/[]byte;数值输入必须为 0~255 的整数,拒绝负数、溢出和非有限浮点且不修改原值。EnumString 对越界索引返回空串,EnumMarshalJSON/EnumMarshalText 返回错误;EnumUnmarshalJSON 在转换前检查数值范围,并支持 256 项映射。字符串解析沿用现行合同,领域取值仍由调用方校验。修改模板后须重新生成业务枚举。

概述

Core 是一个用于快速开发企业级 Go 应用程序的 Web 框架,包括 RESTful API、Web 应用和后端服务。它受到 Tornado、Sinatra 和 Koa (Node.js) 的启发,并具有一些 Go 特有的功能,如接口和结构体嵌入。

主要特性
  • 自动路由注册 - 无需手动配置路由
  • Koa 风格开发 - 类似 Node.js Koa 框架的中间件链式调用
  • 轻量级框架 - 简单易用,性能高效
  • 多数据库支持 - MySQL、PostgreSQL、SQLite、ClickHouse
  • 内置验证器 - 基于 go-playground/validator
  • JSON/XML 支持 - 内置 JSON 和 XML 响应处理
  • 文件上传 - 支持单文件和多文件上传
  • WebSocket 支持 - 内置 WebSocket 处理
  • SSE 推送 - SSE 服务端推送 + EventHub 连接管理
  • 模板引擎 - 支持 HTML 模板渲染
  • Fetch 客户端 - 独立 fetch 包,支持 API 调用、公共/单次 Header、Cookie、HTTP/SOCKS5 代理、请求/响应 Hook
  • Redis Cache - 独立 cache 包,支持 DB fallback、自动回填、singleflight 防击穿、空值缓存
  • 中间件系统 - 灵活的中间件扩展机制
  • ai-context - AI 的工作流程指南
  • skills - 模式库和示例

参考文档:

  • ./AI_CONTEXT.md - Core 任务速查(完整参考见 AI_CONTEXT_REFERENCE.md)
  • ./skills/ - 场景化开发模板

快速开始

安装
go get github.com/xs23933/core/v3
最小示例
package main

import "github.com/xs23933/core/v3"

type Handler struct {
    core.Handler
}

func (Handler) Get(c core.Ctx) {
    c.SendString("Hello, World!")
}

func init() {
    core.RegHandle(new(Handler))
}

func main() {
    app := core.New()
    app.Listen(":8080")
}

项目结构

新业务项目采用 cmd/main.go → internal/app 统一装配, handler/grpc → services → dao → models 处理业务。domain 只放纯业务错误与规则, 不依赖 Core/GORM;现有带数据库支持的生成枚举放在 models。 完整目录、启动与迁移约定见 项目架构。 可运行样例见 example/standard。

配置

config.yaml 示例
debug: true # 调试模式
network: tcp4 # 网络协议
listen: 8080 # 监听端口
prefork: false # 是否启用 prefork 模式
# 空列表默认信任 IPv4/IPv6 私网和回环;非空列表仅信任配置范围。
# 非空列表覆盖默认规则;非法类型/条目使 New() 初始化失败。
trusted_proxies: [] # 公网反代示例: ["203.0.113.10/32"];仅作用于 c.RemoteIP()
log: /var/log/myapp/app.log # 可选:日志文件路径
log_rotate:
  - size: 300M # 文件达到 300MB 后切割
  - daily # 每日切割
  - rotate: 30 # 保留最近 30 天的切割日志
  - compress # 切割后的日志 gzip 压缩
  - delaycompress: 24h # 延迟压缩,需配合 compress
  - missingok # 日志文件不存在时不报错
  - notifempty # 空日志不切割
  - copytruncate # 复制后截断原文件,不替换当前文件句柄

# RESTful 响应格式配置
restful:
  data: data # 数据字段名
  status: success # 状态字段名
  message: msg # 消息字段名

# 数据库配置
database:
  type: sqlite3 # 数据库类型: mysql, pg, sqlite3, clickhouse
  dsn: dat # 数据库连接字符串
  # MySQL 示例: user:password@tcp(localhost:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local
  # PostgreSQL 示例: host=localhost user=postgres password=postgres dbname=test port=5432 sslmode=disable

corectl 命令行工具

go install ./cmd/corectl
corectl new myapp -m example.com/myapp
corectl new users -m example.com/users -t grpc
corectl gen enums ./internal
corectl gen enums --check

new 只创建新目录,生成 cmd/main.go、internal/app 装配、查询业务链和测试。 Go 默认 1.25.0,Core 模板基线 v3.1.71;可显式指定 --go-version 和 --core-version。 初始化步骤、固定 protobuf 工具、版本边界及生成验收见 corectl。 枚举扫描将 *_enums.yaml/enums.yaml 就地生成到同目录,冲突在写入前报错,--check 不写文件; 旧 coregen 单文件方式保留,详见 枚举生成。

核心概念

1. 应用 (Core)

应用是框架的核心,负责管理路由、中间件和服务器。

// 创建应用
app := core.New(core.LoadConfigFile("config.yaml"))

// 启动服务器
app.Listen()

core.New() 会默认注册 GET /health,返回 204 No Content,用于基础存活探测。 业务程序可以显式注册同一路径覆盖默认实现:

app.GET("/health", func(c core.Ctx) error {
    return c.SendString("ok")
})
2. 上下文 (Ctx)

上下文对象封装了 HTTP 请求和响应,提供了丰富的操作方法。

c.RemoteIP() 的 trusted_proxies 未配置、为 null 或空列表时,默认信任 IPv4/IPv6 私网和回环(net.IP.IsPrivate() / IsLoopback());非空列表只信任配置的 IP/CIDR,覆盖默认范围,回环也必须显式列入。配置必须是字符串列表,非法类型、空白项或任意非法 IP/CIDR 都使整个配置失败;New() 沿用现有初始化错误约定直接 panic,不忽略条目、不回退私网兜底。先校验 TCP 对端,不可信则忽略所有 IP 头。XFF 从右向左使用同一可信规则检查,重复头合并,返回首个不可信 IP,全部可信时返回最左项。仅缺少 XFF 时尝试单个合法的 X-Real-IP;XFF 为空或检查途中遇到非法项时直接回退对端。重复或包含列表的 X-Real-IP 无效。不采信其它 IP 头、不内置信任 Cloudflare;无效对端返回 nil。包级 core.RemoteIP(header, addr) 不读取应用配置,使用私网/回环默认规则;ExtractClientInfo(ctx) 使用独立的 Gateway 信任规则,不再解析原始 XFF/X-Real-IP:仅在当前 Core 的 Gateway 信任规则通过且 core-client-ip 为单个合法 IP 时采信,否则返回 gRPC 对端 IP。未设置 GRPCServerConfig.TrustGateway 时按实际 gRPC 对端 IP 默认信任私网/回环;设置后完全使用回调结果,拒绝时不启用兜底。

同机 Caddy/Nginx 连接 127.0.0.1:8080 时,回环默认可信,无需额外配置:

listen: "127.0.0.1:8080"
trusted_proxies: []

严格部署应显式列出服务实际看到的代理 IP 或最小 CIDR,例如 trusted_proxies: ["10.0.0.2/32"],此时其它私网及回环地址不再自动可信。配置在初始化时解析,修改需重建应用。空配置的私网兜底意味着其它内网主机也能提交转发头,因此后端端口仅允许受控代理访问。框架无法验证可信代理自己伪造的头。代理不能原样透传用户 XFF,必须覆盖或追加实际连接来源;使用 X-Real-IP 时必须覆盖为验证后的客户端 IP。

普通 Caddy 入口可使用默认 reverse_proxy 127.0.0.1:8080(默认防止客户端伪造 XFF)。普通 Nginx 入口可在 location 中覆盖为 proxy_set_header X-Forwarded-For $remote_addr;;多级代理也可使用 $proxy_add_x_forwarded_for 追加来源,Core 从右侧识别信任边界。

Cloudflare DNS 代理开启时,由 Caddy/Nginx 验证回源地址,Core 只信任 Caddy/Nginx。以 Caddy 为例,环境变量 CLOUDFLARE_CIDRS 必须填入空格分隔的完整 Cloudflare 官方 IPv4/IPv6 回源段,并随官方变更维护;全局块必须位于 Caddyfile 最前且只出现一次:

{
    servers {
        trusted_proxies static {$CLOUDFLARE_CIDRS}
        trusted_proxies_strict
        client_ip_headers CF-Connecting-IP
    }
}
example.com {
    reverse_proxy 127.0.0.1:8080 {
        header_up X-Forwarded-For {client_ip}
    }
}

Nginx 需要启用 HTTP realip 模块;/etc/nginx/cloudflare-realip.conf 由部署侧维护完整官方回源段,每段一行 set_real_ip_from CIDR;,不能信任任意来源。在 server 中配置:

include /etc/nginx/cloudflare-realip.conf;
real_ip_header CF-Connecting-IP;

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header X-Forwarded-For $remote_addr;
}

不可信来源传入的 CF-Connecting-IP 不会改写上述客户端地址;不要直接转发 $http_cf_connecting_ip。后端禁止绕过受控代理访问,代理层只信任实际的上游来源。

实现依据:Gin 可信链校验、Caddy 可信代理选项、Caddy reverse_proxy 头规则、Nginx realip 模块。

轻量 GRPCCtx

在 protobuf 生成的 gRPC 方法内部使用 c := core.NewGRPCCtx(ctx);stream 使用 core.NewGRPCCtx(stream.Context())。不改变 protobuf 方法签名,不嵌入 HTTP BaseCtx,不提供路由、JSON 或 HTTP 状态码能力。对象只用于当前 RPC 生命周期;业务 Service 继续接收 c.StdContext(),不要保存封装对象或跨 RPC 复用。nil/零值使用 background context,不能据此写有效 RPC 响应。

方法 方向与语义
StdContext() context.Context 原始 context,保留 deadline/cancellation、peer 和 Core 信任配置
GetHeader(key) string 读取 incoming metadata 的第一个值,大小写不敏感;缺失返回空字符串
HeaderValues(key) []string 读取请求多值,返回独立副本
RequestMetadata() metadata.MD 读取全部请求 metadata 的独立副本,修改不会影响请求
ClientIP() string 复用 ExtractClientInfo 的 Gateway 信任校验,不能用原始 core-client-ip 代替
Cookie(name) (string, error) 读取请求 Cookie 并 URL 解码;缺失返回 http.ErrNoCookie,非法转义返回错误
SetHeader(key, values...) error 复用 GrpcSetHeader,排队写入 Gateway HTTP 响应桥接字段,重复调用追加值
SetCookie(name, value, exp, path, args...) error 复用 GrpcSetCookie 的默认值、URL 编码、Domain 与变参规则
WriteCookie(*http.Cookie) error 复用 GrpcCookie,完整响应 Cookie,不补默认值或编码
RemoveCookie(name, path, domain...) error 复用 GrpcRemoveCookie 删除规则
OutgoingContext(metadata.MD) context.Context 构造下游 RPC context,显式添加的键覆盖已有 outgoing 同名键,不自动转发 incoming metadata

请求读取不代表字段已通过身份验证。响应 Header/Cookie 必须在发送 initial headers 或第一条 stream 消息之前写入,并处理 error;此处的 SetHeader 使用 core-http-<name>-bin 响应桥接协议,不是下游调用参数,也不会修改请求。需要原生 gRPC response metadata/trailer 时可直接对 StdContext 使用 gRPC 标准 API。

在现有 RPC 方法中适配协议层,再传递标准 context 给 Service:

c := core.NewGRPCCtx(ctx)
requestID := c.GetHeader("x-request-id")
clientIP := c.ClientIP() // 可供审计;信任规则与 ExtractClientInfo 一致
_ = clientIP
if err := c.SetHeader("X-Request-ID", requestID); err != nil {
    return nil, err
}
return s.service.GetProfile(c.StdContext(), req)

调用下游时,只选择需要传递的字段(需要导入 google.golang.org/grpc/metadata):

c := core.NewGRPCCtx(ctx)
callCtx := c.OutgoingContext(metadata.Pairs("x-request-id", c.GetHeader("x-request-id")))
return userClient.GetProfile(callCtx, req)

OutgoingContext 保留原 context 的 deadline、取消及已有 outgoing metadata;提供的同名键整体覆盖旧值,并复制 map/slice。不会自动传播 Cookie、Authorization、core-client-ip 或响应字段。显式传播身份字段时,下游仍须按自己的调用方信任策略验证。修改请求/传入 metadata 的副本不会改变已创建的下游 context。已有 GrpcHeader、GrpcSetHeader、GrpcSetCookie 等函数继续可用。

Gateway 客户端 IP 的可信传递

Gateway 保留 metadata 字段 core-client-ip(常量 core.GatewayClientIPMetadata),过滤客户端同名 HTTP 头,并在普通 header 和 middleware 变量转换完成后覆盖为 c.RemoteIP().String() 的单值结果。对端无法解析时不发送该字段;自动和手工 HTTP→gRPC 路由使用同一实现,重试沿用同一结果。原始 headers/body 中的字段仍是请求数据,不能当作可信身份来源。

下游可在创建 gRPC server 之前设置 GRPCServerConfig.TrustGateway 收紧或替换默认规则,然后统一通过 core.ExtractClientInfo(ctx).IP 取用户 IP。回调只能依据连接对端或经过验证的 transport 身份判断,不能读取 metadata、XFF 或用户提交的身份字段来决定信任。未设置回调(包括未配置 GRPCServerConfig)时,只根据实际 gRPC 对端 IP 默认信任私网/回环(IPv4/IPv6 的 IsPrivate/IsLoopback);公网、链路本地、缺少或无效对端均不默认可信。设置回调后完全按回调结果判断,回调拒绝不会启用私网兜底。校验拒绝、缺少 peer、缺少字段或非法/重复字段都返回 gRPC 对端 IP,不回退原始 XFF/X-Real-IP。此规则同时适用于 unary 和 stream。直接使用 grpc.NewServer() 或脱离 Core 托管上下文调用 ExtractClientInfo 不会采信该字段。

受控内网按精确 Gateway IP 判断的示例,需要导入 context、net 和 google.golang.org/grpc/peer:

gatewayIP := net.ParseIP("10.0.0.2")
if err := app.ConfigureGRPCServer(core.GRPCServerConfig{
    TrustGateway: func(ctx context.Context) bool {
        p, ok := peer.FromContext(ctx)
        if !ok {
            return false
        }
        addr, ok := p.Addr.(*net.TCPAddr)
        return ok && addr.IP.Equal(gatewayIP)
    },
}); err != nil {
    return err
}
// 随后注册服务、调用 EnableEtcdRegistry(nil),再启动应用。

上面的显式回调没有私网兜底。未设置回调的私网兜底适用于受控内网,后端端口必须限制为仅 Gateway 可访问;内网其它主机能直连时也可以提交该字段。需要 CIDR 时预先使用 net.ParseCIDR 解析并检查错误,回调中对实际 peer.Addr 做 Contains 判断;应用负责限制后端仅允许 Gateway 访问。多 Gateway 应明确列出各个来源。

mTLS 部署在 ConfigureGRPCServer 同时设置 TransportCredentials,启用客户端证书验证。TrustGateway 应检查 peer.AuthInfo 中的 credentials.TLSInfo、非空 State.VerifiedChains,并匹配实际 Gateway 的证书 URI/SAN 身份;仅“证书属于同一 CA”不代表它是 Gateway。Core 不推断业务证书身份,详见 gRPC TLS 配置说明。

兼容性:旧服务依赖 ExtractClientInfo 读取 XFF/X-Real-IP 的用法需要迁移。Gateway 与下游应一起升级;受控私网/回环部署可使用默认规则,严格部署应显式配置回调;旧 Gateway 没有 core-client-ip 时会返回连接对端,不会猜测用户 IP。etcd 自动注册/reflection 不提供调用方认证。用户 IP 仅表示 Gateway 对入站来源的判断,不代替业务鉴权。

func (Handler) Get(c core.Ctx) {
    // 获取请求信息
    method := c.Method()      // 请求方法
    path := c.Path()          // 请求路径
    ip := c.RemoteIP()        // 客户端 IP

    // 获取参数
    id := c.Params("id")              // 路径参数
    name := c.Query("name")           // 查询参数
    age := c.QueryInt("age", 18)      // 查询参数转int

    // 获取表单数据
    email := c.FormValue("email")

    // 获取请求头
    token := c.GetHeader("Authorization")

    // 设置响应头
    c.SetHeader("Content-Type", "application/json")

    // 发送响应
    c.SendString("Hello")
    c.JSON(map[string]any{"code": 200, "msg": "success"})
    c.SendStatus(404, "Not Found")
}
3. 处理器 (Handler)

处理器是业务逻辑的载体,通过嵌入 core.Handler 来获得框架功能。

type UserHandler struct {
    core.Handler
}

// Init 定义Prefix 此Handler 下都加上了 /users group
func (UserHandler) Init() {
	core.Prefix("/users")
}

// GET /users
func (UserHandler) Get(c core.Ctx) {
    users, err := models.GetUsers()
    c.ToJSON(users, err)
}

// POST /users
func (UserHandler) Post(c core.Ctx) {
    var user models.User
    if err := c.ReadBody(&user); err != nil {
        c.ToJSON(nil, err)
        return
    }
    c.ToJSON(user, user.Save())
}

// GET /users/:id
func (UserHandler) GetByID(c core.Ctx) {
    id, err := c.ParamsUid("id")
    if err != nil {
        c.ToJSON(nil, err)
        return
    }
    user, err := models.GetUserByID(id)
    c.ToJSON(user, err)
}

// 自动注册路由
func init() {
    core.RegHandle(new(UserHandler))
}
4. 路由系统

框架支持自动路由注册,基于方法名和注释生成路由。

路由规则
关键字 路由规则 结果
Param 参数关键词 :param
Params 参数关键词 :params?
_id 下划线 /:id
By 参数关键字 /:
__ 中横线 -
__dot__ 点 .

Params 是可选关键词 即:params?

  • Get → GET /
  • GetParam → GET /:param
  • GetParams → GET /:params?
  • GetByID → GET /:id
  • GetDetailParam → GET /detail/:param
  • PostUser → POST /user
  • PutUserParam → PUT /user/:param
  • GetUserByID → GET /user/:id
  • GetUser__Create → GET /user-create
  • GetUser__dot__Html → GET /user.html

框架内置默认路由 GET /health,返回 204 No Content。如果业务代码再次注册 GET /health,业务 handler 会覆盖框架默认 handler。

手动路由的动态 segment 必须有明确且无歧义的定义:同一结构位置不能混用不同参数名, 也不能混用必选 :id 与可选 :id?。可选参数和 catch-all 只能位于最后一段, 路径中不允许空 segment(//)。违反这些规则会在注册时 panic,避免由注册顺序决定匹配结果。 /* 仍是有效的根 catch-all,捕获值通过 c.Params("*") 读取。 通过 Core 的 AddHandle/RemoveHandle 进行的运行期路由更新可与请求匹配并发执行。

路由注释
// GetUser 获取用户信息
// get /user/:param
// @id: uid.UID 用户ID
func (Handler) GetUserParam(c core.Ctx) {
    id, err := c.ParamsUid("param")
	c.ToJSON(nil, err)
}
5. 数据模型

框架集成了 GORM,提供了便捷的数据库操作。

package models

import "github.com/xs23933/core/v3"

type User struct {
    core.Model
    Username string `json:"username" gorm:"size:32;uniqueIndex"`
    Email    string `json:"email" gorm:"size:128;uniqueIndex"`
    Password string `json:"-" gorm:"size:96"`
    Age      int    `json:"age" gorm:"default:18"`
}

// 创建用户
func (u *User) Create() error {
    return db.Create(u).Error
}

// 根据ID查询用户
func GetUserByID(id uid.UID) (user User, err error) {
    err = db.First(&user, "id = ?", id).Error
    return
}

// 分页查询用户
func GetUsers(page, size int) (users []User, total int64, err error) {
    err = db.Model(&User{}).Count(&total).Error
    if err != nil {
        return
    }
    offset := (page - 1) * size
    err = db.Offset(offset).Limit(size).Find(&users).Error
    return
}


var db *core.DB
// 初始化数据库
func InitDB() {
    db := core.Conn()
    db.AutoMigrate(&User{})
}
6. 中间件

框架支持灵活的中间件系统。

// 自定义中间件
func AuthMiddleware(c core.Ctx) error {
    token := c.GetHeader("Authorization")
    if token == "" {
        return c.SendStatus(401, "Unauthorized")
    }
    // 验证 token
    // ...
    return c.Next()
}

// 全局中间件
app.Use(AuthMiddleware)

// 路径级中间件:匹配 /api 及其所有子路径,不要添加 /*。
app.Use("/api", AuthMiddleware)

// 路由级中间件
app.GET("/admin", AdminHandler, AuthMiddleware)

路径级中间件使用路径前缀节点。app.Use("/api", middleware) 会作用于 /api、/api/users、/api/v1/orders 等路由。不要写成 app.Use("/api/*", middleware);* 是路由 catch-all 段,不是路径级中间件的前缀标记。

app.Use("/api", authMiddleware.Handle)
app.Use("/internal", internalAuthMiddleware.Handle)

中间件执行顺序:

  • 全局中间件通过 app.Use(middleware) 注册到根节点,后注册的会前置执行。需要按期望执行顺序反向注册。
  • 同一路径的中间件按注册顺序执行。
  • 嵌套路径始终按父路径到子路径执行,例如 /api 中间件先于 /api/internal 中间件。
  • 路径级中间件之后才执行路由自身的 middleware 和最终 handler。

未匹配到显式路由的请求也会经过全局中间件,然后由框架的 fallback handler 返回 404;因此显式注册的 core.Logger() 能记录 404 METHOD /path。路径级中间件不会为未匹配路由执行。IsRouteFallback(c) 仍只在未匹配的 OPTIONS fallback 链中返回 true。

// 期望执行顺序:requestID -> accessLog -> handler。
// 全局中间件需要反向注册。
app.Use(accessLogMiddleware)
app.Use(requestIDMiddleware)

// 同一路径按注册顺序执行:auth -> audit -> handler。
app.Use("/api", authMiddleware.Handle)
app.Use("/api", auditMiddleware.Handle)

// GET /api/internal/status:auth -> internalAuth -> handler。
app.Use("/api", authMiddleware.Handle)
app.Use("/api/internal", internalAuthMiddleware.Handle)
app.GET("/api/internal/status", statusHandler)
内置中间件
import (
	core "github.com/xs23933/core/v3"
    "github.com/xs23933/core/v3/middleware/requestid"
    "github.com/xs23933/core/v3/middleware/cors"
)

app.Use(requestid.New())  // 请求ID
app.Use(cors.New())       // CORS 支持
app.Use(core.Logger())    // 显式启用请求日志;Recovery 由 core.New() 自动注册
运行时与主机资源监控
import "github.com/xs23933/core/v3/middleware/monitor"

app.Use(monitor.New(monitor.Config{
    Interval: 5 * time.Second,
    ResourceInterval: 30 * time.Second,
    DiskPath: "/var/lib/my-service",
}))
app.GET("/sys/stats", monitor.StatsHandler())
app.GET("/metrics", monitor.PrometheusHandler())
// 读取同一份缓存,不触发系统采集;其中的可空指标仅供只读使用。
stats := monitor.Snapshot()
_ = stats

monitor.New 首次安装时立即采集,随后以固定间隔缓存;重复安装复用首次配置及同一个进程级采集循环。Interval 最小 1 秒,ResourceInterval 默认 30 秒且不短于 Interval。请求和 Snapshot 只读快照;单独注册 Handler 不会启动采集,必须安装 monitor.New。后台循环在进程退出时结束。

原有 Go 内存、GC、goroutine、连接和请求 JSON 字段保留。cpu_percent 改为 Linux /proc/self/stat 用户态与内核态累计 CPU 时间相邻采样差分,使用 /proc/stat 累计时间归一化,单核满载为 100、多核可超过 100;首次采样、CPU 热插拔或计数器回退时 cpu_available=false。host_cpu_percent 为可见内核的全部 CPU 忙碌比例(0–100,不含 idle/iowait,guest 不重复计数),不等同于容器 CPU 配额占用率。max_fds 修正为当前进程软限制,max_fds_hard 提供硬限制;fd_available 表示计数与限制均有效,限制 -1 表示无限制。

Linux 新指标使用可空数值,缺失、权限不足或不支持返回 JSON null:process_rss_bytes、process_threads;host_cpu_count、host_memory_total_bytes、host_memory_available_bytes、host_swap_total_bytes、host_swap_free_bytes;host_load1/5/15;pressure_cpu_some_avg10、pressure_memory_some_avg10、pressure_io_some_avg10。PSI 是最近 10 秒至少一个任务等待对应资源的百分比。macOS 等非 Linux 平台继续提供 Go 运行时指标,系统指标为 null 或对应可用标记为 false,不能当成健康零值。

慢采集只对 DiskPath 所在本地文件系统执行一次 statfs,不扫描目录树或枚举所有挂载。disk_total_bytes、disk_available_bytes 使用当前用户可用块数,disk_inodes_total/available 在文件系统提供 inode 容量时有效;disk_path 仅用于本地受保护的诊断,跨服务投影应按白名单移除路径。FD 目录分批计数,超过 131072 项时本轮不可用。cgroup v2 提供 cgroup_memory_current_bytes、cgroup_memory_limit_bytes、cgroup_pids_current/limit、cgroup_cpu_limit_cores,有限限制取当前及最多 64 层可见祖先的最小值;无限制或读取不到有限限制时 limit 为 null。不支持 cgroup v1,无法观察挂载根外的祖先约束;cgroup memory/pids 的当前值包含当前组的全部进程,不能用单进程 RSS 替代。 cgroup_memory_available_bytes 与 cgroup_pids_available 取各可见祖先自身 limit-current 的最小值,以包含同父组其它进程占用;受限祖先读取失败时为 null,耗尽时为 0。不要用叶组 current 除以继承 limit 推断祖先余量。

sampled_at 为常规采集时间;resource_sampled_at 为 FD、磁盘、cgroup 与主机标识的慢采集时间,disk_sampled_at 仅在磁盘读取成功时返回。监控消费方应检查快照新鲜度与可用性。host_id 是 Linux boot_id 的 SHA-256,可聚合同一内核启动下的服务,重启后变化;获取失败时为空,不包含原始主机名、IP 或 boot_id。Prometheus 对未知的 CPU、FD 与新增资源指标省略对应序列,并额外提供 core_cpu_available、core_fd_available。 disk_id 是同一主机启动身份与文件系统设备号的 SHA-256;不同磁盘分别聚合,未取得主机身份时为空,不包含监控路径。

统一响应压缩(zstd、Brotli、gzip)
import "github.com/xs23933/core/v3/middleware/compress"

app.Use(compress.New())
// 可选:共享 MIME/阈值,分别配置算法级别。
// app.Use(compress.New(compress.Config{MinLength: 2048, GzipLevel: 1}))

compress.New(config ...compress.Config) 返回 core.HandlerFunc。Config 提供 ContentTypes、MinLength、GzipLevel、ZstdLevel、BrotliLevel、EnableSSE、Skip。默认 MIME、1024 字节阈值和三种编码器的默认级别沿用独立中间件;ContentTypes 为非 nil 空切片时禁用压缩,负 MinLength 取消阈值。非法 MIME/算法级别返回配置错误,不按客户端算法静默回退。

按 Accept-Encoding 的正 q 值从高到低选择,平局依次优先 zstd、br、gzip;显式编码覆盖通配符,显式 q=0 禁止。q 必须为 0~1、至多三位小数;非法参数视为该编码不可接受。多行头合并解析;同一编码重复时取最低权重,防止禁止声明被覆盖。显式 identity 权重高于压缩编码时发送原文;未显式声明的 identity 只作兜底(显式 identity 不写 q 时按 1 处理)。缺失或空头保持原文,不自动压缩,也不改写下游看到的请求头。

Accept-Encoding 结果(响应符合压缩条件时)
gzip, zstd zstd
br, gzip br
zstd;q=0.2, br;q=0.8, gzip;q=0.5 br
zstd;q=0.2, gzip;q=0.8 gzip
zstd;q=0, gzip gzip
*;q=0, gzip;q=0.5 gzip;不允许原文
identity;q=1, gzip;q=0.5 原文
*;q=0 406,不调用 handler

仅安装统一入口即可;现有 gzip.New() / zstd.New() 默认行为不变,新增 brotli.New()。三个入口复用内部流式 writer、池化与清理逻辑。保留 Vary、静态缓存、ReaderFrom、HEAD/Range/Upgrade/CONNECT、204/304、默认 SSE、既有编码和 no-transform 等处理。入口已有非 identity 的 Content-Encoding 时透传,不重新编码;下游 handler 写出时设置既有编码也不重复压缩,其编码协商由生成该响应的一方负责。但请求拒绝 identity 且不接受 br/gzip/zstd 时会提前 406,无法预知下游才生成的其它预编码表示;这种预编码路径应使用 Skip(或在进入统一入口前完成编码协商并设置响应头)。

客户端允许 identity 时,不符合 MIME/阈值或提前 Flush 的响应保持原文。若显式禁止 identity(含 *;q=0 未给 identity 例外),而响应无法压缩,返回无缓存的 406,并向正文生产者返回内部拒绝错误以停止继续写出/读盘;该拒绝在中间件边界消化,不作为服务器故障,但其它写入/关闭错误仍保留。不强制压缩图片、默认 SSE 或 no-transform;HEAD、204/304 等无正文响应保持无正文。后验发现无法压缩时 handler 已执行,406 不回滚业务副作用。Skip 为 true 则完全绕过协商(包括 406),由调用方负责该路径。zstd 输出开始后的失败继续返回错误,不能切换为 gzip。测试与样本性能对比见 统一压缩性能报告。

Brotli 插件与 SSE 流式压缩
// 推荐统一协商:q 权重优先,同权重 zstd → br → gzip。
app.Use(compress.New(compress.Config{EnableSSE: true}))

独立入口是 github.com/xs23933/core/v3/middleware/brotli,API 为 brotli.New(config ...brotli.Config);Config 含 ContentTypes、Level、MinLength、EnableSSE、Skip。仅安装统一或单算法入口之一。Brotli 复用已有 andybalholm/brotli 依赖,Level: 0 使用默认质量6,显式范围1~11;普通响应默认阈值1024字节,图片不默认压缩。compress.Config.BrotliLevel 采用相同规则。

EnableSSE 在三个独立入口和统一入口中默认 false,保持现有 SSE 不压缩;设为 true 后,text/event-stream(允许 charset 参数)绕过 MinLength,并在首次 Flush/DoWriteHeader 时先选择压缩编码。每个 SSEWrite / SSESend / SSEComment 的 Flush 都刷新编码器再刷新 HTTP writer,因此微小事件不等待整个响应关闭。仍尊重请求协商、no-transform、Range、已有编码、无正文状态;非 nil 空 ContentTypes 完全禁用压缩,包括 SSE。EnableSSE 明确放行 SSE,不要求额外把它加进非空的 MIME 列表。

SSE 发送前设置 Content-Type: text/event-stream 和 Cache-Control: no-cache;不要同时设置 no-transform 来期望开启压缩,因为压缩中间件会尊重它并跳过转换。普通 HTTP 流仍采用原有阈值规则:先写出达到阈值的数据再 Flush,或以负 MinLength 取消阈值;普通响应首次仅 Flush 仍提交原文。

Upgrade 和 CONNECT 完全绕过统一 HTTP 压缩协商,不由 identity/q 规则阻止 WebSocket 握手。WebSocket 使用独立的 RFC7692 permessage-deflate;不是 Brotli/gzip/zstd Content-Encoding。通过 websocket.Options{EnableCompression: true, ReadLimit: 1 << 20} 开启标准浏览器消息压缩,仅双方协商成功才生效,默认 false。大消息可分段写入 NextWriter,但必须 Close 才结束该消息;浏览器以完整消息触发回调,实时推送应逐条发送,不把所有事件合成一个无限消息。ReadLimit 同时约束解压后的完整消息大小。

本地真实 HTTP 流测试覆盖连接关闭前逐条解压事件、预先刷新头、三种编码与两种 ETag 安装顺序;不保证 Cloudflare/其它代理不会缓冲,生产链路需单独验证。见 流式压缩验证与性能报告。

zstd 响应压缩
import "github.com/xs23933/core/v3/middleware/zstd"

app.Use(zstd.New())
// 或自定义配置:
// app.Use(zstd.New(zstd.Config{MinLength: 2048}))

middleware/zstd 与 gzip 使用相同的 New(config ...Config) 形式,支持 ContentTypes、Level、MinLength、EnableSSE、Skip;默认 MIME 列表、1024 字节阈值和跳过规则同 gzip。Level 使用 github.com/klauspost/compress/zstd.EncoderLevel,0 使用 SpeedDefault,可选 SpeedFastest、SpeedDefault、SpeedBetterCompression、SpeedBestCompression;非法级别或 MIME 返回配置错误。复用已有 klauspost/compress 依赖,单个 encoder 使用并发度 1,请求间池化复用并清除请求 writer 引用。

客户端通过 Accept-Encoding: zstd(支持 q 值、通配符和显式 zstd;q=0 拒绝)协商,响应设置 Content-Encoding: zstd 和 Vary: Accept-Encoding。不足阈值时保留原文,达到后流式压缩;Flush 刷新压缩流,普通响应压缩前提前 Flush/DoWriteHeader 则保持原文;显式启用的 SSE 会先建立编码器再提交/刷新。HEAD/CONNECT/Upgrade/Range、204/304、默认 SSE、已有编码和 no-transform 跳过;长度、摘要、ETag 的处理同 gzip,未协商压缩时保留静态 ReaderFrom 传输路径。独立入口选择 gzip 或 zstd 之一安装;需要自动协商二者时使用 middleware/compress。叠加不提供跨算法 q 值优先选择,只由先处理正文的中间件决定编码,已有编码阻止重复压缩。

gzip 压缩与静态文件缓存
import (
    "time"

    "github.com/xs23933/core/v3"
    "github.com/xs23933/core/v3/middleware/gzip"
)

app.Use(gzip.New())

// 显式启用静态缓存:默认 7 天,HTML 始终 no-cache。
app.Static("/static", "./static", core.StaticConfig{})

// 仅用于内容变化时 URL 也变化的资源,例如 app.a12bc34.js。
app.Static("/assets", "./dist/assets", core.StaticConfig{
    MaxAge:    365 * 24 * time.Hour,
    Immutable: true,
})
app.StaticFile("/", "./dist/index.html", core.StaticConfig{})

gzip 默认压缩 JSON、HTML、CSS、JS、纯文本、XML、SVG;PNG、WebP、JPEG 默认不压缩。默认阈值为 1024 字节,级别为标准库 gzip.DefaultCompression。gzip.Config 支持 EnableSSE、ContentTypes(非 nil 时替换默认 MIME 列表,空切片禁用)、Level、MinLength(0 使用默认值,负数取消阈值)、Skip。MIME 匹配忽略大小写及 charset 等参数;未设置响应类型时从首段数据推断。非法 MIME 类型或压缩级别会使中间件返回配置错误,不能静默回退。

中间件根据 Accept-Encoding(含 q 值)协商并添加 Vary: Accept-Encoding。HEAD、CONNECT、Upgrade、Range、204/304、默认 SSE、已有 Content-Encoding 和 Cache-Control: no-transform 跳过压缩;压缩时移除原始 Content-Length、Accept-Ranges 和内容摘要,将强 ETag 转为弱 ETag。只缓存不足阈值的前缀,之后流式压缩;普通响应在达到阈值前显式 Flush/DoWriteHeader 会立即发送原始内容;EnableSSE 开启的 SSE 则先建立编码器。中间件必须在响应写出前执行。

静态缓存配置也适用于 StaticFS(relativePath, fs, config...)、StaticFile(relativePath, filename, config...) 和 StaticFileFS(relativePath, filename, fs, config...)。不传配置保留原来的缓存行为;传入 StaticConfig{} 后,成功的静态资源使用 Cache-Control: public, max-age=604800。MaxAge 是 time.Duration,按整秒输出;负数或小于一秒的正数使用 no-cache。HTML(含目录默认 index 页面)始终使用 no-cache,允许保存但每次使用前需要重新验证。已有 Cache-Control 优先,不给动态 API、重定向或错误响应添加长缓存;条件请求与 Range 由标准库继续处理。只有明确启用 Immutable 时才追加 immutable,框架不会猜测文件名是否包含内容 hash。

响应已写出后再返回 handler 错误时,Core 记录错误,不再追加错误文本或改写状态,避免破坏已发送的压缩、二进制或流式内容;未写出时仍按原有规则返回错误响应。

兼容性:原有静态方法调用无需修改;如果下游自行声明了包含这些方法的接口,或将方法赋给固定参数的函数类型,需要同步追加可变参数 ...core.StaticConfig。core.Ctx 新增 SetResponseWriter;内嵌 core.BaseCtx 的上下文自动继承,自行维护的 Ctx 包装器或 mock 需同步支持该方法。

7. 验证器

框架集成了 go-playground/validator,支持结构体验证。

type LoginForm struct {
    Username string `json:"username" validate:"required,min=3,max=32"`
    Password string `json:"password" validate:"required,min=6,max=128"`
    Email    string `json:"email" validate:"omitempty,email"`
}

func (Handler) Login(c core.Ctx) {
    var form LoginForm
    if err := c.ReadBody(&form); err != nil {
        c.ToJSON(nil, err)
        return
    }

    // 自动验证
    if err := c.Validate(&form); err != nil {
        c.ToJSON(nil, err)
        return
    }

    // 业务逻辑
    // ...
}
8. 文件上传
// 单文件上传
func (Handler) Upload(c core.Ctx) {
    file, err := c.FormFile("file")
    if err != nil {
        c.ToJSON(nil, err)
        return
    }

    // 保存文件
    relpath, abspath, err := c.SaveFile("file", "./uploads")
    if err != nil {
        c.ToJSON(nil, err)
        return
    }

    c.ToJSON(map[string]string{
        "filename": file.Filename,
        "path":     relpath,
        "size":     fmt.Sprintf("%d", file.Size),
    })
}

// 多文件上传
func (Handler) UploadMultiple(c core.Ctx) {
    files, err := c.SaveFiles("files", "./uploads")
    if err != nil {
        c.ToJSON(nil, err)
        return
    }

    c.ToJSON(files)
}
9. WebSocket 支持
package main

import (
    "net/http"
    "time"
    "github.com/xs23933/core/v3"
    "github.com/xs23933/core/v3/websocket"
)

func main() {
app := core.New()
app.GET("/ws", websocket.New().
    WithOptions(websocket.Options{
        Subprotocols: []string{"example.v1"},
        RequireSubprotocol: true,
        CheckOrigin: func(r *http.Request) bool { return r.Header.Get("Origin") == "" },
        ReadLimit: 512 << 10,
        ReadTimeout: 60 * time.Second,
        WriteTimeout: 10 * time.Second,
        HandshakeTimeout: 10 * time.Second,
    }).
    OnConnect(func(conn *websocket.Conn) {
        if !conn.TrySend([]byte("已连接")) { return }
    }).
    OnMessage(func(conn *websocket.Conn, mt websocket.MessageType, data []byte) {
        conn.TrySendWithType(mt, data)
    }).
    OnClose(func(conn *websocket.Conn) { core.Info("websocket closed") }).
    Handler())
if err := app.Run(); err != nil { core.Erro("websocket stopped error_type=%T", err) }
}

WithOptions 可省略。零配置保持原行为:允许任意 Origin、不要求子协议、不限制消息大小或读写等待。需要设备或敏感通道时,调用方必须先鉴权并显式配置以上边界;框架不解释业务身份。

ReadLimit 限制完整消息含所有分片的累计字节数,超限不进入回调。ReadTimeout 在每条消息开始及收到 pong 时刷新;WriteTimeout 同时约束消息和 ping 写入。RequireSubprotocol 要求客户端提供至少一个配置中的协议,无匹配或配置为空时拒绝升级。

TrySend/TrySendWithType 复制输入并返回是否成功入队;成功不代表网络发送或对端持久接纳。队列满或连接已关闭时返回 false,背压会关闭连接并归还未发送缓冲区。既有 Send/SendWithType 保持无返回值。OnMessage 中的字节切片只在回调期间有效,异步保留须复制。

Conn.Context() 从升级请求派生并在 Close() 时取消;不要把 core.Ctx 放入连接或 goroutine。连接关闭会停止读写、移除默认管理器连接并释放排队缓存,读写循环退出后 OnClose 调用一次。配置和回调在注册 Handler 前设置。

按用户推送消息:

app.GET("/ws", func(c core.Ctx) error {
	userID := c.Query("user_id")
	if userID == "" {
		return c.SendStatus(401, "missing user_id")
	}

	return websocket.New().
		OnConnect(func(conn *websocket.Conn) {
			websocket.DefaultUserManager.Add(userID, conn)
		}).
		OnClose(func(conn *websocket.Conn) {
			websocket.DefaultUserManager.Remove(conn)
		}).
		Handler()(c)
})

websocket.DefaultUserManager.SendToUser("1001", []byte(`{"type":"notice","data":"hello"}`))
10. SSE 支持

Core 在 Ctx 层提供了 SSE(Server-Sent Events)核心方法,并通过 EventHub 封装连接管理和广播能力,适用于服务端实时推送通知、日志流、状态更新等场景。

SSE 核心方法

// 写入 SSE 事件(底层方法,支持 id/event/data 字段和多行数据)
c.SSEWrite("message", "hello world")
c.SSEWrite("update", `{"status":"ok"}`, "evt-001")

// 发送结构化事件(自动 JSON 序列化)
c.SSESend("notify", map[string]any{"title": "Alert", "message": "Server down"})

// 发送 SSE 注释(心跳保活)
c.SSEComment("ping")

EventHub 快速使用

import "github.com/xs23933/core/v3"

func main() {
    app := core.New()

    hub := core.NewEventHub()       // 创建 EventHub,支持广播聚合
    defer hub.Close()

    // SSE 连接端点(浏览器 EventSource 连接目标)
    app.GET("/events", hub.Get)

    // 推送接口(其他服务调用此接口推送数据)
    app.POST("/events/push", hub.PostData)

    app.Run()
}

前端连接示例

const es = new EventSource("/events")
es.addEventListener("connected", () => console.log("SSE 已连接"))
es.addEventListener("message", (e) => console.log("收到:", e.data))
es.onerror = () => console.log("连接中断(将自动重连)")

编程式推送

// 广播到所有客户端
hub.Broadcast(core.EventData{
    Event: "alert",
    Data:  "server maintenance in 5 minutes",
})

// 定向推送到指定 ID
hub.SendTo("admin-01", core.EventData{
    Event: "private",
    Data:  map[string]any{"action": "reload"},
})

EventHub 的广播、定向发送、注册、注销和关闭支持并发,慢客户端仍采用非阻塞丢弃。同 ID 的新连接替换旧连接后,旧连接的延迟注销不会影响新连接。手工 Register 会把管道的发送和关闭所有权移交给 Hub;调用方只接收,不得自行关闭或复用退役管道。同一管道的多个 ID 别名共享生命周期,注销或替换时一起移除。

详细 API 参数和注意事项参见 skills/core-sse.md

11. 模板渲染
import (
    "github.com/xs23933/core/v3/middleware/view"
    "github.com/xs23933/core/v3/middleware/view/html"
)

// 配置模板引擎
var viewEngine view.IEngine = html.NewHtmlView("./views", ".html", app.Debug)
app.Use(viewEngine)

// 渲染模板
func (Handler) Index(c core.Ctx) {
    c.Render("index", core.Map{
        "title": "首页",
        "users": []User{...},
    })
}

gRPC、etcd 与网关

Core 支持同时运行 HTTP 与 gRPC,并通过 etcd 做服务注册、服务发现和网关动态路由。推荐把链路拆成三类程序理解:

  1. 业务服务:启动 HTTP 或注册 protobuf 生成的 gRPC service,并把实例及对外路由发布到 etcd。
  2. 内部客户端:通过 app.GrpcClient("service-name") 按服务名发现并调用 gRPC。
  3. 网关服务:监听 etcd 实例和路由变化,把 HTTP 请求代理到 HTTP 或 gRPC 上游。
1. gRPC 服务

服务端必须先注册 gRPC service,再启动应用。只需要 gRPC 时使用 EnableGRPC;需要被网关发现时使用 EnableEtcdRegistry,它会自动创建/复用 gRPC server、注册服务到 etcd,并开启 gRPC reflection。

package main

import (
    "context"

    "github.com/xs23933/core/v3"
    "google.golang.org/grpc"

    pb "your_project/proto/user/v1"
)

type UserService struct {
    pb.UnimplementedUserServiceServer
}

func (s *UserService) GetProfile(ctx context.Context, req *pb.GetProfileRequest) (*pb.User, error) {
    return &pb.User{Id: req.Id, Name: "tom"}, nil
}

func main() {
    app := core.New()

    app.RegisterGRPCService(func(s *grpc.Server) {
        pb.RegisterUserServiceServer(s, &UserService{})
    })

    app.EnableGRPC(":9001")

    if err := app.Listen(":8080"); err != nil {
        panic(err)
    }
}

HTTP 和 gRPC 使用不同端口时,Listen(":8080") 负责 HTTP,EnableGRPC(":9001") 负责 gRPC。

需要服务端 TLS、mTLS 或自定义 unary/stream interceptor 时,必须在第一次注册或获取 gRPC server 前调用 ConfigureGRPCServer。证书身份和授权策略由应用负责,Core 只托管 server 生命周期和 interceptor chain:

serverTLS := &tls.Config{
    MinVersion:   tls.VersionTLS13,
    Certificates: []tls.Certificate{serverCertificate},
    ClientAuth:   tls.RequireAndVerifyClientCert,
    ClientCAs:    clientCAPool,
}
if err := app.ConfigureGRPCServer(core.GRPCServerConfig{
    TransportCredentials: credentials.NewTLS(serverTLS),
    UnaryInterceptors:     []grpc.UnaryServerInterceptor{identityUnary},
    StreamInterceptors:    []grpc.StreamServerInterceptor{identityStream},
}); err != nil {
    panic(err)
}
app.EnableGRPC(":9001")
app.RegisterGRPCService(registerServices)

配置只能执行一次;GetGRPCServer、RegisterGRPCService 或 EnableEtcdRegistry 已经创建 server 后再配置会返回错误。Core 的默认 unary error wrapper 始终保留,并位于调用方 unary interceptor chain 外层。

如果希望 HTTP/1 和 gRPC 共用端口,可以让 EnableGRPC 使用和 Listen 相同的地址。框架会根据 HTTP/2 与 Content-Type: application/grpc 自动分流。

app.RegisterGRPCService(func(s *grpc.Server) {
    pb.RegisterUserServiceServer(s, &UserService{})
})
app.EnableGRPC(":8080")
app.Listen(":8080")

共端口模式只适用于未配置 gRPC transport credentials 的兼容路径。配置 credentials 后必须使用独立的 Core-managed gRPC 地址;否则启动返回 ErrGRPCTLSSharedAddress,不会把 ServeHTTP 错误描述为已执行 gRPC TLS 握手。

需要注册到 etcd 并提供给网关时:

app := core.New(core.LoadConfigFile("config.yaml"))

app.RegisterGRPCService(func(s *grpc.Server) {
    pb.RegisterUserServiceServer(s, &UserService{})
})

if err := app.EnableEtcdRegistry(nil); err != nil {
    panic(err)
}

if err := app.Listen(":8080"); err != nil {
    panic(err)
}
2. etcd 配置

EnableEtcdRegistry(nil) 会读取 etcd 配置。服务端最少需要配置 endpoints、service name 和暴露给其它进程访问的 service addr。

etcd:
  # 可选:共享同一个 etcd 集群时按项目隔离
  namespace: xpay
  endpoints:
    - 127.0.0.1:2379
  dial_timeout: 5
  service_name: user-service
  service_addr: 127.0.0.1:8080
  service_id: user-service-1
  ttl: 10
  version: 1.0.0

配置 namespace: xpay 后,服务实例、Gateway 路由和相对配置 key 分别写入 /xpay/services/、/xpay/gateway/routes/ 和 /xpay/config/。同一项目的业务服务、内部 gRPC 客户端和 Gateway 必须使用相同 namespace;不配置时仍使用原有 /services/、/gateway/routes/ 和 /config/,无需迁移现有数据。

也可以直接传 etcd.Options,适合测试或多环境注入:

if err := app.EnableEtcdRegistry(&etcd.Options{
    Endpoints:   []string{"127.0.0.1:2379"},
    ServiceName: "user-service",
    ServiceAddr: "127.0.0.1:8080",
    ServiceID:   "user-service-1",
    TTL:         10,
    Version:     "1.0.0",
    Metadata: map[string]string{
        "env": "dev",
    },
}); err != nil {
    panic(err)
}

短期在线记录等场景可以复用 EtcdDiscovery 的租约与 revision CAS。这里只提供通用原语,业务所有权和重试策略仍由调用方决定:

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

leaseID, err := app.EtcdDiscovery.GrantLease(ctx, 10)
if err != nil {
    return err
}
defer app.EtcdDiscovery.RevokeLease(context.Background(), leaseID)

keepAlive, err := app.EtcdDiscovery.KeepAliveLease(ctx, leaseID)
if err != nil {
    return err
}
go func() {
    for range keepAlive {
        // channel 关闭表示 context 取消、租约丢失或 Discovery 已关闭。
    }
}()

current, found, err := app.EtcdDiscovery.GetRevision(ctx, "online/worker-a")
if err != nil {
    return err
}
expectedRevision := int64(0)
if found {
    expectedRevision = current.ModRevision
}
succeeded, err := app.EtcdDiscovery.CompareAndPut(ctx, "online/worker-a", expectedRevision, `{"addr":"127.0.0.1:9001"}`, leaseID)
if err != nil {
    return err
}
if !succeeded {
    return errors.New("online record changed concurrently")
}

租约 API 只接受非空相对 key,并始终写入当前 namespace 的 /config/ 前缀。expectedModRevision=0 表示仅当 key 不存在时创建;CAS 冲突返回 false, nil。调用方应在关闭前主动 revoke 自己创建的租约,再关闭 Discovery。

注意:

  • service_addr 必须是客户端和网关能访问到的地址,不一定等于本机监听地址。
  • 对故障摘除时延敏感时可显式设置 ttl: 5;框架默认仍为 10 秒。
  • 使用网关自动注册路由时,优先用 EnableEtcdRegistry,因为它会自动开启 reflection。
  • RegisterGRPCService 要在 Listen 或 Run 前调用。
  • ConfigureGRPCServer 必须在 RegisterGRPCService、GetGRPCServer 和 EnableEtcdRegistry 之前调用。
3. gRPC 客户端

内部服务调用优先使用 GrpcClient,它会通过 etcd resolver 按服务名连接后端实例。

app := core.New(core.LoadConfigFile("config.yaml"))

conn, err := app.GrpcClient("user-service")
if err != nil {
    panic(err)
}
defer conn.Close()

client := pb.NewUserServiceClient(conn)

当某个逻辑服务要求 TLS 时,在该服务首次 dial 前配置 transport credentials。Core 在配置时保存 credentials 快照,每次新建连接再使用副本;证书、CA 和 server name 语义仍由应用负责。

clientTLS := &tls.Config{
    MinVersion: tls.VersionTLS13,
    RootCAs:    rootPool,
    ServerName: "wallet.internal",
}
if err := app.ConfigureGRPCClient("wallet-service", core.GRPCClientConfig{
    TransportCredentials: credentials.NewTLS(clientTLS),
}); err != nil {
    return err
}

// 已有明确地址时不经过 etcd resolver。
conn, err := app.GrpcClientAt("wallet-service", "127.0.0.1:9001")

ConfigureGRPCClient 按逻辑服务名隔离,同一服务只允许配置一次,且必须早于 GrpcClient、MustGrpcClient 或 GrpcClientAt 的第一次调用。配置过 transport credentials 的服务不接受 GrpcClient(serviceName, opts...) 的额外不透明 dial options,以免同一连接出现两份 transport credentials;请把 transport 配置放入 GRPCClientConfig。未配置的服务继续使用原有 insecure 兼容路径。

如果依赖 GrpcClient 自动初始化 discovery,客户端读取 etcd.endpoints 和 etcd.dialTimeout;网关配置读取 etcd.dial_timeout。

如果启动阶段必须拿到连接,可以用 MustGrpcClient;它失败会 panic,适合 main 函数初始化,不适合请求处理链路。

conn := app.MustGrpcClient("user-service")
client := pb.NewUserServiceClient(conn)
4. 网关启动

网关服务只需要连接 etcd 并启用 gateway。启动时会读取已有服务实例,之后继续 watch 服务上下线和路由变化。业务服务需要使用 EnableEtcdRegistry 注册并开启 reflection,网关才能自动发现方法。

package main

import (
    "log"

    "github.com/xs23933/core/v3"
    "github.com/xs23933/core/v3/gateway"
)

func main() {
    app := core.New(core.LoadConfigFile("config.yaml"))

    if err := app.ConfigureGRPCClient("wallet-service", core.GRPCClientConfig{
        TransportCredentials: credentials.NewTLS(walletClientTLS),
    }); err != nil {
        log.Fatal(err)
    }

    if err := app.EnableEtcdDiscovery(nil); err != nil {
        log.Fatal("启用 etcd 服务发现失败:", err)
    }

    _, err := gateway.NewEtcdGateway(app)
    if err != nil {
        panic(err)
    }

app.Listen(":8080")
}

Gateway 的每个 ServicePool 使用 etcd 中的逻辑服务名选择 Core 客户端配置,因此可以只为一个 TLS 服务配置 credentials,而其他未迁移服务保持现有明文连接。配置必须早于 gateway.NewEtcdGateway(app)。

同一逻辑服务的多个 service_id 会参与轮询。GET/HEAD 遇到上游连接失败时,Gateway 最多改用另一个实例重试一次;写请求不会自动重放。gRPC 服务全部离线时,已自动生成的路由会保留并返回 503,实例恢复后继续使用原路由。

Gateway 首次请求优先选择 Ready 连接;没有 Ready 时只允许已核验方法的 Idle 连接由正常 RPC 唤醒,备用实例重试仍只选择 Ready,不选择 Connecting、TransientFailure 或 Shutdown。

实例删除、ready:false 或进程代次/地址替换时,Gateway 立即将旧实例移出调度并关闭新调用准入,已进入的 unary RPC 继续通过旧连接完成,最后一个调用返回后才关闭连接。排空不设置自动强杀期限;持有旧 proxy 引用的新调用返回 Unavailable。ReflectionProxy.Drain() 返回关闭完成通道,重复调用共享该通道;Close() 仍立即强制关闭,用于显式最终清理。HTTP 反代摘除同样只影响后续选择,不取消已代理请求。服务自身仍须停止新业务、调度和消息领取,并等待异步业务安全收尾后再触发进程关闭;此能力不替代业务幂等、结果恢复或 ShutdownWithTimeout 的最终超时边界。

当请求返回 service <name> unavailable 时,优先看 Gateway 日志中的 state={...} 诊断字段:

  • pool=missing 或 pool_instances=0:网关当前没有可用的 gRPC proxy 连接池。
  • discovery=disabled:网关没有启用 EnableEtcdDiscovery,无法 fallback 读取服务发现快照。
  • discovery_instances=0:fallback discovery 中也没有该服务实例,通常需要检查业务服务是否仍在 /<namespace>/services/<service_name>/ 下注册;未配置 namespace 时检查 /services/<service_name>/。
  • circuit_state=1:该服务 proxy 连续失败后进入熔断冷却期。

服务注册携带每进程唯一 generation,同 ID/地址重启也重新 reflection。每个期望实例保留一个恢复任务,连接/reflection 超时后以 0.5 秒递增、最多 5 秒的间隔重试,熔断冷却后继续尝试;删除、换代或关闭取消任务。Registry 丢租恢复通过 CAS 防旧代覆盖,正常退出先撤注册,异常退出由 TTL 摘除。滚动升级采用方法并集,RPC descriptor 冲突返回 503,写请求不自动重放。

GrpcClient("service-name") 的 resolver 每连接绑定 Discovery;相同配置复用,改变 namespace/endpoints/etcd 身份返回 ErrEtcdDiscoveryConfigurationChanged,应新建 Core 实例迁移。直接 etcd.NewRegistry 默认没有 ready 字段、兼容立即可服务。

ShutdownWithTimeout 使用独立 deadline,先撤注册,再同时排空 HTTP/HTTP3/gRPC,最后关闭业务依赖与 Discovery;超时强制关闭 transport。信号退出默认 10 秒,可配置 shutdown_timeout: "10s"。重复调用共享首个退出任务,后来短期限只停止该调用等待。无 context 的旧 shutdown hook 无法强制取消,后台清理需它自行返回,但不延长调用方期限。

网关内置本地管理接口,仅允许 loopback 地址访问:

方法 路径 说明
GET /admin/gateway/routes 路由列表
GET /admin/gateway/routes/:id 路由详情
POST /admin/gateway/routes 创建路由
PUT /admin/gateway/routes/:id 更新或禁用路由
DELETE /admin/gateway/routes/:id 删除路由
5. HTTP Handler 路由自动注册

HTTP 服务可以把框架自动生成的 Handler 路由发布到 etcd,Gateway 发现后直接反向代理到该服务。该能力默认关闭,只收集嵌入 core.Handler 并按方法名生成的路由;app.GET、app.POST 等手写路由不会自动发布。

HTTP 服务完整 main.go:

package main

import (
    "log"

    core "github.com/xs23933/core/v3"
)

type TaskHandler struct {
    core.Handler
}

func (h *TaskHandler) Init() {
    h.Prefix("/api/tasks")
}

func (h *TaskHandler) Get_id(c core.Ctx) error {
    return c.JSON(core.Map{"id": c.Params("id")})
}

func init() {
    // 这里只登记 Handler;此时不连接 etcd,也不发布 Gateway 路由。
    core.RegHandle(&TaskHandler{})
}

func main() {
    app := core.New(core.LoadConfigFile("config.yaml"))

    // 必须早于 Listen/Run:初始化 registry + discovery,并注册服务实例。
    if err := app.EnableEtcdRegistry(nil); err != nil {
        log.Fatal("enable etcd registry: ", err)
    }

    // 启动阶段加载 Handler、生成自动路由目录并写入 etcd。
    if err := app.Run(); err != nil {
        log.Fatal(err)
    }
}

开启自动发布时必须配置至少一个 include_prefixes。匹配按完整路径段判断,exclude_prefixes 优先排除:

gateway:
  auto_http_routes:
    enabled: true
    include_prefixes:
      - /api
    exclude_prefixes:
      - /api/internal

etcd:
  namespace: xpay
  endpoints:
    - 127.0.0.1:2379
  service_name: task-service
  service_addr: 127.0.0.1:8081
  # Gateway 可访问的 HTTP origin,必须包含 http:// 或 https://。
  http_addr: http://127.0.0.1:8081
  service_id: task-service-1
  ttl: 5

调用顺序必须是 core.New → EnableEtcdRegistry → Listen/Run。具体时机如下:

  1. Go init 阶段的 core.RegHandle 只登记 Handler 模块,不访问 etcd。
  2. EnableEtcdRegistry 创建 Registry,复用相同配置的 Discovery,以每进程唯一 generation 和 ready=false 注册。Gateway 暂不选用准备态实例。
  3. Listen / Run 启动准备阶段加载 Handler,方法名路由在这里生成并进入自动目录。
  4. Handler、gRPC 和 TLS 准备完成后,启用自动 HTTP 发布时先写入完整目录,随后 Registry 更新 ready=true;成功后 server 才进入 Serve。未开启自动 HTTP 发布也使用相同 readiness 顺序。

开启自动发布但未先成功调用 EnableEtcdRegistry,或者目录写入 etcd 失败,Listen / Run 会返回错误并清理已启动资源。框架不会启动周期发布 worker。HTTP 自动路由保持对外路径和上游路径一致,不做参数转换,path、query 和 body 由目标 HTTP 服务处理;不支持路径改写或静态 Header 注入。

Gateway 服务完整 main.go:

package main

import (
    "log"

    core "github.com/xs23933/core/v3"
    "github.com/xs23933/core/v3/gateway"
)

func main() {
    app := core.New(core.LoadConfigFile("config.yaml"))
    if err := app.EnableEtcdDiscovery(nil); err != nil {
        log.Fatal("enable etcd discovery: ", err)
    }
    gw, err := gateway.NewEtcdGateway(app)
    if err != nil {
        log.Fatal(err)
    }
    defer gw.Close()

    if err := app.Run(); err != nil {
        log.Fatal(err)
    }
}

Gateway 的 config.yaml 使用相同 namespace 和 endpoints,并监听 8080:

listen: 8080
etcd:
  namespace: xpay
  endpoints:
    - 127.0.0.1:2379

启动 etcd、HTTP 服务和 Gateway 后验证:

curl http://127.0.0.1:8080/api/tasks/123

请求会由 Gateway 转发到 etcd.http_addr 对应实例的 /api/tasks/123。

不希望自动发布时,可以显式批量注册:

if err := gateway.RegisterHTTPRoutes(app,
    &gateway.Route{Method: http.MethodGet, Path: "/api/tasks/:id"},
    &gateway.Route{Method: http.MethodPost, Path: "/api/tasks"},
); err != nil {
    return err
}

RegisterHTTPRoutes 会先校验完整批次,再逐条发布,不启动后台 worker;单条注册可使用 RegisterHTTPRoute。ServiceName 为空时使用最近一次成功的 etcd registry identity。相同 HTTP method 和规范化 path 的手动路由优先于自动路由。

6. gRPC 自动注册路由规则

网关通过 gRPC reflection 读取服务方法,并按方法名前缀自动生成 HTTP 路由。

只供内部服务调用的 gRPC 契约应通过完整 service 名排除,避免生成公共 HTTP 路由或与其它实例的同名契约冲突:

gateway:
  grpc_service_excludes:
    - payment.provider.v1.PaymentProviderService
    - game.provider.v1.GameProviderService

该配置不关闭 reflection,仅跳过指定 service 的 HTTP 自动路由。

gRPC 方法名 HTTP 方法 HTTP 路径示例
PostLogin POST /v1/auth/user/login
GetProfile GET /v1/auth/user/profile
PutProfile PUT /v1/auth/user/profile
DeleteSession DELETE /v1/auth/user/session
GetUserById GET /v1/auth/user/:id
GetOrderByUserId GET /v1/order/order/:user/id

转换逻辑:

  • proto package v1.auth 转为路径前缀 /v1/auth
  • service v1.auth.UserService 转为 /user
  • 方法前缀 Post/Get/Put/Delete 转为 HTTP method
  • 方法名剩余部分按 CamelCase 拆成路径
  • By 转为路径参数标记 :
  • 缩写建议使用 Id 而不是 ID,避免被拆成 /i/d

例如:

syntax = "proto3";

package v1.auth;

service UserService {
  rpc PostLogin(LoginRequest) returns (LoginResponse);
  rpc GetUserById(GetUserRequest) returns (User);
}

自动生成:

POST /v1/auth/user/login      -> /v1.auth.UserService/PostLogin
GET  /v1/auth/user/:id        -> /v1.auth.UserService/GetUserById

gRPC 自动路由采用当前已接入实例的方法并集:新增 RPC 仅选择支持实例,最后一个支持实例退出后移除该方法;全部离线时保留路由返回 503。同一 RPC 的输入/输出 descriptor(含嵌套消息与枚举)不一致时返回 503,协议一致后恢复。HTTP/manual 路由删除或禁用时撤下相应 source;manual 继续优先于 automatic。

7. 手动配置网关路由

除了自动注册,也可以通过管理接口写入路由配置。

POST http://127.0.0.1:8080/admin/gateway/routes
Content-Type: application/json

{
  "method": "POST",
  "path": "/api/login",
  "service_name": "user-service",
  "grpc_method": "/v1.auth.UserService/PostLogin",
  "description": "manual login route"
}

禁用路由:

PUT http://127.0.0.1:8080/admin/gateway/routes/{route_id}
Content-Type: application/json

{
  "method": "POST",
  "path": "/api/login",
  "service_name": "user-service",
  "grpc_method": "/v1.auth.UserService/PostLogin",
  "enabled": false
}
8. HTTP 到 gRPC 的请求映射

Gateway 的 gRPC 自动代理总期限由 gateway.grpc_request_timeout 配置(例如 180s),也可通过 gateway.Config.GRPCRequestTimeout 指定;默认及非正值保持 10s。此期限覆盖一次 RPC 及其允许的只读重试,短于它的入站 context deadline 仍优先生效。它与下游单次 HTTP timeout 不同,多步骤登录应为整个流程留出预算。配置在 Gateway 启动时读取,修改后需重建/重启;错误日志包含实际 elapsed 和配置 timeout。

网关会把 HTTP 路径参数、query 参数和 JSON body 合并为一个 JSON 对象,然后按 reflection 中的请求 message 反序列化。

GET /v1/auth/user/123?expand=true
Authorization: Bearer token
X-Request-Id: req-1

会转成类似:

{
  "id": "123",
  "expand": "true"
}

默认透传的 metadata:

  • authorization
  • x-request-id
  • x-user-id
  • Ctx.Vars() 中的本地变量 用于前置 middleware 处理后的后传参数 例如 jwt处理的: Ctx.Set("user_id", "123")

服务的 gRPC Handler 可以直接调用 Core helper,Gateway 自动将声明的响应 metadata 写入 HTTP Header,不需要专用登录 adapter:

func GrpcSetHeader(ctx context.Context, key string, values ...string) error
func GrpcSetCookie(ctx context.Context, name, value string, exp time.Time, path string, args ...any) error
func GrpcRemoveCookie(ctx context.Context, name, path string, dom ...string) error
func GrpcCookie(ctx context.Context, cookie *http.Cookie) error

上面列出的是 core 包导出签名。实际登录响应示例(token/expires 来自业务 Service):

if err := core.GrpcSetHeader(ctx, "Cache-Control", "no-store"); err != nil {
    return nil, err
}
if err := core.GrpcSetCookie(ctx, "session", token, expires, "", "httponly", true); err != nil {
    return nil, err
}
// 返回业务 proto response;浏览器通过 Set-Cookie 保存 token。

GrpcSetCookie 与 BaseCtx.SetCookie 使用同一套默认值和可变参数:

参数/属性 行为
空 path 默认 /
value url.QueryEscape 编码
SameSite 默认 http.SameSiteLaxMode
字符串 "httponly" 不区分大小写,启用 HttpOnly
其他字符串参数 设置 Domain;重复参数以后者为准
bool 参数 设置 Secure;重复参数以后者为准
未指定/空 Domain 读取当前服务 Core 的 domain 配置
未指定 HttpOnly/Secure 默认 false,登录场景显式传 "httponly", true
其他类型参数 与 BaseCtx 一样忽略

例如指定域名:core.GrpcSetCookie(ctx, "session", token, expires, "/", "example.com", "httponly", true)。GrpcRemoveCookie(ctx, "session", "/", "example.com") 使用过去的 Expires 删除;与 BaseCtx 一致,删除时空 path 不补 /,首个可选 Domain 生效,其为空时回退配置。Path/Domain 必须与写入时匹配。

需要 MaxAge、自定义 SameSite 或 host-only cookie 时用完整属性入口;它与 BaseCtx.Cookie 一样不补默认值、不编码 value:

if err := core.GrpcCookie(ctx, &http.Cookie{
    Name: "__Host-session", Value: token, Path: "/",
    HttpOnly: true, Secure: true, SameSite: http.SameSiteLaxMode,
    MaxAge: 3600,
}); err != nil {
    return nil, err
}

helper 校验非法 header/cookie 并返回错误,不静默丢弃。header 名只接受字母、数字、-_.,避免生成不合法的 gRPC metadata key;!、+ 等其他 HTTP token 符号不支持。必须使用当前 RPC context,并在 initial headers 发送前调用;Core 的 unary/stream interceptor 自动绑定当前应用配置,多个 Core 实例不会串用默认域名。自建 grpc.NewServer() 可使用 helper,但没有 Core 配置回退,需显式传 Domain 或完整 cookie。

响应协议固定为 core-http-<小写 header 名>-bin initial metadata,grpc-go 自动处理 wire 编码,value 不需手工 base64。GrpcSetHeader 的多值与重复调用都追加;Gateway 逐值追加 HTTP Header,多个 Set-Cookie 不合并。错误响应同样保留声明的 metadata,GET/HEAD 重试只使用最终尝试的响应。普通 metadata、trailer、非法值以及传输层 header(包括 Content-Type、Content-Length、Content-Encoding、Connection、TE、Trailer、Upgrade、Proxy-Authenticate、Proxy-Authorization 和 grpc-*)不桥接,JSON Content-Type 仍由 Gateway 管理。

原生客户端使用 grpc.Header(&md) 读取,例如 md.Get("core-http-set-cookie-bin");原生 gRPC 不会自动操作浏览器 cookie。现有 ReflectionProxy.Invoke 保持 JSON-only 签名,新增 InvokeWithHeaders 返回 (body, initialMetadata, error)。

业务 Service 负责认证和签发会话,gRPC Handler 负责 cookie;Gateway 认证中间件仍需读取并验证后续请求的 cookie。登录等免认证路径使用应用的认证中间件及 gateway/public_routes;该能力不改变认证策略。登录 cookie 使用 HTTPS,跨站调用的 CORS/credentials 与 CSRF 策略由应用配置。

可复制、可编译的登录/退出响应脚手架见 example/grpc-cookie。

9. Demo 目录

仓库内置了几个最小 demo:

目录 说明 运行命令
example/restful REST、模板、中间件、自动路由 go run ./example/restful
example/work 配置文件、数据库模型、分页查询 go run ./example/work
example/websocket WebSocket echo 示例 go run ./example/websocket

REST demo 中同时展示了手写路由和自动路由:

app.GET("/", func(c core.Ctx) {
    c.SendString("what happend")
})

type handler struct {
    core.Handler
}

func (handler) GetHello(c core.Ctx) {
    c.SendString("ok")
}

func (handler) GetUser_id(c core.Ctx) {
    c.SendString("id is %s", c.Params("id"))
}

func init() {
    core.RegHandle(&handler{})
}

生成的自动路由:

GET /hello
GET /user/:id

高级功能

1. 数据库事务
func CreateUserWithProfile(db *core.DB, user User, profile Profile) error {
    return db.Transaction(func(tx *core.DB) error {
        if err := tx.Create(&user).Error; err != nil {
            return err
        }

        profile.UserID = user.ID
        if err := tx.Create(&profile).Error; err != nil {
            return err
        }

        return nil
    })
}
2. 连接多个数据库
database:
  default:
    type: mysql
    dsn: user:pass@tcp(localhost:3306)/main
  log:
    type: clickhouse
    dsn: tcp://localhost:9000?database=logs
// 使用默认数据库
db := core.Conn()

// 使用指定数据库
logDB := core.Conn("log")
3. 查询构建器
// 链式查询
var users []User
err := core.Conn().
    Select("id, username, email").
    Where("age > ?", 18).
    Where("status = ?", "active").
    Order("created_at DESC").
    Limit(10).
    Offset(0).
    Find(&users).Error

// 原生 SQL
var count int
core.Conn().Raw("SELECT COUNT(*) FROM users WHERE age > ?", 18).Scan(&count)

// 子查询
subQuery := core.Conn().Model(&Order{}).Select("user_id").Where("amount > ?", 1000)
core.Conn().Where("id IN (?)", subQuery).Find(&users)
4. 分页查询:Finds、游标分页与兼容 API

Finds、FindPageBy 和 FindNextBy 都会读取 core.Map 中的分页和筛选参数,并可以接收一个已经拼好的 *core.DB 作为基础查询。

常用参数:

参数 说明
p 页码,默认 1
l 每页数量,默认 20
asc 升序字段,如 created_at
desc 降序字段,如 created_at
name 内置 name 模糊查询
field IN IN 查询,如 status IN: []int{}
field > 比较查询,支持 > < >= <=
field* 包含匹配,等价于 %value%
^field 前缀匹配,等价于 value%
field$ 后缀匹配,等价于 %value

三类入口的区别:

  • Finds:推荐用于新代码,通过 FindsParams 传递 Where、DB、Mode、Cursor 和 Extra。默认返回带 total 的经典分页;FindsModeCursor 使用真正的 keyset cursor,不执行 COUNT 或 OFFSET。
  • FindPageBy:返回 Page[T],包含 total 总数;适合后台管理、需要显示总页数的列表。代价是会执行 count。
  • FindNextBy:兼容旧代码的无 COUNT 页码 API,仍按 p 生成 OFFSET,不是真正的游标分页;新代码处理大列表时使用 FindsModeCursor。
Finds:推荐的新分页入口

共享 Where 对 Finds 全部模式、FindPage / FindPageBy、FindNext / FindNextBy 和 Find 统一校验输入:筛选字段仅接受 [A-Za-z_][A-Za-z0-9_]*,或一层 table.column,可以附加上表及 NOTIN、!= 等已支持的操作符。asc / desc / omitFields 必须为字符串,只接受逗号分隔的上述字段;空字符串表示不追加排序或排除字段。字段按数据库方言引用,筛选值继续绑定参数。

SQL 表达式、注释、引号、分号、非法字段和错误的排序参数类型会使整个查询返回 core.ErrInvalidQuery,不会静默丢弃条件或执行查询。直接调用 Where 时通过返回的 tx.Error 获取错误;其他列表接口通过 error 返回,可用 errors.Is(err, core.ErrInvalidQuery) 判断。游标模式仍忽略合法的 p / asc / desc,但会先拒绝非法排序输入。

兼容性:过去在 Map 中传入 asc: "id DESC"、函数排序或任意 SQL 筛选 key 的用法现在会被拒绝;请使用 desc: "id",或把固定、可信的复杂表达式放入 DAO 构造的 GORM scope。框架只校验 SQL 标识符语法;业务仍须限制允许筛选、排序和返回的字段,并独立施加租户和权限条件。不要将请求字符串传给 GORM 的原始 SQL API,也不要将不可信输入包装成 core.Expr。

func (dao *UsersViewDAO) List(ctx context.Context, whr *core.Map, next bool) (core.FindsResult[user.UsersView], error) {
    mode := core.FindsModePage
    if next {
        mode = core.FindsModeNext
    }

    if _, ok := (*whr)["asc"].(string); !ok {
        if _, ok := (*whr)["desc"].(string); !ok {
            (*whr)["desc"] = "created_at"
        }
    }

    tx := dao.db.WithContext(ctx).
        Model(&user.UsersView{}).
        Select("users_profiles.*, users.status").
        Joins("JOIN users ON users.id = users_profiles.user_id").
        Joins("JOIN users_identities ON users_profiles.user_id = users_identities.user_id")

    return core.Finds[user.UsersView](core.FindsParams{
        Where: whr,
        DB:    tx,
        Mode:  mode,
    })
}
FindsModeCursor:真正的 keyset cursor

游标模式只读取 Where 中的 l 和业务筛选条件,不读取 p、asc 或 desc。排序必须通过 CursorSpec 明确声明。字段仅允许安全的单段或一层限定标识符,例如 id、orders.created_at;使用一个唯一字段,或使用一个排序字段加一个唯一 tie-breaker:

func (dao *OrderDAO) List(ctx context.Context, whr *core.Map, token, direction string) (core.FindsResult[model.Order], error) {
    tx := dao.db.WithContext(ctx).Model(&model.Order{})
    return core.Finds[model.Order](core.FindsParams{
        Where: whr,
        DB:    tx,
        Mode:  core.FindsModeCursor,
        Cursor: &core.CursorSpec{
            Token:     token,
            Direction: core.CursorDirection(direction), // "next" 或 "prev";空值按 next
            Fields:    []string{"created_at", "id"},
            Desc:      true,
        },
    })
}

首次查询传空 token。后翻传上一响应的 next_cursor 和 next,前翻传 prev_cursor 和 prev。前翻查询会临时反转 SQL 排序并在返回前恢复规范顺序,因此调用方始终收到相同的 created_at DESC, id DESC 顺序。

{
  "p": 1,
  "l": 20,
  "next_cursor": "eyJ2IjoxLC4uLn0",
  "has_next": true,
  "has_prev": false,
  "data": []
}

实现使用 limit + 1 判断当前导航方向是否还有数据,不执行 COUNT 或 OFFSET。token 是版本化的 URL-safe opaque 值,并绑定字段和升降序;它不是签名或授权凭据。排序字段应为非空,最后一个字段必须唯一且具备索引。常用组合是 created_at,id 或单独的 id。

需要先合并多个数据源的列表可以复用相同 token 格式:

token, err := core.EncodeCursorToken([]string{"created_at", "id"}, true, row.CreatedAt, row.ID)
values, err := core.DecodeCursorToken(core.CursorSpec{
    Token: token, Fields: []string{"created_at", "id"}, Desc: true,
})

DecodeCursorToken 对版本、字段、排序和值数量进行校验,并以 json.Number 返回 JSON 数字,避免 64 位 ID 精度损失。聚合查询仍需自行实现各数据源的边界查询和 limit + 1 合并。

FindPageBy:带总数分页
type UsersViewDAO struct {
    db *core.DB
}

func (dao *UsersViewDAO) ListPage(ctx context.Context, whr *core.Map) (core.Page[user.UsersView], error) {
    if _, ok := (*whr)["asc"].(string); !ok {
        if _, ok := (*whr)["desc"].(string); !ok {
            (*whr)["desc"] = "created_at"
        }
    }

    tx := dao.db.WithContext(ctx).
        Model(&user.UsersView{}).
        Select("users_profiles.*, users.status").
        Joins("JOIN users ON users.id = users_profiles.user_id").
        Joins("JOIN users_identities ON users_profiles.user_id = users_identities.user_id")

    res := make([]user.UsersView, 0)
    return core.FindPageBy(whr, &res, tx)
}

返回结构:

{
  "p": 1,
  "l": 20,
  "total": 128,
  "data": []
}
FindNextBy:兼容的无 Count 页码分页

FindNextBy 会多查一条数据判断 next,并在返回前裁掉探针行。它仍使用 p/OFFSET,仅用于兼容现有调用方。

func (dao *UsersViewDAO) ListNext(ctx context.Context, whr *core.Map) (core.NextPage[user.UsersView], error) {
    if _, ok := (*whr)["asc"].(string); !ok {
        if _, ok := (*whr)["desc"].(string); !ok {
            (*whr)["desc"] = "created_at"
        }
    }

    tx := dao.db.WithContext(ctx).
        Model(&user.UsersView{}).
        Select("users_profiles.*, users.status").
        Joins("JOIN users ON users.id = users_profiles.user_id").
        Joins("JOIN users_identities ON users_profiles.user_id = users_identities.user_id")

    res := make([]user.UsersView, 0)
    return core.FindNextBy(whr, &res, tx)
}

返回结构:

{
  "p": 1,
  "l": 20,
  "next": true,
  "prev": false,
  "data": []
}
同一个 DAO 根据参数切换分页模式
func (dao *UsersViewDAO) List(ctx context.Context, whr *core.Map, page bool) (any, error) {
    _, asc := (*whr)["asc"].(string)
    _, desc := (*whr)["desc"].(string)
    if !asc && !desc {
        (*whr)["desc"] = "created_at"
    }
    if tp := whr.GetString("type"); tp != "" {
        (*whr)["type"] = constants.ParseLoginType(tp)
    }

    tx := dao.db.WithContext(ctx).
        Model(&user.UsersView{}).
        Select("users_profiles.*, users.status").
        Joins("JOIN users ON users.id = users_profiles.user_id").
        Joins("JOIN users_identities ON users_profiles.user_id = users_identities.user_id")

    res := make([]user.UsersView, 0)

    if page {
        return core.FindPageBy(whr, &res, tx)
    }

    return core.FindNextBy(whr, &res, tx)
}
5. 事件钩子
type User struct {
    core.Model
    Username string
    Password string
}

// 保存前钩子 具体可参照 gorm官方文档
func (u *User) BeforeSave(tx *core.DB) error {
    if u.Password != "" {
        hashed, err := bcrypt.GenerateFromPassword([]byte(u.Password), bcrypt.DefaultCost)
        if err != nil {
            return err
        }
        u.Password = string(hashed)
    }
    return nil
}

// 查询后钩子
func (u *User) AfterFind(tx *core.DB) error {
    u.Password = "" // 隐藏密码字段
    return nil
}

Redis Cache 通用包装器

cache 是独立子包,用于封装“先读缓存,未命中再查 DB,并自动回填缓存”的常见模式。

导入路径:

import "github.com/xs23933/core/v3/cache"

推荐为每类数据创建可复用 cache 实例,把 Redis 连接、前缀、TTL 和空值缓存策略集中配置一次。

type UserVO struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

var userCache = cache.New(
    core.RConn("cache"),
    cache.Prefix("user:"),
    cache.TTL(10*time.Minute),
    cache.EmptyTTL(time.Minute),
    cache.Jitter(30*time.Second),
    cache.CacheNil(true),
)

func GetUser(ctx context.Context, id string) (UserVO, error) {
    var user UserVO
    err := userCache.Take(ctx, id, &user, func(ctx context.Context) (any, error) {
        return dao.GetUserByID(ctx, id)
    })
    return user, err
}

同一个 cache 实例可以缓存不同类型,类型由 out 指针决定。

var order OrderVO
err := userCache.Take(ctx, "order:"+orderID, &order, func(ctx context.Context) (any, error) {
    return dao.GetOrderByID(ctx, orderID)
})

想保留返回值风格时,用包级泛型 helper。它不要求 New 绑定类型。

user, err := cache.Load[UserVO](userCache, ctx, "user:"+id, func(ctx context.Context) (UserVO, error) {
    return dao.GetUserByID(ctx, id)
})

user, err = cache.Get(ctx, "user:"+id, func(ctx context.Context) (UserVO, error) {
    return dao.GetUserByID(ctx, id)
})

空值缓存用于防止不存在的数据持续打到 DB。默认识别 cache.ErrNotFound,也可以接入项目自己的 not found 错误。

var userCache = cache.New(
    core.RConn("cache"),
    cache.Prefix("user:"),
    cache.CacheNil(true),
    cache.NotFound(func(err error) bool {
        return errors.Is(err, gorm.ErrRecordNotFound)
    }),
)

更新或删除数据后删除缓存:

if err := userCache.Delete(ctx, id); err != nil {
    return err
}

规则:

  • Take / Load 内部使用 singleflight 合并同进程并发 miss,避免缓存击穿。
  • Redis 读失败会降级执行 loader;写缓存失败不会影响返回结果。
  • TTL 可用 Jitter 增加随机抖动,避免大量 key 同时过期。
  • 不要在每次请求中重复 cache.New;应创建可复用实例。

Fetch API 客户端

可复用客户端使用 fetch.New(baseURL).Timeout(45 * time.Second).SetProxy(proxyURL) 配置每次请求预算,无需为超时构造 http.Client。非正值保持默认 30 秒,更短的父 context deadline 优先。Timeout 复制并原子替换客户端配置,保留代理、Cookie、重定向和其它设置;不修改调用方传入或已开始请求使用的客户端。

fetch 是独立子包,用于调用外部 HTTP API。设计接近前端 JavaScript fetch 的使用习惯,但保留 Go 的显式错误处理和结构体 decode。

导入路径:

import "github.com/xs23933/core/v3/fetch"
1. 最简调用

包级快捷方法使用 fetch.Default,适合一次性调用或简单脚本。

type UserVO struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

var user UserVO
res, err := fetch.Get("https://api.example.com/users/1", &user)
if err != nil {
    return err
}

token := res.Header.Get("X-Token")
_ = token

POST / PUT 带参数时,params 会按类型自动处理:

参数类型 处理方式
nil 不发送 body
[]byte 原始 body
string 字符串 body
其它类型 JSON body,并设置 Content-Type: application/json; charset=utf-8
var out UserVO

_, err := fetch.Post(
    "https://api.example.com/users",
    map[string]any{"name": "tom"},
    &out,
)

_, err = fetch.Put(
    "https://api.example.com/users/1",
    map[string]any{"name": "jerry"},
    &out,
)

_, err = fetch.Delete("https://api.example.com/users/1", nil)
2. 可复用 Client

业务服务中推荐创建可复用 client,统一配置 baseURL、公共 Header、Cookie 和 Hook。

var api = fetch.New("https://api.example.com").
    Header("X-App", "core-service").
    Header("Accept", "application/json").
    UseCookie(true)

func GetUser(ctx context.Context, id string) (UserVO, error) {
    var user UserVO

    res, err := api.DoGet(ctx, "/users/"+id, &user)
    if err != nil {
        return user, err
    }

    refreshedToken := res.Header.Get("X-Token")
    _ = refreshedToken

    return user, nil
}

公共 Header 和单次 Header 分开:

api := fetch.New("https://api.example.com").
    Header("X-App", "core-service") // 每次请求都有

var out UserVO
res, err := api.Post("/users").
    Header("X-Request-ID", "req-123"). // 只对本次请求生效
    JSON(map[string]any{"name": "tom"}).
    Result(context.Background(), &out)
3. 请求前 Hook:签名、鉴权、时间戳

Before 在请求发出前执行,可以读取最终 body 并修改 *http.Request。常用于 hash 签名、认证 Header、请求追踪。

api := fetch.New("https://api.example.com").
    Before(func(ctx context.Context, req *http.Request, body []byte) error {
        sign := core.SHA256HashBytes(body)
        req.Header.Set("X-Sign", sign)
        req.Header.Set("X-Timestamp", strconv.FormatInt(time.Now().Unix(), 10))
        return nil
    })

var out UserVO
_, err := api.DoPost(context.Background(), "/users", map[string]any{"name": "tom"}, &out)
4. 响应后 Hook:解包、解密、统一 decode

After 在响应 body 读取完成后执行,返回值会作为最终 body 继续 decode。适合统一响应格式解包。

type Envelope struct {
    Code int             `json:"code"`
    Msg  string          `json:"msg"`
    Data json.RawMessage `json:"data"`
}

api := fetch.New("https://api.example.com").
    After(func(ctx context.Context, resp *http.Response, body []byte) ([]byte, error) {
        var env Envelope
        if err := json.Unmarshal(body, &env); err != nil {
            return nil, err
        }
        if env.Code != 0 {
            return nil, fmt.Errorf("api error %d: %s", env.Code, env.Msg)
        }
        return env.Data, nil
    })

var user UserVO
_, err := api.DoGet(context.Background(), "/users/1", &user)
5. 获取响应 Header、Status、Body

使用 Result 或 DoGet/DoPost/DoPut/DoDelete 会返回 *fetch.FetchResult。

res, err := api.Get("/session").Result(context.Background(), &out)
if err != nil {
    if ferr, ok := err.(*fetch.FetchError); ok {
        retryToken := ferr.Header.Get("X-Token")
        body := string(ferr.Body)
        _ = retryToken
        _ = body
    }
    return err
}

token := res.Header.Get("X-Token")
status := res.StatusCode
body := res.Body

只需要响应结果,不需要 decode 到 out 时可以省略第二个参数:

res, err := api.Get("/session").Result(context.Background())
if err != nil {
    return err
}

token := res.Header.Get("X-Token")
rawBody := res.Body
6. 调试请求和响应

排查外部 API 问题时,可以显式开启 Debug(true)。每次请求结束时会打印方法、URL、最终请求 Header、请求 body、响应状态、响应 Header、响应 body 和错误信息。响应 body 如果是 Content-Encoding: gzip 会先解压再输出。

api := fetch.New("https://api.example.com").
    Header("X-App", "core-service").
    Debug(true)

var out UserVO
_, err := api.Post("/users").
    Header("X-Request-ID", "req-123").
    JSON(map[string]any{"name": "tom"}).
    Result(context.Background(), &out)

调试日志会包含请求和响应 body,生产环境只应在定位问题时短期开启。

7. HTTP/SOCKS5 代理

SetProxy 支持 HTTP 和 SOCKS5 代理,账号密码会从代理 URL 中解析:

api := fetch.New("https://api.example.com").
    SetProxy("http://127.0.0.1:7890")

api.SetProxy("socks5://127.0.0.1:1080")
api.SetProxy("http://user:password@127.0.0.1:7890")
api.SetProxy("socks5://user:password@127.0.0.1:1080")

传入空字符串会关闭代理:

api.SetProxy("")

默认不保存 Cookie,避免隐式状态。需要模拟浏览器会话时显式启用:

api := fetch.New("https://api.example.com").UseCookie(true)

// 禁用并清空 cookie jar
api.UseCookie(false)

错误处理

自定义错误处理
// 全局错误处理
app.ErrorHandler = func(c core.Ctx, err error) {
    if e, ok := err.(*core.HTTPError); ok {
        c.SendStatus(e.Code, e.Message)
        return
    }

    // 记录错误日志
    core.Erro("请求处理失败: %v", err)

    // 生产环境隐藏详细错误
    if app.Debug {
        c.SendStatus(500, err.Error())
    } else {
        c.SendStatus(500, "Internal Server Error")
    }
}

// 业务错误
func (Handler) GetUser(c core.Ctx) {
    user, err := models.GetUserByID(id)
    if err != nil {
        if errors.Is(err, gorm.ErrRecordNotFound) {
            c.SendStatus(404, "用户不存在")
            return
        }
        c.SendStatus(500, "服务器错误")
        return
    }
    c.ToJSON(user)
}

性能优化

1. 连接池配置
database:
  type: mysql
  dsn: user:pass@tcp(localhost:3306)/dbname
  pool:
    max_idle: 10 # 最大空闲连接数
    max_open: 100 # 最大打开连接数
    max_lifetime: 1h # 连接最大生命周期
2. 启用 Prefork 模式
prefork: true # 启用多进程模式,充分利用多核CPU

测试

GitHub Actions 的 CI 工作流 在 push、Pull Request 或手动触发时运行, 从 go.mod 读取 Go 版本并缓存依赖,执行 go mod verify、go vet ./...、 go test ./... -count=1 -timeout=10m 和 go build ./...。 测试默认不要求外部服务;需要独立 etcd 可执行文件的工作负载集成测试在未安装时会跳过。

CI 还调用 bash scripts/stress.sh 运行并发压力测试;本地可使用同一命令。 脚本对根包、WebSocket 和 metrics 的并发、压力及关闭回归启用 race 检测, 在 GOMAXPROCS=1,4 下各重复 5 次并随机排列测试顺序,每个测试包限时 10 分钟。 HTTP 请求隔离压力测试每轮通过 32 个并发 worker 发出共 3200 次请求并校验路径参数和 query, 用于发现请求上下文串扰;该检查不设置依赖机器性能的吞吐阈值。

单元测试
package handler_test

import (
    "testing"
    "github.com/xs23933/core/v3"
)

func TestUserHandler(t *testing.T) {
    app := core.New()

    // 模拟请求
    req := core.TestRequest{
        Method: "GET",
        Path:   "/users/1",
    }

    resp := app.Test(req)

    if resp.StatusCode != 200 {
        t.Errorf("期望状态码 200,得到 %d", resp.StatusCode)
    }
}
集成测试
@baseURL = http://localhost:8080
@contentType = application/json

### 创建用户
POST {{baseURL}}/users
Content-Type: {{contentType}}

{
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123"
}

### 获取用户
GET {{baseURL}}/users/1

### 获取用户列表
GET {{baseURL}}/users?page=1&size=10

部署

1. 编译
go build -o app ./cmd
2. 使用 Systemd
# /etc/systemd/system/myapp.service
[Unit]
Description=My Core Application
After=network.target

[Service]
Type=simple
User=appuser
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/app
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
3. 使用 Docker
FROM golang:1.25-alpine AS builder
RUN apk add --no-cache build-base

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o app ./cmd

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/app .
COPY --from=builder /app/config.yaml .
EXPOSE 8080
CMD ["./app"]

常见问题

1. 路由不生效

问题: 处理器方法已定义,但路由不生效。

解决方案:

  • 确保处理器嵌入了 core.Handler
  • 确保在 init() 函数中调用 core.RegHandle()
  • 检查方法名是否符合路由规则
  • 查看日志确认路由注册情况
2. 数据库连接失败

问题: 数据库连接失败,返回错误。

解决方案:

  • 检查 config.yaml 中的数据库配置
  • 确认数据库服务是否运行
  • 检查连接字符串格式是否正确
  • 查看数据库日志获取详细错误信息
3. 跨域问题

问题: 前端请求被浏览器阻止,提示跨域错误。

解决方案:

  • 启用 CORS 中间件
  • 配置正确的 CORS 选项
import "github.com/xs23933/core/v3/middleware/cors"

app.Use(cors.New(cors.Config{
    AllowOrigins:     "http://localhost:3000",
    AllowMethods:     "GET,POST,PUT,DELETE,OPTIONS",
    AllowHeaders:     "Content-Type,Authorization",
    AllowCredentials: true,
}))

cors.New 只构造中间件;框架会让未匹配到显式路由的 OPTIONS 请求经过全局中间件,因此无需另外注册预检路由。精确 Origin 包含 scheme 和显式端口;*.example.com 只匹配真实子域,https://*.example.com:8443 还会限制 scheme 与端口。AllowHeaders 为空时会回显浏览器请求的 headers。安全起见,AllowOrigins: "*" 不能与 AllowCredentials: true 同时使用。

旧调用 cors.New(app, config...) 应迁移为 cors.New(config...);过渡期可使用已废弃的 cors.NewWithApp(app, config...)。

4. 文件上传大小限制

问题: 上传大文件时失败。

解决方案:

  • 调整最大文件大小限制
app := core.New(core.Options{
    "max_body_size": "10MB", // 10MB 限制
})

API 参考

核心方法
Ctx 接口主要方法
方法 说明 示例
Params(key) 获取路径参数 c.Params("id")
Query(key) 获取查询参数 c.Query("name")
FormValue(key) 获取表单值 c.FormValue("email")
ReadBody(out) 读取请求体 c.ReadBody(&user)
Validate(out) 验证结构体 c.Validate(&form)
ToJSON(data, err) 返回 JSON 响应 c.ToJSON(user, nil)
JSON(data) 返回 JSON 响应 c.JSON(user)
Type(ty) 设置响应类型 c.Type("json")
Send(msg) 发送[]byte c.Send([]byte( "Not Found"))
SendString(msg) 发送状String c.SendString("Not Found")
SendStatus(code, msg) 发送状态码 c.SendStatus(404, "Not Found")
SetHeader(key, value) 设置响应头 c.SetHeader("Content-Type", "application/json")
GetHeader(key) 获取请求头 c.GetHeader("Authorization")
FormFile(key) 获取上传文件 c.FormFile("file")
SaveFile(key, dst) 保存上传文件 c.SaveFile("file", "./uploads")
数据库操作
方法 说明 示例
core.DB gorm.DB别名 db *core.DB
core.Conn(name) 获取指定数据库连接 core.Conn("log")
core.Transaction(fn) 执行事务 core.Transaction(func(tx) { ... })
core.Find(out) 查询数据 core.Find(&users)
core.First(out, where) 查询单条数据 core.First(&user, "id = ?", id)
配置选项

设置 case-sensitive: false 可让 HTTP 路由的 ASCII 静态路径忽略大小写,例如 /transferIn 和 /transferin 访问同一接口;未配置或设置为 true 时保留大小写敏感行为。此配置在 core.New 时读取,自动 Handler、显式路由、Group、路径中间件和 RemoveHandle 使用相同规则。参数名、参数值、query、c.Path() 和原始 URL 保留大小写;非 ASCII 路径仍精确匹配。开启后仅静态路径大小写不同的同方法路由视为同一路由,后注册的 handler 覆盖前者。

选项 类型 默认值 说明
debug bool false 调试模式
case-sensitive bool true HTTP 静态路径是否区分 ASCII 大小写
listen string ":8080" 监听地址
network string "tcp4" 网络协议
prefork bool false 是否启用 prefork
max_body_size string "1MB" 最大请求体大小
read_timeout string "5s" 读取超时
write_timeout string "10s" 写入超时
trusted_proxies []string [] c.RemoteIP() 可信代理 IP/CIDR;空列表默认私网/回环,非空覆盖默认规则;非法配置初始化报错

最佳实践

1. 项目组织

使用 统一项目架构,不要在 main、Handler 构造器和 DAO 构造器分散装配。Service 使用标准 context,HTTP 传 c.Ctx(),gRPC 传 RPC context; 由协议层映射业务错误,事务在 Service 开启,迁移显式执行。 已有项目按文档迁移并保持接口、表名与启动参数兼容,不由生成器自动搬迁。

2. 错误处理
// 定义业务错误
var (
    ErrUserNotFound = errors.New("用户不存在")
    ErrInvalidToken = errors.New("无效的令牌")
)

// 统一错误响应
func ErrorResponse(c core.Ctx, err error) {
    switch err {
    case ErrUserNotFound:
        c.SendStatus(404, err.Error())
    case ErrInvalidToken:
        c.SendStatus(401, err.Error())
    case gorm.ErrRecordNotFound:
        c.SendStatus(404, "记录不存在")
    default:
        core.Erro("未处理的错误: %v", err)
        c.SendStatus(500, "服务器内部错误")
    }
}

// 使用示例
func (Handler) GetUser(c core.Ctx) {
    user, err := services.GetUserByID(id)
    if err != nil {
        ErrorResponse(c, err)
        return
    }
    c.ToJSON(user)
}
3. 日志记录
// 方式一:始终输出请求日志。
// core.New() 默认不输出,需要时显式启用。
app.Use(core.Logger())

// 方式二:按 debug 配置控制或自定义输出。
// 与上面的裸 Logger() 二选一,不要同时注册。
app.Use(core.Logger(core.LoggerConfig{
	App:    app,
	Debug:  app.Debug,
	Output: os.Stdout,
}))

// 自定义日志级别
core.Info("用户登录成功: %s", username)
core.Warn("API 调用频繁: %s", ip)
core.Erro("数据库连接失败: %v", err)
core.D("请求参数: %v", params)

core.New() 默认注册的 Recovery 会捕获普通 panic、记录堆栈并返回 500。对于 net/http.ErrAbortHandler(包括包装后的同一错误),Recovery 会按标准库语义静默终止当前请求,不记录 panic、不调用自定义 recovery handler,也不再尝试写入 500;这适用于反向代理或 SSE 客户端已断开连接的场景。

日志轮转

框架内置日志文件轮转,配置文件方式:

log: /var/log/myapp/app.log
log_rotate:
  - size: 300M
  - daily
  - rotate: 30
  - compress
  - delaycompress: 24h
  - missingok
  - notifempty
  - copytruncate

只要配置了 log 且 log_rotate 未配置、为 null、空字符串或空数组,框架会自动套用上面的默认轮转配置。

参数说明:

参数 含义
size: 300M 日志文件达到指定大小后切割,支持 K/KB/M/MB/G/GB,也支持纯数字字节数
daily 按天切割,跨日期后第一次写入会创建新的日志文件
rotate: 30 保留最近 30 天的切割日志,超过期限自动删除
compress 切割后的日志文件压缩为 .gz
delaycompress 延迟压缩切割日志,默认延迟 24h,需配合 compress
delaycompress: 2h 指定延迟压缩时长,支持 Go duration 格式,如 30m、2h、24h
missingok 日志文件不存在时继续运行并重新创建,不返回错误
notifempty 当前日志文件为空时不切割、不压缩、不生成空的轮转文件
copytruncate 切割时复制当前日志再截断原文件,适合不希望替换文件句柄的部署方式

调用 RotatingLogWriter.RedirectStdout 后,框架会强制使用 copy-truncate 语义,即使配置中没有显式写 copytruncate。这是为了在并发 fmt.Print* 时保持 os.Stdout 指针和文件描述符稳定,避免轮转过程替换进程级全局指针产生数据竞争;未重定向 stdout 的 writer 仍按配置选择 rename 或 copy-truncate。

代码方式:

w, err := core.NewRotatingLogWriter(
    "/var/log/myapp/app.log",
    "size: 300M",
    "daily",
    "rotate: 30",
    "compress",
    "delaycompress: 24h",
    "missingok",
    "notifempty",
    "copytruncate",
)
if err != nil {
    panic(err)
}
defer w.Close()

app.Use(core.Logger(core.LoggerConfig{
    App:    app,
    Debug:  app.Debug,
    Output: w,
}))
4. 性能监控
import (
    "time"

    "github.com/xs23933/core/v3/middleware/metrics"
    "github.com/xs23933/core/v3/middleware/ratelimit"
)

// 启用指标收集
m, mw := metrics.New()
app.Use(mw)
metrics.Mount(app, "/metrics", m)

// 启用限流(默认内存)
app.Use(ratelimit.New(ratelimit.Config{
    Max:    300,
    Window: time.Minute,
}))

// 更平滑的用户级限流
app.Use(ratelimit.New(ratelimit.Config{
    Max:       120,
    Window:    time.Minute,
    Algorithm: ratelimit.SlidingWindow,
    KeyFunc: func(c core.Ctx) string {
        return c.GetString("user_id", c.RemoteIP().String())
    },
}))

扩展开发

1. 开发自定义中间件
package middleware

import (
    "time"

    "github.com/xs23933/core/v3"
)

func AccessLog() core.HandlerFunc {
    return func(c core.Ctx) error {
        start := time.Now()
        err := c.Next()
        core.Info("%s %s status=%d cost=%s",
            c.Method(), c.Path(), c.GetStatus(), time.Since(start))
        return err
    }
}
2. 开发插件
package plugin

import "github.com/xs23933/core/v3"

type Plugin struct {
    core.Handler
    config map[string]any
}

func New(config map[string]any) *Plugin {
    return &Plugin{
        config: config,
    }
}

func (p *Plugin) Install(app *core.Core) {
    // 注册路由
    app.Get("/plugin/status", p.Status)

    // 注册中间件
    app.Use(p.Middleware)

    // 初始化资源
    p.Init()
}

func (p *Plugin) Status(c core.Ctx) {
    c.ToJSON(map[string]any{
        "name":    p.config["name"],
        "version": p.config["version"],
        "status":  "running",
    })
}

func (p *Plugin) Middleware(c core.Ctx) error {
    // 插件中间件逻辑
    c.Set("plugin_data", p.config)
    return c.Next()
}

func (p *Plugin) Init() {
    // 初始化逻辑
    core.Info("插件 %s 已初始化", p.config["name"])
}

Core/V3 框架路由自动注册规范

本文档描述 github.com/xs23933/core/v3 框架的路由自动注册机制。


一、命名约定

1.1 Handler 结构体
type UserHandler struct {
    core.Handler  // 必须嵌入 core.Handler
    // ... 依赖字段
}
  • Handler 结构体名以 Handler 结尾
  • 框架自动注册时会去掉 Handler 后缀作为路由组名
  • 例:UserHandler → 路由组前缀为 /user(可通过 Init() 覆盖)
1.2 方法命名规则

HTTP 方法前缀 + 路径片段(驼峰命名):

方法名前缀 HTTP 方法
Get GET
Post POST
Put PUT
Delete DELETE
Patch PATCH
All ALL

二、路径转换规则(核心)

2.1 基本规则
字符特征 转换结果 示例
大写字母开头 路径片段 /xxx Profile → /profile
下划线 + 小写字母 路径参数 :xxx _id → :id
Param(固定关键字) 路径参数 :param Param → :param
Params(固定关键字) 可选参数 :param? Params → :param?
2.2 大写字母 = 路径分隔

每个大写字母开头的片段都会生成一个新的路径层级:

// 方法名 → 路由
func (h *Handler) GetProfile(c core.Ctx) error {}
// GET /profile

func (h *Handler) GetCurrentUser(c core.Ctx) error {}
// GET /current/user

func (h *Handler) GetId(c core.Ctx) error {}
// GET /id  (Id 是路径片段,不是参数!)
2.3 下划线 = 自定义路径参数

下划线开头 + 小写字母 = 自定义路径参数名:

// 方法名 → 路由
func (h *Handler) GetByID(c core.Ctx) error {}
// GET /:id

func (h *Handler) GetByUserid(c core.Ctx) error {}
// GET /:userid

func (h *Handler) GetByIDProfile(c core.Ctx) error {}
// GET /:id/profile
2.4 固定关键字 Param / Params

Param 和 Params 是框架固定关键字:

// 方法名 → 路由
func (h *Handler) GetParam(c core.Ctx) error {}
// GET /:param  (必选参数)

func (h *Handler) GetParams(c core.Ctx) error {}
// GET /:param?  (可选参数)

func (h *Handler) GetParam_Callback(c core.Ctx) error {}
// GET /:param/callback

func (h *Handler) GetParams_Detail(c core.Ctx) error {}
// GET /:param?/detail

⚠️ 关键区别:

  • Param → :param(必选)
  • Params → :param?(可选)
  • 参数名固定为 param,通过 c.Params("param") 获取

三、参数获取

3.1 固定关键字参数
// 路由: GET /:param
func (h *Handler) GetParam(c core.Ctx) error {
    val := c.Params("param")  // 参数名固定为 "param"
    // ...
}

// 路由: GET /:param/callback
func (h *Handler) GetParam_Callback(c core.Ctx) error {
    provider := c.Params("param")  // 同样是 "param"
    // ...
}
3.2 自定义参数名
// 路由: GET /:id
func (h *Handler) GetByID(c core.Ctx) error {
    id := c.Params("id")  // 参数名为 "id"
    // ...
}

// 路由: GET /:userid/profile
func (h *Handler) GetByUseridProfile(c core.Ctx) error {
    userId := c.Params("userId")  // 参数名为 "userId"
    // ...
}

四、路由前缀设置

4.1 默认前缀

框架根据 Handler 名称自动推断前缀:

type UserHandler struct { core.Handler }
// 默认前缀: /user

type OAuthHandler struct { core.Handler }
// 默认前缀: /oauth
4.2 自定义前缀

在 Init() 方法中使用 Prefix() 设置:

func (h *OAuthHandler) Init() {
    h.Prefix("/api/v1/oauth")
}

五、完整示例

5.1 OAuth Handler 示例
type OAuthHandler struct {
    core.Handler
    oauthService *OAuthService
}

func (h *OAuthHandler) Init() {
    h.Prefix("/api/v1/oauth")
}

// GET /api/v1/oauth/:param
func (h *OAuthHandler) GetParam(c core.Ctx) error {
    provider := c.Params("param") // google, facebook, twitter, github
    // ...
}

// GET /api/v1/oauth/:param/callback
func (h *OAuthHandler) GetParam_Callback(c core.Ctx) error {
    provider := c.Params("param")
    // ...
}

生成的路由:

GET /api/v1/oauth/:param           → OAuthHandler.GetParam
GET /api/v1/oauth/:param/callback  → OAuthHandler.GetParam_Callback

访问示例:

URL 匹配路由 param 值
GET /api/v1/oauth/google GetParam "google"
GET /api/v1/oauth/facebook/callback GetParam_Callback "facebook"
GET /api/v1/oauth 404 必选参数缺失
5.2 User Handler 示例
type UserHandler struct {
    core.Handler
}

func (h *UserHandler) Init() {
    h.Prefix("/api/v1/users")
}

// GET /api/v1/users
func (h *UserHandler) Get(c core.Ctx) error {}

// GET /api/v1/users/:id
func (h *UserHandler) GetByID(c core.Ctx) error {
    id := c.Params("id")
}

// GET /api/v1/users/:id/profile
func (h *UserHandler) GetByID_Profile(c core.Ctx) error {
    id := c.Params("id")
}

// GET /api/v1/users/current
func (h *UserHandler) GetCurrent(c core.Ctx) error {}

// POST /api/v1/users
func (h *UserHandler) Post(c core.Ctx) error {}

// PUT /api/v1/users/:id
func (h *UserHandler) Put_id(c core.Ctx) error {}

// DELETE /api/v1/users/:id
func (h *UserHandler) Delete_id(c core.Ctx) error {}

六、命名转换规则(ToNamer)

框架内部使用 ToNamer 函数进行命名转换:

转换逻辑:

  1. 提取 HTTP 方法前缀(Get/Post/Put/Delete/Patch)
  2. 遍历剩余字符:
    • 大写字母 → 新路径片段(转小写)
    • _ + 小写字母 → 自定义路径参数
    • Param(关键字)→ :param
    • Params(关键字)→ :param?

转换示例:

方法名 解析过程 最终路由
GetProfile Profile → /profile GET /profile
GetCurrentUser Current + User → /current/user GET /current/user
GetByID ByID → /:id GET /:id
Get_userId _userId → /:userId GET /:userId
GetByID_Profile _id + Profile → /:id/profile GET /:id/profile
GetParam Param → /:param GET /:param
GetParam_Callback Param + Callback → /:param/callback GET /:param/callback
GetParams Params → /:param? GET /:param?
GetParams_Detail Params + Detail → /:param?/detail GET /:param?/detail
GetId Id → /id GET /id(不是参数!)
PostLogin Login → /login POST /login

七、常见错误

7.1 混淆大写和下划线
// ❌ 错误:期望 /:id,实际得到 /id
func (h *Handler) GetId(c core.Ctx) error {}
// GET /id  (Id 是路径片段,不是参数)

// ✅ 正确:使用下划线定义参数
func (h *Handler) GetByID(c core.Ctx) error {}
// GET /:id
7.2 混淆 Param 和 Params
// ❌ 错误:期望可选参数,实际是必选
func (h *Handler) GetParam(c core.Ctx) error {}
// GET /:param  (必选)

// ✅ 正确:使用 Params 表示可选
func (h *Handler) GetParams(c core.Ctx) error {}
// GET /:param?  (可选)
7.3 Param 与自定义参数混用
// ⚠️ 注意:Param 固定参数名为 "param"
func (h *Handler) GetParam(c core.Ctx) error {}
// GET /:param,用 c.Params("param") 获取

// 自定义参数名用下划线
func (h *Handler) GetByID(c core.Ctx) error {}
// GET /:id,用 c.Params("id") 获取

八、调试技巧

8.1 查看注册的路由

框架启动时会打印所有注册的路由:

[DBUG] AutoRoute handler.UserHandler
[DBUG] route: GET /profile > handler.UserHandler.GetProfile
[DBUG] route: POST /login > handler.AuthHandler.PostLogin
[DBUG] route: GET /api/v1/oauth/:param > handler.OAuthHandler.GetParam
8.2 常见问题排查
问题 原因 解决方案
404 路由不匹配 参数必选但未提供 使用 Params 改为可选,或确保 URL 包含参数
参数值为空 使用 Params 但未传参 检查是否应该用 Param 改为必选
路由不是参数 用了大写开头(如 Id) 改用下划线开头(如 _id)
路由冲突 多个方法映射到同一路径 检查方法命名是否重复

九、快速参考卡

┌─────────────────────────────────────────────────────────────┐
│  命名规则                                                    │
├─────────────────────────────────────────────────────────────┤
│  大写字母开头    → 路径片段 /xxx                              │
│  _xxx(下划线)  → 自定义路径参数 :xxx                        │
│  Param(关键字) → 路径参数 :param(必选)                    │
│  Params(关键字)→ 路径参数 :param?(可选)                   │
├─────────────────────────────────────────────────────────────┤
│  方法名               →  路由                               │
├─────────────────────────────────────────────────────────────┤
│  Get                  →  GET /                              │
│  GetProfile           →  GET /profile                       │
│  GetCurrent           →  GET /current                       │
│  GetCurrentProfile    →  GET /current/profile               │
│  GetByID              →  GET /:id       (自定义参数)          │
│  GetUserid            →  GET /:userid   (自定义参数)         │
│  GetByID_Profile      →  GET /:id/profile                   │
│  GetParam             →  GET /:param     (必选关键字)        │
│  GetParam_Callback    →  GET /:param/callback               │
│  GetParams            →  GET /:param?    (可选关键字)        │
│  GetParams_Detail     →  GET /:param?/detail                │
│  GetId                →  GET /id       (不是参数!)          │
│  Post                 →  POST /                             │
│  PostLogin            →  POST /login                        │
│  PutID                →  PUT /:id                           │
│  DeleteID             →  DELETE /:id                        │
└─────────────────────────────────────────────────────────────┘

参数获取:
  - 关键字参数: c.Params("param")
  - 自定义参数: c.Params("id"), c.Params("userId") 等

本地模型与按需上下文

从 AGENTS.md 和 AI_CONTEXT.md 开始,按 skills 索引 选择任务资料。 8k HTTP 任务可直接注入 Handler 包,不用重复加载完整文档; 预算、生成及验证方法见 context/README.md。 完整总览、Handler 参考 与 Ctx 参考 保留按需查阅。框架 API 与运行行为不因本次文档整理改变。

版本历史

v3.1.73
  • 精简 AGENTS/AI_CONTEXT,Handler/Ctx 采用统一的任务、规则、示例、边界和验证结构,保留完整参考。
  • 提供从规则和真实 Handler 源码生成的离线 8k 任务包、预算说明及 CI 漂移检查;未进行本地模型效果评测。
  • 包含 v3.1.72 后已合入的 Gateway protobuf repeated query 解析修正(含数量边界)。
v3.1.72
  • 统一下游项目的 cmd/main.go → internal/app 装配与 handler/grpc → services → dao → models 分层,新增可运行标准样例及真实生成验收。
  • corectl 项目模板拆分为嵌入文件,补齐参数/版本校验、目录独占创建、显式迁移、gRPC protobuf 工具和注册顺序。
  • 新增 corectl gen enums [目录] 与 --check,扫描 *_enums.yaml/enums.yaml 并原地生成,检查包名、符号冲突、输出归属和 Go 特殊文件名,保护手写文件。
  • 保留 coregen 单文件入口;枚举配置校验更严格,旧无 Source 标记产物切换扫描模式前需人工确认并移除。持久化 iota 值只追加、不重排。
  • 脚手架默认依赖基线仍为已验证的 Core v3.1.71;本次生成器与枚举扫描能力通过 v3.1.72 分发。
v3.1.57
  • 修复 HTTP 路由树未应用 case-sensitive: false 的问题,支持 /transferIn 与 /transferin 兼容;默认保持大小写敏感。
  • 保留参数名、参数值、query 和原始 URL,统一注册、中间件、Group 及移除行为,并补充回归测试。
  • 完善 WebSocket 可运行示例,修正队列释放测试命名。
v3.1.0
  • 支持 Go 1.24
  • 性能优化,提升 30% 吞吐量
  • 新增 WebSocket 支持
  • 改进中间件系统
  • 增强数据库支持
v2.0
  • 引入自动路由注册
  • 支持多数据库连接
  • 改进错误处理机制
  • 新增文件上传功能
v1.0
  • 初始版本发布
  • 基础路由功能
  • 数据库集成
  • 中间件支持

社区支持

贡献指南

欢迎贡献代码!请遵循以下步骤:

  1. Fork 项目仓库
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add some amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 创建 Pull Request

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。


文档最后更新: 2026-03-31 Core Framework v3.0.0

托管工作负载 mTLS

通过 core.LoadConfigFile 加载 YAML 或加密 .dat 时,workload.state_dir、trust_bundle_file、bootstrap_token_file 以及 workload_issuer.state_dir、policy_file、pin_file 的非空相对路径,在环境变量展开后按该配置文件所在目录解析。state_dir: ./workload 因而始终位于配置旁,不随启动 cwd 或 -f/--config 的绝对、相对写法变化。绝对路径保持原值;直接以程序构造 Options 或调用 workload.Open 时,仍由调用方确定路径基准。其它业务配置路径不受此规则影响。

Gateway 可使用 Go 标准库首次自动创建私有 CA,后端自动申请、本地保存和续期,服务端、服务间客户端和 Gateway reflection 复用本进程身份。使用前必须在首次创建 gRPC server/client 前调用 app.EnableWorkloadIdentity();启用后禁止明文回退或逐目标显式 transport 冲突配置。完整配置、引导认证、独立端口、根信任更新和验收边界见 工作负载身份说明。

后端跨服务器可预置 workload.root_sha256(根证书 DER SHA-256),Core 从内部签发入口 GET /root.pem 无凭据下载,校验指纹及本次 HTTPS 链/主机名后原子缓存,再申请身份。每次启动校验缓存,拒绝不匹配/损坏缓存的静默覆盖;默认缓存位于本进程 state_dir,不依赖 Gateway 共享文件。指纹必须由可信部署渠道预置,详见工作负载说明。

NSQ 持久化业务重试策略

需要有限自动处理且保留原消息时,显式设置 NSQConsumerConfig.MaxDeliveryAttempts:超限在业务 handler 前原消息 REQ 并暂停本消费者,DeliveryPaused() 可检查状态;不 FIN、不清队列,重启不重置 broker Attempts,恢复边界见 NSQ 说明。

专项授权后,已验证当前进程代次和订阅范围的私有运维入口可调用 RecoverDelivery(commandKey, budget, deadline),有限次数/时间内继续原 handler;同键不充值,到界继续暂停,不改原消息 Attempts 或正常投递上限,详见同页恢复合同。

NSQConsumerConfig.DisableMaxAttempts=true 显式关闭 go-nsq 的次数耗尽自动 FIN,将其 MaxAttempts 设为 0。默认 false 保持旧行为:未指定或 0 的 MaxAttempts 使用 5;正值为有限次数。金融 Outbox/Inbox 等要求故障恢复的消费者应显式启用此项,避免在调用业务 Handler 之前因次数耗尽丢失重试。

该选项不改变 Handler 语义:nil 仍 FIN,error 仍 REQ。只有业务已持久化完成或持久化隔离处理后才能返回 nil;仍在处理的 Inbox 锁、取消、超时和暂态故障须返回 error。格式错误的 poison 消息也不能只靠次数耗尽丢弃,调用方须选择持久隔离及诊断或继续有界退避重试。此项不提供 DLQ、持久化 Inbox 或业务幂等;父 context 和原命令键恢复仍由调用方负责。

Gateway gRPC 响应中的零值 code

未注册 ExactJSONBinding 的默认 Gateway 对 gRPC 响应仅补齐顶层 proto 原名为 code、不带 presence 的单值整数字段:零值仍输出 code: 0;64 位整数按 ProtoJSON 输出 code: "0"。非零值保持原值。未定义 code、optional/proto2/oneof、其他类型及嵌套 code 保持原序列化语义。不会补齐 error、data 或空数组,不会添加响应外层;HTTP 反向代理和普通 HTTP Handler 不受影响。已有接口若依赖零值 code 缺省,需要适配此响应变化。

Gateway 精确 JSON 数字绑定(v3.1.59 起)

自 v3.1.59 起提供 (*gateway.EtcdGateway).RegisterExactJSONBinding。它只作用于显式绑定的逻辑服务名和完整 gRPC 方法,未绑定方法沿用现有 ProtoJSON 行为。

在 NewEtcdGateway(app) 成功后、app.Run() 前注册并处理错误:

err = gw.RegisterExactJSONBinding(gateway.ExactJSONBinding{
    ServiceName: "account-service",
    FullMethod: "/example.v1.AccountService/PostTransfer",
    RequestMessage: "example.v1.RawRequest",
    ResponseMessage: "example.v1.TransferResponse",
    MoneyPaths: []string{"data.amount", "data.rows[*].balance"},
    IntegerPaths: []string{"data.rows[*].created_at"},
    MaxRecvBytes: 32 << 20,
})
if err != nil {
    return err
}

请求 message 必须仅包含一个 bytes raw_body 字段。Gateway 不解析请求 JSON,不合并 query/body/path 参数,直接把原始 HTTP body 字节写入该字段;任何 query 均返回 400。金额指数写法、空白、签名所需字节保持原样,严格 JSON 与业务金额校验归业务服务。HTTP headers 沿用 metadata 桥接及可信 core-client-ip 规则,不从 body 的 headers 取值;业务认证仍须验证所需 header 的单值性。

响应必须具有 int32 code 和普通 message data。每次调用在 RPC 前校验当前 reflection descriptor 的请求/响应全名、容器、数组及选定叶子类型。路径使用 protobuf 原字段名(大小写保留);仅 [*] 表示重复 message。金额叶子必须为 string,整数叶子可为 string 或有符号 64 位整数,支持 optional 但成功响应必须实际提供相应叶子。绑定响应使用 UseProtoNames 与 EmitDefaultValues,因此普通零值和空数组可显式输出。

仅声明路径的十进制字符串转为不加引号的 JSON number:金额最多 8 位小数,精确缩放 10^8 后必须处于 signed int64 范围;整数必须处于 signed int64 范围。过程不使用 float;不接受指数、前导加号、非法前导零或超界。未声明字段(包括 ID)保留原 ProtoJSON 类型。成功必须有对象 data;非零业务 code 可以省略 data,若提供 data 仍校验全部声明路径。字段缺失/null、错误类型、容器错误、精度或范围错误均返回 HTTP 500,不回退字符串或透传任意 JSON 文本。

MaxRecvBytes 必须在 1~33554432 之间,仅覆盖该绑定调用的 gRPC 接收上限;HTTP body 仍受 gateway.max_request_body_bytes 限制。重复注册拒绝且不覆盖;配置切片在注册时复制,注册和读取并发安全。响应 metadata、gRPC 错误映射及现有读请求重试规则继续使用公共链路;写请求不重放。

动态域名 ACME 证书

内置引擎预占回环临时端口,并将 CertMagic solver 固定到该受管理器完整授权保护的 listener;公开挑战入口使用其它端口或外部转发时,也不会自动产生无保护的公网 :80 入口。

certificate 包提供业务授权的精确 hostname 证书生命周期:New(Config)、Ensure(ctx, hostname)、Remove(ctx, hostname)、Status(ctx, hostname)、GetCertificate、HTTPHandler、TLSConfig 和 Close。Ensure 后台申请,未知域名不会在 TLS 握手中触发签发;续期、挑战和新握手均重新检查显式 Authorize 回调。移除绑定后拒绝新握手并停止续期,私钥保留在专用持久存储。

应用在 Run 前使用 app.UseCertificateManager(manager, ":80"),现有 listen: ":443" 提供 HTTPS,Core 托管挑战 listener 和关闭。该能力与静态 acme/certmagic 配置互斥;生产使用持久 StorageDir,多实例使用具备锁能力的共享 Storage,并将公网 HTTP-01 请求送达挑战 handler。默认生产 CA,Config.CA 可切换 staging/本地 directory,测试应注入 Engine,不访问公网 CA。

状态提供 pending、issuing、ready、renewing、failed、expired、removed,以及公开失败码和证书有效期;续期失败可继续提供旧的有效证书,过期和授权未知则拒绝。详细 API、示例、跨实例和安全边界见 动态证书说明。

静态 CertMagic 证书维护

certmagic(Cloudflare DNS-01)与旧版 on-demand 模式为每个 Core 实例创建独立缓存,后台维护复用该实例的存储和签发配置;certmagic.cache 默认 ./certs,服务用户必须可写。启动失败和 Core 关闭时停止维护缓存。外部 Caddy/Nginx 若手动加载这些 PEM 文件,必须在续期后重新加载;Core 更新文件不会刷新其它进程的证书缓存。

通用 gRPC 接收大小

grpc.max_recv_message_bytes 在 Core 首次创建 gRPC server 时固定入站 protobuf 消息接收上限,默认 4194304(4MiB)。合法范围为 1~67108864(64MiB);未设置、非正值、不可解析或超过64MiB安全回落4MiB,显式 0 不表示无限制。app.GRPCMaxRecvMessageBytes() 返回相同规范化值。

Gateway 的普通 ReflectionProxy 调用使用 Gateway 本进程同一配置作为 RPC 响应接收上限;已注册 ExactJSONBinding 的 MaxRecvBytes 优先,不被通用值覆盖。普通 Core gRPC 客户端仍遵循其调用选项;此配置不自动扩大其它服务的客户端限制,也不改变 HTTP 正文上限或业务附件校验。上下游应分别选择所需限额,protobuf 封装也占用消息额度。配置改变需要重建 server/重启进程。

grpc:
  max_recv_message_bytes: 8388608

超时、ETag 与金额运算修复合同

middleware/timeout 采用协作式取消:默认 30 秒(Timeout 非正值仍用默认),deadline 同时作用于 c.Context()、c.Ctx()、c.Request().Context() 和 c.Stream()。保留 JSON/XML/multipart 正文。取消后的 writer 写入返回 http.ErrHandlerTimeout;中间件等待 handler 返回后才恢复 request/writer、回收 Ctx。未提交响应时清除旧 Content-Length、Content-Encoding、validator 等正文相关头,返回配置的超时状态(默认 503),使用 text/plain 和 no-store;已提交响应保留原状态与正文,不追加超时消息。handler 必须把 context 传给下游并主动退出;不响应取消的 handler 会继续占用请求,不保证立即返回 503。这是对原先不安全的 goroutine 抢先返回行为的兼容调整;流式连接建议用 Skip 排除。

middleware/etag 对 GET 的普通 200 响应正文计算 SHA-256 ETag(默认弱 tag),每次仍执行 handler,内容改变会改变 tag;优先保留 handler 的显式 validator。GET/HEAD 按弱比较支持 If-None-Match 列表和 *,命中提交无正文 304。HEAD 不用空正文生成 tag,只使用显式 validator。最多缓冲 1 MiB;超出、SSE、Flush/DoWriteHeader/Hijack 转为直通,不自动计算 tag;Range、Upgrade、非 GET/HEAD 跳过,no-store 和非 200 不生成或比较 tag。静态文件继续复用标准库 Last-Modified/If-Modified-Since 等处理。不要用于需要流式传输或敏感动态 API;用 Skip 排除,etag 不提供 public 缓存或授权策略。普通正文写出不提前强制提交底层 writer,gzip 在 etag 前后均可压缩;Hijack 前已接受的缓冲正文先发送,未写正文的协议升级不预发状态。原 URL hash tag 已废弃,旧 tag 首次请求会重新获取内容。

coins.Money.MulRatio/MulRate 用 big.Int 中间值避免 int64 乘积溢出,结果按最小单位向零截断(负数也向零),分母 0 保持返回零。最终结果越出 int64 时不再静默回绕,而是 panic;需要可恢复错误的调用方使用新增 SafeMulRatio(numerator, denominator) (Money, error),费率对应 SafeMulRatio(rate, coins.MoneyBase)。原签名不变,调用方应检查金额上界或使用安全接口。完整 int64 范围(含 MinInt64)可格式化、字符串解析和按 8 位精度 JSON 往返;SQL 仍按原合同保存缩放后的 int64。

coin.Money.Mul/Div 恢复 1e8 固定缩放,向零截断到 8 位,输入不变;除零(包括零值 Money)保持 panic。零值可作为加减乘运算数和除法被除数。Value() 始终输出完整存储精度,独立于 SetDefaultOutputDecimals;显示/JSON 的精度设置继续生效。曾依赖错误缩放的下游需调整,不得再手动补偿 1e8。

utils.CircularMapBuffer.Values() 从最旧项按插入顺序返回,已有键更新不改变顺序;CircularBuffer.Delete() 压紧逻辑顺序并更新索引,删除后追加和淘汰继续保持顺序。容量需为正整数。

Gateway 请求与快照更新合同

Gateway 的普通 HTTP→gRPC JSON 请求解析失败时立即返回 400,不执行 RPC;空正文、JSON null 和合法对象保持原有语义,ExactJSONBinding 的原始 bytes 透传不受影响。非法 JSON 日志仅包含路由及正文长度,不输出正文片段。

HTTP 反代仍仅对 GET/HEAD 连接失败换一个实例重试一次;有正文时必须能通过 Request.GetBody 重建独立正文,重建失败或正文不可重建时返回 502,不向备用实例发送已消费/已关闭的 Body。普通服务端入站请求通常没有 GetBody;如需带正文重试,调用方中间件须在首次代理前提供一致、可重复读取的正文工厂。无正文重试和写请求不重放的规则不变,gRPC 只读重试规则不变。

Gateway 活跃路由切换通过 Core.ReplaceHandle 在每个 HTTP method 的路由写锁内完成,不再先删除再注册造成瞬时 404;已经匹配的在途请求继续使用旧 handler。manual 优先于 automatic、自动来源冲突停用、全部 gRPC 实例离线保留 503 路由的规则不变。HTTP 实例 reconcile 按服务批量构建,只解析变化的 origin,并复用未变目标、服务快照与轮询计数;未就绪、删除和无效 origin 仍撤销目标。最后一个旧 HTTP 实例退出时清理该服务的轮询及熔断状态,同名服务重新注册不继承已退役服务的熔断;仍有旧实例保留时不重置。

路由事件忽略完全相同的值和无效删除,未变 source 共享不可变对象;变化 source 在接收时复制,旧快照不被修改。路由变化仍重新计算冲突与索引,但仅排序一份记录,并以可比较的派发键代替 JSON 编码比较。JSON bytes 别名和扁平分页兼容预处理仅在 schema 存在对应字段时解析 JSON;简单 schema 直接进入 ProtoJSON,Any、bytes、嵌套 message 及 ExactJSON 语义不变。

(*Core).ReplaceHandle(methods []string, oldURI, uri string, handler any, middleware ...HandlerFunc) Router 是框架内部、动态路由管理使用的增量 API,现有 AddHandle/RemoveHandle 和 Router 接口不变。旧路径不存在时仍注册新路径;支持 ALL、现有大小写配置、handler 适配和声明的 route middleware,不用于替换 USE 中间件。不复制旧 route middleware,新 handler 与 middleware 组成新的链;路径级和全局 middleware 继续由树匹配。每个 method 独立原子替换,不承诺多个 method 或多个 slot 同时切换。参数名可在无共享参数歧义时改变,原有路由格式/参数歧义校验继续生效;非法注册沿用现有程序错误 panic 合同。业务示例仍优先使用自动 Handler 路由。

应用实例、依赖归属与启动准备

core.New(options...) *Core 和现有包级 API 保持签名兼容。配置了 database、redis 或 nsq 时, 初始化失败会保存为启动错误,Listen/Run/Serve 返回脱敏错误并拒绝发布 ready;New 本身不新增 panic。 部分初始化成功后再失败,会关闭本次已创建的资源,且不替换原有全局连接默认值。

每个 Core 只拥有自己创建的数据库、Redis、NSQ producer 和绑定的 consumers。 通过 app.Conn(name...)、app.RConn(name...)、app.NProducer()、 app.NewNSQConsumer(config) 获取实例资源;关闭 A 不关闭或移除 B 的资源。 数据库连接通过创建回调保留其创建时的 SModels 雪花生成器,覆盖 NewDB Session、事务和关联保存, 不随后续 app 的 node_id 改变。同进程相同 node_id 复用同一序列,避免多个 app 产生重复主键。 NSQ consumer 创建时确定归属和认证,显式 AuthSecret 优先;应用退出在用户 hook/模块 Stop 前发出 consumer 停止信号, 随后等待 transport 和框架计数的真实业务 handler 完成(不把 go-nsq 的 StopChan 兜底当成业务完成), 再关闭 producer/Redis/数据库。超时仍限制 ShutdownWithTimeout 的调用等待,但不会强杀业务 goroutine, 不响应取消的消费者会延迟依赖释放。

core.Conf 和全局日志仍使用最近构造应用的进程配置;Conn/RConn/NProducer、ID helper 仍是进程级兼容入口,连接和 ID 代表最近成功发布的默认值, 不能自动按请求识别所属 app。全局 CloseRedis/CloseNSQ 仍是显式关闭默认资源的管理操作; 不要在实例 OnShutdown 中再调用它们。多应用代码须显式注入实例连接;配置和全局默认应在启动阶段设置, 不支持调用方无锁并发重写公开变量。NewModel/NewRedis 返回连接映射快照,修改返回的 map 不再修改全局表。

实现 Prepare 的 Handler 顺序为:实例绑定、Init 和路由建立 → 全部 Prepare(app *core.Core) error 同步完成 → 旧 Start 异步运行 → TLS/路由发布/Registry ready。Prepare 失败返回原始错误链并阻止实现 Prepare 的模块执行 Start, 其网络/数据库操作必须传递 app.Ctx、设置合理超时。未实现 Prepare 的旧模块保留 Start 先异步启动、Init 随后执行的顺序, 兼容 Init 等待 Start 的历史写法;这些 Start 可能早于其他模块的 Prepare。旧 Start 保留异步/常驻任务行为,不充当准备完成信号; 已有代码在 Start 中连接必需依赖或预热时,须将准备部分移入 Prepare。ServingReady 不代表业务异步任务完成。

RegHandle(&Handler{}) 保留单应用写法;同一 Handler 对象不能再次绑定另一 Core,启动会返回错误。 多实例使用工厂,并在 Prepare 中注入当前 app 的依赖,不能浅拷贝包含锁、连接或指针的旧对象:

core.RegHandleFactory(func() core.Module { return &UserHandler{} })

func (h *UserHandler) Prepare(app *core.Core) error {
    db := app.Conn()
    if db == nil { return core.ErrNoConfig }
    h.svc = services.NewUserService(dao.NewUserDAO(db))
    return nil
}

工厂在登记时调用一次确定模块 ID,首个对象用于首个应用;之后每个应用调用一次,必须返回独立同类型 Handler。 工厂只构造对象,不连接外部系统;依赖准备放在 Prepare。停止钩子仍须支持部分初始化后的清理。

fetch 和 cache 不再依赖 core 根包。fetch 单独使用时采用标准日志;同时导入 core 时复用框架日志。 cache 保留 Store 注入以及 Default/Get 签名,core 通过回调装配默认 Redis;显式 SetDefaultStore 优先, SetDefaultStore(nil) 恢复 fallback,DefaultStore() 仍只返回显式默认值。

Gateway 的 core-identity-* metadata 前缀只允许来自认证中间件的 Ctx.Vars,客户端同名 Header 被过滤。 现有自定义 Header 默认继续透传;旧的用户/租户字段须在 gateway.protected_metadata_keys(或 gateway.Config.ProtectedMetadataKeys)列出,才能禁止其来自客户端。未设置认证变量时这些字段保持缺失, 不会回退客户端值。原始 Header/raw_body 不被改写,仍是不可信验签输入。下游必须验证调用方身份并执行授权。 本项不改变 reflection 自动暴露、public_routes 免登录语义、manual 优先或既有 adapter 的鉴权职责。

gateway:
  protected_metadata_keys:
    - user_id
    - x-user-id
    - tenant_id
旧 Handler 启动顺序兼容回归

启动顺序兼容边界:未实现 Prepare 的旧 Handler 在绑定当前 Core 后,先调度异步 Start,再执行 Init 并建立路由,因此 Init 可以等待自身 Start 发出的信号。Start 可以一直运行到 app.Ctx 取消,框架不会等待它返回才发布自动 HTTP 目录或 ready。实现 Prepare 的 Handler 先执行 Init/路由建立,全部 Prepare 成功后才调度 Start;给旧 Handler 新增 Prepare 时,应把必需准备逻辑放入 Prepare,并移除 Init 对 Start 的等待。每个模块的异步调度顺序不代表全部 Start 已执行或业务后台任务已准备完成。

回归覆盖见 module_startup_compat_test.go:旧 Handler 与 Prepare Handler 的两种装载顺序、准备失败时取消已启动旧模块、启动/停止只执行一次;Init 等待有时间上界,使顺序回归直接失败而不拖住全仓测试。自动目录发布边界继续由 TestAutomaticHTTPRouteStartupSyncRunsAfterModuleLoading 验证。

启动与关闭并发的资源边界

并发启动/关闭合同:Shutdown 开始后不再接纳新模块启动或发布 ready。框架先取消 app.Ctx,等待正在执行的 Init、Prepare 和启动发布步骤退出,再调用已加载模块的 Stop;Stop 可发出常驻 Start 的退出信号,框架等待这些 Start 返回后才最终关闭自己拥有的数据库、Redis 等依赖。不会把整个 ErrGroup(含停机观察协程)作为等待对象,避免自等待。ShutdownWithTimeout 的调用方期限仍独立生效;忽略取消或不退出的用户钩子/Start 会推迟后台清理,不能强制释放它们仍可能使用的资源。启动钩子应通过返回错误触发退出,不应同步等待自身的 Shutdown 完成。

Gateway 初始化只执行一次;Close 与任务接纳、请求回退注册共享关闭边界,Close 返回后不允许回退路径重新填入期望实例或连接池。Close 仍清理已拥有的 watcher、连接及客户端,API 签名不变。gRPC 在 server 尚未创建时触发的强制停止不会耗尽未来 server 的一次性停止标记,关闭路径以受锁保护的 server 快照执行停止。

静态传输优化:基础响应 writer 和静态缓存 writer 保留可选 io.ReaderFrom 文件复制接口;gzip 协商禁用压缩时也保留该路径。仍逐层经过当前 writer,不绕过 gzip、ETag 或其它中间件;不支持该接口时回退普通流式复制。公开 ResponseWriter 接口不增加方法,现有自定义 writer 无需修改。是否实际使用 sendfile 取决于协议、连接和文件系统,不能保证 TLS、HTTP/2 或封装文件系统采用零拷贝。默认缓存策略及按请求 gzip 压缩保持不变。

有限 ErrGroup 与 HTTP/3 关闭边界

框架后台任务仍加入原 ErrGroup,保留 ErrGroup().SetLimit(n) 的有限并发语义:容量满时等待已有任务释放位置,等待不持应用锁,并可被 app.Ctx 或关闭标志打断。模块 Start、停机观察协程、gRPC Serve 和 HTTP/3 回调均使用这一可取消接纳边界,避免“启动等入组、停机等启动、Start 等 Stop”的循环。gRPC 已打开但未获接纳的 listener 会立即关闭。

HTTP/3 回调以同一应用锁检查关闭状态并发布 server 所有权;Shutdown/强制关闭读取受锁保护的快照。迟到回调不发布新 server,并关闭传入的 UDP listener;已经发布的 server 会被正常排空或强制关闭。该规则不增加公开 API 或改变默认无限并发配置。

启用 workload.enabled 的 Gateway HTTP 反代只接受 https:// 实例,并按 route.service_name 验证工作负载身份;身份不可用时拒绝受理,不回退明文。内部 HTTP listener/client 使用 WorkloadServerTLSConfig() / WorkloadClientTLSConfig(target) 复用动态证书;调用方须显式用 tls.NewListener 启用内部TLS,并保留应用授权。Gateway 公共浏览器 listener 不要求工作负载客户端证书,详见 工作负载说明。

app.NSQDeliveryPaused() 只读取本应用消费者的内存暂停状态。内置 /health 在暂停时返回 503;monitor.StatsHandler 同样返回 503 并附带 nsq_delivery_paused:true,正常响应保持原格式。可复用服务不可用告警,不能仅依赖 NSQ 连接数判断健康。

Documentation

Overview

grpc.go

Index

Constants

View Source
const (
	MIMETextXML         = "text/xml"
	MIMETextHTML        = "text/html"
	MIMETextPlain       = "text/plain"
	MIMETextJavaScript  = "text/javascript"
	MIMEApplicationXML  = "application/xml"
	MIMEApplicationJSON = "application/json"
	// Deprecated: use MIMETextJavaScript instead
	MIMEApplicationJavaScript = "application/javascript"
	MIMEApplicationForm       = "application/x-www-form-urlencoded"
	MIMEOctetStream           = "application/octet-stream"
	MIMEMultipartForm         = "multipart/form-data"

	MIMETextXMLCharsetUTF8         = "text/xml; charset=utf-8"
	MIMETextHTMLCharsetUTF8        = "text/html; charset=utf-8"
	MIMETextPlainCharsetUTF8       = "text/plain; charset=utf-8"
	MIMETextJavaScriptCharsetUTF8  = "text/javascript; charset=utf-8"
	MIMEApplicationXMLCharsetUTF8  = "application/xml; charset=utf-8"
	MIMEApplicationJSONCharsetUTF8 = "application/json; charset=utf-8"
	// Deprecated: use MIMETextJavaScriptCharsetUTF8 instead
	MIMEApplicationJavaScriptCharsetUTF8 = "application/javascript; charset=utf-8"
)

MIME types that are commonly used

View Source
const (
	CharsetUTF8    = "utf-8"
	CharsetGBK     = "gbk"
	CharsetGB2312  = "gb2312"
	CharsetGB18030 = "gb18030"
)
View Source
const (
	StatusContinue           = 100 // RFC 9110, 15.2.1
	StatusSwitchingProtocols = 101 // RFC 9110, 15.2.2
	StatusProcessing         = 102 // RFC 2518, 10.1
	StatusEarlyHints         = 103 // RFC 8297

	StatusOK                          = 200 // RFC 9110, 15.3.1
	StatusCreated                     = 201 // RFC 9110, 15.3.2
	StatusAccepted                    = 202 // RFC 9110, 15.3.3
	StatusNonAuthoritativeInformation = 203 // RFC 9110, 15.3.4
	StatusNoContent                   = 204 // RFC 9110, 15.3.5
	StatusResetContent                = 205 // RFC 9110, 15.3.6
	StatusPartialContent              = 206 // RFC 9110, 15.3.7
	StatusMultiStatus                 = 207 // RFC 4918, 11.1
	StatusAlreadyReported             = 208 // RFC 5842, 7.1
	StatusIMUsed                      = 226 // RFC 3229, 10.4.1

	StatusMultipleChoices   = 300 // RFC 9110, 15.4.1
	StatusMovedPermanently  = 301 // RFC 9110, 15.4.2
	StatusFound             = 302 // RFC 9110, 15.4.3
	StatusSeeOther          = 303 // RFC 9110, 15.4.4
	StatusNotModified       = 304 // RFC 9110, 15.4.5
	StatusUseProxy          = 305 // RFC 9110, 15.4.6
	StatusSwitchProxy       = 306 // RFC 9110, 15.4.7 (Unused)
	StatusTemporaryRedirect = 307 // RFC 9110, 15.4.8
	StatusPermanentRedirect = 308 // RFC 9110, 15.4.9

	StatusBadRequest                   = 400 // RFC 9110, 15.5.1
	StatusUnauthorized                 = 401 // RFC 9110, 15.5.2
	StatusPaymentRequired              = 402 // RFC 9110, 15.5.3
	StatusForbidden                    = 403 // RFC 9110, 15.5.4
	StatusNotFound                     = 404 // RFC 9110, 15.5.5
	StatusMethodNotAllowed             = 405 // RFC 9110, 15.5.6
	StatusNotAcceptable                = 406 // RFC 9110, 15.5.7
	StatusProxyAuthRequired            = 407 // RFC 9110, 15.5.8
	StatusRequestTimeout               = 408 // RFC 9110, 15.5.9
	StatusConflict                     = 409 // RFC 9110, 15.5.10
	StatusGone                         = 410 // RFC 9110, 15.5.11
	StatusLengthRequired               = 411 // RFC 9110, 15.5.12
	StatusPreconditionFailed           = 412 // RFC 9110, 15.5.13
	StatusRequestEntityTooLarge        = 413 // RFC 9110, 15.5.14
	StatusRequestURITooLong            = 414 // RFC 9110, 15.5.15
	StatusUnsupportedMediaType         = 415 // RFC 9110, 15.5.16
	StatusRequestedRangeNotSatisfiable = 416 // RFC 9110, 15.5.17
	StatusExpectationFailed            = 417 // RFC 9110, 15.5.18
	StatusTeapot                       = 418 // RFC 9110, 15.5.19 (Unused)
	StatusMisdirectedRequest           = 421 // RFC 9110, 15.5.20
	StatusUnprocessableEntity          = 422 // RFC 9110, 15.5.21
	StatusLocked                       = 423 // RFC 4918, 11.3
	StatusFailedDependency             = 424 // RFC 4918, 11.4
	StatusTooEarly                     = 425 // RFC 8470, 5.2.
	StatusUpgradeRequired              = 426 // RFC 9110, 15.5.22
	StatusPreconditionRequired         = 428 // RFC 6585, 3
	StatusTooManyRequests              = 429 // RFC 6585, 4
	StatusRequestHeaderFieldsTooLarge  = 431 // RFC 6585, 5
	StatusUnavailableForLegalReasons   = 451 // RFC 7725, 3

	StatusInternalServerError           = 500 // RFC 9110, 15.6.1
	StatusNotImplemented                = 501 // RFC 9110, 15.6.2
	StatusBadGateway                    = 502 // RFC 9110, 15.6.3
	StatusServiceUnavailable            = 503 // RFC 9110, 15.6.4
	StatusGatewayTimeout                = 504 // RFC 9110, 15.6.5
	StatusHTTPVersionNotSupported       = 505 // RFC 9110, 15.6.6
	StatusVariantAlsoNegotiates         = 506 // RFC 2295, 8.1
	StatusInsufficientStorage           = 507 // RFC 4918, 11.5
	StatusLoopDetected                  = 508 // RFC 5842, 7.2
	StatusNotExtended                   = 510 // RFC 2774, 7
	StatusNetworkAuthenticationRequired = 511 // RFC 6585, 6
)

HTTP status codes were copied from https://github.com/nginx/nginx/blob/67d2a9541826ecd5db97d604f23460210fd3e517/conf/mime.types with the following updates: - Rename StatusNonAuthoritativeInfo to StatusNonAuthoritativeInformation - Add StatusSwitchProxy (306) NOTE: Keep this list in sync with statusMessage

View Source
const (
	HeaderAuthorization                   = "Authorization"
	HeaderProxyAuthenticate               = "Proxy-Authenticate"
	HeaderProxyAuthorization              = "Proxy-Authorization"
	HeaderWWWAuthenticate                 = "WWW-Authenticate"
	HeaderAge                             = "Age"
	HeaderCacheControl                    = "Cache-Control"
	HeaderClearSiteData                   = "Clear-Site-Data"
	HeaderExpires                         = "Expires"
	HeaderPragma                          = "Pragma"
	HeaderWarning                         = "Warning"
	HeaderAcceptCH                        = "Accept-CH"
	HeaderAcceptCHLifetime                = "Accept-CH-Lifetime"
	HeaderContentDPR                      = "Content-DPR"
	HeaderDPR                             = "DPR"
	HeaderEarlyData                       = "Early-Data"
	HeaderSaveData                        = "Save-Data"
	HeaderViewportWidth                   = "Viewport-Width"
	HeaderWidth                           = "Width"
	HeaderETag                            = "ETag"
	HeaderIfMatch                         = "If-Match"
	HeaderIfModifiedSince                 = "If-Modified-Since"
	HeaderIfNoneMatch                     = "If-None-Match"
	HeaderIfUnmodifiedSince               = "If-Unmodified-Since"
	HeaderLastModified                    = "Last-Modified"
	HeaderVary                            = "Vary"
	HeaderConnection                      = "Connection"
	HeaderKeepAlive                       = "Keep-Alive"
	HeaderAccept                          = "Accept"
	HeaderAcceptCharset                   = "Accept-Charset"
	HeaderAcceptEncoding                  = "Accept-Encoding"
	HeaderAcceptLanguage                  = "Accept-Language"
	HeaderCookie                          = "Cookie"
	HeaderExpect                          = "Expect"
	HeaderMaxForwards                     = "Max-Forwards"
	HeaderSetCookie                       = "Set-Cookie"
	HeaderAccessControlAllowCredentials   = "Access-Control-Allow-Credentials"
	HeaderAccessControlAllowHeaders       = "Access-Control-Allow-Headers"
	HeaderAccessControlAllowMethods       = "Access-Control-Allow-Methods"
	HeaderAccessControlAllowOrigin        = "Access-Control-Allow-Origin"
	HeaderAccessControlExposeHeaders      = "Access-Control-Expose-Headers"
	HeaderAccessControlMaxAge             = "Access-Control-Max-Age"
	HeaderAccessControlRequestHeaders     = "Access-Control-Request-Headers"
	HeaderAccessControlRequestMethod      = "Access-Control-Request-Method"
	HeaderOrigin                          = "Origin"
	HeaderTimingAllowOrigin               = "Timing-Allow-Origin"
	HeaderXPermittedCrossDomainPolicies   = "X-Permitted-Cross-Domain-Policies"
	HeaderDNT                             = "DNT"
	HeaderTk                              = "Tk"
	HeaderContentDisposition              = "Content-Disposition"
	HeaderContentEncoding                 = "Content-Encoding"
	HeaderContentLanguage                 = "Content-Language"
	HeaderContentLength                   = "Content-Length"
	HeaderContentLocation                 = "Content-Location"
	HeaderContentType                     = "Content-Type"
	HeaderForwarded                       = "Forwarded"
	HeaderVia                             = "Via"
	HeaderXForwardedFor                   = "X-Forwarded-For"
	HeaderXForwardedHost                  = "X-Forwarded-Host"
	HeaderXForwardedProto                 = "X-Forwarded-Proto"
	HeaderXForwardedProtocol              = "X-Forwarded-Protocol"
	HeaderXForwardedSsl                   = "X-Forwarded-Ssl"
	HeaderXUrlScheme                      = "X-Url-Scheme"
	HeaderLocation                        = "Location"
	HeaderFrom                            = "From"
	HeaderHost                            = "Host"
	HeaderReferer                         = "Referer"
	HeaderReferrerPolicy                  = "Referrer-Policy"
	HeaderUserAgent                       = "User-Agent"
	HeaderAllow                           = "Allow"
	HeaderServer                          = "Server"
	HeaderAcceptRanges                    = "Accept-Ranges"
	HeaderContentRange                    = "Content-Range"
	HeaderIfRange                         = "If-Range"
	HeaderRange                           = "Range"
	HeaderContentSecurityPolicy           = "Content-Security-Policy"
	HeaderContentSecurityPolicyReportOnly = "Content-Security-Policy-Report-Only"
	HeaderCrossOriginResourcePolicy       = "Cross-Origin-Resource-Policy"
	HeaderExpectCT                        = "Expect-CT"
	HeaderPermissionsPolicy               = "Permissions-Policy"
	HeaderPublicKeyPins                   = "Public-Key-Pins"
	HeaderPublicKeyPinsReportOnly         = "Public-Key-Pins-Report-Only"
	HeaderStrictTransportSecurity         = "Strict-Transport-Security"
	HeaderUpgradeInsecureRequests         = "Upgrade-Insecure-Requests"
	HeaderXContentTypeOptions             = "X-Content-Type-Options"
	HeaderXDownloadOptions                = "X-Download-Options"
	HeaderXFrameOptions                   = "X-Frame-Options"
	HeaderXPoweredBy                      = "X-Powered-By"
	HeaderXXSSProtection                  = "X-XSS-Protection"
	HeaderLastEventID                     = "Last-Event-ID"
	HeaderNEL                             = "NEL"
	HeaderPingFrom                        = "Ping-From"
	HeaderPingTo                          = "Ping-To"
	HeaderReportTo                        = "Report-To"
	HeaderTE                              = "TE"
	HeaderTrailer                         = "Trailer"
	HeaderTransferEncoding                = "Transfer-Encoding"
	HeaderSecWebSocketAccept              = "Sec-WebSocket-Accept"
	HeaderSecWebSocketExtensions          = "Sec-WebSocket-Extensions"
	HeaderSecWebSocketKey                 = "Sec-WebSocket-Key"
	HeaderSecWebSocketProtocol            = "Sec-WebSocket-Protocol"
	HeaderSecWebSocketVersion             = "Sec-WebSocket-Version"
	HeaderAcceptPatch                     = "Accept-Patch"
	HeaderAcceptPushPolicy                = "Accept-Push-Policy"
	HeaderAcceptSignature                 = "Accept-Signature"
	HeaderAltSvc                          = "Alt-Svc"
	HeaderDate                            = "Date"
	HeaderIndex                           = "Index"
	HeaderLargeAllocation                 = "Large-Allocation"
	HeaderLink                            = "Link"
	HeaderPushPolicy                      = "Push-Policy"
	HeaderRetryAfter                      = "Retry-After"
	HeaderServerTiming                    = "Server-Timing"
	HeaderSignature                       = "Signature"
	HeaderSignedHeaders                   = "Signed-Headers"
	HeaderSourceMap                       = "SourceMap"
	HeaderUpgrade                         = "Upgrade"
	HeaderXDNSPrefetchControl             = "X-DNS-Prefetch-Control"
	HeaderXPingback                       = "X-Pingback"
	HeaderXRequestID                      = "X-Request-ID"
	HeaderXRequestedWith                  = "X-Requested-With"
	HeaderXRobotsTag                      = "X-Robots-Tag"
	HeaderXUACompatible                   = "X-UA-Compatible"
)

HTTP Headers were copied from net/http.

View Source
const (
	DefaultDateFormat     = "2006-01-02"
	DefaultDateTimeFormat = "2006-01-02 15:04"
)
View Source
const (
	ConstraintInt             = "int"
	ConstraintBool            = "bool"
	ConstraintFloat           = "float"
	ConstraintAlpha           = "alpha"
	ConstraintGUID            = "guid"
	ConstraintMinLen          = "minLen"
	ConstraintMaxLen          = "maxLen"
	ConstraintLen             = "len"
	ConstraintBetweenLen      = "betweenLen"
	ConstraintMinLenLower     = "minlen"
	ConstraintMaxLenLower     = "maxlen"
	ConstraintBetweenLenLower = "betweenlen"
	ConstraintMin             = "min"
	ConstraintMax             = "max"
	ConstraintRange           = "range"
	ConstraintDatetime        = "datetime"
	ConstraintRegex           = "regex"
)

Route Constraints

View Source
const CoreHeader = `` /* 185-byte string literal not displayed */
View Source
const GatewayClientIPMetadata = "core-client-ip"

GatewayClientIPMetadata 是 Gateway 保留并覆盖写入的客户端 IP 字段。

View Source
const VERSION = "v3"

Variables

View Source
var (
	MethodUse     = Methods[METHOD_USE]
	MethodGet     = Methods[METHOD_GET]
	MethodPost    = Methods[METHOD_POST]
	MethodHead    = Methods[METHOD_HEAD]
	MethodPut     = Methods[METHOD_PUT]
	MethodDelete  = Methods[METHOD_DELETE]
	MethodOptions = Methods[METHOD_OPTIONS]
	MethodConnect = Methods[METHOD_CONNECT]
	MethodTrace   = Methods[METHOD_TRACE]
	MethodPatch   = Methods[METHOD_PATCH]
	MethodAll     = Methods[METHOD_ALL]
)
View Source
var (
	ErrDataTypeNotSupport       = errors.New("dataType does not support")
	ErrNoConfig                 = errors.New("field global configuration not found")
	ErrLayoutCalledUnexpectedly = errors.New("layout called unexpectedly")
)
View Source
var (
	ErrBadRequest                   = NewError(StatusBadRequest)                   // 400
	ErrUnauthorized                 = NewError(StatusUnauthorized)                 // 401
	ErrPaymentRequired              = NewError(StatusPaymentRequired)              // 402
	ErrForbidden                    = NewError(StatusForbidden)                    // 403
	ErrNotFound                     = NewError(StatusNotFound)                     // 404
	ErrMethodNotAllowed             = NewError(StatusMethodNotAllowed)             // 405
	ErrNotAcceptable                = NewError(StatusNotAcceptable)                // 406
	ErrProxyAuthRequired            = NewError(StatusProxyAuthRequired)            // 407
	ErrRequestTimeout               = NewError(StatusRequestTimeout)               // 408
	ErrConflict                     = NewError(StatusConflict)                     // 409
	ErrGone                         = NewError(StatusGone)                         // 410
	ErrLengthRequired               = NewError(StatusLengthRequired)               // 411
	ErrPreconditionFailed           = NewError(StatusPreconditionFailed)           // 412
	ErrRequestEntityTooLarge        = NewError(StatusRequestEntityTooLarge)        // 413
	ErrRequestURITooLong            = NewError(StatusRequestURITooLong)            // 414
	ErrUnsupportedMediaType         = NewError(StatusUnsupportedMediaType)         // 415
	ErrRequestedRangeNotSatisfiable = NewError(StatusRequestedRangeNotSatisfiable) // 416
	ErrExpectationFailed            = NewError(StatusExpectationFailed)            // 417
	ErrTeapot                       = NewError(StatusTeapot)                       // 418
	ErrMisdirectedRequest           = NewError(StatusMisdirectedRequest)           // 421
	ErrUnprocessableEntity          = NewError(StatusUnprocessableEntity)          // 422
	ErrLocked                       = NewError(StatusLocked)                       // 423
	ErrFailedDependency             = NewError(StatusFailedDependency)             // 424
	ErrTooEarly                     = NewError(StatusTooEarly)                     // 425
	ErrUpgradeRequired              = NewError(StatusUpgradeRequired)              // 426
	ErrPreconditionRequired         = NewError(StatusPreconditionRequired)         // 428
	ErrTooManyRequests              = NewError(StatusTooManyRequests)              // 429
	ErrRequestHeaderFieldsTooLarge  = NewError(StatusRequestHeaderFieldsTooLarge)  // 431
	ErrUnavailableForLegalReasons   = NewError(StatusUnavailableForLegalReasons)   // 451

	ErrInternalServerError           = NewError(StatusInternalServerError)           // 500
	ErrNotImplemented                = NewError(StatusNotImplemented)                // 501
	ErrBadGateway                    = NewError(StatusBadGateway)                    // 502
	ErrServiceUnavailable            = NewError(StatusServiceUnavailable)            // 503
	ErrGatewayTimeout                = NewError(StatusGatewayTimeout)                // 504
	ErrHTTPVersionNotSupported       = NewError(StatusHTTPVersionNotSupported)       // 505
	ErrVariantAlsoNegotiates         = NewError(StatusVariantAlsoNegotiates)         // 506
	ErrInsufficientStorage           = NewError(StatusInsufficientStorage)           // 507
	ErrLoopDetected                  = NewError(StatusLoopDetected)                  // 508
	ErrNotExtended                   = NewError(StatusNotExtended)                   // 510
	ErrNetworkAuthenticationRequired = NewError(StatusNetworkAuthenticationRequired) // 511
)

Errors

View Source
var (
	// ErrGRPCServerAlreadyInitialized 表示 gRPC server 已创建,不能再改变 transport 或 interceptor。
	ErrGRPCServerAlreadyInitialized = errors.New("grpc server already initialized")
	// ErrGRPCServerAlreadyConfigured 表示同一个 Core 实例已经完成一次 gRPC server 配置。
	ErrGRPCServerAlreadyConfigured = errors.New("grpc server already configured")
	// ErrGRPCTLSSharedAddress 表示 transport credentials 不能在 HTTP 共端口 ServeHTTP 路径上生效。
	ErrGRPCTLSSharedAddress = errors.New("grpc transport credentials require a dedicated grpc address")
	// ErrEtcdDiscoveryConfigurationChanged protects clients bound to an existing Discovery.
	ErrEtcdDiscoveryConfigurationChanged = errors.New("core: etcd discovery configuration change requires a new Core instance")
)
View Source
var (
	ErrGRPCClientAlreadyInitialized  = errors.New("grpc client service already initialized")
	ErrGRPCClientAlreadyConfigured   = errors.New("grpc client service already configured")
	ErrGRPCClientServiceRequired     = errors.New("grpc client service name required")
	ErrGRPCClientTargetRequired      = errors.New("grpc client target required")
	ErrGRPCClientCredentialsRequired = errors.New("grpc client transport credentials required")
	ErrGRPCClientDialOptionsConflict = errors.New("configured grpc client does not accept legacy dial options")
)
View Source
var (
	DefaultErrorWriter io.Writer = os.Stderr
	LogHub                       = NewLogMonitor()
)

DefaultErrorWriter is the default io.Writer used by Gin to debug errors

View Source
var (
	SnID *sid.SnowflakeID
	XID  *xid.Generator
)
View Source
var (
	// AESKey AES-256 密钥(32字节)
	AESKey = []byte("this-is-a-32-byte-key-for-aes256")
)
View Source
var DefaultLogRotateOptions = []string{
	"size: 300M",
	"daily",
	"rotate: 30",
	"compress",
	"delaycompress: 24h",
	"missingok",
	"notifempty",
	"copytruncate",
}
View Source
var (
	DefaultOutput = io.Discard
)
View Source
var ErrConfigFileConflict = errors.New("configuration file revision conflict")

ErrConfigFileConflict 表示正式配置的密文版本已变化。

View Source
var ErrConfigFileUnavailable = errors.New("configuration file unavailable")

ErrConfigFileUnavailable 表示配置无法安全读取或持久化,不包含路径、密钥或明文。

View Source
var ErrInvalidCursor = errors.New("core: invalid cursor")
View Source
var ErrInvalidQuery = errors.New("core: invalid query")

ErrInvalidQuery indicates an invalid filter field or query control parameter.

View Source
var (
	ErrInvalidValidationType = NewError(400, "验证类型必须是结构体指针")
)

全局验证器实例 自定义错误类型

View Source
var ErrNSQRecoveryConflict = errors.New("nsq recovery command conflict")
View Source
var (
	Methods = []string{
		"GET",
		"POST",
		"HEAD",
		"PUT",
		"DELETE",
		"OPTIONS",
		"CONNECT",
		"TRACE",
		"PATCH",
		"ALL",
		"USE",
	}
)
View Source
var UuidNil = UUID{uuid.Nil}

Functions

func AddHealthProbe added in v3.1.30

func AddHealthProbe(probe HealthProbe)

AddHealthProbe 注册健康探针。用于检查 DB/Redis/等依赖健康状态。 在启动时调用 NewModel/NewRedis 后注册对应的 ping 探针。

func CheckHealth added in v3.1.30

func CheckHealth() map[string]string

CheckHealth 执行所有注册的健康探针,返回失败列表。

func CheckPassword added in v3.1.16

func CheckPassword(password, hash string) bool

CheckPassword 验证密码

func CloseNSQ added in v3.1.17

func CloseNSQ()

CloseNSQ 关闭所有 NSQ 连接

func CloseRedis added in v3.1.17

func CloseRedis()

CloseRedis 关闭所有 Redis 连接

func Contains

func Contains[S ~[]E, E comparable](s S, v E) bool

func ContainsAny

func ContainsAny(elems Array, v any) bool

func CurrentConfigFile added in v3.1.65

func CurrentConfigFile() string

CurrentConfigFile 返回最近一次成功加载配置时记录的绝对路径,尚未成功加载时返回空串。

func D

func D(f string, args ...any)

func DBType

func DBType(name ...string) string

func DecodeCursorToken added in v3.1.40

func DecodeCursorToken(spec CursorSpec) ([]any, error)

DecodeCursorToken validates a token against spec and returns its ordered key values. JSON numbers are returned as json.Number so 64-bit IDs stay exact.

func DecryptAES added in v3.1.16

func DecryptAES(ciphertext string) (string, error)

DecryptAES AES-256-GCM 解密

func DecryptAESBytes added in v3.1.16

func DecryptAESBytes(ciphertext []byte) ([]byte, error)

DecryptAESBytes AES-256-GCM 解密

func DefaultErrorHandler

func DefaultErrorHandler(c Ctx, err error) error

func Delete

func Delete[S ~[]E, E any](s S, i, j int) S

Delete removes the elements s[i:j] from s, returning the modified slice. Delete panics if s[i:j] is not a valid slice of s. Delete is O(len(s)-j), so if many items must be deleted, it is better to make a single call deleting them all together than to delete one at a time. Delete might not modify the elements s[len(s)-(j-i):len(s)]. If those elements contain pointers you might consider zeroing those elements so that objects they reference can be garbage collected.

func Dir

func Dir(root string, listDirectory bool) http.FileSystem

Dir returns a http.FileSystem that can be used by http.FileServer(). It is used internally in router.Static(). if listDirectory == true, then it works the same as http.Dir() otherwise it returns a filesystem that prevents http.FileServer() to list the directory files.

func Dump

func Dump(v ...any)

Dump 打印数据信息

func EncodeCursorToken added in v3.1.40

func EncodeCursorToken(fields []string, desc bool, values ...any) (string, error)

EncodeCursorToken returns an opaque, URL-safe token that is bound to the supplied fields and sort direction. Values must follow the same order as fields.

func EncryptAES added in v3.1.16

func EncryptAES(plaintext string) (string, error)

EncryptAES AES-256-GCM 加密

func EncryptAESBytes added in v3.1.16

func EncryptAESBytes(plaintext []byte) ([]byte, error)

EncryptAESBytes AES-256-GCM 加密

func EnumFromString

func EnumFromString[T Enum](str string, mapping []string) T

EnumFromString 字符串转枚举值

func TypeXFromString(str string) TypeX {
	return EnumFromString[TypeX](str, TypeXMap)
}

func EnumMarshalJSON

func EnumMarshalJSON[T Enum](val T, mapping []string) ([]byte, error)

EnumMarshalJSON 枚举 JSON 序列化

func EnumMarshalText added in v3.1.6

func EnumMarshalText[T Enum](v T, mapping []string) ([]byte, error)

EnumMarshalText 将枚举格式化为文本;未定义的索引返回错误。

func EnumString

func EnumString[T Enum](val T, mapping []string) string

EnumString 枚举值转字符串

func (s TypeX) String() string {
	return EnumString(s, TypeXMap)
}

func EnumUnmarshalJSON

func EnumUnmarshalJSON[T Enum](data []byte, mapping []string) (T, error)

EnumUnmarshalJSON 枚举 JSON 反序列化

func EnumUnmarshalText added in v3.1.6

func EnumUnmarshalText[T Enum](data []byte, mapping []string) (T, error)

func EqualFold

func EqualFold[S byteSeq](b, s S) bool

EqualFold tests ascii strings or bytes for equality case-insensitively

func Erro

func Erro(f string, args ...any)

error logger

func Exists

func Exists(absDir string) bool

Exists check file or path exists

func Expr

func Expr(expr string, args ...any) clause.Expr

func ExtractPrimaryDomain added in v3.1.10

func ExtractPrimaryDomain(host string) string

ExtractPrimaryDomain 提取一级域名(主域名) 示例:

"webin.work" -> "webin.work"
"www.webin.work" -> "webin.work"
"api.webin.work" -> "webin.work"
"customer.com" -> "customer.com"
"www.customer.com" -> "customer.com"

func Filter added in v3.0.7

func Filter[T any](slice []T, test func(T) bool) []T

Filter 过滤

activeUsers := core.Filter(users, func(u User) bool {
    return u.Status == "active"
})

func Find

func Find(out any, args ...any) error

Find find all data record max 10000

func FixURI

func FixURI(pre, src, tag string) string

func GetTrimmedParam

func GetTrimmedParam(param string) string

GetTrimmedParam trims the ':' & '?' from a string

func GrpcCookie added in v3.1.45

func GrpcCookie(ctx context.Context, cookie *http.Cookie) error

GrpcCookie queues a complete cookie without applying defaults or escaping its value, like BaseCtx.Cookie. Invalid cookies return an error instead of being silently dropped or sanitized. The caller-owned cookie is not modified.

func GrpcHeader added in v3.1.16

func GrpcHeader(ctx context.Context, key string) string

func GrpcRemoveCookie added in v3.1.45

func GrpcRemoveCookie(ctx context.Context, name, path string, dom ...string) error

GrpcRemoveCookie mirrors BaseCtx.RemoveCookie, including its unchanged path and optional Domain (the first value wins). Use the original Path/Domain.

func GrpcSetCookie added in v3.1.45

func GrpcSetCookie(ctx context.Context, name, value string, exp time.Time, path string, args ...any) error

GrpcSetCookie mirrors BaseCtx.SetCookie: empty path becomes "/", value is URL-escaped, SameSite defaults to Lax, a case-insensitive "httponly" string enables HttpOnly, other strings set Domain, and bools set Secure. Empty Domain falls back to the current Core server's domain config. Unknown args are ignored. Use GrpcCookie for explicit SameSite, MaxAge and a host-only cookie.

func GrpcSetHeader added in v3.1.45

func GrpcSetHeader(ctx context.Context, key string, values ...string) error

GrpcSetHeader queues HTTP response header values in gRPC initial metadata. Repeated calls append values, as with grpc.SetHeader. Gateway converts only this explicit core-http-<lowercase-name>-bin contract, including on RPC errors. Transport headers and invalid names/values are rejected before queuing. Names must also fit the gRPC metadata alphabet (letters, digits, -_.). Call before sending initial headers; ctx must be the current server RPC context.

func HashPassword added in v3.1.16

func HashPassword(password string) (string, error)

HashPassword 使用 bcrypt 哈希密码(使用默认 cost)

func HashPasswordWithCost added in v3.1.16

func HashPasswordWithCost(password string, cost int) (string, error)

HashPasswordWithCost 使用 bcrypt 哈希密码,可指定 cost

func HeaderMap added in v3.1.24

func HeaderMap(headers http.Header) map[string]string

func Index

func Index[S ~[]E, E comparable](s S, v E) int

func Info

func Info(f string, args ...any)

info logger

func InitNSQ added in v3.1.17

func InitNSQ(conf Options, debug bool) error

InitNSQ 初始化 NSQ(从配置自动创建 Producer)

func IsChild

func IsChild() bool

IsChild determines if the current process is a child of Prefork

func IsErrors

func IsErrors(v any) bool

func IsInvalidLengthError

func IsInvalidLengthError(err error) bool

IsInvalidLengthError is matcher function for custom error invalidLengthError

func IsNumeric added in v3.0.7

func IsNumeric(s string) bool

func IsRouteFallback added in v3.1.28

func IsRouteFallback(c Ctx) bool

IsRouteFallback reports whether the current handler chain is running because an OPTIONS request did not match an explicit route.

func LocalIP

func LocalIP() (ip net.IP, err error)

func Log

func Log(f string, args ...any)

func LogRotateOptionsFromConfig added in v3.1.19

func LogRotateOptionsFromConfig(conf Options) []string

func MIME

func MIME(extension string) (mime string)

GetMIME returns the content-type of a file extension

func MakePath

func MakePath(name, dst string, args ...any) (string, string, error)

MakePath make dir

path = {root}/{dst}/{id}
@param
name string filename
dst string dst path
root string root path optional
id   path optional type uid.UID, int, uint, int64,uint64
rename bool optional
return relPath, absPath

 `
   MakePath("favicon.png", "/images")
   (string) relpath "/images/10/favicon.png"
   (string) abspath "/images/10/favicon.png"

   MakePath("favicon.png", "/images", "/static")
   (string) relpath "/images/10/5hsbkthaadld/favicon.png"
   (string) abspath "/static/images/10/5hsbkthaadld/favicon.png"

   MakePath("favicon.png", "/images", "/static", uid.New())
   (string) relpath "/images/10/5hsbkthaadld/5hsbkthaadld.png"
   (string) abspath "/static/images/10/5hsbkthaadld/5hsbkthaadld.png"
              👇filename    👇dst      👇root     👇id      👇rename
   MakePath("favicon.png", "/images", "/static", uid.New(), true)
   (string) relpath "/images/10/5hsbkthaadld/5hsbkthaadld.png"
   (string) abspath "/static/images/10/5hsbkthaadld/5hsbkthaadld.png"
 `

func NSQDecodeJSON added in v3.1.17

func NSQDecodeJSON(msg *nsq.Message, v any) error

NSQDecodeJSON 从 nsq.Message.Body 解析 JSON

func NSQDecodeStdJSON added in v3.1.17

func NSQDecodeStdJSON(msg *nsq.Message, v any) error

NSQDecodeStdJSON 从 nsq.Message.Body 解析 JSON(标准库)

func NSQDeferredPublish added in v3.1.17

func NSQDeferredPublish(topic string, delay time.Duration, body []byte) error

NSQDeferredPublish 快速延迟发布

func NSQDeferredPublishJSON added in v3.1.17

func NSQDeferredPublishJSON(topic string, delay time.Duration, v any) error

NSQDeferredPublishJSON 快速延迟发布 JSON

func NSQHandlerWithTimeout added in v3.1.17

func NSQHandlerWithTimeout(timeout time.Duration, handler func(ctx context.Context, msg *nsq.Message) error) nsq.HandlerFunc

NSQHandlerWithTimeout 包装 handler,为每条消息创建带超时的 context

func NSQParse added in v3.1.17

func NSQParse[T any](msg *nsq.Message) (*T, error)

NSQMessage 泛型消息解析辅助 用法:msg, _ := core.NSQParse[Order](nsqMsg)

func NSQPublish added in v3.1.17

func NSQPublish(topic string, body []byte) error

NSQPublish 快速发布消息到指定 topic

func NSQPublishJSON added in v3.1.17

func NSQPublishJSON(topic string, v any) error

NSQPublishJSON 快速发布 JSON 消息

func NSQPublishString added in v3.1.17

func NSQPublishString(topic, message string) error

NSQPublishString 快速发布字符串消息

func NewModel

func NewModel(conf Options, debug, colorful bool) (map[string]*DB, error)

func NewNID added in v3.1.19

func NewNID() nid.ID

func NewRedis added in v3.1.17

func NewRedis(conf Options, debug bool) (map[string]*RedisClient, error)

NewRedis 根据配置初始化 Redis 连接 支持单实例和多实例两种配置格式

func NewSnID added in v3.0.3

func NewSnID() sid.ID

func NewXID added in v3.1.3

func NewXID() xid.ID

func NormalizeHeaders added in v3.1.7

func NormalizeHeaders(h http.Header)

func PrintJSON

func PrintJSON(v any, tags ...any)

func RegHandle

func RegHandle(mods ...any)

func RegHandleFactory added in v3.1.68

func RegHandleFactory(factory func() Module)

RegHandleFactory registers a per-application Handler factory. It must return a fresh pointer each time; use this API when multiple Core instances coexist. Registration evaluates the factory once to determine its stable module ID.

func RegisterModule

func RegisterModule(inst module)

func RemoteIP added in v3.1.10

func RemoteIP(h iGet, remoteAddr string) net.IP

RemoteIP 默认信任私网和回环代理,不读取应用配置。 可信对端优先解析 XFF,仅缺少 XFF 时尝试单个 X-Real-IP。 无效 RemoteAddr 返回 nil。

func Remove

func Remove[T comparable](elems []T, v T) []T

删除指定元素

func RemoveAll added in v3.1.10

func RemoveAll[S ~[]E, E comparable](s S, v E) S

RemoveAll 删除所有匹配的元素

func RemoveDuplicates

func RemoveDuplicates[T comparable](slice []T) []T

RemoveDuplicates 去重函数,适用于任何类型的切片

func RemoveEscapeChar

func RemoveEscapeChar(word string) string

RemoveEscapeChar removes escape characters

func RemoveEscapeCharBytes

func RemoveEscapeCharBytes(word []byte) []byte

RemoveEscapeCharBytes removes escape characters

func RoutePatternMatch

func RoutePatternMatch(path, pattern string, cfg ...Options) bool

RoutePatternMatch checks if a given path matches a core route pattern.

func SHA256 added in v3.1.15

func SHA256(s string) string

func SHA256Hash added in v3.1.16

func SHA256Hash(data string) string

SHA256Hash 计算 SHA-256 哈希值(string 版本)

func SHA256HashBytes added in v3.1.16

func SHA256HashBytes(data []byte) string

SHA256HashBytes 计算 SHA-256 哈希值([]byte 版本)

func SaveConfigFile

func SaveConfigFile(conf map[string]any) error

func StatusMessage

func StatusMessage(status int) string

StatusMessage returns the correct message for the provided HTTP statuscode

func ToAny

func ToAny[T any](items []T) []any

ToAny 把任意类型切片转换成 []any

e.g: core.ToAny(uuids)

func ToNamer added in v3.1.10

func ToNamer(name string) string

func ToStrings

func ToStrings[T fmt.Stringer](items []T) []string

ToStrings 把任意实现了 fmt.Stringer 的类型切片转换成 []string

e.g: core.ToStrings(uuids)

func ToStringsFromAny

func ToStringsFromAny(items []any) []string

ToStringsFromAny 把 []any 转换成 []string

func Unique added in v3.1.10

func Unique[S ~[]E, E comparable](s S) S

Unique 去重

uniqueScopes := core.Unique(scopes)

func Warn

func Warn(f string, args ...any)

warning logger

func WithTransaction

func WithTransaction(tx *DB, fn func(tx *DB) error) error

WithTransaction

func (s *TypeX) WithTransaction(fn func(tx *core.DB) error) error {
	return WithTransaction(s.DB, fn)
}

Types

type Array

type Array []any

Array 数组类型

func ParseAndDeduplicate

func ParseAndDeduplicate(s string) Array

ParseAndDeduplicate 将输入字符串按逗号分割,去除空字段及重复值

func (Array) FindHandle

func (d Array) FindHandle(handle, value string) Map

func (Array) GormDataType

func (Array) GormDataType() string

GormDataType schema.Field DataType

func (Array) MarshalBinary

func (d Array) MarshalBinary() (data []byte, err error)

func (*Array) Scan

func (d *Array) Scan(src any) error

Scan 数据驱动接口

func (Array) String

func (d Array) String() []string

Strings 转换为 []string

func (Array) StringsJoin

func (d Array) StringsJoin(sp string) string

StringsJoin 链接为字符串

func (*Array) UnmarshalBinary

func (d *Array) UnmarshalBinary(data []byte) error

func (Array) Value

func (d Array) Value() (driver.Value, error)

Value 数据驱动接口

type BaseCtx

type BaseCtx struct {
	W ResponseWriter
	R *http.Request
	// contains filtered or unexported fields
}

func (*BaseCtx) Abort

func (c *BaseCtx) Abort(args ...any) Ctx

func (*BaseCtx) Accepts

func (c *BaseCtx) Accepts(offers ...string) string

Accepts checks if the specified extensions or content types are acceptable.

func (*BaseCtx) AcceptsCharsets

func (c *BaseCtx) AcceptsCharsets(offers ...string) string

AcceptsCharsets checks if the specified charset is acceptable.

func (*BaseCtx) AcceptsEncodings

func (c *BaseCtx) AcceptsEncodings(offers ...string) string

AcceptsEncodings checks if the specified encoding is acceptable.

func (*BaseCtx) AcceptsLanguages

func (c *BaseCtx) AcceptsLanguages(offers ...string) string

AcceptsLanguages checks if the specified language is acceptable.

func (*BaseCtx) Append

func (c *BaseCtx) Append(key string, values ...string) Ctx

Append values to the same key, separated by commas

c.Append("Vary", "Accept-Encoding", "Accept", "X-Requested-With")

Response Header:

Vary: Accept-Encoding, Accept, X-Requested-With

func (*BaseCtx) Bind added in v3.1.8

func (c *BaseCtx) Bind(out any, debug ...bool) error

func (*BaseCtx) BodyParser

func (c *BaseCtx) BodyParser(out any) error

BodyParser parses the request body into the provided 'out' parameter. It delegates the actual parsing to the ReadBody method.

func (*BaseCtx) Context added in v3.1.6

func (c *BaseCtx) Context() context.Context

func (*BaseCtx) Cookie

func (c *BaseCtx) Cookie(cookie *http.Cookie)

Cookie sets a cookie by passing a cookie struct.

func (*BaseCtx) Cookies

func (c *BaseCtx) Cookies(name string) (string, error)

Cookie returns the named cookie provided in the request or ErrNoCookie if not found. And return the named cookie is unescaped. If multiple cookies match the given name, only one cookie will be returned.

func (*BaseCtx) Core

func (c *BaseCtx) Core() *Core

Core implements Ctx.

func (*BaseCtx) Ctx added in v3.1.8

func (c *BaseCtx) Ctx() context.Context

func (*BaseCtx) File

func (c *BaseCtx) File(filePath string)

File implements Ctx.

func (*BaseCtx) FileAttachment

func (c *BaseCtx) FileAttachment(filepath, filename string)

FileAttachment writes the specified file into the body stream in an efficient way On the client side, the file will typically be downloaded with the given filename

func (*BaseCtx) FileFromFS

func (c *BaseCtx) FileFromFS(filepath string, fs http.FileSystem)

FileFromFS writes the specified file from http.FileSystem into the body stream in an efficient way.

func (*BaseCtx) Flush

func (c *BaseCtx) Flush(data any, statusCode ...int) error

Flush response dat and break

func (*BaseCtx) FormFile

func (c *BaseCtx) FormFile(key string) (*multipart.FileHeader, error)

FormFile returns the first file for the provided form key. FormFile calls ParseMultipartForm and ParseForm if necessary.

func (*BaseCtx) FormValue

func (c *BaseCtx) FormValue(key string, def ...string) string

FormValue support old version

func (*BaseCtx) FormValues

func (c *BaseCtx) FormValues(key string, def ...[]string) []string

FormValues returns a slice of strings for a given query key.

func (*BaseCtx) Format

func (c *BaseCtx) Format(body any) error

Format performs content-negotiation on the Accept HTTP header. It uses Accepts to select a proper format. If the header is not specified or there is no proper format, text/plain is used.

func (*BaseCtx) FromValueInt

func (c *BaseCtx) FromValueInt(key string, def ...int) int

func (*BaseCtx) FromValueUUID

func (c *BaseCtx) FromValueUUID(key string, def ...UUID) UUID

func (*BaseCtx) FromValueUid

func (c *BaseCtx) FromValueUid(key string, def ...uid.UID) uid.UID

func (*BaseCtx) FromValueXid added in v3.1.3

func (c *BaseCtx) FromValueXid(key string, def ...xid.ID) xid.ID

func (*BaseCtx) Get

func (c *BaseCtx) Get(key string) (val any, ok bool)

Get returns the value for the given key, ie: (value, true). If the value does not exists it returns (nil, false)

func (*BaseCtx) GetAs

func (c *BaseCtx) GetAs(key string, v any) error

GetAs retrieve struct like c.Get("user").(User)

> Experimental function, problem unknown

func (*BaseCtx) GetBool

func (c *BaseCtx) GetBool(key string) (value bool)

GetBool returns the value associated with the key as a boolean.

func (*BaseCtx) GetDuration

func (c *BaseCtx) GetDuration(key string) (d time.Duration)

GetDuration returns the value associated with the key as a duration.

func (*BaseCtx) GetFloat64

func (c *BaseCtx) GetFloat64(key string, def ...float64) (value float64)

GetFloat64 returns the value associated with the key as a float64.

func (*BaseCtx) GetHeader

func (c *BaseCtx) GetHeader(key string, defaultValue ...string) string

GetHeader get Request header

func (*BaseCtx) GetInt

func (c *BaseCtx) GetInt(key string, def ...int) (i int)

GetInt returns the value associated with the key as an integer.

func (*BaseCtx) GetInt64

func (c *BaseCtx) GetInt64(key string, def ...int64) (i int64)

GetInt64 returns the value associated with the key as an integer.

func (*BaseCtx) GetMap

func (c *BaseCtx) GetMap(key string, def ...map[string]any) (value map[string]any)

GetMap returns the value associated with the key as a map of interfaces.

> return map[string]any

func (*BaseCtx) GetMapString

func (c *BaseCtx) GetMapString(key string, def ...map[string]string) (value map[string]string)

GetMapString returns the value associated with the key as a map of strings.

> return map[string]string

func (*BaseCtx) GetMapStringSlice

func (c *BaseCtx) GetMapStringSlice(key string, def ...map[string][]string) (value map[string][]string)

GetStringMapStringSlice returns the value associated with the key as a map to a slice of strings.

> return map[string][]string

func (*BaseCtx) GetParamInt

func (c *BaseCtx) GetParamInt(key string, defaultValue ...int) (int, error)

GetParamInt get int param, return -1 if failed

func (*BaseCtx) GetParamSid added in v3.0.7

func (c *BaseCtx) GetParamSid(key string, defaultValue ...sid.ID) (sid.ID, error)

func (*BaseCtx) GetParamUid

func (c *BaseCtx) GetParamUid(key string, defaultValue ...uid.UID) (uid.UID, error)

GetParamUid get uid.UID param, return uid.Nil if failed

func (*BaseCtx) GetSid added in v3.1.4

func (c *BaseCtx) GetSid(key string, def ...sid.ID) (v sid.ID)

func (*BaseCtx) GetStatus

func (c *BaseCtx) GetStatus() int

GetStatus get response statusCode

func (*BaseCtx) GetString

func (c *BaseCtx) GetString(key string, def ...string) (value string)

GetString returns the value associated with the key as a string.

func (*BaseCtx) GetStrings

func (c *BaseCtx) GetStrings(key string, def ...[]string) (value []string)

GetStrings String Slice returns the value associated with the key as a slice of strings.

func (*BaseCtx) GetTime

func (c *BaseCtx) GetTime(key string) (t time.Time)

GetTime returns the value associated with the key as time.

func (*BaseCtx) GetUUID

func (c *BaseCtx) GetUUID(key string, def ...UUID) (v UUID)

func (*BaseCtx) GetUint

func (c *BaseCtx) GetUint(key string, def ...uint) (i uint)

GetUint returns the value associated with the key as an integer.

func (*BaseCtx) GetUint64

func (c *BaseCtx) GetUint64(key string, def ...uint64) (i uint64)

GetUint64 returns the value associated with the key as an integer.

func (*BaseCtx) GetXid added in v3.1.3

func (c *BaseCtx) GetXid(key string, def ...xid.ID) (v xid.ID)

func (*BaseCtx) Host added in v3.1.10

func (c *BaseCtx) Host() string

func (*BaseCtx) JSON

func (c *BaseCtx) JSON(data any, code ...int) error

func (*BaseCtx) JSONP

func (c *BaseCtx) JSONP(data any, callback ...string) error

func (*BaseCtx) Locals added in v3.1.10

func (c *BaseCtx) Locals(key string, val ...any) any

func (*BaseCtx) Method

func (c *BaseCtx) Method() string

func (*BaseCtx) Next

func (c *BaseCtx) Next() error

func (*BaseCtx) Param added in v3.1.17

func (c *BaseCtx) Param(key string, defaultValue ...string) string

func (*BaseCtx) ParamUUID

func (c *BaseCtx) ParamUUID(key string, defaultValue ...UUID) UUID

func (*BaseCtx) Params

func (c *BaseCtx) Params(key string, defaultValue ...string) string

func (*BaseCtx) ParamsInt

func (c *BaseCtx) ParamsInt(key string, defaultValue ...int) (int, error)

ParamsInt get int param, return -1 if failed

func (*BaseCtx) ParamsMaps added in v3.1.10

func (c *BaseCtx) ParamsMaps() map[string]string

func (*BaseCtx) ParamsSid added in v3.0.7

func (c *BaseCtx) ParamsSid(key string, defaultValue ...sid.ID) (sid.ID, error)

func (*BaseCtx) ParamsUid

func (c *BaseCtx) ParamsUid(key string, defaultValue ...uid.UID) (uid.UID, error)

ParamsUid get uid.UID param, return uid.Nil if failed

func (*BaseCtx) ParamsUuid

func (c *BaseCtx) ParamsUuid(key string, defaultValue ...UUID) (UUID, error)

ParamsUid get uid.UID param, return uid.Nil if failed

func (*BaseCtx) ParamsXid added in v3.1.3

func (c *BaseCtx) ParamsXid(key string, defaultValue ...xid.ID) (xid.ID, error)

func (*BaseCtx) Path

func (c *BaseCtx) Path() string

func (*BaseCtx) Query

func (c *BaseCtx) Query(key string, def ...string) string

FormValue Get query

key string
def string default val optional

> GET /?name=Jack&id=

`
  name := c.FormValue("name")  // name = Jack
  id := c.FormValue("id", "1") // id = 1 Because the default value is used
`

func (*BaseCtx) QueryInt

func (c *BaseCtx) QueryInt(key string, def ...int) int

func (*BaseCtx) Querys

func (c *BaseCtx) Querys(key string, def ...[]string) []string

func (*BaseCtx) ReadBody

func (c *BaseCtx) ReadBody(out any, debug ...bool) error

多文件

type Upload struct {
    Files []*multipart.FileHeader `form:"files"`
}

func (*BaseCtx) ReadBodyAndValidate added in v3.1.30

func (c *BaseCtx) ReadBodyAndValidate(out any) error

ReadBodyAndValidate 读取请求体并验证,返回统一的错误响应格式。 先调用 c.ReadBody(out) 解析,再调用 c.Validate(out) 验证。 解析失败返回 400,验证失败返回 422。 使用方式:

var req CreateUserReq
if err := c.ReadBodyAndValidate(&req); err != nil {
    return err
}

func (*BaseCtx) Redirect

func (c *BaseCtx) Redirect(to string, stCode ...int) error

func (*BaseCtx) RedirectJS

func (c *BaseCtx) RedirectJS(to string, msg ...string)

func (*BaseCtx) RemoteIP

func (c *BaseCtx) RemoteIP() net.IP

RemoteIP 空 trusted_proxies 配置时信任私网/回环;非空时仅信任配置范围。 XFF 从右向左检查,仅缺少 XFF 时尝试单个 X-Real-IP;无效头回退 TCP 对端。 代理必须覆盖转发头或向 XFF 追加实际来源。

func (*BaseCtx) RemoveCookie

func (c *BaseCtx) RemoveCookie(name, path string, dom ...string)

func (*BaseCtx) Render

func (c *BaseCtx) Render(f string, bind ...any) error

func (*BaseCtx) Request

func (c *BaseCtx) Request() *http.Request

Request implements Ctx.

func (*BaseCtx) Response

func (c *BaseCtx) Response() ResponseWriter

ResponseWriter implements Ctx.

func (*BaseCtx) SSEComment added in v3.1.30

func (c *BaseCtx) SSEComment(comment string) error

SSEComment sends an SSE comment line (used for heartbeat/keepalive). The SSE spec says lines starting with ":" are comments and ignored by clients.

func (*BaseCtx) SSESend added in v3.1.30

func (c *BaseCtx) SSESend(event string, data any, id ...string) error

SSESend sends a structured SSE event, auto-serializing data to JSON.

func (*BaseCtx) SSEWrite added in v3.1.30

func (c *BaseCtx) SSEWrite(event, data string, id ...string) error

SSEWrite writes a single Server-Sent Event to the response. Handles proper formatting of id, event, and data fields. Multi-line data is automatically prefixed with "data: " on each line.

func (*BaseCtx) SaveFile

func (c *BaseCtx) SaveFile(key, dst string, args ...any) (relpath, abspath string, err error)

SaveFile upload file save to a folder

path = {root}/{dst}/{id}
@param
name string filename
dst string dst path
root string root path optional
id   path optional type uid.UID, int, uint, int64,uint64
rename bool optional
return relPath, absPath

   c.SaveFile("file", "/images")
   (string) relpath "/images/10/favicon.png"
   (string) abspath "/images/10/favicon.png"

   c.SaveFile("file", "/images", "./static")
   (string) relpath "/images/10/5hsbkthaadld/favicon.png"
   (string) abspath "/static/images/10/5hsbkthaadld/favicon.png"

   c.SaveFile("file", "/images", "./static", uid.New())
   (string) relpath "/images/10/5hsbkthaadld/5hsbkthaadld.png"
   (string) abspath "/static/images/10/5hsbkthaadld/5hsbkthaadld.png"
              👇file    👇dst      👇root     👇id      👇rename
   c.SaveFile("file", "/images", "./static", uid.New(), true)
   (string) relpath "/images/10/5hsbkthaadld/5hsbkthaadld.png"
   (string) abspath "/static/images/10/5hsbkthaadld/5hsbkthaadld.png"

func (*BaseCtx) SaveFiles

func (c *BaseCtx) SaveFiles(key, dst string, args ...any) (rel Array, err error)

SaveFiles like SaveFile

@params key string MultipartForm key name : files dst string static to ./static more args see SaveFile

rel, err := c.SaveFiles("files", "static", true)

return relative url path rel is

return []string {
	"/static/09/wjejwifx.jpg",
	"/static/09/wjejwifx.jpg",
	"/static/09/wjejwifx.jpg",
}

func (*BaseCtx) Send

func (c *BaseCtx) Send(buf []byte) error

Send send []byte to client

func (*BaseCtx) SendStatus

func (c *BaseCtx) SendStatus(code int, msg ...string) error

func (*BaseCtx) SendString

func (c *BaseCtx) SendString(str ...any) error

func (*BaseCtx) Set

func (c *BaseCtx) Set(key string, val any)

set locals var

func (*BaseCtx) SetCookie

func (c *BaseCtx) SetCookie(name, value string, exp time.Time, path string, args ...any)

SetCookie adds a Set-Cookie header to the ResponseWriter's headers. The provided cookie must have a valid Name. Invalid cookies may be silently dropped.

func (*BaseCtx) SetHeader

func (c *BaseCtx) SetHeader(key string, value string)

func (*BaseCtx) SetParams

func (c *BaseCtx) SetParams(key, val string)

func (*BaseCtx) SetResponseWriter added in v3.1.61

func (c *BaseCtx) SetResponseWriter(w ResponseWriter)

SetResponseWriter replaces the current response writer. Middleware must restore the previous writer before returning; the writer must not outlive the request.

func (*BaseCtx) StartAt

func (c *BaseCtx) StartAt(t ...time.Time) time.Time

func (*BaseCtx) Status

func (c *BaseCtx) Status(code int) Ctx

func (*BaseCtx) Stream

func (c *BaseCtx) Stream(step func(w io.Writer) bool) bool

Stream sends a streaming response and returns a boolean indicates "Is client disconnected in middle of stream"

func (*BaseCtx) TextBytes

func (c *BaseCtx) TextBytes(out io.Writer, f string, bind ...any) error

func (*BaseCtx) TextRender

func (c *BaseCtx) TextRender(f string, bind ...any) error

func (*BaseCtx) ToJSON

func (c *BaseCtx) ToJSON(data any, msg ...any) error

func (*BaseCtx) ToJSONCode

func (c *BaseCtx) ToJSONCode(data any, msg ...any) error

func (*BaseCtx) Type

func (c *BaseCtx) Type(extension string, charset ...string) Ctx

Type sets the Content-Type HTTP header to the MIME type specified by the file extension.

func (*BaseCtx) Validate

func (c *BaseCtx) Validate(out any) error

Validate 验证传入的结构体

func (*BaseCtx) Vars

func (c *BaseCtx) Vars() Map

func (*BaseCtx) Vary

func (c *BaseCtx) Vary(fields ...string) Ctx

Vary add the given header field to the vary response header

c.Vary("Accept-Encoding", "Accept", "X-Requested-With")

Response Header:

Vary: Accept-Encoding, Accept, X-Requested-With

func (*BaseCtx) ViewReload

func (c *BaseCtx) ViewReload()

func (*BaseCtx) ViewTheme

func (c *BaseCtx) ViewTheme(theme string)

ViewTheme 使用模版风格

func (*BaseCtx) XML

func (c *BaseCtx) XML(data any) error

XML converts any interface or string to XML. This method also sets the content header to application/xml.

type CertMagicConfig added in v3.1.10

type CertMagicConfig struct {
	APIToken string
	Email    string
	Domains  []string
	CacheDir string
}

type ClientInfo added in v3.1.10

type ClientInfo struct {
	IP string
	UA string
}

func ExtractClientInfo added in v3.1.10

func ExtractClientInfo(ctx context.Context) *ClientInfo

ExtractClientInfo 对 Core 托管的 RPC 使用 TrustGateway 策略;未设置时 根据实际对端 IP 信任私网/回环。仅采信单值合法 core-client-ip, 其它情况返回 gRPC 对端,不解析原始 IP 转发头。

type Constraint

type Constraint struct {
	ID            TypeConstraint
	RegexCompiler *regexp.Regexp
	Data          []string
}

func (*Constraint) CheckConstraint

func (c *Constraint) CheckConstraint(param string) bool

type Core

type Core struct {
	*http.Server

	Conf Options

	Debug bool

	RequestMethods []string

	ErrorHandler ErrorHandler

	Ctx context.Context

	MaxMultipartMemory int64

	Views      view.IEngine
	TextEngine view.ITextEngine

	EtcdDiscovery *etcd.Discovery
	// contains filtered or unexported fields
}

func New

func New(options ...Options) *Core

func (*Core) ALL

func (app *Core) ALL(path string, handler any, middleware ...any) Router

func (*Core) AcquireCtx

func (app *Core) AcquireCtx(w http.ResponseWriter, r *http.Request) *BaseCtx

func (*Core) Add

func (app *Core) Add(methods []string, path string, handler any, middleware ...any) Router

func (*Core) AddHandle

func (app *Core) AddHandle(methods []string, uri string, group *Group, handler any, middleware ...HandlerFunc) Router

core.go - AddHandle 方法

func (*Core) CONNECT

func (app *Core) CONNECT(path string, handler any, middleware ...any) Router

func (*Core) ConfigureGRPCClient added in v3.1.29

func (app *Core) ConfigureGRPCClient(serviceName string, config GRPCClientConfig) error

ConfigureGRPCClient 必须在指定逻辑服务首次建立连接前调用。

func (*Core) ConfigureGRPCServer added in v3.1.28

func (app *Core) ConfigureGRPCServer(config GRPCServerConfig) error

ConfigureGRPCServer 在 gRPC server 初始化前配置 transport 和 interceptor。 每个 Core 实例只允许配置一次,避免后续调用静默覆盖安全策略。

func (*Core) Conn added in v3.1.68

func (app *Core) Conn(name ...string) *DB

Conn returns this application's database, independently of the global Conn default.

func (*Core) DELETE

func (app *Core) DELETE(path string, handler any, middleware ...any) Router

func (*Core) EnableEtcdDiscovery added in v3.1.10

func (app *Core) EnableEtcdDiscovery(opts *etcd.Options) error

EnableEtcdDiscovery 启用 etcd 服务发现

func (*Core) EnableEtcdRegistry added in v3.1.10

func (app *Core) EnableEtcdRegistry(opts *etcd.Options) error

EnableEtcdRegistry 启用 etcd 服务注册 当 opts 为 nil 时,从配置文件读取;当 opts 已设置字段时,保留用户值

func (*Core) EnableGRPC added in v3.1.10

func (app *Core) EnableGRPC(addr ...string) *Core

EnableGRPC 启用 gRPC 支持

func (*Core) EnableWorkloadIdentity added in v3.1.51

func (app *Core) EnableWorkloadIdentity() error

EnableWorkloadIdentity 在首次创建 gRPC 服务端或客户端前准备本进程身份。 未启用配置时不改变既有 transport;启用后任何初始化失败都拒绝明文回退。

func (*Core) ErrGroup added in v3.1.10

func (app *Core) ErrGroup() *errgroup.Group

func (*Core) EtcdRegistryIdentity added in v3.1.35

func (app *Core) EtcdRegistryIdentity() (serviceName, namespace string, ok bool)

EtcdRegistryIdentity returns the identity installed by the most recent successful EnableEtcdRegistry call. Failed replacements leave this snapshot unchanged.

func (*Core) EtcdTLSConfig added in v3.1.51

func (app *Core) EtcdTLSConfig() (*tls.Config, string, error)

EtcdTLSConfig 为 Registry、Discovery 和 Gateway 自建连接读取相同 etcd TLS 配置。

func (*Core) GET

func (app *Core) GET(path string, handler any, middleware ...any) Router

func (*Core) GRPCMaxRecvMessageBytes added in v3.1.66

func (app *Core) GRPCMaxRecvMessageBytes() int

GRPCMaxRecvMessageBytes 返回通用 gRPC 接收上限,单位为字节。 未配置、非正值或超过64MiB均安全回落4MiB;不会把零解释为无限制。

func (*Core) GetGRPCServer added in v3.1.10

func (app *Core) GetGRPCServer() *grpc.Server

GetGRPCServer 获取 gRPC 服务器实例(用于注册服务)

func (*Core) GetModule

func (app *Core) GetModule(id string) (ModuleInfo, error)

func (*Core) Group

func (app *Core) Group(prefix string, handlers ...HandlerFuncs) Router

func (*Core) GrpcClient added in v3.1.10

func (app *Core) GrpcClient(serviceName string, opts ...grpc.DialOption) (*grpc.ClientConn, error)

GrpcClient 创建 gRPC 客户端连接(基于 etcd 服务发现)

func (*Core) GrpcClientAt added in v3.1.29

func (app *Core) GrpcClientAt(serviceName, target string) (*grpc.ClientConn, error)

GrpcClientAt 使用明确 target 建立连接,并与服务发现连接共用同一份每服务安全配置。

func (*Core) HEAD

func (app *Core) HEAD(path string, handler any, middleware ...any) Router

func (*Core) Listen

func (app *Core) Listen(port ...any) error

func (*Core) MustGrpcClient added in v3.1.13

func (app *Core) MustGrpcClient(serviceName string, opts ...grpc.DialOption) *grpc.ClientConn

MustGrpcClient 创建 gRPC 客户端连接,失败则 panic

func (*Core) NProducer added in v3.1.68

func (app *Core) NProducer() *NSQProducer

NProducer returns this application's NSQ producer.

func (*Core) NSQDeliveryPaused added in v3.1.74

func (app *Core) NSQDeliveryPaused() bool

NSQDeliveryPaused 只检查本应用拥有的消费者,不执行网络访问。

func (*Core) NewNSQConsumer added in v3.1.68

func (app *Core) NewNSQConsumer(conf NSQConsumerConfig) (*NSQConsumer, error)

NewNSQConsumer binds authentication and shutdown to this application, rather than the most recently initialized process-wide producer. Explicit AuthSecret wins.

func (*Core) OPTIONS

func (app *Core) OPTIONS(path string, handler any, middleware ...any) Router

func (*Core) OnShutdown added in v3.1.10

func (app *Core) OnShutdown(fn func())

OnShutdown 添加关闭钩子

func (*Core) PATCH

func (app *Core) PATCH(path string, handler any, middleware ...any) Router

func (*Core) POST

func (app *Core) POST(path string, handler any, middleware ...any) Router

func (*Core) PUT

func (app *Core) PUT(path string, handler any, middleware ...any) Router

func (*Core) ProcessedHandler added in v3.1.11

func (app *Core) ProcessedHandler(hand any) HandlerFuncs

func (*Core) RConn added in v3.1.68

func (app *Core) RConn(name ...string) *RedisClient

RConn returns this application's Redis client.

func (*Core) RegisterGRPCService added in v3.1.10

func (app *Core) RegisterGRPCService(registerFunc func(*grpc.Server))

RegisterGRPCService 注册 gRPC 服务

func (*Core) ReleaseCtx

func (app *Core) ReleaseCtx(c Ctx)

func (*Core) RemoveHandle added in v3.1.17

func (app *Core) RemoveHandle(methods []string, uri string)

func (*Core) ReplaceHandle added in v3.1.68

func (app *Core) ReplaceHandle(methods []string, oldURI, uri string, handler any, middleware ...HandlerFunc) Router

ReplaceHandle replaces a route under one routing lock per HTTP method. Existing in-flight requests keep their handler chain. Parameter names may change provided no other route shares an incompatible parameter position.

func (*Core) RotateWorkloadIntermediate added in v3.1.51

func (app *Core) RotateWorkloadIntermediate() error

RotateWorkloadIntermediate 供受控运维更新中间 CA,不改变根信任;根私钥离线时明确拒绝。

func (*Core) Run

func (app *Core) Run(port ...any) error

Run 启动应用程序并监听指定端口 参数 port 是可选的端口号,可以是一个或多个值 返回可能发生的错误

func (*Core) Serve

func (app *Core) Serve(ln net.Listener) error

func (*Core) ServeHTTP

func (app *Core) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Core) ServingReady added in v3.1.65

func (app *Core) ServingReady() bool

ServingReady 表示传输、工作负载、路由发布及注册就绪步骤均已成功完成。 该状态用于运行态观测,不替代具体业务依赖的健康检查。

func (*Core) ShutdownWithTimeout added in v3.1.30

func (app *Core) ShutdownWithTimeout(timeout time.Duration) error

ShutdownWithTimeout bounds service withdrawal, transport drain, and cleanup. Legacy OnShutdown hooks cannot be forcibly canceled; a deadline still closes HTTP/gRPC transports and returns while an uncooperative hook finishes later.

func (*Core) Static

func (app *Core) Static(relativePath, root string, config ...StaticConfig) Router

func (*Core) StaticFS

func (app *Core) StaticFS(relativePath string, fs http.FileSystem, config ...StaticConfig) Router

func (*Core) StaticFile

func (app *Core) StaticFile(relativePath, dirname string, config ...StaticConfig) Router

StaticFile static file

app.StaticFile("/favicon.ico", "./favicon.ico")

func (*Core) StaticFileFS

func (app *Core) StaticFileFS(relativePath, dirname string, fs http.FileSystem, config ...StaticConfig) Router

StaticFileFS works just like `StaticFile` but a custom `http.FileSystem` can be used instead..

app.StaticFileFS("favicon.ico", "./resources/favicon.ico", Dir{".", false})

func (*Core) TRACE

func (app *Core) TRACE(path string, handler any, middleware ...any) Router

func (*Core) Use

func (app *Core) Use(fn ...any) Router

func (*Core) UseCertificateManager added in v3.1.59

func (app *Core) UseCertificateManager(manager *certificate.Manager, httpAddress string) error

UseCertificateManager 将动态证书接入已有 HTTPS listener,并托管可选的 HTTP-01 listener。 必须在 Run/Serve 前调用;httpAddress 为空时由部署层转发挑战到 manager.HTTPHandler。 成功后由 Core 在关闭时释放 manager;证书状态和域名归属仍由调用方管理。

func (*Core) WorkloadClientCredentials added in v3.1.51

func (app *Core) WorkloadClientCredentials(target string) (credentials.TransportCredentials, error)

WorkloadClientCredentials 为专用内部客户端复用身份并验证目标逻辑服务。

func (*Core) WorkloadClientTLSConfig added in v3.1.71

func (app *Core) WorkloadClientTLSConfig(target string) (*tls.Config, error)

WorkloadClientTLSConfig verifies the logical target and reads renewed certificates at handshake time.

func (*Core) WorkloadIdentityStats added in v3.1.51

func (app *Core) WorkloadIdentityStats() (workload.Stats, error)

WorkloadIdentityStats 返回不含凭据的本进程申请与有效期快照。

func (*Core) WorkloadIssuerStats added in v3.1.51

func (app *Core) WorkloadIssuerStats() (workload.IssuerStats, error)

WorkloadIssuerStats 返回签发器的无秘密统计,不把 CA 状态暴露到普通业务接口。

func (*Core) WorkloadServerCredentials added in v3.1.51

func (app *Core) WorkloadServerCredentials() (credentials.TransportCredentials, error)

WorkloadServerCredentials 为专用内部 listener 复用当前进程的动态身份。

func (*Core) WorkloadServerTLSConfig added in v3.1.71

func (app *Core) WorkloadServerTLSConfig() (*tls.Config, error)

WorkloadServerTLSConfig reuses the managed identity for a dedicated TLS listener. The listener owner must enable TLS and close it during application shutdown.

type Ctx

type Ctx interface {
	Context() context.Context // Request().Context()
	Ctx() context.Context
	Host() string
	Response() ResponseWriter                                              // Response() return http.ResponseWriter
	SetResponseWriter(ResponseWriter)                                      // Replace the writer for the current request; middleware must restore it.
	Request() *http.Request                                                // Request() return *http.Request
	RedirectJS(to string, msg ...string)                                   // use js redirect
	Redirect(to string, stCode ...int) error                               // base redirect
	RemoteIP() net.IP                                                      // remote client ip
	SetCookie(name, value string, exp time.Time, path string, args ...any) // set cookie
	RemoveCookie(name, path string, dom ...string)                         // remove some cookie
	Cookie(cookie *http.Cookie)                                            // set cookie with cookie object
	Cookies(name string) (string, error)                                   // get some cookie
	ReadBody(out any, debug ...bool) error                                 // read put post any request body to struct or map
	Bind(out any, debug ...bool) error                                     // ReadBody alias  read put post form data to struct or map
	BodyParser(out any) error                                              // read put post form data to struct or map
	Validate(out any) error                                                // validate struct or map
	Next() error                                                           // next HandlerFunc
	Path() string                                                          // return http.Request.URI.path

	Send(buf []byte) error                               // send []byte data
	SendString(msg ...any) error                         // send string to body
	SendStatus(code int, msg ...string) error            // send status to client, options msg with display
	SetHeader(key string, value string)                  // set response header
	GetHeader(key string, defaultValue ...string) string // get request header
	Method() string                                      // return method e.g: GET,POST,PUT,DELETE,OPTION,HEAD...
	GetStatus() int                                      // get response status
	Status(code int) Ctx                                 // set response status
	Core() *Core                                         // return app(*Core)
	Abort(args ...any) Ctx                               // Deprecated: As of v2.0.0, this function simply calls Ctx.Format.
	JSON(any, ...int) error                              // send json
	JSONP(data any, callback ...string) error            // send jsonp
	ToJSON(data any, msg ...any) error                   // send json with status
	ToJSONCode(data any, msg ...any) error               // send have code to json
	StartAt(t ...time.Time) time.Time                    // set ctx start time if t set, else get start at
	ParamsMaps() map[string]string
	Params(key string, defaultValue ...string) string                           // get Params data e.g c.Params("param")
	Param(key string, defaultValue ...string) string                            // get Param data e.g c.Param("param")
	ParamsUid(key string, defaultValue ...uid.UID) (uid.UID, error)             // get Param UID type, return uid.Nil if failed
	GetParamSid(key string, defaultValue ...sid.ID) (sid.ID, error)             // get Param ID type, return sid.Nil if failed
	ParamsSid(key string, defaultValue ...sid.ID) (sid.ID, error)               // get Param ID type, return sid.Nil if failed
	ParamsXid(key string, defaultValue ...xid.ID) (xid.ID, error)               // get Param XID type, return xid.Nil if failed
	ParamsUuid(key string, defaultValue ...UUID) (UUID, error)                  // get Param UID type, return uid.Nil if failed
	ParamUUID(key string, defaultValue ...UUID) UUID                            // get Param UUID type, return uid.Nil if failed
	ParamsInt(key string, defaultValue ...int) (int, error)                     // get Param int type, return -1 if failed
	GetParamUid(key string, defaultValue ...uid.UID) (uid.UID, error)           // get param uid.UID, return uid.Nil if failed
	GetParamInt(key string, defaultValue ...int) (int, error)                   // get param int, return -1 if failed
	File(filePath string)                                                       // send file
	FileAttachment(filepath, filename string)                                   // send file attachment
	FileFromFS(filePath string, fs http.FileSystem)                             // send file from FS
	Append(key string, values ...string) Ctx                                    // append response header
	Vary(fields ...string) Ctx                                                  // set response vary
	FormFile(key string) (*multipart.FileHeader, error)                         // get form file
	SaveFile(key, dst string, args ...any) (relpath, abspath string, err error) // upload some one file
	SaveFiles(key, dst string, args ...any) (rel Array, err error)              // upload multi-file
	Query(key string, def ...string) string                                     // get request query string like ?id=12345
	QueryInt(key string, def ...int) int                                        // parse form value to int
	Querys(key string, def ...[]string) []string                                // like query, but return []string values

	FromValueXid(key string, def ...xid.ID) xid.ID   // parse form value to xid
	FormValue(key string, def ...string) string      // like Query support old version
	FromValueInt(key string, def ...int) int         // parse form value to int
	FromValueUid(key string, def ...uid.UID) uid.UID // parse form value to uid
	FromValueUUID(key string, def ...UUID) UUID      // parse form value to uuid
	FormValues(key string, def ...[]string) []string // like Querys
	Flush(data any, statusCode ...int) error         // flush
	Accepts(offers ...string) string                 // Accepts checks if the specified extensions or content types are acceptable.
	AcceptsCharsets(offers ...string) string         // AcceptsCharsets checks if the specified charset is acceptable.
	AcceptsEncodings(offers ...string) string        // AcceptsEncodings checks if the specified encoding is acceptable.
	AcceptsLanguages(offers ...string) string        // AcceptsLanguages checks if the specified language is acceptable.
	Format(body any) error                           // Format performs content-negotiation on the Accept HTTP header. It uses Accepts to select a proper format. If the header is not specified or there is no proper format, text/plain is used.
	Type(extension string, charset ...string) Ctx    // 发送 response content-type
	XML(data any) error                              // output xml
	Set(key string, val any)
	Get(key string) (val any, ok bool)
	Locals(key string, val ...any) any // set get local ver
	GetString(key string, def ...string) (value string)
	GetBool(key string) (value bool)
	GetInt(key string, def ...int) (i int)
	GetInt64(key string, def ...int64) (i int64)
	GetUint(key string, def ...uint) (i uint)
	GetUint64(key string, def ...uint64) (i uint64)
	GetUUID(key string, def ...UUID) (v UUID)
	GetXid(key string, def ...xid.ID) (v xid.ID)
	GetSid(key string, def ...sid.ID) (v sid.ID)
	GetFloat64(key string, def ...float64) (value float64)
	GetTime(key string) (t time.Time)
	GetDuration(key string) (d time.Duration)
	GetStrings(key string, def ...[]string) (value []string)
	GetMap(key string, def ...map[string]any) (value map[string]any)
	GetMapString(key string, def ...map[string]string) (value map[string]string)
	GetMapStringSlice(key string, def ...map[string][]string) (value map[string][]string)
	GetAs(key string, v any) error
	Vars() Map
	Stream(step func(w io.Writer) bool) bool
	ViewReload() // set view reload
	// SSE 相关
	SSEWrite(event, data string, id ...string) error    // 写入单条 SSE 事件
	SSESend(event string, data any, id ...string) error // 发送结构化 SSE 事件(自动序列化 data)
	SSEComment(comment string) error                    // 发送 SSE 注释(心跳)
	// SSE 相关结束
	Render(f string, bind ...any) error
	TextBytes(out io.Writer, f string, bind ...any) error
	TextRender(f string, bind ...any) error
	SetParams(key string, val string)
	// contains filtered or unexported methods
}

type CursorDirection added in v3.1.40

type CursorDirection string
const (
	CursorDirectionNext CursorDirection = "next"
	CursorDirectionPrev CursorDirection = "prev"
)

type CursorSpec added in v3.1.40

type CursorSpec struct {
	Token     string
	Direction CursorDirection
	Fields    []string
	Desc      bool
}

CursorSpec defines a stable keyset order and the optional position to resume from. Fields must contain either a unique column or an ordered column followed by a unique tie-breaker, for example []string{"id"} or []string{"created_at", "id"}.

type DB

type DB = gorm.DB

func Conn

func Conn(name ...string) *DB

func Where

func Where(whr *Map, db ...*DB) (*DB, int, int)

Where build page query Invalid filter fields or sort/omit controls set ErrInvalidQuery on the returned DB and prevent query execution. Values remain parameter-bound; caller-supplied GORM expressions and scopes must be trusted.

whr *Map
db  *DB optional
return *DB, pos, lmt

type Date

type Date struct {
	time.Time
}

func (Date) MarshalJSON

func (d Date) MarshalJSON() ([]byte, error)

func (*Date) Scan

func (d *Date) Scan(value any) error

func (Date) String

func (d Date) String() string

func (*Date) UnmarshalJSON

func (d *Date) UnmarshalJSON(b []byte) error

func (Date) Value

func (d Date) Value() (driver.Value, error)

type EncryptedConfigFile added in v3.1.65

type EncryptedConfigFile struct {
	// contains filtered or unexported fields
}

EncryptedConfigFile 对部署侧指定的可信 .dat 文件提供跨进程的原子版本交换。 配置目录必须可写;预备文件和永久锁文件只保存密文或锁状态。

func NewEncryptedConfigFile added in v3.1.65

func NewEncryptedConfigFile(path string) (*EncryptedConfigFile, error)

NewEncryptedConfigFile 校验配置、密钥与目录,拒绝链接和会在启动时覆盖配置的模板。

func (*EncryptedConfigFile) Commit added in v3.1.65

func (s *EncryptedConfigFile) Commit(expectedRevision, preparedRevision string) error

Commit 仅在版本匹配时原子替换正式配置,重复提交已生效版本返回成功。

func (*EncryptedConfigFile) Discard added in v3.1.65

func (s *EncryptedConfigFile) Discard(preparedRevision string) error

Discard 删除尚未使用的预备密文;文件已不存在时返回成功。

func (*EncryptedConfigFile) Prepare added in v3.1.65

func (s *EncryptedConfigFile) Prepare(expectedRevision string, next Options) (string, error)

Prepare 校验期望版本后,将下一版仅以密文写入持久预备文件,不改变正式配置。

func (*EncryptedConfigFile) Snapshot added in v3.1.65

func (s *EncryptedConfigFile) Snapshot() (Options, string, error)

Snapshot 读取未经环境变量展开、路径替换的原始配置及密文 SHA-256 版本。

type Enum

type Enum interface {
	~uint8
}

type Error

type Error struct {
	// contains filtered or unexported fields
}

func NewError

func NewError(code int, args ...any) *Error

func (*Error) Code

func (e *Error) Code() int

Code 实现 自定义接口,返回业务错误码

func (*Error) Error

func (e *Error) Error() string

Error 实现 error 接口

func (*Error) Errors

func (e *Error) Errors() (int, string)

Errors 实现自定义接口,返回业务错误码和消息

func (*Error) GRPCStatus added in v3.1.16

func (e *Error) GRPCStatus() *status.Status

GRPCStatus 实现 gRPC 状态接口,让 status.FromError 能正常工作

func (*Error) Unwrap added in v3.1.16

func (e *Error) Unwrap() error

type ErrorHandler

type ErrorHandler func(Ctx, error) error

type Errors

type Errors interface {
	Error() string
	Errors() (int, string)
	Code() int
}

type EventData

type EventData struct {
	ID    string `json:"id,omitempty"`
	Event string `json:"event"`
	Data  any    `json:"data"`
}

func (EventData) String

func (h EventData) String() string

func (*EventData) ToString

func (h *EventData) ToString() string

type EventHub

type EventHub struct {
	// contains filtered or unexported fields
}

func NewEventHub

func NewEventHub(interval ...time.Duration) *EventHub

func (*EventHub) Broadcast

func (h *EventHub) Broadcast(data EventData)

func (*EventHub) Close added in v3.1.24

func (h *EventHub) Close()

func (*EventHub) Get

func (h *EventHub) Get(c Ctx)

func (*EventHub) PostData

func (h *EventHub) PostData(c Ctx)

func (*EventHub) Register

func (h *EventHub) Register(c chan EventData, id ...string)

Register 将管道的发送和关闭所有权交给 Hub;调用方只接收,不得自行关闭或复用已退役管道。 同一活动管道重复注册幂等;一个管道的多个 ID 别名共享同一生命周期。

func (*EventHub) SendTo added in v3.1.20

func (h *EventHub) SendTo(id string, data EventData)

SendTo 向指定 ID 的客户端发送通知,非阻塞

func (*EventHub) UnRegister

func (h *EventHub) UnRegister(c chan EventData, id ...string)

UnRegister 仅清理对应管道;旧连接退出不能移除同 ID 的新连接。

type FindsMode added in v3.1.39

type FindsMode string
const (
	FindsModePage   FindsMode = "page"
	FindsModeNext   FindsMode = "next"
	FindsModeCursor FindsMode = "cursor"
)

type FindsParams added in v3.1.39

type FindsParams struct {
	Where  *Map
	DB     *DB
	Mode   FindsMode
	Cursor *CursorSpec
	Extra  any
}

type FindsResult added in v3.1.39

type FindsResult[T any] struct {
	P             int    `json:"p"`
	L             int    `json:"l"`
	Total         *int64 `json:"total,omitempty"`
	Next          *bool  `json:"next,omitempty"`
	Prev          *bool  `json:"prev,omitempty"`
	NextCursor    string `json:"next_cursor,omitempty"`
	PrevCursor    string `json:"prev_cursor,omitempty"`
	CursorHasNext *bool  `json:"has_next,omitempty"`
	CursorHasPrev *bool  `json:"has_prev,omitempty"`
	Data          []T    `json:"data"`
	Extra         any    `json:"extra,omitempty"`
}

func Finds added in v3.1.39

func Finds[T any](params FindsParams) (result FindsResult[T], err error)

func (FindsResult[T]) HasNext added in v3.1.39

func (r FindsResult[T]) HasNext() bool

func (FindsResult[T]) HasPrev added in v3.1.40

func (r FindsResult[T]) HasPrev() bool

type GRPCClientConfig added in v3.1.29

type GRPCClientConfig struct {
	TransportCredentials credentials.TransportCredentials
}

GRPCClientConfig 为一个逻辑服务配置 transport credentials。 Core 不解析证书或服务身份,每次建立连接时只使用该凭据的副本。

type GRPCCtx added in v3.1.50

type GRPCCtx struct {
	// contains filtered or unexported fields
}

GRPCCtx is a request-scoped adapter for unary or stream server contexts. It does not change protobuf method signatures or own the context lifetime. Services should continue to accept context.Context, obtained with StdContext.

func NewGRPCCtx added in v3.1.50

func NewGRPCCtx(ctx context.Context) *GRPCCtx

NewGRPCCtx wraps the current RPC context (stream.Context for streams). A nil context has background semantics; response writes still require a server RPC.

func (*GRPCCtx) ClientIP added in v3.1.50

func (c *GRPCCtx) ClientIP() string

ClientIP uses ExtractClientInfo's Gateway trust checks, never a raw IP header.

func (*GRPCCtx) Cookie added in v3.1.50

func (c *GRPCCtx) Cookie(name string) (string, error)

Cookie reads and URL-decodes an incoming cookie, like BaseCtx.Cookies. Missing cookies return http.ErrNoCookie; malformed URL escapes return an error.

func (*GRPCCtx) GetHeader added in v3.1.50

func (c *GRPCCtx) GetHeader(key string) string

GetHeader reads the first incoming metadata value. It is not an identity check.

func (*GRPCCtx) HeaderValues added in v3.1.50

func (c *GRPCCtx) HeaderValues(key string) []string

HeaderValues reads all incoming values and returns an independent copy.

func (*GRPCCtx) OutgoingContext added in v3.1.50

func (c *GRPCCtx) OutgoingContext(md metadata.MD) context.Context

OutgoingContext returns a derived context for a downstream RPC. Only explicitly supplied metadata is added; existing outgoing keys are replaced by supplied keys. Incoming metadata is never automatically forwarded. Neither source map is mutated or aliased. The original deadline/cancellation and other context values are retained.

func (*GRPCCtx) RemoveCookie added in v3.1.50

func (c *GRPCCtx) RemoveCookie(name, path string, domain ...string) error

RemoveCookie queues an expired response cookie using the existing removal rules.

func (*GRPCCtx) RequestMetadata added in v3.1.50

func (c *GRPCCtx) RequestMetadata() metadata.MD

RequestMetadata returns an independent copy of incoming metadata. Editing it affects neither the request nor a response/downstream call.

func (*GRPCCtx) SetCookie added in v3.1.50

func (c *GRPCCtx) SetCookie(name, value string, exp time.Time, path string, args ...any) error

SetCookie queues a response cookie using the existing BaseCtx-compatible defaults.

func (*GRPCCtx) SetHeader added in v3.1.50

func (c *GRPCCtx) SetHeader(key string, values ...string) error

SetHeader queues HTTP response headers through Core's Gateway bridge. Repeated calls append values; this does not modify request or outgoing metadata.

func (*GRPCCtx) StdContext added in v3.1.50

func (c *GRPCCtx) StdContext() context.Context

StdContext preserves the original context, including deadline, cancellation, transport identity and Core's Gateway trust configuration.

func (*GRPCCtx) WriteCookie added in v3.1.50

func (c *GRPCCtx) WriteCookie(cookie *http.Cookie) error

WriteCookie queues a complete response cookie without adding defaults or escaping.

type GRPCServerConfig added in v3.1.28

type GRPCServerConfig struct {
	TransportCredentials credentials.TransportCredentials
	UnaryInterceptors    []grpc.UnaryServerInterceptor
	StreamInterceptors   []grpc.StreamServerInterceptor
	// TrustGateway verifies the RPC caller using peer address or authenticated
	// transport identity. Nil trusts private/loopback peer IPs. A configured
	// callback fully overrides that fallback. Never trust request metadata here.
	TrustGateway func(context.Context) bool
}

GRPCServerConfig 定义 Core 创建 gRPC server 前可注入的通用 transport 与 interceptor。 调用方拥有证书身份和授权策略;Core 只负责 server 生命周期和 interceptor chain。

type Group

type Group struct {
	*Core

	Prefix string
	// contains filtered or unexported fields
}

func (*Group) ALL

func (g *Group) ALL(path string, handler any, middleware ...any) Router

func (*Group) Add

func (g *Group) Add(methods []string, path string, handler any, middleware ...any) Router

Add allows you to specify multiple HTTP methods to register a route.

func (*Group) CONNECT

func (g *Group) CONNECT(path string, handler any, middleware ...any) Router

func (*Group) DELETE

func (g *Group) DELETE(path string, handler any, middleware ...any) Router

func (*Group) GET

func (g *Group) GET(path string, handler any, middleware ...any) Router

Get registers a route for GET methods that requests a representation of the specified resource. Requests using GET should only retrieve data.

func (*Group) Group

func (g *Group) Group(prefix string, handlers ...HandlerFuncs) Router

func (*Group) HEAD

func (g *Group) HEAD(path string, handler any, middleware ...any) Router

func (*Group) Name

func (g *Group) Name(name string) Router

func (*Group) OPTIONS

func (g *Group) OPTIONS(path string, handler any, middleware ...any) Router

func (*Group) PATCH

func (g *Group) PATCH(path string, handler any, middleware ...any) Router

func (*Group) POST

func (g *Group) POST(path string, handler any, middleware ...any) Router

func (*Group) PUT

func (g *Group) PUT(path string, handler any, middleware ...any) Router

func (*Group) TRACE

func (g *Group) TRACE(path string, handler any, middleware ...any) Router

func (*Group) Use

func (g *Group) Use(fn ...any) Router

Use registers a middleware route that will match requests with the provided prefix (which is optional and defaults to "/"). Also, you can pass another app instance as a sub-router along a routing path. It's very useful to split up a large API as many independent routers and compose them as a single service using Use. The core error handler and any of the core sub apps are added to the application's error handlers to be invoked on errors that happen within the prefix route.

	app.Use(func(c core.Ctx) error {
	     return c.Next()
	})
	app.Use("/api", func(c core.Ctx) error {
	     return c.Next()
	})
	app.Use("/api", handler, func(c core.Ctx) error {
	     return c.Next()
	})
 	subApp := core.New()
	app.Use("/mounted-path", subApp)

This method will match all HTTP verbs: GET, POST, PUT, HEAD etc...

type Handler

type Handler struct {
	Handlers map[string]any // record callable handle

	ID string
	// contains filtered or unexported fields
}

func (*Handler) Core

func (h *Handler) Core(app ...*Core) *Core

func (*Handler) Debug added in v3.1.8

func (h *Handler) Debug() bool

func (*Handler) HandName

func (h *Handler) HandName(name ...string) string

func (*Handler) Init

func (h *Handler) Init()

func (*Handler) Prefix

func (h *Handler) Prefix(prefix ...string) string

func (*Handler) Preload

func (h *Handler) Preload(c Ctx) error

func (*Handler) PushHandler

func (h *Handler) PushHandler(method, path string)

type HandlerFun

type HandlerFun = func(Ctx)

type HandlerFunc

type HandlerFunc = func(Ctx) error

func CustomRecoveryWithWriter

func CustomRecoveryWithWriter(out io.Writer, handle RecoveryFunc) HandlerFunc

CustomRecoveryWithWriter returns a middleware for a given writer that recovers from any panics and calls the provided handle func to handle it.

func Logger

func Logger(conf ...LoggerConfig) HandlerFunc

func Recovery

func Recovery() HandlerFunc

Recovery returns a middleware that recovers from any panics and writes a 500 if there was one.

func RecoveryWithWriter

func RecoveryWithWriter(out io.Writer, recovery ...RecoveryFunc) HandlerFunc

RecoveryWithWriter returns a middleware for a given writer that recovers from any panics and writes a 500 if there was one.

type HandlerFuncs

type HandlerFuncs []HandlerFunc

type HandlerNormal

type HandlerNormal = func(w http.ResponseWriter, r *http.Request)

type HasUUID

type HasUUID interface {
	GetUUID() UUID
}

type HealthProbe added in v3.1.30

type HealthProbe func() error

HealthProbe 健康探针函数,返回 nil 表示健康,否则返回错误信息。

type HookWriter

type HookWriter struct {
	Writer  io.Writer
	Monitor *LogMonitor
}

func (*HookWriter) Write

func (h *HookWriter) Write(p []byte) (n int, err error)

type IModel added in v3.0.7

type IModel struct {
	ID        IntID           `gorm:"primarykey;autoIncrement:false;comment:主键" json:"id,omitzero"`
	CreatedAt *time.Time      `gorm:"<-:create;comment:创建时间" json:"created_at,omitempty"`
	UpdatedAt *time.Time      `gorm:"autoUpdateTime;comment:更新时间" json:"updated_at,omitempty"`
	DeletedAt *gorm.DeletedAt `gorm:"index;comment:删除时间" json:"deleted_at,omitempty"`
}

type Int

type Int int64

func (Int) GormDataType

func (Int) GormDataType() string

GormDataType schema.Field DataType

func (Int) Int

func (m Int) Int() int

转换结果为标准的 int

func (Int) Int64

func (m Int) Int64() int64

转换结果为标准的 int64

func (*Int) UnmarshalJSON

func (m *Int) UnmarshalJSON(data []byte) error

type IntID added in v3.0.7

type IntID uint

func (*IntID) Encode added in v3.0.7

func (id *IntID) Encode() string

func (*IntID) Scan added in v3.0.7

func (id *IntID) Scan(value any) error

func (IntID) Value added in v3.0.7

func (id IntID) Value() (driver.Value, error)

type IntMoney deprecated

type IntMoney int64

Deprecated: IntMoney 已废弃,请使用 coins.Money

func IntMoneyFromRedisString

func IntMoneyFromRedisString(s string) IntMoney

Scan 实现 sql.Scanner (数据库读取时转为 IntMoney) 不做 100 倍转换

func NewIntMoneyFromFloat

func NewIntMoneyFromFloat(f float64) IntMoney

NewIntMoneyFromFloat 创建 IntMoney(内部存储分)

func ParseIntMoney

func ParseIntMoney(val any) IntMoney

ParseIntMoney 从 any 解析为 IntMoney

func (IntMoney) Abs

func (m IntMoney) Abs() IntMoney

func (IntMoney) Add

func (m IntMoney) Add(x IntMoney) IntMoney

加法

func (IntMoney) DivInt

func (m IntMoney) DivInt(n int64) IntMoney

除法

func (IntMoney) EmvAmount

func (m IntMoney) EmvAmount() string

func (IntMoney) Float64

func (m IntMoney) Float64() float64

Float64 转换为 float64 元

func (IntMoney) GormDBDataType

func (IntMoney) GormDBDataType(db *gorm.DB, field *schema.Field) string

GormDBDataType gorm 方言映射 (不同数据库可指定不同字段类型)

func (IntMoney) GormDataType

func (IntMoney) GormDataType() string

GormDataType gorm 通用数据类型 (用于生成表结构)

func (IntMoney) Int64

func (m IntMoney) Int64() int64

func (IntMoney) IsEqual

func (m IntMoney) IsEqual(x IntMoney, fraction ...int) bool

IsEqual 比较是否相等,允许指定小数位比较

func (IntMoney) MarshalBinary

func (m IntMoney) MarshalBinary() (data []byte, err error)

func (IntMoney) MarshalJSON

func (m IntMoney) MarshalJSON() ([]byte, error)

MarshalJSON 序列化

func (IntMoney) MulInt

func (m IntMoney) MulInt(n int64) IntMoney

乘法

func (*IntMoney) Scan

func (m *IntMoney) Scan(value any) error

Scan 实现 sql.Scanner (数据库读取时转为 IntMoney) 支持 int64 / float64 / string

func (IntMoney) String

func (m IntMoney) String() string

String 格式化输出

func (IntMoney) Sub

func (m IntMoney) Sub(x IntMoney) IntMoney

减法

func (IntMoney) ToFixed

func (m IntMoney) ToFixed(fraction ...int) float64

ToFixed 保留 fraction 位小数(默认 2 位)

func (*IntMoney) UnmarshalBinary

func (m *IntMoney) UnmarshalBinary(data []byte) error

func (*IntMoney) UnmarshalJSON

func (m *IntMoney) UnmarshalJSON(data []byte) error

UnmarshalJSON 反序列化

func (IntMoney) Value

func (m IntMoney) Value() (driver.Value, error)

Value 实现 driver.Valuer (写入数据库时存储为分)

type InvalidUnmarshalError

type InvalidUnmarshalError struct {
	Type reflect.Type
}

An InvalidUnmarshalError describes an invalid argument passed to Unmarshal. (The argument to Unmarshal must be a non-nil pointer.)

func (*InvalidUnmarshalError) Error

func (e *InvalidUnmarshalError) Error() string

type JSON

type JSON json.RawMessage

func (JSON) GormDBDataType

func (JSON) GormDBDataType(db *gorm.DB, field *schema.Field) string

func (JSON) GormDataType

func (JSON) GormDataType() string

GormDataType gorm common data type

func (JSON) GormValue

func (js JSON) GormValue(ctx context.Context, db *gorm.DB) clause.Expr

func (JSON) MarshalJSON

func (j JSON) MarshalJSON() ([]byte, error)

MarshalJSON to output non base64 encoded []byte

func (*JSON) Scan

func (j *JSON) Scan(value any) error

Scan scan value into Jsonb, implements sql.Scanner interface

func (JSON) String

func (j JSON) String() string

func (*JSON) UnmarshalJSON

func (j *JSON) UnmarshalJSON(b []byte) error

UnmarshalJSON to deserialize []byte

func (JSON) Value

func (j JSON) Value() (driver.Value, error)

Value return json value, implement driver.Valuer interface

type LogMonitor

type LogMonitor struct {
	// contains filtered or unexported fields
}

func NewLogMonitor

func NewLogMonitor() *LogMonitor

func (*LogMonitor) Broadcast

func (m *LogMonitor) Broadcast(msg string)

func (*LogMonitor) Register

func (m *LogMonitor) Register(c chan string)

func (*LogMonitor) UnRegister

func (m *LogMonitor) UnRegister(c chan string)

type LogRotateConfig added in v3.1.19

type LogRotateConfig struct {
	MaxSize       int64
	Daily         bool
	RetainDays    int
	Compress      bool
	CopyTruncate  bool
	DelayCompress time.Duration
	MissingOK     bool
	NotifEmpty    bool
}

func ParseLogRotateConfig added in v3.1.19

func ParseLogRotateConfig(opts ...string) (LogRotateConfig, error)

type LoggerConfig

type LoggerConfig struct {
	ForceColor bool
	Debug      bool
	Output     io.Writer
	App        *Core
}

type Map

type Map map[string]any

func (Map) Contains

func (d Map) Contains(k string) bool

func (Map) GetAs

func (d Map) GetAs(k string, v any) error

func (Map) GetBool

func (d Map) GetBool(k string) (value bool)

func (Map) GetInt

func (d Map) GetInt(k string, defaultValue ...int) (value int)

func (Map) GetString

func (d Map) GetString(k string, defaultValue ...string) (value string)

func (Map) GormDataType

func (Map) GormDataType() string

GormDataType schema.Field DataType

func (Map) MarshalBinary

func (d Map) MarshalBinary() (data []byte, err error)

func (*Map) Scan

func (d *Map) Scan(src any) error

Scan 数据驱动接口

func (Map) ToString

func (d Map) ToString(k string, def ...string) string

func (*Map) UnmarshalBinary

func (d *Map) UnmarshalBinary(data []byte) error

func (Map) UnmarshalTo

func (d Map) UnmarshalTo(k string, v any) error

func (Map) Value

func (d Map) Value() (driver.Value, error)

Value 数据驱动接口

type MethodType

type MethodType uint8
const (
	METHOD_GET MethodType = iota
	METHOD_POST
	METHOD_HEAD
	METHOD_PUT
	METHOD_DELETE
	METHOD_OPTIONS
	METHOD_CONNECT
	METHOD_TRACE
	METHOD_PATCH
	METHOD_ALL
	METHOD_USE
)

type Mod

type Mod interface {
	Init()
}

type Model

type Model struct {
	ID        uid.UID         `gorm:"size:12;primaryKey" json:"id,omitempty"`
	CreatedAt *time.Time      `json:"created_at,omitempty" gorm:"<-:create"`
	UpdatedAt *time.Time      `json:"updated_at,omitempty" gorm:"autoUpdateTime"`
	DeletedAt *gorm.DeletedAt `json:"deleted_at,omitempty" gorm:"index"`
}

func (*Model) BeforeCreate

func (m *Model) BeforeCreate(tx *DB) error

type Models

type Models struct {
	ID        UUID            `json:"id,omitzero" gorm:"size:32;primaryKey"`
	CreatedAt *time.Time      `json:"created_at,omitempty" gorm:"<-:create;comment:创建时间"`
	UpdatedAt *time.Time      `json:"updated_at,omitempty" gorm:"autoUpdateTime;comment:更新时间"`
	DeletedAt *gorm.DeletedAt `json:"deleted_at,omitempty" gorm:"index;comment:删除时间"`
}

func (*Models) BeforeCreate

func (m *Models) BeforeCreate(tx *DB) error

type Module

type Module interface {
	Init()
}

type ModuleInfo

type ModuleInfo struct {
	ID       string
	Instance func() Module
}

type Money deprecated

type Money float64

Deprecated: Money 已废弃,请使用 coins.Money

func ParseMoney

func ParseMoney(val any) Money

ParseMoney 从 any 解析为 Money

func (Money) Abs

func (m Money) Abs() Money

func (Money) AddInt

func (m Money) AddInt(in int, fraction ...int) Money

AddInt 加整数 m + in fraction in 保留小数位

func (Money) DivInt

func (m Money) DivInt(in int, fraction ...int) Money

DivInt 除以整数 m / in fraction in 保留小数位

func (Money) EmvAmount

func (m Money) EmvAmount() string

func (Money) Float64

func (m Money) Float64() float64

Float64 输出 float64

func (Money) GormDBDataType

func (Money) GormDBDataType(db *gorm.DB, field *schema.Field) string

GormDBDataType gorm 方言映射 (不同数据库可指定不同字段类型)

func (Money) Int

func (m Money) Int() Int

func (Money) IsEqual

func (m Money) IsEqual(x Money, fixed ...int) bool

func (Money) MarshalBinary added in v3.0.1

func (m Money) MarshalBinary() (data []byte, err error)

func (Money) MarshalJSON

func (m Money) MarshalJSON() ([]byte, error)

func (Money) MulInt

func (m Money) MulInt(in int, fraction ...int) Money

MulInt 乘以整数 m * in fraction in 保留小数位

func (*Money) Scan added in v3.1.35

func (m *Money) Scan(value any) error

Scan 实现 sql.Scanner

func (Money) SubInt

func (m Money) SubInt(in int, fraction ...int) Money

SubInt 减整数 m - in fraction in 保留小数位

func (Money) ToFixed

func (m Money) ToFixed(fraction ...int) Money

ToFixed 保留几位小数 Param fraction int return float64

func (m Money) ToFixed(fraction ...int) Money {
	places := 2
	if len(fraction) > 0 {
		places = fraction[0]
	}
	shift := math.Pow(10, float64(places))
	fv := 0.0000000001 + float64(m) //对浮点数产生.xxx999999999 计算不准进行处理
	return Money(math.Floor(fv*shift) / shift)
}

func (Money) ToFloor

func (m Money) ToFloor(p int) Money

ToFloor 保留 p 位小数, 向下取整

func (Money) ToRound

func (m Money) ToRound(p int) Money

ToRound 保留 p 位小数,四舍五入

func (*Money) UnmarshalBinary added in v3.0.1

func (m *Money) UnmarshalBinary(data []byte) error

func (*Money) UnmarshalJSON

func (m *Money) UnmarshalJSON(data []byte) error

func (Money) Value added in v3.1.35

func (m Money) Value() (driver.Value, error)

Value 实现 driver.Valuer,用于 ClickHouse Decimal 类型写入

type NSQConsumer added in v3.1.17

type NSQConsumer struct {
	// contains filtered or unexported fields
}

NSQConsumer 封装 nsq.Consumer

func NewNSQConsumer added in v3.1.17

func NewNSQConsumer(conf NSQConsumerConfig) (*NSQConsumer, error)

NewNSQConsumer 创建 NSQ Consumer

func (*NSQConsumer) ChangeMaxInFlight added in v3.1.17

func (nc *NSQConsumer) ChangeMaxInFlight(maxInFlight int)

ChangeMaxInFlight 动态调整最大在途消息数

func (*NSQConsumer) DeliveryPaused added in v3.1.74

func (nc *NSQConsumer) DeliveryPaused() bool

DeliveryPaused 表示本消费者因投递次数耗尽而暂停;原消息仍保留在 broker。

func (*NSQConsumer) DeliveryState added in v3.1.74

func (nc *NSQConsumer) DeliveryState() NSQDeliveryState

DeliveryState 返回投递预算与暂停原因,供健康检查和告警读取。

func (*NSQConsumer) IsStarved added in v3.1.17

func (nc *NSQConsumer) IsStarved() bool

IsStarved 判断消费者是否饥饿(可用于背压)

func (*NSQConsumer) RecoverDelivery added in v3.1.75

func (nc *NSQConsumer) RecoverDelivery(key string, budget uint32, deadline time.Time) (NSQDeliveryRecovery, error)

RecoverDelivery 仅供已验证的运维入口调用;调用方必须验证当前进程代次及订阅作用域。

func (*NSQConsumer) Start added in v3.1.17

func (nc *NSQConsumer) Start(handler NSQHandlerFunc) error

Start 启动消费者(阻塞直到 Stop 或连接断开) handler 返回 nil 确认消息,返回 error 重新入队

func (*NSQConsumer) StartAsync added in v3.1.17

func (nc *NSQConsumer) StartAsync(handler NSQHandlerFunc) error

StartAsync 异步启动消费者

func (*NSQConsumer) Stats added in v3.1.17

func (nc *NSQConsumer) Stats() *nsq.ConsumerStats

Stats 获取消费者统计

func (*NSQConsumer) Stop added in v3.1.17

func (nc *NSQConsumer) Stop()

Stop requests asynchronous withdrawal; application cleanup separately waits for both the transport and the real business handlers to finish.

type NSQConsumerBuilder added in v3.1.17

type NSQConsumerBuilder struct {
	// contains filtered or unexported fields
}

NSQConsumerBuilder 消费者构建器

func NewNSQConsumerBuilder added in v3.1.17

func NewNSQConsumerBuilder(topic, channel string) *NSQConsumerBuilder

NewNSQConsumerBuilder 创建消费者构建器

func (*NSQConsumerBuilder) Build added in v3.1.17

func (b *NSQConsumerBuilder) Build() (*NSQConsumer, error)

Build 构建 Consumer

func (*NSQConsumerBuilder) BuildAndStart added in v3.1.17

func (b *NSQConsumerBuilder) BuildAndStart(handler NSQHandlerFunc) (*NSQConsumer, error)

BuildAndStart 构建并启动消费者

func (*NSQConsumerBuilder) WithConcurrency added in v3.1.17

func (b *NSQConsumerBuilder) WithConcurrency(n int) *NSQConsumerBuilder

WithConcurrency 设置并发数

func (*NSQConsumerBuilder) WithLookupd added in v3.1.17

func (b *NSQConsumerBuilder) WithLookupd(addrs ...string) *NSQConsumerBuilder

WithLookupd 设置 lookupd 地址

func (*NSQConsumerBuilder) WithMaxAttempts added in v3.1.17

func (b *NSQConsumerBuilder) WithMaxAttempts(n uint16) *NSQConsumerBuilder

WithMaxAttempts 设置最大重试次数

func (*NSQConsumerBuilder) WithMaxBackoff added in v3.1.17

func (b *NSQConsumerBuilder) WithMaxBackoff(d time.Duration) *NSQConsumerBuilder

WithMaxBackoff 设置最大退避时间

func (*NSQConsumerBuilder) WithMaxInFlight added in v3.1.17

func (b *NSQConsumerBuilder) WithMaxInFlight(n int) *NSQConsumerBuilder

WithMaxInFlight 设置最大在途消息数

func (*NSQConsumerBuilder) WithMsgTimeout added in v3.1.17

func (b *NSQConsumerBuilder) WithMsgTimeout(d time.Duration) *NSQConsumerBuilder

WithMsgTimeout 设置消息处理超时

func (*NSQConsumerBuilder) WithNSQD added in v3.1.17

func (b *NSQConsumerBuilder) WithNSQD(addrs ...string) *NSQConsumerBuilder

WithNSQD 设置 nsqd 直连地址

type NSQConsumerConfig added in v3.1.17

type NSQConsumerConfig struct {
	AuthSecret          string        // 非空时显式覆盖,否则继承最近成功 InitNSQ 的认证凭据。
	Topic               string        // Topic 名称(必填)
	Channel             string        // Channel 名称(必填)
	NSQDs               []string      // 直连 nsqd 地址列表(如 ["127.0.0.1:4150"])
	Lookupds            []string      // nsqlookupd 地址列表(如 ["127.0.0.1:4161"])
	Concurrency         int           // 并发处理数(默认 1)
	MaxInFlight         int           // 最大在途消息数(默认 200)
	MaxAttempts         uint16        // 最大重试次数(默认 5)
	DisableMaxAttempts  bool          // 显式关闭超限自动 FIN,由业务持久化结果决定是否确认。
	MaxDeliveryAttempts uint16        // 非零时超限暂停本消费者并保留原消息,禁止自动 FIN。
	MaxBackoff          time.Duration // 最大退避时间(默认 2m)
	MsgTimeout          time.Duration // 消息处理超时(0 使用服务端默认)
}

NSQConsumerConfig 消费者配置

type NSQDeliveryRecovery added in v3.1.75

type NSQDeliveryRecovery struct {
	CommandKey string    `json:"command_key"`
	Budget     uint32    `json:"budget"`
	Used       uint32    `json:"used"`
	Deadline   time.Time `json:"deadline"`
	Active     bool      `json:"active"`
}

NSQDeliveryRecovery 只记录当前进程的有限恢复授权,不修改 broker 消息身份和次数。

type NSQDeliveryState added in v3.1.74

type NSQDeliveryState struct {
	Topic    string               `json:"topic"`
	Channel  string               `json:"channel"`
	Paused   bool                 `json:"paused"`
	Attempts uint16               `json:"attempts"`
	Limit    uint16               `json:"limit"`
	Recovery *NSQDeliveryRecovery `json:"recovery,omitempty"`
}

NSQDeliveryState 提供不含消息正文的投递暂停观测。

type NSQHandlerContext added in v3.1.17

type NSQHandlerContext struct {
	context.Context
	Message *nsq.Message
	Cancel  context.CancelFunc
}

NSQHandlerContext 带超时的消息处理上下文

func NewNSQHandlerContext added in v3.1.17

func NewNSQHandlerContext(msg *nsq.Message, timeout time.Duration) *NSQHandlerContext

NewNSQHandlerContext 创建带超时的消息处理上下文

type NSQHandlerFunc added in v3.1.17

type NSQHandlerFunc func(msg *nsq.Message) error

NSQHandlerFunc 消息处理函数 返回 nil → FIN(确认处理完成) 返回 error → REQ(重新入队,自动退避重试)

type NSQProducer added in v3.1.17

type NSQProducer struct {
	*nsq.Producer
	// contains filtered or unexported fields
}

NSQProducer 封装 nsq.Producer

func NProducer added in v3.1.17

func NProducer() *NSQProducer

NProducer 获取全局 NSQ Producer

func NewNSQProducer added in v3.1.17

func NewNSQProducer(addr string, cfg *nsq.Config) (*NSQProducer, error)

NewNSQProducer 创建 Producer

func (*NSQProducer) DeferredPublish added in v3.1.17

func (p *NSQProducer) DeferredPublish(topic string, delay time.Duration, body []byte) error

DeferredPublish 延迟发布消息

func (*NSQProducer) DeferredPublishJSON added in v3.1.17

func (p *NSQProducer) DeferredPublishJSON(topic string, delay time.Duration, v any) error

DeferredPublishJSON 延迟发布 JSON 消息

func (*NSQProducer) MultiPublish added in v3.1.17

func (p *NSQProducer) MultiPublish(topic string, bodies [][]byte) error

MultiPublish 批量发布消息到同一 topic

func (*NSQProducer) Ping added in v3.1.17

func (p *NSQProducer) Ping() error

Ping 检测连接

func (*NSQProducer) Publish added in v3.1.17

func (p *NSQProducer) Publish(topic string, body []byte) error

Publish 发布消息

func (*NSQProducer) PublishJSON added in v3.1.17

func (p *NSQProducer) PublishJSON(topic string, v any) error

PublishJSON 发布 JSON 消息(自动序列化)

func (*NSQProducer) PublishString added in v3.1.17

func (p *NSQProducer) PublishString(topic, message string) error

PublishString 发布字符串消息

func (*NSQProducer) Stop added in v3.1.17

func (p *NSQProducer) Stop()

Stop 停止 Producer

type NextPage added in v3.1.8

type NextPage[T any] struct {
	P     int  `json:"p"`
	L     int  `json:"l"`
	Next  bool `json:"next"`
	Prev  bool `json:"prev"`
	Data  []T  `json:"data"`
	Extra any  `json:"extra,omitempty"`
}

func FindNextBy added in v3.1.8

func FindNextBy[T any](whr *Map, out *[]T, db ...*DB) (result NextPage[T], err error)

type NextPages

type NextPages struct {
	P     int  `json:"p"`
	L     int  `json:"l"`
	Next  bool `json:"next"`
	Prev  bool `json:"prev"`
	Data  any  `json:"data"`
	Extra any  `json:"extra,omitempty"`
}

func FindNext

func FindNext(whr *Map, out any, db ...*DB) (result NextPages, err error)

type Options

type Options map[string]any
var (
	Conf Options
)

func LoadConfigFile

func LoadConfigFile(file string, opts ...Options) Options

LoadConfigFile 加载并展开配置;托管身份的相对文件路径以该配置所在目录为基准。

func (Options) As added in v3.1.8

func (d Options) As(k string, v any) error

func (Options) ExpandEnv added in v3.1.30

func (opt Options) ExpandEnv()

ExpandEnv 递归替换所有配置值中的 ${ENV:VAR} 为环境变量值。 支持格式:

  • ${ENV:VAR} → os.Getenv("VAR")
  • ${ENV:VAR:def} → os.Getenv("VAR") 或默认值 "def"

零开销 — 仅在 LoadConfigFile 启动时调用一次。

func (*Options) GetAs

func (opt *Options) GetAs(k string, v any) error

func (*Options) GetBool

func (opt *Options) GetBool(k string, def ...bool) bool

func (*Options) GetDuration added in v3.1.25

func (opt *Options) GetDuration(k string, def ...time.Duration) time.Duration

func (*Options) GetInt

func (opt *Options) GetInt(k string, def ...int) int

func (*Options) GetInt64

func (opt *Options) GetInt64(k string, def ...int64) int64

func (*Options) GetMap

func (opt *Options) GetMap(k string, def ...Options) Options

func (*Options) GetPathBool added in v3.1.8

func (opt *Options) GetPathBool(path string, def ...bool) bool

GetPathBool 获取布尔值

func (*Options) GetPathInt added in v3.1.8

func (opt *Options) GetPathInt(path string, def ...int) int

func (*Options) GetPathString added in v3.1.8

func (opt *Options) GetPathString(path string, def ...string) string

GetPathString 支持通过点号路径获取嵌套配置 例如: GetPathString("telegram.token") 会获取 cfg["telegram"].(Options)["token"]

func (*Options) GetPathStrings added in v3.1.10

func (opt *Options) GetPathStrings(path string, def ...[]string) []string

GetPathStrings 获取字符串数组类型的配置值

func (*Options) GetString

func (opt *Options) GetString(k string, def ...string) string

func (*Options) GetStrings

func (opt *Options) GetStrings(k string, def ...[]string) []string

func (*Options) ToString

func (opt *Options) ToString(k string, def ...string) string

func (*Options) Value

func (opt *Options) Value(k string) (any, bool)

type Page added in v3.1.8

type Page[T any] struct {
	P     int   `json:"p"`
	L     int   `json:"l"`
	Total int64 `json:"total"`
	Data  []T   `json:"data"`
	Extra any   `json:"extra,omitempty"`
}

func FindPageBy added in v3.1.8

func FindPageBy[T any](whr *Map, out *[]T, db ...*DB) (result Page[T], err error)

FindPage Gorm find to page process whr

type Pages

type Pages struct {
	P     int   `json:"p"`
	L     int   `json:"l"`
	Total int64 `json:"total"`
	Data  any   `json:"data"`
	Extra any   `json:"extra,omitempty"`
}

func FindPage

func FindPage(whr *Map, out any, db ...*DB) (result Pages, err error)

FindPage Gorm find to page process whr

type RecoveryFunc

type RecoveryFunc func(c Ctx, err any)

RecoveryFunc defines the function passable to CustomRecovery.

type RedisClient added in v3.1.17

type RedisClient struct {
	*redis.Client
}

func RConn added in v3.1.17

func RConn(name ...string) *RedisClient

RConn 获取 Redis 连接(默认实例)

func (*RedisClient) BitCount added in v3.1.17

func (r *RedisClient) BitCount(ctx context.Context, key string, bitCount *redis.BitCount) (int64, error)

BitCount 统计位为1的数量

func (*RedisClient) Close added in v3.1.17

func (r *RedisClient) Close() error

Close 关闭连接

func (*RedisClient) Decr added in v3.1.17

func (r *RedisClient) Decr(ctx context.Context, key string) (int64, error)

Decr 原子递减

func (*RedisClient) Delete added in v3.1.17

func (r *RedisClient) Delete(ctx context.Context, keys ...string) error

Delete 删除

func (*RedisClient) Eval added in v3.1.17

func (r *RedisClient) Eval(ctx context.Context, script string, keys []string, args ...any) (any, error)

Eval 执行 Lua 脚本

func (*RedisClient) EvalSha added in v3.1.17

func (r *RedisClient) EvalSha(ctx context.Context, sha1 string, keys []string, args ...any) (any, error)

EvalSha 执行 Lua 脚本(通过 SHA1)

func (*RedisClient) Exists added in v3.1.17

func (r *RedisClient) Exists(ctx context.Context, key string) (bool, error)

Exists 是否存在

func (*RedisClient) Expire added in v3.1.17

func (r *RedisClient) Expire(ctx context.Context, key string, ttl time.Duration) error

Expire 设置过期时间

func (*RedisClient) Get added in v3.1.17

func (r *RedisClient) Get(ctx context.Context, key string) (string, error)

Get 获取值(redis.Nil 返回空字符串不报错)

func (*RedisClient) GetBit added in v3.1.17

func (r *RedisClient) GetBit(ctx context.Context, key string, offset int64) (int64, error)

GetBit 获取位

func (*RedisClient) GetInt added in v3.1.17

func (r *RedisClient) GetInt(ctx context.Context, key string) (int, error)

GetInt 获取整数值

func (*RedisClient) GetJSON added in v3.1.17

func (r *RedisClient) GetJSON(ctx context.Context, key string, v any) error

GetJSON 自动反序列化读取

func (*RedisClient) HDel added in v3.1.17

func (r *RedisClient) HDel(ctx context.Context, key string, fields ...string) error

HDel 删除 Hash 字段

func (*RedisClient) HExists added in v3.1.17

func (r *RedisClient) HExists(ctx context.Context, key, field string) (bool, error)

HExists 判断 Hash 字段是否存在

func (*RedisClient) HGet added in v3.1.17

func (r *RedisClient) HGet(ctx context.Context, key, field string) (string, error)

HGet 获取 Hash 字段值

func (*RedisClient) HGetAll added in v3.1.17

func (r *RedisClient) HGetAll(ctx context.Context, key string) (map[string]string, error)

HGetAll 获取 Hash 所有字段

func (*RedisClient) HGetJSON added in v3.1.17

func (r *RedisClient) HGetJSON(ctx context.Context, key, field string, v any) error

HGetJSON Hash 字段 JSON 反序列化读取

func (*RedisClient) HIncrBy added in v3.1.17

func (r *RedisClient) HIncrBy(ctx context.Context, key, field string, incr int64) (int64, error)

HIncrBy Hash 字段原子递增

func (*RedisClient) HLen added in v3.1.17

func (r *RedisClient) HLen(ctx context.Context, key string) (int64, error)

HLen Hash 字段数量

func (*RedisClient) HSet added in v3.1.17

func (r *RedisClient) HSet(ctx context.Context, key string, values ...any) error

HSet 设置 Hash 字段

func (*RedisClient) HSetJSON added in v3.1.17

func (r *RedisClient) HSetJSON(ctx context.Context, key, field string, value any) error

HSetJSON Hash 字段 JSON 序列化存储

func (*RedisClient) Incr added in v3.1.17

func (r *RedisClient) Incr(ctx context.Context, key string) (int64, error)

Incr 原子递增

func (*RedisClient) IncrBy added in v3.1.17

func (r *RedisClient) IncrBy(ctx context.Context, key string, value int64) (int64, error)

IncrBy 原子增减指定值

func (*RedisClient) IncrWithTTL added in v3.1.17

func (r *RedisClient) IncrWithTTL(ctx context.Context, key string, ttl time.Duration) (int64, error)

IncrWithTTL 递增并设置过期(常用于限流)

func (*RedisClient) LLen added in v3.1.17

func (r *RedisClient) LLen(ctx context.Context, key string) (int64, error)

LLen 列表长度

func (*RedisClient) LPop added in v3.1.17

func (r *RedisClient) LPop(ctx context.Context, key string) (string, error)

LPop 左侧出队

func (*RedisClient) LPush added in v3.1.17

func (r *RedisClient) LPush(ctx context.Context, key string, values ...any) error

LPush 左侧入队

func (*RedisClient) LRange added in v3.1.17

func (r *RedisClient) LRange(ctx context.Context, key string, start, stop int64) ([]string, error)

LRange 获取列表范围

func (*RedisClient) NewStreamConsumer added in v3.1.17

func (r *RedisClient) NewStreamConsumer(conf StreamConsumerConfig) *StreamConsumer

NewStreamConsumer 创建 Stream 消费者

func (*RedisClient) Ping added in v3.1.17

func (r *RedisClient) Ping(ctx context.Context) error

Ping 检测连接

func (*RedisClient) Pipeline added in v3.1.17

func (r *RedisClient) Pipeline() redis.Pipeliner

Pipeline 获取管道

func (*RedisClient) Pipelined added in v3.1.17

func (r *RedisClient) Pipelined(ctx context.Context, fn func(redis.Pipeliner) error) ([]redis.Cmder, error)

Pipelined 执行管道操作

func (*RedisClient) Publish added in v3.1.17

func (r *RedisClient) Publish(ctx context.Context, channel string, message any) error

Publish 发布消息

func (*RedisClient) RPop added in v3.1.17

func (r *RedisClient) RPop(ctx context.Context, key string) (string, error)

RPop 右侧出队

func (*RedisClient) RPush added in v3.1.17

func (r *RedisClient) RPush(ctx context.Context, key string, values ...any) error

RPush 右侧入队

func (*RedisClient) SAdd added in v3.1.17

func (r *RedisClient) SAdd(ctx context.Context, key string, members ...any) error

SAdd 添加成员到集合

func (*RedisClient) SCard added in v3.1.17

func (r *RedisClient) SCard(ctx context.Context, key string) (int64, error)

SCard 集合成员数量

func (*RedisClient) SIsMember added in v3.1.17

func (r *RedisClient) SIsMember(ctx context.Context, key string, member any) (bool, error)

SIsMember 判断是否为集合成员

func (*RedisClient) SMembers added in v3.1.17

func (r *RedisClient) SMembers(ctx context.Context, key string) ([]string, error)

SMembers 获取集合所有成员

func (*RedisClient) SRem added in v3.1.17

func (r *RedisClient) SRem(ctx context.Context, key string, members ...any) error

SRem 从集合移除成员

func (*RedisClient) Scan added in v3.1.17

func (r *RedisClient) Scan(ctx context.Context, cursor uint64, match string, count int64) *redis.ScanCmd

Scan 扫描匹配的 key

func (*RedisClient) ScriptLoad added in v3.1.17

func (r *RedisClient) ScriptLoad(ctx context.Context, script string) (string, error)

ScriptLoad 预加载 Lua 脚本

func (*RedisClient) Set added in v3.1.17

func (r *RedisClient) Set(ctx context.Context, key string, value any, ttl ...time.Duration) error

Set 设置值(可选TTL)

func (*RedisClient) SetBit added in v3.1.17

func (r *RedisClient) SetBit(ctx context.Context, key string, offset int64, value int) error

SetBit 设置位

func (*RedisClient) SetJSON added in v3.1.17

func (r *RedisClient) SetJSON(ctx context.Context, key string, value any, ttl ...time.Duration) error

SetJSON 自动序列化存储

func (*RedisClient) Subscribe added in v3.1.17

func (r *RedisClient) Subscribe(ctx context.Context, channel string, handler func(string)) error

Subscribe 订阅频道(阻塞式)

func (*RedisClient) TTL added in v3.1.17

func (r *RedisClient) TTL(ctx context.Context, key string) (time.Duration, error)

TTL 获取剩余过期时间

func (*RedisClient) TxPipeline added in v3.1.17

func (r *RedisClient) TxPipeline() redis.Pipeliner

TxPipeline 获取事务管道

func (*RedisClient) XAck added in v3.1.17

func (r *RedisClient) XAck(ctx context.Context, stream, group string, ids ...string) error

XAck 确认消息已处理

func (*RedisClient) XAdd added in v3.1.17

func (r *RedisClient) XAdd(ctx context.Context, stream string, fields map[string]any, id ...string) (string, error)

XAdd 向 Stream 添加消息 返回消息 ID

func (*RedisClient) XAddJSON added in v3.1.17

func (r *RedisClient) XAddJSON(ctx context.Context, stream string, value any, id ...string) (string, error)

XAddJSON 向 Stream 添加 JSON 消息 将 value 序列化为 JSON 存入 _data 字段

func (*RedisClient) XClaim added in v3.1.17

func (r *RedisClient) XClaim(ctx context.Context, stream, group, consumer string, minIdleTime time.Duration, ids ...string) ([]StreamMessage, error)

XClaim 认领待处理消息(用于故障恢复)

func (*RedisClient) XDel added in v3.1.17

func (r *RedisClient) XDel(ctx context.Context, stream string, ids ...string) (int64, error)

XDel 删除 Stream 中的消息

func (*RedisClient) XGroupCreate added in v3.1.17

func (r *RedisClient) XGroupCreate(ctx context.Context, stream, group, startID string) error

XGroupCreate 创建消费者组 startID: "0" 从头消费, "$" 只消费新消息

func (*RedisClient) XGroupDestroy added in v3.1.17

func (r *RedisClient) XGroupDestroy(ctx context.Context, stream, group string) error

XGroupDestroy 删除消费者组

func (*RedisClient) XLen added in v3.1.17

func (r *RedisClient) XLen(ctx context.Context, stream string) (int64, error)

XLen 获取 Stream 长度

func (*RedisClient) XPending added in v3.1.17

func (r *RedisClient) XPending(ctx context.Context, stream, group string) (*redis.XPending, error)

XPending 获取消费者组的待处理消息信息

func (*RedisClient) XRange added in v3.1.17

func (r *RedisClient) XRange(ctx context.Context, stream, start, stop string, count ...int64) ([]StreamMessage, error)

XRange 按 ID 范围读取消息

func (*RedisClient) XRead added in v3.1.17

func (r *RedisClient) XRead(ctx context.Context, stream string, startID string, count ...int64) ([]StreamMessage, error)

XRead 从 Stream 读取消息(非消费者组模式)

func (*RedisClient) XReadGroup added in v3.1.17

func (r *RedisClient) XReadGroup(ctx context.Context, stream, group, consumer string, count int64, block time.Duration) ([]StreamMessage, error)

XReadGroup 从消费者组读取消息

func (*RedisClient) XTrim added in v3.1.17

func (r *RedisClient) XTrim(ctx context.Context, stream string, maxLen int64) error

XTrim 按 maxlen 裁剪 Stream

func (*RedisClient) ZAdd added in v3.1.17

func (r *RedisClient) ZAdd(ctx context.Context, key string, members ...redis.Z) error

ZAdd 添加成员到有序集合

func (*RedisClient) ZCard added in v3.1.17

func (r *RedisClient) ZCard(ctx context.Context, key string) (int64, error)

ZCard 有序集合成员数量

func (*RedisClient) ZIncrBy added in v3.1.17

func (r *RedisClient) ZIncrBy(ctx context.Context, key string, increment float64, member string) (float64, error)

ZIncrBy 有序集合成员分数递增

func (*RedisClient) ZRangeByScore added in v3.1.17

func (r *RedisClient) ZRangeByScore(ctx context.Context, key string, opt *redis.ZRangeBy) ([]string, error)

ZRangeByScore 按分数范围获取有序集合成员

func (*RedisClient) ZRem added in v3.1.17

func (r *RedisClient) ZRem(ctx context.Context, key string, members ...any) error

ZRem 移除有序集合成员

func (*RedisClient) ZRevRangeByScore added in v3.1.17

func (r *RedisClient) ZRevRangeByScore(ctx context.Context, key string, opt *redis.ZRangeBy) ([]string, error)

ZRevRangeByScore 按分数范围倒序获取有序集合成员

func (*RedisClient) ZScore added in v3.1.17

func (r *RedisClient) ZScore(ctx context.Context, key string, member string) (float64, error)

ZScore 获取有序集合成员分数

type ResponseWriter

type ResponseWriter interface {
	http.ResponseWriter
	http.Hijacker
	http.Flusher

	// Returns the HTTP response status code of the current request.
	Status() int

	// Returns the number of bytes already written into the response http body.
	// See Written()
	Size() int

	// Writes the string into the response body.
	WriteString(string) (int, error)

	// Returns true if the response body was already written.
	Written() bool

	// Forces to write the http header (status code + headers).
	DoWriteHeader()

	// get the http.Pusher for server push
	Pusher() http.Pusher
}

ResponseWriter ...

type RestfulDefine

type RestfulDefine struct {
	Data    string
	Status  string
	Message string
	Code    any
}

type RotatingLogWriter added in v3.1.19

type RotatingLogWriter struct {
	// contains filtered or unexported fields
}

func NewRotatingLogWriter added in v3.1.19

func NewRotatingLogWriter(path string, opts ...string) (*RotatingLogWriter, error)

func NewRotatingLogWriterConfig added in v3.1.19

func NewRotatingLogWriterConfig(path string, cfg LogRotateConfig) (*RotatingLogWriter, error)

func (*RotatingLogWriter) Close added in v3.1.19

func (w *RotatingLogWriter) Close() error

func (*RotatingLogWriter) RedirectStdout added in v3.1.19

func (w *RotatingLogWriter) RedirectStdout() error

func (*RotatingLogWriter) Write added in v3.1.19

func (w *RotatingLogWriter) Write(p []byte) (int, error)

type RouteNode

type RouteNode struct {
	// contains filtered or unexported fields
}

RouteNode 压缩基数树节点。 每个节点的 path 可跨越多个路径段(如 "api/v1/"),实现 O(k) 前缀匹配。

type Router

type Router interface {
	Use(args ...any) Router

	GET(path string, handler any, middleware ...any) Router
	HEAD(path string, handler any, middleware ...any) Router
	POST(path string, handler any, middleware ...any) Router
	PUT(path string, handler any, middleware ...any) Router
	DELETE(path string, handler any, middleware ...any) Router
	CONNECT(path string, handler any, middleware ...any) Router
	OPTIONS(path string, handler any, middleware ...any) Router
	TRACE(path string, handler any, middleware ...any) Router
	PATCH(path string, handler any, middleware ...any) Router
	ALL(path string, handler any, middleware ...any) Router
	Group(prefix string, handlers ...HandlerFuncs) Router
	// contains filtered or unexported methods
}

Router defines all router handle interface, including app and group router.

type SModels added in v3.0.3

type SModels struct {
	ID        sid.ID          `json:"id,omitzero" gorm:"primaryKey;autoIncrement:false;comment:主键"`
	CreatedAt *time.Time      `json:"created_at,omitempty" gorm:"<-:create;comment:创建时间"`
	UpdatedAt *time.Time      `json:"updated_at,omitempty" gorm:"autoUpdateTime;comment:更新时间"`
	DeletedAt *gorm.DeletedAt `json:"deleted_at,omitempty" gorm:"index;comment:删除时间"`
}

func (*SModels) BeforeCreate added in v3.0.3

func (m *SModels) BeforeCreate(tx *DB) error

type StaticConfig added in v3.1.61

type StaticConfig struct {
	// MaxAge defaults to 7 days when zero; a negative value requests revalidation.
	MaxAge time.Duration
	// Immutable is only appropriate when changing content also changes its URL.
	// HTML always uses no-cache so entry documents can discover new assets.
	Immutable bool
}

StaticConfig opts a static mount into browser/CDN caching. Omit the config to retain the original behavior. Existing Cache-Control headers take precedence.

type StreamConsumer added in v3.1.17

type StreamConsumer struct {
	// contains filtered or unexported fields
}

func (*StreamConsumer) Run added in v3.1.17

func (c *StreamConsumer) Run(ctx context.Context, handler func(ctx context.Context, msg StreamMessage) error) error

Run 启动消费者(阻塞运行,直到 context 取消) handler 返回 nil 自动 ACK,返回 error 不 ACK(进入 pending 列表等待重试)

type StreamConsumerConfig added in v3.1.17

type StreamConsumerConfig struct {
	Stream     string        // Stream 名称
	Group      string        // 消费者组名称
	Consumer   string        // 消费者名称
	Count      int64         // 每次读取条数(默认 10)
	Block      time.Duration // 阻塞等待时间(默认 5s)
	ClaimIdle  time.Duration // 认领待处理消息的最小空闲时间(默认 30s,0 禁用)
	ClaimCount int64         // 每次认领的最大条数(默认 10)
	AutoAck    bool          // 处理成功是否自动 ACK(默认 true)
}

type StreamMessage added in v3.1.17

type StreamMessage struct {
	ID     string         // 消息 ID (如 "1672531200000-0")
	Fields map[string]any // 消息字段
}

StreamMessage 表示一条 Stream 消息

type StringOrNil

type StringOrNil string

空字符串 存入数据库 存 NULL ,这样会跳过数据库唯一索引的检查

func (*StringOrNil) Scan

func (s *StringOrNil) Scan(src any) error

implements sql.Scanner, will be invoked automatically when read from the db

func (StringOrNil) String

func (s StringOrNil) String() string

func (StringOrNil) Value

func (s StringOrNil) Value() (driver.Value, error)

implements driver.Valuer, will be invoked automatically when written to the db

type TypeConstraint

type TypeConstraint int16

TypeConstraint parameter constraint types

type UUID

type UUID struct {
	uuid.UUID
}

func ExtractUUIDs

func ExtractUUIDs[T HasUUID](items []T) []UUID

func MustUUID

func MustUUID(s string) UUID

func NewUUID

func NewUUID() UUID

NewUUID 使用默认随机源生成 UUID,不修改进程级随机池开关。

func ParseBytes

func ParseBytes(b []byte) (UUID, error)

ParseBytes is like Parse, except it parses a byte slice instead of a string.

func SafeToUUIDs

func SafeToUUIDs(items any) []UUID

SafeToUUIDs 安全地将任意类型转换为 []UUID

func ToUUIDsFromAny

func ToUUIDsFromAny(items []any) []UUID

ToUUIDsFromAny 把 []any 转换成 []UUID

func UUIDFromString

func UUIDFromString(s string) (UUID, error)

func (UUID) Bytes

func (u UUID) Bytes() []byte

func (UUID) GormDBDataType

func (UUID) GormDBDataType(db *gorm.DB, field *schema.Field) string

func (UUID) GormDataType

func (uuid UUID) GormDataType() string

GormDataType gorm common data type

func (UUID) IsEmpty

func (u UUID) IsEmpty() bool

func (UUID) MarshalBinary

func (u UUID) MarshalBinary() (data []byte, err error)

func (UUID) MarshalText

func (id UUID) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*UUID) Scan

func (uuid *UUID) Scan(src any) error

Scan implements sql.Scanner so UUIDs can be read from databases transparently. Currently, database types that map to string and []byte are supported. Please consult database-specific driver documentation for matching types.

func (UUID) String

func (u UUID) String() string

func (*UUID) UnmarshalBinary

func (u *UUID) UnmarshalBinary(data []byte) error

func (*UUID) UnmarshalText

func (uuid *UUID) UnmarshalText(data []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (UUID) Value

func (uuid UUID) Value() (driver.Value, error)

Value implements sql.Valuer so that UUIDs can be written to databases transparently. Currently, UUIDs map to strings. Please consult database-specific driver documentation for matching types.

type Writers

type Writers struct{}

func (Writers) Printf

func (Writers) Printf(f string, args ...any)

Directories

Path Synopsis
Package certificate 提供由业务授权的精确域名证书管理,不在握手中触发签发。
Package certificate 提供由业务授权的精确域名证书管理,不在握手中触发签发。
cmd
corectl command
coregen command
* KV 存储相关方法 提供对etcd KV存储的封装,包括Put、Get等操作
* KV 存储相关方法 提供对etcd KV存储的封装,包括Put、Get等操作
example
grpc-cookie
Package grpccookie provides copyable response scaffolding for gRPC auth handlers.
Package grpccookie provides copyable response scaffolding for gRPC auth handlers.
restful command
standard/cmd command
standard/internal/app
Package app owns dependency assembly.
Package app owns dependency assembly.
standard/internal/domain/user
Package user defines protocol-independent business errors.
Package user defines protocol-independent business errors.
standard/internal/models
Code generated by core.
Code generated by core.
websocket command
work command
internal
grpchttp
Package grpchttp defines the explicit response metadata contract shared by Core gRPC helpers and the HTTP Gateway.
Package grpchttp defines the explicit response metadata contract shared by Core gRPC helpers and the HTTP Gateway.
logbridge
Package logbridge lets independent clients use Core's configured logger without importing the application, database, discovery, or server packages.
Package logbridge lets independent clients use Core's configured logger without importing the application, database, discovery, or server packages.
responsecompression
Package responsecompression shares streaming response behavior between codecs.
Package responsecompression shares streaming response behavior between codecs.
middleware
bodylimit
Package bodylimit 限制请求体大小,防止恶意大 Body 导致 OOM。
Package bodylimit 限制请求体大小,防止恶意大 Body 导致 OOM。
brotli
Package brotli provides opt-in streaming Brotli HTTP response compression.
Package brotli provides opt-in streaming Brotli HTTP response compression.
compress
Package compress negotiates zstd, Brotli and gzip response compression.
Package compress negotiates zstd, Brotli and gzip response compression.
etag
Package etag provides conditional responses using representation validators.
Package etag provides conditional responses using representation validators.
gzip
Package gzip provides opt-in streaming HTTP response compression.
Package gzip provides opt-in streaming HTTP response compression.
monitor
Package monitor 提供服务器运行时监控插件,暴露 CPU、内存、文件句柄、连接数等指标。
Package monitor 提供服务器运行时监控插件,暴露 CPU、内存、文件句柄、连接数等指标。
otel
Package otel 提供 OpenTelemetry Trace 上下文传播中间件。
Package otel 提供 OpenTelemetry Trace 上下文传播中间件。
security
Package security 提供安全 HTTP 响应头中间件,设置 HSTS、CSP、X-Content-Type-Options 等。
Package security 提供安全 HTTP 响应头中间件,设置 HSTS、CSP、X-Content-Type-Options 等。
timeout
Package timeout 提供请求超时控制中间件。
Package timeout 提供请求超时控制中间件。
zstd
Package zstd provides opt-in streaming HTTP response compression.
Package zstd provides opt-in streaming HTTP response compression.
Package reuseport provides TCP net.Listener with SO_REUSEPORT support.
Package reuseport provides TCP net.Listener with SO_REUSEPORT support.
Package tcplisten provides customizable TCP net.Listener with various performance-related options:
Package tcplisten provides customizable TCP net.Listener with various performance-related options:

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址