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/v3package 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。
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=disablego 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 --checknew 只创建新目录,生成 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 单文件方式保留,详见 枚举生成。
应用是框架的核心,负责管理路由、中间件和服务器。
// 创建应用
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")
})上下文对象封装了 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 模块。
在 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 保留 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")
}处理器是业务逻辑的载体,通过嵌入 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))
}框架支持自动路由注册,基于方法名和注释生成路由。
| 关键字 | 路由规则 | 结果 |
|---|---|---|
| Param | 参数关键词 | :param |
| Params | 参数关键词 | :params? |
| _id | 下划线 | /:id |
| By | 参数关键字 | /: |
| __ | 中横线 | - |
| __dot__ | 点 | . |
Params 是可选关键词 即:params?
Get→GET /GetParam→GET /:paramGetParams→GET /:params?GetByID→GET /:idGetDetailParam→GET /detail/:paramPostUser→POST /userPutUserParam→PUT /user/:paramGetUserByID→GET /user/:idGetUser__Create→GET /user-createGetUser__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)
}框架集成了 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{})
}框架支持灵活的中间件系统。
// 自定义中间件
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()
_ = statsmonitor.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;不同磁盘分别聚合,未取得主机身份时为空,不包含监控路径。
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。测试与样本性能对比见 统一压缩性能报告。
// 推荐统一协商: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/其它代理不会缓冲,生产链路需单独验证。见 流式压缩验证与性能报告。
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 值优先选择,只由先处理正文的中间件决定编码,已有编码阻止重复压缩。
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 需同步支持该方法。
框架集成了 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
}
// 业务逻辑
// ...
}// 单文件上传
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)
}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"}`))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
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{...},
})
}Core 支持同时运行 HTTP 与 gRPC,并通过 etcd 做服务注册、服务发现和网关动态路由。推荐把链路拆成三类程序理解:
- 业务服务:启动 HTTP 或注册 protobuf 生成的 gRPC service,并把实例及对外路由发布到 etcd。
- 内部客户端:通过
app.GrpcClient("service-name")按服务名发现并调用 gRPC。 - 网关服务:监听 etcd 实例和路由变化,把 HTTP 请求代理到 HTTP 或 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)
}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之前调用。
内部服务调用优先使用 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)网关服务只需要连接 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 |
删除路由 |
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。具体时机如下:
- Go
init阶段的core.RegHandle只登记 Handler 模块,不访问 etcd。 EnableEtcdRegistry创建 Registry,复用相同配置的 Discovery,以每进程唯一generation和ready=false注册。Gateway 暂不选用准备态实例。Listen/Run启动准备阶段加载 Handler,方法名路由在这里生成并进入自动目录。- 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 的手动路由优先于自动路由。
网关通过 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。
除了自动注册,也可以通过管理接口写入路由配置。
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
}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:
authorizationx-request-idx-user-idCtx.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。
仓库内置了几个最小 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
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
})
}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")// 链式查询
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)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。
共享 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,
})
}游标模式只读取 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 合并。
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 会多查一条数据判断 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": []
}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)
}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
}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.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"包级快捷方法使用 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")
_ = tokenPOST / 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)业务服务中推荐创建可复用 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)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)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)使用 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排查外部 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,生产环境只应在定位问题时短期开启。
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)
}database:
type: mysql
dsn: user:pass@tcp(localhost:3306)/dbname
pool:
max_idle: 10 # 最大空闲连接数
max_open: 100 # 最大打开连接数
max_lifetime: 1h # 连接最大生命周期prefork: true # 启用多进程模式,充分利用多核CPUGitHub 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=10go build -o app ./cmd# /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.targetFROM 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"]问题: 处理器方法已定义,但路由不生效。
解决方案:
- 确保处理器嵌入了
core.Handler - 确保在
init()函数中调用core.RegHandle() - 检查方法名是否符合路由规则
- 查看日志确认路由注册情况
问题: 数据库连接失败,返回错误。
解决方案:
- 检查
config.yaml中的数据库配置 - 确认数据库服务是否运行
- 检查连接字符串格式是否正确
- 查看数据库日志获取详细错误信息
问题: 前端请求被浏览器阻止,提示跨域错误。
解决方案:
- 启用 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...)。
问题: 上传大文件时失败。
解决方案:
- 调整最大文件大小限制
app := core.New(core.Options{
"max_body_size": "10MB", // 10MB 限制
})| 方法 | 说明 | 示例 |
|---|---|---|
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;空列表默认私网/回环,非空覆盖默认规则;非法配置初始化报错 |
使用 统一项目架构,不要在 main、Handler 构造器和 DAO 构造器分散装配。Service 使用标准 context,HTTP 传 c.Ctx(),gRPC 传 RPC context; 由协议层映射业务错误,事务在 Service 开启,迁移显式执行。 已有项目按文档迁移并保持接口、表名与启动参数兼容,不由生成器自动搬迁。
// 定义业务错误
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)
}// 方式一:始终输出请求日志。
// 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,
}))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())
},
}))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
}
}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"])
}本文档描述
github.com/xs23933/core/v3框架的路由自动注册机制。
type UserHandler struct {
core.Handler // 必须嵌入 core.Handler
// ... 依赖字段
}- Handler 结构体名以
Handler结尾 - 框架自动注册时会去掉
Handler后缀作为路由组名 - 例:
UserHandler→ 路由组前缀为/user(可通过Init()覆盖)
HTTP 方法前缀 + 路径片段(驼峰命名):
| 方法名前缀 | HTTP 方法 |
|---|---|
Get |
GET |
Post |
POST |
Put |
PUT |
Delete |
DELETE |
Patch |
PATCH |
All |
ALL |
| 字符特征 | 转换结果 | 示例 |
|---|---|---|
| 大写字母开头 | 路径片段 /xxx |
Profile → /profile |
| 下划线 + 小写字母 | 路径参数 :xxx |
_id → :id |
Param(固定关键字) |
路径参数 :param |
Param → :param |
Params(固定关键字) |
可选参数 :param? |
Params → :param? |
每个大写字母开头的片段都会生成一个新的路径层级:
// 方法名 → 路由
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 是路径片段,不是参数!)下划线开头 + 小写字母 = 自定义路径参数名:
// 方法名 → 路由
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/profileParam 和 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")获取
// 路由: 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"
// ...
}// 路由: 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"
// ...
}框架根据 Handler 名称自动推断前缀:
type UserHandler struct { core.Handler }
// 默认前缀: /user
type OAuthHandler struct { core.Handler }
// 默认前缀: /oauth在 Init() 方法中使用 Prefix() 设置:
func (h *OAuthHandler) Init() {
h.Prefix("/api/v1/oauth")
}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 | 必选参数缺失 |
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 函数进行命名转换:
转换逻辑:
- 提取 HTTP 方法前缀(
Get/Post/Put/Delete/Patch) - 遍历剩余字符:
- 大写字母 → 新路径片段(转小写)
_+ 小写字母 → 自定义路径参数Param(关键字)→:paramParams(关键字)→: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 |
// ❌ 错误:期望 /:id,实际得到 /id
func (h *Handler) GetId(c core.Ctx) error {}
// GET /id (Id 是路径片段,不是参数)
// ✅ 正确:使用下划线定义参数
func (h *Handler) GetByID(c core.Ctx) error {}
// GET /:id// ❌ 错误:期望可选参数,实际是必选
func (h *Handler) GetParam(c core.Ctx) error {}
// GET /:param (必选)
// ✅ 正确:使用 Params 表示可选
func (h *Handler) GetParams(c core.Ctx) error {}
// GET /: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") 获取框架启动时会打印所有注册的路由:
[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
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 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 与运行行为不因本次文档整理改变。
- 精简 AGENTS/AI_CONTEXT,Handler/Ctx 采用统一的任务、规则、示例、边界和验证结构,保留完整参考。
- 提供从规则和真实 Handler 源码生成的离线 8k 任务包、预算说明及 CI 漂移检查;未进行本地模型效果评测。
- 包含 v3.1.72 后已合入的 Gateway protobuf repeated query 解析修正(含数量边界)。
- 统一下游项目的
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 分发。
- 修复 HTTP 路由树未应用
case-sensitive: false的问题,支持/transferIn与/transferin兼容;默认保持大小写敏感。 - 保留参数名、参数值、query 和原始 URL,统一注册、中间件、Group 及移除行为,并补充回归测试。
- 完善 WebSocket 可运行示例,修正队列释放测试命名。
- 支持 Go 1.24
- 性能优化,提升 30% 吞吐量
- 新增 WebSocket 支持
- 改进中间件系统
- 增强数据库支持
- 引入自动路由注册
- 支持多数据库连接
- 改进错误处理机制
- 新增文件上传功能
- 初始版本发布
- 基础路由功能
- 数据库集成
- 中间件支持
欢迎贡献代码!请遵循以下步骤:
- Fork 项目仓库
- 创建功能分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add some amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
本项目采用 MIT 许可证。详见 LICENSE 文件。
文档最后更新: 2026-03-31 Core Framework v3.0.0
通过 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 共享文件。指纹必须由可信部署渠道预置,详见工作负载说明。
需要有限自动处理且保留原消息时,显式设置 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 和原命令键恢复仍由调用方负责。
未注册 ExactJSONBinding 的默认 Gateway 对 gRPC 响应仅补齐顶层 proto 原名为 code、不带 presence 的单值整数字段:零值仍输出 code: 0;64 位整数按 ProtoJSON 输出 code: "0"。非零值保持原值。未定义 code、optional/proto2/oneof、其他类型及嵌套 code 保持原序列化语义。不会补齐 error、data 或空数组,不会添加响应外层;HTTP 反向代理和普通 HTTP Handler 不受影响。已有接口若依赖零值 code 缺省,需要适配此响应变化。
自 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 错误映射及现有读请求重试规则继续使用公共链路;写请求不重放。
内置引擎预占回环临时端口,并将 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(Cloudflare DNS-01)与旧版 on-demand 模式为每个 Core 实例创建独立缓存,后台维护复用该实例的存储和签发配置;certmagic.cache 默认 ./certs,服务用户必须可写。启动失败和 Core 关闭时停止维护缓存。外部 Caddy/Nginx 若手动加载这些 PEM 文件,必须在续期后重新加载;Core 更新文件不会刷新其它进程的证书缓存。
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: 8388608middleware/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 的普通 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启动顺序兼容边界:未实现 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,保留 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 连接数判断健康。