mirrors/xlgo-core
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-14 10:24:10 +08:00
commit e00aa620f9
161 changed files with 43937 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+16
View File
@@ -0,0 +1,16 @@
# Claude Code 协作指引（本地，不入库）
CLAUDE.md
AGENTS.md
# 临时发版辅助文件
gitHub_release_*.md
# 构建产物
*.exe
bin/
md/
.gocache/
gpt_check_report_framework.md
gpt_check_report_review.md
gpt_check_report_module.md
CHANGELOG.md
+1141
View File
File diff suppressed because it is too large Load Diff
GUIDE.md
+1894
View File
File diff suppressed because it is too large Load Diff
LICENSE
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Ethan xlp
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Makefile
+34
View File
@@ -0,0 +1,34 @@
.PHONY: build run test clean tidy docker
# 构建二进制文件
build:
go build -o bin/server ./example
# 开发模式运行
run:
go run ./example
# 运行测试
test:
go test ./...
# 清理
clean:
rm -rf bin/
rm -rf logs/
# 安装依赖
tidy:
go mod tidy
# 生成 Swagger 文档
swagger:
swag init -g example/main.go -o example/swagger
# Docker 构建
docker:
docker build -t xlgo-app:latest .
# Docker 运行
docker-run:
docker run -d -p 8080:8080 xlgo-app:latest
README.md
+1117
View File
File diff suppressed because it is too large Load Diff
README.wehub.md
+7
View File
@@ -0,0 +1,7 @@
# WeHub 来源说明
- 原始项目：`frostbyte_neo/xlgo-core`
- 原始仓库：https://gitea-dev.autobee.pro/frostbyte_neo/xlgo-core
- 导入方式：上游默认分支的最新快照
- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
- 本文件仅用于记录来源，不代表 WeHub 是原项目作者
app.go
+1364
View File
File diff suppressed because it is too large Load Diff
app_cache_test.go
+131
View File
@@ -0,0 +1,131 @@
package xlgo_test
import (
"context"
"errors"
"net"
"strconv"
"testing"
"time"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/cache"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/alicebob/miniredis/v2"
)
func splitAddr(t *testing.T, addr string) (string, int) {
t.Helper()
host, portStr, err := net.SplitHostPort(addr)
if err != nil {
t.Fatalf("SplitHostPort %q: %v", addr, err)
}
port, err := strconv.Atoi(portStr)
if err != nil {
t.Fatalf("Atoi port %q: %v", portStr, err)
}
if host == "" {
host = "127.0.0.1"
}
return host, port
}
// TestAppCacheMultiAppRedisIsolation 固化 Phase 4 核心契约：单进程多 App 时，每个 App 的
// 缓存走自己的 redisManager.Client()，互不串越。修复前 cache 硬编码 database.GetRedis()
// （全局），App B swap 后 App A 的缓存会读到 App B 的 redis。
//
// 用两个 miniredis 实例分别作 App A/B 的 Redis 后端，断言各自 cache 只写自己的实例、
// 互读对方的 key 为 miss。appA.Cache()/appB.Cache() 绕过全局 facade 直取 App 实例。
func TestAppCacheMultiAppRedisIsolation(t *testing.T) {
mrA := miniredis.RunT(t)
mrB := miniredis.RunT(t)
hostA, portA := splitAddr(t, mrA.Addr())
hostB, portB := splitAddr(t, mrB.Addr())
cfgA := testConfig(18120)
cfgA.Redis = config.RedisConfig{Host: hostA, Port: portA}
cfgB := testConfig(18121)
cfgB.Redis = config.RedisConfig{Host: hostB, Port: portB}
appA := xlgo.New(xlgo.WithConfig(cfgA), xlgo.WithRedis())
if err := appA.Init(); err != nil {
t.Fatalf("appA Init: %v", err)
}
defer appA.Shutdown()
appB := xlgo.New(xlgo.WithConfig(cfgB), xlgo.WithRedis())
if err := appB.Init(); err != nil {
t.Fatalf("appB Init: %v", err)
}
defer appB.Shutdown()
if appA.Cache() == nil || appB.Cache() == nil {
t.Fatal("app.Cache() = nil after Init with WithRedis")
}
ctx := context.Background()
// A 写 keyA -> 仅落 miniredisA
if err := appA.Cache().Set(ctx, "keyA", "valA", time.Minute); err != nil {
t.Fatalf("appA cache Set: %v", err)
}
if !mrA.Exists("keyA") {
t.Error("keyA not in miniredisA (appA redis)")
}
if mrB.Exists("keyA") {
t.Error("keyA leaked into miniredisB (appB redis) -- cache not isolated")
}
// B 写 keyB -> 仅落 miniredisB
if err := appB.Cache().Set(ctx, "keyB", "valB", time.Minute); err != nil {
t.Fatalf("appB cache Set: %v", err)
}
if !mrB.Exists("keyB") {
t.Error("keyB not in miniredisB (appB redis)")
}
if mrA.Exists("keyB") {
t.Error("keyB leaked into miniredisA (appA redis) -- cache not isolated")
}
// 互读对方 key -> miss（各自走自己的 redis）
var got string
if ok, err := appA.Cache().Get(ctx, "keyB", &got); ok || err != nil {
t.Errorf("appA cache should miss keyB (different redis): ok=%v err=%v", ok, err)
}
if ok, err := appB.Cache().Get(ctx, "keyA", &got); ok || err != nil {
t.Errorf("appB cache should miss keyA (different redis): ok=%v err=%v", ok, err)
}
// 各自读自己的 key -> hit
if ok, err := appA.Cache().Get(ctx, "keyA", &got); err != nil || !ok || got != "valA" {
t.Errorf("appA cache Get keyA = %v %q err=%v (want true valA)", ok, got, err)
}
if ok, err := appB.Cache().Get(ctx, "keyB", &got); err != nil || !ok || got != "valB" {
t.Errorf("appB cache Get keyB = %v %q err=%v (want true valB)", ok, got, err)
}
}
// TestAppCacheRollbackOnInitFailure 固化 Phase 4 回滚：Init 失败后全局默认 CacheManager
// 必须恢复为 Init 前的实例。
func TestAppCacheRollbackOnInitFailure(t *testing.T) {
preInit := cache.NewCacheManager()
saved := cache.SwapDefaultCacheManager(preInit) // saved = init 默认；preInit 现为全局
defer cache.SwapDefaultCacheManager(saved)
mr := miniredis.RunT(t)
host, port := splitAddr(t, mr.Addr())
cfg := testConfig(18122)
cfg.Redis = config.RedisConfig{Host: host, Port: port}
app := xlgo.New(
xlgo.WithConfig(cfg),
xlgo.WithRedis(),
xlgo.WithHook(xlgo.Hook{Name: "fail", OnInit: func(*xlgo.App) error { return errors.New("boom") }}),
)
if err := app.Init(); err == nil {
_ = app.Shutdown()
t.Fatal("expected Init to fail via OnInit hook")
}
if cache.GetDefaultCache() != preInit {
t.Fatal("rollback did not restore preInit cache manager as global default")
}
}
app_config_test.go
+60
View File
@@ -0,0 +1,60 @@
package xlgo_test
import (
"os"
"path/filepath"
"runtime"
"testing"
"time"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/config"
)
// TestAppShutdownStopsConfigWatcher_Mconfig3 固化 M-config-3：App.Shutdown 须停止其
// configManager 的热重载 watcher，避免关闭后遗留监听 goroutine（违反 C7 生命周期契约）。
//
// Init 后 resolveConfig 把 a.configManager 提升为全局默认，故经包级 config.StartWatcher
// 在其上启动 watcher（等价于用户对 configManager 调 LoadWithWatch/StartWatcher）；
// Shutdown 后断言 watchLoop goroutine 已退出。
func TestAppShutdownStopsConfigWatcher_Mconfig3(t *testing.T) {
dir := filepath.Join(os.TempDir(), "xlgo_app_mconfig3")
if err := os.MkdirAll(dir, 0755); err != nil {
t.Fatalf("MkdirAll: %v", err)
}
defer os.RemoveAll(dir)
cfgPath := filepath.Join(dir, "config.yaml")
if err := os.WriteFile(cfgPath, []byte("app:\n name: m3\n env: dev\nserver:\n port: 18080\n"), 0644); err != nil {
t.Fatalf("WriteFile: %v", err)
}
app := xlgo.New(xlgo.WithConfigPath(cfgPath))
if err := app.Init(); err != nil {
t.Fatalf("Init: %v", err)
}
// 经全局默认（=a.configManager）启动 watcher，模拟用户开启热重载
if err := config.StartWatcher(); err != nil {
t.Fatalf("StartWatcher: %v", err)
}
defer config.SetDefaultManager(nil)
time.Sleep(120 * time.Millisecond) // 等 watchLoop 就绪
before := runtime.NumGoroutine()
if err := app.Shutdown(); err != nil {
t.Fatalf("Shutdown: %v", err)
}
// watchLoop goroutine 应随 Shutdown 退出
deadline := time.Now().Add(2 * time.Second)
for time.Now().Before(deadline) {
if runtime.NumGoroutine() < before {
break
}
time.Sleep(20 * time.Millisecond)
}
if after := runtime.NumGoroutine(); after >= before {
t.Errorf("App.Shutdown 未停止 config watcher（M-config-3）: before=%d after=%d", before, after)
}
}
app_cron_test.go
+135
View File
@@ -0,0 +1,135 @@
package xlgo_test
import (
"context"
"errors"
"sync/atomic"
"testing"
"time"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/cron"
)
// TestAppCronSchedulerInstance 固化 Phase 3：WithCronTask 把任务注册到 App 专属调度器，
// app.Scheduler() 返回该实例且含注册的任务。
func TestAppCronSchedulerInstance(t *testing.T) {
saved := cron.SwapDefaultScheduler(cron.NewScheduler())
defer cron.SwapDefaultScheduler(saved)
app := xlgo.New(
xlgo.WithConfig(testConfig(18112)),
xlgo.WithCronTask("my-task", cron.Every(time.Hour), func(context.Context) error { return nil }),
)
if err := app.Init(); err != nil {
t.Fatalf("Init: %v", err)
}
defer app.Shutdown()
s := app.Scheduler()
if s == nil {
t.Fatal("app.Scheduler() = nil after Init with WithCronTask")
}
found := false
for _, tk := range s.ListTasks() {
if tk.Name == "my-task" {
found = true
break
}
}
if !found {
t.Fatal("WithCronTask task not registered on App scheduler")
}
}
// TestAppCronRollbackRestoresDefault 固化 Phase 3 回滚：Init 失败后全局默认调度器
// 必须恢复为 Init 前的实例（不含 App 注册的任务），而非残留 App 的调度器。
func TestAppCronRollbackRestoresDefault(t *testing.T) {
saved := cron.SwapDefaultScheduler(cron.NewScheduler())
defer cron.SwapDefaultScheduler(saved)
app := xlgo.New(
xlgo.WithConfig(testConfig(18113)),
xlgo.WithCronTask("rollback-task", cron.Every(time.Hour), func(context.Context) error { return nil }),
xlgo.WithHook(xlgo.Hook{Name: "fail", OnInit: func(*xlgo.App) error { return errors.New("boom") }}),
)
if err := app.Init(); err == nil {
_ = app.Shutdown()
t.Fatal("expected Init to fail via OnInit hook")
}
// 回滚后全局默认不应含 App 的 "rollback-task"
for _, tk := range cron.GetScheduler().ListTasks() {
if tk.Name == "rollback-task" {
t.Fatal("rollback did not restore global default scheduler (App task still on global)")
}
}
}
// TestAppCronMultiAppIsolation 固化 Phase 3 核心契约：单进程多 App 时，App A 的 Shutdown
// 只停 A 自己的调度器，不影响 App B 的调度器继续运行（修复前 cron 是全局单例，A.Shutdown
// 会经 cron.StopGlobalWithTimeout 把 B 的调度器也停了）。
//
// 调度器内部 ticker 为 1s，故任务每 1s tick 触发一次（schedule=Every(1ms) 仅决定 due 判定，
// 实际 spawn 受 1s ticker 节拍）。测试因此需要跨 1s tick 观测。
func TestAppCronMultiAppIsolation(t *testing.T) {
saved := cron.SwapDefaultScheduler(cron.NewScheduler())
defer cron.SwapDefaultScheduler(saved)
var ranA, ranB atomic.Int32
appA := xlgo.New(
xlgo.WithConfig(testConfig(18110)),
xlgo.WithCronTask("taskA", cron.Every(time.Millisecond), func(context.Context) error {
ranA.Add(1)
return nil
}),
)
appB := xlgo.New(
xlgo.WithConfig(testConfig(18111)),
xlgo.WithCronTask("taskB", cron.Every(time.Millisecond), func(context.Context) error {
ranB.Add(1)
return nil
}),
)
if err := appA.Init(); err != nil {
t.Fatalf("appA Init: %v", err)
}
if err := appB.Init(); err != nil {
t.Fatalf("appB Init: %v", err)
}
defer appB.Shutdown()
// 轮询等第一个 1s tick：两个调度器都应各跑至少一次（deadline 3s，容忍慢机/CI 漂移）
deadline := time.Now().Add(3 * time.Second)
for time.Now().Before(deadline) {
if ranA.Load() > 0 && ranB.Load() > 0 {
break
}
time.Sleep(50 * time.Millisecond)
}
aAtTick := ranA.Load()
bAtTick := ranB.Load()
if aAtTick == 0 || bAtTick == 0 {
t.Fatalf("expected both schedulers ran at least once: A=%d B=%d", aAtTick, bAtTick)
}
// 停 App A
if err := appA.Shutdown(); err != nil {
t.Fatalf("appA Shutdown: %v", err)
}
// 轮询等 B 再跑一次（deadline 3s），证明 B 调度器未被 A.Shutdown 停掉
deadline = time.Now().Add(3 * time.Second)
for time.Now().Before(deadline) {
if ranB.Load() > bAtTick {
break
}
time.Sleep(50 * time.Millisecond)
}
if ranA.Load() != aAtTick {
t.Errorf("App A scheduler ran after its Shutdown (not isolated): before=%d after=%d", aAtTick, ranA.Load())
}
if ranB.Load() <= bAtTick {
t.Errorf("App B scheduler did not continue after App A Shutdown (not isolated): before=%d after=%d", bAtTick, ranB.Load())
}
}
app_go_test.go
+43
View File
@@ -0,0 +1,43 @@
package xlgo_test
import (
"context"
"testing"
"time"
xlgo "github.com/EthanCodeCraft/xlgo-core"
)
func TestAppGoWaitsOnShutdown(t *testing.T) {
app := xlgo.New()
started := make(chan struct{})
exited := make(chan struct{})
app.Go(func(ctx context.Context) {
close(started)
<-ctx.Done()
// 模拟收尾
time.Sleep(10 * time.Millisecond)
close(exited)
})
<-started
// Shutdown 应 cancel ctx 并等待 goroutine 退出
done := make(chan error, 1)
go func() { done <- app.Shutdown() }()
select {
case <-exited:
// goroutine 在 cancel 后退出，符合预期
case <-time.After(2 * time.Second):
t.Fatal("App.Go goroutine did not exit after Shutdown cancel")
}
select {
case err := <-done:
if err != nil {
t.Errorf("Shutdown returned error: %v", err)
}
case <-time.After(2 * time.Second):
t.Fatal("Shutdown did not return")
}
}
app_hdb1_test.go
+116
View File
@@ -0,0 +1,116 @@
package xlgo_test
import (
"context"
"database/sql"
"database/sql/driver"
"errors"
"sync"
"testing"
"time"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/database"
"gorm.io/gorm"
"gorm.io/gorm/clause"
"gorm.io/gorm/schema"
)
// appHungDriver 是测试用 database/sql 驱动，Conn.Ping 阻塞到 ctx 取消，模拟挂起 DB。
// 与 database 包内部的 hungDriver 同构（app_test 为外部包，需自带一份）。
type appHungDriver struct{}
func (appHungDriver) Open(string) (driver.Conn, error) { return appHungConn{}, nil }
type appHungConn struct{}
func (appHungConn) Prepare(string) (driver.Stmt, error) { return nil, errors.New("hung: not implemented") }
func (appHungConn) Close() error { return nil }
func (appHungConn) Begin() (driver.Tx, error) { return nil, errors.New("hung: not implemented") }
// Ping 阻塞到 ctx 取消（实现 driver.Pinger，方法名 Ping 而非 PingContext）。
func (appHungConn) Ping(ctx context.Context) error {
<-ctx.Done()
return ctx.Err()
}
var appHungRegisterOnce sync.Once
func registerAppHungDialect() {
appHungRegisterOnce.Do(func() {
sql.Register("xlgo_app_hung_hdb1", appHungDriver{})
database.RegisterDialect(database.DialectSpec{
Name: "app_hung_hdb1",
Dialector: func(string) gorm.Dialector {
db, _ := sql.Open("xlgo_app_hung_hdb1", "")
return appHungDialector{sqlDB: db}
},
DSN: func(*config.DatabaseConfig) string { return "app_hung://" },
})
})
}
// appHungDialector 让 gorm.Open 成功并注入挂起 *sql.DB，使 initDB 的 pingWithTimeout 触发。
type appHungDialector struct{ sqlDB *sql.DB }
func (d appHungDialector) Name() string { return "app_hung_hdb1" }
func (d appHungDialector) Initialize(db *gorm.DB) error { db.Config.ConnPool = d.sqlDB; return nil }
func (d appHungDialector) Migrator(*gorm.DB) gorm.Migrator { return nil }
func (d appHungDialector) DataTypeOf(*schema.Field) string { return "" }
func (d appHungDialector) DefaultValueOf(*schema.Field) clause.Expression { return nil }
func (d appHungDialector) BindVarTo(clause.Writer, *gorm.Statement, any) {}
func (d appHungDialector) QuoteTo(w clause.Writer, s string) { _, _ = w.WriteString(s) }
func (d appHungDialector) Explain(s string, _ ...any) string { return s }
// TestAppInitHungDBBounded_Hdb1 端到端回归 H-db-1（App 级闭环）：
// App.Init 启用 MySQL 且 DB 挂起时，initDB 的 pingWithTimeout 3s 失败 -> InitDB 返回错误
// -> App.Init 失败（failAfterInit 回滚）。全程有界，不因挂起 DB 无限卡死 App.Init。
// 修复前 gorm.Open 的 automatic Ping() 在 pingWithTimeout 之前就无限阻塞 -> App.Init 永久 hang。
// 同时验证 App.Init 失败后无 goroutine 泄漏（closeResources 正常）。
func TestAppInitHungDBBounded_Hdb1(t *testing.T) {
registerAppHungDialect()
cfg := &config.Config{
App: config.AppConfig{Env: "test"},
Server: config.ServerConfig{Port: 18091},
Database: config.DatabaseConfig{
Driver: "app_hung_hdb1",
Host: "localhost", Port: 3306, User: "u", Password: "p", Name: "n",
},
}
app := xlgo.New(xlgo.WithConfig(cfg), xlgo.WithMySQL())
done := make(chan error, 1)
start := time.Now()
go func() { done <- app.Init() }()
select {
case err := <-done:
elapsed := time.Since(start)
if err == nil {
t.Fatalf("挂起 DB 下 App.Init 应失败，got nil")
}
// initDB pingWithTimeout 3s 失败后重试 5 次（每次 ping 3s + retryDelay 1s 起步翻倍），
// 全跑约 5*4s=20s+。放宽到 35s 上限。关键是不触发下方 45s watchdog 的"无限阻塞"。
if elapsed > 35*time.Second {
t.Fatalf("App.Init 耗时 %v 超过 35s 上限（H-db-1：initDB ping 应被 3s 约束，重试 5 次应 ~20s）", elapsed)
}
case <-time.After(45 * time.Second):
t.Fatalf("App.Init 在挂起 DB 上无限阻塞（H-db-1：gorm.Open automatic ping 或 initDB ping 未被超时约束）")
}
// App.Init 失败后应能正常 Shutdown（failAfterInit 已回滚资源，Shutdown 幂等）。
shutdownDone := make(chan error, 1)
go func() { shutdownDone <- app.Shutdown() }()
select {
case err := <-shutdownDone:
if err != nil {
t.Logf("App.Shutdown after failed Init returned err: %v（可接受，资源已回滚）", err)
}
case <-time.After(10 * time.Second):
t.Fatalf("App.Shutdown 在 Init 失败后无限阻塞（closeResources 未正常收口）")
}
// rootCtx 已被 failAfterInit cancel，无残留 goroutine（StartProbing 未启动因 Init 失败）。
// 此处不直接断言 goroutine 数（受测试 runtime 噪声影响），靠 Shutdown 有界退出间接证明。
_ = context.Background()
}
app_m1_test.go
+463
View File
@@ -0,0 +1,463 @@
package xlgo_test
import (
"context"
"errors"
"net"
"os"
"path/filepath"
"runtime"
"strings"
"sync"
"sync/atomic"
"testing"
"time"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/cron"
"github.com/EthanCodeCraft/xlgo-core/logger"
"gorm.io/gorm"
)
// TestAppGoAddWaitRace_M1 回归（须 -race）：App.Go 的 wg.Add 与 Shutdown 的 wg.Wait 并发，
// 必须由 lifecycleMu 串行化（Add happens-before Wait），否则违反 WaitGroup 契约。
// 修复前：-race 报 wg.Add/wg.Wait data race 或 "negative WaitGroup counter" panic。
func TestAppGoAddWaitRace_M1(t *testing.T) {
const M = 20
const iters = 20
for iter := 0; iter < iters; iter++ {
app := xlgo.New()
var spawned, exited atomic.Int32
gate := make(chan struct{})
var goDone sync.WaitGroup
goDone.Add(M)
for i := 0; i < M; i++ {
go func() {
<-gate
app.Go(func(ctx context.Context) {
spawned.Add(1)
<-ctx.Done()
exited.Add(1)
})
goDone.Done()
}()
}
shutCh := make(chan error, 1)
go func() {
<-gate
shutCh <- app.Shutdown()
}()
close(gate)
goDone.Wait()
err := <-shutCh
if err != nil {
t.Fatalf("iter %d: Shutdown error: %v", iter, err)
}
sp, ex := spawned.Load(), exited.Load()
if sp != ex {
t.Fatalf("iter %d: spawned %d != exited %d (goroutine leak / Add-after-Wait)", iter, sp, ex)
}
}
}
// TestAppGoRefusedAfterShutdown_M1：Shutdown 后 Go() 必须拒绝（state>=Stopping），不 spawn。
func TestAppGoRefusedAfterShutdown_M1(t *testing.T) {
app := xlgo.New(xlgo.WithConfig(testConfig(18102)))
if err := app.Shutdown(); err != nil {
t.Fatalf("Shutdown: %v", err)
}
ran := make(chan struct{}, 1)
app.Go(func(context.Context) { ran <- struct{}{} })
time.Sleep(50 * time.Millisecond) // 给可能被 spawn 的 goroutine 时间发送
select {
case <-ran:
t.Fatal("Go ran after Shutdown — should be refused (state=Stopping)")
default:
}
}
// TestAppInitAfterShutdownRejected_M1（Edge 1）：Shutdown 后再 Init 必须返 ErrAppClosed。
func TestAppInitAfterShutdownRejected_M1(t *testing.T) {
app := xlgo.New(xlgo.WithConfig(testConfig(18101)))
if err := app.Shutdown(); err != nil {
t.Fatalf("Shutdown: %v", err)
}
if err := app.Init(); !errors.Is(err, xlgo.ErrAppClosed) {
t.Fatalf("Init after Shutdown err = %v, want ErrAppClosed", err)
}
}
// TestAppShutdownIdempotent_M1：并发 Shutdown 幂等，OnStop 仅执行一次。
func TestAppShutdownIdempotent_M1(t *testing.T) {
var stopCount atomic.Int32
app := xlgo.New(
xlgo.WithConfig(testConfig(18100)),
xlgo.WithHook(xlgo.Hook{Name: "count-stop", OnStop: func(*xlgo.App) error { stopCount.Add(1); return nil }}),
)
if err := app.Init(); err != nil {
t.Fatalf("Init: %v", err)
}
var wg sync.WaitGroup
wg.Add(2)
go func() { defer wg.Done(); _ = app.Shutdown() }()
go func() { defer wg.Done(); _ = app.Shutdown() }()
wg.Wait()
if stopCount.Load() != 1 {
t.Fatalf("OnStop called %d times, want 1 (idempotent)", stopCount.Load())
}
if err := app.Shutdown(); err != nil {
t.Fatalf("third Shutdown error: %v", err)
}
if stopCount.Load() != 1 {
t.Fatalf("OnStop called %d times after 3rd, want 1", stopCount.Load())
}
}
// TestAppInitFailureRollsBackCron_M1（Edge 3 + 资源回滚）：Init 失败（OnInit hook 报错）时，
// 已 cron.Start() 的全局调度器必须被 failAfterInit 停止，canary 任务不再触发。
// 修复前：Init 失败不停 cron → canary 在下个 1s tick 跑 → ran > 0。
// TestAppShutdownTimeoutCoversOnStop_M1 回归：OnStop 必须受 server.shutdown_timeout 约束。
// 修复前：OnStop 同步执行且不看超时，阻塞 hook 会拖死 Shutdown。
func TestAppShutdownTimeoutCoversOnStop_M1(t *testing.T) {
cfg := testConfig(18105)
cfg.Server.ShutdownTimeout = 30 * time.Millisecond
release := make(chan struct{})
defer close(release)
app := xlgo.New(
xlgo.WithConfig(cfg),
xlgo.WithHook(xlgo.Hook{Name: "slow-stop", OnStop: func(*xlgo.App) error {
<-release
return nil
}}),
)
if err := app.Init(); err != nil {
t.Fatalf("Init: %v", err)
}
start := time.Now()
err := app.Shutdown()
if err == nil || !strings.Contains(err.Error(), "OnStop hook") {
t.Fatalf("Shutdown err = %v, want OnStop timeout error", err)
}
if elapsed := time.Since(start); elapsed > time.Second {
t.Fatalf("Shutdown took %s, OnStop timeout did not bound shutdown", elapsed)
}
}
// TestWithConfigClonesAndValidates_M1 回归：WithConfig 捕获私有快照，并在 Init 时校验。
func TestWithConfigClonesAndValidates_M1(t *testing.T) {
cfg := testConfig(18106)
app := xlgo.New(xlgo.WithConfig(cfg))
cfg.Server.Port = -1 // 不应污染 App 内部快照
if err := app.Init(); err != nil {
t.Fatalf("Init with cloned config failed after caller mutation: %v", err)
}
if err := app.Shutdown(); err != nil {
t.Fatalf("Shutdown: %v", err)
}
bad := testConfig(-1)
err := xlgo.New(xlgo.WithConfig(bad)).Init()
if err == nil || !strings.Contains(err.Error(), "配置校验失败") {
t.Fatalf("Init with invalid WithConfig err = %v, want validation error", err)
}
}
func TestAppInitFailureRollsBackCron_M1(t *testing.T) {
cron.StopGlobalWithTimeout(time.Second) // 清前序残留
t.Cleanup(func() {
cron.GetScheduler().RemoveTask("canary-m1")
cron.StopGlobalWithTimeout(time.Second)
})
var ran atomic.Int32
// Phase 3：canary 注册到 App 专属调度器（WithCronTask），Init 失败时 stopCron 必须停掉它。
app := xlgo.New(
xlgo.WithConfig(testConfig(18104)),
xlgo.WithCronTask("canary-m1", cron.Every(time.Millisecond), func(context.Context) error {
ran.Add(1)
return nil
}),
xlgo.WithHook(xlgo.Hook{Name: "fail", OnInit: func(*xlgo.App) error { return errors.New("boom-init") }}),
)
err := app.Init()
if err == nil || !strings.Contains(err.Error(), "boom-init") {
t.Fatalf("Init err = %v, want boom-init", err)
}
time.Sleep(1300 * time.Millisecond) // 跨一个 1s ticker
if ran.Load() != 0 {
t.Fatalf("canary ran %d times after Init failure — cron not stopped by rollback", ran.Load())
}
}
// TestAppGoRefusedAfterInitFailure_M1：Init 失败后 failAfterInit 置 state=Stopping，
// 后续 Go() 拒绝；先前的 Go goroutine 因 rootCtx cancel 退出（不泄漏）。
func TestAppGoRefusedAfterInitFailure_M1(t *testing.T) {
app := xlgo.New(
xlgo.WithConfig(testConfig(18103)),
xlgo.WithMigrator(func(*gorm.DB) error { return nil }), // 无 WithMySQL → Init 确定性失败
)
firstDone := make(chan struct{})
app.Go(func(ctx context.Context) { <-ctx.Done(); close(firstDone) })
if err := app.Init(); err == nil {
t.Fatal("expected Init error")
}
select {
case <-firstDone:
case <-time.After(5 * time.Second):
t.Fatal("first Go goroutine did not exit after Init failure (rootCtx not cancelled)")
}
ran := make(chan struct{}, 1)
app.Go(func(context.Context) { ran <- struct{}{} })
time.Sleep(50 * time.Millisecond)
select {
case <-ran:
t.Fatal("Go ran after Init failure — should be refused (state=Stopping)")
default:
}
}
// TestAppInitFailureDoesNotCloseUnownedGlobals_M1 回归：一个尚未成功初始化任何资源的
// App Init 失败时，不得关闭进程里已有的全局 logger/db/redis 等资源。
func TestAppInitFailureDoesNotCloseUnownedGlobals_M1(t *testing.T) {
dir := t.TempDir()
if err := logger.Init(&config.Config{
App: config.AppConfig{Env: "test"},
Server: config.ServerConfig{Mode: "development"},
Log: config.LogConfig{Dir: dir, MaxSize: 1, MaxBackups: 1, MaxAge: 1},
}); err != nil {
t.Fatalf("logger.Init: %v", err)
}
t.Cleanup(func() { _ = logger.Close() })
missingConfig := filepath.Join(t.TempDir(), "missing.yaml")
if err := xlgo.New(xlgo.WithConfigPath(missingConfig)).Init(); err == nil {
t.Fatal("expected Init error without config")
}
const mark = "M1_UNOWNED_LOGGER_STILL_ACTIVE"
logger.Info(mark)
_ = logger.Sync()
data, err := os.ReadFile(filepath.Join(dir, "app.log"))
if err != nil {
t.Fatalf("read app.log: %v", err)
}
if !strings.Contains(string(data), mark) {
t.Fatal("unowned global logger was closed by failed App.Init")
}
}
// TestAppInitShutdownConcurrentSerialization_M1 直接覆盖 initMu 串行化 doInit/doShutdown
// （Edge 2）：Init 持 initMu 期间（OnInit hook 阻塞），并发 Shutdown 必须阻塞等 Init 释放，
// 不能与 doInit 并发改资源。确定性逻辑测试，不依赖 -race 概率。
func TestAppInitFailureRestoresReplacedLogger_M1(t *testing.T) {
oldMgr := logger.NewLogManager()
oldDir := t.TempDir()
if err := oldMgr.Init(&config.Config{
App: config.AppConfig{Env: "test"},
Server: config.ServerConfig{Mode: "development"},
Log: config.LogConfig{Dir: oldDir, MaxSize: 1, MaxBackups: 1, MaxAge: 1},
}); err != nil {
t.Fatalf("old logger Init: %v", err)
}
logger.SetDefaultLogManager(oldMgr)
t.Cleanup(func() {
_ = logger.Close()
logger.SetDefaultLogManager(logger.NewLogManager())
})
cfg := testConfig(18105)
cfg.Log.Dir = t.TempDir()
app := xlgo.New(
xlgo.WithConfig(cfg),
xlgo.WithLogger(),
xlgo.WithHook(xlgo.Hook{Name: "fail-after-logger", OnInit: func(*xlgo.App) error {
return errors.New("boom-after-logger")
}}),
)
err := app.Init()
if err == nil || !strings.Contains(err.Error(), "boom-after-logger") {
t.Fatalf("Init err = %v, want boom-after-logger", err)
}
if got := logger.GetDefaultLogManager(); got != oldMgr {
t.Fatalf("default logger manager was not restored after Init failure: got %p want %p", got, oldMgr)
}
const mark = "M1_RESTORED_LOGGER_STILL_ACTIVE"
logger.Info(mark)
_ = logger.Sync()
data, err := os.ReadFile(filepath.Join(oldDir, "app.log"))
if err != nil {
t.Fatalf("read old app.log: %v", err)
}
if !strings.Contains(string(data), mark) {
t.Fatal("restored logger did not write to old app.log")
}
}
func TestAppInitShutdownConcurrentSerialization_M1(t *testing.T) {
initStarted := make(chan struct{})
releaseInit := make(chan struct{})
app := xlgo.New(
xlgo.WithConfig(testConfig(18200)),
xlgo.WithHook(xlgo.Hook{
Name: "block-init",
OnInit: func(*xlgo.App) error {
close(initStarted)
<-releaseInit
return nil
},
}),
)
initDone := make(chan error, 1)
go func() { initDone <- app.Init() }()
<-initStarted // OnInit 在 doInit 末尾运行 → 此时 Init 持 initMu
// 并发 Shutdown：必须阻塞等 initMu，不能在 Init 完成前返回。
shutDone := make(chan error, 1)
go func() { shutDone <- app.Shutdown() }()
select {
case <-shutDone:
t.Fatal("Shutdown returned before Init finished — initMu not serializing doInit/doShutdown")
case <-time.After(150 * time.Millisecond):
// 期望：Shutdown 仍阻塞等 initMu
}
close(releaseInit) // 让 OnInit 返回 → doInit 完成 → Init 释放 initMu
select {
case err := <-initDone:
if err != nil {
t.Fatalf("Init: %v", err)
}
case <-time.After(5 * time.Second):
t.Fatal("Init did not return after release")
}
select {
case <-shutDone:
// Shutdown 在 Init 后获得 initMu 并完成
case <-time.After(5 * time.Second):
t.Fatal("Shutdown did not return after Init finished — initMu not released?")
}
}
// TestAppStartServerListenFailureSkipsOnReady_M1 回归：监听失败时不得先执行 OnReady。
// 修复前 StartServer 在 goroutine 内 ListenAndServe，主 goroutine 立即跑 OnReady；
// 端口被占用时仍可能先触发 ready 副作用，再返回启动失败。
func TestAppStartServerListenFailureSkipsOnReady_M1(t *testing.T) {
ln, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
t.Fatalf("occupy port: %v", err)
}
defer ln.Close()
port := ln.Addr().(*net.TCPAddr).Port
cfg := testConfig(port)
cfg.Server.Host = "127.0.0.1"
var ready atomic.Int32
app := xlgo.New(
xlgo.WithConfig(cfg),
xlgo.WithHook(xlgo.Hook{
Name: "ready-must-not-run",
OnReady: func(*xlgo.App) error {
ready.Add(1)
return nil
},
}),
)
if err := app.Init(); err != nil {
t.Fatalf("Init: %v", err)
}
err = app.StartServer()
if err == nil || !strings.Contains(err.Error(), "服务器监听失败") {
t.Fatalf("StartServer err = %v, want listen failure", err)
}
if ready.Load() != 0 {
t.Fatalf("OnReady ran %d times despite listen failure", ready.Load())
}
_ = app.Shutdown()
}
// TestAppStartServerTLSFailureSkipsOnReady_M1 回归：TLS 证书装配失败也不得触发 OnReady。
func TestAppStartServerTLSFailureSkipsOnReady_M1(t *testing.T) {
ln, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
t.Fatalf("reserve port: %v", err)
}
port := ln.Addr().(*net.TCPAddr).Port
if err := ln.Close(); err != nil {
t.Fatalf("release port: %v", err)
}
cfg := testConfig(port)
cfg.Server.Host = "127.0.0.1"
cfg.Server.TLS.Enabled = true
cfg.Server.TLS.CertFile = filepath.Join(t.TempDir(), "missing.crt")
cfg.Server.TLS.KeyFile = filepath.Join(t.TempDir(), "missing.key")
var ready atomic.Int32
app := xlgo.New(
xlgo.WithConfig(cfg),
xlgo.WithHook(xlgo.Hook{
Name: "tls-ready-must-not-run",
OnReady: func(*xlgo.App) error {
ready.Add(1)
return nil
},
}),
)
if err := app.Init(); err != nil {
t.Fatalf("Init: %v", err)
}
err = app.StartServer()
if err == nil || !strings.Contains(err.Error(), "服务器 TLS 配置无效") {
t.Fatalf("StartServer err = %v, want TLS configuration failure", err)
}
if ready.Load() != 0 {
t.Fatalf("OnReady ran %d times despite TLS failure", ready.Load())
}
_ = app.Shutdown()
}
// TestAppStartServerUnixSocketListens_M1 回归：server.unix_socket 必须真的通过
// net.Listen("unix", path) 监听，而不是把 path 塞给 TCP ListenAndServe 的 Addr。
func TestAppStartServerUnixSocketListens_M1(t *testing.T) {
if runtime.GOOS == "windows" {
t.Skip("Windows unix socket support varies by environment")
}
sock := filepath.Join(t.TempDir(), "xlgo.sock")
cfg := testConfig(0)
cfg.Server.UnixSocket = sock
app := xlgo.New(
xlgo.WithConfig(cfg),
xlgo.WithHook(xlgo.Hook{
Name: "dial-unix-ready",
OnReady: func(*xlgo.App) error {
conn, err := net.DialTimeout("unix", sock, time.Second)
if err != nil {
return err
}
_ = conn.Close()
return errors.New("stop after unix socket ready")
},
}),
)
if err := app.Init(); err != nil {
t.Fatalf("Init: %v", err)
}
err := app.StartServer()
if err == nil || !strings.Contains(err.Error(), "stop after unix socket ready") {
t.Fatalf("StartServer err = %v, want OnReady sentinel after unix dial", err)
}
}
app_ratelimit_bound_test.go
+101
View File
@@ -0,0 +1,101 @@
package xlgo_test
import (
"errors"
"net/http"
"net/http/httptest"
"testing"
"time"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/gin-gonic/gin"
)
// TestAppRateLimitPerAppCountingIsolation 固化 #1 修复：app.RateLimitRegistry().LoginRateLimit()
// 返回的中间件捕获 App 自己的 Registry，多 App 下 per-App 计数隔离。修复前包级 LoginRateLimit()
// 解析全局默认（多 App 仅最后 Init 的 App），App A 用满额度后 App B 首请求即被拒。
//
// 验证：App A 用满 10/10 后第 11 次 429；App B 同 IP 仍可 10 次 200、第 11 次 429（独立计数）。
func TestAppRateLimitPerAppCountingIsolation(t *testing.T) {
// REST 模式：限流映射 HTTP 429
cfgA := testConfig(18140)
cfgA.Server.ResponseMode = "rest"
cfgB := testConfig(18141)
cfgB.Server.ResponseMode = "rest"
appA := xlgo.New(xlgo.WithConfig(cfgA))
if appA.RateLimitRegistry() == nil {
t.Fatal("appA.RateLimitRegistry() = nil before Init (should be pre-created in New)")
}
if err := appA.Init(); err != nil {
t.Fatalf("appA Init: %v", err)
}
defer appA.Shutdown()
// app-bound 中间件：捕获 appA 的 Registry，不查全局默认
appA.GetRouter().GET("/login", appA.RateLimitRegistry().LoginRateLimit(), func(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"ok": true})
})
appB := xlgo.New(xlgo.WithConfig(cfgB))
if err := appB.Init(); err != nil {
t.Fatalf("appB Init: %v", err)
}
defer appB.Shutdown()
appB.GetRouter().GET("/login", appB.RateLimitRegistry().LoginRateLimit(), func(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"ok": true})
})
req := func(h http.Handler) *httptest.ResponseRecorder {
w := httptest.NewRecorder()
r := httptest.NewRequest(http.MethodGet, "/login", nil)
r.RemoteAddr = "192.0.2.7:1234" // 两 App 用同一 IP
h.ServeHTTP(w, r)
return w
}
// App A 用满 10 次（200），第 11 次 429
for i := 0; i < 10; i++ {
if w := req(appA.GetRouter()); w.Code != http.StatusOK {
t.Fatalf("appA request %d: got %d, want 200", i+1, w.Code)
}
}
if w := req(appA.GetRouter()); w.Code != http.StatusTooManyRequests {
t.Fatalf("appA 11th: got %d, want 429 (limit reached)", w.Code)
}
// App B 同 IP：应独立计数，10 次 200、第 11 次 429。
// 包级 facade 下 B 会共享 A 的 loginLimiter（A 已用满）-> 首请求即 429，本测试即暴露该回归。
for i := 0; i < 10; i++ {
if w := req(appB.GetRouter()); w.Code != http.StatusOK {
t.Fatalf("appB request %d: got %d, want 200 (per-App isolation: B should not share A's count)", i+1, w.Code)
}
}
if w := req(appB.GetRouter()); w.Code != http.StatusTooManyRequests {
t.Fatalf("appB 11th: got %d, want 429 (B independent limit reached)", w.Code)
}
}
// TestAppRateLimitRegistryCustomNoLeakOnRollback 固化 #2 修复路径：app-bound CustomRateLimit
// 的 limiter 登记在 App 的 Registry 上，Init 失败回滚时由 registry.Stop() 收口，不泄漏。
// 验证：注册 CustomRateLimit 任务后 Init 失败，rollback 调 registry.Stop（customLimiters 被清）。
func TestAppRateLimitRegistryCustomNoLeakOnRollback(t *testing.T) {
cfg := testConfig(18142)
app := xlgo.New(xlgo.WithConfig(cfg),
xlgo.WithHook(xlgo.Hook{Name: "fail", OnInit: func(*xlgo.App) error { return errors.New("boom") }}),
)
// app-bound CustomRateLimit（首请求才创建 limiter，但 Init 会失败故不会触发请求；
// 此用例固化 app.RateLimitRegistry() 在 pre-Init 可用、Init 失败回滚不 panic）
app.GetRouter().GET("/c", app.RateLimitRegistry().CustomRateLimit(5, time.Minute), func(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"ok": true})
})
if err := app.Init(); err == nil {
_ = app.Shutdown()
t.Fatal("expected Init to fail via OnInit hook")
}
// Init 失败后 rollbackReplacedResources 已 Stop App 的 Registry 并把 a.rateLimitRegistry 置 nil，
// 故 app.RateLimitRegistry() 返回 nil（rollback 已收口，无泄漏、无 panic）。
if app.RateLimitRegistry() != nil {
t.Fatal("a.rateLimitRegistry should be nil after Init-failure rollback")
}
}
app_ratelimit_test.go
+107
View File
@@ -0,0 +1,107 @@
package xlgo_test
import (
"errors"
"net/http"
"net/http/httptest"
"testing"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/middleware"
"github.com/gin-gonic/gin"
)
// TestAppRateLimitMultiAppShutdownIsolation 固化 Phase 5 核心契约：单进程多 App 时，
// App A 的 Shutdown 不得重置/停止 App B 的限流器。修复前 App.Shutdown 调全局
// middleware.StopRateLimiters，把全局 loginLimiter 置 nil，App B 下次请求会懒创建
// 新 limiter（计数清零）--稳态客户端借 App A 的 Shutdown 窗口绕过限流。
//
// 验证：App B 的 /login 已用 10/10 次后，App A.Shutdown，第 11 次仍应 429（计数保留）。
// 修复前第 11 次会 200（计数被重置）。
func TestAppRateLimitMultiAppShutdownIsolation(t *testing.T) {
saved := middleware.SwapDefaultRateLimitRegistry(middleware.NewRateLimitRegistry())
defer middleware.SwapDefaultRateLimitRegistry(saved)
// 用 REST 响应模式：限流映射 HTTP 429（business 模式下是 200+业务码 429，不便断言）
cfgA := testConfig(18130)
cfgA.Server.ResponseMode = "rest"
cfgB := testConfig(18131)
cfgB.Server.ResponseMode = "rest"
appA := xlgo.New(xlgo.WithConfig(cfgA))
if err := appA.Init(); err != nil {
t.Fatalf("appA Init: %v", err)
}
appA.GetRouter().GET("/login", middleware.LoginRateLimit(), func(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"ok": true})
})
appB := xlgo.New(xlgo.WithConfig(cfgB))
if err := appB.Init(); err != nil {
t.Fatalf("appB Init: %v", err)
}
defer appB.Shutdown()
appB.GetRouter().GET("/login", middleware.LoginRateLimit(), func(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"ok": true})
})
// 10 次请求 App B 的 /login（限流 10/min，同一 IP）-> 全 200
for i := 0; i < 10; i++ {
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/login", nil)
req.RemoteAddr = "192.0.2.1:1234"
appB.GetRouter().ServeHTTP(w, req)
if w.Code != http.StatusOK {
t.Fatalf("request %d: got %d, want 200 (under limit)", i+1, w.Code)
}
}
// 第 11 次（不经 A.Shutdown）应 429 -- 先确认限流器确实计数到上限（排除 IP/计数 bug）
{
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/login", nil)
req.RemoteAddr = "192.0.2.1:1234"
appB.GetRouter().ServeHTTP(w, req)
if w.Code != http.StatusTooManyRequests {
t.Fatalf("sanity: 11th without shutdown got %d, want 429 (limiter not counting?)", w.Code)
}
}
// App A Shutdown -- 不得重置/停止 App B 的 login limiter
if err := appA.Shutdown(); err != nil {
t.Fatalf("appA Shutdown: %v", err)
}
// 第 12 次请求 App B 的 /login -> 应仍 429（计数保留在 10，registryB 未被 A.Shutdown 重置）。
// 修复前 A.Shutdown 调 StopRateLimiters 把全局 loginLimiter 置 nil，下次请求懒创建新 limiter（计数清零）-> 200。
{
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/login", nil)
req.RemoteAddr = "192.0.2.1:1234"
appB.GetRouter().ServeHTTP(w, req)
if w.Code != http.StatusTooManyRequests {
t.Errorf("12th request after appA Shutdown: got %d, want 429 (limiter count should be preserved, not reset by appA.Shutdown)", w.Code)
}
}
}
// TestAppRateLimitRollbackOnInitFailure 固化 Phase 5 回滚：Init 失败后全局默认 Registry
// 必须恢复为 Init 前的实例。
func TestAppRateLimitRollbackOnInitFailure(t *testing.T) {
preInit := middleware.NewRateLimitRegistry()
saved := middleware.SwapDefaultRateLimitRegistry(preInit)
defer middleware.SwapDefaultRateLimitRegistry(saved)
app := xlgo.New(
xlgo.WithConfig(testConfig(18132)),
xlgo.WithHook(xlgo.Hook{Name: "fail", OnInit: func(*xlgo.App) error { return errors.New("boom") }}),
)
if err := app.Init(); err == nil {
_ = app.Shutdown()
t.Fatal("expected Init to fail via OnInit hook")
}
if middleware.GetDefaultRateLimitRegistry() != preInit {
t.Fatal("rollback did not restore preInit rate limit registry as global default")
}
}
app_storage_test.go
+71
View File
@@ -0,0 +1,71 @@
package xlgo_test
import (
"errors"
"testing"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/storage"
)
// localStorageCfg 构造一个本地存储配置（tmpdir 由调用方提供）。
func localStorageCfg(port int, dir string) *config.Config {
cfg := testConfig(port)
cfg.Storage = config.StorageConfig{
Driver: "local",
Local: config.LocalStorageConfig{Path: dir},
}
return cfg
}
// TestAppWithStorageSwapsDefault 固化 Phase 2 契约：App.Init(WithStorage) 必须把 App 的
// StorageManager 提升为全局默认。证据：Init 前 GetStorage()=nil（空 manager），Init 后非 nil。
func TestAppWithStorageSwapsDefault(t *testing.T) {
// 用空 manager 作"Init 前"默认，确保 GetStorage() 起点 nil
saved := storage.SwapDefaultStorageManager(storage.NewStorageManager())
defer storage.SwapDefaultStorageManager(saved)
if s := storage.GetStorage(); s != nil {
t.Fatalf("precondition: GetStorage() should be nil, got %T", s)
}
dir := t.TempDir()
app := xlgo.New(xlgo.WithConfig(localStorageCfg(18094, dir)), xlgo.WithStorage())
if err := app.Init(); err != nil {
t.Fatalf("Init: %v", err)
}
defer app.Shutdown()
if s := storage.GetStorage(); s == nil {
t.Fatal("storage.GetStorage() = nil after App.Init with WithStorage（未把 App manager 提升为全局默认）")
}
}
// TestAppStorageRollbackOnInitFailure 固化 Phase 2 回滚契约：Init 在 storage 之后失败时，
// rollbackReplacedResources 必须把全局默认 swap 回 Init 前的旧 manager。
// 用 OnInit hook 触发失败（OnInit 在 storage init 之后、commitReplacedResources 之前）。
func TestAppStorageRollbackOnInitFailure(t *testing.T) {
saved := storage.SwapDefaultStorageManager(storage.NewStorageManager())
defer storage.SwapDefaultStorageManager(saved)
dir := t.TempDir()
app := xlgo.New(
xlgo.WithConfig(localStorageCfg(18095, dir)),
xlgo.WithStorage(),
xlgo.WithHook(xlgo.Hook{
Name: "force-fail",
OnInit: func(*xlgo.App) error { return errors.New("boom") },
}),
)
if err := app.Init(); err == nil {
_ = app.Shutdown()
t.Fatal("expected Init to fail via OnInit hook")
}
// 回滚后全局默认应恢复为 saved（空 manager）-> GetStorage() 返回 nil
if s := storage.GetStorage(); s != nil {
t.Errorf("Init 失败回滚未恢复 storage 全局默认: GetStorage()=%T", s)
}
}
app_test.go
+361
View File
@@ -0,0 +1,361 @@
package xlgo_test
import (
"context"
"errors"
"net"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strconv"
"strings"
"testing"
"time"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/router"
"github.com/gin-gonic/gin"
"gorm.io/gorm"
)
func testConfig(port int) *config.Config {
return &config.Config{
App: config.AppConfig{Env: "test"},
Server: config.ServerConfig{Port: port, Mode: "development"},
Log: config.LogConfig{Dir: filepath.Join(os.TempDir(), "xlgo_app_test_logs"), MaxSize: 1, MaxBackups: 1, MaxAge: 1},
}
}
func writeConfig(t *testing.T, name string, port int) string {
t.Helper()
dir := t.TempDir()
path := filepath.Join(dir, name)
content := "app:\n env: test\nserver:\n port: " + strconv.Itoa(port) + "\n mode: development\nlog:\n dir: " + filepath.ToSlash(filepath.Join(dir, "logs")) + "\n max_size: 1\n max_backups: 1\n max_age: 1\n"
if err := os.WriteFile(path, []byte(content), 0644); err != nil {
t.Fatalf("write config: %v", err)
}
return path
}
func TestAppWithConfigPath(t *testing.T) {
path := writeConfig(t, "config.yaml", 18081)
app := xlgo.New(xlgo.WithConfigPath(path))
if err := app.Init(); err != nil {
t.Fatalf("Init error: %v", err)
}
if app.GetServer() != nil {
t.Fatal("Init should not start server")
}
}
func TestAppWithConfigNoDefaultRoutes(t *testing.T) {
app := xlgo.New(xlgo.WithConfig(testConfig(18082)))
if err := app.Init(); err != nil {
t.Fatalf("Init error: %v", err)
}
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/health", nil)
app.GetRouter().ServeHTTP(w, req)
if w.Code != http.StatusNotFound {
t.Fatalf("expected /health 404 without health routes, got %d", w.Code)
}
}
func TestAppWithHealthRoutes(t *testing.T) {
app := xlgo.New(xlgo.WithConfig(testConfig(18083)), xlgo.WithHealthRoutes())
if err := app.Init(); err != nil {
t.Fatalf("Init error: %v", err)
}
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/health", nil)
app.GetRouter().ServeHTTP(w, req)
if w.Code != http.StatusOK {
t.Fatalf("expected /health 200, got %d", w.Code)
}
}
func TestAppWithHealthCheckFailure(t *testing.T) {
app := xlgo.New(
xlgo.WithConfig(testConfig(18084)),
xlgo.WithHealthRoutes(),
xlgo.WithHealthCheck("custom", func(_ context.Context) error { return errors.New("down") }),
)
if err := app.Init(); err != nil {
t.Fatalf("Init error: %v", err)
}
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/health", nil)
app.GetRouter().ServeHTTP(w, req)
if w.Code != http.StatusServiceUnavailable {
t.Fatalf("expected /health 503, got %d", w.Code)
}
}
func TestAppMigratorRequiresMySQL(t *testing.T) {
app := xlgo.New(
xlgo.WithConfig(testConfig(18085)),
xlgo.WithMigrator(func(_ *gorm.DB) error { return nil }),
)
err := app.Init()
if err == nil || !strings.Contains(err.Error(), "未启用 MySQL") {
t.Fatalf("expected mysql disabled migrator error, got %v", err)
}
}
func TestAppRoutesModule(t *testing.T) {
app := xlgo.New(
xlgo.WithConfig(testConfig(18086)),
xlgo.WithModules(router.ModuleFunc(func(r *gin.RouterGroup) {
r.GET("/hello", func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"hello": "world"}) })
})),
)
if err := app.Init(); err != nil {
t.Fatalf("Init error: %v", err)
}
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/hello", nil)
app.GetRouter().ServeHTTP(w, req)
if w.Code != http.StatusOK {
t.Fatalf("expected module route 200, got %d", w.Code)
}
}
func TestAppWithoutDefaultRoutesOverrides(t *testing.T) {
app := xlgo.New(
xlgo.WithConfig(testConfig(18087)),
xlgo.WithDefaultRoutes(),
xlgo.WithoutDefaultRoutes(),
)
if err := app.Init(); err != nil {
t.Fatalf("Init error: %v", err)
}
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/health", nil)
app.GetRouter().ServeHTTP(w, req)
if w.Code != http.StatusNotFound {
t.Fatalf("expected /health 404 after WithoutDefaultRoutes, got %d", w.Code)
}
}
// TestAppWithSwaggerRoutesOnly 验证可以单独启用 Swagger 而不开启 health。
func TestAppWithSwaggerRoutesOnly(t *testing.T) {
app := xlgo.New(
xlgo.WithConfig(testConfig(18088)),
xlgo.WithSwaggerRoutes(),
)
if err := app.Init(); err != nil {
t.Fatalf("Init error: %v", err)
}
// /health 不应注册
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/health", nil)
app.GetRouter().ServeHTTP(w, req)
if w.Code != http.StatusNotFound {
t.Fatalf("expected /health 404 when only Swagger enabled, got %d", w.Code)
}
// /swagger/* 应注册（具体子路径返回什么取决于 swag 文档是否生成，这里只验证未 404）
w = httptest.NewRecorder()
req = httptest.NewRequest(http.MethodGet, "/swagger/index.html", nil)
app.GetRouter().ServeHTTP(w, req)
if w.Code == http.StatusNotFound {
t.Fatalf("expected /swagger/index.html to be registered, got 404")
}
}
// TestAppWithoutAutoMigrateOverride 验证 WithoutAutoMigrate 能覆盖
// 之前通过 WithMigrator 隐式开启的迁移，不再要求 MySQL 已启用。
func TestAppWithoutAutoMigrateOverride(t *testing.T) {
migratorCalled := false
app := xlgo.New(
xlgo.WithConfig(testConfig(18089)),
xlgo.WithMigrator(func(_ *gorm.DB) error {
migratorCalled = true
return nil
}),
xlgo.WithoutAutoMigrate(),
)
if err := app.Init(); err != nil {
t.Fatalf("Init should succeed when AutoMigrate is disabled, got %v", err)
}
if migratorCalled {
t.Fatal("migrator must not be called when WithoutAutoMigrate is applied")
}
}
// TestAppDefaultsLightweight 验证 v1.0.2 起 xlgo.New 默认是轻量应用：
// 不启 MySQL/Redis/Storage、不注册 health/swagger 路由。
func TestAppDefaultsLightweight(t *testing.T) {
app := xlgo.New(xlgo.WithConfig(testConfig(18090)))
if err := app.Init(); err != nil {
t.Fatalf("Init error: %v", err)
}
r := app.GetRouter()
for _, path := range []string{"/health", "/swagger/index.html"} {
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, path, nil)
r.ServeHTTP(w, req)
if w.Code != http.StatusNotFound {
t.Fatalf("expected %s 404 by default, got %d", path, w.Code)
}
}
// 默认未注册 MySQL/Redis 健康检查项，故 healthChecks 应为空
// 这里通过启用 health 路由后只返回 status:ok 来间接验证
app2 := xlgo.New(xlgo.WithConfig(testConfig(18091)), xlgo.WithHealthRoutes())
if err := app2.Init(); err != nil {
t.Fatalf("Init error: %v", err)
}
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/health", nil)
app2.GetRouter().ServeHTTP(w, req)
if w.Code != http.StatusOK {
t.Fatalf("expected /health 200 with no checks, got %d", w.Code)
}
}
// TestAppWithConfigPathDrivesManager 验证 WithConfigPath 真正驱动 App 自己的
// config.Manager，并把它推到全局 default，使 config.Get 能取到加载后的配置。
func TestAppWithConfigPathDrivesManager(t *testing.T) {
path := writeConfig(t, "config_drive.yaml", 18092)
app := xlgo.New(xlgo.WithConfigPath(path))
if err := app.Init(); err != nil {
t.Fatalf("Init error: %v", err)
}
cfg := config.Get()
if cfg == nil {
t.Fatal("config.Get returned nil after WithConfigPath; manager not promoted to default")
}
if cfg.Server.Port != 18092 {
t.Fatalf("expected port 18092 from loaded config, got %d", cfg.Server.Port)
}
if config.GetInt("server.port") != 18092 {
t.Fatalf("expected GetInt(server.port)=18092, got %d", config.GetInt("server.port"))
}
}
// TestAppMetricsInstrumentsRegistryRoutes_H8c 端到端验证 H8c：经注册中心注册的业务路由
// 被指标中间件采集，不依赖 RegisterMetricsRoute 的调用顺序。修复前 RegisterMetricsRoute
// 用 r.Use 仅采集其后注册的路由；修复后采集中间件在 Apply 内作首个全局中间件装入。
func TestAppMetricsInstrumentsRegistryRoutes_H8c(t *testing.T) {
app := xlgo.New(
xlgo.WithConfig(testConfig(18093)),
xlgo.WithMetricsRoute(),
xlgo.WithModules(router.ModuleFunc(func(r *gin.RouterGroup) {
r.GET("/h8c-biz", func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"ok": true}) })
})),
)
if err := app.Init(); err != nil {
t.Fatalf("Init error: %v", err)
}
r := app.GetRouter()
for i := 0; i < 2; i++ {
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/h8c-biz", nil))
if w.Code != http.StatusOK {
t.Fatalf("/h8c-biz status = %d, want 200", w.Code)
}
}
// 拉取 /metrics，断言 /h8c-biz 路由被采集（route 标签存在）。
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/metrics", nil))
if w.Code != http.StatusOK {
t.Fatalf("/metrics status = %d, want 200", w.Code)
}
body := w.Body.String()
if !strings.Contains(body, `route="/h8c-biz"`) {
t.Fatalf("metrics output should contain route=\"/h8c-biz\" series, got:\n%s", body)
}
}
// freePort 返回一个当前空闲的 TCP 端口。
func freePort(t *testing.T) int {
t.Helper()
l, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
t.Fatalf("freePort: %v", err)
}
defer l.Close()
return l.Addr().(*net.TCPAddr).Port
}
// TestAppOnReadyFailureReleasesPort H-1 回归：OnReady 失败时 Run 应返回错误，
// 且 HTTP 端口被释放（监听 goroutine 不泄漏）。
// 修复前 OnReady 失败直接 return，监听 goroutine 仍阻塞在 ListenAndServe，
// 端口不释放、goroutine 泄漏。
func TestAppOnReadyFailureReleasesPort(t *testing.T) {
port := freePort(t)
app := xlgo.New(
xlgo.WithConfig(testConfig(port)),
xlgo.WithHook(xlgo.Hook{
Name: "fail-on-ready",
OnReady: func(*xlgo.App) error { return errors.New("boom") },
}),
)
errCh := make(chan error, 1)
go func() { errCh <- app.Run() }()
select {
case err := <-errCh:
if err == nil || !strings.Contains(err.Error(), "boom") {
t.Fatalf("expected OnReady failure error, got %v", err)
}
case <-time.After(10 * time.Second):
t.Fatal("Run did not return after OnReady failure (server goroutine leaked?)")
}
// 端口应已释放：能重新 bind。容忍 TIME_WAIT 短暂残留。
deadline := time.Now().Add(3 * time.Second)
for {
l, err := net.Listen("tcp", "127.0.0.1:"+strconv.Itoa(port))
if err == nil {
l.Close()
break
}
if time.Now().After(deadline) {
t.Fatalf("port %d not released 3s after Run returned: %v (server goroutine leaked)", port, err)
}
time.Sleep(50 * time.Millisecond)
}
}
// TestAppInitFailureCancelsGoGoroutine H-2 回归：App.Go 启动的 goroutine 在 Init 失败后
// 应因 rootCtx cancel 而退出，不泄漏。
// 修复前 Init 失败不 cancel rootCtx，goroutine 永久阻塞在 ctx.Done()。
func TestAppInitFailureCancelsGoGoroutine(t *testing.T) {
app := xlgo.New(
xlgo.WithConfig(testConfig(18087)),
// WithMigrator 无 WithMySQL → Init 确定性失败（"未启用 MySQL"）
xlgo.WithMigrator(func(_ *gorm.DB) error { return nil }),
)
ctxDone := make(chan struct{})
app.Go(func(ctx context.Context) {
<-ctx.Done()
close(ctxDone)
})
if err := app.Init(); err == nil {
t.Fatal("expected Init error")
}
select {
case <-ctxDone:
// 好：goroutine 在 Init 失败后退出
case <-time.After(5 * time.Second):
t.Fatal("App.Go goroutine did not exit after Init failure (rootCtx not cancelled, leaked)")
}
}
app_trace_test.go
+120
View File
@@ -0,0 +1,120 @@
package xlgo_test
import (
"context"
"net/http"
"net/http/httptest"
"runtime"
"strings"
"testing"
"time"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/trace"
"github.com/gin-gonic/gin"
)
// TestWithTraceInitErrorPropagated 固化 Phase 1 契约：WithTrace 启用后 doInit 必须调
// trace.Init 并把错误向上传播。用非法 ExporterType 触发 trace.Init 失败（config.Validate
// 只校验 SampleRatio，故 bogus exporter 能过 Validate、在 trace.Init 失败，证明是 App 主动调 Init）。
func TestWithTraceInitErrorPropagated(t *testing.T) {
cfg := testConfig(18090)
cfg.Trace.Enabled = true
cfg.Trace.ExporterType = "bogus-exporter"
app := xlgo.New(xlgo.WithConfig(cfg), xlgo.WithTrace())
err := app.Init()
if err == nil {
_ = app.Shutdown()
t.Fatal("expected Init to fail with bogus trace exporter, got nil")
}
// "初始化 trace 失败" 包裹 trace.Init 的 "不支持的导出器类型"
msg := err.Error()
if !strings.Contains(msg, "trace") && !strings.Contains(msg, "导出器") {
t.Fatalf("expected trace init error, got %v", err)
}
}
// TestWithTraceNoopMiddlewareDoesNotBreakRequest 固化：WithTrace + Enabled=false（默认）
// 时 trace.Init 安装 Noop tracer，trace.Middleware 装入链后不应破坏正常请求。
func TestWithTraceNoopMiddlewareDoesNotBreakRequest(t *testing.T) {
cfg := testConfig(18091)
// Trace.Enabled 保持默认 false -> noop
app := xlgo.New(xlgo.WithConfig(cfg), xlgo.WithTrace())
if err := app.Init(); err != nil {
t.Fatalf("Init: %v", err)
}
defer app.Shutdown()
// Init 后（middleware 链已装入）注册路由，确保该路由经过 trace 中间件。
app.GetRouter().GET("/ping", func(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"ok": true})
})
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/ping", nil)
app.GetRouter().ServeHTTP(w, req)
if w.Code != http.StatusOK {
t.Fatalf("trace noop middleware broke request: got status %d, body %s", w.Code, w.Body.String())
}
}
// TestWithTraceShutdownReleasesExporterGoroutine 固化 Phase 1 生命周期闭环：
// WithTrace + Enabled=true + stdout exporter，Init 后 BatchSpanProcessor 后台 goroutine
// 在运行；Shutdown 必须调 trace.Close 让其退出，否则 goroutine 泄漏（H-14 修了 Close 幂等，
// 但 App 此前从未调 Close -- 本测试断言 App.Shutdown 确实调了）。
//
// 不发任何请求 -> stdout exporter 不输出 -> 无测试输出污染；仅观测 goroutine 计数。
func TestWithTraceShutdownReleasesExporterGoroutine(t *testing.T) {
cfg := testConfig(18092)
cfg.Trace.Enabled = true
cfg.Trace.ExporterType = "stdout"
app := xlgo.New(xlgo.WithConfig(cfg), xlgo.WithTrace())
baseline := runtime.NumGoroutine()
if err := app.Init(); err != nil {
t.Fatalf("Init: %v", err)
}
afterInit := runtime.NumGoroutine()
if afterInit <= baseline {
t.Logf("note: afterInit=%d baseline=%d (batch goroutine delta not detected; test may be noisy)", afterInit, baseline)
}
if err := app.Shutdown(); err != nil {
t.Fatalf("Shutdown: %v", err)
}
// trace.Close 的 provider.Shutdown 异步停止 batch goroutine，轮询等待回归 baseline。
deadline := time.Now().Add(2 * time.Second)
for time.Now().Before(deadline) {
if runtime.NumGoroutine() <= baseline {
break
}
time.Sleep(20 * time.Millisecond)
}
if after := runtime.NumGoroutine(); after > baseline {
t.Errorf("trace.Close 未释放 exporter goroutine（App.Shutdown 疑未调 trace.Close）: baseline=%d after=%d", baseline, after)
}
}
// TestWithTraceEnabledStdoutInitOK 固化：WithTrace + Enabled=true + stdout 是合法组合，
// trace.Init 成功，App.Init 成功；二次 trace.Close 幂等（H-14）。
func TestWithTraceEnabledStdoutInitOK(t *testing.T) {
cfg := testConfig(18093)
cfg.Trace.Enabled = true
cfg.Trace.ExporterType = "stdout"
app := xlgo.New(xlgo.WithConfig(cfg), xlgo.WithTrace())
if err := app.Init(); err != nil {
t.Fatalf("Init: %v", err)
}
if err := app.Shutdown(); err != nil {
t.Fatalf("Shutdown: %v", err)
}
// Shutdown 已调 trace.Close；再调一次必须幂等不报错（H-14 契约）
if err := trace.Close(context.Background()); err != nil {
t.Fatalf("trace.Close after Shutdown should be idempotent: %v", err)
}
}
cache/cache.go
Vendored
+279
View File
@@ -0,0 +1,279 @@
package cache
import (
"context"
"encoding/json"
"sync"
"sync/atomic"
"time"
"github.com/EthanCodeCraft/xlgo-core/database"
"github.com/EthanCodeCraft/xlgo-core/logger"
"github.com/redis/go-redis/v9"
"go.uber.org/zap"
)
// CacheService 缓存服务接口
type CacheService interface {
// Get 获取缓存值，命中则反序列化到 dest 并返回 (true, nil)；未命中返回 (false, nil)；
// Redis 未就绪、命令错误或反序列化失败返回 (false, err)。调用方须显式处理错误。
Get(ctx context.Context, key string, dest any) (bool, error)
// Set 设置缓存值
Set(ctx context.Context, key string, value any, ttl time.Duration) error
// Delete 删除缓存
Delete(ctx context.Context, key string) error
// DeleteByPattern 按模式删除缓存
DeleteByPattern(ctx context.Context, pattern string) error
// Exists 检查缓存是否存在；未命中返回 (false, nil)，后端错误返回 (false, err)。
Exists(ctx context.Context, key string) (bool, error)
}
// redisCache Redis 缓存实现。
//
// 不在构造时快照 redis.Client（M12 修复：原 NewRedisCache 构造时取 database.GetRedis()，
// 若在 database.InitRedis 之前构造则永久 nil、即使后续 Redis 就绪也是 no-op）。
// 改为每次操作实时取 redis 客户端，使"先构造后 Init Redis"的顺序也能正确工作。
//
// Phase 4：持有可选的注入 client（NewRedisCacheWithRedis），注入优先、否则回退全局
// database.GetRedis()（照 jwt.TokenBlacklist.redisClient 模型）。App 经 InitWithRedis
// 注入 per-App redisManager.Client()，使缓存走 App 自己的 Redis 而非全局（修复跨 App 串越）。
type redisCache struct {
injectedClient *redis.Client
}
// client 返回缓存使用的 Redis 客户端：注入优先，否则回退全局 database.GetRedis()。
func (c *redisCache) client() *redis.Client {
if c != nil && c.injectedClient != nil {
return c.injectedClient
}
return database.GetRedis()
}
// NewRedisCache 创建 Redis 缓存实例（懒取全局 Redis，兼容 standalone 用法）。
func NewRedisCache() CacheService {
return &redisCache{}
}
// NewRedisCacheWithRedis 创建使用指定 Redis 客户端的缓存实例（多 Redis/测试隔离）。
func NewRedisCacheWithRedis(client *redis.Client) CacheService {
return &redisCache{injectedClient: client}
}
// Get 获取缓存值。命中返回 (true, nil)；未命中返回 (false, nil)；
// Redis 未就绪返回 (false, ErrRedisNotReady)；Redis 命令错误或反序列化失败返回 (false, err)。
func (c *redisCache) Get(ctx context.Context, key string, dest any) (bool, error) {
cli := c.client()
if cli == nil {
return false, ErrRedisNotReady
}
val, err := cli.Get(ctx, key).Result()
if err != nil {
if err == redis.Nil {
return false, nil
}
return false, err
}
if err := json.Unmarshal([]byte(val), dest); err != nil {
return false, err
}
return true, nil
}
// Set 设置缓存值
func (c *redisCache) Set(ctx context.Context, key string, value any, ttl time.Duration) error {
cli := c.client()
if cli == nil {
return ErrRedisNotReady
}
data, err := json.Marshal(value)
if err != nil {
logger.Warn("缓存序列化失败", zap.String("key", key), zap.Error(err))
return err
}
if err := cli.Set(ctx, key, data, ttl).Err(); err != nil {
logger.Warn("缓存设置失败", zap.String("key", key), zap.Error(err))
return err
}
return nil
}
// Delete 删除缓存
func (c *redisCache) Delete(ctx context.Context, key string) error {
cli := c.client()
if cli == nil {
return ErrRedisNotReady
}
if err := cli.Del(ctx, key).Err(); err != nil {
logger.Warn("缓存删除失败", zap.String("key", key), zap.Error(err))
return err
}
return nil
}
// DeleteByPattern 按模式删除缓存（使用 SCAN 避免阻塞 Redis）
func (c *redisCache) DeleteByPattern(ctx context.Context, pattern string) error {
cli := c.client()
if cli == nil {
return ErrRedisNotReady
}
var cursor uint64
var deleted int
for {
// 使用 SCAN 命令迭代查找匹配的键
keys, nextCursor, err := cli.Scan(ctx, cursor, pattern, 100).Result()
if err != nil {
logger.Warn("缓存键扫描失败", zap.String("pattern", pattern), zap.Error(err))
return err
}
// 删除找到的键
if len(keys) > 0 {
if err := cli.Del(ctx, keys...).Err(); err != nil {
logger.Warn("缓存批量删除失败", zap.Strings("keys", keys), zap.Error(err))
return err
}
deleted += len(keys)
}
// 更新游标
cursor = nextCursor
// 游标为 0 表示遍历完成
if cursor == 0 {
break
}
}
if deleted > 0 {
logger.Debug("缓存批量删除完成", zap.String("pattern", pattern), zap.Int("count", deleted))
}
return nil
}
// Exists 检查缓存是否存在。命中返回 (true, nil)；未命中返回 (false, nil)；
// Redis 未就绪返回 (false, ErrRedisNotReady)；命令错误返回 (false, err)。
func (c *redisCache) Exists(ctx context.Context, key string) (bool, error) {
cli := c.client()
if cli == nil {
return false, ErrRedisNotReady
}
n, err := cli.Exists(ctx, key).Result()
if err != nil {
return false, err
}
return n > 0, nil
}
// CacheManager 缓存管理器（#10）。照 database.Manager 模式：
// 实例化 + DefaultCache 全局默认 + 包级 facade 代理，支持测试注入 mock 实现。
type CacheManager struct {
mu sync.Mutex
svc CacheService
}
// defaultCachePtr 全局默认缓存管理器（CK3 修复：atomic.Pointer 替代裸指针）。
var defaultCachePtr atomic.Pointer[CacheManager]
func init() {
defaultCachePtr.Store(NewCacheManager())
}
// NewCacheManager 创建缓存管理器实例。
func NewCacheManager() *CacheManager { return &CacheManager{} }
// GetDefaultCache 返回全局默认缓存管理器（并发安全，CK3 修复）。
func GetDefaultCache() *CacheManager {
return defaultCachePtr.Load()
}
// SetDefaultCacheManager 提升指定 CacheManager 为全局默认（atomic 置换，并发安全）。
func SetDefaultCacheManager(m *CacheManager) {
if m != nil {
defaultCachePtr.Store(m)
}
}
// SwapDefaultCacheManager 将指定 CacheManager 置为全局默认，返回被替换的旧 Manager。
// 旧 Manager 不会被关闭，供 App 初始化这类需要失败回滚的生命周期流程暂存（照
// SwapDefaultRedisManager / SwapDefaultStorageManager 模式）。nil 被忽略，返回当前默认。
func SwapDefaultCacheManager(m *CacheManager) *CacheManager {
if m == nil {
return defaultCachePtr.Load()
}
return defaultCachePtr.Swap(m)
}
// Init 初始化缓存服务（基于 DefaultRedis 的客户端）。
func (m *CacheManager) Init() {
m.mu.Lock()
defer m.mu.Unlock()
m.svc = NewRedisCache()
}
// InitWithRedis 用指定 Redis 客户端初始化缓存服务（多 Redis/测试隔离）。
func (m *CacheManager) InitWithRedis(client *redis.Client) {
m.mu.Lock()
defer m.mu.Unlock()
m.svc = NewRedisCacheWithRedis(client)
}
// Set 设置缓存服务实现（用于注入 mock 或自定义实现）。
func (m *CacheManager) Set(svc CacheService) {
m.mu.Lock()
defer m.mu.Unlock()
m.svc = svc
}
// Get 返回缓存服务（未初始化时延迟初始化）。
func (m *CacheManager) Get() CacheService {
m.mu.Lock()
defer m.mu.Unlock()
if m.svc == nil {
m.svc = NewRedisCache()
}
return m.svc
}
// --- 包级 facade（代理到 GetDefaultCache()，CK3 修复） ---
// Init 初始化全局缓存实例
func Init() {
GetDefaultCache().Init()
}
// GetCache 获取全局缓存实例
func GetCache() CacheService {
return GetDefaultCache().Get()
}
// Get 获取全局缓存值。命中返回 (true, nil)；未命中返回 (false, nil)；
// 缓存未初始化或 Redis 错误返回 (false, err)。
func Get(ctx context.Context, key string, dest any) (bool, error) {
svc := GetCache()
if svc == nil {
return false, ErrRedisNotReady
}
return svc.Get(ctx, key, dest)
}
// Exists 检查全局缓存是否存在。未命中返回 (false, nil)；缓存未初始化或
// Redis 错误返回 (false, err)。
func Exists(ctx context.Context, key string) (bool, error) {
svc := GetCache()
if svc == nil {
return false, ErrRedisNotReady
}
return svc.Exists(ctx, key)
}
cache/cache_m10_internal_test.go
Vendored
+199
View File
@@ -0,0 +1,199 @@
package cache
import (
"context"
"errors"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/database"
"github.com/alicebob/miniredis/v2"
"github.com/redis/go-redis/v9"
)
func setupM10MiniRedis(t *testing.T) *miniredis.Miniredis {
t.Helper()
mr := miniredis.RunT(t)
client := redis.NewClient(&redis.Options{Addr: mr.Addr()})
t.Cleanup(func() { _ = client.Close() })
database.SetTestRedisClient(client)
t.Cleanup(func() { database.SetTestRedisClient(nil) })
return mr
}
func TestM10CacheWritesReturnRedisNotReady(t *testing.T) {
database.SetTestRedisClient(nil)
t.Cleanup(func() { database.SetTestRedisClient(nil) })
c := &redisCache{}
ctx := context.Background()
if err := c.Set(ctx, "k", "v", time.Minute); !errors.Is(err, ErrRedisNotReady) {
t.Fatalf("Set without Redis err = %v, want ErrRedisNotReady", err)
}
if err := c.Delete(ctx, "k"); !errors.Is(err, ErrRedisNotReady) {
t.Fatalf("Delete without Redis err = %v, want ErrRedisNotReady", err)
}
if err := c.DeleteByPattern(ctx, "k:*"); !errors.Is(err, ErrRedisNotReady) {
t.Fatalf("DeleteByPattern without Redis err = %v, want ErrRedisNotReady", err)
}
}
func TestM10RawHelpersReturnRedisNotReady(t *testing.T) {
database.SetTestRedisClient(nil)
t.Cleanup(func() { database.SetTestRedisClient(nil) })
ctx := context.Background()
if _, err := Incr(ctx, "k"); !errors.Is(err, ErrRedisNotReady) {
t.Fatalf("Incr without Redis err = %v, want ErrRedisNotReady", err)
}
if _, err := IncrBy(ctx, "k", 2); !errors.Is(err, ErrRedisNotReady) {
t.Fatalf("IncrBy without Redis err = %v, want ErrRedisNotReady", err)
}
if _, err := Decr(ctx, "k"); !errors.Is(err, ErrRedisNotReady) {
t.Fatalf("Decr without Redis err = %v, want ErrRedisNotReady", err)
}
if _, err := GetTTL(ctx, "k"); !errors.Is(err, ErrRedisNotReady) {
t.Fatalf("GetTTL without Redis err = %v, want ErrRedisNotReady", err)
}
if _, err := SetExpire(ctx, "k", time.Minute); !errors.Is(err, ErrRedisNotReady) {
t.Fatalf("SetExpire without Redis err = %v, want ErrRedisNotReady", err)
}
if _, err := GetRaw(ctx, "k"); !errors.Is(err, ErrRedisNotReady) {
t.Fatalf("GetRaw without Redis err = %v, want ErrRedisNotReady", err)
}
if err := SetRaw(ctx, "k", "v", time.Minute); !errors.Is(err, ErrRedisNotReady) {
t.Fatalf("SetRaw without Redis err = %v, want ErrRedisNotReady", err)
}
}
func TestM10ExistsReturnsBackendErrors(t *testing.T) {
setupM10MiniRedis(t)
c := &redisCache{}
ctx := context.Background()
exists, err := c.Exists(ctx, "missing")
if err != nil {
t.Fatalf("Exists missing err = %v", err)
}
if exists {
t.Fatal("Exists missing = true, want false")
}
if err := c.Set(ctx, "present", "value", time.Minute); err != nil {
t.Fatalf("Set present: %v", err)
}
exists, err = c.Exists(ctx, "present")
if err != nil || !exists {
t.Fatalf("Exists present = %v, err=%v; want true,nil", exists, err)
}
canceled, cancel := context.WithCancel(ctx)
cancel()
if exists, err = c.Exists(canceled, "present"); err == nil || exists {
t.Fatalf("Exists canceled = %v, err=%v; want false,error", exists, err)
}
}
func TestM10GetReturnsBackendAndDecodeErrors(t *testing.T) {
setupM10MiniRedis(t)
c := &redisCache{}
ctx := context.Background()
var got string
ok, err := c.Get(ctx, "missing", &got)
if err != nil || ok {
t.Fatalf("Get missing = %v, err=%v; want false,nil", ok, err)
}
if err := c.Set(ctx, "present", "value", time.Minute); err != nil {
t.Fatalf("Set present: %v", err)
}
ok, err = c.Get(ctx, "present", &got)
if err != nil || !ok || got != "value" {
t.Fatalf("Get present = %v, %q, err=%v; want true,value,nil", ok, got, err)
}
if err := c.client().Set(ctx, "bad-json", "{", time.Minute).Err(); err != nil {
t.Fatalf("Set bad-json: %v", err)
}
ok, err = c.Get(ctx, "bad-json", &got)
if err == nil || ok {
t.Fatalf("Get bad-json = %v, err=%v; want false,error", ok, err)
}
canceled, cancel := context.WithCancel(ctx)
cancel()
ok, err = c.Get(canceled, "present", &got)
if err == nil || ok {
t.Fatalf("Get canceled = %v, err=%v; want false,error", ok, err)
}
}
func TestM10PackageExistsReturnsBackendErrors(t *testing.T) {
setupM10MiniRedis(t)
orig := GetDefaultCache()
t.Cleanup(func() { SetDefaultCacheManager(orig) })
SetDefaultCacheManager(NewCacheManager())
Init()
ctx := context.Background()
if err := GetCache().Set(ctx, "present", "value", time.Minute); err != nil {
t.Fatalf("Set through facade: %v", err)
}
exists, err := Exists(ctx, "present")
if err != nil || !exists {
t.Fatalf("facade Exists = %v, err=%v; want true,nil", exists, err)
}
}
func TestM10PackageGetReturnsBackendErrors(t *testing.T) {
setupM10MiniRedis(t)
orig := GetDefaultCache()
t.Cleanup(func() { SetDefaultCacheManager(orig) })
SetDefaultCacheManager(NewCacheManager())
Init()
ctx := context.Background()
if err := GetCache().Set(ctx, "present", "value", time.Minute); err != nil {
t.Fatalf("Set through facade: %v", err)
}
var got string
ok, err := Get(ctx, "present", &got)
if err != nil || !ok || got != "value" {
t.Fatalf("facade Get = %v, %q, err=%v; want true,value,nil", ok, got, err)
}
}
// TestM10CustomCacheServiceCompile asserts a user-provided CacheService
// implementation compiles against the (bool, error) contract. This is a
// compile-time guard: if the interface changes again, this stops building.
type customCacheSvc struct{}
func (customCacheSvc) Get(ctx context.Context, key string, dest any) (bool, error) { return false, nil }
func (customCacheSvc) Set(ctx context.Context, key string, value any, ttl time.Duration) error {
return nil
}
func (customCacheSvc) Delete(ctx context.Context, key string) error { return nil }
func (customCacheSvc) DeleteByPattern(ctx context.Context, p string) error { return nil }
func (customCacheSvc) Exists(ctx context.Context, key string) (bool, error) { return false, nil }
func TestM10CustomCacheServiceCompiles(t *testing.T) {
var _ CacheService = customCacheSvc{}
}
// TestM10RedisNotReadyOnGetExists asserts the Redis-not-ready error is
// surfaced (not swallowed) when no backend is configured.
func TestM10RedisNotReadyOnGetExists(t *testing.T) {
database.SetTestRedisClient(nil)
t.Cleanup(func() { database.SetTestRedisClient(nil) })
c := &redisCache{}
ctx := context.Background()
if _, err := c.Get(ctx, "k", new(string)); !errors.Is(err, ErrRedisNotReady) {
t.Fatalf("Get without Redis err = %v, want ErrRedisNotReady", err)
}
if _, err := c.Exists(ctx, "k"); !errors.Is(err, ErrRedisNotReady) {
t.Fatalf("Exists without Redis err = %v, want ErrRedisNotReady", err)
}
}
cache/cache_phase4_internal_test.go
Vendored
+69
View File
@@ -0,0 +1,69 @@
package cache
import (
"testing"
"github.com/EthanCodeCraft/xlgo-core/database"
"github.com/alicebob/miniredis/v2"
"github.com/redis/go-redis/v9"
)
// TestRedisCacheInjectedClientPriority 固化 Phase 4 核心契约（jwt 模型）：
// redisCache.client() 注入优先、全局兜底。注入的 client 即使与 database.GetRedis()
// 不同也必须用注入的--这是多 App 缓存隔离的基础。
func TestRedisCacheInjectedClientPriority(t *testing.T) {
// 全局 redis = clientG
mrG := miniredis.RunT(t)
clientG := redis.NewClient(&redis.Options{Addr: mrG.Addr()})
t.Cleanup(func() { _ = clientG.Close() })
origGlobal := database.SetTestRedisClient(clientG)
t.Cleanup(func() { database.SetTestRedisClient(origGlobal) })
// 注入 clientA（与全局 clientG 不同实例）
mrA := miniredis.RunT(t)
clientA := redis.NewClient(&redis.Options{Addr: mrA.Addr()})
t.Cleanup(func() { _ = clientA.Close() })
// 注入优先
injected := &redisCache{injectedClient: clientA}
if got := injected.client(); got != clientA {
t.Fatalf("injected redisCache.client() = %v, want clientA (注入优先)", got)
}
// 未注入 -> 回退全局 clientG
fallback := &redisCache{}
if got := fallback.client(); got != clientG {
t.Fatalf("fallback redisCache.client() = %v, want clientG (全局兜底)", got)
}
// NewRedisCacheWithRedis 构造的实例持注入 client
svc := NewRedisCacheWithRedis(clientA)
rc, ok := svc.(*redisCache)
if !ok {
t.Fatalf("NewRedisCacheWithRedis returned %T, want *redisCache", svc)
}
if rc.client() != clientA {
t.Fatalf("NewRedisCacheWithRedis client = %v, want clientA", rc.client())
}
}
// TestSwapDefaultCacheManagerReturnsOld 固化 Phase 4：Swap 返回被替换的旧 Manager 且不关闭。
func TestSwapDefaultCacheManagerReturnsOld(t *testing.T) {
orig := defaultCachePtr.Load()
defer SwapDefaultCacheManager(orig)
first := NewCacheManager()
if prev := SwapDefaultCacheManager(first); prev != orig {
t.Fatalf("Swap returned %v, want orig", prev)
}
second := NewCacheManager()
if returned := SwapDefaultCacheManager(second); returned != first {
t.Fatalf("Swap returned %v, want first", returned)
}
if defaultCachePtr.Load() != second {
t.Fatal("Swap did not install second as default")
}
if got := SwapDefaultCacheManager(nil); got != second {
t.Fatalf("Swap(nil) = %v, want second (current default)", got)
}
}
cache/keybuilder.go
Vendored
+297
View File
@@ -0,0 +1,297 @@
package cache
import (
"context"
"strings"
"sync"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
)
// KeyBuilder 缓存键名构建器（CK2 修复：mu 保护并发访问）。
// 使用场景: 多个小项目共用一台 Redis 服务器，每个项目设置不同前缀
type KeyBuilder struct {
mu sync.Mutex
prefix string // 项目/站点前缀，如 "site_a"
_separator string // 分隔符，默认 ":"
_cacheType string // 缓存类型标识，如 "cache"
}
// KeyBuilderOption 配置选项
type KeyBuilderOption func(*KeyBuilder)
// WithPrefix 设置前缀（项目/站点别名）
// 示例: WithPrefix("site_a") -> 所有 key 自动添加 "site_a" 前缀
func WithPrefix(prefix string) KeyBuilderOption {
return func(kb *KeyBuilder) {
if kb == nil {
return
}
kb.prefix = prefix
}
}
// WithSeparator 设置分隔符
// 示例: WithSeparator(":") -> "site_a:user:1"
func WithSeparator(separator string) KeyBuilderOption {
return func(kb *KeyBuilder) {
if kb == nil {
return
}
kb._separator = separator
}
}
// WithCacheType 设置缓存类型标识
// 示例: WithCacheType("session") -> "session:site_a:user:1"
func WithCacheType(cacheType string) KeyBuilderOption {
return func(kb *KeyBuilder) {
if kb == nil {
return
}
kb._cacheType = cacheType
}
}
// NewKeyBuilder 创建键名构建器
func NewKeyBuilder(opts ...KeyBuilderOption) *KeyBuilder {
kb := &KeyBuilder{
prefix: "",
_separator: ":",
_cacheType: "cache",
}
for _, opt := range opts {
if opt == nil {
continue
}
opt(kb)
}
return kb
}
// Build 构建完整键名（CK2 修复：mu 读保护）。
// 格式: {cacheType}{separator}{prefix}{separator}{key}
// 示例: kb.Build("user:1") -> "cache:site_a:user:1"
func (kb *KeyBuilder) Build(key string) string {
kb.mu.Lock()
defer kb.mu.Unlock()
parts := []string{}
if kb._cacheType != "" {
parts = append(parts, kb._cacheType)
}
if kb.prefix != "" {
parts = append(parts, kb.prefix)
}
parts = append(parts, key)
return strings.Join(parts, kb._separator)
}
// BuildTemp 构建临时缓存键名（CK2 修复：mu 读保护）。
// 格式: "temp{separator}{prefix}{separator}{key}"
func (kb *KeyBuilder) BuildTemp(key string) string {
kb.mu.Lock()
defer kb.mu.Unlock()
parts := []string{"temp"}
if kb.prefix != "" {
parts = append(parts, kb.prefix)
}
parts = append(parts, key)
return strings.Join(parts, kb._separator)
}
// BuildPerm 构建永久缓存键名（CK2 修复：mu 读保护）。
// 格式: "perm{separator}{prefix}{separator}{key}"
func (kb *KeyBuilder) BuildPerm(key string) string {
kb.mu.Lock()
defer kb.mu.Unlock()
parts := []string{"perm"}
if kb.prefix != "" {
parts = append(parts, kb.prefix)
}
parts = append(parts, key)
return strings.Join(parts, kb._separator)
}
// BuildLock 构建分布式锁键名（CK2 修复：mu 读保护）。
// 格式: "lock{separator}{prefix}{separator}{key}"
func (kb *KeyBuilder) BuildLock(key string) string {
kb.mu.Lock()
defer kb.mu.Unlock()
parts := []string{"lock"}
if kb.prefix != "" {
parts = append(parts, kb.prefix)
}
parts = append(parts, key)
return strings.Join(parts, kb._separator)
}
// BuildCounter 构建计数器键名（CK2 修复：mu 读保护）。
// 格式: "counter{separator}{prefix}{separator}{key}"
func (kb *KeyBuilder) BuildCounter(key string) string {
kb.mu.Lock()
defer kb.mu.Unlock()
parts := []string{"counter"}
if kb.prefix != "" {
parts = append(parts, kb.prefix)
}
parts = append(parts, key)
return strings.Join(parts, kb._separator)
}
// BuildSession 构建会话键名（CK2 修复：mu 读保护）。
// 格式: "session{separator}{prefix}{separator}{key}"
func (kb *KeyBuilder) BuildSession(key string) string {
kb.mu.Lock()
defer kb.mu.Unlock()
parts := []string{"session"}
if kb.prefix != "" {
parts = append(parts, kb.prefix)
}
parts = append(parts, key)
return strings.Join(parts, kb._separator)
}
// BuildPattern 构建匹配模式（用于 SCAN/Keys）（CK2 修复：mu 读保护）。
// 示例: kb.BuildPattern("user:*") -> "cache:site_a:user:*"
func (kb *KeyBuilder) BuildPattern(pattern string) string {
return kb.Build(pattern)
}
// GetPrefix 获取当前前缀（CK2 修复：mu 读保护）。
func (kb *KeyBuilder) GetPrefix() string {
kb.mu.Lock()
defer kb.mu.Unlock()
return kb.prefix
}
// SetPrefix 动态设置前缀（CK2 修复：mu 写保护，并发安全）。
func (kb *KeyBuilder) SetPrefix(prefix string) *KeyBuilder {
kb.mu.Lock()
defer kb.mu.Unlock()
kb.prefix = prefix
return kb
}
// ===== 全局键名构建器 =====
// globalKeyBuilder 全局构建器，受 globalKBMu 保护；globalKBOnce 保证自动初始化只执行一次（M13）。
var (
globalKeyBuilder *KeyBuilder
globalKBMu sync.RWMutex
globalKBOnce sync.Once
)
// InitKeyBuilder 初始化全局键名构建器
// 参数: prefix 站点别名，如果为空则自动从配置读取
// 示例:
//
// InitKeyBuilder("site_a") // 手动指定
// InitKeyBuilder("") // 自动从配置读取
// InitKeyBuilder("", WithSeparator(":")) // 自动读取 + 自定义分隔符
func InitKeyBuilder(prefix string, opts ...KeyBuilderOption) {
// 如果 prefix 为空，尝试从配置读取
if prefix == "" {
cfg := config.Get()
if cfg != nil {
prefix = cfg.GetSiteName()
}
}
opts = append([]KeyBuilderOption{WithPrefix(prefix)}, opts...)
kb := NewKeyBuilder(opts...)
globalKBMu.Lock()
globalKeyBuilder = kb
globalKBMu.Unlock()
}
// AutoInitKeyBuilder 自动从配置初始化键名构建器
// 配置示例:
//
// app:
// site_name: "site_a"
// env: "prod"
func AutoInitKeyBuilder(opts ...KeyBuilderOption) {
InitKeyBuilder("", opts...)
}
// GetKeyBuilder 获取全局键名构建器，未初始化时用 sync.Once 自动初始化一次（M13）。
func GetKeyBuilder() *KeyBuilder {
globalKBOnce.Do(func() {
// 仅在仍为 nil 时自动初始化（已由 InitKeyBuilder 设置则跳过）。
globalKBMu.RLock()
kb := globalKeyBuilder
globalKBMu.RUnlock()
if kb == nil {
AutoInitKeyBuilder()
}
})
globalKBMu.RLock()
defer globalKBMu.RUnlock()
return globalKeyBuilder
}
// K 快捷构建键名（使用全局构建器）
// 示例: cache.K("user:1") -> 自动添加前缀
func K(key string) string {
return GetKeyBuilder().Build(key)
}
// KTemp 快捷构建临时缓存键名
func KTemp(key string) string {
return GetKeyBuilder().BuildTemp(key)
}
// KPerm 快捷构建永久缓存键名
func KPerm(key string) string {
return GetKeyBuilder().BuildPerm(key)
}
// KLock 快捷构建锁键名
func KLock(key string) string {
return GetKeyBuilder().BuildLock(key)
}
// KCounter 快捷构建计数器键名
func KCounter(key string) string {
return GetKeyBuilder().BuildCounter(key)
}
// KSession 快捷构建会话键名
func KSession(key string) string {
return GetKeyBuilder().BuildSession(key)
}
// ===== 带键名构建器的缓存操作 =====
// SetWithPrefix 带前缀的缓存设置
func SetWithPrefix(ctx context.Context, key string, value any, ttl time.Duration, prefix string) error {
kb := NewKeyBuilder(WithPrefix(prefix))
return GetCache().Set(ctx, kb.Build(key), value, ttl)
}
// GetWithPrefix 带前缀的缓存获取。命中返回 (true, nil)；未命中返回 (false, nil)；
// Redis 错误或反序列化失败返回 (false, err)。
func GetWithPrefix(ctx context.Context, key string, dest any, prefix string) (bool, error) {
kb := NewKeyBuilder(WithPrefix(prefix))
return GetCache().Get(ctx, kb.Build(key), dest)
}
// DeleteWithPrefix 带前缀的缓存删除
func DeleteWithPrefix(ctx context.Context, key string, prefix string) error {
kb := NewKeyBuilder(WithPrefix(prefix))
return GetCache().Delete(ctx, kb.Build(key))
}
// LockWithPrefix 带前缀的分布式锁
func LockWithPrefix(ctx context.Context, key string, ttl time.Duration, prefix string) (bool, error) {
kb := NewKeyBuilder(WithPrefix(prefix))
return Lock(ctx, kb.BuildLock(key), ttl)
}
// UnlockWithPrefix 带前缀的锁释放
// 注意: 此函数不检查 Token，仅用于向后兼容，建议使用 NewLock/Unlock 组合
func UnlockWithPrefix(ctx context.Context, key string, prefix string) error {
kb := NewKeyBuilder(WithPrefix(prefix))
return UnlockByKey(ctx, kb.BuildLock(key))
}
cache/keybuilder_m13_internal_test.go
Vendored
+31
View File
@@ -0,0 +1,31 @@
package cache
import (
"sync"
"testing"
)
// TestGlobalKeyBuilderConcurrentInitGet_M13：并发 InitKeyBuilder/GetKeyBuilder/K 不触发 data race
// 且不 nil-panic（M13：sync.Once + RWMutex 保护全局构建器）。须配合 -race 运行。
func TestGlobalKeyBuilderConcurrentInitGet_M13(t *testing.T) {
// 预置一个已知前缀，避免依赖 config.Get。
InitKeyBuilder("race_site")
t.Cleanup(func() { globalKBMu.Lock(); globalKeyBuilder = nil; globalKBMu.Unlock() })
var wg sync.WaitGroup
for i := 0; i < 50; i++ {
wg.Add(3)
go func() { defer wg.Done(); InitKeyBuilder("race_site") }()
go func() { defer wg.Done(); _ = GetKeyBuilder() }()
go func() { defer wg.Done(); _ = K("user:1") }()
}
wg.Wait()
// 最终 GetKeyBuilder 非 nil，K 返回带前缀键。
if GetKeyBuilder() == nil {
t.Fatal("GetKeyBuilder nil after concurrent init")
}
if got := K("user:1"); got == "user:1" {
t.Errorf("K returned unprefixed key %q (prefix not applied)", got)
}
}
cache/keybuilder_test.go
Vendored
+225
View File
@@ -0,0 +1,225 @@
package cache_test
import (
"testing"
"github.com/EthanCodeCraft/xlgo-core/cache"
)
func TestKeyBuilder(t *testing.T) {
kb := cache.NewKeyBuilder(
cache.WithPrefix("test_site"),
cache.WithSeparator(":"),
cache.WithCacheType("cache"),
)
// 测试 Build
result := kb.Build("user:1")
expected := "cache:test_site:user:1"
if result != expected {
t.Errorf("Build = %s, want %s", result, expected)
}
// 测试 BuildTemp
tempResult := kb.BuildTemp("token")
if tempResult != "temp:test_site:token" {
t.Errorf("BuildTemp = %s, want temp:test_site:token", tempResult)
}
// 测试 BuildPerm
permResult := kb.BuildPerm("config")
if permResult != "perm:test_site:config" {
t.Errorf("BuildPerm = %s, want perm:test_site:config", permResult)
}
// 测试 BuildLock
lockResult := kb.BuildLock("order:123")
if lockResult != "lock:test_site:order:123" {
t.Errorf("BuildLock = %s, want lock:test_site:order:123", lockResult)
}
// 测试 BuildCounter
counterResult := kb.BuildCounter("visit")
if counterResult != "counter:test_site:visit" {
t.Errorf("BuildCounter = %s, want counter:test_site:visit", counterResult)
}
// 测试 BuildSession
sessionResult := kb.BuildSession("sid123")
if sessionResult != "session:test_site:sid123" {
t.Errorf("BuildSession = %s, want session:test_site:sid123", sessionResult)
}
}
func TestKeyBuilderNoPrefix(t *testing.T) {
// 无前缀的构建器
kb := cache.NewKeyBuilder()
result := kb.Build("user:1")
expected := "cache:user:1"
if result != expected {
t.Errorf("Build without prefix = %s, want %s", result, expected)
}
}
func TestKeyBuilderNilOptionIgnored(t *testing.T) {
kb := cache.NewKeyBuilder(nil, cache.WithPrefix("site"))
if got := kb.Build("user:1"); got != "cache:site:user:1" {
t.Fatalf("Build with nil option = %q, want cache:site:user:1", got)
}
cache.WithPrefix("ignored")(nil)
cache.WithSeparator("_")(nil)
cache.WithCacheType("ignored")(nil)
}
func TestKeyBuilderSetPrefix(t *testing.T) {
kb := cache.NewKeyBuilder(cache.WithPrefix("site_a"))
// 动态修改前缀
kb.SetPrefix("site_b")
result := kb.Build("user:1")
if result != "cache:site_b:user:1" {
t.Errorf("SetPrefix failed: %s", result)
}
// 验证链式调用
kb2 := kb.SetPrefix("site_c")
if kb2 != kb {
t.Error("SetPrefix should return same builder")
}
}
func TestKeyBuilderGetPrefix(t *testing.T) {
kb := cache.NewKeyBuilder(cache.WithPrefix("my_site"))
prefix := kb.GetPrefix()
if prefix != "my_site" {
t.Errorf("GetPrefix = %s, want my_site", prefix)
}
}
func TestKeyBuilderBuildPattern(t *testing.T) {
kb := cache.NewKeyBuilder(cache.WithPrefix("site_a"))
result := kb.BuildPattern("user:*")
if result != "cache:site_a:user:*" {
t.Errorf("BuildPattern = %s, want cache:site_a:user:*", result)
}
}
func TestKeyBuilderCustomSeparator(t *testing.T) {
kb := cache.NewKeyBuilder(
cache.WithPrefix("site"),
cache.WithSeparator("_"),
)
result := kb.Build("user:1")
if result != "cache_site_user:1" {
t.Errorf("Custom separator = %s, want cache_site_user:1", result)
}
}
func TestKeyBuilderCustomCacheType(t *testing.T) {
kb := cache.NewKeyBuilder(
cache.WithPrefix("site"),
cache.WithCacheType("session"),
)
result := kb.Build("user:1")
if result != "session:site:user:1" {
t.Errorf("Custom cache type = %s, want session:site:user:1", result)
}
}
func TestGlobalKeyBuilder(t *testing.T) {
// 初始化全局构建器
cache.InitKeyBuilder("global_site")
// 测试 K 函数
result := cache.K("user:1")
if result != "cache:global_site:user:1" {
t.Errorf("K = %s, want cache:global_site:user:1", result)
}
// 测试 KTemp
temp := cache.KTemp("token")
if temp != "temp:global_site:token" {
t.Errorf("KTemp = %s, want temp:global_site:token", temp)
}
// 测试 KPerm
perm := cache.KPerm("config")
if perm != "perm:global_site:config" {
t.Errorf("KPerm = %s, want perm:global_site:config", perm)
}
// 测试 KLock
lock := cache.KLock("order:123")
if lock != "lock:global_site:order:123" {
t.Errorf("KLock = %s, want lock:global_site:order:123", lock)
}
// 测试 KCounter
counter := cache.KCounter("visit")
if counter != "counter:global_site:visit" {
t.Errorf("KCounter = %s, want counter:global_site:visit", counter)
}
// 测试 KSession
session := cache.KSession("sid")
if session != "session:global_site:sid" {
t.Errorf("KSession = %s, want session:global_site:sid", session)
}
}
func TestGetKeyBuilder(t *testing.T) {
// 获取全局构建器（如果未初始化会自动初始化）
kb := cache.GetKeyBuilder()
if kb == nil {
t.Error("GetKeyBuilder should not return nil")
}
}
func TestWithPrefixFunc(t *testing.T) {
opt := cache.WithPrefix("test")
kb := cache.NewKeyBuilder()
opt(kb)
if kb.GetPrefix() != "test" {
t.Errorf("WithPrefix failed")
}
}
func TestWithSeparatorFunc(t *testing.T) {
opt := cache.WithSeparator("_")
kb := cache.NewKeyBuilder()
opt(kb)
result := kb.Build("key")
// 分隔符应该是 _
if !contains(result, "_") {
t.Errorf("WithSeparator failed, result: %s", result)
}
}
func TestWithCacheTypeFunc(t *testing.T) {
opt := cache.WithCacheType("custom")
kb := cache.NewKeyBuilder()
opt(kb)
result := kb.Build("key")
if !contains(result, "custom") {
t.Errorf("WithCacheType failed, result: %s", result)
}
}
func contains(s, sub string) bool {
for i := 0; i <= len(s)-len(sub); i++ {
if s[i:i+len(sub)] == sub {
return true
}
}
return false
}
cache/lock.go
Vendored
+428
View File
@@ -0,0 +1,428 @@
package cache
import (
"context"
"errors"
"fmt"
"time"
"github.com/EthanCodeCraft/xlgo-core/database"
"github.com/EthanCodeCraft/xlgo-core/utils"
)
// 分布式锁错误
var (
ErrLockNotHeld = errors.New("锁未被当前客户端持有")
ErrLockExpired = errors.New("锁已过期")
ErrRedisNotReady = errors.New("Redis 未初始化")
// ErrLockNotAcquired 表示锁被其它客户端持有，业务函数未执行。
ErrLockNotAcquired = errors.New("未获取到锁")
// ErrInvalidLockTTL 表示锁 TTL 小于 Redis PX 支持的 1ms 粒度或非正。
ErrInvalidLockTTL = errors.New("锁 TTL 必须大于等于 1ms")
// ErrInvalidLockRetryInterval 表示重试或续期间隔非法。
ErrInvalidLockRetryInterval = errors.New("锁重试/续期间隔必须大于 0")
// ErrLockUnexpectedResult Lua 脚本返回了非预期的结果类型（C1b：裸类型断言防护）。
ErrLockUnexpectedResult = errors.New("锁脚本返回非预期结果")
// ErrLockFuncNil 表示分布式锁业务函数为空。
ErrLockFuncNil = errors.New("锁业务函数不能为空")
)
// toInt64 将 Lua 脚本返回值安全断言为 int64（C1b：禁止裸断言 panic）。
// go-redis 对整数返回 int64，但 nil/错误响应下可能为其他类型。
func toInt64(v any) (int64, error) {
n, ok := v.(int64)
if !ok {
return 0, fmt.Errorf("脚本返回类型 %T: %w", v, ErrLockUnexpectedResult)
}
return n, nil
}
func ttlMillis(ttl time.Duration) (int64, error) {
if ttl < time.Millisecond {
return 0, ErrInvalidLockTTL
}
return int64(ttl / time.Millisecond), nil
}
// LockToken 锁令牌（用于安全释放锁）。
//
// 安全说明（C1d 设计局限）：Token 是随机 UUID（非单调递增的 fencing token）。
// 本实现基于 Redis SET PX + Lua CAS，保证"持有者才能解锁/续期"，但**无法防 TTL 到期后的
// 双 worker 并发**：若 worker A 因 GC/网络停滞超过 TTL，锁过期后 worker B 获得锁，
// A 恢复后仍可能写过期数据。完整的 fencing token 防护需：① 用 Redis INCR 生成单调 token，
// ② 下游存储层（DB/外部服务）记录已见最大 token 并拒绝旧 token 写入。
// 框架无法单方面保证②，需下游配合，故本类型仅提供 UUID token。对 TTL 到期敏感的场景，
// 请确保 ttl >> 业务最长执行时间，或下游实现 fencing token 校验。
type LockToken struct {
Key string // 锁的键名
Token string // 锁的唯一标识（UUID）
}
// lockScript 加锁 Lua 脚本
// 返回: 1 表示成功加锁，0 表示锁已被占用
const lockScript = `
if redis.call("exists", KEYS[1]) == 0 then
redis.call("set", KEYS[1], ARGV[1], "PX", ARGV[2])
return 1
else
return 0
end
`
// unlockScript 解锁 Lua 脯本
// 只有持有正确 Token 的客户端才能解锁
// 返回: 1 表示成功解锁，0 表示 Token 不匹配（锁不属于该客户端）
const unlockScript = `
if redis.call("get", KEYS[1]) == ARGV[1] then
redis.call("del", KEYS[1])
return 1
else
return 0
end
`
// extendScript 续期 Lua 脚本
// 只有持有正确 Token 的客户端才能续期
// 返回: 1 表示成功续期，0 表示 Token 不匹配或锁不存在
const extendScript = `
if redis.call("get", KEYS[1]) == ARGV[1] then
redis.call("pexpire", KEYS[1], ARGV[2])
return 1
else
return 0
end
`
// NewLock 创建分布式锁
// 参数: key 锁名称，ttl 锁定时长
// 返回: LockToken 用于后续解锁或续期
func NewLock(ctx context.Context, key string, ttl time.Duration) (*LockToken, error) {
rdb := database.GetRedis()
if rdb == nil {
return nil, ErrRedisNotReady
}
token := utils.UUID()
ttlMs, err := ttlMillis(ttl)
if err != nil {
return nil, err
}
result, err := rdb.Eval(ctx, lockScript, []string{key}, token, ttlMs).Result()
if err != nil {
return nil, err
}
n, err := toInt64(result)
if err != nil {
return nil, err
}
if n == 1 {
return &LockToken{Key: key, Token: token}, nil
}
return nil, nil // 锁已被其他客户端持有
}
// Lock 简化的加锁函数（返回 bool）
// 注意: 使用此函数无法安全释放锁，建议使用 NewLock
func Lock(ctx context.Context, key string, ttl time.Duration) (bool, error) {
token, err := NewLock(ctx, key, ttl)
if err != nil {
return false, err
}
return token != nil, nil
}
// Unlock 安全释放锁
func Unlock(ctx context.Context, token *LockToken) error {
rdb := database.GetRedis()
if rdb == nil {
return ErrRedisNotReady
}
if token == nil {
return ErrLockNotHeld
}
result, err := rdb.Eval(ctx, unlockScript, []string{token.Key}, token.Token).Result()
if err != nil {
return err
}
n, err := toInt64(result)
if err != nil {
return err
}
if n == 0 {
return ErrLockNotHeld
}
return nil
}
// UnlockByKey 按键名释放锁（不安全，仅用于旧代码兼容）
// 注意: 此函数不检查 Token，任何客户端都能释放锁
func UnlockByKey(ctx context.Context, key string) error {
rdb := database.GetRedis()
if rdb == nil {
return ErrRedisNotReady
}
return rdb.Del(ctx, key).Err()
}
// ExtendLock 续期锁
// 参数: token 锁令牌，ttl 新的过期时间
func ExtendLock(ctx context.Context, token *LockToken, ttl time.Duration) error {
rdb := database.GetRedis()
if rdb == nil {
return ErrRedisNotReady
}
if token == nil {
return ErrLockNotHeld
}
ttlMs, err := ttlMillis(ttl)
if err != nil {
return err
}
result, err := rdb.Eval(ctx, extendScript, []string{token.Key}, token.Token, ttlMs).Result()
if err != nil {
return err
}
n, err := toInt64(result)
if err != nil {
return err
}
if n == 0 {
return ErrLockNotHeld
}
return nil
}
// TryLock 尝试获取锁，失败时等待重试。重试等待响应 ctx 取消（C1c 修复）。
func TryLock(ctx context.Context, key string, ttl time.Duration, retryInterval time.Duration, maxRetry int) (*LockToken, error) {
if retryInterval <= 0 {
return nil, ErrInvalidLockRetryInterval
}
for i := 0; i < maxRetry; i++ {
token, err := NewLock(ctx, key, ttl)
if err != nil {
return nil, err
}
if token != nil {
return token, nil
}
// 响应 ctx 取消，避免最长阻塞 maxRetry*retryInterval（C1c：禁止 time.Sleep 无视 ctx）。
select {
case <-ctx.Done():
return nil, ctx.Err()
case <-time.After(retryInterval):
}
}
return nil, ErrLockNotAcquired
}
// WithLock 使用分布式锁执行函数（自动管理锁）。
// 参数: key 锁名称，ttl 锁定时长，fn 业务函数
// 注意: 如果任务执行时间超过 ttl，需要设置更长的 ttl 或使用 WithLockAutoExtend。
//
// 解锁用独立 Background ctx（C1a 一致性修复）：fn 返回或 panic 后，原 ctx 可能已被
// 调用方取消，用其解锁会失败导致锁泄漏到 TTL。fn panic 时 defer 也保证解锁执行。
func WithLock(ctx context.Context, key string, ttl time.Duration, fn func(context.Context) error) error {
if fn == nil {
return ErrLockFuncNil
}
token, err := NewLock(ctx, key, ttl)
if err != nil {
return err
}
if token == nil {
return ErrLockNotAcquired
}
defer func() {
unlockCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
_ = Unlock(unlockCtx, token)
}()
return fn(ctx)
}
// WithLockAutoExtend 使用分布式锁执行函数（自动续期）。
// 参数: key 锁名称，initialTTL 初始锁定时长，extendInterval 续期间隔，fn 业务函数
//
// 并发安全说明（C1a 修复）：续期 goroutine 与父用"父关停 + 子 ack"双 channel 协调——
// 父用 close(stop) 通知子退出（close 由唯一所有者执行，安全），子用 close(finished) ack。
// 避免旧实现 done 无缓冲 + 子 defer close(done) + 父 done<-struct{}{} 的 send-on-closed panic
// （ctx 取消或 ExtendLock 失败时 done 已 closed，父再 send 即 panic，Unlock 不执行、锁泄漏到 TTL）。
// Unlock 用 context.Background() 派生超时，避免原 ctx 已取消致 Unlock 失败再泄漏。
func WithLockAutoExtend(ctx context.Context, key string, initialTTL time.Duration, extendInterval time.Duration, fn func(context.Context) error) error {
if fn == nil {
return ErrLockFuncNil
}
if extendInterval <= 0 {
return ErrInvalidLockRetryInterval
}
token, err := NewLock(ctx, key, initialTTL)
if err != nil {
return err
}
if token == nil {
return ErrLockNotAcquired
}
// 父关停信号（仅父 close）与子 ack 信号（仅子 close）。
stop := make(chan struct{})
finished := make(chan struct{})
go func() {
defer close(finished) // 子退出时 ack，父等待 finished
ticker := time.NewTicker(extendInterval)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-stop:
return
case <-ticker.C:
// 续期锁（每次续期为 initialTTL）。续期失败则停止续期，fn 应尽快结束。
if err := ExtendLock(ctx, token, initialTTL); err != nil {
return
}
}
}
}()
// defer 兜底：fn panic 时也要停止续期 goroutine 并释放锁（C1a panic 路径修复）。
// 无 defer 时 fn panic 会导致 close(stop) 不执行 → 续期 goroutine 永久泄漏，且 Unlock 不执行 → 锁泄漏到 TTL。
defer func() {
close(stop)
<-finished
unlockCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
_ = Unlock(unlockCtx, token)
}()
// 执行业务函数。fn 必须接收 ctx，避免请求取消后业务 loader/DB/HTTP 调用继续运行。
err = fn(ctx)
return err
}
// IsLocked 检查锁是否被占用（不获取锁）。
//
// M-E 修复（失败语义统一）：Redis 未初始化时返回 (false, ErrRedisNotReady) 而非 (false, nil)——
// 后者与"锁确实未被占用"不可区分，调用方可能误以为可获取锁而进入临界区（正确性 bug）。
// 调用方应 errors.Is(err, ErrRedisNotReady) 区分"Redis 不可用"与"锁未占用"。
// L-G 修复：用 .Result() 显式返回 Redis 错误（原 .Val() 吞错致故障被当"未占用"）。
//
// 契约说明：锁操作有正确性影响（无锁进入临界区 = bug），故 Redis 不可用时显式返错；
// 与 cache.Get/Set 等数据操作（性能层、best-effort 静默 no-op）区分。
func IsLocked(ctx context.Context, key string) (bool, error) {
rdb := database.GetRedis()
if rdb == nil {
return false, ErrRedisNotReady
}
n, err := rdb.Exists(ctx, key).Result()
if err != nil {
return false, err
}
return n > 0, nil
}
// GetLockTTL 获取锁的剩余过期时间。
//
// M-E 修复：Redis 未初始化时返回 (0, ErrRedisNotReady) 而非 (0, nil)，调用方可区分
// "Redis 不可用"与"锁不存在/已过期"（后者 TTL=-1/-2）。
func GetLockTTL(ctx context.Context, key string) (time.Duration, error) {
rdb := database.GetRedis()
if rdb == nil {
return 0, ErrRedisNotReady
}
return rdb.TTL(ctx, key).Result()
}
// ForceUnlock 强制释放锁（危险操作，仅用于管理场景）
// 注意: 此函数不检查 Token，强制删除锁
//
// M-E 修复：Redis 未初始化时返回 ErrRedisNotReady 而非 nil——原 nil 让调用方误以为
// 已解锁成功、实则从未操作。管理脚本应据此重试或告警，而非假设成功。
func ForceUnlock(ctx context.Context, key string) error {
rdb := database.GetRedis()
if rdb == nil {
return ErrRedisNotReady
}
return rdb.Del(ctx, key).Err()
}
// ===== 计数器操作 =====
// Incr 自增计数器
func Incr(ctx context.Context, key string) (int64, error) {
rdb := database.GetRedis()
if rdb == nil {
return 0, ErrRedisNotReady
}
return rdb.Incr(ctx, key).Result()
}
// IncrBy 指定增量自增
func IncrBy(ctx context.Context, key string, value int64) (int64, error) {
rdb := database.GetRedis()
if rdb == nil {
return 0, ErrRedisNotReady
}
return rdb.IncrBy(ctx, key, value).Result()
}
// Decr 自减计数器
func Decr(ctx context.Context, key string) (int64, error) {
rdb := database.GetRedis()
if rdb == nil {
return 0, ErrRedisNotReady
}
return rdb.Decr(ctx, key).Result()
}
// GetTTL 获取键的剩余过期时间
func GetTTL(ctx context.Context, key string) (time.Duration, error) {
rdb := database.GetRedis()
if rdb == nil {
return 0, ErrRedisNotReady
}
return rdb.TTL(ctx, key).Result()
}
// SetExpire 设置键的过期时间
func SetExpire(ctx context.Context, key string, ttl time.Duration) (bool, error) {
rdb := database.GetRedis()
if rdb == nil {
return false, ErrRedisNotReady
}
return rdb.Expire(ctx, key, ttl).Result()
}
// GetRaw 获取原始字符串值（不反序列化）
func GetRaw(ctx context.Context, key string) (string, error) {
rdb := database.GetRedis()
if rdb == nil {
return "", ErrRedisNotReady
}
return rdb.Get(ctx, key).Result()
}
// SetRaw 设置原始值（不序列化）
func SetRaw(ctx context.Context, key string, value string, ttl time.Duration) error {
rdb := database.GetRedis()
if rdb == nil {
return ErrRedisNotReady
}
return rdb.Set(ctx, key, value, ttl).Err()
}
cache/lock_concurrency_test.go
Vendored
+413
View File
@@ -0,0 +1,413 @@
package cache_test
import (
"context"
"errors"
"sync"
"sync/atomic"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/cache"
"github.com/EthanCodeCraft/xlgo-core/database"
"github.com/alicebob/miniredis/v2"
"github.com/redis/go-redis/v9"
)
// setupMiniRedis 启动一个 miniredis 实例并把它注入 database 内部，返回清理函数。
func setupMiniRedis(t *testing.T) *miniredis.Miniredis {
t.Helper()
mr := miniredis.RunT(t)
client := redis.NewClient(&redis.Options{Addr: mr.Addr()})
t.Cleanup(func() { _ = client.Close() })
// 通过 SetTestRedisClient 注入 miniredis 客户端到 database 包的内部 redisClient
database.SetTestRedisClient(client)
t.Cleanup(func() { database.SetTestRedisClient(nil) })
return mr
}
// ===== C1a：WithLockAutoExtend 不 panic / 不泄漏锁 =====
// 回归 C1a：ctx 取消时 WithLockAutoExtend 不 send-on-closed panic，且锁被释放。
// 旧实现：ctx 取消时子 goroutine defer close(done)，父 fn() 后 done<-struct{}{} 即 panic，
// Unlock 不执行，锁泄漏到 TTL。
func TestWithLockAutoExtendCtxCancelNoPanic(t *testing.T) {
mr := setupMiniRedis(t)
_ = mr
ctx, cancel := context.WithCancel(context.Background())
key := "c1a:cancel"
ran := make(chan struct{})
var panicked any
var wg sync.WaitGroup
wg.Add(1)
go func() {
defer wg.Done()
defer func() { panicked = recover() }()
err := cache.WithLockAutoExtend(ctx, key, 10*time.Second, 100*time.Millisecond, func(runCtx context.Context) error {
close(ran)
// 阻塞直到 ctx 被取消，模拟长任务。
<-runCtx.Done()
return runCtx.Err()
})
// WithLockAutoExtend 返回 fn 的错误（ctx.Err），不应 panic。
if err != nil && !errors.Is(err, context.Canceled) {
t.Errorf("unexpected err: %v", err)
}
}()
// 等 fn 启动 + 至少一次续期 ticker，再取消 ctx，制造最大竞态窗口。
<-ran
time.Sleep(250 * time.Millisecond)
cancel()
wg.Wait()
if panicked != nil {
t.Fatalf("WithLockAutoExtend panicked on ctx cancel (C1a send-on-closed): %v", panicked)
}
// 锁必须被释放（Unlock 用 Background ctx 执行）。
locked, err := cache.IsLocked(context.Background(), key)
if err != nil {
t.Fatalf("IsLocked: %v", err)
}
if locked {
t.Error("lock leaked after ctx cancel (Unlock not executed)")
}
}
// 回归 C1a：fn 正常返回时锁被释放，无 panic。
func TestWithLockAutoExtendNormalRelease(t *testing.T) {
setupMiniRedis(t)
ctx := context.Background()
key := "c1a:normal"
called := false
err := cache.WithLockAutoExtend(ctx, key, 10*time.Second, 100*time.Millisecond, func(context.Context) error {
called = true
return nil
})
if err != nil {
t.Fatalf("WithLockAutoExtend: %v", err)
}
if !called {
t.Error("fn not called")
}
locked, _ := cache.IsLocked(ctx, key)
if locked {
t.Error("lock not released after normal fn return")
}
}
// 回归 C1a：fn 执行超过续期间隔，锁被续期不丢失（续期 goroutine 工作）。
func TestWithLockAutoExtendExtendsLock(t *testing.T) {
mr := setupMiniRedis(t)
ctx := context.Background()
key := "c1a:extend"
// initialTTL=500ms，extendInterval=100ms。fn 执行 800ms，期间应多次续期。
// 若续期失效，锁会在 500ms 过期，另一 worker 可获取。
err := cache.WithLockAutoExtend(ctx, key, 500*time.Millisecond, 100*time.Millisecond, func(context.Context) error {
time.Sleep(800 * time.Millisecond)
return nil
})
if err != nil {
t.Fatalf("WithLockAutoExtend: %v", err)
}
// 期间另一 worker 应无法获取锁（续期生效）。
// 此断言在 fn 执行中验证更准；这里用 fn 返回后锁已释放验证基础闭环。
locked, _ := cache.IsLocked(ctx, key)
if locked {
t.Error("lock not released after fn")
}
_ = mr
}
// 回归 C1a：fn 执行中另一 worker 拿不到锁（续期保活）。
func TestWithLockAutoExtendBlocksContender(t *testing.T) {
setupMiniRedis(t)
ctx := context.Background()
key := "c1a:block"
fnStarted := make(chan struct{})
fnDone := make(chan struct{})
lockDone := make(chan struct{})
var contenderGotLock atomic.Bool
go func() {
defer close(lockDone)
cache.WithLockAutoExtend(ctx, key, 2*time.Second, 100*time.Millisecond, func(context.Context) error {
close(fnStarted)
time.Sleep(600 * time.Millisecond)
close(fnDone)
return nil
})
}()
<-fnStarted
// 期间尝试获取锁，应失败（nil）。
token, err := cache.NewLock(ctx, key, 2*time.Second)
if err != nil {
t.Fatalf("NewLock contender: %v", err)
}
if token != nil {
contenderGotLock.Store(true)
_ = cache.Unlock(ctx, token)
}
<-fnDone
<-lockDone
if contenderGotLock.Load() {
t.Error("contender acquired lock while auto-extend active (extend failed)")
}
}
// 回归 C1a：fn panic 时锁仍被释放、续期 goroutine 不泄漏（defer 兜底）。
// 旧实现（无 defer）fn panic → close(stop) 不执行 → 续期 goroutine 永久泄漏 + Unlock 不执行 → 锁泄漏。
func TestWithLockAutoExtendFnPanicReleasesLock(t *testing.T) {
setupMiniRedis(t)
ctx := context.Background()
key := "c1a:panic"
var panicked any
func() {
defer func() { panicked = recover() }()
_ = cache.WithLockAutoExtend(ctx, key, 10*time.Second, 100*time.Millisecond, func(context.Context) error {
time.Sleep(150 * time.Millisecond) // 让续期 ticker 至少触发一次
panic("boom")
})
}()
if panicked == nil {
t.Fatal("expected fn panic to propagate")
}
// 锁必须被释放（defer Unlock 执行）。
locked, _ := cache.IsLocked(ctx, key)
if locked {
t.Error("lock leaked after fn panic (defer Unlock not executed)")
}
}
// 回归 C1a/HIGH：WithLock 在 ctx 取消后仍能解锁（Unlock 用 Background ctx）。
// 旧实现 defer Unlock(ctx, token) 用原 ctx，ctx 取消致 Unlock 失败、锁泄漏到 TTL。
func TestWithLockCtxCancelReleasesLock(t *testing.T) {
setupMiniRedis(t)
ctx, cancel := context.WithCancel(context.Background())
key := "c1a:withlock"
fnStarted := make(chan struct{})
done := make(chan struct{})
go func() {
defer close(done)
_ = cache.WithLock(ctx, key, 10*time.Second, func(runCtx context.Context) error {
close(fnStarted)
<-runCtx.Done()
return runCtx.Err()
})
}()
<-fnStarted
cancel()
<-done
locked, _ := cache.IsLocked(context.Background(), key)
if locked {
t.Error("lock leaked after ctx cancel (WithLock Unlock should use Background ctx)")
}
}
func TestWithLockPassesContextToFunction(t *testing.T) {
setupMiniRedis(t)
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
key := "m10:ctx-aware"
var seen context.Context
err := cache.WithLock(ctx, key, time.Second, func(runCtx context.Context) error {
seen = runCtx
cancel()
<-runCtx.Done()
return runCtx.Err()
})
if !errors.Is(err, context.Canceled) {
t.Fatalf("WithLock ctx-aware err = %v, want context.Canceled", err)
}
if seen != ctx {
t.Fatal("WithLock 应把调用方 ctx 传入业务函数")
}
}
func TestWithLockRejectsNilFunction(t *testing.T) {
setupMiniRedis(t)
ctx := context.Background()
if err := cache.WithLock(ctx, "m10:nil-fn", time.Second, nil); !errors.Is(err, cache.ErrLockFuncNil) {
t.Fatalf("WithLock nil fn err = %v, want ErrLockFuncNil", err)
}
if err := cache.WithLockAutoExtend(ctx, "m10:nil-fn-auto", time.Second, 100*time.Millisecond, nil); !errors.Is(err, cache.ErrLockFuncNil) {
t.Fatalf("WithLockAutoExtend nil fn err = %v, want ErrLockFuncNil", err)
}
}
// ===== C1b：类型断言不 panic =====
// 回归 C1b：NewLock/Unlock/ExtendLock 在正常路径返回正确结果（Lua 脚本返 int64）。
// 此用例锁定正常路径不被 toInt64 改坏；裸断言 panic 路径需构造非 int64 返回，
// miniredis Lua 恒返整数，故 panic 路径由 toInt64 的 comma-ok 防护（代码审查保证）。
func TestLockUnlockExtendCycle(t *testing.T) {
setupMiniRedis(t)
ctx := context.Background()
key := "c1b:cycle"
// 加锁
token, err := cache.NewLock(ctx, key, 5*time.Second)
if err != nil || token == nil {
t.Fatalf("NewLock: err=%v token=%v", err, token)
}
// 重复加锁应失败（返回 nil token）
t2, err := cache.NewLock(ctx, key, 5*time.Second)
if err != nil {
t.Fatalf("second NewLock err: %v", err)
}
if t2 != nil {
t.Error("second NewLock should return nil token (lock held)")
_ = cache.Unlock(ctx, t2)
}
// 续期
if err := cache.ExtendLock(ctx, token, 5*time.Second); err != nil {
t.Errorf("ExtendLock: %v", err)
}
// 用错误 token 解锁应失败
wrong := &cache.LockToken{Key: key, Token: "wrong-token"}
if err := cache.Unlock(ctx, wrong); !errors.Is(err, cache.ErrLockNotHeld) {
t.Errorf("Unlock wrong token err = %v, want ErrLockNotHeld", err)
}
// 正确解锁
if err := cache.Unlock(ctx, token); err != nil {
t.Errorf("Unlock: %v", err)
}
// 解锁后另一方可获取
t3, err := cache.NewLock(ctx, key, 5*time.Second)
if err != nil || t3 == nil {
t.Fatalf("NewLock after unlock: err=%v token=%v", err, t3)
}
_ = cache.Unlock(ctx, t3)
}
// ===== C1c：TryLock 响应 ctx 取消 =====
// 回归 C1c：TryLock 在 ctx 取消时立即返回，不阻塞 maxRetry*retryInterval。
// 旧实现 time.Sleep 不响应 ctx，取消后仍要等满所有重试。
func TestTryLockRespectsCtxCancel(t *testing.T) {
setupMiniRedis(t)
// 先占用锁，使 TryLock 必然重试。
holder, err := cache.NewLock(context.Background(), "c1c:try", 10*time.Second)
if err != nil || holder == nil {
t.Fatalf("setup holder: err=%v token=%v", err, holder)
}
defer cache.Unlock(context.Background(), holder)
ctx, cancel := context.WithCancel(context.Background())
// retryInterval=200ms，maxRetry=10 → 旧实现取消后最长阻塞 2s。
start := time.Now()
go func() {
time.Sleep(150 * time.Millisecond)
cancel()
}()
token, err := cache.TryLock(ctx, "c1c:try", 5*time.Second, 200*time.Millisecond, 10)
elapsed := time.Since(start)
if !errors.Is(err, context.Canceled) {
t.Errorf("TryLock err = %v, want context.Canceled", err)
}
if token != nil {
t.Error("TryLock should return nil token (held by other)")
_ = cache.Unlock(context.Background(), token)
}
// 取消应在 ~150ms 后返回，远小于 2s。
if elapsed > 1*time.Second {
t.Errorf("TryLock took %v, should return shortly after ctx cancel (C1c: time.Sleep ignored ctx)", elapsed)
}
}
func TestLockRejectsSubMillisecondTTL(t *testing.T) {
setupMiniRedis(t)
ctx := context.Background()
if token, err := cache.NewLock(ctx, "m10:ttl", time.Nanosecond); !errors.Is(err, cache.ErrInvalidLockTTL) || token != nil {
t.Fatalf("NewLock sub-ms ttl token=%v err=%v, want ErrInvalidLockTTL", token, err)
}
token, err := cache.NewLock(ctx, "m10:ttl-valid", time.Second)
if err != nil || token == nil {
t.Fatalf("NewLock valid setup token=%v err=%v", token, err)
}
defer cache.Unlock(ctx, token)
if err := cache.ExtendLock(ctx, token, 0); !errors.Is(err, cache.ErrInvalidLockTTL) {
t.Errorf("ExtendLock zero ttl err = %v, want ErrInvalidLockTTL", err)
}
}
func TestWithLockAutoExtendRejectsNonPositiveInterval(t *testing.T) {
setupMiniRedis(t)
called := false
err := cache.WithLockAutoExtend(context.Background(), "m10:interval", time.Second, 0, func(context.Context) error {
called = true
return nil
})
if !errors.Is(err, cache.ErrInvalidLockRetryInterval) {
t.Fatalf("WithLockAutoExtend zero interval err = %v, want ErrInvalidLockRetryInterval", err)
}
if called {
t.Fatal("WithLockAutoExtend should not run fn with invalid interval")
}
}
func TestWithLockHeldReturnsErrLockNotAcquired(t *testing.T) {
setupMiniRedis(t)
ctx := context.Background()
key := "m10:not-acquired"
holder, err := cache.NewLock(ctx, key, time.Second)
if err != nil || holder == nil {
t.Fatalf("setup holder token=%v err=%v", holder, err)
}
defer cache.Unlock(ctx, holder)
called := false
err = cache.WithLock(ctx, key, time.Second, func(context.Context) error {
called = true
return nil
})
if !errors.Is(err, cache.ErrLockNotAcquired) {
t.Fatalf("WithLock held err = %v, want ErrLockNotAcquired", err)
}
if called {
t.Fatal("WithLock should not run fn when lock is held")
}
}
func TestTryLockExhaustedReturnsErrLockNotAcquired(t *testing.T) {
setupMiniRedis(t)
ctx := context.Background()
key := "m10:try-exhausted"
holder, err := cache.NewLock(ctx, key, time.Second)
if err != nil || holder == nil {
t.Fatalf("setup holder token=%v err=%v", holder, err)
}
defer cache.Unlock(ctx, holder)
token, err := cache.TryLock(ctx, key, time.Second, time.Millisecond, 2)
if !errors.Is(err, cache.ErrLockNotAcquired) {
t.Fatalf("TryLock exhausted err = %v, want ErrLockNotAcquired", err)
}
if token != nil {
t.Fatalf("TryLock exhausted token = %v, want nil", token)
}
}
cache/lock_test.go
Vendored
+151
View File
@@ -0,0 +1,151 @@
package cache_test
import (
"context"
"errors"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/cache"
)
func TestLockToken(t *testing.T) {
token := &cache.LockToken{
Key: "test_lock",
Token: "abc123",
}
if token.Key != "test_lock" {
t.Error("LockToken Key failed")
}
if token.Token != "abc123" {
t.Error("LockToken Token failed")
}
}
func TestLockErrors(t *testing.T) {
ctx := context.Background()
// Test ErrLockNotHeld - 当 Redis 未初始化时，先检查 nil token
err := cache.Unlock(ctx, nil)
// 当 Redis 未初始化时，会返回 ErrRedisNotReady
if err != cache.ErrLockNotHeld && err != cache.ErrRedisNotReady {
t.Errorf("Unlock with nil token should return ErrLockNotHeld or ErrRedisNotReady, got %v", err)
}
// Test IsLocked without Redis — M-E：应返回 (false, ErrRedisNotReady)，
// 让调用方可区分"Redis 不可用"与"锁未占用"（原 (false,nil) 与"未占用"不可区分）。
locked, err := cache.IsLocked(ctx, "test_key")
if !errors.Is(err, cache.ErrRedisNotReady) {
t.Errorf("IsLocked without Redis should return ErrRedisNotReady, got %v", err)
}
if locked {
t.Error("IsLocked should return false without Redis")
}
// Test GetLockTTL without Redis — M-E：应返回 (0, ErrRedisNotReady)。
ttl, err := cache.GetLockTTL(ctx, "test_key")
if !errors.Is(err, cache.ErrRedisNotReady) {
t.Errorf("GetLockTTL without Redis should return ErrRedisNotReady, got %v", err)
}
if ttl != 0 {
t.Error("GetLockTTL should return 0 without Redis")
}
if err := cache.UnlockByKey(ctx, "test_key"); !errors.Is(err, cache.ErrRedisNotReady) {
t.Errorf("UnlockByKey without Redis should return ErrRedisNotReady, got %v", err)
}
}
func TestIncrDecr(t *testing.T) {
ctx := context.Background()
// Redis 未初始化时应显式返回 ErrRedisNotReady，避免调用方误判为计数器值为 0。
n, err := cache.Incr(ctx, "counter")
if !errors.Is(err, cache.ErrRedisNotReady) {
t.Errorf("Incr without Redis should return ErrRedisNotReady, got %v", err)
}
if n != 0 {
t.Error("Incr should return 0 without Redis")
}
n, err = cache.IncrBy(ctx, "counter", 10)
if !errors.Is(err, cache.ErrRedisNotReady) {
t.Errorf("IncrBy without Redis should return ErrRedisNotReady, got %v", err)
}
if n != 0 {
t.Error("IncrBy should return 0 without Redis")
}
n, err = cache.Decr(ctx, "counter")
if !errors.Is(err, cache.ErrRedisNotReady) {
t.Errorf("Decr without Redis should return ErrRedisNotReady, got %v", err)
}
if n != 0 {
t.Error("Decr should return 0 without Redis")
}
}
func TestSetExpire(t *testing.T) {
ctx := context.Background()
ok, err := cache.SetExpire(ctx, "test_key", time.Minute)
if !errors.Is(err, cache.ErrRedisNotReady) {
t.Errorf("SetExpire without Redis should return ErrRedisNotReady, got %v", err)
}
if ok {
t.Error("SetExpire should return false without Redis")
}
}
func TestGetRawSetRaw(t *testing.T) {
ctx := context.Background()
// Test SetRaw
err := cache.SetRaw(ctx, "test_key", "test_value", time.Minute)
if !errors.Is(err, cache.ErrRedisNotReady) {
t.Errorf("SetRaw without Redis should return ErrRedisNotReady, got %v", err)
}
// Test GetRaw
val, err := cache.GetRaw(ctx, "test_key")
if !errors.Is(err, cache.ErrRedisNotReady) {
t.Errorf("GetRaw without Redis should return ErrRedisNotReady, got %v", err)
}
if val != "" {
t.Error("GetRaw should return empty string without Redis")
}
}
func TestKFunctions(t *testing.T) {
// Test various K functions
key := cache.K("user:1")
if key == "" {
t.Error("K should not return empty string")
}
tempKey := cache.KTemp("token")
if tempKey == "" {
t.Error("KTemp should not return empty string")
}
permKey := cache.KPerm("config")
if permKey == "" {
t.Error("KPerm should not return empty string")
}
lockKey := cache.KLock("order:123")
if lockKey == "" {
t.Error("KLock should not return empty string")
}
counterKey := cache.KCounter("visit")
if counterKey == "" {
t.Error("KCounter should not return empty string")
}
sessionKey := cache.KSession("sid")
if sessionKey == "" {
t.Error("KSession should not return empty string")
}
}
cmd/xlgo/commands.go
+336
View File
@@ -0,0 +1,336 @@
package main
import (
"fmt"
"os"
"strings"
"text/template"
"time"
"golang.org/x/text/cases"
"golang.org/x/text/language"
xlgo "github.com/EthanCodeCraft/xlgo-core"
)
func createProject(name string) error {
// P1 #21：校验项目名，拒绝路径穿越与非法 Go 包名。
if err := validateProjectName(name); err != nil {
return err
}
// #nosec G703 -- name was validated by validateProjectName: no path separators, no "..", no leading dot, Go identifier only.
if _, err := os.Stat(name); !os.IsNotExist(err) {
return fmt.Errorf("目录 %s 已存在", name)
}
// 解析 --template 与 --module 参数（默认 template=api）
tmplName := "api"
module := name
args := os.Args[3:]
for i := 0; i < len(args); i++ {
switch args[i] {
case "--template", "-t":
if i+1 >= len(args) {
return fmt.Errorf("%s 缺少参数值", args[i])
}
tmplName = args[i+1]
i++
case "--module", "-m":
if i+1 >= len(args) {
return fmt.Errorf("%s 缺少参数值", args[i])
}
module = args[i+1]
i++
default:
// P1 #21：未知参数显式报错，不再静默忽略。
return fmt.Errorf("未知参数: %s", args[i])
}
}
// P1 #21：校验 module 路径，避免模板元字符 {{ }} 经 Sprintf 进 go.mod 后触发 Parse 报错。
if err := validateModulePath(module); err != nil {
return err
}
// 校验模板名
switch tmplName {
case "minimal", "api", "fullstack":
// ok
default:
return fmt.Errorf("未知模板: %s（可选: minimal / api / fullstack）", tmplName)
}
// minimal 模板目录结构最小化；api/fullstack 含完整分层目录
var dirs []string
dirs = append(dirs, name, name+"/public", name+"/logs")
if tmplName != "minimal" {
dirs = append(dirs,
name+"/config",
name+"/handler",
name+"/model",
name+"/repository",
name+"/service",
name+"/middleware",
)
}
for _, dir := range dirs {
// #nosec G301,G703 -- dir is built from validated project name plus fixed scaffold subdirectories; 0755 is intentional for generated project dirs.
if err := os.MkdirAll(dir, 0755); err != nil {
// #nosec G703 -- name was validated by validateProjectName and is the scaffold root being rolled back.
_ = os.RemoveAll(name) // P1 #21：清理半成品
return fmt.Errorf("创建目录失败: %w", err)
}
}
caser := cases.Title(language.English)
data := TemplateData{
Package: caser.String(name),
Name: caser.String(name),
NameLower: strings.ToLower(name),
Module: module,
Year: time.Now().Year(),
}
// 按模板选择 main.go 与 config.yaml
var mainTmpl, configTmpl string
switch tmplName {
case "minimal":
mainTmpl, configTmpl = templates.MainMinimal, templates.ConfigMinimal
case "fullstack":
mainTmpl, configTmpl = templates.MainFull, templates.ConfigFull
default: // api
mainTmpl, configTmpl = templates.Main, templates.Config
}
// 创建文件
files := map[string]string{
name + "/main.go": mainTmpl,
name + "/config.yaml": configTmpl,
name + "/go.mod": fmt.Sprintf(templates.GoMod, module, xlgo.Version),
name + "/Makefile": templates.Makefile,
name + "/.gitignore": templates.Gitignore,
}
// api/fullstack 模板带示例 handler
if tmplName != "minimal" {
files[name+"/handler/home.go"] = templates.Handler
}
for path, content := range files {
if err := renderTemplateFile(path, content, data); err != nil {
// #nosec G703 -- name was validated by validateProjectName and is the scaffold root being rolled back.
_ = os.RemoveAll(name) // P1 #21：部分失败回滚，避免留下半成品项目
return err
}
}
fmt.Printf("✓ 项目 %s 创建成功（模板: %s）\n", name, tmplName)
fmt.Println("\n下一步:")
fmt.Printf(" cd %s\n", name)
fmt.Println(" go mod tidy")
fmt.Println(" go run main.go")
return nil
}
// renderTemplateFile 解析并渲染单个模板文件，每次调用显式关闭句柄
// （P1 #21：不在循环内 defer 累积句柄，且 Close 错误纳入返回）。
func renderTemplateFile(path, content string, data TemplateData) (retErr error) {
tmpl, err := template.New(path).Parse(content)
if err != nil {
return fmt.Errorf("解析模板 %s 失败: %w", path, err)
}
// #nosec G304 -- path is from createProject's files map built from validated project name plus fixed filenames.
file, err := os.Create(path)
if err != nil {
return fmt.Errorf("创建文件 %s 失败: %w", path, err)
}
defer func() {
if cerr := file.Close(); cerr != nil && retErr == nil {
retErr = fmt.Errorf("关闭文件 %s 失败: %w", path, cerr)
}
}()
if err := tmpl.Execute(file, data); err != nil {
return fmt.Errorf("写入文件 %s 失败: %w", path, err)
}
return nil
}
// validateProjectName 校验项目名（P1 #21）：非空、无路径分隔符/.. /前导点，
// 且可派生为合法 Go 包名（须以字母开头，仅含字母/数字/下划线）。
func validateProjectName(name string) error {
if name == "" {
return fmt.Errorf("项目名不能为空")
}
if strings.ContainsAny(name, `/\`) || strings.Contains(name, "..") {
return fmt.Errorf("项目名不能包含路径分隔符或 ..（防止在预期目录外创建文件）: %q", name)
}
if strings.HasPrefix(name, ".") {
return fmt.Errorf("项目名不能以 . 开头: %q", name)
}
if !isValidGoIdentifier(name) {
return fmt.Errorf("项目名 %q 无法生成合法 Go 包名：须以字母开头，仅含字母、数字、下划线", name)
}
return nil
}
// isValidGoIdentifier 判断 s 是否为脚手架接受的 ASCII 标识符：字母开头，后续允许字母、数字、下划线。
func isValidGoIdentifier(s string) bool {
if s == "" {
return false
}
for i, r := range s {
isLetter := (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z')
isNum := r >= '0' && r <= '9'
if i == 0 {
if !isLetter {
return false
}
} else if !isLetter && !isNum && r != '_' {
return false
}
}
return true
}
// validateModulePath 校验 --module（P1 #21）：非空、不含模板元字符与空白。
func validateModulePath(module string) error {
if module == "" {
return fmt.Errorf("模块路径不能为空")
}
if strings.Contains(module, "{{") || strings.Contains(module, "}}") {
return fmt.Errorf("模块路径不能包含模板元字符 {{ }}: %q", module)
}
if strings.ContainsAny(module, " \t\r\n") {
return fmt.Errorf("模块路径不能包含空白字符: %q", module)
}
return nil
}
func makeFile(fileType, name string) error {
if err := validateMakeName(name); err != nil {
return err
}
name = strings.ToLower(name)
nameTitle := makeNameTitle(name)
switch fileType {
case "handler":
return createHandler(name, nameTitle)
case "repository":
return createRepository(name, nameTitle)
case "model":
return createModel(name, nameTitle)
case "service":
return createService(name, nameTitle)
default:
return fmt.Errorf("未知类型: %s（可用类型: handler, repository, model, service）", fileType)
}
}
// validateMakeName 校验 xlgo make 的资源名，避免路径穿越或生成不可编译的 Go 代码。
func validateMakeName(name string) error {
if name == "" {
return fmt.Errorf("名称不能为空")
}
if strings.ContainsAny(name, `/\`) || strings.Contains(name, "..") {
return fmt.Errorf("名称不能包含路径分隔符或 ..: %q", name)
}
if strings.HasPrefix(name, ".") {
return fmt.Errorf("名称不能以 . 开头: %q", name)
}
if !isValidGoIdentifier(name) {
return fmt.Errorf("名称 %q 必须是合法标识符：须以字母开头，仅含字母、数字、下划线", name)
}
return nil
}
// makeNameTitle 把 snake_case 名称转为导出的 CamelCase 类型名。
func makeNameTitle(name string) string {
caser := cases.Title(language.English)
nameTitle := caser.String(strings.ReplaceAll(name, "_", " "))
return strings.ReplaceAll(nameTitle, " ", "")
}
func createHandler(name, nameTitle string) error {
path := fmt.Sprintf("handler/%s.go", name)
if fileExists(path) {
return fmt.Errorf("文件 %s 已存在", path)
}
content := fmt.Sprintf(templates.HandlerMake,
nameTitle, name, nameTitle,
nameTitle, name, nameTitle, nameTitle, nameTitle,
name, nameTitle, name, nameTitle,
nameTitle, name, name, nameTitle,
nameTitle, name, name, nameTitle,
nameTitle, name, name, nameTitle,
nameTitle, name, name, nameTitle,
)
content = replaceModuleImports(content)
if err := writeFile(path, content); err != nil {
return err
}
fmt.Printf("✓ 创建处理器: %s\n", path)
return nil
}
func createRepository(name, nameTitle string) error {
path := fmt.Sprintf("repository/%s_repository.go", name)
if fileExists(path) {
return fmt.Errorf("文件 %s 已存在", path)
}
content := fmt.Sprintf(templates.RepositoryMake,
nameTitle, name, nameTitle, nameTitle,
nameTitle, name, nameTitle, nameTitle, nameTitle, nameTitle,
nameTitle, nameTitle,
)
content = replaceModuleImports(content)
if err := writeFile(path, content); err != nil {
return err
}
fmt.Printf("✓ 创建仓库: %s\n", path)
return nil
}
func createModel(name, nameTitle string) error {
path := fmt.Sprintf("model/%s.go", name)
if fileExists(path) {
return fmt.Errorf("文件 %s 已存在", path)
}
content := fmt.Sprintf(templates.ModelMake,
nameTitle, name, nameTitle, nameTitle, name,
)
if err := writeFile(path, content); err != nil {
return err
}
fmt.Printf("✓ 创建模型: %s\n", path)
return nil
}
func createService(name, nameTitle string) error {
path := fmt.Sprintf("service/%s_service.go", name)
if fileExists(path) {
return fmt.Errorf("文件 %s 已存在", path)
}
content := fmt.Sprintf(templates.ServiceMake,
nameTitle, name, nameTitle, nameTitle,
nameTitle, name, nameTitle, nameTitle, nameTitle, nameTitle, nameTitle,
nameTitle, nameTitle,
nameTitle, nameTitle,
nameTitle, nameTitle,
nameTitle, nameTitle,
)
content = replaceModuleImports(content)
if err := writeFile(path, content); err != nil {
return err
}
fmt.Printf("✓ 创建服务: %s\n", path)
return nil
}
cmd/xlgo/commands_test.go
+56
View File
@@ -0,0 +1,56 @@
package main
import (
"os"
"path/filepath"
"strings"
"testing"
)
func TestValidateMakeNameRejectsUnsafeOrInvalidNames(t *testing.T) {
tests := []string{
"",
"../user",
`..\user`,
".user",
"my-thing",
"123user",
}
for _, tt := range tests {
t.Run(tt, func(t *testing.T) {
if err := validateMakeName(tt); err == nil {
t.Fatalf("名称 %q 应返回错误", tt)
}
})
}
}
func TestMakeFileAcceptsSnakeCaseIdentifier(t *testing.T) {
oldWd, err := os.Getwd()
if err != nil {
t.Fatalf("获取当前目录失败: %v", err)
}
tmp := t.TempDir()
if err := os.Chdir(tmp); err != nil {
t.Fatalf("切换测试目录失败: %v", err)
}
t.Cleanup(func() {
if err := os.Chdir(oldWd); err != nil {
t.Fatalf("恢复测试目录失败: %v", err)
}
})
if err := makeFile("model", "user_profile"); err != nil {
t.Fatalf("生成模型失败: %v", err)
}
path := filepath.Join(tmp, "model", "user_profile.go")
content, err := os.ReadFile(path)
if err != nil {
t.Fatalf("读取生成文件失败: %v", err)
}
if !strings.Contains(string(content), "type UserProfile struct") {
t.Fatalf("生成类型名不符合预期:\n%s", content)
}
}
cmd/xlgo/main.go
+71
View File
@@ -0,0 +1,71 @@
package main
import (
"fmt"
"os"
xlgo "github.com/EthanCodeCraft/xlgo-core"
)
func printUsage() {
fmt.Println(`xlgo - Go Web 框架脚手架工具
用法:
xlgo new <项目名> [--template <模板>] [--module <模块路径>] 创建新项目
xlgo make handler <名称> 创建处理器
xlgo make repository <名称> 创建仓库
xlgo make model <名称> 创建模型
xlgo make service <名称> 创建服务
xlgo version 显示版本号
模板 (xlgo new --template <名称>):
minimal 轻量 HTTP 服务，不依赖 MySQL/Redis（默认入门）
api 标准业务 API，含 MySQL/Redis/JWT 与 handler/model/repository/service 分层（默认）
fullstack 全组件，一键启用 MySQL/Redis/Storage/Swagger/AutoMigrate
示例:
xlgo new myapp
xlgo new myapp --template minimal
xlgo new myapp --template fullstack --module github.com/me/myapp
xlgo make handler user
xlgo make repository user`)
}
func main() {
if len(os.Args) < 2 {
printUsage()
return
}
command := os.Args[1]
// P1 #21：命令执行失败时以非零码退出，便于 `xlgo new x && cd x` 等脚本/CI 正确中断。
switch command {
case "new":
if len(os.Args) < 3 {
fmt.Fprintln(os.Stderr, "用法: xlgo new <项目名>")
os.Exit(2)
}
if err := createProject(os.Args[2]); err != nil {
fmt.Fprintf(os.Stderr, "错误: %s\n", err)
os.Exit(1)
}
case "make":
if len(os.Args) < 4 {
fmt.Fprintln(os.Stderr, "用法: xlgo make <类型> <名称>")
fmt.Fprintln(os.Stderr, "类型: handler, repository, model, service")
os.Exit(2)
}
if err := makeFile(os.Args[2], os.Args[3]); err != nil {
fmt.Fprintf(os.Stderr, "错误: %s\n", err)
os.Exit(1)
}
case "version":
fmt.Printf("xlgo v%s\n", xlgo.Version)
default:
printUsage()
}
}
cmd/xlgo/templates.go
+571
View File
@@ -0,0 +1,571 @@
package main
// Templates 存放所有代码生成模板
var templates = struct {
Main string // api 模板：标准业务 API（mysql+redis+jwt+分层）
MainMinimal string // minimal 模板：轻量 HTTP，无外部依赖
MainFull string // fullstack 模板：全组件
Config string // api 模板配置
ConfigMinimal string
ConfigFull string
GoMod string
Makefile string
Gitignore string
Handler string
HandlerMake string
RepositoryMake string
ModelMake string
ServiceMake string
}{
// Main 新项目主文件模板
Main: `package main
import (
"flag"
"fmt"
"os"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/middleware"
"github.com/EthanCodeCraft/xlgo-core/response"
"github.com/EthanCodeCraft/xlgo-core/router"
"github.com/gin-gonic/gin"
)
var configPath string
func init() {
flag.StringVar(&configPath, "config", "./config.yaml", "配置文件路径")
}
func main() {
flag.Parse()
app := xlgo.New(
xlgo.WithConfigPath(configPath),
xlgo.WithLogger(),
xlgo.WithHealthRoutes(),
// 如需 Swagger 文档：xlgo.WithSwaggerRoutes() 或 xlgo.WithDefaultRoutes()
// 如需 MySQL/Redis/Storage：xlgo.WithMySQL() / xlgo.WithRedis() / xlgo.WithStorage()
// 一键启用全部默认组件：使用 xlgo.NewFullStack(...) 替代 xlgo.New(...)
xlgo.WithMiddlewares(middleware.Logger(), middleware.CORS()),
xlgo.WithModules(router.ModuleFunc(registerRoutes)),
)
if err := app.Run(); err != nil {
fmt.Printf("启动失败: %v\n", err)
os.Exit(1)
}
}
func registerRoutes(r *gin.RouterGroup) {
api := r.Group("/api/v1")
api.GET("/", func(c *gin.Context) {
response.Success(c, gin.H{"message": "Welcome to {{.Name}}!"})
})
}
`,
// Config 配置文件模板
Config: `app:
name: "{{.Name}}"
site_name: "{{.NameLower}}" # 站点别名，用于缓存键前缀、日志标识、多站点区分
version: "1.0.0"
env: "dev" # dev/test/prod
debug: true
base_url: "http://localhost:8080"
server:
host: "" # 绑定地址，空=监听所有接口；127.0.0.1=仅本机；内网IP=绑定指定网卡
port: 8080
mode: development # development 或 production
read_timeout: 15s # 读超时
write_timeout: 30s # 写超时
idle_timeout: 60s # 空闲超时
shutdown_timeout: 30s # 优雅关闭超时
response_mode: business # business(默认,全200+业务码) 或 rest(按错误码映射HTTP status)
database:
driver: mysql # mysql（默认）或 postgres
host: localhost
port: 3306
user: root
password: your_password
name: {{.NameLower}}
max_idle_conns: 10
max_open_conns: 100
# dsn: "自定义连接字符串，设置后优先于上面的字段"
redis:
host: localhost
port: 6379
password: ""
db: 0
jwt:
secret: your_jwt_secret_key_change_me_to_32_bytes_at_least
expire: "24h" # time.Duration，支持 "24h"/"30m" 等
refresh_expire: "168h" # 刷新 token 过期时间
issuer: xlgo
algorithm: HS256 # HS256(默认)/HS384/HS512
storage:
driver: local
local:
path: ./public
base_url: http://localhost:8080/public
log:
dir: ./logs
max_size: 100
max_backups: 30
max_age: 30
compress: true
`,
// MainMinimal minimal 模板：轻量 HTTP 服务，不依赖 MySQL/Redis/Storage
MainMinimal: `package main
import (
"flag"
"fmt"
"os"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/middleware"
"github.com/EthanCodeCraft/xlgo-core/response"
"github.com/EthanCodeCraft/xlgo-core/router"
"github.com/gin-gonic/gin"
)
var configPath string
func init() {
flag.StringVar(&configPath, "config", "./config.yaml", "配置文件路径")
}
func main() {
flag.Parse()
app := xlgo.New(
xlgo.WithConfigPath(configPath),
xlgo.WithLogger(),
xlgo.WithHealthRoutes(),
xlgo.WithMiddlewares(middleware.Logger(), middleware.CORS()),
xlgo.WithModules(router.ModuleFunc(registerRoutes)),
)
if err := app.Run(); err != nil {
fmt.Printf("启动失败: %v\n", err)
os.Exit(1)
}
}
func registerRoutes(r *gin.RouterGroup) {
api := r.Group("/api/v1")
api.GET("/", func(c *gin.Context) {
response.Success(c, gin.H{"message": "Hello {{.Name}}!"})
})
}
`,
// ConfigMinimal minimal 模板配置：仅 app + server + log，无数据库/Redis
ConfigMinimal: `app:
name: "{{.Name}}"
site_name: "{{.NameLower}}"
version: "1.0.0"
env: "dev"
debug: true
base_url: "http://localhost:8080"
server:
port: 8080
mode: development
log:
dir: ./logs
max_size: 100
max_backups: 30
max_age: 30
compress: true
`,
// MainFull fullstack 模板：全组件（FullStack），含 Swagger + Storage
MainFull: `package main
import (
"flag"
"fmt"
"os"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/middleware"
"github.com/EthanCodeCraft/xlgo-core/response"
"github.com/EthanCodeCraft/xlgo-core/router"
"github.com/gin-gonic/gin"
)
var configPath string
func init() {
flag.StringVar(&configPath, "config", "./config.yaml", "配置文件路径")
}
func main() {
flag.Parse()
// NewFullStack 一键启用全部组件：Logger/MySQL/Redis/Storage/Wire/Health/Swagger/AutoMigrate
// 如需排除个别组件，追加对应 Without* Option，例如 xlgo.WithoutSwaggerRoutes()
app := xlgo.NewFullStack(
xlgo.WithConfigPath(configPath),
xlgo.WithMiddlewares(middleware.Logger(), middleware.CORS()),
xlgo.WithModules(router.ModuleFunc(registerRoutes)),
// xlgo.WithModels(&User{}, &Order{}), // 注册模型以启用自动迁移
)
if err := app.Run(); err != nil {
fmt.Printf("启动失败: %v\n", err)
os.Exit(1)
}
}
func registerRoutes(r *gin.RouterGroup) {
api := r.Group("/api/v1")
api.GET("/", func(c *gin.Context) {
response.Success(c, gin.H{"message": "Welcome to {{.Name}} (fullstack)!"})
})
}
`,
// ConfigFull fullstack 模板配置：全组件配置
ConfigFull: `app:
name: "{{.Name}}"
site_name: "{{.NameLower}}"
version: "1.0.0"
env: "dev"
debug: true
base_url: "http://localhost:8080"
server:
host: "" # 绑定地址，空=监听所有接口；127.0.0.1=仅本机
port: 8080
mode: development
read_timeout: 15s
write_timeout: 30s
idle_timeout: 60s
shutdown_timeout: 30s
response_mode: business
database:
driver: mysql # mysql（默认）或 postgres
host: localhost
port: 3306
user: root
password: your_password
name: {{.NameLower}}
max_idle_conns: 10
max_open_conns: 100
redis:
host: localhost
port: 6379
password: ""
db: 0
jwt:
secret: your_jwt_secret_key_change_me_to_32_bytes_at_least
expire: "24h" # time.Duration，支持 "24h"/"30m" 等
refresh_expire: "168h" # 刷新 token 过期时间
issuer: xlgo
algorithm: HS256 # HS256(默认)/HS384/HS512
storage:
driver: local
local:
path: ./public
base_url: http://localhost:8080/public
log:
dir: ./logs
max_size: 100
max_backups: 30
max_age: 30
compress: true
`,
// GoMod go.mod 文件模板
// %s: module 名称；%s: xlgo 框架版本（来自 xlgo.Version，避免字面量散落）
GoMod: `module %s
go 1.25
require (
github.com/EthanCodeCraft/xlgo-core v%s
github.com/gin-gonic/gin v1.9.1
)
`,
// Makefile 模板
Makefile: `.PHONY: build run test clean tidy swagger
build:
go build -o bin/server .
run:
go run main.go
test:
go test ./...
clean:
rm -rf bin/
rm -rf logs/
tidy:
go mod tidy
swagger:
swag init -g main.go -o ./swagger
`,
// Gitignore 模板
Gitignore: `# Binaries
bin/
*.exe
*.exe~
*.dll
*.so
*.dylib
# Test files
*.test
*.out
coverage.txt
# Go workspace file
go.work
# IDE
.idea/
.vscode/
*.swp
*.swo
# Environment
.env
.env.local
# Logs
logs/
*.log
# Config (keep example)
config.local.yaml
`,
// Handler 新项目默认处理器模板
Handler: `package handler
import (
"github.com/EthanCodeCraft/xlgo-core/response"
"github.com/gin-gonic/gin"
)
// HealthCheck 健康检查
func HealthCheck(c *gin.Context) {
response.Success(c, gin.H{
"status": "ok",
})
}
// Home 首页
func Home(c *gin.Context) {
response.Success(c, gin.H{
"message": "Welcome to {{.Name}}!",
})
}
`,
// HandlerMake make handler 命令模板
HandlerMake: `package handler
import (
"github.com/EthanCodeCraft/xlgo-core/response"
"github.com/gin-gonic/gin"
)
// %sHandler %s 处理器
type %sHandler struct {
// 可以注入 service
}
// New%sHandler 创建 %s 处理器
func New%sHandler() *%sHandler {
return &%sHandler{}
}
// List 获取列表
// @Summary 获取%s列表
// @Tags %s
// @Accept json
// @Produce json
// @Success 200 {object} response.Response
// @Router /api/v1/%ss [get]
func (h *%sHandler) List(c *gin.Context) {
response.Success(c, gin.H{
"Items": []string{},
})
}
// Get 获取详情
// @Summary 获取%s详情
// @Tags %s
// @Accept json
// @Produce json
// @Param id path int true "ID"
// @Success 200 {object} response.Response
// @Router /api/v1/%ss/{id} [get]
func (h *%sHandler) Get(c *gin.Context) {
response.Success(c, gin.H{
"id": c.Param("id"),
})
}
// Create 创建
// @Summary 创建%s
// @Tags %s
// @Accept json
// @Produce json
// @Success 200 {object} response.Response
// @Router /api/v1/%ss [post]
func (h *%sHandler) Create(c *gin.Context) {
response.Success(c, nil)
}
// Update 更新
// @Summary 更新%s
// @Tags %s
// @Accept json
// @Produce json
// @Param id path int true "ID"
// @Success 200 {object} response.Response
// @Router /api/v1/%ss/{id} [put]
func (h *%sHandler) Update(c *gin.Context) {
response.Success(c, nil)
}
// Delete 删除
// @Summary 删除%s
// @Tags %s
// @Accept json
// @Produce json
// @Param id path int true "ID"
// @Success 200 {object} response.Response
// @Router /api/v1/%ss/{id} [delete]
func (h *%sHandler) Delete(c *gin.Context) {
response.Success(c, nil)
}
`,
// RepositoryMake make repository 命令模板
RepositoryMake: `package repository
import (
"context"
"github.com/EthanCodeCraft/xlgo-core/database"
xlrepo "github.com/EthanCodeCraft/xlgo-core/repository"
"xlgo/model"
)
// %sRepository %s 仓库
type %sRepository struct {
*xlrepo.BaseRepo[model.%s]
}
// New%sRepository 创建 %s 仓库
func New%sRepository() *%sRepository {
return &%sRepository{
BaseRepo: xlrepo.NewBaseRepo[model.%s](database.GetDB()),
}
}
// FindByName 根据名称查询。
//
// 走 BaseRepo.FindOne → readConn 读连接：默认路由到从库（读写分离，H6c），
// 需读主库用 database.UseMaster(ctx)，事务内自动 join 外层事务。
// 不要用 r.GetDB() 自行查询——它返回注入的主库且不参与路由（M-35 footgun）。
func (r *%sRepository) FindByName(ctx context.Context, name string) (*model.%s, error) {
return r.FindOne(ctx, "name = ?", name)
}
`,
// ModelMake make model 命令模板
ModelMake: `package model
import xlmodel "github.com/EthanCodeCraft/xlgo-core/model"
// %s %s 模型
type %s struct {
xlmodel.BaseModel
Name string ` + "`" + `gorm:"size:100;not null" json:"name"` + "`" + `
Description string ` + "`" + `gorm:"size:500" json:"description"` + "`" + `
Status int ` + "`" + `gorm:"default:1" json:"status"` + "`" + ` // 1: 启用, 0: 禁用
}
// TableName 表名
func (%s) TableName() string {
return "%ss"
}
`,
// ServiceMake make service 命令模板
ServiceMake: `package service
import (
"context"
"xlgo/model"
"xlgo/repository"
)
// %sService %s 服务
type %sService struct {
repo *repository.%sRepository
}
// New%sService 创建 %s 服务
func New%sService() *%sService {
return &%sService{
repo: repository.New%sRepository(),
}
}
// List 获取列表
func (s *%sService) List(ctx context.Context, page, pageSize int) ([]model.%s, int64, error) {
// TODO: 实现列表查询
return nil, 0, nil
}
// GetByID 根据 ID 获取
func (s *%sService) GetByID(ctx context.Context, id uint) (*model.%s, error) {
return s.repo.FindByID(ctx, id)
}
// Create 创建
func (s *%sService) Create(ctx context.Context, m *model.%s) error {
return s.repo.Create(ctx, m)
}
// Update 更新
func (s *%sService) Update(ctx context.Context, m *model.%s) error {
return s.repo.Update(ctx, m)
}
// Delete 删除
func (s *%sService) Delete(ctx context.Context, id uint) error {
return s.repo.Delete(ctx, id)
}
`,
}
cmd/xlgo/types.go
+10
View File
@@ -0,0 +1,10 @@
package main
// TemplateData 模板数据
type TemplateData struct {
Package string
Name string
NameLower string
Module string
Year int
}
cmd/xlgo/utils.go
+57
View File
@@ -0,0 +1,57 @@
package main
import (
"fmt"
"os"
"path/filepath"
"strings"
)
func writeFile(path, content string) error {
dir := filepath.Dir(path)
// #nosec G301,G703 -- path is built by makeFile from fixed scaffold directories and a name that rejects separators/".."; 0755 is intentional for generated dirs.
if err := os.MkdirAll(dir, 0755); err != nil {
return fmt.Errorf("创建目录失败: %w", err)
}
// #nosec G306,G703 -- path is built by makeFile from fixed scaffold directories and a validated name; 0644 is intentional for generated source files.
if err := os.WriteFile(path, []byte(content), 0644); err != nil {
return fmt.Errorf("写入文件失败: %w", err)
}
return nil
}
func fileExists(path string) bool {
// #nosec G703 -- path is built by makeFile from fixed scaffold directories and a name that rejects separators/"..".
_, err := os.Stat(path)
if err == nil {
return true
}
// 仅当"不存在"才返回 false；权限错误等其它错误视为"可能存在/不可覆写"，
// 避免把无权限访问的路径误判为可创建（M20：原 !os.IsNotExist 把权限错误当存在，
// 反而安全；但语义模糊，显式区分更清晰）。
return !os.IsNotExist(err)
}
func currentModule() string {
data, err := os.ReadFile("go.mod")
if err != nil {
return "xlgo"
}
for _, line := range strings.Split(string(data), "\n") {
line = strings.TrimSpace(line)
if strings.HasPrefix(line, "module ") {
return strings.TrimSpace(strings.TrimPrefix(line, "module "))
}
}
return "xlgo"
}
func replaceModuleImports(content string) string {
module := currentModule()
content = strings.ReplaceAll(content, "\"xlgo/model\"", fmt.Sprintf("\"%s/model\"", module))
content = strings.ReplaceAll(content, "\"xlgo/repository\"", fmt.Sprintf("\"%s/repository\"", module))
content = strings.ReplaceAll(content, "\"xlgo/database\"", fmt.Sprintf("\"%s/database\"", module))
content = strings.ReplaceAll(content, "\"xlgo/response\"", "\"github.com/EthanCodeCraft/xlgo-core/response\"")
return content
}
compress/compress.go
+403
View File
@@ -0,0 +1,403 @@
package compress
import (
"archive/zip"
"bytes"
"compress/gzip"
"errors"
"fmt"
"io"
"io/fs"
"os"
"path/filepath"
"strings"
)
// 解压安全相关错误。
var (
// ErrPathTraversal zip 条目名逃逸目标目录（C5a Zip-Slip）。
ErrPathTraversal = errors.New("zip entry escapes destination directory")
// ErrSymlinkEntry zip 条目为符号链接，已拒绝（防经软链二次穿越）。
ErrSymlinkEntry = errors.New("zip entry is a symlink, rejected")
// ErrDecompressLimit 解压大小超过上限（C5b 解压炸弹）。
ErrDecompressLimit = errors.New("decompress size limit exceeded")
)
const (
// defaultDecompressLimit 单流/单条目默认解压上限（100MB），防 OOM / 磁盘耗尽（C5b）。
defaultDecompressLimit int64 = 100 * 1024 * 1024
// defaultDecompressTotalLimit Unzip 默认累计解压上限（1GB）。
defaultDecompressTotalLimit int64 = 1 * 1024 * 1024 * 1024
)
// DecompressOptions 解压安全选项。Zip-Slip 防护（前缀锚定 + 拒绝符号链接）始终启用，无需配置；
// 本选项仅控制解压大小上限以防解压炸弹（C5b）。
type DecompressOptions struct {
// MaxBytes 单流 / 单条目解压大小上限（字节）。0 = 默认 100MB，-1 = 不限制。
MaxBytes int64
// MaxTotalBytes Unzip 累计解压大小上限（字节）。0 = 默认 1GB，-1 = 不限制。
// 仅 Unzip 生效。
MaxTotalBytes int64
}
// resolveLimit 解析大小上限：n<0 不限，n==0 用 def，n>0 用 n。
func resolveLimit(n, def int64) int64 {
if n < 0 {
return -1
}
if n == 0 {
return def
}
return n
}
// minLimit 返回两个上限中较小者；-1 视为无限。
func minLimit(a, b int64) int64 {
if a < 0 {
return b
}
if b < 0 {
return a
}
if a < b {
return a
}
return b
}
// GzipCompress 压缩数据
func GzipCompress(data []byte) ([]byte, error) {
var buf bytes.Buffer
gz := gzip.NewWriter(&buf)
if _, err := gz.Write(data); err != nil {
_ = gz.Close()
return nil, err
}
if err := gz.Close(); err != nil {
return nil, err
}
return buf.Bytes(), nil
}
// GzipDecompress 解压缩数据。默认上限 100MB 防解压炸弹 OOM（C5b）；
// 需解压更大文件请用 GzipDecompressWithOptions。
func GzipDecompress(data []byte) ([]byte, error) {
return GzipDecompressWithOptions(data, DecompressOptions{})
}
// GzipDecompressWithOptions 解压缩数据，可配置大小上限（C5b）。
func GzipDecompressWithOptions(data []byte, opts DecompressOptions) ([]byte, error) {
buf := bytes.NewReader(data)
gz, err := gzip.NewReader(buf)
if err != nil {
return nil, err
}
defer gz.Close()
limit := resolveLimit(opts.MaxBytes, defaultDecompressLimit)
var reader io.Reader = gz
if limit > 0 {
// 多读 1 字节用于判断是否超限。
reader = io.LimitReader(gz, limit+1)
}
out, err := io.ReadAll(reader)
if err != nil {
return nil, err
}
if limit > 0 && int64(len(out)) > limit {
return nil, fmt.Errorf("解压后大小超过上限 %d 字节: %w", limit, ErrDecompressLimit)
}
return out, nil
}
// GzipCompressFile 压缩文件
func GzipCompressFile(src, dst string) error {
// #nosec G304 -- src/dst 为调用方提供的本地文件路径，压缩 API 固有语义，非不可信输入
srcFile, err := os.Open(src)
if err != nil {
return err
}
defer srcFile.Close()
// #nosec G304 -- 同上，dst 为调用方指定输出路径
dstFile, err := os.Create(dst)
if err != nil {
return err
}
gz := gzip.NewWriter(dstFile)
// 保留原文件名和时间戳
if info, err := srcFile.Stat(); err == nil {
gz.Name = info.Name()
gz.ModTime = info.ModTime()
}
_, copyErr := io.Copy(gz, srcFile)
// gz.Close 刷出 gzip 尾部（含 CRC/大小校验），失败说明归档损坏，必须向上传播（M16/B18）。
closeErr := gz.Close()
// dstFile.Close 失败（如延迟写盘）同样意味着归档可能不完整。
dstErr := dstFile.Close()
if copyErr != nil {
return copyErr
}
if closeErr != nil {
return closeErr
}
return dstErr
}
// GzipDecompressFile 解压文件。默认上限 100MB 防磁盘耗尽（C5b）；
// 需解压更大文件请用 GzipDecompressFileWithOptions。
func GzipDecompressFile(src, dst string) error {
return GzipDecompressFileWithOptions(src, dst, DecompressOptions{})
}
// GzipDecompressFileWithOptions 解压文件，可配置大小上限（C5b）。
func GzipDecompressFileWithOptions(src, dst string, opts DecompressOptions) (err error) {
// #nosec G304 -- src 为调用方提供的本地文件路径，解压 API 固有语义，非不可信输入
srcFile, err := os.Open(src)
if err != nil {
return err
}
defer srcFile.Close()
gz, err := gzip.NewReader(srcFile)
if err != nil {
return err
}
defer gz.Close()
// #nosec G304 -- dst 为调用方指定输出路径，解压 API 固有语义
dstFile, err := os.Create(dst)
if err != nil {
return err
}
// L-A 修复：失败时（超限/拷贝错误）清理部分落盘的 dst，避免被拒炸弹遗留残片；
// 成功时仅关闭。os.Remove 在 Close 之后，兼容 Windows（删除打开中的文件会失败）。
defer func() {
if cerr := dstFile.Close(); cerr != nil {
err = errors.Join(err, cerr)
}
if err != nil {
_ = os.Remove(dst)
}
}()
limit := resolveLimit(opts.MaxBytes, defaultDecompressLimit)
var written int64
if limit > 0 {
// CopyN 最多读 limit+1 字节，超限即判定为炸弹。
written, err = io.CopyN(dstFile, gz, limit+1)
} else {
// #nosec G110 -- 仅当调用方显式 MaxBytes=-1 不限时走此分支，有限分支已用 CopyN 封顶防炸弹
written, err = io.Copy(dstFile, gz)
}
if err != nil && err != io.EOF {
return err
}
if limit > 0 && written > limit {
return fmt.Errorf("解压后大小超过上限 %d 字节: %w", limit, ErrDecompressLimit)
}
return nil
}
// Zip 压缩文件或目录
// 参数: zipPath 目标zip文件路径，paths 要压缩的文件或目录列表
func Zip(zipPath string, paths []string) error {
// 创建目标目录
if err := os.MkdirAll(filepath.Dir(zipPath), 0750); err != nil {
return err
}
// 创建 zip 文件
// #nosec G304 -- zipPath 为调用方指定输出路径，压缩 API 固有语义
archive, err := os.Create(zipPath)
if err != nil {
return err
}
zipWriter := zip.NewWriter(archive)
walkErr := func() error {
for _, srcPath := range paths {
srcPath = strings.TrimSuffix(srcPath, string(os.PathSeparator))
// #nosec G122 -- 压缩调用方提供的源路径，非解压不可信输入；symlink 跟随是压缩场景的可接受行为
err := filepath.Walk(srcPath, func(path string, info fs.FileInfo, err error) error {
if err != nil {
return err
}
// 创建文件头
header, err := zip.FileInfoHeader(info)
if err != nil {
return err
}
header.Method = zip.Deflate
// 设置相对路径
header.Name, err = filepath.Rel(filepath.Dir(srcPath), path)
if err != nil {
return err
}
if info.IsDir() {
header.Name += string(os.PathSeparator)
}
writer, err := zipWriter.CreateHeader(header)
if err != nil {
return err
}
if info.IsDir() {
return nil
}
// #nosec G304,G122 -- path 为 Walk 遍历调用方源路径产生，非不可信输入；压缩场景接受 symlink 跟随语义。
file, err := os.Open(path)
if err != nil {
return err
}
defer file.Close()
_, err = io.Copy(writer, file)
return err
})
if err != nil {
return err
}
}
return nil
}()
// zipWriter.Close 刷出中央目录记录，失败说明归档损坏，必须向上传播（M16/B18）。
zipCloseErr := zipWriter.Close()
archiveCloseErr := archive.Close()
if walkErr != nil {
return walkErr
}
if zipCloseErr != nil {
return zipCloseErr
}
return archiveCloseErr
}
// Unzip 解压 zip 文件。默认启用 Zip-Slip 防护（前缀锚定 + 拒绝符号链接），
// 单条目上限 100MB、累计上限 1GB 防解压炸弹（C5b）；需自定义上限请用 UnzipWithOptions。
func Unzip(zipPath, dstDir string) error {
return UnzipWithOptions(zipPath, dstDir, DecompressOptions{})
}
// UnzipWithOptions 解压 zip 文件，可配置大小上限（C5b）。Zip-Slip 防护始终启用。
func UnzipWithOptions(zipPath, dstDir string, opts DecompressOptions) error {
reader, err := zip.OpenReader(zipPath)
if err != nil {
return err
}
defer reader.Close()
// 用绝对路径作目标锚定根，避免相对路径 + `..` 组合绕过前缀校验（C5a）。
absDst, err := filepath.Abs(dstDir)
if err != nil {
return fmt.Errorf("resolve unzip destination failed: %w", err)
}
absDst = filepath.Clean(absDst)
entryLimit := resolveLimit(opts.MaxBytes, defaultDecompressLimit)
totalLimit := resolveLimit(opts.MaxTotalBytes, defaultDecompressTotalLimit)
var total int64
for _, file := range reader.File {
written, err := unzipFile(file, absDst, entryLimit, totalLimit, total)
if err != nil {
return err
}
total += written
}
return nil
}
// unzipFile 解压单个 zip 条目到 absDst 下。
// entryLimit: 单条目上限（-1 不限）；totalLimit: 累计上限（-1 不限）；accrued: 已解压累计字节。
// 返回本条目写入字节数。
func unzipFile(file *zip.File, absDst string, entryLimit, totalLimit, accrued int64) (written int64, err error) {
// 拒绝符号链接条目，防经软链二次穿越（C5a）。
if file.Mode()&os.ModeSymlink != 0 {
return 0, fmt.Errorf("条目 %s 为符号链接: %w", file.Name, ErrSymlinkEntry)
}
// zip 条目名规范用正斜杠；转成当前平台分隔符后再 Join，并以前缀锚定拒绝 `..` 逃逸（C5a）。
name := filepath.FromSlash(file.Name)
// 拒绝绝对路径与以分隔符开头的条目（非标准、可疑，避免平台语义差异）。
// filepath.IsAbs 在 Windows 不认 "/x"（无盘符）为绝对路径，故补充分隔符前缀检查。
if filepath.IsAbs(name) || strings.HasPrefix(name, string(os.PathSeparator)) || strings.HasPrefix(file.Name, "/") {
return 0, fmt.Errorf("条目 %s 为绝对路径: %w", file.Name, ErrPathTraversal)
}
target := filepath.Join(absDst, name)
if target == absDst || !strings.HasPrefix(target, absDst+string(os.PathSeparator)) {
return 0, fmt.Errorf("条目 %s 逃逸目标目录: %w", file.Name, ErrPathTraversal)
}
if file.FileInfo().IsDir() {
if err := os.MkdirAll(target, 0750); err != nil {
return 0, err
}
return 0, nil
}
// 创建父目录
if err := os.MkdirAll(filepath.Dir(target), 0750); err != nil {
return 0, err
}
// 打开 zip 中的文件
rc, err := file.Open()
if err != nil {
return 0, err
}
defer rc.Close()
// 创建目标文件
// #nosec G304 -- target 经前缀锚定校验（absDst+sep），已防 Zip-Slip 逃逸
dstFile, err := os.Create(target)
if err != nil {
return 0, err
}
// L-A 修复：失败时（超限/拷贝错误）清理部分落盘的 target，避免被拒炸弹遗留残片；
// 成功时仅关闭。os.Remove 在 Close 之后，兼容 Windows（删除打开中的文件会失败）。
defer func() {
if cerr := dstFile.Close(); cerr != nil {
err = errors.Join(err, cerr)
}
if err != nil {
_ = os.Remove(target)
}
}()
// 计算本次拷贝上限：单条目上限与累计剩余上限中较小者（-1 视为无限）。
// remaining: 累计剩余（-1 表示累计不限）；totalLimit>0 时若已无剩余，直接判超限。
remaining := int64(-1)
if totalLimit > 0 {
remaining = totalLimit - accrued
if remaining <= 0 {
return 0, fmt.Errorf("累计解压超过上限 %d 字节: %w", totalLimit, ErrDecompressLimit)
}
}
cap := minLimit(entryLimit, remaining)
// cap 为 -1（两者皆不限）或 >0（有限上限，剩余已保证 >0），不会是 0。
if cap > 0 {
written, err = io.CopyN(dstFile, rc, cap+1)
} else {
// #nosec G110 -- 仅当调用方显式 MaxBytes=-1 不限时走此分支，有限分支已用 CopyN 封顶防炸弹
written, err = io.Copy(dstFile, rc)
}
if err != nil && err != io.EOF {
return written, err
}
if cap > 0 && written > cap {
return written, fmt.Errorf("条目 %s 超过解压上限 %d 字节: %w", file.Name, cap, ErrDecompressLimit)
}
return written, nil
}
compress/compress_security_test.go
+347
View File
@@ -0,0 +1,347 @@
package compress_test
import (
"archive/zip"
"bytes"
"compress/gzip"
"errors"
"os"
"path/filepath"
"strings"
"testing"
"github.com/EthanCodeCraft/xlgo-core/compress"
)
// makeZipAt 构造一个 zip 文件，entries 为 name -> content；dir 条目用空 content 且 IsDir=true。
func makeZipAt(t *testing.T, zipPath string, entries []struct {
name string
content string
isDir bool
}) {
t.Helper()
if err := os.MkdirAll(filepath.Dir(zipPath), 0750); err != nil {
t.Fatalf("mkdir: %v", err)
}
f, err := os.Create(zipPath)
if err != nil {
t.Fatalf("create zip: %v", err)
}
defer f.Close()
zw := zip.NewWriter(f)
for _, e := range entries {
hdr := &zip.FileHeader{Name: e.name, Method: zip.Deflate}
if e.isDir {
hdr.SetMode(os.ModeDir | 0750)
}
w, err := zw.CreateHeader(hdr)
if err != nil {
t.Fatalf("CreateHeader %s: %v", e.name, err)
}
if !e.isDir {
if _, err := w.Write([]byte(e.content)); err != nil {
t.Fatalf("write %s: %v", e.name, err)
}
}
}
if err := zw.Close(); err != nil {
t.Fatalf("close zip writer: %v", err)
}
}
// ===== C5a：Zip-Slip =====
// 回归 C5a：zip 条目名含 `..` 逃逸目标目录必须被拒绝，且不在 dst 外创建/覆盖文件。
func TestUnzipZipSlipRejected(t *testing.T) {
dir := t.TempDir()
zipPath := filepath.Join(dir, "evil.zip")
// 在 dst 的父目录放一个蜜罐文件，确保穿越不会覆盖它。
canary := filepath.Join(dir, "canary.txt")
if err := os.WriteFile(canary, []byte("original"), 0644); err != nil {
t.Fatalf("write canary: %v", err)
}
dst := filepath.Join(dir, "out")
makeZipAt(t, zipPath, []struct {
name string
content string
isDir bool
}{
{name: "../canary.txt", content: "pwned"},
})
err := compress.Unzip(zipPath, dst)
if !errors.Is(err, compress.ErrPathTraversal) {
t.Errorf("Unzip with ../ entry err = %v, want ErrPathTraversal", err)
}
// 蜜罐文件必须未被覆盖。
data, err := os.ReadFile(canary)
if err != nil {
t.Fatalf("read canary: %v", err)
}
if string(data) != "original" {
t.Errorf("canary overwritten by Zip-Slip: got %q", string(data))
}
}
// 回归 C5a：绝对路径条目必须被拒绝。
func TestUnzipAbsolutePathRejected(t *testing.T) {
dir := t.TempDir()
zipPath := filepath.Join(dir, "abs.zip")
dst := filepath.Join(dir, "out")
makeZipAt(t, zipPath, []struct {
name string
content string
isDir bool
}{
{name: "/etc/evil.txt", content: "x"},
})
if err := compress.Unzip(zipPath, dst); !errors.Is(err, compress.ErrPathTraversal) {
t.Errorf("Unzip absolute path err = %v, want ErrPathTraversal", err)
}
}
// 回归 C5a：合法相对路径条目不误伤（含子目录）。
func TestUnzipNormalEntriesWork(t *testing.T) {
dir := t.TempDir()
zipPath := filepath.Join(dir, "ok.zip")
dst := filepath.Join(dir, "out")
makeZipAt(t, zipPath, []struct {
name string
content string
isDir bool
}{
{name: "sub/", isDir: true},
{name: "sub/a.txt", content: "hello"},
{name: "top.txt", content: "world"},
})
if err := compress.Unzip(zipPath, dst); err != nil {
t.Fatalf("Unzip normal: %v", err)
}
if b, err := os.ReadFile(filepath.Join(dst, "sub", "a.txt")); err != nil || string(b) != "hello" {
t.Errorf("sub/a.txt = %q, err=%v, want 'hello'", string(b), err)
}
if b, err := os.ReadFile(filepath.Join(dst, "top.txt")); err != nil || string(b) != "world" {
t.Errorf("top.txt = %q, err=%v, want 'world'", string(b), err)
}
}
// 回归 C5a：符号链接条目必须被拒绝（防经软链二次穿越）。
func TestUnzipSymlinkRejected(t *testing.T) {
dir := t.TempDir()
zipPath := filepath.Join(dir, "symlink.zip")
dst := filepath.Join(dir, "out")
makeZipAt(t, zipPath, []struct {
name string
content string
isDir bool
}{
{name: "lnk", content: "/etc/passwd"}, // content 为链接目标，mode 设为 symlink
})
// 把条目 mode 改成符号链接：重建 zip 时设置 ModeSymlink。
// makeZipAt 不支持 symlink mode，这里直接用底层 API 重建。
zipPath2 := filepath.Join(dir, "symlink2.zip")
f, err := os.Create(zipPath2)
if err != nil {
t.Fatalf("create: %v", err)
}
defer f.Close()
zw := zip.NewWriter(f)
hdr := &zip.FileHeader{Name: "lnk", Method: zip.Deflate}
hdr.SetMode(os.ModeSymlink | 0777)
w, err := zw.CreateHeader(hdr)
if err != nil {
t.Fatalf("CreateHeader: %v", err)
}
if _, err := w.Write([]byte("/etc/passwd")); err != nil {
t.Fatalf("write: %v", err)
}
if err := zw.Close(); err != nil {
t.Fatalf("close: %v", err)
}
if err := compress.Unzip(zipPath2, dst); !errors.Is(err, compress.ErrSymlinkEntry) {
t.Errorf("Unzip symlink err = %v, want ErrSymlinkEntry", err)
}
}
// ===== C5b：解压炸弹 =====
// 回归 C5b：GzipDecompress 超限返回错误而非 OOM。
// 用显式小上限验证限流代码路径（与默认 100MB 走同一 io.LimitReader + 超限判定逻辑）。
func TestGzipDecompressBombLimit(t *testing.T) {
// 2MB 解压后数据。
big := bytes.Repeat([]byte("A"), 2*1024*1024)
var buf bytes.Buffer
gz := gzip.NewWriter(&buf)
if _, err := gz.Write(big); err != nil {
t.Fatalf("gzip write: %v", err)
}
if err := gz.Close(); err != nil {
t.Fatalf("gzip close: %v", err)
}
compressed := buf.Bytes()
// 显式上限 1MB → 必须拒绝（2MB 超限）。
if _, err := compress.GzipDecompressWithOptions(compressed, compress.DecompressOptions{MaxBytes: 1 * 1024 * 1024}); !errors.Is(err, compress.ErrDecompressLimit) {
t.Errorf("GzipDecompress over-limit err = %v, want ErrDecompressLimit", err)
}
// 显式 -1 不限 → 成功解压完整 2MB。
out, err := compress.GzipDecompressWithOptions(compressed, compress.DecompressOptions{MaxBytes: -1})
if err != nil {
t.Errorf("GzipDecompress unlimited err = %v", err)
}
if len(out) != len(big) {
t.Errorf("unlimited decompressed len = %d, want %d", len(out), len(big))
}
// 默认上限（100MB）放行 2MB 正常数据。
if _, err := compress.GzipDecompress(compressed); err != nil {
t.Errorf("GzipDecompress default err = %v (2MB should pass default 100MB limit)", err)
}
}
// 回归 C5b：Unzip 单条目上限——超大条目被拒。
func TestUnzipEntryBombLimit(t *testing.T) {
dir := t.TempDir()
zipPath := filepath.Join(dir, "bomb.zip")
dst := filepath.Join(dir, "out")
// 构造一个含 2MB（解压后）条目的 zip。
f, err := os.Create(zipPath)
if err != nil {
t.Fatalf("create: %v", err)
}
defer f.Close()
zw := zip.NewWriter(f)
w, err := zw.Create("big.txt")
if err != nil {
t.Fatalf("Create: %v", err)
}
if _, err := w.Write(bytes.Repeat([]byte("A"), 2 * 1024 * 1024)); err != nil {
t.Fatalf("write: %v", err)
}
if err := zw.Close(); err != nil {
t.Fatalf("close: %v", err)
}
// 显式单条目上限 1MB → 必须拒绝。
opts := compress.DecompressOptions{MaxBytes: 1 * 1024 * 1024}
if err := compress.UnzipWithOptions(zipPath, dst, opts); !errors.Is(err, compress.ErrDecompressLimit) {
t.Errorf("Unzip entry bomb err = %v, want ErrDecompressLimit", err)
}
}
// 回归 C5b：Unzip 累计上限——多个条目累计超限被拒。
func TestUnzipTotalBombLimit(t *testing.T) {
dir := t.TempDir()
zipPath := filepath.Join(dir, "many.zip")
dst := filepath.Join(dir, "out")
// 5 个 1MB 条目 = 累计 5MB；单条目上限 2MB（不超），累计上限 3MB → 第 4 个累计 4MB 超限。
f, err := os.Create(zipPath)
if err != nil {
t.Fatalf("create: %v", err)
}
defer f.Close()
zw := zip.NewWriter(f)
chunk := bytes.Repeat([]byte("B"), 1*1024*1024)
for i := 0; i < 5; i++ {
w, err := zw.Create("file" + string(rune('0'+i)) + ".dat")
if err != nil {
t.Fatalf("Create: %v", err)
}
if _, err := w.Write(chunk); err != nil {
t.Fatalf("write: %v", err)
}
}
if err := zw.Close(); err != nil {
t.Fatalf("close: %v", err)
}
opts := compress.DecompressOptions{MaxBytes: 2 * 1024 * 1024, MaxTotalBytes: 3 * 1024 * 1024}
if err := compress.UnzipWithOptions(zipPath, dst, opts); !errors.Is(err, compress.ErrDecompressLimit) {
t.Errorf("Unzip total bomb err = %v, want ErrDecompressLimit", err)
}
}
// 回归 C5b：GzipDecompressFile 单流封顶——超限返回错误而非磁盘耗尽。
func TestGzipDecompressFileBombLimit(t *testing.T) {
dir := t.TempDir()
// 2MB 解压后数据写入 gzip 文件。
big := bytes.Repeat([]byte("A"), 2*1024*1024)
srcGz := filepath.Join(dir, "src.gz")
{
f, err := os.Create(srcGz)
if err != nil {
t.Fatalf("create: %v", err)
}
gz := gzip.NewWriter(f)
if _, err := gz.Write(big); err != nil {
t.Fatalf("write: %v", err)
}
if err := gz.Close(); err != nil {
t.Fatalf("close gz: %v", err)
}
f.Close()
}
// 显式上限 1MB → 必须拒绝（2MB 超限）。
dst1 := filepath.Join(dir, "out1.txt")
if err := compress.GzipDecompressFileWithOptions(srcGz, dst1, compress.DecompressOptions{MaxBytes: 1 * 1024 * 1024}); !errors.Is(err, compress.ErrDecompressLimit) {
t.Errorf("GzipDecompressFile over-limit err = %v, want ErrDecompressLimit", err)
}
// 显式 -1 不限 → 成功解压完整 2MB。
dst2 := filepath.Join(dir, "out2.txt")
if err := compress.GzipDecompressFileWithOptions(srcGz, dst2, compress.DecompressOptions{MaxBytes: -1}); err != nil {
t.Errorf("GzipDecompressFile unlimited err = %v", err)
}
b, err := os.ReadFile(dst2)
if err != nil {
t.Fatalf("read out: %v", err)
}
if len(b) != len(big) {
t.Errorf("unlimited out len = %d, want %d", len(b), len(big))
}
// 默认上限（100MB）放行 2MB。
dst3 := filepath.Join(dir, "out3.txt")
if err := compress.GzipDecompressFile(srcGz, dst3); err != nil {
t.Errorf("GzipDecompressFile default err = %v (2MB should pass default 100MB limit)", err)
}
}
// 兼容性回归：原有 Zip/Unzip 闭环（合法归档）在默认防护下仍正常。
func TestZipUnzipRoundTripStillWorks(t *testing.T) {
dir := t.TempDir()
src := filepath.Join(dir, "src.txt")
content := "round trip content"
if err := os.WriteFile(src, []byte(content), 0644); err != nil {
t.Fatalf("write: %v", err)
}
zipPath := filepath.Join(dir, "rt.zip")
if err := compress.Zip(zipPath, []string{src}); err != nil {
t.Fatalf("Zip: %v", err)
}
dst := filepath.Join(dir, "out")
if err := compress.Unzip(zipPath, dst); err != nil {
t.Fatalf("Unzip: %v", err)
}
// Zip 用 filepath.Rel(src 的父目录, src) = "src.txt"。
b, err := os.ReadFile(filepath.Join(dst, "src.txt"))
if err != nil {
// 目录结构可能因平台分隔符略有差异，尝试找 src.txt。
_ = filepath.Walk(dst, func(p string, _ os.FileInfo, _ error) error {
if strings.HasSuffix(p, "src.txt") {
b, err = os.ReadFile(p)
return filepath.SkipDir
}
return nil
})
}
if string(b) != content {
t.Errorf("round trip = %q, want %q", string(b), content)
}
}
compress/compress_test.go
+244
View File
@@ -0,0 +1,244 @@
package compress_test
import (
"os"
"path/filepath"
"testing"
"github.com/EthanCodeCraft/xlgo-core/compress"
"github.com/EthanCodeCraft/xlgo-core/utils"
)
func fileExists(path string) bool {
return utils.FileExists(path)
}
func getTempDir() string {
return filepath.Join(os.TempDir(), "xlgo_compress_test")
}
func setupTestFiles(t *testing.T) (string, string, string) {
dir := getTempDir()
os.MkdirAll(dir, 0755)
// 创建测试文件
srcFile := filepath.Join(dir, "test.txt")
content := "Hello, this is a test file for compression!"
os.WriteFile(srcFile, []byte(content), 0644)
// 创建子目录和文件
subDir := filepath.Join(dir, "subdir")
os.MkdirAll(subDir, 0755)
subFile := filepath.Join(subDir, "sub.txt")
os.WriteFile(subFile, []byte("Subdir content"), 0644)
return dir, srcFile, content
}
func cleanupTestDir(t *testing.T) {
os.RemoveAll(getTempDir())
}
func TestGzipCompress(t *testing.T) {
defer cleanupTestDir(t)
data := []byte("Hello World, this is test data for gzip compression!")
compressed, err := compress.GzipCompress(data)
if err != nil {
t.Fatalf("GzipCompress error: %v", err)
}
if len(compressed) == 0 {
t.Error("Compressed data is empty")
}
// 压缩后的数据应该比原数据小（对于重复数据）
// 但对于很短的数据可能更大，所以不做严格长度比较
// 解压缩验证
decompressed, err := compress.GzipDecompress(compressed)
if err != nil {
t.Fatalf("GzipDecompress error: %v", err)
}
if string(decompressed) != string(data) {
t.Errorf("Decompressed data mismatch: got %s, want %s", decompressed, data)
}
}
func TestGzipDecompressInvalid(t *testing.T) {
// 测试无效数据解压
_, err := compress.GzipDecompress([]byte("invalid gzip data"))
if err == nil {
t.Error("GzipDecompress should fail with invalid data")
}
}
func TestGzipCompressEmpty(t *testing.T) {
data := []byte("")
compressed, err := compress.GzipCompress(data)
if err != nil {
t.Fatalf("GzipCompress empty error: %v", err)
}
decompressed, err := compress.GzipDecompress(compressed)
if err != nil {
t.Fatalf("GzipDecompress empty error: %v", err)
}
if len(decompressed) != 0 {
t.Error("Decompressed empty data should be empty")
}
}
func TestGzipCompressFile(t *testing.T) {
defer cleanupTestDir(t)
dir, srcFile, content := setupTestFiles(t)
dstFile := filepath.Join(dir, "test.txt.gz")
// 压缩文件
err := compress.GzipCompressFile(srcFile, dstFile)
if err != nil {
t.Fatalf("GzipCompressFile error: %v", err)
}
// 验证压缩文件存在
if !fileExists(dstFile) {
t.Error("Compressed file not created")
}
// 解压文件
outFile := filepath.Join(dir, "test_out.txt")
err = compress.GzipDecompressFile(dstFile, outFile)
if err != nil {
t.Fatalf("GzipDecompressFile error: %v", err)
}
// 验证解压内容
outContent, err := os.ReadFile(outFile)
if err != nil {
t.Fatalf("ReadFile error: %v", err)
}
if string(outContent) != content {
t.Errorf("Decompressed content mismatch: got %s, want %s", outContent, content)
}
}
func TestGzipCompressFileNonexistent(t *testing.T) {
err := compress.GzipCompressFile("/nonexistent/file.txt", "/tmp/out.gz")
if err == nil {
t.Error("GzipCompressFile should fail with nonexistent source")
}
}
func TestZip(t *testing.T) {
defer cleanupTestDir(t)
dir, srcFile, _ := setupTestFiles(t)
zipPath := filepath.Join(dir, "test.zip")
paths := []string{srcFile, filepath.Join(dir, "subdir")}
// 创建 zip
err := compress.Zip(zipPath, paths)
if err != nil {
t.Fatalf("Zip error: %v", err)
}
// 验证 zip 文件存在
if !fileExists(zipPath) {
t.Error("Zip file not created")
}
// 解压 zip
dstDir := filepath.Join(dir, "unzipped")
err = compress.Unzip(zipPath, dstDir)
if err != nil {
t.Fatalf("Unzip error: %v", err)
}
// 验证解压后的文件
outFile := filepath.Join(dstDir, "test.txt")
if !fileExists(outFile) {
t.Error("Unzipped file not found")
}
}
func TestZipSingleFile(t *testing.T) {
defer cleanupTestDir(t)
dir, srcFile, content := setupTestFiles(t)
zipPath := filepath.Join(dir, "single.zip")
err := compress.Zip(zipPath, []string{srcFile})
if err != nil {
t.Fatalf("Zip single file error: %v", err)
}
dstDir := filepath.Join(dir, "single_unzipped")
err = compress.Unzip(zipPath, dstDir)
if err != nil {
t.Fatalf("Unzip error: %v", err)
}
// 验证内容
outContent, err := os.ReadFile(filepath.Join(dstDir, "test.txt"))
if err != nil {
t.Fatalf("ReadFile error: %v", err)
}
if string(outContent) != content {
t.Error("Unzipped content mismatch")
}
}
func TestUnzipInvalid(t *testing.T) {
defer cleanupTestDir(t)
dir := getTempDir()
os.MkdirAll(dir, 0755)
// 无效 zip 文件
invalidZip := filepath.Join(dir, "invalid.zip")
os.WriteFile(invalidZip, []byte("not a zip file"), 0644)
dstDir := filepath.Join(dir, "out")
err := compress.Unzip(invalidZip, dstDir)
if err == nil {
t.Error("Unzip should fail with invalid zip file")
}
}
func TestUnzipNonexistent(t *testing.T) {
err := compress.Unzip("/nonexistent/file.zip", "/tmp/out")
if err == nil {
t.Error("Unzip should fail with nonexistent file")
}
}
// ===== Benchmarks =====
func BenchmarkGzipCompress(b *testing.B) {
data := make([]byte, 1024)
for i := range data {
data[i] = byte(i % 256)
}
b.ResetTimer()
for i := 0; i < b.N; i++ {
compress.GzipCompress(data)
}
}
func BenchmarkGzipDecompress(b *testing.B) {
data := make([]byte, 1024)
for i := range data {
data[i] = byte(i % 256)
}
compressed, _ := compress.GzipCompress(data)
b.ResetTimer()
for i := 0; i < b.N; i++ {
compress.GzipDecompress(compressed)
}
}
config/config.go
+1161
View File
File diff suppressed because it is too large Load Diff
config/config_c10_test.go
+499
View File
@@ -0,0 +1,499 @@
package config_test
import (
"os"
"path/filepath"
"runtime"
"strings"
"sync"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
)
// writeConfig 写入临时配置文件并返回路径。
func writeConfig(t *testing.T, name, content string) string {
t.Helper()
dir := filepath.Join(os.TempDir(), "xlgo_c10_test")
if err := os.MkdirAll(dir, 0755); err != nil {
t.Fatalf("MkdirAll: %v", err)
}
p := filepath.Join(dir, name)
if err := os.WriteFile(p, []byte(content), 0644); err != nil {
t.Fatalf("WriteFile: %v", err)
}
return p
}
func validConfigYAML(port int) string {
return "app:\n name: c10\n env: dev\nserver:\n port: " + itoa(port) + "\n"
}
func itoa(n int) string {
if n == 0 {
return "0"
}
neg := n < 0
if neg {
n = -n
}
var b [20]byte
i := len(b)
for n > 0 {
i--
b[i] = byte('0' + n%10)
n /= 10
}
if neg {
i--
b[i] = '-'
}
return string(b[i:])
}
// TestSetDefaultManagerConcurrent 并发置换默认 Manager 与并发读取，
// 必须经 -race 无竞争（C10a）。
func TestSetDefaultManagerConcurrent(t *testing.T) {
// 准备若干可加载的 Manager
paths := make([]string, 4)
for i := range paths {
paths[i] = writeConfig(t, "c10_concurrent_"+itoa(i)+".yaml", validConfigYAML(9000+i))
}
defer func() {
for _, p := range paths {
os.Remove(p)
}
}()
var wg sync.WaitGroup
stop := make(chan struct{})
// 写者：并发 SetDefaultManager
for i := 0; i < 4; i++ {
wg.Add(1)
go func(idx int) {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
m := config.NewManager(paths[idx])
_, _ = m.Load()
config.SetDefaultManager(m)
}
}(i)
}
// 读者：并发 Get / GetViper / GetString
for i := 0; i < 4; i++ {
wg.Add(1)
go func() {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
_ = config.Get()
_ = config.GetViper()
_ = config.GetString("server.port")
}
}()
}
// 跑足够长以让 -race 采到
time.Sleep(150 * time.Millisecond)
close(stop)
wg.Wait()
// 还原全局状态，避免污染其他测试
config.SetDefaultManager(nil)
}
// TestLoadReturnsDefensiveCopy Load 返回的配置与 Get() 内部指针独立，
// 修改返回值不污染全局（C10c）。
func TestLoadReturnsDefensiveCopy(t *testing.T) {
p := writeConfig(t, "c10_defensive.yaml", validConfigYAML(8081))
defer os.Remove(p)
config.Set(nil)
cfg, err := config.Load(p)
if err != nil {
t.Fatalf("Load: %v", err)
}
if cfg.Server.Port != 8081 {
t.Fatalf("port = %d, want 8081", cfg.Server.Port)
}
// 调用方修改返回值
cfg.Server.Port = 1
cfg.App.Name = "mutated"
// 全局读取不受影响
got := config.Get()
if got == nil {
t.Fatal("Get returned nil")
}
if got.Server.Port != 8081 {
t.Errorf("global port polluted = %d, want 8081 (C10c)", got.Server.Port)
}
if got.App.Name == "mutated" {
t.Errorf("global app name polluted (C10c)")
}
config.SetDefaultManager(nil)
}
// TestLoadDefensiveCopySliceContract 固化 M-G 的深拷贝语义契约：
// 标量字段与切片字段均独立（修改不污染全局）。M-G 修复后 Load() 返回 Clone() 深拷贝，
// 切片字段不再共享底层数组——调用方可安全修改切片元素。本测试锁定该行为，防止回退到浅拷贝。
func TestLoadDefensiveCopySliceContract(t *testing.T) {
content := "app:\n name: c10slice\nserver:\n port: 8090\ncors:\n allowed_origins:\n - https://a.example.com\n - https://b.example.com\n"
p := writeConfig(t, "c10_slice.yaml", content)
defer os.Remove(p)
config.Set(nil)
cfg, err := config.Load(p)
if err != nil {
t.Fatalf("Load: %v", err)
}
// 标量独立
cfg.Server.Port = 1
if got := config.Get().Server.Port; got != 8090 {
t.Errorf("scalar polluted = %d, want 8090", got)
}
// M-G：切片底层数组独立（深拷贝）——修改切片元素不污染全局。
cfg.CORS.AllowedOrigins[0] = "https://mutated.example.com"
if got := config.Get().CORS.AllowedOrigins[0]; got != "https://a.example.com" {
t.Errorf("slice should be deep-copied (independent), global polluted to %q, want %q", got, "https://a.example.com")
}
// append 也不应污染全局（深拷贝后调用方持独立切片）
cfg.CORS.AllowedOrigins = append(cfg.CORS.AllowedOrigins, "https://c.example.com")
if got := config.Get().CORS.AllowedOrigins; len(got) != 2 {
t.Errorf("global slice length should be unaffected by caller append, got %d, want 2", len(got))
}
config.SetDefaultManager(nil)
}
func TestReloadInvalidConfigKeepsOld(t *testing.T) {
p := writeConfig(t, "c10_reload_bad.yaml", validConfigYAML(8082))
defer os.Remove(p)
m := config.NewManager(p)
if _, err := m.Load(); err != nil {
t.Fatalf("Load: %v", err)
}
if got := m.Get().Server.Port; got != 8082 {
t.Fatalf("initial port = %d, want 8082", got)
}
// 覆盖为非法配置（端口越界）
if err := os.WriteFile(p, []byte("app:\n name: bad\nserver:\n port: 99999\n"), 0644); err != nil {
t.Fatalf("WriteFile: %v", err)
}
err := m.Reload()
if err == nil {
t.Fatal("Reload invalid config should return error (C10b)")
}
if !strings.Contains(err.Error(), "server.port") {
t.Errorf("error should mention server.port, got %v", err)
}
// 旧配置保留
if got := m.Get().Server.Port; got != 8082 {
t.Errorf("old config not preserved = %d, want 8082 (C10b)", got)
}
}
// TestHotReloadInvalidConfigKeepsOld 文件监听路径遇非法配置保留旧配置，
// 且不触发回调；监听仍存活，后续合法变更正常生效（C10b + C10d 监听健壮性）。
func TestHotReloadInvalidConfigKeepsOld(t *testing.T) {
p := writeConfig(t, "c10_watch_bad.yaml", validConfigYAML(8083))
defer os.Remove(p)
m := config.NewManager(p)
if _, err := m.Load(); err != nil {
t.Fatalf("Load: %v", err)
}
changes := make(chan int, 16)
m.RegisterCallback(func(c *config.Config) {
select {
case changes <- c.Server.Port:
default:
}
})
if err := m.StartWatcher(); err != nil {
t.Fatalf("StartWatcher: %v", err)
}
defer m.StopWatcher()
// 1) 写入非法配置：应保留旧配置、不触发回调
if err := os.WriteFile(p, []byte("app:\n name: bad\nserver:\n port: 99999\n"), 0644); err != nil {
t.Fatalf("WriteFile invalid: %v", err)
}
deadline := time.Now().Add(2 * time.Second)
for time.Now().Before(deadline) {
if got := m.Get().Server.Port; got != 8083 {
t.Errorf("invalid config leaked into global = %d, want 8083 (C10b)", got)
break
}
time.Sleep(20 * time.Millisecond)
}
select {
case port := <-changes:
t.Errorf("callback fired for invalid config with port %d (C10b)", port)
default:
}
// 2) 写入合法配置：监听仍存活，应触发回调且全局更新
if err := os.WriteFile(p, []byte(validConfigYAML(8084)), 0644); err != nil {
t.Fatalf("WriteFile valid: %v", err)
}
deadline = time.Now().Add(3 * time.Second)
for time.Now().Before(deadline) {
if got := m.Get().Server.Port; got == 8084 {
break
}
time.Sleep(20 * time.Millisecond)
}
if got := m.Get().Server.Port; got != 8084 {
t.Fatalf("watcher did not reload valid config = %d, want 8084", got)
}
}
// TestStopWatcherReleasesGoroutine StopWatcher 后监听 goroutine 退出，无泄漏（C10d）。
func TestStopWatcherReleasesGoroutine(t *testing.T) {
p := writeConfig(t, "c10_stop.yaml", validConfigYAML(8085))
defer os.Remove(p)
m := config.NewManager(p)
if _, err := m.Load(); err != nil {
t.Fatalf("Load: %v", err)
}
if err := m.StartWatcher(); err != nil {
t.Fatalf("StartWatcher: %v", err)
}
// 等待监听 goroutine 就绪
time.Sleep(100 * time.Millisecond)
before := runtime.NumGoroutine()
m.StopWatcher()
// 轮询确认 goroutine 退出
deadline := time.Now().Add(2 * time.Second)
for time.Now().Before(deadline) {
if runtime.NumGoroutine() < before {
break
}
time.Sleep(20 * time.Millisecond)
}
if after := runtime.NumGoroutine(); after >= before {
t.Errorf("watcher goroutine not released: before=%d after=%d (C10d)", before, after)
}
// 幂等：再次 Stop 不 panic
m.StopWatcher()
}
// TestStartWatcherIdempotent 重复 StartWatcher 不创建多个监听 goroutine（幂等）。
func TestStartWatcherIdempotent(t *testing.T) {
p := writeConfig(t, "c10_idem.yaml", validConfigYAML(8086))
defer os.Remove(p)
m := config.NewManager(p)
if _, err := m.Load(); err != nil {
t.Fatalf("Load: %v", err)
}
if err := m.StartWatcher(); err != nil {
t.Fatalf("StartWatcher 1: %v", err)
}
time.Sleep(80 * time.Millisecond)
once := runtime.NumGoroutine()
if err := m.StartWatcher(); err != nil {
t.Fatalf("StartWatcher 2: %v", err)
}
if err := m.StartWatcher(); err != nil {
t.Fatalf("StartWatcher 3: %v", err)
}
time.Sleep(80 * time.Millisecond)
twice := runtime.NumGoroutine()
if twice > once {
t.Errorf("idempotent StartWatcher leaked goroutine: once=%d twice=%d", once, twice)
}
m.StopWatcher()
}
func TestStopWatcherWaitsInFlightReload(t *testing.T) {
p := writeConfig(t, "c10_stop_wait.yaml", validConfigYAML(8091))
defer os.Remove(p)
m := config.NewManager(p)
if _, err := m.Load(); err != nil {
t.Fatalf("Load: %v", err)
}
entered := make(chan struct{})
release := make(chan struct{})
m.RegisterCallback(func(*config.Config) {
close(entered)
<-release
})
if err := m.StartWatcher(); err != nil {
t.Fatalf("StartWatcher: %v", err)
}
if err := os.WriteFile(p, []byte(validConfigYAML(8092)), 0644); err != nil {
t.Fatalf("WriteFile: %v", err)
}
select {
case <-entered:
case <-time.After(3 * time.Second):
t.Fatal("热更新回调未触发")
}
stopped := make(chan struct{})
go func() {
m.StopWatcher()
close(stopped)
}()
select {
case <-stopped:
t.Fatal("StopWatcher 不应在 reload 回调结束前返回")
case <-time.After(120 * time.Millisecond):
}
close(release)
select {
case <-stopped:
case <-time.After(2 * time.Second):
t.Fatal("StopWatcher 未等待到 reload 回调结束")
}
}
func TestLoadWithWatchFailureKeepsOldWatcher(t *testing.T) {
p := writeConfig(t, "c10_keep_old.yaml", validConfigYAML(8093))
defer os.Remove(p)
changes := make(chan int, 4)
if _, err := config.LoadWithWatch(p, func(c *config.Config) {
changes <- c.Server.Port
}); err != nil {
t.Fatalf("LoadWithWatch old: %v", err)
}
defer config.StopWatcher()
missing := filepath.Join(filepath.Dir(p), "missing.yaml")
if _, err := config.LoadWithWatch(missing, nil); err == nil {
t.Fatal("加载缺失配置应失败")
}
if err := os.WriteFile(p, []byte(validConfigYAML(8094)), 0644); err != nil {
t.Fatalf("WriteFile: %v", err)
}
select {
case port := <-changes:
if port != 8094 {
t.Fatalf("旧 watcher 回调端口错误: %d", port)
}
case <-time.After(3 * time.Second):
t.Fatal("加载失败后旧 watcher 不应被停止")
}
}
func TestSetDefaultManagerStopsOldWatcher(t *testing.T) {
oldPath := writeConfig(t, "c10_old_default.yaml", validConfigYAML(8095))
newPath := writeConfig(t, "c10_new_default.yaml", validConfigYAML(8096))
defer os.Remove(oldPath)
defer os.Remove(newPath)
oldManager := config.NewManager(oldPath)
if _, err := oldManager.Load(); err != nil {
t.Fatalf("old Load: %v", err)
}
changes := make(chan int, 4)
oldManager.RegisterCallback(func(c *config.Config) {
changes <- c.Server.Port
})
if err := oldManager.StartWatcher(); err != nil {
t.Fatalf("old StartWatcher: %v", err)
}
config.SetDefaultManager(oldManager)
newManager := config.NewManager(newPath)
if _, err := newManager.Load(); err != nil {
t.Fatalf("new Load: %v", err)
}
config.SetDefaultManager(newManager)
defer config.SetDefaultManager(nil)
if err := os.WriteFile(oldPath, []byte(validConfigYAML(8097)), 0644); err != nil {
t.Fatalf("WriteFile old: %v", err)
}
select {
case port := <-changes:
t.Fatalf("旧 watcher 已停止，不应收到端口 %d", port)
case <-time.After(500 * time.Millisecond):
}
}
func TestSetGetAndViperReturnCopies(t *testing.T) {
cfg := &config.Config{
App: config.AppConfig{Name: "copy", Env: "dev"},
CORS: config.CORSConfig{
AllowedOrigins: []string{"https://a.example.com"},
},
}
if err := config.Set(cfg); err != nil {
t.Fatalf("Set: %v", err)
}
defer config.SetDefaultManager(nil)
cfg.App.Name = "mutated-input"
cfg.CORS.AllowedOrigins[0] = "https://mutated-input.example.com"
got := config.Get()
if got.App.Name != "copy" {
t.Fatalf("Set 应保存副本，实际 App.Name=%q", got.App.Name)
}
if got.CORS.AllowedOrigins[0] != "https://a.example.com" {
t.Fatalf("Set 应深拷贝切片，实际 origin=%q", got.CORS.AllowedOrigins[0])
}
got.App.Name = "mutated-get"
got.CORS.AllowedOrigins[0] = "https://mutated-get.example.com"
gotAgain := config.Get()
if gotAgain.App.Name != "copy" || gotAgain.CORS.AllowedOrigins[0] != "https://a.example.com" {
t.Fatalf("Get 应返回副本，实际 %+v", gotAgain)
}
if err := config.Set(&config.Config{Server: config.ServerConfig{Port: 99999}}); err == nil {
t.Fatal("Set 非法配置应返回错误")
}
if got := config.Get().App.Name; got != "copy" {
t.Fatalf("Set 非法配置不应覆盖旧配置，实际 App.Name=%q", got)
}
}
func TestGetViperReturnsSnapshot(t *testing.T) {
p := writeConfig(t, "c10_viper_snapshot.yaml", validConfigYAML(8098))
defer os.Remove(p)
if _, err := config.Load(p); err != nil {
t.Fatalf("Load: %v", err)
}
defer config.SetDefaultManager(nil)
v := config.GetViper()
if v == nil {
t.Fatal("GetViper returned nil")
}
v.Set("app.name", "mutated")
if got := config.GetString("app.name"); got != "c10" {
t.Fatalf("GetViper 应返回快照，不应污染内部 viper，实际 app.name=%q", got)
}
}
config/config_fix_test.go
+329
View File
@@ -0,0 +1,329 @@
package config_test
import (
"os"
"reflect"
"strings"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
)
// TestSetKeepsViperInSync_Hconfig1 固化 H-config-1：Set(cfg) 后 Get() 与
// GetString/GetInt/GetBool/GetViper 必须读到同一配置世界，消除原"Set 只更新类型化视图、
// viper 视图停留旧值"的静默分裂（违反 C1 单一配置源）。
func TestSetKeepsViperInSync_Hconfig1(t *testing.T) {
cfg := &config.Config{
App: config.AppConfig{Name: "sync-test", SiteName: "sync_site", Env: "prod", Debug: true},
Server: config.ServerConfig{Port: 7777},
}
if err := config.Set(cfg); err != nil {
t.Fatalf("Set: %v", err)
}
defer config.SetDefaultManager(nil)
// 类型化视图
got := config.Get()
if got == nil || got.App.Name != "sync-test" || got.Server.Port != 7777 {
t.Fatalf("Get() 不一致: %+v", got)
}
// viper 视图必须同源
if v := config.GetString("app.name"); v != "sync-test" {
t.Errorf("GetString(app.name) = %q, want sync-test（H-config-1 同源）", v)
}
if v := config.GetInt("server.port"); v != 7777 {
t.Errorf("GetInt(server.port) = %d, want 7777（H-config-1）", v)
}
if v := config.GetBool("app.debug"); v != true {
t.Errorf("GetBool(app.debug) = %v, want true（H-config-1）", v)
}
if v := config.GetString("app.env"); v != "prod" {
t.Errorf("GetString(app.env) = %q, want prod（H-config-1）", v)
}
vp := config.GetViper()
if vp == nil || vp.GetString("app.name") != "sync-test" {
t.Errorf("GetViper().GetString(app.name) 不一致（H-config-1）: %v", vp)
}
// Set(nil) 清空，GetString 返回空（m.v=nil）
if err := config.Set(nil); err != nil {
t.Fatalf("Set(nil): %v", err)
}
if v := config.GetString("app.name"); v != "" {
t.Errorf("Set(nil) 后 GetString 应为空, got %q", v)
}
}
// TestSetDurationGetDurationConsistent_Hconfig1 锁定 H-config-1 已知行为：Duration 字段经 Set
// 重建 viper 后，GetString 字面格式与文件加载不同（mapstructure 存 time.Duration -> Duration.String()），
// 但 typed view 与 GetDuration 在两条路径下一致。Duration 应经 typed view / GetDuration 读取。
func TestSetDurationGetDurationConsistent_Hconfig1(t *testing.T) {
cfg := &config.Config{
JWT: config.JWTConfig{Secret: strings.Repeat("k", 32), Expire: 24 * time.Hour},
}
if err := config.Set(cfg); err != nil {
t.Fatalf("Set: %v", err)
}
defer config.SetDefaultManager(nil)
if got := config.Get().JWT.Expire; got != 24*time.Hour {
t.Errorf("Get().JWT.Expire = %v, want 24h", got)
}
if got := config.GetViper().GetDuration("jwt.expire"); got != 24*time.Hour {
t.Errorf("GetDuration(jwt.expire) = %v, want 24h（Duration 同源应读 GetDuration/typed view）", got)
}
}
// TestReloadCallbackPanicIsolation_Mconfig1 固化 M-config-1：单个热重载回调 panic 不得
// 向上传播、不得阻断后续回调、不得让 watcher/reload 链路静默失效。
func TestReloadCallbackPanicIsolation_Mconfig1(t *testing.T) {
p := writeConfig(t, "m1_panic.yaml", validConfigYAML(8301))
defer os.Remove(p)
m := config.NewManager(p)
if _, err := m.Load(); err != nil {
t.Fatalf("Load: %v", err)
}
called := make(chan int, 4)
m.RegisterCallback(func(*config.Config) {
panic("boom from user callback") // 模拟用户回调 panic
})
m.RegisterCallback(func(c *config.Config) {
called <- c.Server.Port
})
// Reload 不应把回调 panic 向上传播
if err := m.Reload(); err != nil {
t.Fatalf("Reload 不应传播回调 panic: %v", err)
}
// 第二个回调仍触发：panic 被隔离，未阻断后续回调
select {
case port := <-called:
if port != 8301 {
t.Errorf("第二个回调端口 = %d, want 8301", port)
}
case <-time.After(time.Second):
t.Fatal("panic 后续回调未触发（M-config-1 隔离失败）")
}
// 后续 reload 仍正常，watcher/reload 链路未静默失效
if err := os.WriteFile(p, []byte(validConfigYAML(8302)), 0644); err != nil {
t.Fatalf("WriteFile: %v", err)
}
if err := m.Reload(); err != nil {
t.Fatalf("panic 后 Reload 应仍可用: %v", err)
}
select {
case port := <-called:
if port != 8302 {
t.Errorf("第二次 reload 回调端口 = %d, want 8302", port)
}
case <-time.After(time.Second):
t.Fatal("panic 后 reload 链路静默失效（M-config-1）")
}
}
// TestMySQLDSN_TLS_Mconfig2 固化 M-config-2 MySQL TLS：TLS=false 无 tls 参数；
// TLS=true 无 CA 用内置 tls=true；TLS=true 有 CA 用 tls=MySQLTLSConfigName。
func TestMySQLDSN_TLS_Mconfig2(t *testing.T) {
db := config.DatabaseConfig{Host: "h", Port: 3306, User: "u", Password: "p", Name: "n"}
if dsn := db.MySQLDSN(); strings.Contains(dsn, "tls=") {
t.Errorf("TLS=false 不应含 tls 参数, dsn=%s", dsn)
}
db.TLS = true
if dsn := db.MySQLDSN(); !strings.Contains(dsn, "&tls=true") {
t.Errorf("TLS=true 无 CA 应用内置 tls=true, dsn=%s", dsn)
}
db.TLSRootCA = "/path/ca.pem"
if dsn := db.MySQLDSN(); !strings.Contains(dsn, "&tls="+config.MySQLTLSConfigName) {
t.Errorf("TLS=true 有 CA 应用 tls=%s, dsn=%s", config.MySQLTLSConfigName, dsn)
}
// CustomDSN 优先，TLS 字段不影响 DSN()
db.CustomDSN = "custom-dsn"
if dsn := db.DSN(); dsn != "custom-dsn" {
t.Errorf("CustomDSN 应优先, got %s", dsn)
}
}
// TestPostgresDSN_SSLMode_Mconfig2 固化 M-config-2 Postgres SSLMode：空默认 prefer；
// 显式值透传（sslmode 不加引号，与原 disable 格式一致）。
func TestPostgresDSN_SSLMode_Mconfig2(t *testing.T) {
db := config.DatabaseConfig{Driver: config.DriverPostgres, Host: "h", Port: 5432, User: "u", Password: "p", Name: "n"}
if dsn := db.PostgresDSN(); !strings.Contains(dsn, "sslmode=prefer ") {
t.Errorf("空 SSLMode 默认 prefer, dsn=%s", dsn)
}
for _, mode := range []string{"disable", "allow", "require", "verify-ca", "verify-full"} {
db.SSLMode = mode
if dsn := db.PostgresDSN(); !strings.Contains(dsn, "sslmode="+mode+" ") {
t.Errorf("SSLMode=%s 应透传, dsn=%s", mode, dsn)
}
}
}
// TestValidateMaxIdleExceedsOpen_Lconfig3 固化 L-config-3：MaxOpenConns>0 时
// MaxIdleConns>MaxOpenConns 视为配置错误；MaxOpenConns=0（无限）不校验。
func TestValidateMaxIdleExceedsOpen_Lconfig3(t *testing.T) {
cfg := &config.Config{
Database: config.DatabaseConfig{
Host: "h", Port: 3306, User: "u", Password: "p", Name: "n",
MaxOpenConns: 10, MaxIdleConns: 20,
},
}
err := cfg.Validate()
if err == nil || !strings.Contains(err.Error(), "max_idle_conns") {
t.Fatalf("MaxIdleConns>MaxOpenConns 应报错, got: %v", err)
}
cfg.Database.MaxOpenConns = 0 // 未配置/无限，不校验 idle
if err := cfg.Validate(); err != nil {
t.Fatalf("MaxOpenConns=0 时不该校验 idle, got: %v", err)
}
cfg.Database.MaxOpenConns = 20 // 合法
if err := cfg.Validate(); err != nil {
t.Fatalf("合法配置不应报错, got: %v", err)
}
}
// TestValidatePostgresSSLMode_Mconfig2 固化 M-config-2：非法 SSLMode 在 Validate 阶段报错。
func TestValidatePostgresSSLMode_Mconfig2(t *testing.T) {
cfg := &config.Config{
Database: config.DatabaseConfig{
Driver: config.DriverPostgres, Host: "h", Port: 5432, User: "u", Password: "p", Name: "n",
SSLMode: "invalid-mode",
},
}
err := cfg.Validate()
if err == nil || !strings.Contains(err.Error(), "ssl_mode") {
t.Fatalf("非法 SSLMode 应报错, got: %v", err)
}
cfg.Database.SSLMode = "require"
if err := cfg.Validate(); err != nil {
t.Fatalf("合法 SSLMode=require 不应报错, got: %v", err)
}
}
// TestValidateTLSRootCAWithoutTLS_Mconfig2 固化 M-config-2：TLSRootCA 需配合 tls:true。
func TestValidateTLSRootCAWithoutTLS_Mconfig2(t *testing.T) {
cfg := &config.Config{
Database: config.DatabaseConfig{
Host: "h", Port: 3306, User: "u", Password: "p", Name: "n",
TLSRootCA: "/path/ca.pem", // TLS=false
},
}
err := cfg.Validate()
if err == nil || !strings.Contains(err.Error(), "tls_root_ca") {
t.Fatalf("TLSRootCA 无 tls:true 应报错, got: %v", err)
}
cfg.Database.TLS = true
if err := cfg.Validate(); err != nil {
t.Fatalf("TLS=true + TLSRootCA 合法不应报错, got: %v", err)
}
}
// TestDSNAddrNilReceiver_Lconfig6 固化 L-config-6：DSN/MySQLDSN/PostgresDSN/Addr 对 nil receiver 安全。
func TestDSNAddrNilReceiver_Lconfig6(t *testing.T) {
var db *config.DatabaseConfig
if v := db.DSN(); v != "" {
t.Errorf("nil DatabaseConfig.DSN() = %q, want empty", v)
}
if v := db.MySQLDSN(); v != "" {
t.Errorf("nil MySQLDSN() = %q, want empty", v)
}
if v := db.PostgresDSN(); v != "" {
t.Errorf("nil PostgresDSN() = %q, want empty", v)
}
var r *config.RedisConfig
if v := r.Addr(); v != "" {
t.Errorf("nil RedisConfig.Addr() = %q, want empty", v)
}
}
// TestCloneDeepCopiesAllSliceFields_Mconfig4 固化 M-config-4：反射枚举 Config 所有切片/map 字段，
// 断言 Clone 深拷贝（不同底层数组/map）。fixture 必须填充每个切片字段--新增切片字段若未在 Clone
// 中处理、或未在 fixture 中填充，本测试都会失败，形成机械守卫。
func TestCloneDeepCopiesAllSliceFields_Mconfig4(t *testing.T) {
original := allSlicesPopulatedConfig()
clone := original.Clone()
var check func(o, c reflect.Value, path string)
check = func(o, c reflect.Value, path string) {
for o.Kind() == reflect.Pointer {
o = o.Elem()
}
for c.Kind() == reflect.Pointer {
c = c.Elem()
}
if o.Kind() != reflect.Struct {
return
}
for i := 0; i < o.NumField(); i++ {
of := o.Field(i)
cf := c.Field(i)
p := path + "." + o.Type().Field(i).Name
switch of.Kind() {
case reflect.Pointer, reflect.Struct:
check(of, cf, p)
case reflect.Slice:
if of.IsNil() || of.Len() == 0 {
t.Errorf("M-config-4: fixture 未填充切片 %s（新增切片字段须同步 fixture 与 Clone）", p)
continue
}
if cf.IsNil() || cf.Len() != of.Len() {
t.Errorf("M-config-4: Clone 后切片 %s 为 nil 或长度不一致", p)
continue
}
if of.Pointer() == cf.Pointer() {
t.Errorf("M-config-4: Clone 未深拷贝切片 %s（共享底层数组）", p)
}
case reflect.Map:
if of.IsNil() || of.Len() == 0 {
t.Errorf("M-config-4: fixture 未填充 map %s", p)
continue
}
if of.Pointer() == cf.Pointer() {
t.Errorf("M-config-4: Clone 未深拷贝 map %s（共享 map）", p)
}
}
}
}
check(reflect.ValueOf(original), reflect.ValueOf(clone), "Config")
}
// allSlicesPopulatedConfig 返回一个填充了所有切片字段的 Config，供 Clone 覆盖断言使用。
// 新增任何切片/map 字段到 Config 或其子结构体时，必须同步在此填充，否则
// TestCloneDeepCopiesAllSliceFields_Mconfig4 会以"未填充"失败提醒。
func allSlicesPopulatedConfig() *config.Config {
return &config.Config{
CORS: config.CORSConfig{
AllowedOrigins: []string{"https://a.example.com"},
AllowedMethods: []string{"GET"},
AllowedHeaders: []string{"X-Test"},
ExposedHeaders: []string{"X-Exp"},
},
Upload: config.UploadConfig{
AllowedImageTypes: []string{"image/jpeg"},
AllowedVideoTypes: []string{"video/mp4"},
},
Storage: config.StorageConfig{
Local: config.LocalStorageConfig{
Upload: config.UploadPolicy{
AllowedExts: []string{".jpg"},
AllowedMIMEs: []string{"image/jpeg"},
},
},
OSS: config.OSSStorageConfig{
Upload: config.UploadPolicy{
AllowedExts: []string{".png"},
AllowedMIMEs: []string{"image/png"},
},
},
},
}
}
config/config_test.go
+441
View File
@@ -0,0 +1,441 @@
package config_test
import (
"os"
"path/filepath"
"strings"
"testing"
"github.com/EthanCodeCraft/xlgo-core/config"
)
func getTempDir() string {
dir := os.TempDir()
return filepath.Join(dir, "xlgo_test")
}
func setupTempFile(name, content string) (string, error) {
dir := getTempDir()
os.MkdirAll(dir, 0755)
path := filepath.Join(dir, name)
err := os.WriteFile(path, []byte(content), 0644)
return path, err
}
func TestAppConfig(t *testing.T) {
// 测试 AppConfig 方法
app := config.AppConfig{
Name: "TestApp",
SiteName: "test_site",
Version: "1.0.0",
Env: "dev",
Debug: true,
BaseURL: "https://test.example.com",
}
// GetSiteName
if app.GetSiteName() != "test_site" {
t.Error("GetSiteName failed")
}
// IsDebug
if !app.IsDebug() {
t.Error("IsDebug failed")
}
// IsDev
if !app.IsDev() {
t.Error("IsDev failed")
}
// IsProd
if app.IsProd() {
t.Error("IsProd should be false for dev")
}
// 测试 nil 安全性
var nilApp *config.AppConfig
if nilApp.GetSiteName() != "" {
t.Error("nil GetSiteName should return empty")
}
if nilApp.IsDebug() {
t.Error("nil IsDebug should return false")
}
}
func TestAppConfigIsProd(t *testing.T) {
app := config.AppConfig{Env: "prod"}
if !app.IsProd() {
t.Error("IsProd failed for prod")
}
app2 := config.AppConfig{Env: "production"}
if !app2.IsProd() {
t.Error("IsProd failed for production")
}
}
func TestDatabaseConfigDSN(t *testing.T) {
db := config.DatabaseConfig{
Host: "localhost",
Port: 3306,
User: "root",
Password: "password",
Name: "testdb",
}
dsn := db.DSN()
expected := "root:password@tcp(localhost:3306)/testdb?charset=utf8mb4&parseTime=True&loc=Local"
if dsn != expected {
t.Errorf("DSN = %s, want %s", dsn, expected)
}
}
func TestDatabaseConfigPostgresDSN(t *testing.T) {
db := config.DatabaseConfig{
Driver: config.DriverPostgres,
Host: "localhost",
Port: 5432,
User: "postgres",
Password: "password",
Name: "testdb",
}
dsn := db.DSN()
expected := "host='localhost' port=5432 user='postgres' password='password' dbname='testdb' sslmode=prefer TimeZone='Asia/Shanghai'"
if dsn != expected {
t.Errorf("Postgres DSN = %s, want %s", dsn, expected)
}
// 显式 MySQL DSN 不受 Driver 影响
if db.MySQLDSN() == "" {
t.Error("MySQLDSN should not be empty")
}
}
func TestDatabaseConfigUnknownDriverDoesNotFallback(t *testing.T) {
db := config.DatabaseConfig{
Driver: "no-such-driver",
Host: "localhost",
Port: 3306,
User: "root",
Password: "password",
Name: "testdb",
}
if dsn := db.DSN(); dsn != "" {
t.Fatalf("未知 driver 不应静默回退 MySQL，实际 DSN=%q", dsn)
}
cfg := &config.Config{Database: db}
if err := cfg.Validate(); err == nil || !strings.Contains(err.Error(), "database.driver") {
t.Fatalf("未知 driver 应在 Validate 阶段报错，实际: %v", err)
}
}
// TestDatabaseConfigDSNPasswordEscape_M9：含特殊字符的密码须被转义，不破坏 DSN。
func TestDatabaseConfigDSNPasswordEscape_M9(t *testing.T) {
// MySQL：密码含 @/:/空格 → url.QueryEscape
mysql := config.DatabaseConfig{
Driver: config.DriverMySQL,
Host: "localhost",
Port: 3306,
User: "root",
Password: "p@ss w:ord",
Name: "testdb",
}
mdsn := mysql.MySQLDSN()
// 密码段应被转义，@ 不应与 DSN 的 @ 分隔符混淆
if !strings.Contains(mdsn, "root:p%40ss+w%3Aord@tcp") {
t.Errorf("MySQL DSN password not escaped: %s", mdsn)
}
// Postgres：密码含单引号 → 翻倍转义
pg := config.DatabaseConfig{
Driver: config.DriverPostgres,
Host: "localhost",
Port: 5432,
User: "postgres",
Password: "p'ord",
Name: "testdb",
}
pdsn := pg.PostgresDSN()
if !strings.Contains(pdsn, `password='p\'ord'`) {
t.Errorf("Postgres DSN password not escaped: %s", pdsn)
}
// Timezone 可配置
pg2 := config.DatabaseConfig{Driver: config.DriverPostgres, Host: "h", Port: 5432, User: "u", Password: "p", Name: "n", Timezone: "UTC"}
if !strings.Contains(pg2.PostgresDSN(), "TimeZone='UTC'") {
t.Errorf("Postgres DSN should honor Timezone=UTC: %s", pg2.PostgresDSN())
}
mysql2 := config.DatabaseConfig{Driver: config.DriverMySQL, Host: "h", Port: 3306, User: "u", Password: "p", Name: "n", Timezone: "UTC"}
if !strings.Contains(mysql2.MySQLDSN(), "loc=UTC") {
t.Errorf("MySQL DSN should honor Timezone=UTC: %s", mysql2.MySQLDSN())
}
}
func TestDatabaseConfigCustomDSN(t *testing.T) {
db := config.DatabaseConfig{
Driver: config.DriverPostgres,
CustomDSN: "custom-connection-string",
}
if db.DSN() != "custom-connection-string" {
t.Errorf("CustomDSN should take precedence, got %s", db.DSN())
}
}
func TestRedisConfigAddr(t *testing.T) {
redis := config.RedisConfig{
Host: "localhost",
Port: 6379,
}
addr := redis.Addr()
if addr != "localhost:6379" {
t.Errorf("Addr = %s, want localhost:6379", addr)
}
}
func TestConfigLoad(t *testing.T) {
// 创建临时配置文件
content := `
app:
name: "测试应用"
site_name: "test_api"
version: "1.0.0"
env: "dev"
debug: true
server:
port: 8080
mode: "development"
database:
host: "localhost"
port: 3306
user: "root"
password: "test"
name: "testdb"
redis:
host: "localhost"
port: 6379
password: ""
db: 0
jwt:
secret: "test-secret-12345678901234567890123456789012"
expire: "1h"
`
tmpFile, err := setupTempFile("test_config.yaml", content)
if err != nil {
t.Fatalf("WriteFile error: %v", err)
}
defer os.Remove(tmpFile)
defer os.Remove(getTempDir())
// 重置全局状态
config.Set(nil)
// 加载配置
cfg, err := config.Load(tmpFile)
if err != nil {
t.Fatalf("Load error: %v", err)
}
// 验证配置
if cfg.App.Name != "测试应用" {
t.Errorf("App.Name = %s", cfg.App.Name)
}
if cfg.App.SiteName != "test_api" {
t.Errorf("App.SiteName = %s", cfg.App.SiteName)
}
if cfg.Server.Port != 8080 {
t.Errorf("Server.Port = %d", cfg.Server.Port)
}
if cfg.Database.Host != "localhost" {
t.Errorf("Database.Host = %s", cfg.Database.Host)
}
// 测试 Get
cfg2 := config.Get()
if cfg2 == nil {
t.Error("Get returned nil")
}
// 测试 GetSiteName
if cfg.GetSiteName() != "test_api" {
t.Errorf("GetSiteName = %s", cfg.GetSiteName())
}
// 测试 GetAppName
if cfg.GetAppName() != "测试应用" {
t.Errorf("GetAppName = %s", cfg.GetAppName())
}
// 测试 IsDevelopment
if !cfg.IsDevelopment() {
t.Error("IsDevelopment should be true")
}
// 测试 IsProduction
if cfg.IsProduction() {
t.Error("IsProduction should be false")
}
// 测试 GetString/GetInt (子测试)
t.Run("GetString", func(t *testing.T) {
val := config.GetString("app.site_name")
if val != "test_api" {
t.Errorf("GetString = %s, want test_api", val)
}
})
t.Run("GetInt", func(t *testing.T) {
port := config.GetInt("server.port")
if port != 8080 {
t.Errorf("GetInt = %d, want 8080", port)
}
})
t.Run("GetBool", func(t *testing.T) {
if config.GetBool("nonexistent") != false {
t.Error("GetBool should return false for nonexistent")
}
})
}
func TestConfigGetString(_ *testing.T) {
// 已在 TestConfigLoad 中作为子测试完成
// 此函数保留为占位符，避免删除后影响其他测试引用
}
func TestConfigLoadReloadsDifferentFiles(t *testing.T) {
first, err := setupTempFile("first_config.yaml", "app:\n name: first\nserver:\n port: 1001\n")
if err != nil {
t.Fatalf("WriteFile first error: %v", err)
}
second, err := setupTempFile("second_config.yaml", "app:\n name: second\nserver:\n port: 1002\n")
if err != nil {
t.Fatalf("WriteFile second error: %v", err)
}
defer os.Remove(first)
defer os.Remove(second)
cfg, err := config.Load(first)
if err != nil {
t.Fatalf("Load first error: %v", err)
}
if cfg.App.Name != "first" || cfg.Server.Port != 1001 {
t.Fatalf("unexpected first config: %+v", cfg)
}
cfg, err = config.Load(second)
if err != nil {
t.Fatalf("Load second error: %v", err)
}
if cfg.App.Name != "second" || cfg.Server.Port != 1002 {
t.Fatalf("unexpected second config: %+v", cfg)
}
}
func TestConfigManagerIsolation(t *testing.T) {
first, err := setupTempFile("manager_first.yaml", "app:\n name: manager_first\n")
if err != nil {
t.Fatalf("WriteFile first error: %v", err)
}
second, err := setupTempFile("manager_second.yaml", "app:\n name: manager_second\n")
if err != nil {
t.Fatalf("WriteFile second error: %v", err)
}
defer os.Remove(first)
defer os.Remove(second)
m1 := config.NewManager(first)
m2 := config.NewManager(second)
cfg1, err := m1.Load()
if err != nil {
t.Fatalf("m1 Load error: %v", err)
}
cfg2, err := m2.Load()
if err != nil {
t.Fatalf("m2 Load error: %v", err)
}
if cfg1.App.Name != "manager_first" || cfg2.App.Name != "manager_second" {
t.Fatalf("managers should be isolated: %+v %+v", cfg1, cfg2)
}
}
func TestConfigSet(t *testing.T) {
cfg := &config.Config{
App: config.AppConfig{
Name: "Manual",
SiteName: "manual_site",
},
}
config.Set(cfg)
if config.Get().App.Name != "Manual" {
t.Error("Set failed")
}
}
func TestConfigMethodsOnNil(t *testing.T) {
// 测试 nil Config 的方法安全性
var nilCfg *config.Config
if nilCfg.IsDevelopment() {
t.Error("nil IsDevelopment should be false")
}
if nilCfg.IsProduction() {
t.Error("nil IsProduction should be false")
}
if nilCfg.GetAppName() != "" {
t.Error("nil GetAppName should return empty")
}
if nilCfg.GetSiteName() != "" {
t.Error("nil GetSiteName should return empty")
}
}
func TestStorageConfig(t *testing.T) {
cfg := config.StorageConfig{
Driver: "local",
Local: config.LocalStorageConfig{
Path: "/uploads",
BaseURL: "http://localhost/uploads",
},
}
if cfg.Driver != "local" {
t.Error("StorageConfig Driver failed")
}
}
func TestLogConfig(t *testing.T) {
log := config.LogConfig{
Dir: "/logs",
MaxSize: 100,
MaxBackups: 5,
MaxAge: 30,
Compress: true,
}
if log.Dir != "/logs" {
t.Error("LogConfig Dir failed")
}
}
func TestUploadConfig(t *testing.T) {
upload := config.UploadConfig{
MaxFileSize: 10,
MaxVideoSize: 100,
AllowedImageTypes: []string{"image/jpeg", "image/png"},
}
if upload.MaxFileSize != 10 {
t.Error("UploadConfig failed")
}
}
config/validate.go
+109
View File
@@ -0,0 +1,109 @@
package config
import (
"fmt"
"strings"
"time"
)
// Validate 校验配置完整性与取值合法性（#16）。
// 在 Manager.Load 解析后自动调用，把"运行时第一次请求才暴露"的配置错误
// 提前到进程启动期。返回的 error 描述具体字段，便于定位。
func (c *Config) Validate() error {
if c == nil {
return fmt.Errorf("配置为空")
}
var problems []string
// Server
if c.Server.Port < 0 || c.Server.Port > 65535 {
problems = append(problems, fmt.Sprintf("server.port 超出范围(0-65535): %d", c.Server.Port))
}
if c.Server.TLS.Enabled {
if strings.TrimSpace(c.Server.TLS.CertFile) == "" || strings.TrimSpace(c.Server.TLS.KeyFile) == "" {
problems = append(problems, "server.tls 启用后必须同时配置 cert_file 与 key_file")
}
}
if !validDuration(c.Server.ReadTimeout) || !validDuration(c.Server.WriteTimeout) ||
!validDuration(c.Server.IdleTimeout) || !validDuration(c.Server.ShutdownTimeout) {
problems = append(problems, "server 的 timeout 配置不能为负值")
}
// JWT：仅当配置了 secret 时校验（未启用 jwt 的项目可留空）
if c.JWT.Secret != "" {
if len(c.JWT.Secret) < 32 {
problems = append(problems, fmt.Sprintf("jwt.secret 长度不足 32 字节（当前 %d），HMAC 密钥过短不安全", len(c.JWT.Secret)))
}
if c.JWT.Expire < 0 || c.JWT.RefreshExpire < 0 {
problems = append(problems, "jwt.expire / jwt.refresh_expire 不能为负值")
}
}
// Database：出现任一数据库字段时视为启用；driver 为空按 MySQL 兼容处理。
if c.Database.isConfigured() {
driver := strings.TrimSpace(c.Database.Driver)
if driver != "" {
if _, ok := LookupDSNBuilder(driver); !ok {
problems = append(problems, fmt.Sprintf("database.driver 未注册: %s", driver))
}
}
if strings.TrimSpace(c.Database.CustomDSN) == "" && strings.TrimSpace(c.Database.Host) == "" {
problems = append(problems, "database.host 启用数据库后必填")
}
if strings.TrimSpace(c.Database.CustomDSN) == "" && strings.TrimSpace(c.Database.Name) == "" {
problems = append(problems, "database.name 启用数据库后必填")
}
if strings.TrimSpace(c.Database.CustomDSN) == "" && (c.Database.Port <= 0 || c.Database.Port > 65535) {
problems = append(problems, fmt.Sprintf("database.port 超出范围(1-65535): %d", c.Database.Port))
}
// L-config-3：连接池配置交叉校验。MaxOpenConns>0 时 MaxIdleConns 不应超过它，
// 否则 database/sql 会按 MaxOpenConns 截断空闲连接，配置意图与实际不符。
if c.Database.MaxOpenConns > 0 && c.Database.MaxIdleConns > c.Database.MaxOpenConns {
problems = append(problems, fmt.Sprintf(
"database.max_idle_conns(%d) 不应大于 max_open_conns(%d)", c.Database.MaxIdleConns, c.Database.MaxOpenConns))
}
// M-config-2：Postgres SSLMode 合法性（非空时校验，空由 PostgresDSN 默认 prefer）。
if sslmode := strings.TrimSpace(c.Database.SSLMode); sslmode != "" {
if !validPostgresSSLMode(sslmode) {
problems = append(problems, fmt.Sprintf(
"database.ssl_mode 非法: %s（允许: disable/allow/prefer/require/verify-ca/verify-full）", sslmode))
}
}
// M-config-2：TLSRootCA 仅在 TLS=true 时生效，单独配置而无 tls:true 视为配置不一致。
if strings.TrimSpace(c.Database.TLSRootCA) != "" && !c.Database.TLS {
problems = append(problems, "database.tls_root_ca 需配合 tls: true 才生效")
}
}
// Redis：仅当配置了 host 时校验
if strings.TrimSpace(c.Redis.Host) != "" {
if c.Redis.Port <= 0 || c.Redis.Port > 65535 {
problems = append(problems, fmt.Sprintf("redis.port 超出范围(1-65535): %d", c.Redis.Port))
}
}
// Trace：仅当启用时校验采样比例。ExporterType/Propagator 的枚举校验委托 trace.Init
// （随 OTel 版本可能扩展，避免 config 与 trace 双源枚举漂移）。
if c.Trace.Enabled {
if c.Trace.SampleRatio < 0 || c.Trace.SampleRatio > 1 {
problems = append(problems, fmt.Sprintf("trace.sample_ratio 超出范围(0.0-1.0): %v", c.Trace.SampleRatio))
}
}
if len(problems) > 0 {
return fmt.Errorf("配置校验失败: %s", strings.Join(problems, "; "))
}
return nil
}
// validDuration 校验 Duration 非负（0 表示未配置/用默认，合法）。
func validDuration(d time.Duration) bool { return d >= 0 }
// validPostgresSSLMode 校验 PostgreSQL sslmode 取值（M-config-2）。
func validPostgresSSLMode(s string) bool {
switch s {
case "disable", "allow", "prefer", "require", "verify-ca", "verify-full":
return true
}
return false
}
config/validate_test.go
+81
View File
@@ -0,0 +1,81 @@
package config_test
import (
"strings"
"testing"
"github.com/EthanCodeCraft/xlgo-core/config"
)
func validBase() *config.Config {
return &config.Config{
Server: config.ServerConfig{Port: 8080},
}
}
func TestValidateOK(t *testing.T) {
if err := validBase().Validate(); err != nil {
t.Fatalf("unexpected error: %v", err)
}
}
func TestValidateServerPort(t *testing.T) {
c := validBase()
c.Server.Port = 99999
if err := c.Validate(); err == nil || !strings.Contains(err.Error(), "server.port") {
t.Fatalf("expected server.port error, got %v", err)
}
}
func TestValidateJWTSecretTooShort(t *testing.T) {
c := validBase()
c.JWT.Secret = "short"
if err := c.Validate(); err == nil || !strings.Contains(err.Error(), "jwt.secret") {
t.Fatalf("expected jwt.secret error, got %v", err)
}
}
func TestValidateJWTSecretAbsentSkipped(t *testing.T) {
c := validBase()
// secret 为空时不校验（未启用 jwt）
if err := c.Validate(); err != nil {
t.Fatalf("unexpected error: %v", err)
}
}
func TestValidateTraceSampleRatioWhenEnabled(t *testing.T) {
c := validBase()
c.Trace.Enabled = true
c.Trace.SampleRatio = 1.5
if err := c.Validate(); err == nil || !strings.Contains(err.Error(), "trace.sample_ratio") {
t.Fatalf("expected trace.sample_ratio error, got %v", err)
}
}
func TestValidateTraceDisabledSkipsRatio(t *testing.T) {
c := validBase()
// Enabled=false 时即使 SampleRatio 非法也不校验（trace 未启用）
c.Trace.SampleRatio = 1.5
if err := c.Validate(); err != nil {
t.Fatalf("unexpected error when trace disabled: %v", err)
}
}
func TestValidateDatabaseMissingHost(t *testing.T) {
c := validBase()
c.Database.Driver = "mysql"
c.Database.Port = 3306
c.Database.Name = "db"
// Host 留空
if err := c.Validate(); err == nil || !strings.Contains(err.Error(), "database.host") {
t.Fatalf("expected database.host error, got %v", err)
}
}
func TestValidateTLSMissingCert(t *testing.T) {
c := validBase()
c.Server.TLS.Enabled = true
if err := c.Validate(); err == nil || !strings.Contains(err.Error(), "cert_file") {
t.Fatalf("expected tls cert_file error, got %v", err)
}
}
console/console.go
+292
View File
@@ -0,0 +1,292 @@
package console
import (
"fmt"
"io"
"os"
"runtime"
"strings"
"sync"
"sync/atomic"
"time"
)
// writeMu 串行化所有 Console 的写出序列（P1 #7）。
// 用包级锁而非 per-Console 锁：多个 Console 实例可能共享同一底层 writer（如 stdout），
// per-Console 锁无法阻止跨实例交错；且 Windows printColor 的"设色→写→复位"三步必须整体
// 原子，否则并发彩色输出会串色。控制台输出非热路径，单一全局写锁的串行化开销可忽略。
var writeMu sync.Mutex
// Level 日志级别
type Level int32
const (
// LevelDebug 调试级别（最低）。
LevelDebug Level = iota
// LevelInfo 普通信息。
LevelInfo
// LevelSuccess 成功信息。
LevelSuccess
// LevelWarn 警告。
LevelWarn
// LevelError 错误（最高常规级别）。
LevelError
// LevelSilent 完全静默：所有调用都不输出
LevelSilent Level = 127
)
// String 返回级别名称
func (l Level) String() string {
if c, ok := colors[l]; ok {
return c.Name
}
if l == LevelSilent {
return "Silent"
}
return "Unknown"
}
// Color 颜色定义
type Color struct {
Code string
Name string
}
var colors = map[Level]Color{
LevelDebug: {Code: "0;36", Name: "Debug"}, // 青色
LevelInfo: {Code: "0;37", Name: "Info"}, // 白色
LevelSuccess: {Code: "0;92", Name: "Success"}, // 亮绿色
LevelWarn: {Code: "1;93", Name: "Warn"}, // 亮黄色
LevelError: {Code: "1;31", Name: "Error"}, // 亮红色
}
// Console 控制台打印器。
//
// console 包定位：开发期彩色 stdout 工具，跟 fmt.Println 同级。
// 不写文件、不感知运行环境、不做任何隐式 level 切换——
// 所有 level 行为都由调用方显式控制（SetLevel / WithLevel）。
//
// 业务可观测信息（用户登录、订单状态变更等"上线后必须保留的事件"）
// 请使用 logger 包；console 仅用于开发期肉眼调试。
type Console struct {
output io.Writer
isColor bool
showTime bool
showCall bool
timeFmt string
skipCall int
// level 通过 atomic 访问，支持运行期热切换且并发安全。
// 用 int32 存储 Level，0 = LevelDebug，与零值默认对齐。
level atomic.Int32
}
// Option 配置选项
type Option func(*Console)
// WithOutput 设置输出目标
func WithOutput(w io.Writer) Option {
return func(c *Console) {
c.output = w
}
}
// WithColor 设置是否启用颜色
func WithColor(enable bool) Option {
return func(c *Console) {
c.isColor = enable
}
}
// WithTime 设置是否显示时间
func WithTime(show bool) Option {
return func(c *Console) {
c.showTime = show
}
}
// WithCaller 设置是否显示调用位置。
// skip 可选，默认 2（直接调用方）；自封装一层时传 3。
func WithCaller(show bool, skip ...int) Option {
return func(c *Console) {
c.showCall = show
if len(skip) > 0 && skip[0] > 0 {
c.skipCall = skip[0]
}
}
}
// WithTimeFormat 设置时间格式
func WithTimeFormat(fmt string) Option {
return func(c *Console) {
c.timeFmt = fmt
}
}
// WithLevel 设置最低输出级别。低于该级别的调用会被静默丢弃。
//
// 例：WithLevel(LevelWarn) 只输出 Warn 与 Error；
//
// WithLevel(LevelSilent) 完全静默，常用于压测或上线观察期临时关闭调试输出。
func WithLevel(l Level) Option {
return func(c *Console) {
c.level.Store(int32(l))
}
}
// New 创建控制台打印器
func New(opts ...Option) *Console {
c := &Console{
output: os.Stdout,
isColor: true,
showTime: true,
showCall: true,
timeFmt: "15:04:05.000",
skipCall: 2,
}
// 默认 LevelDebug：开发期所有级别都打印。生产期请显式 SetLevel/WithLevel。
c.level.Store(int32(LevelDebug))
for _, opt := range opts {
opt(c)
}
return c
}
// SetLevel 运行期切换最低输出级别。并发安全。
func (c *Console) SetLevel(l Level) {
c.level.Store(int32(l))
}
// Level 返回当前最低输出级别
func (c *Console) Level() Level {
return Level(c.level.Load())
}
// Default 默认控制台
var Default = New()
// SetLevel 设置默认控制台的最低输出级别。并发安全。
//
// 典型用法（在 main 中根据 cfg 显式切换）：
//
// if cfg.IsProduction() {
// console.SetLevel(console.LevelWarn) // 生产期只看 Warn / Error
// }
//
// 框架不会自动根据环境模式切换，选择权完全在调用方。
func SetLevel(l Level) {
Default.SetLevel(l)
}
// GetLevel 返回默认控制台当前最低输出级别。
// （命名加 Get 前缀是因为 Level 已被类型占用，Go 不允许同名函数。）
func GetLevel() Level {
return Default.Level()
}
// print 内部打印函数
func (c *Console) print(level Level, s ...any) {
// 级别过滤：低于阈值或调用方显式 LevelSilent 时直接返回，零开销
if level < c.Level() {
return
}
var sb strings.Builder
// 时间
if c.showTime {
sb.WriteString(time.Now().Format(c.timeFmt))
sb.WriteString(" ")
}
// 级别名称
color := colors[level]
sb.WriteString("[")
sb.WriteString(color.Name)
sb.WriteString("] ")
// 调用位置
if c.showCall {
sb.WriteString(c.getCaller())
sb.WriteString(" ")
}
// 内容
sb.WriteString(fmt.Sprint(s...))
// 输出。P1 #7：全局写锁串行化整个写序列，避免并发交错输出；
// Windows 下 printColor 的"设色→写→复位"三步也被此锁整体保护，防止串色。
writeMu.Lock()
if c.isColor {
c.printColor(color.Code, sb.String())
} else {
fmt.Fprintln(c.output, sb.String())
}
writeMu.Unlock()
}
// getCaller 获取调用位置
func (c *Console) getCaller() string {
_, file, line, ok := runtime.Caller(c.skipCall)
if !ok {
return ""
}
// 只取文件名（兼容 / 与 \ 分隔）
if idx := strings.LastIndexAny(file, "/\\"); idx >= 0 {
file = file[idx+1:]
}
return fmt.Sprintf("%s:%d", file, line)
}
// Debug 打印调试信息（青色）
func (c *Console) Debug(s ...any) {
c.print(LevelDebug, s...)
}
// Info 打印普通信息（白色）
func (c *Console) Info(s ...any) {
c.print(LevelInfo, s...)
}
// Success 打印成功信息（绿色）
func (c *Console) Success(s ...any) {
c.print(LevelSuccess, s...)
}
// Warn 打印警告信息（黄色）
func (c *Console) Warn(s ...any) {
c.print(LevelWarn, s...)
}
// Error 打印错误信息（红色）
func (c *Console) Error(s ...any) {
c.print(LevelError, s...)
}
// ===== 包级别便捷函数 =====
// Debug 使用默认控制台打印调试信息
func Debug(s ...any) {
Default.print(LevelDebug, s...)
}
// Info 使用默认控制台打印普通信息
func Info(s ...any) {
Default.print(LevelInfo, s...)
}
// Success 使用默认控制台打印成功信息
func Success(s ...any) {
Default.print(LevelSuccess, s...)
}
// Warn 使用默认控制台打印警告信息
func Warn(s ...any) {
Default.print(LevelWarn, s...)
}
// Error 使用默认控制台打印错误信息
func Error(s ...any) {
Default.print(LevelError, s...)
}
console/console_test.go
+152
View File
@@ -0,0 +1,152 @@
package console_test
import (
"bytes"
"strings"
"testing"
"github.com/EthanCodeCraft/xlgo-core/console"
)
func TestConsole(t *testing.T) {
// 使用默认控制台
console.Debug("这是一条调试信息")
console.Info("这是一条普通信息")
console.Success("这是一条成功信息")
console.Warn("这是一条警告信息")
console.Error("这是一条错误信息")
// 创建自定义控制台
c := console.New(
console.WithColor(true),
console.WithTime(true),
console.WithCaller(true, 2),
)
c.Debug("自定义控制台 - Debug")
c.Info("自定义控制台 - Info")
c.Success("自定义控制台 - Success")
c.Warn("自定义控制台 - Warn")
c.Error("自定义控制台 - Error")
}
// TestConsoleLevelFilter 验证显式 level 屏蔽：低于阈值的调用不输出。
// 这是方案 A 的核心契约——用户显式控制何时屏蔽，框架不做隐式行为。
func TestConsoleLevelFilter(t *testing.T) {
var buf bytes.Buffer
c := console.New(
console.WithOutput(&buf),
console.WithColor(false),
console.WithTime(false),
console.WithCaller(false),
console.WithLevel(console.LevelWarn),
)
c.Debug("DEBUG_MARK")
c.Info("INFO_MARK")
c.Success("SUCCESS_MARK")
c.Warn("WARN_MARK")
c.Error("ERROR_MARK")
out := buf.String()
// Warn / Error 必须输出
if !strings.Contains(out, "WARN_MARK") {
t.Errorf("Warn should be printed at LevelWarn, got: %q", out)
}
if !strings.Contains(out, "ERROR_MARK") {
t.Errorf("Error should be printed at LevelWarn, got: %q", out)
}
// Debug / Info / Success 必须被静默
for _, mark := range []string{"DEBUG_MARK", "INFO_MARK", "SUCCESS_MARK"} {
if strings.Contains(out, mark) {
t.Errorf("%s should be filtered at LevelWarn, but found in: %q", mark, out)
}
}
}
// TestConsoleLevelSilent 验证 LevelSilent 完全静默所有调用。
func TestConsoleLevelSilent(t *testing.T) {
var buf bytes.Buffer
c := console.New(
console.WithOutput(&buf),
console.WithColor(false),
console.WithLevel(console.LevelSilent),
)
c.Debug("D")
c.Info("I")
c.Success("S")
c.Warn("W")
c.Error("E")
if buf.Len() != 0 {
t.Errorf("LevelSilent should suppress all output, got %d bytes: %q", buf.Len(), buf.String())
}
}
// TestConsoleSetLevel 验证运行期热切换 level。
func TestConsoleSetLevel(t *testing.T) {
var buf bytes.Buffer
c := console.New(
console.WithOutput(&buf),
console.WithColor(false),
console.WithTime(false),
console.WithCaller(false),
)
// 默认 LevelDebug，Debug 应输出
c.Debug("FIRST")
if !strings.Contains(buf.String(), "FIRST") {
t.Errorf("Debug should print at default LevelDebug, got: %q", buf.String())
}
buf.Reset()
// 切到 LevelError 后，Debug 应静默
c.SetLevel(console.LevelError)
if got := c.Level(); got != console.LevelError {
t.Errorf("Level() = %v, want LevelError", got)
}
c.Debug("SECOND")
if buf.Len() != 0 {
t.Errorf("Debug should be filtered after SetLevel(LevelError), got: %q", buf.String())
}
// Error 仍然输出
c.Error("THIRD")
if !strings.Contains(buf.String(), "THIRD") {
t.Errorf("Error should print at LevelError, got: %q", buf.String())
}
}
// TestConsolePackageLevelAPI 验证包级 SetLevel / GetLevel 操作的是 Default 实例。
func TestConsolePackageLevelAPI(t *testing.T) {
original := console.GetLevel()
t.Cleanup(func() { console.SetLevel(original) })
console.SetLevel(console.LevelWarn)
if got := console.GetLevel(); got != console.LevelWarn {
t.Errorf("GetLevel() = %v, want LevelWarn", got)
}
if got := console.Default.Level(); got != console.LevelWarn {
t.Errorf("Default.Level() = %v, want LevelWarn (package SetLevel must affect Default)", got)
}
}
// TestConsoleLevelString 验证 Level.String 输出可读名称（错误信息 / 日志会用到）。
func TestConsoleLevelString(t *testing.T) {
cases := map[console.Level]string{
console.LevelDebug: "Debug",
console.LevelInfo: "Info",
console.LevelSuccess: "Success",
console.LevelWarn: "Warn",
console.LevelError: "Error",
console.LevelSilent: "Silent",
}
for l, want := range cases {
if got := l.String(); got != want {
t.Errorf("Level(%d).String() = %q, want %q", l, got, want)
}
}
}
console/console_unix.go
+15
View File
@@ -0,0 +1,15 @@
//go:build linux || darwin
package console
import (
"fmt"
)
// printColor 彩色打印（使用ANSI转义序列）
func (c *Console) printColor(code, msg string) {
// \033[ 是ANSI转义序列起始
// %sm 是颜色代码
// \033[0m 是重置颜色
fmt.Fprintf(c.output, "\033[%sm%s\033[0m\n", code, msg)
}
console/console_windows.go
+69
View File
@@ -0,0 +1,69 @@
//go:build windows
package console
import (
"fmt"
"os"
"syscall"
"unsafe"
)
var kernel32 = syscall.NewLazyDLL("kernel32.dll")
// 颜色映射：ANSI -> Windows控制台颜色
// 0 黑色, 1 蓝色, 2 绿色, 3 青色, 4 红色, 5 紫色, 6 黄色, 7 淡灰色
// 8 灰色, 9 亮蓝色, 10 亮绿色, 11 亮青色, 12 亮红色, 13 亮紫色, 14 亮黄色, 15 白色
var colorMap = map[string]uintptr{
"0;36": 11, // 青色 -> 亮青色
"0;37": 15, // 白色 -> 白色
"0;92": 10, // 亮绿色
"1;93": 14, // 亮黄色
"1;31": 12, // 亮红色
}
// printColor 彩色打印。
//
// 修复 M17：原实现对 syscall.Stdout 设置颜色、却把文本写到 c.output——
// 当 c.output 非 stdout（如 WithOutput 指向文件）时，颜色落到错误句柄、文本落文件，
// 二者分裂。现按 c.output 实际类型取句柄：*os.File 用其 Fd()，否则放弃着色只写文本。
func (c *Console) printColor(code, msg string) {
color := colorMap[code]
if color == 0 {
color = 7 // 默认淡灰色
}
handle, ok := consoleHandle(c.output)
if !ok {
// 非 *os.File（如 bytes.Buffer/文件），无法设置控制台属性，退化为纯文本。
fmt.Fprintln(c.output, msg)
return
}
proc := kernel32.NewProc("SetConsoleTextAttribute")
_, _, _ = proc.Call(handle, color)
fmt.Fprintln(c.output, msg)
_, _, _ = proc.Call(handle, 7) // 恢复默认颜色
}
// consoleHandle 从 io.Writer 取 Windows 控制台句柄；非 *os.File 返回 (0, false)。
func consoleHandle(w interface{ Write([]byte) (int, error) }) (uintptr, bool) {
f, ok := w.(*os.File)
if !ok {
return 0, false
}
fd := f.Fd()
switch fd {
case uintptr(syscall.Stdout), uintptr(syscall.Stderr), uintptr(syscall.Stdin):
return fd, true
default:
// 重定向到文件/管道的 *os.File，SetConsoleTextAttribute 无意义，退化为纯文本。
return 0, false
}
}
// （M17：原 EnableVirtualTerminal 为死代码且从未被调用，已移除。
// Windows 10+ 默认支持 ANSI/VT 着色；需要 VT 的调用方应自行调 kernel32。）
// 保留 unsafe 引用以备将来 VT 扩展；当前 printColor 不再需要，故显式抑制未用告警。
var _ = unsafe.Sizeof(uintptr(0))
cron/cron.go
+840
View File
@@ -0,0 +1,840 @@
package cron
import (
"context"
"fmt"
"runtime/debug"
"strconv"
"strings"
"sync"
"sync/atomic"
"time"
"github.com/EthanCodeCraft/xlgo-core/logger"
"go.uber.org/zap"
)
// Task 定时任务
type Task struct {
Name string // 任务名称
Schedule Schedule // 调度规则
Handler TaskHandler // 任务处理函数
Enabled bool // 是否启用
LastRun time.Time // 上次运行时间
NextRun time.Time // 下次运行时间
RunCount int // 运行次数
LastError error // CR3 修复：最近一次执行错误
// running 防止长任务跨 tick 重叠执行（C12b）。
// 用指针以便 GetTask/ListTasks 返回 Task 拷贝时不触发 atomic.Bool 值类型的
// copylocks 警告；拷贝共享同一守卫状态，但该字段未导出，外部无法操作。
// nil 表示未初始化（仅非 AddTask 构造的 Task），checkAndRun/RunTask 以 nil 守卫跳过。
running *atomic.Bool
}
// TaskHandler 任务处理函数
type TaskHandler func(ctx context.Context) error
// Schedule 调度接口
type Schedule interface {
Next(now time.Time) time.Time
}
func validateSchedule(schedule Schedule) {
switch s := schedule.(type) {
case *IntervalSchedule:
validateInterval(s.Interval)
case *DailySchedule:
validateClock(s.Hour, s.Minute, "Daily")
case *WeeklySchedule:
validateWeekday(s.Day)
validateClock(s.Hour, s.Minute, "Weekly")
}
}
func validateInterval(interval time.Duration) {
if interval <= 0 {
panic("cron: interval must be positive")
}
}
func validateClock(hour, minute int, name string) {
if hour < 0 || hour > 23 {
panic(fmt.Sprintf("cron: %s hour must be in [0,23]", name))
}
if minute < 0 || minute > 59 {
panic(fmt.Sprintf("cron: %s minute must be in [0,59]", name))
}
}
func validateWeekday(day time.Weekday) {
if day < time.Sunday || day > time.Saturday {
panic("cron: Weekly day must be in [Sunday,Saturday]")
}
}
// Scheduler 调度器
type Scheduler struct {
tasks map[string]*Task
mu sync.RWMutex
lifecycleMu sync.Mutex
ctx context.Context
cancel context.CancelFunc
wg sync.WaitGroup
running bool
}
func newSchedulerContext() (context.Context, context.CancelFunc) {
return context.WithCancel(context.Background())
}
// NewScheduler 创建调度器
func NewScheduler() *Scheduler {
ctx, cancel := newSchedulerContext()
return &Scheduler{
tasks: make(map[string]*Task),
ctx: ctx,
cancel: cancel,
}
}
// AddTask 添加任务
func (s *Scheduler) AddTask(name string, schedule Schedule, handler TaskHandler) *Task {
if schedule == nil {
panic("cron: AddTask requires a non-nil schedule")
}
if handler == nil {
panic("cron: AddTask requires a non-nil handler")
}
validateSchedule(schedule)
task := &Task{
Name: name,
Schedule: schedule,
Handler: handler,
Enabled: true,
NextRun: schedule.Next(time.Now()),
running: &atomic.Bool{},
}
s.mu.Lock()
s.tasks[name] = task
s.mu.Unlock()
return task
}
// RemoveTask 移除任务
func (s *Scheduler) RemoveTask(name string) {
s.mu.Lock()
delete(s.tasks, name)
s.mu.Unlock()
}
// EnableTask 启用任务
func (s *Scheduler) EnableTask(name string) error {
s.mu.Lock()
defer s.mu.Unlock()
task, ok := s.tasks[name]
if !ok {
return fmt.Errorf("任务不存在: %s", name)
}
task.Enabled = true
task.NextRun = task.Schedule.Next(time.Now())
return nil
}
// DisableTask 禁用任务
func (s *Scheduler) DisableTask(name string) error {
s.mu.Lock()
defer s.mu.Unlock()
task, ok := s.tasks[name]
if !ok {
return fmt.Errorf("任务不存在: %s", name)
}
task.Enabled = false
return nil
}
// GetTask 获取任务（返回拷贝快照，避免外部并发读 live 指针，C12a）。
func (s *Scheduler) GetTask(name string) (*Task, error) {
s.mu.RLock()
defer s.mu.RUnlock()
task, ok := s.tasks[name]
if !ok {
return nil, fmt.Errorf("任务不存在: %s", name)
}
cp := *task
return &cp, nil
}
// ListTasks 获取所有任务（返回拷贝快照，C12a）。
func (s *Scheduler) ListTasks() []*Task {
s.mu.RLock()
defer s.mu.RUnlock()
tasks := make([]*Task, 0, len(s.tasks))
for _, task := range s.tasks {
cp := *task
tasks = append(tasks, &cp)
}
return tasks
}
// executeTask 在 exec 边界运行 task handler；recover 捕获 panic 转为 error（含调用栈），
// 防止调度 goroutine 内未 recover 的 panic 终止整个进程（M13）。
// 命名返回值让 defer 在 panic 时改写 err。两侧调用点（RunTask / checkAndRun goroutine）
// 共用此边界，panic 一律转为 error 记入 LastError 并向上返回，不破坏 running 守卫与 wg.Done
// （recover 在本函数内部完成，外侧 defer 仍正常执行）。
func (s *Scheduler) executeTask(t *Task) (err error) {
s.mu.RLock()
ctx := s.ctx
s.mu.RUnlock()
return s.executeTaskWithContext(ctx, t)
}
func (s *Scheduler) executeTaskWithContext(ctx context.Context, t *Task) (err error) {
defer func() {
if r := recover(); r != nil {
err = fmt.Errorf("cron task %q panic recovered: %v\n%s", t.Name, r, debug.Stack())
}
}()
return t.Handler(ctx)
}
// RunTask 立即运行任务（手动触发，同步返回 handler 错误）。
//
// 占用 per-task running 守卫，与调度循环互斥，防止同一任务重叠执行（C12b）。
// 不推进 NextRun（手动触发不影响调度节奏，C12c）。LastRun/RunCount 在锁内更新（C12a）。
//
// L-J：handler 收到的 ctx 为调度器 s.ctx。Stop 后 s.ctx 已取消，handler 会收到 canceled
// ctx——这是预期行为（手动触发在调度器停止后不应继续执行长任务）。调用方若需在 Stop 后
// 仍运行一次性任务，应在自己的 ctx 下执行而非依赖调度器。
func (s *Scheduler) RunTask(name string) error {
s.mu.Lock()
task, ok := s.tasks[name]
s.mu.Unlock()
if !ok {
return fmt.Errorf("任务不存在: %s", name)
}
// 占用 running 守卫（nil 守卫直接放行，仅防御非 AddTask 构造的 Task）。
if task.running != nil && !task.running.CompareAndSwap(false, true) {
return fmt.Errorf("任务正在执行中: %s", name)
}
defer func() {
if task.running != nil {
task.running.Store(false)
}
}()
err := s.executeTask(task)
s.mu.Lock()
task.LastRun = time.Now()
task.RunCount++
task.LastError = err // M13: 手动路径也记 LastError（与调度路径对齐）
s.mu.Unlock()
return err
}
// Start 启动调度器
func (s *Scheduler) Start() {
s.lifecycleMu.Lock()
defer s.lifecycleMu.Unlock()
s.mu.Lock()
if s.running {
s.mu.Unlock()
return
}
select {
case <-s.ctx.Done():
s.ctx, s.cancel = newSchedulerContext()
default:
}
ctx := s.ctx
s.running = true
s.wg.Add(1)
s.mu.Unlock()
go s.run(ctx)
}
// Stop 停止调度器并无限等待在跑任务退出（要求 handler 尊重 ctx.Done）。
// 若担心某 handler 不响应 ctx 而永久阻塞，请用 StopWithTimeout。
func (s *Scheduler) Stop() {
s.StopWithTimeout(0)
}
// StopWithTimeout 停止调度器，最多等待 timeout 让在跑任务退出（P1 #10）。
// 返回 true 表示所有任务已退出；false 表示超时（仍有任务未响应 ctx.Done 而运行）。
// timeout<=0 等价于无限等待（同 Stop）。幂等：未运行时直接返回 true。
func (s *Scheduler) StopWithTimeout(timeout time.Duration) bool {
s.lifecycleMu.Lock()
defer s.lifecycleMu.Unlock()
s.mu.Lock()
if !s.running {
s.mu.Unlock()
return true
}
s.running = false
cancel := s.cancel
s.mu.Unlock()
cancel()
if timeout <= 0 {
s.wg.Wait()
return true
}
done := make(chan struct{})
go func() { s.wg.Wait(); close(done) }()
select {
case <-done:
return true
case <-time.After(timeout):
return false
}
}
// run 运行调度循环
func (s *Scheduler) run(ctx context.Context) {
defer s.wg.Done()
ticker := time.NewTicker(1 * time.Second)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
s.checkAndRun(ctx)
}
}
}
// checkAndRun 检查并运行到期任务。
//
// C12b：per-task running 守卫（CAS）防止长任务跨 tick 重叠 spawn。
// C12c：占用守卫后**先推进 NextRun**（以上次 NextRun 锚定，非 time.Now()），
// 避免每周期累积 handler 时长致调度漂移；推进在 spawn 前，下次 tick 不会重复 spawn。
// C12a：NextRun 推进在写锁内；LastRun/RunCount 在 goroutine 内写锁更新。
//
// M-H 修复：锁内只收集到期任务（CAS 占用 + 推进 NextRun + wg.Add），锁外再 spawn。
// 原实现整个遍历+spawn 持写锁，task 多时阻塞 GetTask/AddTask/RunTask 等管理 API。
//
// wg.Add 必须在锁内完成：Stop 先持锁置 running=false 再 wg.Wait，若 wg.Add 在锁外，
// Stop 可能在两个 due 任务之间读到计数器 0 并提前返回，留下后启动的 goroutine 在调度器
// 停止后运行（其 wg.Done 还会触发计数器下溢 panic）。锁内 Add 保证 Stop 的 wg.Wait
// 一定能等到本批全部 goroutine。收集阶段已 CAS 占用守卫并推进 NextRun，故 spawn 必须
// 执行（否则守卫不释放、NextRun 已推进却未跑）。spawn 用 s.ctx——Stop 后 ctx 已取消，
// handler 收到 canceled ctx 应及时退出。
func (s *Scheduler) checkAndRun(ctxs ...context.Context) {
now := time.Now()
var ctx context.Context
enforceRunning := len(ctxs) > 0 && ctxs[0] != nil
if len(ctxs) > 0 && ctxs[0] != nil {
ctx = ctxs[0]
} else {
s.mu.RLock()
ctx = s.ctx
s.mu.RUnlock()
}
s.mu.Lock()
if enforceRunning && (!s.running || ctx.Err() != nil) {
s.mu.Unlock()
return
}
var due []*Task
for _, task := range s.tasks {
if !task.Enabled || task.NextRun.IsZero() || !now.After(task.NextRun) {
continue
}
// 占用 running 守卫；正在执行则跳过本轮（防重叠 C12b）。
if task.running != nil && !task.running.CompareAndSwap(false, true) {
continue
}
// 先推进 NextRun（以上次 NextRun 锚定防漂移 C12c），再收集待 spawn。
task.NextRun = task.Schedule.Next(task.NextRun)
s.wg.Add(1) // 锁内 Add，保证 Stop 的 wg.Wait 等到本批（见上方注释）
due = append(due, task)
}
s.mu.Unlock()
for _, t := range due {
go func(t *Task) {
defer s.wg.Done()
defer func() {
if t.running != nil {
t.running.Store(false)
}
}()
err := s.executeTaskWithContext(ctx, t)
s.mu.Lock()
t.LastRun = time.Now()
t.RunCount++
t.LastError = err // CR3 修复：记录错误不再静默丢弃
s.mu.Unlock()
if err != nil {
logger.Error("cron task failed",
zap.String("task", t.Name),
zap.Error(err))
}
}(t)
}
}
// IntervalSchedule 固定间隔调度
type IntervalSchedule struct {
Interval time.Duration
}
// Next 计算下次运行时间
func (s *IntervalSchedule) Next(now time.Time) time.Time {
return now.Add(s.Interval)
}
// Every 每隔指定时间运行
func Every(interval time.Duration) *IntervalSchedule {
validateInterval(interval)
return &IntervalSchedule{Interval: interval}
}
// DailySchedule 每日定时调度
type DailySchedule struct {
Hour int
Minute int
}
// Next 计算下次运行时间
func (s *DailySchedule) Next(now time.Time) time.Time {
next := time.Date(now.Year(), now.Month(), now.Day(), s.Hour, s.Minute, 0, 0, now.Location())
if next.Before(now) || next.Equal(now) {
next = next.Add(24 * time.Hour)
}
return next
}
// Daily 每日指定时间运行
func Daily(hour, minute int) *DailySchedule {
validateClock(hour, minute, "Daily")
return &DailySchedule{Hour: hour, Minute: minute}
}
// WeeklySchedule 每周定时调度
type WeeklySchedule struct {
Day time.Weekday
Hour int
Minute int
}
// Next 计算下次运行时间。
//
// C12d：原实现 `daysUntil <= 0 → +7` 仅按 weekday 差值，不比较当天时刻，
// 当天目标时刻未到（如周一 9:00 目标、当前周一 12:00 之前的 8:00）被错误跳一周。
// 改为：先算今天的目标时刻，按 `((day-now)+7)%7` 加天数，再与 now 比较——
// 当天未到点则本周，当天已过则下周。
func (s *WeeklySchedule) Next(now time.Time) time.Time {
next := time.Date(now.Year(), now.Month(), now.Day(), s.Hour, s.Minute, 0, 0, now.Location())
daysUntil := (int(s.Day) - int(now.Weekday()) + 7) % 7
next = next.AddDate(0, 0, daysUntil)
if !next.After(now) {
next = next.AddDate(0, 0, 7)
}
return next
}
// Weekly 每周指定时间运行
func Weekly(day time.Weekday, hour, minute int) *WeeklySchedule {
validateWeekday(day)
validateClock(hour, minute, "Weekly")
return &WeeklySchedule{Day: day, Hour: hour, Minute: minute}
}
// FullCronSchedule 完整 Cron 表达式调度
// 格式: "分钟 小时 日 月 星期" (5字段)
// 示例: "0 12 * * *" 每天12点
//
// "0 0 1 * *" 每月1号凌晨
// "0 9-17 * * 1-5" 周一到周五 9点到17点每小时
type FullCronSchedule struct {
Minute string // 分钟: 0-59, "*", "*/n", "a-b", "a,b,c"
Hour string // 小时: 0-23, "*", "*/n", "a-b", "a,b,c"
Day string // 日: 1-31, "*", "*/n", "a-b", "a,b,c"
Month string // 月: 1-12, "*", "*/n", "a-b", "a,b,c"
Weekday string // 星期: 0-6 (周日=0), "*", "*/n", "a-b", "a,b,c"
}
// Next 计算下次运行时间
func (s *FullCronSchedule) Next(now time.Time) time.Time {
// 从下一分钟开始查找
next := now.Add(time.Minute)
next = time.Date(next.Year(), next.Month(), next.Day(), next.Hour(), next.Minute(), 0, 0, next.Location())
// 最多查找一年（防止无效表达式死循环）
maxAttempts := 366 * 24 * 60
for i := 0; i < maxAttempts; i++ {
if s.match(next) {
return next
}
next = next.Add(time.Minute)
}
return time.Time{}
}
// match 检查时间是否匹配表达式
func (s *FullCronSchedule) match(t time.Time) bool {
return s.matchField(s.Minute, t.Minute(), 0, 59) &&
s.matchField(s.Hour, t.Hour(), 0, 23) &&
s.matchField(s.Day, t.Day(), 1, 31) &&
s.matchField(s.Month, int(t.Month()), 1, 12) &&
s.matchField(s.Weekday, int(t.Weekday()), 0, 6)
}
// matchField 匹配单个字段（C12e 重写）。
//
// 旧实现先判 `-` 再判 `*/` 最后列表，且 parseInt 忽略非数字逐位累积：
// - `1-5,8` 因整字段含 `-` 被当范围，parseInt("5,8")=58 → 范围被破坏为 1..58，列表项丢失。
// - `garbage` → parseInt=0，分/时/周字段 value=0 时误触发。
// - `*/garbage` → step=0 → return true 匹配全部。
// - 周日 `7` 不匹配（Go Sunday=0）。
//
// 新实现：先按逗号拆列表，每项独立判 `*/n` / `a-b/n` / `a-b` / 单值（列表分支独立于范围分支）；
// 全部用 strconv.Atoi 返错；weekday 字段（min=0,max=6）7→0，范围 lo>hi 环绕。
func (s *FullCronSchedule) matchField(field string, value int, min, max int) bool {
if field == "*" {
return true
}
for _, raw := range strings.Split(field, ",") {
item := strings.TrimSpace(raw)
if item == "" {
continue
}
if matchCronItem(item, value, min, max) {
return true
}
}
return false
}
// matchCronItem 处理单个 cron 字段项（已按逗号拆分）。
func matchCronItem(item string, value, min, max int) bool {
isWeekday := min == 0 && max == 6
// 步长 "*/n" 或 "a-b/n"
if idx := strings.Index(item, "/"); idx >= 0 {
base := item[:idx]
step, err := strconv.Atoi(item[idx+1:])
if err != nil || step <= 0 {
return false
}
lo, hi := min, max
if base != "*" {
rlo, rhi, err := parseCronRange(base, min, max)
if err != nil {
return false
}
lo, hi = rlo, rhi
}
return value >= lo && value <= hi && (value-lo)%step == 0
}
// 范围 "a-b"
if strings.Contains(item, "-") {
lo, hi, err := parseCronRange(item, min, max)
if err != nil {
return false
}
if isWeekday && lo > hi {
// 环绕：lo..6 ∪ 0..hi（如 "6-1" = 周六、周日、周一）
return (value >= lo && value <= max) || (value >= min && value <= hi)
}
return value >= lo && value <= hi
}
// 单值
v, err := strconv.Atoi(item)
if err != nil {
return false
}
if isWeekday && v == 7 {
v = 0
}
if v < min || v > max {
return false
}
return v == value
}
// parseCronRange 解析 "a-b" 范围，含边界校验与 weekday 7→0 归一化。
func parseCronRange(s string, min, max int) (int, int, error) {
parts := strings.SplitN(s, "-", 2)
if len(parts) != 2 {
return 0, 0, fmt.Errorf("invalid range %q", s)
}
lo, err1 := strconv.Atoi(strings.TrimSpace(parts[0]))
hi, err2 := strconv.Atoi(strings.TrimSpace(parts[1]))
if err1 != nil || err2 != nil {
return 0, 0, fmt.Errorf("invalid range %q", s)
}
isWeekday := min == 0 && max == 6
if isWeekday {
// 7 → 0（周日）。但若两端归一化后都为 0 而原始值不同（如 "0-7"/"7-0"），
// 语义为"整周"却坍缩成"仅周日"，属歧义范围，拒绝以免静默错误匹配。
nlo, nhi := lo, hi
if nlo == 7 {
nlo = 0
}
if nhi == 7 {
nhi = 0
}
if nlo == nhi && lo != hi {
return 0, 0, fmt.Errorf("ambiguous weekday range %q (0 与 7 均为周日)", s)
}
lo, hi = nlo, nhi
}
if lo < min || lo > max || hi < min || hi > max {
return 0, 0, fmt.Errorf("range out of bounds %q", s)
}
return lo, hi, nil
}
// ParseCron 解析完整 Cron 表达式。
// 格式: "分钟 小时 日 月 星期"
// 示例:
//
// "0 12 * * *" - 每天12:00
// "*/15 * * * *" - 每15分钟
// "0 9-17 * * 1-5" - 工作日9-17点每小时
// "0 0 1 * *" - 每月1号凌晨
// "0 0 * * 0" - 每周日凌晨
//
// 非法表达式会 panic（fail-fast），动态输入请用 ParseCronStrict 处理 error。
// 如需旧版“非法表达式回退为每分钟”的兼容语义，请显式使用 ParseCronOrDefault。
func ParseCron(expr string) *FullCronSchedule {
if sched, err := ParseCronStrict(expr); err == nil {
return sched
} else {
panic(err)
}
}
// ParseCronOrDefault parses a Cron expression and falls back to all "*" (every
// minute) when expr is invalid. Prefer ParseCronStrict or ParseCron for new
// code; this helper exists for callers that intentionally want legacy fallback
// semantics.
func ParseCronOrDefault(expr string) *FullCronSchedule {
if sched, err := ParseCronStrict(expr); err == nil {
return sched
}
return &FullCronSchedule{"*", "*", "*", "*", "*"}
}
// ParseCronStrict 严格解析 Cron 表达式，校验字段数与各字段范围，非法返 error。
// 字段范围：分钟 0-59，小时 0-23，日 1-31，月 1-12，星期 0-6（周日=0，7 归一为 0）。
func ParseCronStrict(expr string) (*FullCronSchedule, error) {
fields := strings.Fields(expr)
if len(fields) != 5 {
return nil, fmt.Errorf("cron: 需要 5 个字段，实际 %d", len(fields))
}
specs := []struct {
val string
min, max int
name string
}{
{fields[0], 0, 59, "minute"},
{fields[1], 0, 23, "hour"},
{fields[2], 1, 31, "day"},
{fields[3], 1, 12, "month"},
{fields[4], 0, 6, "weekday"},
}
for _, sp := range specs {
if err := validateCronField(sp.val, sp.min, sp.max, sp.name); err != nil {
return nil, err
}
}
return &FullCronSchedule{
Minute: fields[0],
Hour: fields[1],
Day: fields[2],
Month: fields[3],
Weekday: fields[4],
}, nil
}
// validateCronField 校验单个 cron 字段语法与范围。
func validateCronField(field string, min, max int, name string) error {
if field == "*" {
return nil
}
for _, raw := range strings.Split(field, ",") {
item := strings.TrimSpace(raw)
if item == "" {
return fmt.Errorf("cron %s: 空列表项", name)
}
if err := validateCronItem(item, min, max, name); err != nil {
return err
}
}
return nil
}
func validateCronItem(item string, min, max int, name string) error {
isWeekday := min == 0 && max == 6
norm := func(v int) int {
if isWeekday && v == 7 {
return 0
}
return v
}
if idx := strings.Index(item, "/"); idx >= 0 {
base := item[:idx]
step, err := strconv.Atoi(item[idx+1:])
if err != nil || step <= 0 {
return fmt.Errorf("cron %s: 非法步长 %q", name, item)
}
if base == "*" {
return nil
}
lo, hi, err := parseCronRange(base, min, max)
if err != nil {
return fmt.Errorf("cron %s: %v", name, err)
}
_ = lo
_ = hi
return nil
}
if strings.Contains(item, "-") {
if _, _, err := parseCronRange(item, min, max); err != nil {
return fmt.Errorf("cron %s: %v", name, err)
}
return nil
}
v, err := strconv.Atoi(item)
if err != nil {
return fmt.Errorf("cron %s: 非数字 %q", name, item)
}
if v = norm(v); v < min || v > max {
return fmt.Errorf("cron %s: %d 超出范围 [%d,%d]", name, v, min, max)
}
return nil
}
// CronSchedule 简化 Cron 调度（仅分钟和小时）
type CronSchedule struct {
Minute string // 分钟: "*" 或具体值如 "0,15,30"
Hour string // 小时: "*" 或具体值如 "8,12"
}
// Next 计算下次运行时间
func (s *CronSchedule) Next(now time.Time) time.Time {
for i := 1; i <= 60*24; i++ { // 最多查找24小时
next := now.Add(time.Duration(i) * time.Minute)
if s.matchMinute(next.Minute()) && s.matchHour(next.Hour()) {
return next
}
}
return time.Time{}
}
func (s *CronSchedule) matchMinute(minute int) bool {
return s.Minute == "*" || s.matchValue(s.Minute, minute)
}
func (s *CronSchedule) matchHour(hour int) bool {
return s.Hour == "*" || s.matchValue(s.Hour, hour)
}
func (s *CronSchedule) matchValue(pattern string, value int) bool {
for _, p := range splitPattern(pattern) {
if p == value {
return true
}
}
return false
}
// splitPattern 将逗号分隔的模式解析为值列表（C12e：用 strconv.Atoi，非法项跳过）。
func splitPattern(pattern string) []int {
var values []int
for _, p := range strings.Split(pattern, ",") {
v, err := strconv.Atoi(strings.TrimSpace(p))
if err != nil {
continue
}
values = append(values, v)
}
return values
}
// Cron 创建类 Cron 调度
func Cron(minute, hour string) *CronSchedule {
return &CronSchedule{Minute: minute, Hour: hour}
}
// 全局调度器。init 时预创建默认实例（与 storage.DefaultStorage / cache.defaultCachePtr
// 对齐），使 SwapDefaultScheduler 返回非 nil、App 回滚总能恢复一个有效默认。用 atomic.Pointer
// 保护并发读写，消除原 once+裸指针读写竞态。GetScheduler 仍保留懒初始化分支作防御。
var globalScheduler atomic.Pointer[Scheduler]
func init() {
globalScheduler.Store(NewScheduler())
}
// GetScheduler 获取全局调度器（并发安全；init 后通常非 nil，保留懒初始化作防御）。
func GetScheduler() *Scheduler {
if s := globalScheduler.Load(); s != nil {
return s
}
ns := NewScheduler()
if globalScheduler.CompareAndSwap(nil, ns) {
return ns
}
return globalScheduler.Load()
}
// SwapDefaultScheduler 将指定 Scheduler 置为全局默认，并返回被替换的旧调度器。
// 旧调度器不会被停止，供 App 初始化这类需要失败回滚的生命周期流程暂存（照
// database.SwapDefaultManager / SwapDefaultRedisManager 模式）。nil 被忽略，返回当前默认。
func SwapDefaultScheduler(s *Scheduler) *Scheduler {
if s == nil {
return globalScheduler.Load()
}
return globalScheduler.Swap(s)
}
// AddTask 添加任务到全局调度器
func AddTask(name string, schedule Schedule, handler TaskHandler) *Task {
return GetScheduler().AddTask(name, schedule, handler)
}
// Start 启动全局调度器
func Start() {
GetScheduler().Start()
}
// Stop 停止全局调度器（无限等待，见 Scheduler.Stop）。
func Stop() {
GetScheduler().Stop()
}
// StopGlobalWithTimeout 停止全局调度器并最多等待 timeout（P1 #10）。
// 全局调度器尚未创建时无操作返回 true，不会因此惰性创建它——供 App.Shutdown 安全调用。
func StopGlobalWithTimeout(timeout time.Duration) bool {
if s := globalScheduler.Load(); s != nil {
return s.StopWithTimeout(timeout)
}
return true
}
cron/cron_c12_internal_test.go
+190
View File
@@ -0,0 +1,190 @@
package cron
import (
"context"
"sync/atomic"
"testing"
"time"
)
// stepSchedule 是一个固定步长调度，Next(now)=now+step，用于确定性测试 C12c 锚定。
type stepSchedule struct{ step time.Duration }
func (s stepSchedule) Next(now time.Time) time.Time { return now.Add(s.step) }
// TestC12bNoOverlapManualDrive 验证 per-task running 守卫防止重叠执行。
//
// 修复前：checkAndRun 无 running 守卫，handler 未完成时下一次 checkAndRun（NextRun 仍为过去）
// 会再次 spawn 同一任务，并发执行。
// 手动驱动两轮 checkAndRun，handler 阻塞至释放——修复后第二轮被 running 守卫拦截，仅 1 次 spawn。
func TestC12bNoOverlapManualDrive(t *testing.T) {
s := NewScheduler()
var started int32
release := make(chan struct{})
task := s.AddTask("block", stepSchedule{step: time.Microsecond}, func(ctx context.Context) error {
atomic.AddInt32(&started, 1)
<-release
return nil
})
task.NextRun = time.Now().Add(-time.Hour) // 过去 → 到期
s.checkAndRun() // 第一轮：spawn，handler 阻塞
for atomic.LoadInt32(&started) == 0 {
time.Sleep(time.Millisecond)
}
s.checkAndRun() // 第二轮：修复后 running 守卫拦截，不再 spawn
time.Sleep(50 * time.Millisecond) // 给潜在二次 spawn 启动时间
if n := atomic.LoadInt32(&started); n != 1 {
t.Errorf("task overlapped: started = %d, want 1 (C12b)", n)
}
close(release)
deadline := time.Now().Add(2 * time.Second)
for task.running != nil && task.running.Load() {
if time.Now().After(deadline) {
t.Fatalf("running guard never released")
}
time.Sleep(time.Millisecond)
}
}
// TestC12cNextRunAnchoredOnPrevious 验证 NextRun 以上次 NextRun 锚定（不漂移）。
//
// 修复前：NextRun = schedule.Next(time.Now())（handler 完成后的 now），每周期累积 handler 时长。
// 修复后：NextRun = schedule.Next(task.NextRun)（上次计划时间锚定）。
//
// 将 NextRun 设到过去的固定锚点 T0，手动驱动 3 轮 checkAndRun（每轮等 handler 完成），
// 断言 NextRun == T0 + 3*step（锚定）。漂移实现下 NextRun ≈ now+step（远大于 T0+3*step）。
func TestC12cNextRunAnchoredOnPrevious(t *testing.T) {
s := NewScheduler()
step := 100 * time.Millisecond
done := make(chan struct{}, 16)
task := s.AddTask("anchored", stepSchedule{step: step}, func(ctx context.Context) error {
// 模拟 handler 耗时——修复后不应影响 NextRun 锚定。
time.Sleep(50 * time.Millisecond)
done <- struct{}{}
return nil
})
// 将 NextRun 设到过去的固定锚点 T0（远早于 now，确保每轮都到期触发）。
T0 := time.Now().Add(-10 * time.Second)
task.NextRun = T0
for i := 1; i <= 3; i++ {
s.checkAndRun()
// 等 handler 执行；若 NextRun 未锚定（漂移实现下 NextRun 跳到未来，
// 后续 checkAndRun 不再到期），done 不会收到 → 超时明确失败而非挂起。
select {
case <-done:
case <-time.After(2 * time.Second):
t.Fatalf("iter %d: handler did not fire (NextRun drifted to future, not anchored on previous) (C12c)", i)
}
// 等 running 守卫释放（defer 在 handler 返回后置 false）。
deadline := time.Now().Add(2 * time.Second)
for task.running != nil && task.running.Load() {
if time.Now().After(deadline) {
t.Fatalf("running guard never released (iter %d)", i)
}
time.Sleep(time.Millisecond)
}
}
got := task.NextRun
want := T0.Add(3 * step)
if diff := got.Sub(want); diff < -5*time.Millisecond || diff > 5*time.Millisecond {
t.Errorf("NextRun not anchored on previous: got %v, want %v (diff %v, C12c drift)", got, want, diff)
}
}
// C12e 直接测试 matchField（未导出，故 internal test）。
//
// 修复前：matchField 先判 `-` 把整字段当范围，parseInt 忽略非数字逐位累积：
// - "1-5,8" 含 `-` → parseInt("5,8")=58 → 范围 1..58 全匹配，列表项 8 丢失。
// - "garbage" → parseInt=0，value=0 误触发。
// - "*/garbage" → step=0 → return true 匹配全部。
var schedForMatch = &FullCronSchedule{}
func TestC12eMatchFieldListAndRangeIndependent(t *testing.T) {
// "1-5,8" 仅匹配 1,2,3,4,5,8。
for _, v := range []int{1, 2, 3, 4, 5, 8} {
if !schedForMatch.matchField("1-5,8", v, 0, 59) {
t.Errorf("1-5,8 should match %d (C12e)", v)
}
}
for _, v := range []int{0, 6, 7, 9, 30, 58} {
if schedForMatch.matchField("1-5,8", v, 0, 59) {
t.Errorf("1-5,8 should NOT match %d (C12e range broken to 1..58)", v)
}
}
}
func TestC12eMatchFieldGarbageNotMatch(t *testing.T) {
for v := 0; v <= 59; v++ {
if schedForMatch.matchField("garbage", v, 0, 59) {
t.Errorf("garbage should not match any value, matched %d (C12e)", v)
}
}
}
func TestC12eMatchFieldStarSlashGarbageNotMatchAll(t *testing.T) {
// 修复前 step=0 → return true 匹配全部。
matched := 0
for v := 0; v <= 59; v++ {
if schedForMatch.matchField("*/garbage", v, 0, 59) {
matched++
}
}
if matched != 0 {
t.Errorf("*/garbage should match nothing, matched %d (C12e step=0 bug)", matched)
}
}
func TestC12eMatchFieldWeekday7IsSunday(t *testing.T) {
// weekday 字段 7 → 0（周日）。
if !schedForMatch.matchField("7", 0, 0, 6) {
t.Error("weekday 7 should match Sunday(0) (C12e)")
}
if schedForMatch.matchField("7", 7, 0, 6) {
t.Error("weekday 7 should not match value 7 (out of range after normalize)")
}
}
func TestC12eMatchFieldRangeAndStepAndList(t *testing.T) {
// 范围 9-17。
for _, v := range []int{9, 12, 17} {
if !schedForMatch.matchField("9-17", v, 0, 23) {
t.Errorf("9-17 should match %d", v)
}
}
for _, v := range []int{8, 18} {
if schedForMatch.matchField("9-17", v, 0, 23) {
t.Errorf("9-17 should NOT match %d", v)
}
}
// 步长 */15。
for _, v := range []int{0, 15, 30, 45} {
if !schedForMatch.matchField("*/15", v, 0, 59) {
t.Errorf("*/15 should match %d", v)
}
}
for _, v := range []int{1, 7, 16} {
if schedForMatch.matchField("*/15", v, 0, 59) {
t.Errorf("*/15 should NOT match %d", v)
}
}
// 范围步长 9-17/2 → 9,11,13,15,17。
for _, v := range []int{9, 11, 13, 15, 17} {
if !schedForMatch.matchField("9-17/2", v, 0, 23) {
t.Errorf("9-17/2 should match %d", v)
}
}
for _, v := range []int{10, 12, 14, 16} {
if schedForMatch.matchField("9-17/2", v, 0, 23) {
t.Errorf("9-17/2 should NOT match %d", v)
}
}
}
cron/cron_c12_test.go
+321
View File
@@ -0,0 +1,321 @@
package cron_test
import (
"context"
"sync"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/cron"
)
// ============================================================
// C12a：runTask 计数写入无锁 + GetTask/ListTasks 返回 live 指针 → data race
// ============================================================
// TestC12aConcurrentReadWriteNoRace 验证并发 RunTask/GetTask/ListTasks + 调度运行
// 无数据竞争（-race）。
//
// 修复前：runTask 无锁写 LastRun/RunCount，GetTask/ListTasks 返回 live 指针并发读 →
// -race 必采到 DATA RACE。修复后：写入纳入锁、Getter 返回拷贝。
func TestC12aConcurrentReadWriteNoRace(t *testing.T) {
scheduler := cron.NewScheduler()
scheduler.AddTask("t1", cron.Every(50*time.Millisecond), func(ctx context.Context) error {
return nil
})
scheduler.AddTask("t2", cron.Every(80*time.Millisecond), func(ctx context.Context) error {
return nil
})
scheduler.Start()
t.Cleanup(scheduler.Stop)
stop := make(chan struct{})
var wg sync.WaitGroup
for i := 0; i < 4; i++ {
wg.Add(1)
go func() {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
// 读取返回拷贝的字段——若写侧无锁，与此处读竞争（C12a）。
if g, err := scheduler.GetTask("t1"); err == nil {
_ = g.RunCount
_ = g.LastRun
}
for _, tk := range scheduler.ListTasks() {
_ = tk.RunCount
_ = tk.LastRun
}
}
}()
}
wg.Add(1)
go func() {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
_ = scheduler.RunTask("t2")
}
}()
time.Sleep(300 * time.Millisecond)
close(stop)
wg.Wait()
}
// TestC12aGetTaskReturnsCopy 验证 GetTask 返回拷贝，修改返回值不影响内部状态。
func TestC12aGetTaskReturnsCopy(t *testing.T) {
scheduler := cron.NewScheduler()
scheduler.AddTask("t", cron.Every(time.Minute), func(ctx context.Context) error {
return nil
})
got, err := scheduler.GetTask("t")
if err != nil {
t.Fatalf("GetTask: %v", err)
}
got.RunCount = 9999
got.Enabled = false
again, _ := scheduler.GetTask("t")
if again.RunCount == 9999 {
t.Error("GetTask returned live pointer (RunCount mutated internally)")
}
if !again.Enabled {
t.Error("GetTask returned live pointer (Enabled mutated internally)")
}
}
// TestC12aListTasksReturnsCopies 验证 ListTasks 元素为拷贝。
func TestC12aListTasksReturnsCopies(t *testing.T) {
scheduler := cron.NewScheduler()
scheduler.AddTask("t", cron.Every(time.Minute), func(ctx context.Context) error {
return nil
})
list := scheduler.ListTasks()
list[0].RunCount = 777
again := scheduler.ListTasks()
if again[0].RunCount == 777 {
t.Error("ListTasks returned live pointer (RunCount mutated internally)")
}
}
// ============================================================
// C12b：长任务跨 tick 重叠执行
// ============================================================
// TestC12bRunTaskConcurrentManualTriggerReturnsError 验证手动 RunTask 占用守卫期间，
// 再次 RunTask 返"任务正在执行中"错误。
func TestC12bRunTaskConcurrentManualTriggerReturnsError(t *testing.T) {
scheduler := cron.NewScheduler()
started := make(chan struct{})
release := make(chan struct{})
scheduler.AddTask("block", cron.Every(time.Hour), func(ctx context.Context) error {
close(started)
<-release
return nil
})
var firstErr error
var wg sync.WaitGroup
wg.Add(1)
go func() {
defer wg.Done()
firstErr = scheduler.RunTask("block")
}()
<-started
secondErr := scheduler.RunTask("block")
if secondErr == nil {
t.Error("second RunTask should fail while first is running (C12b running guard)")
}
close(release)
wg.Wait()
if firstErr != nil {
t.Errorf("first RunTask error: %v", firstErr)
}
}
// ============================================================
// C12d：Weekly 当天未到点目标被跳一周
// ============================================================
func TestC12dWeeklySameDayBeforeTarget(t *testing.T) {
schedule := cron.WeeklySchedule{Day: time.Monday, Hour: 9, Minute: 0}
// 周一 8:00（目标 9:00 未到）→ 应返回本周一 9:00，不跳周。
now := time.Date(2026, 6, 29, 8, 0, 0, 0, time.UTC) // 2026-06-29 是周一
if now.Weekday() != time.Monday {
t.Fatalf("test fixture: expected Monday, got %v", now.Weekday())
}
next := schedule.Next(now)
want := time.Date(2026, 6, 29, 9, 0, 0, 0, time.UTC)
if !next.Equal(want) {
t.Errorf("Weekly same-day-before-target: got %v, want %v (C12d skip-week bug)", next, want)
}
}
func TestC12dWeeklySameDayAfterTarget(t *testing.T) {
schedule := cron.WeeklySchedule{Day: time.Monday, Hour: 9, Minute: 0}
// 周一 10:00（目标 9:00 已过）→ 下周一 9:00。
now := time.Date(2026, 6, 29, 10, 0, 0, 0, time.UTC)
next := schedule.Next(now)
want := time.Date(2026, 7, 6, 9, 0, 0, 0, time.UTC)
if !next.Equal(want) {
t.Errorf("Weekly same-day-after-target: got %v, want %v", next, want)
}
}
func TestC12dWeeklyCrossWeek(t *testing.T) {
schedule := cron.WeeklySchedule{Day: time.Monday, Hour: 9, Minute: 0}
// 周三 → 下周一。
now := time.Date(2026, 7, 1, 12, 0, 0, 0, time.UTC) // 周三
if now.Weekday() != time.Wednesday {
t.Fatalf("test fixture: expected Wednesday, got %v", now.Weekday())
}
next := schedule.Next(now)
want := time.Date(2026, 7, 6, 9, 0, 0, 0, time.UTC)
if !next.Equal(want) {
t.Errorf("Weekly cross-week: got %v, want %v", next, want)
}
}
// ============================================================
// C12e：cron 解析缺陷（周日 7 / 范围环绕 / 严格解析）
// （1-5,8 / garbage / */garbage 的 matchField 直接测试见 cron_c12_internal_test.go）
// ============================================================
func TestC12eWeekdaySundayAs7(t *testing.T) {
schedule := cron.FullCronSchedule{
Minute: "0",
Hour: "0",
Day: "*",
Month: "*",
Weekday: "7",
}
// 0 0 * * 7 → 每周日凌晨。从周六 23:00 找下一个匹配应落周日 00:00。
now := time.Date(2026, 6, 27, 23, 0, 0, 0, time.UTC) // 周六
if now.Weekday() != time.Saturday {
t.Fatalf("test fixture: expected Saturday, got %v", now.Weekday())
}
next := schedule.Next(now)
if next.Weekday() != time.Sunday {
t.Errorf("0 0 * * 7 should land on Sunday, got %v (C12e 7≠Sunday)", next.Weekday())
}
if next.Hour() != 0 || next.Minute() != 0 {
t.Errorf("0 0 * * 7 should land on 00:00, got %v", next)
}
}
func TestC12eWeekdayRangeWraparound(t *testing.T) {
// "6-1" 在 weekday 环绕：周六(6)、周日(0)、周一(1)。
schedule := cron.FullCronSchedule{
Minute: "0",
Hour: "0",
Day: "*",
Month: "*",
Weekday: "6-1",
}
for _, w := range []time.Weekday{time.Saturday, time.Sunday, time.Monday} {
tt := time.Date(2026, 6, 29, 0, 0, 0, 0, time.UTC) // 周一
for tt.Weekday() != w {
tt = tt.AddDate(0, 0, 1)
}
next := schedule.Next(tt.Add(-1 * time.Minute))
if next.Weekday() != w {
t.Errorf("6-1 should match %v, got %v", w, next.Weekday())
}
}
// 周二不应被 6-1 匹配，下一个应是周六。
tt := time.Date(2026, 6, 30, 0, 0, 0, 0, time.UTC) // 周二
if tt.Weekday() != time.Tuesday {
t.Fatalf("test fixture: expected Tuesday, got %v", tt.Weekday())
}
next := schedule.Next(tt.Add(-1 * time.Minute))
if next.Weekday() != time.Saturday {
t.Errorf("6-1 should skip Tuesday, next match %v, want Saturday", next.Weekday())
}
}
// TestC12eParseCronStrict 验证严格解析。
func TestC12eParseCronStrict(t *testing.T) {
cases := []struct {
expr string
ok bool
}{
{"0 12 * * *", true},
{"*/15 * * * *", true},
{"0 9-17 * * 1-5", true},
{"0 0 1 * 7", true}, // 周日 7 合法
{"0 0 * * 0-7", false},
{"invalid", false},
{"1-5,8 0 * * *", true},
{"60 0 * * *", false}, // 分钟越界
{"0 25 * * *", false}, // 小时越界
{"0 0 0 * *", false}, // 日越界
{"0 0 * 13 *", false}, // 月越界
{"0 0 * * 9", false}, // 周越界
{"garbage 0 * * *", false},
{"*/0 * * * *", false}, // step=0 非法
}
for _, c := range cases {
_, err := cron.ParseCronStrict(c.expr)
if c.ok && err != nil {
t.Errorf("ParseCronStrict(%q) unexpected error: %v", c.expr, err)
}
if !c.ok && err == nil {
t.Errorf("ParseCronStrict(%q) expected error, got nil", c.expr)
}
}
}
// TestC12eParseCronFallback verifies ParseCron now fails fast on invalid input.
func TestC12eParseCronFallback(t *testing.T) {
defer func() {
if recover() == nil {
t.Fatal("ParseCron(invalid) should panic")
}
}()
_ = cron.ParseCron("invalid")
}
func TestC12eParseCronOrDefaultFallback(t *testing.T) {
s := cron.ParseCronOrDefault("invalid")
if s.Minute != "*" || s.Hour != "*" || s.Day != "*" || s.Month != "*" || s.Weekday != "*" {
t.Errorf("ParseCronOrDefault(invalid) should fall back to all-*, got %+v", s)
}
// 合法表达式不回退。
s = cron.ParseCron("1-5,8 0 * * *")
if s.Minute != "1-5,8" {
t.Errorf("ParseCron valid: Minute = %q, want 1-5,8", s.Minute)
}
}
// TestC12eCronScheduleGarbageNoMatch 验证简化 Cron 不再 parseInt 容错为 0。
func TestC12eCronScheduleGarbageNoMatch(t *testing.T) {
bad := cron.CronSchedule{Minute: "garbage", Hour: "9"}
// garbage → splitPattern 返空 → matchMinute 返 false → 24h 内无匹配。
now := time.Date(2026, 6, 29, 8, 0, 0, 0, time.UTC)
next := bad.Next(now)
if !next.IsZero() {
t.Errorf("CronSchedule garbage minute should not match, got next=%v (C12e)", next)
}
}
cron/cron_m13_internal_test.go
+168
View File
@@ -0,0 +1,168 @@
package cron
import (
"context"
"errors"
"strings"
"sync/atomic"
"testing"
"time"
)
func mustPanicM13(t *testing.T, name string, fn func()) {
t.Helper()
defer func() {
if recover() == nil {
t.Fatalf("%s should panic", name)
}
}()
fn()
}
// TestCronRunTaskPanicRecovered_M13 回归：RunTask handler panic 时，executeTask 边界
// recover 转为 error 返回调用方并记入 LastError，不崩进程；running 守卫随后释放。
// 修复前：panic 直接上抛 → 测试进程崩溃。
func TestCronRunTaskPanicRecovered_M13(t *testing.T) {
s := NewScheduler()
s.AddTask("panic", Every(time.Minute), func(context.Context) error { panic("boom") })
err := s.RunTask("panic")
if err == nil || !strings.Contains(err.Error(), "panic recovered") {
t.Fatalf("RunTask err = %v, want a panic-recovered error", err)
}
got, _ := s.GetTask("panic")
if got.LastError == nil || !strings.Contains(got.LastError.Error(), "panic recovered") {
t.Fatalf("LastError = %v, want panic-recovered error", got.LastError)
}
// running 守卫必须已释放：再次 RunTask 不应返“任务正在执行中”（会再次 panic→recover）。
err2 := s.RunTask("panic")
if err2 != nil && strings.Contains(err2.Error(), "任务正在执行中") {
t.Fatal("running guard not released after panic (second RunTask blocked)")
}
}
// TestCronRunTaskRecordsLastError_M13 回归：RunTask 手动路径此前只更 LastRun/RunCount，
// 不记 LastError。修复后与调度路径一致，正常 error 也记入 LastError。
func TestCronRunTaskRecordsLastError_M13(t *testing.T) {
s := NewScheduler()
sentinel := errors.New("sentinel fail")
s.AddTask("err", Every(time.Minute), func(context.Context) error { return sentinel })
err := s.RunTask("err")
if !errors.Is(err, sentinel) {
t.Fatalf("RunTask err = %v, want sentinel", err)
}
got, _ := s.GetTask("err")
if !errors.Is(got.LastError, sentinel) {
t.Fatalf("LastError = %v, want sentinel", got.LastError)
}
if got.RunCount != 1 {
t.Fatalf("RunCount = %d, want 1", got.RunCount)
}
}
// TestCronCheckAndRunPanicRecovered_M13 回归：调度 goroutine 内 handler panic 时，
// recover 防止进程崩溃；同 tick 派生的兄弟 goroutine 不受影响；无 goroutine 泄漏。
// 同包测试直接驱动 checkAndRun + wg.Wait，零 sleep、确定性。
// 修复前：派生 goroutine 内未 recover 的 panic 终止测试进程。
func TestCronCheckAndRunPanicRecovered_M13(t *testing.T) {
s := NewScheduler()
var ran atomic.Int32
s.AddTask("panic", Every(time.Millisecond), func(context.Context) error { panic("boom") })
s.AddTask("canary", Every(time.Millisecond), func(context.Context) error {
ran.Add(1)
return nil
})
// AddTask 设 NextRun=now+1ms；手动改到过去确保两者 due，跨过 1s ticker 的不确定性。
s.mu.Lock()
s.tasks["panic"].NextRun = time.Now().Add(-time.Second)
s.tasks["canary"].NextRun = time.Now().Add(-time.Second)
s.mu.Unlock()
s.checkAndRun()
s.wg.Wait() // 等派生的两个 goroutine 退出，证无泄漏
pt, _ := s.GetTask("panic")
if pt.LastError == nil || !strings.Contains(pt.LastError.Error(), "panic recovered") {
t.Fatalf("panic task LastError = %v, want panic-recovered error", pt.LastError)
}
if ran.Load() == 0 {
t.Fatal("canary did not run — sibling goroutine killed by panic?")
}
}
func TestCronAddTaskRejectsNilScheduleOrHandler_M13(t *testing.T) {
s := NewScheduler()
mustPanicM13(t, "nil schedule", func() {
s.AddTask("nil-schedule", nil, func(context.Context) error { return nil })
})
mustPanicM13(t, "nil handler", func() {
s.AddTask("nil-handler", Every(time.Minute), nil)
})
}
func TestCronScheduleConstructorsRejectInvalidBounds_M13(t *testing.T) {
mustPanicM13(t, "Every(0)", func() { Every(0) })
mustPanicM13(t, "Every(negative)", func() { Every(-time.Second) })
mustPanicM13(t, "Daily hour", func() { Daily(24, 0) })
mustPanicM13(t, "Daily minute", func() { Daily(23, 60) })
mustPanicM13(t, "Weekly day", func() { Weekly(time.Weekday(9), 9, 0) })
mustPanicM13(t, "Weekly hour", func() { Weekly(time.Monday, -1, 0) })
mustPanicM13(t, "Weekly minute", func() { Weekly(time.Monday, 9, -1) })
}
func TestCronAddTaskRejectsInvalidExportedScheduleValues_M13(t *testing.T) {
s := NewScheduler()
mustPanicM13(t, "invalid interval schedule", func() {
s.AddTask("bad-interval", &IntervalSchedule{}, func(context.Context) error { return nil })
})
mustPanicM13(t, "invalid daily schedule", func() {
s.AddTask("bad-daily", &DailySchedule{Hour: 99}, func(context.Context) error { return nil })
})
mustPanicM13(t, "invalid weekly schedule", func() {
s.AddTask("bad-weekly", &WeeklySchedule{Day: time.Weekday(8)}, func(context.Context) error { return nil })
})
}
func TestCronStartAfterStopRebuildsContext_M13(t *testing.T) {
s := NewScheduler()
s.AddTask("ctx", Every(time.Hour), func(ctx context.Context) error {
return ctx.Err()
})
s.Start()
s.Stop()
s.Start()
t.Cleanup(s.Stop)
if err := s.RunTask("ctx"); err != nil {
t.Fatalf("RunTask after Stop/Start got ctx err = %v, want nil", err)
}
}
func TestCronCheckAndRunSkipsAfterStopContextCanceled_M13(t *testing.T) {
s := NewScheduler()
var ran atomic.Int32
s.AddTask("due", Every(time.Minute), func(context.Context) error {
ran.Add(1)
return nil
})
ctx, cancel := context.WithCancel(context.Background())
cancel()
s.mu.Lock()
s.running = false
s.tasks["due"].NextRun = time.Now().Add(-time.Second)
s.mu.Unlock()
s.checkAndRun(ctx)
s.wg.Wait()
if got := ran.Load(); got != 0 {
t.Fatalf("task ran %d times after stopped/canceled ctx, want 0", got)
}
}
cron/cron_test.go
+268
View File
@@ -0,0 +1,268 @@
package cron_test
import (
"context"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/cron"
)
func TestTask(t *testing.T) {
task := cron.Task{
Name: "test_task",
Enabled: true,
RunCount: 0,
}
if task.Name != "test_task" {
t.Error("Task Name failed")
}
if !task.Enabled {
t.Error("Task Enabled failed")
}
}
func TestNewScheduler(t *testing.T) {
scheduler := cron.NewScheduler()
if scheduler == nil {
t.Error("NewScheduler should not return nil")
}
}
func TestAddTask(t *testing.T) {
scheduler := cron.NewScheduler()
task := scheduler.AddTask("test", cron.Every(time.Minute), func(ctx context.Context) error {
return nil
})
if task == nil {
t.Error("AddTask should return task")
}
if task.Name != "test" {
t.Errorf("Task name = %s, want test", task.Name)
}
}
func TestRemoveTask(t *testing.T) {
scheduler := cron.NewScheduler()
scheduler.AddTask("test", cron.Every(time.Minute), func(ctx context.Context) error {
return nil
})
scheduler.RemoveTask("test")
task, err := scheduler.GetTask("test")
if err == nil {
t.Error("RemoveTask should remove task")
}
if task != nil {
t.Error("Removed task should be nil")
}
}
func TestEnableDisableTask(t *testing.T) {
scheduler := cron.NewScheduler()
scheduler.AddTask("test", cron.Every(time.Minute), func(ctx context.Context) error {
return nil
})
err := scheduler.DisableTask("test")
if err != nil {
t.Errorf("DisableTask error: %v", err)
}
task, _ := scheduler.GetTask("test")
if task.Enabled {
t.Error("Task should be disabled")
}
err = scheduler.EnableTask("test")
if err != nil {
t.Errorf("EnableTask error: %v", err)
}
task, _ = scheduler.GetTask("test")
if !task.Enabled {
t.Error("Task should be enabled")
}
}
func TestListTasks(t *testing.T) {
scheduler := cron.NewScheduler()
scheduler.AddTask("task1", cron.Every(time.Minute), func(ctx context.Context) error { return nil })
scheduler.AddTask("task2", cron.Every(time.Hour), func(ctx context.Context) error { return nil })
tasks := scheduler.ListTasks()
if len(tasks) != 2 {
t.Errorf("ListTasks length = %d, want 2", len(tasks))
}
}
func TestIntervalSchedule(t *testing.T) {
schedule := cron.IntervalSchedule{Interval: time.Minute}
now := time.Now()
next := schedule.Next(now)
if next.Before(now) {
t.Error("Next should be after now")
}
}
func TestEvery(t *testing.T) {
schedule := cron.Every(5 * time.Minute)
if schedule.Interval != 5*time.Minute {
t.Errorf("Every interval = %v, want 5m", schedule.Interval)
}
}
func TestDailySchedule(t *testing.T) {
schedule := cron.DailySchedule{Hour: 9, Minute: 30}
now := time.Now()
next := schedule.Next(now)
if next.Hour() != 9 || next.Minute() != 30 {
t.Errorf("DailySchedule next = %v, want 09:30", next)
}
}
func TestDaily(t *testing.T) {
schedule := cron.Daily(10, 0)
if schedule.Hour != 10 || schedule.Minute != 0 {
t.Error("Daily failed")
}
}
func TestWeeklySchedule(t *testing.T) {
schedule := cron.WeeklySchedule{Day: time.Monday, Hour: 9, Minute: 0}
now := time.Now()
next := schedule.Next(now)
if next.Hour() != 9 {
t.Errorf("WeeklySchedule hour = %d, want 9", next.Hour())
}
}
func TestWeekly(t *testing.T) {
schedule := cron.Weekly(time.Monday, 10, 0)
if schedule.Day != time.Monday {
t.Error("Weekly Day failed")
}
}
func TestCronSchedule(t *testing.T) {
schedule := cron.CronSchedule{Minute: "0,15,30", Hour: "9"}
now := time.Now()
next := schedule.Next(now)
if next.IsZero() {
t.Error("CronSchedule should find next time")
}
}
func TestCron(t *testing.T) {
schedule := cron.Cron("0", "9")
if schedule.Minute != "0" || schedule.Hour != "9" {
t.Error("Cron failed")
}
}
func TestGetScheduler(t *testing.T) {
scheduler := cron.GetScheduler()
if scheduler == nil {
t.Error("GetScheduler should not return nil")
}
}
func TestGlobalAddTask(t *testing.T) {
task := cron.AddTask("global_test", cron.Every(time.Hour), func(ctx context.Context) error {
return nil
})
if task == nil {
t.Error("Global AddTask should return task")
}
}
func TestTaskHandler(t *testing.T) {
var handler cron.TaskHandler = func(ctx context.Context) error {
return nil
}
if handler == nil {
t.Error("TaskHandler should not be nil")
}
}
func TestFullCronSchedule(t *testing.T) {
// 测试每15分钟
schedule := cron.ParseCron("*/15 * * * *")
now := time.Now()
next := schedule.Next(now)
if next.IsZero() {
t.Error("FullCronSchedule */15 should find next time")
}
// 验证分钟是0,15,30,45之一
minute := next.Minute()
if minute%15 != 0 {
t.Errorf("FullCronSchedule minute = %d, should be divisible by 15", minute)
}
// 测试每天12点
schedule = cron.ParseCron("0 12 * * *")
next = schedule.Next(now)
if next.IsZero() {
t.Error("FullCronSchedule daily noon should find next time")
}
if next.Hour() != 12 || next.Minute() != 0 {
t.Errorf("FullCronSchedule noon = %v, want 12:00", next)
}
// 测试工作日9-17点
schedule = cron.ParseCron("0 9-17 * * 1-5")
next = schedule.Next(now)
if next.IsZero() {
t.Error("FullCronSchedule workday should find next time")
}
}
func TestParseCron(t *testing.T) {
// 正常5字段表达式
schedule := cron.ParseCron("0 12 * * *")
if schedule.Minute != "0" || schedule.Hour != "12" {
t.Error("ParseCron 5 fields failed")
}
// 无效表达式返回默认
func() {
defer func() {
if recover() == nil {
t.Fatal("ParseCron invalid should panic")
}
}()
_ = cron.ParseCron("invalid")
}()
}
func TestFullCronScheduleMatch(t *testing.T) {
schedule := cron.FullCronSchedule{
Minute: "*/5",
Hour: "*",
Day: "*",
Month: "*",
Weekday: "*",
}
// 测试匹配 - 通过Next验证
testTime := time.Date(2024, 1, 15, 10, 0, 0, 0, time.UTC)
next := schedule.Next(testTime)
// 10:00 下一个应该是 10:05
if next.Minute() != 5 || next.Hour() != 10 {
t.Errorf("Next after 10:00 should be 10:05, got %v", next)
}
testTime = time.Date(2024, 1, 15, 10, 7, 0, 0, time.UTC)
next = schedule.Next(testTime)
// 10:07 下一个应该是 10:10
if next.Minute() != 10 || next.Hour() != 10 {
t.Errorf("Next after 10:07 should be 10:10, got %v", next)
}
}
database/dialect.go
+184
View File
@@ -0,0 +1,184 @@
package database
import (
"errors"
"fmt"
"strings"
"sync"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/logger"
"gorm.io/driver/mysql"
"gorm.io/driver/postgres"
"gorm.io/gorm"
"gorm.io/gorm/clause"
"gorm.io/gorm/schema"
)
// 内置驱动常量（更多驱动可通过 RegisterDialect 扩展）
const (
DriverMySQL = config.DriverMySQL
DriverPostgres = config.DriverPostgres
)
// DialectorFactory 根据 DSN 返回 GORM Dialector
type DialectorFactory func(dsn string) gorm.Dialector
// DialectSpec 描述一种数据库方言：如何建立连接 + 如何拼接 DSN
type DialectSpec struct {
// Name 驱动主名称（如 "mysql"、"postgres"、"sqlite"），大小写不敏感
Name string
// Aliases 驱动别名（如 postgres 的 "postgresql"、"pg"）
Aliases []string
// Dialector 由 DSN 构造 GORM Dialector
Dialector DialectorFactory
// DSN 由 DatabaseConfig 拼接连接字符串。可选。
// 不提供时仅 CustomDSN 能直接生效；需要由配置字段拼接连接串的自定义驱动应显式提供该函数。
DSN config.DSNBuilder
}
var (
dialectsMu sync.RWMutex
dialects = map[string]DialectorFactory{}
)
// RegisterDialect 注册一种数据库方言。
// 同时把 DSN 构建器登记到 config 包，使 cfg.Database.DSN() 也能识别新驱动。
// 已注册的同名驱动会被覆盖。
//
// 用法示例（接入 SQLite）：
//
// import "gorm.io/driver/sqlite"
//
// database.RegisterDialect(database.DialectSpec{
// Name: "sqlite",
// Dialector: func(dsn string) gorm.Dialector { return sqlite.Open(dsn) },
// DSN: func(c *config.DatabaseConfig) string { return c.Name }, // 文件路径
// })
func RegisterDialect(spec DialectSpec) {
if spec.Dialector == nil || strings.TrimSpace(spec.Name) == "" {
return
}
dialectsMu.Lock()
for _, n := range append([]string{spec.Name}, spec.Aliases...) {
key := normalizeDriver(n)
if key != "" {
dialects[key] = spec.Dialector
}
}
dialectsMu.Unlock()
if spec.DSN != nil {
config.RegisterDSNBuilder(spec.Name, spec.DSN, spec.Aliases...)
}
}
// LookupDialect 查找已注册的 Dialector 工厂
func LookupDialect(driver string) (DialectorFactory, bool) {
key := normalizeDriver(driver)
dialectsMu.RLock()
defer dialectsMu.RUnlock()
f, ok := dialects[key]
return f, ok
}
// RegisteredDialects 返回所有已注册的驱动名（用于诊断）
func RegisteredDialects() []string {
dialectsMu.RLock()
defer dialectsMu.RUnlock()
names := make([]string, 0, len(dialects))
for k := range dialects {
names = append(names, k)
}
return names
}
// Dialector 根据配置返回 GORM Dialector。
// 驱动由 cfg.Database.Driver 决定；未指定时默认 MySQL，非空但未注册时返回会初始化失败的
// Dialector，避免拼写错误静默回退到 MySQL。
func Dialector(cfg *config.Config) gorm.Dialector {
if cfg == nil {
logger.Warn("database: 配置为空，回退到 MySQL 空 DSN")
return mysql.Open("")
}
return dialectorForDSN(cfg.Database.Driver, cfg.Database.DSN())
}
// dialectorForDSN 根据驱动名和 DSN 返回 Dialector
func dialectorForDSN(driver, dsn string) gorm.Dialector {
normalized := normalizeDriver(driver)
if normalized == "" {
normalized = DriverMySQL
}
if f, ok := LookupDialect(normalized); ok {
return f(dsn)
}
logger.Warnf("database: 驱动 %q 未注册（已注册: %s），拒绝静默回退到 MySQL；请修正配置或先注册方言",
normalized, strings.Join(RegisteredDialects(), ", "))
return errorDialector{
name: "invalid",
err: fmt.Errorf("数据库驱动未注册: %s", normalized),
}
}
type errorDialector struct {
name string
err error
}
func (d errorDialector) Name() string { return d.name }
func (d errorDialector) Initialize(*gorm.DB) error {
if d.err == nil {
return errors.New("数据库驱动未注册")
}
return d.err
}
func (d errorDialector) Migrator(*gorm.DB) gorm.Migrator { return nil }
func (d errorDialector) DataTypeOf(*schema.Field) string { return "" }
func (d errorDialector) DefaultValueOf(*schema.Field) clause.Expression { return nil }
func (d errorDialector) BindVarTo(clause.Writer, *gorm.Statement, any) {}
func (d errorDialector) QuoteTo(writer clause.Writer, str string) {
_, _ = writer.WriteString(str)
}
func (d errorDialector) Explain(sql string, _ ...any) string { return sql }
// normalizeDriver 规范化驱动名（小写、去空白）
func normalizeDriver(name string) string {
return strings.ToLower(strings.TrimSpace(name))
}
// driverDescription 返回带别名提示的驱动描述（用于错误信息和日志）
func driverDescription(driver string) string {
key := normalizeDriver(driver)
if key == "" {
return DriverMySQL + " (default)"
}
if _, ok := LookupDialect(key); ok {
return key
}
return fmt.Sprintf("%s (unregistered)", key)
}
func init() {
// 内置 MySQL
RegisterDialect(DialectSpec{
Name: DriverMySQL,
Dialector: func(dsn string) gorm.Dialector { return mysql.Open(dsn) },
DSN: func(c *config.DatabaseConfig) string { return c.MySQLDSN() },
})
// 内置 PostgreSQL
RegisterDialect(DialectSpec{
Name: DriverPostgres,
Aliases: []string{"postgresql", "pg"},
Dialector: func(dsn string) gorm.Dialector { return postgres.Open(dsn) },
DSN: func(c *config.DatabaseConfig) string { return c.PostgresDSN() },
})
}
database/manager.go
+914
View File
@@ -0,0 +1,914 @@
package database
import (
"context"
cryptorand "crypto/rand"
"database/sql"
"errors"
"fmt"
"math/big"
"strings"
"sync"
"sync/atomic"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/logger"
"go.uber.org/zap"
"gorm.io/gorm"
gormlogger "gorm.io/gorm/logger"
)
type dbModeContextKey struct{}
// txContextKey 携带外层事务的 *gorm.DB，使 repository 等上层在调用时能 join 到外层事务
// （H6c：外层 ctx 事务无法 join）。由 WithTx 注入、TxFromContext 读取。
type txContextKey struct{}
const (
dbModeMaster = "master"
dbModeReplica = "replica"
)
func normalizeContext(ctx context.Context) context.Context {
if ctx == nil {
return context.Background()
}
return ctx
}
// ReplicaPicker 从库选择策略
type ReplicaPicker interface {
Pick(replicas []*gorm.DB) *gorm.DB
}
// RoundRobinPicker 轮询选择从库
type RoundRobinPicker struct {
mu sync.Mutex
counter int
}
// Pick 轮询选择一个从库
func (p *RoundRobinPicker) Pick(replicas []*gorm.DB) *gorm.DB {
if len(replicas) == 0 {
return nil
}
p.mu.Lock()
idx := p.counter % len(replicas)
p.counter = (idx + 1) % len(replicas)
p.mu.Unlock()
return replicas[idx]
}
// RandomPicker 随机选择从库。
//
// 使用 crypto/rand 生成随机索引，并发安全且不可预测。len(replicas)<=0 返回 nil；
// crypto/rand 失败（极罕见，如熵池耗尽）时回退到 replicas[0]，保证可用性。
type RandomPicker struct{}
// Pick 随机选择一个从库
func (p *RandomPicker) Pick(replicas []*gorm.DB) *gorm.DB {
if len(replicas) == 0 {
return nil
}
n, err := cryptorand.Int(cryptorand.Reader, big.NewInt(int64(len(replicas))))
if err != nil {
return replicas[0]
}
return replicas[int(n.Int64())]
}
// Manager 数据库管理器，持有主库与从库连接实例
type Manager struct {
cfg *config.Config
master *gorm.DB
replicas []*gorm.DB
picker ReplicaPicker
mu sync.Mutex
// opMu 串行化 InitDB / InitDBWithReplicas / Close 这类资源生命周期操作。
// 避免关闭已开始后初始化又发布新连接，或初始化发布后被并发 Close 置空。
opMu sync.Mutex
// #21 健康自愈
healthy atomic.Bool // 主库是否健康
replicaHealthy []atomic.Bool // 每个从库的健康标记，索引与 replicas 对齐
probeFailures int // 主库连续探活失败次数
probeMu sync.Mutex // 保护 probeFailures
replicaHealthSet bool // replicaHealthy 是否已按 replicas 长度初始化
}
// NewManager 创建数据库管理器
func NewManager(cfg *config.Config) *Manager {
return &Manager{cfg: cfg, picker: &RandomPicker{}}
}
// getCfg 在锁内读取 m.cfg（P1 #11：消除与 InitDB 写 m.cfg 的数据竞争）。
func (m *Manager) getCfg() *config.Config {
m.mu.Lock()
defer m.mu.Unlock()
return m.cfg
}
// setCfg 在锁内写入 m.cfg（P1 #11）。
func (m *Manager) setCfg(cfg *config.Config) {
m.mu.Lock()
m.cfg = cfg
m.mu.Unlock()
}
// SetPicker 设置从库选择策略
func (m *Manager) SetPicker(p ReplicaPicker) {
if p == nil {
return
}
m.mu.Lock()
m.picker = p
m.mu.Unlock()
}
// Picker 返回当前从库选择策略
func (m *Manager) Picker() ReplicaPicker {
m.mu.Lock()
defer m.mu.Unlock()
return m.picker
}
// Master 返回主库实例。
// 经 m.mu 锁保护读取，避免与 InitDB/Close 的写竞争返回已关闭/nil 池（C11d）。
func (m *Manager) Master() *gorm.DB {
m.mu.Lock()
defer m.mu.Unlock()
return m.master
}
// Replicas 返回所有从库实例的拷贝。
// 经 m.mu 锁保护读取并返回拷贝，避免调用方持活切片与 InitDBWithReplicas/Close 重置竞争（C11d）。
func (m *Manager) Replicas() []*gorm.DB {
m.mu.Lock()
defer m.mu.Unlock()
if m.replicas == nil {
return nil
}
out := make([]*gorm.DB, len(m.replicas))
copy(out, m.replicas)
return out
}
// Replica 按策略选择一个从库；无从库时返回主库。
// #21：启用探活后，自动过滤不健康的从库；全不健康时回退到全部从库（仍可服务）。
// 全程持 m.mu 锁，避免 replicas/master 与重建路径写竞争（C11d）。
func (m *Manager) Replica() *gorm.DB {
m.mu.Lock()
defer m.mu.Unlock()
if len(m.replicas) == 0 {
return m.master
}
pool := m.replicas
// 启用探活且至少有一个健康标记时，仅从健康从库中选取
if m.replicaHealthSet {
var healthy []*gorm.DB
for i, r := range m.replicas {
if i < len(m.replicaHealthy) && m.replicaHealthy[i].Load() {
healthy = append(healthy, r)
}
}
if len(healthy) > 0 {
pool = healthy
}
// healthy 为空时回退到全部 replicas，避免读流量完全中断
}
if m.picker != nil {
if db := m.picker.Pick(pool); db != nil {
return db
}
}
return pool[0]
}
// IsHealthy 返回主库当前健康状态（#21）。供 readiness/health 探针联动。
func (m *Manager) IsHealthy() bool {
return m.healthy.Load()
}
// initReplicaHealth 按 replicas 数量初始化健康标记（全部为健康）。
// 已初始化（replicaHealthSet=true）时早返回；重建从库前须先 resetReplicaHealth 重置，
// 否则健康切片长度与新 replicas 错位（C11a）。
func (m *Manager) initReplicaHealth() {
m.mu.Lock()
defer m.mu.Unlock()
if m.replicaHealthSet {
return
}
m.replicaHealthy = make([]atomic.Bool, len(m.replicas))
for i := range m.replicaHealthy {
m.replicaHealthy[i].Store(true)
}
m.replicaHealthSet = true
}
// ensureReplicaHealthLocked 按当前 replicas 重建健康标记。调用方须持有 m.mu。
func (m *Manager) ensureReplicaHealthLocked() {
m.replicaHealthy = make([]atomic.Bool, len(m.replicas))
for i := range m.replicaHealthy {
m.replicaHealthy[i].Store(true)
}
m.replicaHealthSet = true
}
// resetReplicaHealth 清空从库健康标记，使下次 initReplicaHealth 按新 replicas 长度重建。
// 重建从库（InitDBWithReplicas）/Close 前必须调用，避免健康切片与新 replicas 长度错位（C11a）。
// 调用方须持有 m.mu。
func (m *Manager) resetReplicaHealth() {
m.replicaHealthy = nil
m.replicaHealthSet = false
}
// StartProbing 启动主库与从库的健康探活后台循环（#21）。
// 阻塞调用方，应通过 App.Go 在独立 goroutine 运行；ctx 取消时退出。
// 周期 ping 主库，连续失败达阈值后标记不健康（IsHealthy=false）；
// 同时 ping 各从库，失败则从读流量剔除，恢复后自动重新纳入。
func (m *Manager) StartProbing(ctx context.Context) {
ctx = normalizeContext(ctx)
m.initReplicaHealth()
cfg := m.getCfg() // P1 #11：锁内快照，避免与 InitDB 写 m.cfg 竞态
interval := 30 * time.Second
if cfg != nil && cfg.Database.HealthCheckInterval > 0 {
interval = cfg.Database.HealthCheckInterval
}
threshold := 3
if cfg != nil && cfg.Database.HealthCheckFailureThreshold > 0 {
threshold = cfg.Database.HealthCheckFailureThreshold
}
ticker := time.NewTicker(interval)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
m.probeOnce(ctx, threshold)
}
}
}
// probeOnce 执行一轮主库+从库探活并更新健康标记。
func (m *Manager) probeOnce(ctx context.Context, threshold int) {
// 主库
if err := m.HealthCheck(ctx); err != nil {
m.probeMu.Lock()
m.probeFailures++
if m.probeFailures >= threshold {
if m.healthy.Load() {
logger.Warnf("数据库主库连续探活失败 %d 次，标记为不健康: %v", m.probeFailures, err)
}
m.healthy.Store(false)
}
m.probeMu.Unlock()
} else {
m.probeMu.Lock()
if m.probeFailures >= threshold && !m.healthy.Load() {
logger.Info("数据库主库探活恢复，重新标记为健康")
}
m.probeFailures = 0
m.probeMu.Unlock()
m.healthy.Store(true)
}
// 从库
m.mu.Lock()
replicas := make([]*gorm.DB, len(m.replicas))
copy(replicas, m.replicas)
if len(replicas) > 0 && !m.replicaHealthSet {
m.ensureReplicaHealthLocked()
}
healthSet := m.replicaHealthSet
replicaHealthy := m.replicaHealthy // 快照切片头，避免与 resetReplicaHealth 写竞争
m.mu.Unlock()
if !healthSet {
return
}
for i, r := range replicas {
if r == nil {
continue
}
sqlDB, err := r.DB()
if err != nil {
if i < len(replicaHealthy) {
replicaHealthy[i].Store(false)
}
continue
}
// M11（H-db-1）：从库探活 ping 经 pingWithTimeout 受 3s 约束，挂起 DB 不无限阻塞探活 goroutine。
if err := pingWithTimeout(sqlDB, ctx); err != nil {
if i < len(replicaHealthy) && replicaHealthy[i].Load() {
logger.Warnf("数据库从库 #%d 探活失败，暂时剔除读流量: %v", i, err)
}
if i < len(replicaHealthy) {
replicaHealthy[i].Store(false)
}
} else {
if i < len(replicaHealthy) {
replicaHealthy[i].Store(true)
}
}
}
}
// FromContext 根据上下文选择数据库
func (m *Manager) FromContext(ctx context.Context) *gorm.DB {
ctx = normalizeContext(ctx)
mode, ok := ctx.Value(dbModeContextKey{}).(string)
if !ok {
return m.Replica()
}
switch mode {
case dbModeMaster:
return m.Master()
case dbModeReplica:
return m.Replica()
default:
return m.Replica()
}
}
// Open 打开主库连接
func (m *Manager) Open(ctx context.Context) error {
cfg := m.getCfg() // P1 #11：锁内读取，避免与 InitDB 写竞态
if cfg == nil {
return errors.New("数据库配置未设置")
}
return m.InitDB(ctx, cfg)
}
// OpenWithReplicas 打开主库与从库连接
func (m *Manager) OpenWithReplicas(ctx context.Context, replicaDSNs []string) error {
cfg := m.getCfg() // P1 #11：锁内读取
if cfg == nil {
return errors.New("数据库配置未设置")
}
return m.InitDBWithReplicas(ctx, cfg, replicaDSNs)
}
// closeDB 关闭 gorm.DB 底层连接池。nil 或未初始化（无 ConnPool）时返回 nil，不 panic。
// 用于重建/关闭路径释放旧池，避免直接覆盖致泄漏（C11b/C11c）。
func closeDB(db *gorm.DB) error {
if db == nil {
return nil
}
sqlDB, err := db.DB()
if err != nil {
return err
}
return sqlDB.Close()
}
func warnCloseDB(db *gorm.DB, context string) {
if err := closeDB(db); err != nil {
logger.Warnf("%s: %v", context, err)
}
}
// Close 关闭主库与全部从库连接，并重置从库健康状态。
// 字段置空在锁内完成（保证新读取得到 nil），实际关闭在锁外执行避免持锁阻塞。
func (m *Manager) Close() error {
m.opMu.Lock()
defer m.opMu.Unlock()
m.mu.Lock()
master := m.master
replicas := m.replicas
m.master = nil
m.replicas = nil
m.resetReplicaHealth()
m.healthy.Store(false)
m.mu.Unlock()
var errs []error
if err := closeDB(master); err != nil {
errs = append(errs, err)
}
for _, replica := range replicas {
if err := closeDB(replica); err != nil {
errs = append(errs, err)
}
}
return errors.Join(errs...)
}
// HealthCheck 健康检查，主库不可达时返回错误。
//
// M11 完整覆盖（H-db-1 修复）：ping 经 pingWithTimeout 受 healthCheckTimeout(3s) 约束，
// 使后台探活（probeOnce）与 /health 端点（app.go 经本方法）都不会被挂起 DB（连接活但不
// 响应）无限阻塞。ctx 自带更短 deadline 时优先尊重 ctx。
func (m *Manager) HealthCheck(ctx context.Context) error {
ctx = normalizeContext(ctx)
m.mu.Lock()
db := m.master
m.mu.Unlock()
if db == nil {
return errors.New("数据库主库未初始化")
}
sqlDB, err := db.DB()
if err != nil {
return err
}
return pingWithTimeout(sqlDB, ctx)
}
// DefaultManager 默认数据库管理器，包级 facade 代理到它。
//
// 主线A 修复：改用 atomic.Pointer 保护读写，消除原裸指针（外部直接
// `database.DefaultManager = ...` 赋值与请求 goroutine 经 facade 读取）之间的数据竞争。
// 与 config.defaultManager / database.DefaultRedis / storage.DefaultStorage /
// cache.defaultCachePtr / jwt.defaultManager 对齐——框架内包级可变全局一律 atomic.Pointer。
//
// 类型由 *Manager 变更为 atomic.Pointer[Manager]（breaking）：下游若直接调用
// DefaultManager.Init/Master 等方法需改用 InitDB/GetDB 等 facade，或
// DefaultManager.Load().Init(...)，或经 GetDefaultManager() 取实例后再调方法。
var DefaultManager atomic.Pointer[Manager]
func init() {
DefaultManager.Store(NewManager(nil))
}
// SwapDefaultManager 将指定 Manager 置为全局默认，并返回被替换的旧 Manager。
// 旧 Manager 不会被关闭，供 App 初始化这类需要失败回滚的生命周期流程暂存。
// nil 被忽略，以防 facade Load 到 nil panic。
func SwapDefaultManager(m *Manager) *Manager {
if m == nil {
return DefaultManager.Load()
}
return DefaultManager.Swap(m)
}
// SetDefaultManager 提升指定 Manager 为全局默认，并关闭被替换的旧 Manager。
// 用于多实例场景或测试注入。nil 被忽略以防 facade Load 到 nil panic。
// 若调用方需要保留旧 Manager 用于回滚，请使用 SwapDefaultManager。
func SetDefaultManager(m *Manager) {
if m == nil {
return
}
old := SwapDefaultManager(m)
if old != nil && old != m {
if err := old.Close(); err != nil {
logger.Warnf("关闭被替换的旧数据库 manager 失败: %v", err)
}
}
}
// GetDefaultManager 返回全局默认 Manager（atomic 读取，并发安全）。
// 替代直接读 DefaultManager 包级变量（类型已改为 atomic.Pointer，直接读得到的是 atomic
// 值而非 *Manager）。需直接持有 Manager 调用其方法时用本函数或 DefaultManager.Load()。
func GetDefaultManager() *Manager {
return DefaultManager.Load()
}
// InitDB 初始化数据库连接（带重试机制），驱动由配置决定。
// ctx 控制 Ping 与重试等待；调用方取消 ctx 时初始化会尽快返回。
func (m *Manager) InitDB(ctx context.Context, cfg *config.Config) error {
ctx = normalizeContext(ctx)
m.opMu.Lock()
defer m.opMu.Unlock()
return m.initDB(ctx, cfg)
}
func (m *Manager) initDB(ctx context.Context, cfg *config.Config) error {
if cfg == nil {
return errors.New("数据库配置未设置")
}
if err := ctx.Err(); err != nil {
return fmt.Errorf("数据库初始化已取消: %w", err)
}
m.setCfg(cfg) // P1 #11：锁内写入，避免与 StartProbing/Open 读竞态
// GORM 日志配置
var gormLogLevel gormlogger.LogLevel
if cfg.IsDevelopment() {
gormLogLevel = gormlogger.Info
} else {
gormLogLevel = gormlogger.Warn
}
gormConfig := &gorm.Config{
Logger: gormlogger.Default.LogMode(gormLogLevel),
// H-db-1：禁用 gorm.Open 的自动 Ping（gorm.go:204，ConnPool 为 *sql.DB 时会调
// pinger.Ping() 无超时）。挂起 DB（连接活但不响应）下该 Ping 无 ctx deadline 无限阻塞，
// 发生在 initDB 的 pingWithTimeout 之前，使启动卡死。框架改用 pingWithTimeout（3s）自管
// 启动 ping，故禁用 gorm 无超时自动 ping。InitDBWithReplicas 的 replica 路径同理。
DisableAutomaticPing: true,
}
// M-config-2：MySQL 启用 TLS 且配置自定义 CA 时，注册命名 TLS 配置，使 DSN 中 tls=<name> 生效。
// 失败 fail-fast 返回错误，绝不静默回退明文连接。非 MySQL / 未配 CA 为 no-op。
if err := ensureMySQLTLSRegistered(cfg); err != nil {
return err
}
// 重试配置
maxRetries := 5
retryDelay := time.Second
var lastErr error
for i := range maxRetries {
if err := ctx.Err(); err != nil {
return fmt.Errorf("数据库初始化已取消: %w", err)
}
// 连接主库：先打开到局部变量，仅 Ping 成功后才安装为 m.master，
// 避免 Ping 失败时下轮覆盖 m.master 泄漏旧池（C11b）。
db, err := gorm.Open(Dialector(cfg), gormConfig)
if err != nil {
lastErr = err
// 不可恢复的错误（认证失败、未知数据库、DSN 非法等）直接返回，不必重试
if !isTransientDBError(err) {
return fmt.Errorf("数据库连接失败（不可恢复）: %w", err)
}
} else {
sqlDB, err := db.DB()
if err != nil {
lastErr = err
warnCloseDB(db, "关闭刚打开的数据库连接池失败") // C11b: 关闭刚打开的池，避免下轮泄漏
} else {
sqlDB.SetMaxIdleConns(cfg.Database.MaxIdleConns)
sqlDB.SetMaxOpenConns(cfg.Database.MaxOpenConns)
sqlDB.SetConnMaxLifetime(time.Hour)
if cfg.Database.ConnMaxIdleTime > 0 {
sqlDB.SetConnMaxIdleTime(cfg.Database.ConnMaxIdleTime)
}
// M11（H-db-1）：启动 ping 经 pingWithTimeout 受 3s 约束，挂起 DB 致 InitDB 重试失败而非无限阻塞。
if err := pingWithTimeout(sqlDB, ctx); err == nil {
// 成功：安装为新主库，关闭旧主库池（重建路径覆盖前先释放旧资源，C11b）
m.mu.Lock()
old := m.master
m.master = db
m.mu.Unlock()
m.healthy.Store(true) // Ping 通过才标记健康（#21）
warnCloseDB(old, "关闭旧数据库主库连接池失败")
logger.Info("数据库主库连接成功",
zap.String("driver", driverDescription(cfg.Database.Driver)),
zap.String("host", cfg.Database.Host),
zap.Int("port", cfg.Database.Port))
return nil
} else {
// Ping 失败（如服务端暂时不可达）视作可重试
lastErr = err
warnCloseDB(db, "关闭 Ping 失败的数据库连接池失败") // C11b: 关闭刚打开的池，避免下轮覆盖泄漏
}
}
}
logger.Warnf("数据库连接失败，第 %d/%d 次重试: %v", i+1, maxRetries, lastErr)
if i == maxRetries-1 {
break
}
select {
case <-ctx.Done():
return fmt.Errorf("数据库初始化已取消: %w", ctx.Err())
case <-time.After(retryDelay):
}
retryDelay *= 2
if retryDelay > 30*time.Second {
retryDelay = 30 * time.Second
}
}
return fmt.Errorf("数据库连接失败（重试 %d 次）: %w", maxRetries, lastErr)
}
// isTransientDBError 判断数据库连接错误是否值得重试。
// 认证失败、未知数据库、非法 DSN/驱动等属于配置类错误，重试无意义，直接返回更友好。
// D5 修复：覆盖 MySQL 和 PostgreSQL 常见非瞬态错误。
func isTransientDBError(err error) bool {
if err == nil {
return true
}
msg := err.Error()
nonTransient := []string{
// MySQL
"Access denied", // 认证失败（用户名/密码错误）
"authentication plugin", // 认证插件不支持
"Unknown database", // 目标库不存在
"invalid DSN", // DSN 语法错误
"unknown driver", // 驱动未注册
"unsupported driver", // 驱动不支持
// PostgreSQL（D5 修复；P1 #12：移除过宽的独立 "database" 子串——它会把
// "the database system is starting up" 等瞬态错误误判为非瞬态而放弃重试。
// PG 目标库不存在的消息形如 database "x" does not exist，用 "does not exist" 精确匹配）。
"password authentication failed", // pg 密码错误
"does not exist", // pg 目标库/角色不存在
"no pg_hba.conf entry", // pg_hba.conf 拒绝
}
for _, sub := range nonTransient {
if strings.Contains(msg, sub) {
return false
}
}
return true
}
// replicaMaxOpenConns 计算从库连接池 MaxOpenConns（H-A 修复）。
// masterMax>0 时取 max(1, masterMax/2)（从库适当减少，但绝不截断为 0）；
// masterMax<=0（未配置/无限）时返回 0，与主库"无限"语义一致。
func replicaMaxOpenConns(masterMax int) int {
if masterMax <= 0 {
return 0
}
half := masterMax / 2
if half < 1 {
half = 1
}
return half
}
// InitDBWithReplicas 初始化数据库主从连接，驱动由配置决定
// replicaDSNs: 从库连接字符串列表（需与主库驱动匹配）
func (m *Manager) InitDBWithReplicas(ctx context.Context, cfg *config.Config, replicaDSNs []string) error {
ctx = normalizeContext(ctx)
m.opMu.Lock()
defer m.opMu.Unlock()
if cfg == nil {
return errors.New("数据库配置未设置")
}
// 先初始化主库
if err := m.initDB(ctx, cfg); err != nil {
return err
}
// C11c: 重建从库前关闭旧从库池；C11a: 重置健康状态，使下次 initReplicaHealth 按新 replicas 长度重建
m.mu.Lock()
oldReplicas := m.replicas
m.replicas = nil
m.resetReplicaHealth()
m.mu.Unlock()
for _, r := range oldReplicas {
warnCloseDB(r, "关闭旧数据库从库连接池失败")
}
// 初始化从库
if len(replicaDSNs) > 0 {
var gormLogLevel gormlogger.LogLevel
if cfg.IsDevelopment() {
gormLogLevel = gormlogger.Info
} else {
gormLogLevel = gormlogger.Warn
}
gormConfig := &gorm.Config{
Logger: gormlogger.Default.LogMode(gormLogLevel),
// H-db-1：禁用 gorm.Open 自动 Ping（同 initDB），框架用 pingWithTimeout 自管 replica 启动 ping。
DisableAutomaticPing: true,
}
// 先构建到局部切片，全部成功后再安装，避免部分构建期间外部读到中间态
var newReplicas []*gorm.DB
for i, dsn := range replicaDSNs {
if err := ctx.Err(); err != nil {
for _, r := range newReplicas {
warnCloseDB(r, "关闭已打开的数据库从库连接池失败")
}
return fmt.Errorf("数据库从库初始化已取消: %w", err)
}
replicaDB, err := gorm.Open(dialectorForDSN(cfg.Database.Driver, dsn), gormConfig)
if err != nil {
logger.Warnf("数据库从库 %d 连接失败: %v", i+1, err)
continue
}
sqlDB, err := replicaDB.DB()
if err != nil {
logger.Warnf("数据库从库 %d 获取连接池失败: %v", i+1, err)
warnCloseDB(replicaDB, "关闭刚打开的数据库从库连接池失败") // C11c: 关闭刚打开的池避免泄漏
continue
}
sqlDB.SetMaxIdleConns(cfg.Database.MaxIdleConns)
// H-A 修复：从库 MaxOpenConns 适当减少，但须避免截断为 0。
// database/sql 中 SetMaxOpenConns(0) 表示"无限制"——原实现 MaxOpenConns/2 在
// 配置为 1 时得 0，反而让从库连接池无上限（与"减少"意图相反、高并发下打爆 DB）；
// 配置为 0（未配置/无限）时 0/2=0 恰好"无限"，与主库一致，保持语义。
// 现规则：MaxOpenConns>0 时取 max(1, /2)；<=0 时从库亦无限（0），与主库对齐。
sqlDB.SetMaxOpenConns(replicaMaxOpenConns(cfg.Database.MaxOpenConns))
sqlDB.SetConnMaxLifetime(time.Hour)
// M11（H-db-1）：从库启动 ping 经 pingWithTimeout 受 3s 约束，挂起 DB 不无限阻塞 InitDBWithReplicas。
if err := pingWithTimeout(sqlDB, ctx); err != nil {
logger.Warnf("数据库从库 %d Ping 失败: %v", i+1, err)
warnCloseDB(replicaDB, "关闭 Ping 失败的数据库从库连接池失败") // C11c: 关闭刚打开的池避免泄漏
continue
}
newReplicas = append(newReplicas, replicaDB)
logger.Info("数据库从库连接成功", zap.Int("index", i+1))
}
m.mu.Lock()
m.replicas = newReplicas
m.ensureReplicaHealthLocked()
m.mu.Unlock()
}
return nil
}
// InitDB 初始化数据库连接（带重试机制），驱动由配置决定。
func InitDB(ctx context.Context, cfg *config.Config) error {
return DefaultManager.Load().InitDB(ctx, cfg)
}
// InitDBWithReplicas 初始化数据库主从连接，驱动由配置决定
func InitDBWithReplicas(ctx context.Context, cfg *config.Config, replicaDSNs []string) error {
return DefaultManager.Load().InitDBWithReplicas(ctx, cfg, replicaDSNs)
}
// GetReadDB 获取读库实例（按策略选择从库）
func GetReadDB() *gorm.DB {
return DefaultManager.Load().Replica()
}
// GetWriteDB 获取写库实例（主库）
func GetWriteDB() *gorm.DB {
return DefaultManager.Load().Master()
}
// GetDB 获取数据库实例（默认主库，兼容旧代码）
func GetDB() *gorm.DB {
return DefaultManager.Load().Master()
}
// GetReplicas 获取所有从库实例
func GetReplicas() []*gorm.DB {
return DefaultManager.Load().Replicas()
}
// SetReplicaPicker 设置默认管理器的从库选择策略
func SetReplicaPicker(p ReplicaPicker) {
DefaultManager.Load().SetPicker(p)
}
// UseMaster 强制使用主库（用于事务或需要实时数据的场景）
func UseMaster(ctx context.Context) context.Context {
ctx = normalizeContext(ctx)
return context.WithValue(ctx, dbModeContextKey{}, dbModeMaster)
}
// UseReplica 强制使用从库（用于报表查询等场景）
func UseReplica(ctx context.Context) context.Context {
ctx = normalizeContext(ctx)
return context.WithValue(ctx, dbModeContextKey{}, dbModeReplica)
}
// GetDBFromContext 根据上下文选择数据库
func GetDBFromContext(ctx context.Context) *gorm.DB {
return DefaultManager.Load().FromContext(ctx)
}
// WithTx 将外层事务注入 ctx，使上层（如 repository.BaseRepo）在调用时能 join 到该事务
// 而非另开连接/路由到主从库（H6c）。
//
// 用法：
//
// err := database.TransactionWithContext(ctx, func(tx *gorm.DB) error {
// ctx2 := database.WithTx(ctx, tx)
// // 传 ctx2 给 repo 方法，repo 内部会优先使用该 tx
// return repo.FindByID(ctx2, id) // 此查询参与外层事务
// })
//
// 注意：tx 仅在该 ctx 的生命周期内有效；事务提交/回滚后不得再用该 ctx 携带的 tx。
func WithTx(ctx context.Context, tx *gorm.DB) context.Context {
ctx = normalizeContext(ctx)
if tx == nil {
return ctx
}
return context.WithValue(ctx, txContextKey{}, tx)
}
// TxFromContext 取出 ctx 携带的外层事务；无则返回 nil。
func TxFromContext(ctx context.Context) *gorm.DB {
ctx = normalizeContext(ctx)
if tx, ok := ctx.Value(txContextKey{}).(*gorm.DB); ok {
return tx
}
return nil
}
// AutoMigrate 自动迁移数据库表结构（由应用通过 WithMigrator/WithModels 注册）
func AutoMigrate() error {
logger.Info("数据库表结构迁移完成")
return nil
}
// Close 关闭所有数据库连接（主库与从库），等价于 CloseAll。
// 历史上仅关闭主库、遗留从库池泄漏（C11f），已修正为委托 CloseAll。
func Close() error {
return CloseAll()
}
// CloseAll 关闭所有数据库连接（包括从库）
func CloseAll() error {
return DefaultManager.Load().Close()
}
// Transaction 事务操作（自动使用主库）
func Transaction(fn func(tx *gorm.DB) error) error {
db := DefaultManager.Load().Master()
if db == nil {
return errors.New("数据库未初始化")
}
return db.Transaction(fn)
}
// TransactionWithContext 带上下文的事务操作
func TransactionWithContext(ctx context.Context, fn func(tx *gorm.DB) error) error {
ctx = normalizeContext(ctx)
db := DefaultManager.Load().Master()
if db == nil {
return errors.New("数据库未初始化")
}
return db.WithContext(ctx).Transaction(fn)
}
// ReadQuery 读查询。遵循 ctx 中的数据库路由标记；未指定时默认走从库。
func ReadQuery(ctx context.Context, model any, query string, args ...any) error {
ctx = normalizeContext(ctx)
db := GetDBFromContext(ctx)
if db == nil {
return errors.New("数据库未初始化")
}
return db.WithContext(ctx).Where(query, args...).Find(model).Error
}
// WriteQuery 在主库上执行查询并扫描到 model（强制主库，绕过从库延迟）。
// 注意：命名沿用历史，实际用 .Find() 扫描结果集（读取语义），并非写操作——
// 强制主库是为了读到刚写入的最新数据（read-your-writes）。命名误导见 M11。
func WriteQuery(ctx context.Context, model any, query string, args ...any) error {
ctx = normalizeContext(ctx)
db := DefaultManager.Load().Master()
if db == nil {
return errors.New("数据库未初始化")
}
return db.WithContext(ctx).Where(query, args...).Find(model).Error
}
// healthCheckTimeout 健康检查单次 ping 超时，避免探针被慢/挂起的 DB 长期阻塞（M11）。
const healthCheckTimeout = 3 * time.Second
// pingWithTimeout 带超时的 ping，ctx 由调用方传入时优先尊重其 deadline。
func pingWithTimeout(sqlDB *sql.DB, parent context.Context) error {
parent = normalizeContext(parent)
ctx, cancel := context.WithTimeout(parent, healthCheckTimeout)
defer cancel()
return sqlDB.PingContext(ctx)
}
// HealthCheck 健康检查（主库 + 从库），单次 ping 限 3s 超时（M11）。
func HealthCheck() map[string]bool {
result := make(map[string]bool)
ctx := context.Background()
m := DefaultManager.Load()
// 检查主库
if master := m.Master(); master != nil {
sqlDB, err := master.DB()
if err == nil && pingWithTimeout(sqlDB, ctx) == nil {
result["master"] = true
} else {
result["master"] = false
}
} else {
result["master"] = false
}
// 检查从库
for i, replica := range m.Replicas() {
if replica != nil {
sqlDB, err := replica.DB()
if err == nil && pingWithTimeout(sqlDB, ctx) == nil {
result[fmt.Sprintf("replica_%d", i+1)] = true
} else {
result[fmt.Sprintf("replica_%d", i+1)] = false
}
} else {
result[fmt.Sprintf("replica_%d", i+1)] = false
}
}
return result
}
// IsDBHealthy 返回主库探活健康状态（#21）。
// 与 HealthCheck()（实时 ping）不同，这是后台探活维护的缓存标记，
// 供 readiness 探针快速判断是否接流量，避免每次探针都同步 ping。
func IsDBHealthy() bool {
return DefaultManager.Load().IsHealthy()
}
// StartDBProbing 启动主库/从库探活后台循环（#21）。
// 阻塞，应通过 App.Go 在独立 goroutine 运行；ctx 取消时退出。
func StartDBProbing(ctx context.Context) {
DefaultManager.Load().StartProbing(ctx)
}
database/manager_c11_internal_test.go
+404
View File
@@ -0,0 +1,404 @@
package database
import (
"context"
"errors"
"sync"
"sync/atomic"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/logger"
"gorm.io/gorm"
"gorm.io/gorm/clause"
"gorm.io/gorm/schema"
)
func init() {
// 部分用例触发 logger.Warnf 路径，确保 logger 已初始化避免 nil deref。
logger.Close()
}
// sentinelDB 返回一个可安全调用 .DB() 的 gorm.DB 占位实例。
// 直接用 &gorm.DB{} 会令内嵌 *Config 为 nil，.DB() 访问提升字段 ConnPool 时 nil deref；
// 这里给定非 nil Config，.DB() 走到 nil ConnPool 分支返回 ErrInvalidDB 而不 panic。
func sentinelDB() *gorm.DB {
return &gorm.DB{Config: &gorm.Config{}}
}
// TestC11MasterReplicasConcurrentReadWrite 验证 Master/Replicas/Replica 全程加锁，
// 与并发重建路径（写 master/replicas）无数据竞争（C11d）。
// 修复前 Master/Replicas 为裸读，-race 必采到竞争。
func TestC11MasterReplicasConcurrentReadWrite(t *testing.T) {
m := &Manager{picker: &RandomPicker{}}
sentinels := []*gorm.DB{{}, {}, {}}
replicaSets := [][]*gorm.DB{
{sentinels[0], sentinels[1]},
{sentinels[2]},
{},
}
var wg sync.WaitGroup
stop := make(chan struct{})
// 写者：在锁内置换 master/replicas（模拟 InitDB/InitDBWithReplicas/Close 的写路径）
wg.Add(1)
go func() {
defer wg.Done()
for i := 0; ; i++ {
select {
case <-stop:
return
default:
}
m.mu.Lock()
m.master = sentinels[i%len(sentinels)]
m.replicas = replicaSets[i%len(replicaSets)]
m.mu.Unlock()
}
}()
// 读者：并发调用读取方法
for range 4 {
wg.Add(1)
go func() {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
_ = m.Master()
_ = m.Replicas()
_ = m.Replica()
_ = m.FromContext(context.Background())
}
}()
}
// 让竞争窗口运行一段时间，确保 -race 能采到（若有未加锁读）
time.Sleep(50 * time.Millisecond)
close(stop)
wg.Wait()
}
// TestC11ReplicasReturnsCopy 验证 Replicas 返回拷贝，调用方修改不影响内部状态（C11d）。
func TestC11ReplicasReturnsCopy(t *testing.T) {
m := &Manager{picker: &RandomPicker{}}
m.mu.Lock()
m.replicas = []*gorm.DB{{}, {}}
m.mu.Unlock()
got := m.Replicas()
if len(got) != 2 {
t.Fatalf("expected 2 replicas, got %d", len(got))
}
got[0] = nil
m.mu.Lock()
defer m.mu.Unlock()
if m.replicas[0] == nil {
t.Fatal("Replicas should return a copy, not the live slice")
}
}
// TestC11ReplicaHealthResetOnRebuild 验证重建从库前重置健康状态，
// 使 initReplicaHealth 按新 replicas 长度重建（C11a）。
// 修复前 initReplicaHealth 的 replicaHealthSet 早返回导致健康切片与新 replicas 长度错位。
func TestC11ReplicaHealthResetOnRebuild(t *testing.T) {
m := &Manager{picker: &RandomPicker{}}
// 首轮：2 个从库 + 健康初始化
m.mu.Lock()
m.replicas = []*gorm.DB{{}, {}}
m.mu.Unlock()
m.initReplicaHealth()
if !m.replicaHealthSet || len(m.replicaHealthy) != 2 {
t.Fatalf("expected health init for 2 replicas, got set=%v len=%d", m.replicaHealthSet, len(m.replicaHealthy))
}
// 重建：3 个从库 + 重置健康状态（C11a/C11c 路径）
m.mu.Lock()
m.replicas = []*gorm.DB{{}, {}, {}}
m.resetReplicaHealth()
m.mu.Unlock()
m.initReplicaHealth()
if !m.replicaHealthSet || len(m.replicaHealthy) != 3 {
t.Fatalf("C11a: expected re-init aligned with 3 new replicas, got set=%v len=%d", m.replicaHealthSet, len(m.replicaHealthy))
}
for i := range m.replicaHealthy {
if !m.replicaHealthy[i].Load() {
t.Fatal("re-init should mark all replicas healthy")
}
}
}
func TestM4ProbeOnceReinitializesReplicaHealthAfterRebuild(t *testing.T) {
m := &Manager{picker: &RandomPicker{}}
m.mu.Lock()
m.replicas = []*gorm.DB{sentinelDB(), sentinelDB()}
m.resetReplicaHealth()
m.mu.Unlock()
m.probeOnce(context.Background(), 1)
m.mu.Lock()
defer m.mu.Unlock()
if !m.replicaHealthSet {
t.Fatal("probeOnce 应在从库重建后自动重建健康标记")
}
if len(m.replicaHealthy) != 2 {
t.Fatalf("健康标记长度应与从库数量一致，实际 %d", len(m.replicaHealthy))
}
}
// TestC11ReplicaHealthStaleWithoutReset 反向验证：不调 resetReplicaHealth 时
// initReplicaHealth 早返回，健康切片长度不随新 replicas 变化（复现 C11a 缺陷根因）。
func TestC11ReplicaHealthStaleWithoutReset(t *testing.T) {
m := &Manager{picker: &RandomPicker{}}
m.mu.Lock()
m.replicas = []*gorm.DB{{}, {}}
m.mu.Unlock()
m.initReplicaHealth()
// 仅换 replicas 不重置健康状态
m.mu.Lock()
m.replicas = []*gorm.DB{{}, {}, {}}
m.mu.Unlock()
m.initReplicaHealth() // replicaHealthSet 仍为 true → 早返回
m.mu.Lock()
defer m.mu.Unlock()
if len(m.replicaHealthy) == 3 {
t.Fatal("without reset, initReplicaHealth should NOT re-align (early-returns); this proves reset is required")
}
if len(m.replicaHealthy) != 2 {
t.Fatalf("expected stale len=2, got %d", len(m.replicaHealthy))
}
}
// TestC11ManagerCloseResetsState 验证 Close 清空 master/replicas 并重置健康状态（C11a/C11c/C11d）。
func TestC11ManagerCloseResetsState(t *testing.T) {
m := &Manager{picker: &RandomPicker{}}
m.mu.Lock()
m.master = sentinelDB()
m.replicas = []*gorm.DB{sentinelDB(), sentinelDB()}
m.replicaHealthy = make([]atomic.Bool, 2)
m.replicaHealthy[0].Store(true)
m.replicaHealthy[1].Store(true)
m.replicaHealthSet = true
m.mu.Unlock()
m.healthy.Store(true)
// closeDB 对空 gorm.DB{}（无 ConnPool）返回 ErrInvalidDB，Close 收集后 join 返回；
// 这里不关心关闭错误，只断言状态被重置。
_ = m.Close()
m.mu.Lock()
defer m.mu.Unlock()
if m.master != nil {
t.Fatal("expected master nil after Close")
}
if m.replicas != nil {
t.Fatal("expected replicas nil after Close")
}
if m.replicaHealthSet {
t.Fatal("expected replicaHealthSet reset after Close")
}
if m.replicaHealthy != nil {
t.Fatal("expected replicaHealthy nil after Close")
}
if m.healthy.Load() {
t.Fatal("expected healthy=false after Close")
}
}
// TestC11PackageCloseClosesReplicas 验证包级 Close 委托 CloseAll，
// 关闭从库而非仅主库（C11f）。修复前包级 Close 仅关 master，replicas 残留。
func TestC11PackageCloseClosesReplicas(t *testing.T) {
// 保存并恢复 DefaultManager 状态，避免污染其他用例
defer func() {
DefaultManager.Load().mu.Lock()
DefaultManager.Load().master = nil
DefaultManager.Load().replicas = nil
DefaultManager.Load().resetReplicaHealth()
DefaultManager.Load().healthy.Store(false)
DefaultManager.Load().mu.Unlock()
}()
DefaultManager.Load().mu.Lock()
DefaultManager.Load().master = sentinelDB()
DefaultManager.Load().replicas = []*gorm.DB{sentinelDB(), sentinelDB()}
DefaultManager.Load().mu.Unlock()
// 包级 Close → CloseAll → DefaultManager.Load().Close()，应同时清空 master 与 replicas
_ = Close()
DefaultManager.Load().mu.Lock()
master := DefaultManager.Load().master
repl := DefaultManager.Load().replicas
DefaultManager.Load().mu.Unlock()
if master != nil {
t.Fatal("C11f: expected master nil after package Close")
}
if repl != nil {
t.Fatal("C11f: package Close should close replicas too (delegates to CloseAll), got residual replicas")
}
}
// TestC11HealthCheckLockedRead 验证 HealthCheck 在锁内快照 master，未初始化时返错（C11d）。
func TestC11HealthCheckLockedRead(t *testing.T) {
m := &Manager{picker: &RandomPicker{}}
if err := m.HealthCheck(context.Background()); err == nil {
t.Fatal("expected error when health checking uninitialized master")
}
// 空 gorm.DB（无 ConnPool）：DB() 返 ErrInvalidDB，HealthCheck 返该错而非 panic
m.mu.Lock()
m.master = sentinelDB()
m.mu.Unlock()
if err := m.HealthCheck(context.Background()); err == nil {
t.Fatal("expected error for gorm.DB without ConnPool")
}
}
func TestSetDefaultManagerClosesReplacedManager(t *testing.T) {
old := NewManager(nil)
old.mu.Lock()
old.master = sentinelDB()
old.replicas = []*gorm.DB{sentinelDB()}
old.replicaHealthy = make([]atomic.Bool, 1)
old.replicaHealthy[0].Store(true)
old.replicaHealthSet = true
old.mu.Unlock()
old.healthy.Store(true)
orig := SwapDefaultManager(old)
t.Cleanup(func() {
current := SwapDefaultManager(orig)
if current != nil && current != orig {
_ = current.Close()
}
})
next := NewManager(nil)
SetDefaultManager(next)
if GetDefaultManager() != next {
t.Fatal("SetDefaultManager 应安装新的默认 manager")
}
old.mu.Lock()
defer old.mu.Unlock()
if old.master != nil || old.replicas != nil || old.replicaHealthy != nil || old.replicaHealthSet {
t.Fatal("SetDefaultManager 应关闭并清空被替换的旧 manager，避免连接池泄漏")
}
if old.healthy.Load() {
t.Fatal("SetDefaultManager 关闭旧 manager 后健康状态应为 false")
}
}
func TestSwapDefaultManagerPreservesReplacedManager(t *testing.T) {
old := NewManager(nil)
old.mu.Lock()
old.master = sentinelDB()
old.replicas = []*gorm.DB{sentinelDB()}
old.mu.Unlock()
orig := SwapDefaultManager(old)
t.Cleanup(func() {
current := SwapDefaultManager(orig)
if current != nil && current != orig {
_ = current.Close()
}
_ = old.Close()
})
next := NewManager(nil)
previous := SwapDefaultManager(next)
if previous != old {
t.Fatal("SwapDefaultManager 应返回被替换的旧 manager")
}
if GetDefaultManager() != next {
t.Fatal("SwapDefaultManager 应安装新的默认 manager")
}
old.mu.Lock()
defer old.mu.Unlock()
if old.master == nil || len(old.replicas) != 1 {
t.Fatal("SwapDefaultManager 不应关闭旧 manager，旧资源需可用于失败回滚")
}
}
type transientDialector struct{}
func (d transientDialector) Name() string { return "m4_transient" }
func (d transientDialector) Initialize(*gorm.DB) error {
return errors.New("temporary connection failure")
}
func (d transientDialector) Migrator(*gorm.DB) gorm.Migrator { return nil }
func (d transientDialector) DataTypeOf(*schema.Field) string { return "" }
func (d transientDialector) DefaultValueOf(*schema.Field) clause.Expression { return nil }
func (d transientDialector) BindVarTo(clause.Writer, *gorm.Statement, any) {}
func (d transientDialector) QuoteTo(writer clause.Writer, str string) {
_, _ = writer.WriteString(str)
}
func (d transientDialector) Explain(sql string, _ ...any) string { return sql }
func TestM4InitDBHonorsContextDuringRetrySleep(t *testing.T) {
const driver = "m4_transient_retry"
RegisterDialect(DialectSpec{
Name: driver,
Dialector: func(string) gorm.Dialector { return transientDialector{} },
DSN: func(*config.DatabaseConfig) string { return "m4://retry" },
})
m := NewManager(nil)
ctx, cancel := context.WithCancel(context.Background())
go func() {
time.Sleep(30 * time.Millisecond)
cancel()
}()
start := time.Now()
err := m.InitDB(ctx, &config.Config{Database: config.DatabaseConfig{Driver: driver}})
if err == nil || !errors.Is(err, context.Canceled) {
t.Fatalf("InitDB 应返回 context.Canceled，实际: %v", err)
}
if elapsed := time.Since(start); elapsed > 500*time.Millisecond {
t.Fatalf("InitDB 不应等待完整 retry sleep，耗时 %s", elapsed)
}
}
func TestM4CloseWaitsForLifecycleOperation(t *testing.T) {
m := NewManager(nil)
m.opMu.Lock()
done := make(chan struct{})
go func() {
_ = m.Close()
close(done)
}()
select {
case <-done:
t.Fatal("Close 不应越过正在执行的生命周期操作")
case <-time.After(50 * time.Millisecond):
}
m.opMu.Unlock()
select {
case <-done:
case <-time.After(time.Second):
t.Fatal("释放生命周期锁后 Close 未返回")
}
}
database/manager_hdb1_internal_test.go
+199
View File
@@ -0,0 +1,199 @@
package database
import (
"context"
"database/sql"
"database/sql/driver"
"errors"
"sync"
"sync/atomic"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
"gorm.io/gorm"
"gorm.io/gorm/clause"
"gorm.io/gorm/schema"
)
// hungDriver 是测试用 database/sql 驱动，其 Conn.PingContext 阻塞直到 ctx 取消，
// 模拟"挂起 DB"（TCP 连接活但不响应查询，区别于宕机的 connection-refused 快速失败）。
// 用于回归 H-db-1：ping 路径须经 pingWithTimeout 受 healthCheckTimeout(3s) 约束，
// 挂起 DB 不得无限阻塞探活 goroutine / 启动 / /health 端点。
type hungDriver struct{}
func (hungDriver) Open(name string) (driver.Conn, error) { return hungConn{}, nil }
type hungConn struct{}
func (hungConn) Prepare(string) (driver.Stmt, error) { return nil, errors.New("hung: not implemented") }
func (hungConn) Close() error { return nil }
func (hungConn) Begin() (driver.Tx, error) { return nil, errors.New("hung: not implemented") }
// Ping 阻塞直到 ctx 取消（模拟挂起 DB 永不响应 ping）。实现 driver.Pinger 接口
// （方法名为 Ping 而非 PingContext，否则 *sql.DB.PingContext 视为 no-op 返回 nil）。
func (hungConn) Ping(ctx context.Context) error {
<-ctx.Done()
return ctx.Err()
}
var registerHungOnce sync.Once
func registerHungDriver() {
registerHungOnce.Do(func() { sql.Register("xlgo_hung_hdb1", hungDriver{}) })
}
func newHungSqlDB(t *testing.T) *sql.DB {
t.Helper()
registerHungDriver()
db, err := sql.Open("xlgo_hung_hdb1", "")
if err != nil {
t.Fatalf("sql.Open hung driver: %v", err)
}
t.Cleanup(func() { _ = db.Close() })
return db
}
// newHungGormDB 构造底层 *sql.DB 为挂起驱动的 gorm.DB，其 DB() 返回挂起 *sql.DB。
func newHungGormDB(t *testing.T) *gorm.DB {
t.Helper()
return &gorm.DB{Config: &gorm.Config{ConnPool: newHungSqlDB(t)}}
}
// assertBoundedPing 在 max+2s 内等待 fn 返回；超时则 fail（H-db-1：ping 应被
// pingWithTimeout 3s 约束，不应无限 hang）。返回 fn 的 error 供调用方断言。
func assertBoundedPing(t *testing.T, fn func() error, max time.Duration) error {
t.Helper()
done := make(chan error, 1)
start := time.Now()
go func() { done <- fn() }()
select {
case err := <-done:
if elapsed := time.Since(start); elapsed > max {
t.Fatalf("ping 路径耗时 %v 超过上限 %v（H-db-1：应被 pingWithTimeout 3s 约束）", elapsed, max)
}
return err
case <-time.After(max + 2*time.Second):
t.Fatalf("ping 路径在挂起 DB 上无限阻塞（H-db-1：pingWithTimeout 未覆盖该路径）")
return nil
}
}
// TestPingWithTimeoutBoundsHungDB_Hdb1 回归 H-db-1 机制：pingWithTimeout 对挂起 DB 的
// *sql.DB.PingContext 限 healthCheckTimeout 返回，不因 ctx 无 deadline 无限阻塞。
// 修复前若直接 PingContext(Background()) 会无限阻塞。
func TestPingWithTimeoutBoundsHungDB_Hdb1(t *testing.T) {
sqlDB := newHungSqlDB(t)
err := assertBoundedPing(t, func() error {
return pingWithTimeout(sqlDB, context.Background())
}, healthCheckTimeout+1*time.Second)
if err == nil {
t.Fatalf("挂起 DB 的 ping 应返回超时错误，got nil")
}
}
// TestManagerHealthCheckBoundsHungDB_Hdb1 回归 H-db-1 主路径：m.HealthCheck(Background)
// 对挂起主库经 pingWithTimeout ~3s 返回超时错误，不无限阻塞。该路径被后台探活
// probeOnce（master）与 /health 端点（app.go 经 dbm.HealthCheck）共用。
// 修复前 m.HealthCheck 用裸 sqlDB.PingContext(ctx)，Background ctx 无 deadline -> 无限阻塞。
func TestManagerHealthCheckBoundsHungDB_Hdb1(t *testing.T) {
m := NewManager(nil)
m.master = newHungGormDB(t)
err := assertBoundedPing(t, func() error {
return m.HealthCheck(context.Background())
}, healthCheckTimeout+1*time.Second)
if err == nil {
t.Fatalf("挂起主库的 HealthCheck 应返回超时错误，got nil")
}
}
// TestProbeOnceReplicaBoundsHungDB_Hdb1 回归 H-db-1 从库探活路径：probeOnce 对挂起从库
// 经 pingWithTimeout ~3s 返回，不无限阻塞探活 goroutine（#21 自愈不冻结）。master 置 nil
// 使 HealthCheck 快速返回"未初始化"，让 probeOnce 只在从库 ping 路径耗时。
// 修复前 probeOnce 从库用裸 sqlDB.PingContext(ctx)，Background ctx 无 deadline -> 无限阻塞。
func TestProbeOnceReplicaBoundsHungDB_Hdb1(t *testing.T) {
m := NewManager(nil)
m.master = nil // master 路径快速失败，集中测从库 ping 超时
m.replicas = []*gorm.DB{newHungGormDB(t)}
m.replicaHealthSet = true
m.replicaHealthy = make([]atomic.Bool, 1)
m.replicaHealthy[0].Store(true)
_ = assertBoundedPing(t, func() error {
m.probeOnce(context.Background(), 3)
return nil
}, healthCheckTimeout+1*time.Second)
// 挂起从库应被标记不健康（剔除读流量，#21 自愈生效）
if m.replicaHealthy[0].Load() {
t.Errorf("挂起从库应被标记不健康（replicaHealthy=false），got true")
}
}
// hungDialector 让 gorm.Open 成功并注入挂起 *sql.DB 作为 ConnPool，使 initDB 的
// db.DB() 返回挂起 *sql.DB、pingWithTimeout 触发。用于回归启动 ping 路径。
type hungDialector struct{ sqlDB *sql.DB }
func (d hungDialector) Name() string { return "hdb1_hung" }
func (d hungDialector) Initialize(db *gorm.DB) error { db.Config.ConnPool = d.sqlDB; return nil }
func (d hungDialector) Migrator(*gorm.DB) gorm.Migrator { return nil }
func (d hungDialector) DataTypeOf(*schema.Field) string { return "" }
func (d hungDialector) DefaultValueOf(*schema.Field) clause.Expression { return nil }
func (d hungDialector) BindVarTo(clause.Writer, *gorm.Statement, any) {}
func (d hungDialector) QuoteTo(w clause.Writer, s string) { _, _ = w.WriteString(s) }
func (d hungDialector) Explain(sql string, _ ...any) string { return sql }
// registerHungDialect 注册挂起 dialect（幂等）。
func registerHungDialect(t *testing.T) {
t.Helper()
RegisterDialect(DialectSpec{
Name: "hdb1_hung",
Dialector: func(string) gorm.Dialector { return hungDialector{sqlDB: newHungSqlDB(t)} },
DSN: func(*config.DatabaseConfig) string { return "hdb1_hung://" },
})
}
// hungCfg 构造用挂起 dialect 的 config。
func hungCfg() *config.Config {
return &config.Config{Database: config.DatabaseConfig{Driver: "hdb1_hung"}}
}
// TestInitDBBoundsHungDB_Hdb1 回归 H-db-1 启动 master ping 路径：InitDB(Background) 对
// 挂起主库的 ping 经 pingWithTimeout 3s 失败，5 次重试后总耗时 ~15s 返回错误，不无限阻塞。
// 修复前 initDB 用裸 sqlDB.PingContext(ctx)，Background 无 deadline -> 首次 ping 无限阻塞。
// 用 ctx 在首次 ping 超时后取消加速（避免 15s 全跑），同时证明 ctx 仍可中断重试循环。
func TestInitDBBoundsHungDB_Hdb1(t *testing.T) {
registerHungDialect(t)
m := NewManager(nil)
ctx, cancel := context.WithCancel(context.Background())
// 4s 后 cancel：首次 ping 经 pingWithTimeout ~3s 超时返回错误，进入重试前 ctx 已取消，
// initDB 在重试循环的 ctx.Err() 检查处快速返回。若修复前裸 PingContext(Background)
// 首次即无限阻塞，cancel 无法中断 -> assertBoundedPing 超时 fail。
go func() { time.Sleep(4 * time.Second); cancel() }()
_ = assertBoundedPing(t, func() error {
return m.InitDB(ctx, hungCfg())
}, 6*time.Second)
}
// TestInitDBWithReplicasBoundsHungDB_Hdb1 回归 H-db-1 启动 replica ping 路径：
// InitDBWithReplicas 对挂起 replica DSN 的 ping 经 pingWithTimeout 失败（replica 被 continue
// 跳过），主库经挂起 dialect 同样 ping 失败。整流程有界返回，不无限阻塞。
// 修复前 replica 启动 ping 用裸 PingContext -> 挂起 replica 无限阻塞 InitDBWithReplicas。
func TestInitDBWithReplicasBoundsHungDB_Hdb1(t *testing.T) {
registerHungDialect(t)
m := NewManager(nil)
// 用可取消 ctx 限制总时长；主库挂起 ping ~3s 失败后 InitDBWithReplicas 直接返回错误
// （主库失败不进入 replica 初始化）。此处验证主库 ping 路径有界即可覆盖启动 ping 约束。
ctx, cancel := context.WithCancel(context.Background())
go func() { time.Sleep(4 * time.Second); cancel() }()
err := assertBoundedPing(t, func() error {
return m.InitDBWithReplicas(ctx, hungCfg(), []string{"hdb1_hung://replica"})
}, 6*time.Second)
if err == nil {
t.Fatalf("挂起主库的 InitDBWithReplicas 应返回错误，got nil")
}
}
database/manager_test.go
+277
View File
@@ -0,0 +1,277 @@
package database_test
import (
"context"
"strings"
"testing"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/database"
"gorm.io/gorm"
"gorm.io/gorm/clause"
"gorm.io/gorm/schema"
)
func TestCloseAllWithoutInit(t *testing.T) {
if err := database.CloseAll(); err != nil {
t.Fatalf("CloseAll without init should not error: %v", err)
}
if database.GetDB() != nil {
t.Fatal("expected DB nil")
}
if database.GetReadDB() != nil {
t.Fatal("expected read DB nil")
}
if len(database.GetReplicas()) != 0 {
t.Fatal("expected replicas empty")
}
}
func TestDBContextHelpersWithoutInit(t *testing.T) {
ctx := database.UseMaster(context.Background())
if db := database.GetDBFromContext(ctx); db != nil {
t.Fatal("expected nil DB without init")
}
ctx = database.UseReplica(context.Background())
if db := database.GetDBFromContext(ctx); db != nil {
t.Fatal("expected nil read DB without init")
}
}
func TestRoundRobinPicker(t *testing.T) {
replicas := []*gorm.DB{{}, {}, {}}
p := &database.RoundRobinPicker{}
first := p.Pick(replicas)
second := p.Pick(replicas)
third := p.Pick(replicas)
fourth := p.Pick(replicas)
if first == nil || second == nil || third == nil {
t.Fatal("Picker returned nil for non-empty replicas")
}
if first != replicas[0] || second != replicas[1] || third != replicas[2] {
t.Fatal("RoundRobinPicker should cycle through replicas in order")
}
if fourth != replicas[0] {
t.Fatal("RoundRobinPicker should wrap around to the first replica")
}
if p.Pick(nil) != nil || p.Pick([]*gorm.DB{}) != nil {
t.Fatal("Picker should return nil for empty replicas")
}
}
func TestRandomPicker(t *testing.T) {
replicas := []*gorm.DB{{}, {}}
p := &database.RandomPicker{}
picked := p.Pick(replicas)
if picked == nil {
t.Fatal("RandomPicker returned nil for non-empty replicas")
}
if picked != replicas[0] && picked != replicas[1] {
t.Fatal("RandomPicker returned a replica not in the slice")
}
if p.Pick(nil) != nil || p.Pick([]*gorm.DB{}) != nil {
t.Fatal("RandomPicker should return nil for empty replicas")
}
}
func TestManagerReplicaFallbackToMaster(t *testing.T) {
mgr := database.NewManager(&config.Config{})
if mgr.Master() != nil {
t.Fatal("expected nil master before init")
}
if mgr.Replicas() != nil {
t.Fatal("expected nil replicas before init")
}
// 无从库时 Replica 应返回 master（此处均为 nil）
if mgr.Replica() != nil {
t.Fatal("expected Replica to fall back to master when no replicas")
}
}
func TestManagerSetPicker(t *testing.T) {
mgr := database.NewManager(&config.Config{})
rr := &database.RoundRobinPicker{}
mgr.SetPicker(rr)
if mgr.Picker() != rr {
t.Fatal("SetPicker did not install the picker")
}
// nil 不应覆盖已有 picker
mgr.SetPicker(nil)
if mgr.Picker() != rr {
t.Fatal("SetPicker(nil) should not clear the existing picker")
}
}
func TestDefaultManagerHealthCheckWithoutInit(t *testing.T) {
if err := database.GetDefaultManager().HealthCheck(context.Background()); err == nil {
t.Fatal("expected error when health checking uninitialized master")
}
}
func TestNilContextHelpersDoNotPanic(t *testing.T) {
_ = database.CloseAll()
if ctx := database.UseMaster(nil); ctx == nil {
t.Fatal("UseMaster(nil) 应返回可用 context")
}
if ctx := database.UseReplica(nil); ctx == nil {
t.Fatal("UseReplica(nil) 应返回可用 context")
}
if db := database.GetDBFromContext(nil); db != nil {
t.Fatal("未初始化数据库时 GetDBFromContext(nil) 应返回 nil")
}
if ctx := database.WithTx(nil, nil); ctx == nil {
t.Fatal("WithTx(nil, nil) 应返回可用 context")
}
if tx := database.TxFromContext(nil); tx != nil {
t.Fatal("TxFromContext(nil) 应返回 nil")
}
if err := database.TransactionWithContext(nil, func(tx *gorm.DB) error { return nil }); err == nil {
t.Fatal("未初始化数据库时 TransactionWithContext(nil) 应返回错误")
}
if err := database.ReadQuery(nil, &struct{}{}, "1=1"); err == nil {
t.Fatal("未初始化数据库时 ReadQuery(nil) 应返回错误")
}
if err := database.WriteQuery(nil, &struct{}{}, "1=1"); err == nil {
t.Fatal("未初始化数据库时 WriteQuery(nil) 应返回错误")
}
if got := database.HealthCheck(); !got["master"] {
// HealthCheck 内部使用 background context；未初始化时 master=false 即可。
return
}
t.Fatal("未初始化数据库时 HealthCheck master 不应为 true")
}
func TestNilConfigInitializationReturnsError(t *testing.T) {
mgr := database.NewManager(nil)
if err := mgr.InitDB(context.Background(), nil); err == nil {
t.Fatal("InitDB(nil) 应返回错误")
}
if err := mgr.InitDBWithReplicas(context.Background(), nil, nil); err == nil {
t.Fatal("InitDBWithReplicas(nil) 应返回错误")
}
if err := database.InitDB(context.Background(), nil); err == nil {
t.Fatal("包级 InitDB(nil) 应返回错误")
}
if err := database.InitDBWithReplicas(context.Background(), nil, nil); err == nil {
t.Fatal("包级 InitDBWithReplicas(nil) 应返回错误")
}
}
func TestDialectorNilConfigDoesNotPanic(t *testing.T) {
if d := database.Dialector(nil); d == nil {
t.Fatal("Dialector(nil) 应返回兜底 dialector")
}
}
func TestDialectorSelectsByDriver(t *testing.T) {
mysqlCfg := &config.Config{Database: config.DatabaseConfig{
Driver: config.DriverMySQL, Host: "localhost", Port: 3306,
User: "root", Password: "pass", Name: "db",
}}
if name := database.Dialector(mysqlCfg).Name(); name != "mysql" {
t.Fatalf("expected mysql dialector, got %q", name)
}
pgCfg := &config.Config{Database: config.DatabaseConfig{
Driver: config.DriverPostgres, Host: "localhost", Port: 5432,
User: "postgres", Password: "pass", Name: "db",
}}
if name := database.Dialector(pgCfg).Name(); name != "postgres" {
t.Fatalf("expected postgres dialector, got %q", name)
}
// 别名也应解析为 postgres
pgAliasCfg := &config.Config{Database: config.DatabaseConfig{
Driver: "PG", Host: "localhost", Port: 5432,
User: "postgres", Password: "pass", Name: "db",
}}
if name := database.Dialector(pgAliasCfg).Name(); name != "postgres" {
t.Fatalf("expected postgres dialector via alias, got %q", name)
}
// 未指定 Driver 时默认 mysql
defaultCfg := &config.Config{Database: config.DatabaseConfig{
Host: "localhost", Port: 3306, User: "root", Password: "pass", Name: "db",
}}
if name := database.Dialector(defaultCfg).Name(); name != "mysql" {
t.Fatalf("expected default mysql dialector, got %q", name)
}
}
// stubDialector 是一个用于测试 RegisterDialect 的占位 Dialector。
type stubDialector struct{ name string }
func (s stubDialector) Name() string { return s.name }
func (s stubDialector) Initialize(_ *gorm.DB) error { return nil }
func (s stubDialector) Migrator(db *gorm.DB) gorm.Migrator { return nil }
func (s stubDialector) DataTypeOf(*schema.Field) string { return "" }
func (s stubDialector) DefaultValueOf(*schema.Field) clause.Expression { return nil }
func (s stubDialector) BindVarTo(writer clause.Writer, _ *gorm.Statement, _ any) {}
func (s stubDialector) QuoteTo(writer clause.Writer, str string) { _, _ = writer.WriteString(str) }
func (s stubDialector) Explain(sql string, _ ...any) string { return sql }
func TestRegisterDialectAndCustomDriver(t *testing.T) {
const driver = "stubdb"
database.RegisterDialect(database.DialectSpec{
Name: driver,
Aliases: []string{"stub"},
Dialector: func(dsn string) gorm.Dialector { return stubDialector{name: "stubdb"} },
DSN: func(c *config.DatabaseConfig) string {
return "stub://" + c.Host
},
})
// Dialector 工厂可以解析主名和别名
if _, ok := database.LookupDialect(driver); !ok {
t.Fatal("expected stubdb dialector to be registered")
}
if _, ok := database.LookupDialect("STUB"); !ok {
t.Fatal("expected stub alias to be registered (case-insensitive)")
}
cfg := &config.Config{Database: config.DatabaseConfig{
Driver: driver, Host: "localhost",
}}
if name := database.Dialector(cfg).Name(); name != "stubdb" {
t.Fatalf("expected stubdb dialector, got %q", name)
}
// config.DSN() 应使用注册的 DSN 构建器
if dsn := cfg.Database.DSN(); dsn != "stub://localhost" {
t.Fatalf("expected DSN built by registered builder, got %q", dsn)
}
// 未知驱动应 fail-closed，避免拼写错误静默连向 MySQL。
unknownCfg := &config.Config{Database: config.DatabaseConfig{
Driver: "no-such-driver", Host: "localhost", Port: 3306,
User: "root", Password: "pass", Name: "db",
}}
d := database.Dialector(unknownCfg)
if name := d.Name(); name != "invalid" {
t.Fatalf("expected invalid dialector for unknown driver, got %q", name)
}
if _, err := gorm.Open(d, &gorm.Config{}); err == nil || !strings.Contains(err.Error(), "数据库驱动未注册") {
t.Fatalf("未知 driver 应在 GORM 初始化时报错，实际: %v", err)
}
}
func TestRegisteredDialectsContainsBuiltins(t *testing.T) {
registered := database.RegisteredDialects()
want := map[string]bool{"mysql": false, "postgres": false, "pg": false}
for _, n := range registered {
if _, ok := want[n]; ok {
want[n] = true
}
}
for k, found := range want {
if !found {
t.Errorf("expected %q to be registered by default", k)
}
}
}
database/redis.go
+194
View File
@@ -0,0 +1,194 @@
package database
import (
"context"
"errors"
"fmt"
"sync"
"sync/atomic"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/logger"
"github.com/redis/go-redis/v9"
"go.uber.org/zap"
)
// RedisManager Redis 连接管理器（#10）。照 database.Manager 模式：
// 实例化 + DefaultRedis 全局默认 + 包级 facade 代理，支持多实例与测试注入。
type RedisManager struct {
mu sync.Mutex
cfg *config.Config
client *redis.Client
}
// DefaultRedis 默认 Redis 管理器，包级 facade 代理到它。
//
// C-1/H-4 修复：改用 atomic.Pointer 保护读写，消除原裸指针置换（SetDefaultRedisManager）
// 与请求 goroutine 无锁读（GetRedis 等 facade）之间的数据竞争。与 config.defaultManager
// 对齐。类型由 *RedisManager 变更为 atomic.Pointer[RedisManager]（breaking：下游若直接
// 调用 DefaultRedis.Init 等方法需改用 InitRedis 等 facade，或 DefaultRedis.Load().Init）。
var DefaultRedis atomic.Pointer[RedisManager]
func init() {
DefaultRedis.Store(NewRedisManager())
}
// NewRedisManager 创建 Redis 管理器实例。
func NewRedisManager() *RedisManager { return &RedisManager{} }
// SwapDefaultRedisManager 将指定 RedisManager 置为全局默认，并返回被替换的旧 Manager。
// 旧 Manager 不会被关闭，供 App 初始化这类需要失败回滚的生命周期流程暂存。
// nil 被忽略，以防 facade Load 到 nil panic。
func SwapDefaultRedisManager(m *RedisManager) *RedisManager {
if m == nil {
return DefaultRedis.Load()
}
return DefaultRedis.Swap(m)
}
// SetDefaultRedisManager 提升指定 RedisManager 为全局默认，并关闭被替换的旧 Manager。
// 用于多实例场景或测试注入 mock。并发安全。若调用方需要保留旧 Manager
// 用于回滚，请使用 SwapDefaultRedisManager。
func SetDefaultRedisManager(m *RedisManager) {
if m == nil {
return
}
old := SwapDefaultRedisManager(m)
if old != nil && old != m {
if err := old.Close(); err != nil {
logger.Warnf("关闭被替换的旧 Redis manager 失败: %v", err)
}
}
}
// GetDefaultRedisManager 返回当前默认 Redis 管理器。
func GetDefaultRedisManager() *RedisManager {
return DefaultRedis.Load()
}
// newRedisClient 构造带 D7 超时（Dial 5s / Read 3s / Write 3s）的 redis.Client。
// 由 Init 与测试共用，确保所有 client 实例一致具备超时约束（挂起 Redis 不无限阻塞）。
func newRedisClient(addr, password string, db int) *redis.Client {
return redis.NewClient(&redis.Options{
Addr: addr,
Password: password,
DB: db,
DialTimeout: 5 * time.Second, // D7 修复：连接超时
ReadTimeout: 3 * time.Second, // D7 修复：读超时（约束 HealthCheck Ping 不被挂起 Redis 阻塞）
WriteTimeout: 3 * time.Second, // D7 修复：写超时
})
}
// Init 初始化 Redis 连接并 ping 验证。
func (m *RedisManager) Init(cfg *config.Config) error {
if cfg == nil {
return errors.New("Redis 配置未设置")
}
m.mu.Lock()
defer m.mu.Unlock()
client := newRedisClient(cfg.Redis.Addr(), cfg.Redis.Password, cfg.Redis.DB)
pingCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := client.Ping(pingCtx).Err(); err != nil {
if cerr := client.Close(); cerr != nil {
return errors.Join(fmt.Errorf("Redis 连接失败: %w", err), fmt.Errorf("Redis 关闭失败: %w", cerr))
}
return fmt.Errorf("Redis 连接失败: %w", err)
}
old := m.client
m.cfg = cfg
m.client = client
if old != nil {
if err := old.Close(); err != nil {
logger.Warnf("关闭旧 Redis 连接失败: %v", err)
}
}
logger.Info("Redis 连接成功", zap.String("addr", cfg.Redis.Addr()))
return nil
}
// Close 关闭 Redis 连接。
func (m *RedisManager) Close() error {
m.mu.Lock()
defer m.mu.Unlock()
if m.client == nil {
return nil
}
err := m.client.Close()
m.client = nil
return err
}
// Client 返回当前 Redis 客户端（未初始化返回 nil）。
func (m *RedisManager) Client() *redis.Client {
m.mu.Lock()
defer m.mu.Unlock()
return m.client
}
// setClientForTest 仅测试用：在持锁下替换 manager 的 client，返回旧 client。
// 供 SetTestRedisClient 注入 miniredis 等 mock，消除原包级 redisClient 双源真相。
func (m *RedisManager) setClientForTest(c *redis.Client) *redis.Client {
m.mu.Lock()
defer m.mu.Unlock()
old := m.client
m.client = c
return old
}
// HealthCheck Redis 健康检查。
func (m *RedisManager) HealthCheck(ctx context.Context) error {
ctx = normalizeContext(ctx)
m.mu.Lock()
client := m.client
m.mu.Unlock()
if client == nil {
return fmt.Errorf("Redis 未初始化")
}
return client.Ping(ctx).Err()
}
// --- 包级 facade（代理到 DefaultRedis，兼容存量） ---
// InitRedis 初始化 Redis 连接
func InitRedis(cfg *config.Config) error {
return DefaultRedis.Load().Init(cfg)
}
// CloseRedis 关闭 Redis 连接
func CloseRedis() error {
return DefaultRedis.Load().Close()
}
// HealthCheckRedis Redis 健康检查
func HealthCheckRedis(ctx context.Context) error {
return DefaultRedis.Load().HealthCheck(ctx)
}
// GetRedis 获取 Redis 客户端（未初始化返回 nil）。
//
// H-4 修复：单源——仅从 DefaultRedis.Load().Client() 取，废弃原包级 redisClient
// 回退路径（其在 manager 替换后会返回 stale client，且无锁读存在竞态）。
// 测试注入的 mock client 经 SetTestRedisClient 直接设在当前 manager 上，闭环一致。
func GetRedis() *redis.Client {
return DefaultRedis.Load().Client()
}
// SetTestRedisClient 供测试注入 miniredis 等 mock 客户端。
// 返回旧客户端引用以便测试清理时恢复。生产代码严禁调用。
//
// H-4 修复：改为在当前默认 manager 上持锁替换 client（setClientForTest），
// 不再写独立的包级 redisClient 变量，消除双源真相与无锁写竞态。
//
// 约束：操作 DefaultRedis.Load() 返回的当前默认 manager。测试应避免在调用本函数
// 的同时并发 SetDefaultRedisManager 替换默认 manager，否则注入/恢复会作用到不同
// manager 上。典型用法为 init 阶段注入、t.Cleanup 恢复，串行执行。
func SetTestRedisClient(c *redis.Client) *redis.Client {
return DefaultRedis.Load().setClientForTest(c)
}
database/redis_hdb1_internal_test.go
+84
View File
@@ -0,0 +1,84 @@
package database
import (
"context"
"net"
"testing"
"time"
"github.com/redis/go-redis/v9"
)
// startHungRedisListener 启动一个接受 TCP 连接但不读写任何数据的 listener，
// 模拟"挂起 Redis"（连接建立但不响应 RESP，区别于宕机的 connection-refused）。
// 返回 listener 地址；t.Cleanup 关闭 listener。
func startHungRedisListener(t *testing.T) string {
t.Helper()
ln, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
t.Fatalf("hung redis listen: %v", err)
}
t.Cleanup(func() { _ = ln.Close() })
go func() {
for {
conn, err := ln.Accept()
if err != nil {
return // listener 关闭
}
// 故意不读写、不关闭，持住连接模拟挂起。连接由 t.Cleanup 的 ln.Close 间接清理。
_ = conn
}
}()
return ln.Addr().String()
}
// TestRedisHealthCheckBoundsHungRedis_Hdb1 回归 H-db-1 边界（Redis 侧）：
// RedisManager.HealthCheck(Background) 对挂起 Redis（连接活但不响应）应受
// redis client 的 ReadTimeout(3s，redis.go D7) 约束有界返回错误，不无限阻塞。
// ctx 无 deadline 时由 client ReadTimeout 兜底；ctx 自带更短 deadline 时优先尊重 ctx。
// 修复前/缺 ReadTimeout 时 Ping(Background) 会无限阻塞。
func TestRedisHealthCheckBoundsHungRedis_Hdb1(t *testing.T) {
addr := startHungRedisListener(t)
cfg := redisTestConfig(t, addr)
m := NewRedisManager()
if err := m.Init(cfg); err == nil {
// Init 的 Ping 有 5s ctx，挂起 Redis 下应在 ~3s（ReadTimeout）失败返回错误。
t.Fatalf("挂起 Redis 的 Init 应返回错误，got nil")
}
// Init 失败后 m.client 未被安装（nil），HealthCheck 返 "Redis 未初始化"。
// 为测 HealthCheck 自身的 ping 超时约束，需 client 已安装但指向挂起 Redis。
// 用 setClientForTest 注入一个指向挂起 Redis 的 client。
client := newRedisClientForTest(addr)
old := m.setClientForTest(client)
t.Cleanup(func() {
if old != nil {
_ = old.Close()
}
_ = client.Close()
})
// HealthCheck(Background)：挂起 Redis 下 client.Ping 受 ReadTimeout 3s 约束有界返回。
done := make(chan error, 1)
start := time.Now()
go func() { done <- m.HealthCheck(context.Background()) }()
select {
case err := <-done:
elapsed := time.Since(start)
if err == nil {
t.Fatalf("挂起 Redis 的 HealthCheck 应返回错误，got nil")
}
// 应在 ReadTimeout(3s) 附近返回，给 6s 上限（含连接/重试余量）。
if elapsed > 6*time.Second {
t.Fatalf("HealthCheck 耗时 %v 超过 6s 上限（应受 ReadTimeout 3s 约束）", elapsed)
}
case <-time.After(10 * time.Second):
t.Fatalf("HealthCheck 在挂起 Redis 上无限阻塞（ReadTimeout 未约束 Ping）")
}
}
// newRedisClientForTest 构造指向 addr 的 redis.Client（复用 Init 的 client 配置，
// 含 DialTimeout 5s / ReadTimeout 3s / WriteTimeout 3s）。
func newRedisClientForTest(addr string) *redis.Client {
return newRedisClient(addr, "", 0)
}
database/redis_internal_test.go
+56
View File
@@ -0,0 +1,56 @@
package database
import (
"testing"
"github.com/redis/go-redis/v9"
)
func TestSetDefaultRedisManagerClosesReplacedManager(t *testing.T) {
old := NewRedisManager()
old.setClientForTest(redis.NewClient(&redis.Options{Addr: "127.0.0.1:0"}))
orig := SwapDefaultRedisManager(old)
t.Cleanup(func() {
current := SwapDefaultRedisManager(orig)
if current != nil && current != orig {
_ = current.Close()
}
})
next := NewRedisManager()
SetDefaultRedisManager(next)
if GetDefaultRedisManager() != next {
t.Fatal("SetDefaultRedisManager 应安装新的默认 manager")
}
if old.Client() != nil {
t.Fatal("SetDefaultRedisManager 应关闭并清空被替换的旧 Redis manager")
}
}
func TestSwapDefaultRedisManagerPreservesReplacedManager(t *testing.T) {
old := NewRedisManager()
client := redis.NewClient(&redis.Options{Addr: "127.0.0.1:0"})
old.setClientForTest(client)
orig := SwapDefaultRedisManager(old)
t.Cleanup(func() {
current := SwapDefaultRedisManager(orig)
if current != nil && current != orig {
_ = current.Close()
}
_ = old.Close()
})
next := NewRedisManager()
previous := SwapDefaultRedisManager(next)
if previous != old {
t.Fatal("SwapDefaultRedisManager 应返回被替换的旧 manager")
}
if GetDefaultRedisManager() != next {
t.Fatal("SwapDefaultRedisManager 应安装新的默认 manager")
}
if old.Client() != client {
t.Fatal("SwapDefaultRedisManager 不应关闭旧 Redis manager，旧资源需可用于失败回滚")
}
}
database/redis_manager_internal_test.go
+45
View File
@@ -0,0 +1,45 @@
package database
import (
"context"
"net"
"strconv"
"testing"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/alicebob/miniredis/v2"
)
func redisTestConfig(t *testing.T, addr string) *config.Config {
t.Helper()
host, portText, err := net.SplitHostPort(addr)
if err != nil {
t.Fatalf("split redis addr: %v", err)
}
port, err := strconv.Atoi(portText)
if err != nil {
t.Fatalf("parse redis port: %v", err)
}
return &config.Config{Redis: config.RedisConfig{Host: host, Port: port}}
}
func TestRedisManagerInitClosesPreviousClient(t *testing.T) {
mr1 := miniredis.RunT(t)
mr2 := miniredis.RunT(t)
m := NewRedisManager()
if err := m.Init(redisTestConfig(t, mr1.Addr())); err != nil {
t.Fatalf("first Init: %v", err)
}
first := m.Client()
if first == nil {
t.Fatal("first client is nil")
}
if err := m.Init(redisTestConfig(t, mr2.Addr())); err != nil {
t.Fatalf("second Init: %v", err)
}
if err := first.Ping(context.Background()).Err(); err == nil {
t.Fatal("first client still usable after second Init; old Redis pool was not closed")
}
}
database/redis_test.go
+66
View File
@@ -0,0 +1,66 @@
package database_test
import (
"context"
"sync"
"testing"
"github.com/EthanCodeCraft/xlgo-core/database"
)
func TestCloseRedisWithoutInit(t *testing.T) {
if err := database.CloseRedis(); err != nil {
t.Fatalf("CloseRedis without init should not error: %v", err)
}
if database.GetRedis() != nil {
t.Fatal("expected Redis client nil")
}
}
func TestHealthCheckRedisWithoutInit(t *testing.T) {
if err := database.HealthCheckRedis(context.Background()); err == nil {
t.Fatal("expected health check error without Redis init")
}
}
func TestRedisNilConfigReturnsError(t *testing.T) {
prev := database.SetTestRedisClient(nil)
t.Cleanup(func() { database.SetTestRedisClient(prev) })
if err := database.NewRedisManager().Init(nil); err == nil {
t.Fatal("RedisManager.Init(nil) 应返回错误")
}
if err := database.InitRedis(nil); err == nil {
t.Fatal("包级 InitRedis(nil) 应返回错误")
}
if err := database.HealthCheckRedis(nil); err == nil {
t.Fatal("未初始化 Redis 时 HealthCheckRedis(nil) 应返回错误")
}
}
// TestDefaultRedisConcurrentSetAndGet C-1/H-4 回归：并发 SetDefaultRedisManager
// 与 GetRedis/CloseRedis/HealthCheckRedis facade 读取不应触发数据竞争。
// 修复前 DefaultRedis 是裸 *Redis.Pointer，SetDefaultRedisManager 无锁写、
// facade 无锁读，-race 必采。修复后 atomic.Pointer 保护。
func TestDefaultRedisConcurrentSetAndGet(t *testing.T) {
// 保存并恢复默认 manager，避免污染其他测试。
orig := database.NewRedisManager()
database.SetDefaultRedisManager(orig)
// 不设 client，GetRedis 返回 nil；本用例只验证读写无竞态。
var wg sync.WaitGroup
for i := 0; i < 20; i++ {
wg.Add(2)
go func() {
defer wg.Done()
database.SetDefaultRedisManager(database.NewRedisManager())
}()
go func() {
defer wg.Done()
_ = database.GetRedis()
_ = database.CloseRedis()
_ = database.HealthCheckRedis(context.Background())
}()
}
wg.Wait()
}
database/retry_internal_test.go
+38
View File
@@ -0,0 +1,38 @@
package database
import (
"errors"
"testing"
)
func TestIsTransientDBError(t *testing.T) {
tests := []struct {
name string
err error
want bool
}{
{"nil", nil, true},
{"access denied", errors.New("Error 1045: Access denied for user 'root'@'localhost'"), false},
{"auth plugin", errors.New("authentication plugin 'caching_sha2_password' cannot be loaded"), false},
{"unknown database", errors.New("Error 1049: Unknown database 'foo'"), false},
{"invalid DSN", errors.New("invalid DSN: missing the slash separating the database name"), false},
{"unknown driver", errors.New("sql: unknown driver \"foobar\" (forgotten import?)"), false},
{"connection refused (transient)", errors.New("dial tcp 127.0.0.1:3306: connect: connection refused"), true},
{"i/o timeout (transient)", errors.New("dial tcp 10.0.0.1:3306: i/o timeout"), true},
{"empty msg", errors.New(""), true},
// P1 #12：PG 目标库不存在应视为非瞬态（不重试）。
{"pg database not exist", errors.New(`FATAL: database "app" does not exist (SQLSTATE 3D000)`), false},
{"pg password auth failed", errors.New("FATAL: password authentication failed for user \"app\""), false},
// P1 #12 回归核心：含 "database" 但是瞬态的错误必须仍被判为瞬态（可重试），
// 修复前独立 "database" 子串会把它误判为非瞬态而放弃重试。
{"pg starting up (transient)", errors.New("FATAL: the database system is starting up (SQLSTATE 57P03)"), true},
{"pg in recovery (transient)", errors.New("FATAL: the database system is in recovery mode"), true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := isTransientDBError(tt.err); got != tt.want {
t.Errorf("isTransientDBError(%v) = %v, want %v", tt.err, got, tt.want)
}
})
}
}
database/tls.go
+72
View File
@@ -0,0 +1,72 @@
package database
import (
"crypto/tls"
"crypto/x509"
"fmt"
"os"
"strings"
"github.com/EthanCodeCraft/xlgo-core/config"
mysqldriver "github.com/go-sql-driver/mysql"
)
// ensureMySQLTLSRegistered 按 cfg.Database 的 TLS 配置注册命名 TLS 配置到 go-sql-driver/mysql（M-config-2）。
//
// go-sql-driver/mysql v1.7.0 的 tls DSN 参数语义：
// - tls=true：内置安全（&tls.Config{}，系统根 CA + ServerName 自动取自 host + 证书校验），无需注册。
// - tls=<name>：引用经 RegisterTLSConfig 注册的命名配置，用于私有 CA/自签证书。
//
// 本函数仅在「TLS=true 且 TLSRootCA 非空」时注册 config.MySQLTLSConfigName 命名配置：
// 加载 TLSRootCA 的 PEM 到 RootCAs，ServerName 取自 Host，MinVersion=TLS1.2。其余情况（TLS 未启用、
// 或启用但用内置 tls=true）直接返回 nil。
//
// 非 MySQL 驱动（如 postgres，用 SSLMode）跳过。失败返回错误，由 initDB fail-fast，
// 绝不静默回退明文连接（生产 DB 流量明文是安全风险）。
//
// 注意：RegisterTLSConfig 是驱动级全局状态——一个名字对应唯一 *tls.Config（含唯一 ServerName），
// 同名重复注册会覆盖前者且不报错，故无法用「同名」同时匹配多个不同 host。
//
// 覆盖范围（注册配置的 ServerName 固定取自主库 Host）：
// - 单 host 集群：replica DSN 的 host 与主库 Host 相同（同机不同端口，或经同一 LB/主机名暴露）——
// master 与 replica DSN 均用 tls=MySQLTLSConfigName，ServerName 一致，握手通过。
// - 多 host replicas + 私有 CA：replica DSN 的 host 与主库 Host 不同时，本注册的 ServerName（主库
// host）与 replica 证书 SAN 不匹配，握手失败。此场景须用户为每个 replica host 注册**不同名**的
// TLS 配置（各自 ServerName=该 replica host）并自行构造对应 replica DSN（tls=<该名>）；框架
// MySQLDSN() 硬编码 tls=MySQLTLSConfigName，不能用于这些 replica DSN。切勿对 MySQLTLSConfigName
// 同名重复注册——会覆盖主库注册、导致主库握手失败。
//
// replica 路径（InitDBWithReplicas 的 replicaDSNs）由调用方传原始 DSN，不经本函数注册。
// 多集群不同 CA 亦属已知多 App 限制，需用户按上述方式自行注册。
func ensureMySQLTLSRegistered(cfg *config.Config) error {
if cfg == nil {
return nil
}
db := &cfg.Database
if !db.TLS || strings.TrimSpace(db.TLSRootCA) == "" {
return nil
}
// 仅 MySQL 走注册路径；postgres 用 SSLMode，其他驱动自管 TLS。空 driver 默认 MySQL。
drv := normalizeDriver(db.Driver)
if drv != "" && drv != DriverMySQL {
return nil
}
pem, err := os.ReadFile(db.TLSRootCA)
if err != nil {
return fmt.Errorf("读取 MySQL TLS CA 文件失败 %q: %w", db.TLSRootCA, err)
}
pool := x509.NewCertPool()
if !pool.AppendCertsFromPEM(pem) {
return fmt.Errorf("解析 MySQL TLS CA 文件失败 %q: 非 PEM 格式或无有效证书", db.TLSRootCA)
}
tlsCfg := &tls.Config{
RootCAs: pool,
ServerName: db.Host,
MinVersion: tls.VersionTLS12, // 禁用 TLS1.0/1.1，符合安全基线
}
if err := mysqldriver.RegisterTLSConfig(config.MySQLTLSConfigName, tlsCfg); err != nil {
return fmt.Errorf("注册 MySQL TLS 配置 %q 失败: %w", config.MySQLTLSConfigName, err)
}
return nil
}
database/tls_internal_test.go
+146
View File
@@ -0,0 +1,146 @@
package database
import (
"crypto/rand"
"crypto/rsa"
"crypto/x509"
"crypto/x509/pkix"
"encoding/pem"
"math/big"
"os"
"path/filepath"
"strings"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
mysqldriver "github.com/go-sql-driver/mysql"
)
// writeSelfSignedCAPEM 生成一个自签名 CA 证书并写入临时 PEM 文件，返回路径。
func writeSelfSignedCAPEM(t *testing.T) string {
t.Helper()
key, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
t.Fatalf("rsa.GenerateKey: %v", err)
}
tmpl := &x509.Certificate{
SerialNumber: big.NewInt(1),
Subject: pkix.Name{CommonName: "xlgo-test-ca"},
NotBefore: time.Now().Add(-time.Hour),
NotAfter: time.Now().Add(time.Hour),
IsCA: true,
}
der, err := x509.CreateCertificate(rand.Reader, tmpl, tmpl, &key.PublicKey, key)
if err != nil {
t.Fatalf("x509.CreateCertificate: %v", err)
}
p := filepath.Join(os.TempDir(), "xlgo_tls_ca_test.pem")
if err := os.WriteFile(p, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der}), 0644); err != nil {
t.Fatalf("WriteFile: %v", err)
}
return p
}
// TestEnsureMySQLTLSRegistered_NoOpCases 固化 M-config-2：非 MySQL / 未启用 TLS / 无 CA 时
// ensureMySQLTLSRegistered 为 no-op，不注册、不报错。
func TestEnsureMySQLTLSRegistered_NoOpCases(t *testing.T) {
if err := ensureMySQLTLSRegistered(nil); err != nil {
t.Errorf("nil cfg 应 no-op, got %v", err)
}
mysqlNoTLS := &config.Config{Database: config.DatabaseConfig{
Driver: "mysql", Host: "h", Port: 3306, User: "u", Password: "p", Name: "n",
}}
if err := ensureMySQLTLSRegistered(mysqlNoTLS); err != nil {
t.Errorf("TLS=false 应 no-op, got %v", err)
}
mysqlBuiltIn := &config.Config{Database: config.DatabaseConfig{
Driver: "mysql", Host: "h", Port: 3306, User: "u", Password: "p", Name: "n",
TLS: true, // 无 TLSRootCA，用内置 tls=true
}}
if err := ensureMySQLTLSRegistered(mysqlBuiltIn); err != nil {
t.Errorf("TLS=true 无 CA 应 no-op（内置 tls=true）, got %v", err)
}
// postgres 用 SSLMode，不走 MySQL TLS 注册
pg := &config.Config{Database: config.DatabaseConfig{
Driver: config.DriverPostgres, Host: "h", Port: 5432, User: "u", Password: "p", Name: "n",
TLS: true, TLSRootCA: "/path/ca.pem",
}}
if err := ensureMySQLTLSRegistered(pg); err != nil {
t.Errorf("postgres 应跳过 MySQL TLS 注册, got %v", err)
}
// 空 driver（默认 MySQL）+ 无 TLS：no-op
emptyDrv := &config.Config{Database: config.DatabaseConfig{
Host: "h", Port: 3306, User: "u", Password: "p", Name: "n",
}}
if err := ensureMySQLTLSRegistered(emptyDrv); err != nil {
t.Errorf("空 driver 无 TLS 应 no-op, got %v", err)
}
}
// TestEnsureMySQLTLSRegistered_BadCA 固化 M-config-2：CA 文件不可读或非 PEM 时 fail-fast，
// 绝不静默回退明文连接。
func TestEnsureMySQLTLSRegistered_BadCA(t *testing.T) {
missing := &config.Config{Database: config.DatabaseConfig{
Driver: "mysql", Host: "h", Port: 3306, User: "u", Password: "p", Name: "n",
TLS: true, TLSRootCA: "/no/such/ca.pem",
}}
if err := ensureMySQLTLSRegistered(missing); err == nil || !strings.Contains(err.Error(), "读取") {
t.Fatalf("CA 文件不存在应报读取错误, got: %v", err)
}
nonPEM := filepath.Join(os.TempDir(), "xlgo_tls_nonpem.pem")
if err := os.WriteFile(nonPEM, []byte("this is not a pem file"), 0644); err != nil {
t.Fatalf("WriteFile: %v", err)
}
bad := &config.Config{Database: config.DatabaseConfig{
Driver: "mysql", Host: "h", Port: 3306, User: "u", Password: "p", Name: "n",
TLS: true, TLSRootCA: nonPEM,
}}
if err := ensureMySQLTLSRegistered(bad); err == nil || !strings.Contains(err.Error(), "解析") {
t.Fatalf("非 PEM 文件应报解析错误, got: %v", err)
}
}
// TestEnsureMySQLTLSRegistered_ResolvesViaParseDSN 固化 M-config-2 端到端：
// 注册前 ParseDSN(tls=xlgo-mysql) 报 unknown config name；注册后成功解析且 TLS 非 nil。
// 利用 go-sql-driver/mysql 的 TLS 解析发生在 ParseDSN 的 normalize() 阶段，无需真实 DB 连接。
func TestEnsureMySQLTLSRegistered_ResolvesViaParseDSN(t *testing.T) {
caPath := writeSelfSignedCAPEM(t)
defer os.Remove(caPath)
// 清理同名残留注册，保证「注册前」断言不被前序测试污染
mysqldriver.DeregisterTLSConfig(config.MySQLTLSConfigName)
defer mysqldriver.DeregisterTLSConfig(config.MySQLTLSConfigName)
cfg := &config.Config{Database: config.DatabaseConfig{
Driver: "mysql", Host: "127.0.0.1", Port: 3306, User: "u", Password: "p", Name: "n",
TLS: true, TLSRootCA: caPath,
}}
dsn := cfg.Database.DSN()
if !strings.Contains(dsn, "tls="+config.MySQLTLSConfigName) {
t.Fatalf("DSN 应含 tls=%s: %s", config.MySQLTLSConfigName, dsn)
}
// 注册前：ParseDSN 应报 unknown config name
if _, err := mysqldriver.ParseDSN(dsn); err == nil {
t.Fatal("注册前 ParseDSN 不应成功（未知 TLS 配置名）")
} else if !strings.Contains(err.Error(), "unknown config name") {
t.Logf("注册前 ParseDSN 错误（预期未知配置名）: %v", err)
}
// 注册后：ParseDSN 成功，TLS 已解析为非 nil
if err := ensureMySQLTLSRegistered(cfg); err != nil {
t.Fatalf("ensureMySQLTLSRegistered: %v", err)
}
mc, err := mysqldriver.ParseDSN(dsn)
if err != nil {
t.Fatalf("注册后 ParseDSN 应成功, got: %v", err)
}
if mc.TLS == nil {
t.Error("注册后 ParseDSN 的 TLS 配置应为非 nil（CA 已注册）")
}
if mc.TLS.ServerName != "127.0.0.1" {
t.Errorf("TLS ServerName = %q, want 127.0.0.1", mc.TLS.ServerName)
}
}
docs/plans/Version_Update_Plan_v1.0.2.md
+1047
View File
File diff suppressed because it is too large Load Diff
docs/plans/Version_Update_Plan_v1.1.0.md
+128
View File
@@ -0,0 +1,128 @@
# xlgo v1.1.0 实施计划 — HA & Manager 化
> 本文件为 v1.1.0 版本的逐项实施计划，对应体检报告（`docs/plans/Version_v1.0.2_report.md`）第三~四章 #10-#24 架构/HA 改进。
> 范围：13 项（#20 RedisRateLimiter、#23 Recover 带 request_id 已实现，本次核对配合）。
## Context
v1.0.3（bug fix）与 v1.0.4（DX & Docs）已发布推送，GitHub Release 已创建，工作区干净。v1.0.2 体检报告规划的 v1.1.0 阶段共 13 项架构/HA 改进，目标是把 xlgo 从"一半组件可注入、一半是单例"的撕裂状态，贯彻到"通用 / 高可用 / 易上手"。
本次一次性推完 13 项，发 v1.1.0。已确认的边界决策：
- **版本策略**：v1.1.0 接受少量 breaking（#11 删 wire 包、#14 删 `AppConfig.TokenExpire`、删 `StartServerWithPort`/`GracefulShutdown`、`JWTConfig.Expire` 类型变更），在 CHANGELOG「升级说明」章节列出；其余（#15 response）用全局开关默认兼容存量。
- **#10 Manager 化**：storage/cache/redis/jwt/logger **5 个全做**（含 logger），照 `database.Manager` + 包级 facade 蓝本。
- **#15 response**：全局 `SetMode(ModeBusiness|ModeREST)`，默认 `ModeBusiness`（现状全 200 + 业务码）兼容；`ModeREST` 下 401/404/500 返回对应 HTTP status，body 仍带业务码。可在 `ServerConfig.ResponseMode` 配置。
- **#11 wire**：删掉整个 `wire` 包（其事 App Option 已覆盖）。
- **#18**：接受 `prometheus/client_golang` 新依赖。
- **#12**：只提供 `WithHook(Hook{...})` 机制，不引入 etcd 依赖、不提供内置示例。
## 实现方案（按依赖顺序分 6 组）
### 组 1：配置层（其余项的基础）
**#13 Server 参数配置化** — `config/config.go:84-88`
`ServerConfig` 增字段：`ReadTimeout/WriteTimeout/IdleTimeout/ShutdownTimeout/MaxHeaderBytes`、`TLS{Enabled,CertFile,KeyFile}`、`UnixSocket string`、`ResponseMode string`。`app.go:408-414` 的 `http.Server` 改为读这些字段（缺省回退到当前硬编码值）。TLS 开启时用 `ListenAndServeTLS`；`UnixSocket` 非空时优先 unix socket。Shutdown 超时读 `ShutdownTimeout`。
**#14 JWTConfig.Expire time.Duration + 删 TokenExpire** — `config/config.go:44, 209-213`
`JWTConfig.Expire` 改 `time.Duration`（mapstructure + viper string 解析 `"24h"`），新增 `RefreshExpire time.Duration`、`Issuer`、`Algorithm`。**删 `AppConfig.TokenExpire`**（breaking）。`jwt/jwt.go` 内过期取值改读 `JWTConfig.Expire`。Duration 解析依赖 mapstructure decode hook。
**#16 Config Validate** — 新增 `config/config.go` `(*Config).Validate() error`
校验：`Server.Port` 范围、`JWT.Secret` 非空且 ≥32 字符（启用 jwt 时）、启用 mysql 时关键字段、Duration 非负等。`config.Manager.Load`（`config/manager.go:340`）解析后自动调用，错误包裹返回，把"运行时第一次请求才暴露"提前到启动。
**#15 response Mode 开关** — `response/response.go`
新增 `type Mode int`、`ModeBusiness/ModeREST`、包级 `currentMode` + `SetMode(m)`、`Mode()`。`Fail/Unauthorized/NotFound/ServerError/RateLimit/FailWithCode` 内：`ModeREST` 时按错误码/错误类型映射 HTTP status（`ErrUnauthorized→401`、`ErrNotFound→404`、`ErrServer→500`、`ErrRateLimit→429`、参数类→400），`c.JSON(status, Response{...})`；`ModeBusiness` 维持 200。`App.Init` 末尾按 `ServerConfig.ResponseMode` 调 `response.SetMode`。新增 `response.Custom(c, httpStatus, code, data)` 显式 API。
### 组 2：组件 Manager 化（#10，5 组件，照 database.Manager 蓝本）
蓝本参考 `database/manager.go:180-192`（`DefaultManager` 包级实例 + `SetDefaultManager` + 包级 facade 代理 + 实例方法）。每个组件统一模式：
- 新增 `type Manager struct{ ...; mu sync.Mutex }` + `var DefaultXxx = &Manager{}`
- `SetDefaultManager(m)` 提升用户实例到全局
- 包级 `Init/Get/操作` 函数代理到 `DefaultXxx`（**保留，兼容存量**）
- `App` 持有各 Manager 实例（`App` 加字段），`WithXxx` 时初始化 App 自己的实例并 `SetDefaultXxx`
顺序（按依赖）：**redis → cache → jwt → storage → logger**
1. **redis** — `database/redis.go`：新增 `type RedisManager struct{ cfg; client *redis.Client; mu }` + `DefaultRedis`。`InitRedis/CloseRedis/GetRedis/HealthCheckRedis` 代理。下游 5 处直接读 `database.RedisClient`（`jwt/jwt.go`、`middleware/ratelimit.go`、`cache/cache.go`、`cache/lock.go` 20+ 处、`app.go`）全部改为 `database.GetRedis()`。`cache/lock.go` 改为接受 `*redis.Client` 参数或内部 `GetRedis()`。
2. **cache** — `cache/cache.go`：`type CacheManager struct{ client *redis.Client; svc CacheService; mu }` + `DefaultCache`。`redisCache.client` 从硬编码 `database.RedisClient` 改为构造时注入。`Init/GetCache` 代理。`cache/lock.go` 的分布式锁函数改走 `DefaultCache` 或显式传 client。
3. **jwt** — `jwt/jwt.go`：`type Manager struct{ blacklist *TokenBlacklist; cfg *config.JWTConfig; mu }` + `DefaultJWT`。`TokenBlacklist.Add/IsBlacklisted` 内部 `database.RedisClient` 改 `database.GetRedis()`。`GenerateToken/ParseToken/InvalidateToken/RefreshToken/...` 代理到 `DefaultJWT`。
4. **storage** — `storage/storage.go`：`type Manager struct{ cfg; current Storage; mu }` + `DefaultStorage`。`Init/GetStorage/SetStorage/Upload/...` 代理到 `DefaultStorage.current`。最干净，无外部下游。
5. **logger** — `logger/logger.go`：`type Manager struct{ cfg; logger/apiLog/dbLog *zap.Logger; fileWriters; mu }` + `DefaultLogger`。包级 `Init/Sync/Close/Info/.../APILog/DBLog` 代理。**特殊**：logger 是 `App.Init` 最先初始化的组件，`DefaultLogger` 初始化前包级函数须安全降级到 Nop（现状 `Close()` 已重置为 Nop，沿用）。下游 8 包的 `logger.Info(...)` 调用点无需改（仍走包级 facade）。
`App` struct（`app.go:41-62`）加字段：`redisMgr *database.RedisManager`、`cacheMgr *cache.CacheManager`、`jwtMgr *jwt.Manager`、`storageMgr *storage.Manager`、`loggerMgr *logger.Manager`。
### 组 3：App 生命周期
**#12 Lifecycle Hooks** — `app.go`
新增 `type Hook struct{ Name string; OnInit func(*App) error; OnStart func(*App) error; OnReady func(*App); OnStop func(*App) error }` + `WithHook(Hook) Option`。`App` 加 `hooks []Hook`。`Init()` 内组件初始化完成后按序调 `OnInit`；`StartServer` 监听前调 `OnStart`，端口就绪后调 `OnReady`；`Shutdown` 开头调 `OnStop`。各 hook 错误中断流程并返回。
**#22 App.Go + in-flight goroutine** — `app.go`
`App` 加 `wg sync.WaitGroup` + `ctx context.Context`（根 ctx）+ `cancel`。新增 `App.Go(fn func(ctx context.Context))`：`wg.Add(1); go func(){ defer wg.Done(); fn(ctx) }()`。`Shutdown` 在 `OnStop` 后、关 HTTP 前调 `cancel()` 并 `wg.Wait()`（带 `ShutdownTimeout` 超时）。
**#11 删 wire 包** — 删 `wire/wire.go`（整包）。清理 `app.go` 的 `WithWire/WithoutWire/enableWire` 及 `Init()` 中 `wire.InitServices()` 调用。`cache.Init()` 原由 wire 触发，改由 `WithRedis`/`WithCache` 触发（或 `App.Init` 显式调）。
**清理双轨** — `app.go:494-537`：删 `StartServerWithPort`、`GracefulShutdown`（与 `App.StartServer`/`App.Shutdown` 重复）。breaking，升级说明列出。
### 组 4：中间件与路由
**#24 RequestID 默认装入** — `app.go:~348`
`App.Init` 中间件链改为无条件 `a.router.Use(middleware.RequestID())`（在 Recovery 之前），让每个响应/panic 日志都带 request_id。核对 #23：`middleware/recover.go:20` 已 `GetRequestID(c)`，配合 #24 后 panic 日志 request_id 非空。移除 `gin.Recovery()` 双重保险（保留 `middleware.Recover()` 一个即可）。
**#19 请求级 Timeout 中间件** — 新增 `middleware/timeout.go`
`func Timeout(d time.Duration) gin.HandlerFunc`：`ctx, cancel := context.WithTimeout(c.Request.Context(), d); defer cancel(); c.Request = c.Request.WithContext(ctx); c.Next()`。可通过 `WithRequestTimeout(d)` Option 装入全局，下游 GORM/Redis 走 `c.Request.Context()` 级联取消。
**#18 Prometheus metrics** — 新依赖 `prometheus/client_golang`
新增 `middleware/metrics.go`：`middleware.Metrics()` 记录 HTTP latency / status code / in-flight（histogram + counter + gauge）。新增 `router/metrics.go`：`RegisterMetricsRoute(r, path...)` 默认 `/metrics` 挂 `promhttp.Handler()`。新增 `WithMetricsRoute(path...)` Option。`App.Init` 装入 `Metrics()` 中间件 + 路由。
**#17 livez/readyz** — `router/router.go`
新增 `RegisterLivenessRoute(r)` → `GET /livez` 永不依赖外部（进程存活即 200）。新增 `RegisterReadinessRoute(r, checks...)` → `GET /readyz` 复用 `HealthCheck`，失败 503。新增 `WithLivenessRoute()`/`WithReadinessRoute()` Option。`/health` 保留兼容。`livez` 不查依赖、`readyz` 查依赖，对 K8s probe 友好。
### 组 5：依赖健康自愈（#21）
**#21 主库探活 + replica 健康剔除** — `database/manager.go`
- `database.Manager` 加 `healthy bool` + `consecutiveFailures int` + `healthMu`。`Pool.SetConnMaxIdleTime` 配置化（`DatabaseConfig` 加 `ConnMaxIdleTime`）。
- 探活：`App.Init` 末尾用 `App.Go` 起后台 goroutine，每 30s `HealthCheck(ctx)`，连续 N 次失败标记 `healthy=false`；`readyz`/`/health` 读此标记返回 503。
- `ReplicaPicker` 接口加健康度：replica ping 失败剔除轮询，恢复后重新纳入。`RoundRobinPicker`/`RandomPicker` 实现 health-aware 选取。
### 组 6：收尾与发版
- `app.go:27` `const Version = "1.1.0"`。
- `CHANGELOG.md` 加 `[1.1.0]` 章节（Added/Changed/Fixed + **升级说明** breaking 列表）。README 更新日志 + 底部链接。
- `examples/`（full/minimal）同步：full 例子的配置文件加 `server.read_timeout` 等新字段、`jwt.expire: 24h`，验证 5 组件 Manager 化后仍可跑。
- 测试：`go test ./...` 全绿；为 Manager 化、Validate、response Mode、livez/readyz、metrics、timeout、App.Go 补单测。
- `go mod tidy`。
## 关键文件清单
| 文件 | 涉及 issue |
|---|---|
| `app.go` | #10 App 字段、#12 hooks、#13 server、#19/#18/#17/#24 路由中间件、#21 探活、#22 App.Go、#11 删 wire、删双轨、Version |
| `config/config.go` | #13 ServerConfig、#14 JWTConfig+删TokenExpire、#16 Validate |
| `config/manager.go` | #16 Load 调 Validate、Duration decode hook |
| `response/response.go` | #15 Mode 开关 + status 映射 |
| `database/redis.go` | #10 redis Manager |
| `database/manager.go` | #21 探活 + replica 健康剔除 |
| `cache/cache.go` `cache/lock.go` | #10 cache Manager + 解耦 RedisClient |
| `jwt/jwt.go` | #10 jwt Manager + #14 Expire |
| `storage/storage.go` | #10 storage Manager |
| `logger/logger.go` | #10 logger Manager |
| `middleware/{requestid,recover}.go` | #24 装入 + #23 核对 |
| `middleware/timeout.go`(新) | #19 |
| `middleware/metrics.go`(新) | #18 |
| `router/router.go` `router/metrics.go`(新) | #17 livez/readyz + #18 /metrics |
| `wire/wire.go` | #11 删除 |
| `go.mod` | #18 prometheus 依赖 |
| `CHANGELOG.md` `README.md` | 发版 |
## 验证
1. `go mod tidy && go build ./...` — 编译通过。
2. `go test ./...` — 全绿，含新增单测。
3. `go run ./example`（full 栈）— 启动无错，`/livez`→200、`/readyz`→200（依赖在时）、`/metrics`→prometheus 文本、`/health` 兼容；配置错误时 `Validate` 在启动期拦截。
4. 手动验证 breaking：删 wire 后 `example` 不再 import wire；`AppConfig.TokenExpire` 删除后 grep 无残留；`response.SetMode(ModeREST)` 下 `Unauthorized` 返回 401。
5. `App.Go` 起一个长任务 goroutine，发 SIGTERM，确认 `Shutdown` 等其退出（日志可见）。
6. 主库探活：手动关 mysql，30s 后 `/readyz`→503、`/health`→503；恢复后自动转 200。
7. 发版：commit + annotated tag `v1.1.0` → `git push xlgo-core main && git push xlgo-core v1.1.0`；release 内容写本地 `gitHub_release_v1.1.0.md`（.gitignore 忽略），用户网页创建。
docs/plans/Version_v1.0.2_report.md
+519
View File
@@ -0,0 +1,519 @@
# xlgo v1.0.2 体检报告
> 资深 Go 视角的代码与架构 Review。目标是把 xlgo 从"业务沉淀工具集"打磨成"通用 / 高可用 / 易上手"的开源 Web 框架。
>
> 整体判断：v1.0.2 已经把"业务耦合 + 不可组合 + 框架内 Fatal"这三个最大的设计债还掉了，框架骨架是健康的。但仍有若干**真实 Bug**和**架构层面的债**，按下方优先级逐项核查即可。
---
## 一、必须立刻修的真实 Bug（带行号）
这些不是设计取舍，是确凿的缺陷，先于一切改进。
### 1. `response.CodeSuccess` 与 `CodeInvalidParams` 撞码 ⚠️
```go
// response/error.go:13-16
CodeSuccess = 1 // 成功
CodeFail = 0 // 通用失败
CodeInvalidParams = 1 // 参数错误 ← 跟 Success 同值！
```
只要任何业务调用 `response.FailWithError(c, response.ErrInvalidParams)`，前端拿到的 `code` 跟成功响应一模一样。这是**生产级 bug**。
**建议**：制定明确的码段策略——
- `0` = success（业内更通用），或者 `200`/`0` 二选一
- `1` 留给"通用失败"
- 参数错误使用 `40001` 等业务码段
- 同时为了避免后续重复，写一个 `init()` 自检：
```go
func init() {
seen := map[int]string{}
for code, name := range allErrorCodes {
if old, ok := seen[code]; ok {
panic(fmt.Sprintf("duplicate error code %d: %s vs %s", code, old, name))
}
seen[code] = name
}
}
```
### 2. CORS 中 `Allow-Credentials` 永远是 `true` ⚠️
```go
// middleware/cors.go:86-91
if corsConfig != nil && corsConfig.AllowCredentials {
c.Header("Access-Control-Allow-Credentials", "true")
} else {
c.Header("Access-Control-Allow-Credentials", "true") // 默认允许 ← 错
}
```
并且当 `Origin: *` 时还会被浏览器拒绝。这是 CORS 经典坑。**修复**：
```go
if corsConfig.AllowCredentials && allowedOrigin != "*" {
c.Header("Access-Control-Allow-Credentials", "true")
}
```
### 3. 日志在开发模式下写两份到同一文件链 ⚠️
```go
// logger/logger.go:95-99
core := zapcore.NewTee(apiCore, dbCore, consoleCore)
Logger = zap.New(core, ...)
```
`Logger` 是全局通用 logger，但 Tee 把 dbCore 也接进去——结果**所有 `logger.Info(...)` 都会同时写到 `api.log` 和 `database.log`**，再加一份控制台。`APILog()`/`DBLog()` 的"分流"形同虚设。
**修复**：通用 logger 只写 console + 一个 app.log；`APILog()`/`DBLog()` 各自独立 core，互不 Tee。
### 4. `DBResolver.BeforeQuery` 是死代码 ⚠️
```go
// database/mysql.go:386-408
func (r *DBResolver) BeforeQuery(db *gorm.DB) { ... }
```
这个 hook 从未通过 `db.Callback().Query().Before(...)` 注册过。所以**读写分离实际上需要业务侧自己调用 `GetDBFromContext(ctx)`**，但 README/GUIDE 暗示它会自动路由。要么把 hook 真正注册上，要么把这段代码删掉、文档明确"显式 `UseReplica/UseMaster`"。
我倾向**删掉**——GORM 官方有 `dbresolver` plugin，实现得更完整（权重、policy）。引入它比自造轮子更稳。
### 5. 重试策略对所有错误一视同仁
```go
// database/mysql.go:213-240
maxRetries := 5
// 不论是 driver 错、密码错、端口错都重试 5 次，指数退避
```
**密码错误**也会让进程在启动阶段死等 1 分钟才报错，体验很差。建议区分：
- `*mysql.MySQLError` Code 1045（access denied）/ 1049（unknown db）等 → 直接返回，不重试
- `net.OpError`、`io.EOF`、上下文未到等 → 重试
### 6. `generateJTI` 忽略 `rand.Read` 错误
```go
// jwt/jwt.go:40-44
func generateJTI() string {
bytes := make([]byte, 16)
rand.Read(bytes) // ← 错误丢弃
return base64.URLEncoding.EncodeToString(bytes)
}
```
`crypto/rand.Read` 在 Linux 早期启动或某些容器中**确实会失败**。失败时 JTI 会是全零，黑名单可能误判。改为返回 `(string, error)` 或在失败时 `panic` 都比静默吞错好。
### 7. `repository.QueryBuilder.Page` 的 Count 受残留 limit 影响
```go
// repository/repository.go:404-417
countDB := qb.db.Session(&gorm.Session{}) // ← 复用了已 Limit/Offset 的 db
if err := countDB.WithContext(ctx).Count(&total).Error; err != nil { ... }
```
如果用户先 `.Limit(10)` 再 `.Page(...)`，`countDB` 会带 LIMIT，Count 是错的。需要 `Limit(-1).Offset(-1).Order("")`：
```go
countDB := qb.db.Session(&gorm.Session{}).Limit(-1).Offset(-1).Order("")
```
### 8. `OSSStorage.Upload` 文件名冲突风险
```go
// storage/storage.go:205
objectKey := fmt.Sprintf("%s/%d%s", filepath.Join(...), now.UnixNano(), ext)
```
并发上传 / 容器集群同纳秒会产生**完全相同的 key**，OSS 会覆盖。补一个随机后缀或 uuid：
```go
objectKey := fmt.Sprintf("%s/%d-%s%s", dir, now.UnixNano(), randHex(8), ext)
```
### 9. `go.mod` indirect 里的可疑版本
```
google.golang.org/genproto/googleapis/api v0.0.0-20260401024825-9d38bb4040a9
```
这是 2026-04-01 的 pseudo-version，搭配 `golang.org/x/crypto v0.49.0`、`golang.org/x/net v0.52.0` 看起来正常，但需要确认这是 OTel 1.43 强制带来的传递依赖，还是历史 `go.sum` 没整理。建议跑一次 `go mod tidy && go mod verify` 之后人工 review。
---
## 二、架构层面的"债"（影响通用性与多实例化）
v1.0.2 把 config 和 database 改成了 Manager + 全局 facade 的双轨，但还有几个核心组件**没跟上这套抽象**：
### 10. Storage / Cache / Redis / JWT / Logger 仍是单例
| 组件 | 全局变量 | 多实例可能性 |
|---|---|---|
| `storage.storage` | 包级 var | 不能同时连 OSS + 本地 |
| `cache.globalCache` | 包级 var | 不能为不同业务设不同 prefix/TTL 默认值 |
| `database.RedisClient` | 包级 var | 不能多 Redis（缓存 + 队列 + 限流分库） |
| `jwt.tokenBlacklist` | 包级 var | 不能区分 user-token 和 refresh-token blacklist |
| `logger.Logger` | 包级 var | 不能区分多 app/多模块独立日志 |
**建议**：照 `database.Manager` + `database.DefaultManager` 的模式，每个组件提供 `XxxManager` 类型 + 全局便捷 facade，App 持有自己的 Manager 实例。这样：
- 单元测试可以注入 mock
- 多 App 共存（比如同进程跑 admin + api 两个 Engine）
- 微服务里组件解耦
优先级：**Redis Manager 最重要**（因为 JWT、Cache、RateLimiter、分布式锁都依赖它，目前全是访问 `database.RedisClient`，没法替换）。
### 11. `wire` 包名误导
```go
// wire/wire.go - 整个文件 32 行
func InitServices() { ... }
```
它叫 `wire`，但跟 Google Wire 没关系，也不是 DI 容器。新用户会困惑。建议二选一：
- **删掉**——其实现的事 App 通过 Option 已经做了
- **真正引入 Wire 或 fx/uber**——给一个最小 DI 范式
### 12. `App.Init()` / `App.Run()` 缺少 Lifecycle Hooks
现在的 App 内部是硬编码顺序：config → logger → mysql → redis → storage → wire → migrate → routes。如果用户想插入"Migrate 之前先初始化分布式锁，避免多副本同时迁移"或者"启动后注册到服务发现"，没有钩子。
**建议**（v1.1.0 路线）：
```go
type Hook struct {
Name string
OnInit func(*App) error // Init 流程内
OnStart func(*App) error // 监听端口前
OnReady func(*App) // 端口就绪后
OnStop func(*App) error // Shutdown 前
}
func WithHook(h Hook) Option
```
并提供两个内置示例：`hooks.RegisterEtcd(...)`、`hooks.RegisterDistributedMigrate(...)`。
### 13. Server 参数全部硬编码
```go
// app.go:400-406
ReadTimeout: 15 * time.Second,
WriteTimeout: 30 * time.Second,
IdleTimeout: 60 * time.Second,
```
加上 `Shutdown` 30s 超时。这些都该进 `ServerConfig`：
```yaml
server:
port: 8080
read_timeout: 15s
write_timeout: 30s
idle_timeout: 60s
shutdown_timeout: 30s
max_header_bytes: 1048576
tls:
enabled: false
cert_file: ""
key_file: ""
unix_socket: "" # 优先级高于 port
```
### 14. `JWTConfig.Expire` 与 `AppConfig.TokenExpire` 重复且单位不明
两个字段都是过期秒数，都没有 `time.Duration` 类型。Go 项目应优先用 `time.Duration` + viper 的 `string` 解析（`"24h"`、`"30m"`），**单位看就懂**：
```go
type JWTConfig struct {
Secret string `mapstructure:"secret"`
Expire time.Duration `mapstructure:"expire"` // "24h"
RefreshExpire time.Duration `mapstructure:"refresh_expire"` // "168h"
Issuer string `mapstructure:"issuer"`
Algorithm string `mapstructure:"algorithm"` // HS256/RS256
}
```
`AppConfig.TokenExpire` 直接删掉。
### 15. `response` 把 4xx/5xx 全压成 HTTP 200
```go
// response/response.go:32-39
func Success(c *gin.Context, data any) {
c.JSON(http.StatusOK, ...) // ← 永远 200
}
// Unauthorized / Fail / NotFound / ServerError 全部 200
```
这是国内典型"业务码 in body"的玩法，**对接 APM、Prometheus、APISIX/网关、Sentry 都很难受**——它们靠 HTTP status 区分异常。建议：
1. 默认仍保留业务码模式（兼容存量），但允许通过全局开关切到"REST 模式"：
```go
response.SetMode(response.ModeREST) // 或在 ServerConfig 中
// 401 错误 → 返回 HTTP 401, body 带业务 code
```
2. 或者更优雅：`Fail` 带一个明示的 HTTP status：
```go
response.Fail(c, response.ErrUnauthorized) // 自动 401
response.Custom(c, http.StatusBadRequest, ErrInvalidParams, nil)
```
### 16. 配置缺少 Validate
`config.Manager.Load` 解析完直接返回，对必填字段 / 取值范围都没校验。建议加 `Validate() error`：
```go
func (c *Config) Validate() error {
if c.Server.Port <= 0 || c.Server.Port > 65535 { ... }
if c.JWT.Secret != "" && len(c.JWT.Secret) < 32 { ... }
// 启用 mysql 时强制要求关键字段
return nil
}
```
并在 `Manager.Load` 内自动调用——配置错把启动时间从"运行时第一次请求"提前到"进程启动"，是高可用的小细节。
---
## 三、高可用 / 生产就绪的缺口
### 17. 没有 Liveness / Readiness 区分
v1.0.2 的 `/health` 只有一个，对 K8s 不友好。K8s probe 期望：
- `/livez`：进程是否活着（**永远不依赖外部**，只检查 goroutine、内存）
- `/readyz`：是否可以接流量（依赖 mysql/redis 通透）
建议在保持 `/health` 兼容的同时加：
```go
xlgo.WithLivenessRoute() // GET /livez
xlgo.WithReadinessRoute() // GET /readyz, 复用 healthChecks
```
### 18. 没有 Prometheus / Metrics 中间件
通用 Web 框架不带 metrics endpoint 是硬伤。建议：
```go
import "github.com/prometheus/client_golang/prometheus/promhttp"
func WithMetricsRoute(path ...string) Option // 默认 /metrics
```
并提供一个 `middleware.Metrics()`——HTTP latency、status code、in-flight 这些标配指标。
### 19. 没有请求级超时中间件
`http.Server.ReadTimeout` 是连接级。**业务级**超时需要 `middleware.Timeout(5*time.Second)`：
```go
func Timeout(d time.Duration) gin.HandlerFunc {
return func(c *gin.Context) {
ctx, cancel := context.WithTimeout(c.Request.Context(), d)
defer cancel()
c.Request = c.Request.WithContext(ctx)
c.Next()
}
}
```
下游 GORM/Redis 调用走 `c.Request.Context()` 才能真正级联取消。
### 20. RateLimiter 内存版无法集群共享
`middleware/ratelimit.go` 的 `RateLimiter` 是单进程内存版，多副本部署时限流器各管各的。Redis 版本（`RedisRateLimiter`）应该一并提供，并且：
- 用 lua 脚本实现 token bucket 或滑动窗口（避免多次 round-trip）
- 默认每个限流器有 `Name`，方便 Prometheus 上报"被限流次数"
### 21. 没有依赖健康自愈
主库宕机后 `database.Manager.master` 会一直握着断连。建议：
- `Pool.SetConnMaxIdleTime` 配置化
- 探活定时任务：每 30s ping 一次，连续 N 次失败标记"unhealthy"，readiness 立即返回 503
- Replica 健康剔除：`ReplicaPicker` 支持权重 + 健康度（v1.1.0 路线）
### 22. Graceful shutdown 没等业务 in-flight goroutine
现在 `Shutdown` 只关 HTTP server。如果业务在 handler 里 spawn 了后台 goroutine（异步发短信、写日志），它们会被进程退出强制砍掉。建议：
- App 暴露 `App.Go(fn func(ctx context.Context))`，内部维护 `sync.WaitGroup`
- Shutdown 时 `wg.Wait()` 带超时
### 23. `gin.Recovery` + `middleware.Recover` 双重保险但没 trace_id
panic 时只记录 stack，没有 request_id / trace_id 关联。建议 Recover 中间件改为：
```go
func Recover() gin.HandlerFunc {
return func(c *gin.Context) {
defer func() {
if r := recover(); r != nil {
rid := c.GetString("request_id")
logger.Error("panic recovered",
zap.String("request_id", rid),
zap.Any("error", r),
zap.ByteString("stack", debug.Stack()))
response.ServerError(c, "服务器内部错误")
}
}()
c.Next()
}
}
```
### 24. RequestID 中间件没默认装入
`response.go` 依赖 `c.GetString("request_id")` 但默认中间件链里没有这一环。建议 `app.Init` 时无条件 `Use(middleware.RequestID())`，让每个响应都带 `request_id`，trace 才有意义。
---
## 四、易上手 / 开发体验
### 25. 模块路径与 import alias 不一致
`go.mod` 是 `github.com/EthanCodeCraft/xlgo-core`，CLAUDE.md 又提"本地导入用 xlgo"——新用户第一次 `go mod tidy` 多半会撞墙。建议：
- 模块路径直接定为 `github.com/EthanCodeCraft/xlgo`（去掉 `-core`），**包名仍然 `xlgo`**
- README 第一段就给完整 import 语句，不要让用户猜
### 26. 代码里大量 "评分: ⭐⭐⭐⭐⭐" 注释
`response.go`、`storage.go`、`repository.go`、`config.go`、`cache.go`、`middleware/cors.go` ……到处都是：
```go
// 评分: ⭐⭐⭐⭐⭐
// 理由: 文件下载封装，自动设置响应头
```
这些是 AI 生成留下的"自夸"，**对外发布的库代码里出现这个会显得不专业**。建议批量删掉。如果想留设计理由，改成 `// Why: ...` 风格的简洁注释。
### 27. 大量 `Without*` Option 实际上不需要
```go
WithLogger / WithoutLogger
WithMySQL / WithoutMySQL
WithRedis / WithoutRedis
...
```
每对都是 v1.0.2 在"全开 vs 全关"摇摆产生的副产品。既然已经定调"`xlgo.New()` 是轻量"，那 `WithoutLogger` 的用途就只剩"用了 `NewFullStack` 又想关掉一个"。**建议**：
- `Without*` 全部标 `Deprecated`
- 文档统一推荐组合：
- `xlgo.New(...)` + 显式 `With*`
- `xlgo.NewFullStack(...)` 全开
- 真要关单项，让 FullStack 接受函数式排除：`xlgo.NewFullStack(xlgo.Disable("redis"))`
### 28. CLI 模板太单一
`xlgo new` 只生成一种模板。`Version_Update_Plan_v1.0.2.md` 第 884 行已经规划了：
```
xlgo new myproject --template minimal
xlgo new myproject --template api
xlgo new myproject --template fullstack
xlgo new myproject --template grpc # 建议补
xlgo new myproject --template microservice
```
是时候做了。最小模板对降低"上手第一公里"的心理负担非常关键。
### 29. 缺一个 examples/ 目录
我看到 README 里有 `make run` → `go run ./example`，但仓库里**没有 example 目录**。新用户 clone 之后跑不起来。建议至少补两个：
- `examples/minimal/` —— 50 行能跑
- `examples/full/` —— mysql + redis + jwt + 一个 user CRUD
### 30. CHANGELOG 与 Version_Update_Plan 应分离
`Version_Update_Plan_v1.0.2.md` 是规划文档，不应放仓库根。建议：
```
docs/
├── CHANGELOG.md # 追加格式，每个版本 Added/Changed/Fixed
├── plans/
│ └── v1.0.2.md # 历史规划归档
├── architecture.md
└── migration/v1.0.1-to-v1.0.2.md
```
---
## 五、值得期待的 v1.1+ 路线
按优先级排成一个推荐的迭代节奏：
### v1.0.3（Bug Fix Release，1～2 周）
**修真实 bug，不破坏 API**
- ✅ #1 错误码冲突 + 自检
- ✅ #2 CORS Allow-Credentials
- ✅ #3 Logger Tee bug
- ✅ #4 删掉死代码 DBResolver / 引入 gorm dbresolver
- ✅ #6 `generateJTI` 错误处理
- ✅ #7 QueryBuilder.Page Count
- ✅ #8 OSS 文件名冲突
- ✅ #9 go.mod tidy 复查
- ✅ #26 删除"评分"注释
### v1.0.4（DX & Docs）
- ✅ #25 模块路径修正
- ✅ #28 CLI 多模板
- ✅ #29 examples/
- ✅ #30 文档结构调整
### v1.1.0（HA & Manager 化）
- #10 Storage/Cache/Redis/JWT 全部 Manager 化
- #12 Lifecycle Hooks
- #13 Server 参数全配置化
- #14 `time.Duration` 配置
- #16 Config Validate
- #17 livez / readyz
- #18 metrics 中间件
- #19 请求级 Timeout
- #20 Redis 限流器
- #21 主库探活 + replica 健康剔除
- #22 等业务 goroutine
- #23 Recover 带 request_id
- #24 RequestID 默认装入
### v1.2.0（生态）
- 内置 OpenAPI 3.x（替代 swaggo，后者已半弃维）
- gRPC Gateway 模板
- 多租户模板（参考 #1 错误码 namespace）
- RBAC 扩展包
- DDD / Clean Architecture 项目模板
---
## 六、整体判断
xlgo 的 v1.0.2 已经迈过了"内部工具集"到"框架"的这道坎，特别是**dialect 注册表**、**config.Manager + SetDefaultManager**、**database.Manager** 这三个设计是真正的框架式抽象，证明设计上是在往正确方向走。
但要打到"通用 / 高可用 / 易上手"，**最值得马上做的两件事**是：
1. **先把第一节那 9 个 Bug 修掉**——它们里任意一个被开源用户踩到，都会发 issue 质疑框架质量。
2. **把 Storage/Cache/Redis/JWT 也 Manager 化**——这是把 v1.0.2 的好抽象"贯彻到底"。否则现在是**一半组件可注入，一半是单例**的撕裂状态，对中大型项目和单元测试都不友好。
建议从 v1.0.3 的 Bug Fix 开始动手，优先级：
> #1 (错误码冲突) → #2 (CORS) → #3 (Logger Tee) → #4 (DBResolver 死代码)
这几个改完都不破坏 API，可以一个 PR 一个 commit 走 review。
docs/plans/v2.0-review.md
+485
View File
@@ -0,0 +1,485 @@
# xlgo Web 框架评估报告（v2.0 优化后版本）
## 一、项目概述
xlgo 是一个基于 Go + Gin 构建的轻量级 Web 开发框架，旨在提供后端开发的基础设施。本报告基于 v2.0 版本（经过全面优化和 zl 工具库移植后）进行评估。
---
## 二、本轮优化内容汇总
### 2.1 新增核心包
| 包名 | 来源 | 函数数 | 核心功能 |
|------|------|--------|----------|
| `utils/` | zl/utils | 111 | 随机数、字符串、时间、转换、文件、URL、验证、加密、HTTP客户端、UUID |
| `console/` | zl/utils/print_*.go | 22 | 彩色控制台输出（Debug/Info/Success/Warn/Error） |
| `compress/` | zl/service/compress | 7 | Gzip/Zip 压缩解压 |
| `cache/keybuilder.go` | zl/service/cache | 新增 | 键名前缀管理，多站点共用 Redis |
| `cache/lock.go` | zl/service/cache | 新增 | 分布式锁、计数器、TTL管理 |
| `middleware/requestid.go` | zl/middleware | 2 | 请求ID追踪 |
| `middleware/recover.go` | zl/middleware | 2 | Panic恢复中间件 |
| `handler/handler.go` | zl/response | 增强 | 类型安全参数获取（QueryInt/PathInt/FormInt等） |
| `response/response.go` | zl/response | 增强 | RequestID字段、文件下载、HTML响应、跳转 |
| `config/config.go` | 新增 | AppConfig | 应用配置（SiteName/Env/Version等） |
### 2.2 配置增强
新增 `AppConfig` 配置块，支持站点别名：
```yaml
app:
name: "用户管理系统"
site_name: "user_api" # 站点别名，用于缓存键前缀、日志标识
version: "1.0.0"
env: "prod"
debug: false
base_url: "https://user.example.com"
token_expire: 86400
```
### 2.3 CLI 工具重构
将原来单个 `main.go`（约700行）拆分为模块化结构：
```
cmd/xlgo/
├── main.go # 入口和命令路由（~50行）
├── types.go # 类型定义
├── utils.go # 工具函数
├── commands.go # 命令实现
└── templates.go # 所有模板定义
```
---
## 三、项目规模对比
| 指标 | v1.1.0 | v2.0 | 提升 |
|------|--------|------|------|
| Go 源文件数 | 28 | 54 | +93% |
| 代码行数 | ~2,800 | ~8,400 | +200% |
| 包数量 | 16 | 23 | +44% |
| 函数数量 | ~150 | ~450 | +200% |
| 测试覆盖 | 0% | 8% (2/24包) | +8% | utils/console已有测试 |
---
## 四、模块完整性评估（v2.0）
### 4.1 核心模块评分对比
| 模块 | v1.1.0 | v2.0 | 提升 | 说明 |
|------|--------|------|------|------|
| 配置管理 | 8/10 | 9/10 | +1 | 新增 AppConfig、SiteName |
| 数据库 | 8/10 | 8/10 | - | 保持稳定 |
| Redis/缓存 | 9/10 | 10/10 | +1 | 分布式锁、键名前缀、计数器 |
| JWT 认证 | 8/10 | 8/10 | - | 保持稳定 |
| 日志系统 | 9/10 | 9/10 | - | 保持稳定 |
| 中间件 | 8/10 | 9/10 | +1 | RequestID、Recover、彩色输出 |
| 文件存储 | 9/10 | 9/10 | - | 保持稳定 |
| 工具函数 | 3/10 | 9/10 | +6 | 111个实用函数 |
| 验证器 | 9/10 | 9/10 | - | 保持稳定 |
| 错误处理 | 8/10 | 8/10 | - | 保持稳定 |
| 密码加密 | 9/10 | 9/10 | - | 保持稳定 |
| SSE 支持 | 8/10 | 8/10 | - | 保持稳定 |
| WebSocket | 8/10 | 8/10 | - | 保持稳定 |
| 定时任务 | 7/10 | 7/10 | - | 保持稳定 |
| 测试支持 | 8/10 | 8/10 | - | 保持稳定 |
| CLI 工具 | 7/10 | 8/10 | +1 | 模块化重构、模板分离 |
| 压缩解压 | 0/10 | 8/10 | +8 | Gzip/Zip完整实现 |
| 控制台输出 | 0/10 | 9/10 | +9 | 跨平台彩色输出 |
### 4.2 新增 utils 包功能清单
#### 4.2.1 随机数生成 (random.go)
```go
RandString(16) // 随机字符串（字母+数字）
RandDigit(6) // 随机数字字符串
RandInt(1, 100) // 随机整数
RandInt64(0, 1000) // 随机int64
```
#### 4.2.2 字符串处理 (strings.go)
```go
IsBlank(s) // 检查空白
IsAnyBlank(strs...) // 批量检查
DefaultIfBlank(s, def) // 默认值
Substr(s, 0, 10) // 子字符串（支持中文）
StrLen(s) // Unicode长度
EqualsIgnoreCase(a, b) // 不区分大小写
Trim(s) // 去除空白
```
#### 4.2.3 时间日期 (datetime.go)
```go
NowUnix() // 秒时间戳
NowTimestamp() // 毫秒时间戳
FromUnix(unix) // 时间戳转时间
FormatDateTime(t) // 格式化 "2006-01-02 15:04:05"
StartOfDay(t) // 当天开始
EndOfDay(t) // 当天结束
StartOfMonth(t) // 当月开始
EndOfMonth(t) // 当月结束
```
#### 4.2.4 类型转换 (convert.go)
```go
ToInt(s) // 字符串转int
ToIntDefault(s, 0) // 带默认值
ToInt64(s) // 转int64
ToFloat64(s) // float64
CalcPageCount(100, 10) // 计算总页数
CalcOffset(2, 20) // 分页偏移
```
#### 4.2.5 文件操作 (file.go)
```go
FileExists(path) // 检查文件存在
DirExists(path) // 检查目录存在
EnsureDir(path) // 确保目录存在
ReadFile(path) // 读取文件
WriteFile(path, data) // 写入文件
CopyFile(dst, src) // 复制文件
```
#### 4.2.6 URL处理 (url.go)
```go
ParseURL(rawURL) // 解析URL
builder.AddQuery("key", "value") // 链式添加参数
URLEncode(s) // URL编码
URLDecode(s) // URL解码
```
#### 4.2.7 格式验证 (validator.go)
```go
IsPhone(phone) // 手机号验证
IsEmail(email) // 邮箱验证
IsIPv4(ip) // IPv4验证
IsIDCard(id) // 身份证验证
IsChinese(s) // 中文验证
IsNumeric(s) // 数字验证
IsAlphanumeric(s) // 字母数字验证
```
#### 4.2.8 加密编码 (crypto.go)
```go
MD5(s) // MD5哈希
SHA256(s) // SHA256哈希
Base64Encode(data) // Base64编码
Base64URLEncode(data) // URL安全编码
```
#### 4.2.9 HTTP客户端 (http.go)
```go
client := NewHTTPClient()
client.SetTimeout(30*time.Second)
client.SetHeader("Authorization", "Bearer xxx")
client.Get(url, params) // GET请求
client.PostJSON(url, data) // POST JSON
client.Upload(url, files, params) // 文件上传
```
#### 4.2.10 UUID生成 (uuid.go)
```go
UUID() // UUID v4字符串
UUIDShort() // 短UUID（无横线）
UUIDValid(s) // 验证UUID
```
### 4.3 新增 console 包功能
```go
console.Debug("调试信息") // 青色
console.Info("普通信息") // 白色
console.Success("成功信息") // 绿色
console.Warn("警告信息") // 黄色
console.Error("错误信息") // 红色
// 自定义配置
c := console.New(
console.WithColor(true),
console.WithTime(true),
console.WithCaller(true, 2),
)
c.Debug("自定义控制台输出")
```
### 4.4 新增 compress 包功能
```go
// Gzip 数据压缩
GzipCompress(data)
GzipDecompress(data)
// Gzip 文件压缩
GzipCompressFile(src, dst)
GzipDecompressFile(src, dst)
// Zip 打包
Zip(zipPath, paths) // 打包文件/目录
Unzip(zipPath, dstDir) // 解压到目录
```
### 4.5 缓存键名前缀管理
```go
// 自动从配置读取 site_name
cache.K("user:1") // -> "cache:user_api:user:1"
cache.KTemp("token") // -> "temp:user_api:token"
cache.KPerm("config") // -> "perm:user_api:config"
cache.KLock("order:123") // -> "lock:user_api:order:123"
cache.KCounter("visit") // -> "counter:user_api:visit"
cache.KSession("sid") // -> "session:user_api:sid"
// 分布式锁
cache.Lock(ctx, key, ttl)
cache.Unlock(ctx, key)
cache.TryLock(ctx, key, ttl, retry, maxRetry)
cache.WithLock(ctx, key, ttl, func(context.Context) error) // 自动管理锁
// 计数器
cache.Incr(ctx, key)
cache.Decr(ctx, key)
```
### 4.6 中间件增强
```go
// RequestID - 请求追踪
r.Use(middleware.RequestID())
// 响应头自动添加 X-Request-ID
// Recover - Panic恢复
r.Use(middleware.Recover()) // 生产环境
r.Use(middleware.RecoverWithDetail()) // 开发环境（返回详细信息）
```
### 4.7 Handler 参数获取增强
```go
// 类型安全的参数获取
page := handler.QueryInt(c, "page", 1)
id := handler.PathInt64(c, "id", 0)
price := handler.QueryFloat64(c, "price", 0.0)
enabled := handler.QueryBool(c, "enabled", false)
count := handler.FormInt(c, "count", 0)
```
---
## 五、多站点共用 Redis 方案
### 5.1 问题背景
多个小项目共用一台 Redis 服务器时，缓存键名可能冲突：
- 项目A: `user:1`
- 项目B: `user:1`
- 项目C: `user:1`
### 5.2 解决方案
通过 `site_name` 配置自动添加前缀：
| 项目 | config.yaml | 实际键名 |
|------|-------------|----------|
| 用户API | `site_name: user_api` | `cache:user_api:user:1` |
| 订单API | `site_name: order_api` | `cache:order_api:user:1` |
| 支付API | `site_name: pay_api` | `cache:pay_api:user:1` |
### 5.3 使用方式
```yaml
# config.yaml
app:
site_name: "my_project"
```
```go
// 无需额外代码，自动生效
cache.K("user:1") // -> "cache:my_project:user:1"
```
---
## 六、性能评估（v2.0）
### 6.1 性能优化点
| 优化项 | 说明 |
|--------|------|
| RandString/RandDigit | 使用 sync.Pool 复用 rand.Source |
| StringToBytes/BytesToString | 零拷贝转换 |
| HTTPClient | 链式配置，连接复用 |
| 缓存键名 | 预构建，避免重复拼接 |
### 6.2 性能基准估算
| 场景 | 预估 QPS | 说明 |
|------|----------|------|
| 简单查询 API | 12,000-18,000 | 无 DB 查询 |
| 带 DB 查询 | 3,000-5,000 | 单表主键查询 |
| 缓存查询 | 10,000-15,000 | Redis 缓存命中 |
| SSE 流式响应 | 5,000-8,000 | 单连接 |
| WebSocket 连接 | 10,000+ | 连接数 |
| 文件压缩 | 50-100 MB/s | Gzip |
| HTTP请求 | 1,000-5,000 | 外部API调用 |
---
## 七、扩展性评估（v2.0）
| 方面 | v1.1.0 | v2.0 | 说明 |
|------|--------|------|------|
| 存储扩展 | 本地 + OSS | 本地 + OSS | 保持 |
| 缓存扩展 | 基础操作 | 分布式锁、计数器、前缀 | +3功能 |
| 验证扩展 | 自定义规则 | 手机/邮箱/IP等预定义 | +7规则 |
| 通信扩展 | HTTP + SSE + WS | 保持 | - |
| 工具扩展 | 无 | 111个函数 | +111 |
| 压缩扩展 | 无 | Gzip + Zip | +2 |
| 控制台扩展 | 无 | 彩色输出 | +1 |
---
## 八、易用性评估（v2.0）
### 8.1 开发效率提升
| 任务 | v1.1.0 | v2.0 | 节省 |
|------|--------|------|------|
| 创建新项目 | 5 分钟 | 5 分钟 | - |
| 添加 CRUD 模块 | 10 分钟 | 10 分钟 | - |
| 请求验证 | 5 分钟 | 5 分钟 | - |
| 参数类型转换 | 手动编写 | 调用 handler.QueryInt | 90% |
| 文件压缩 | 手动实现 | 调用 compress.Zip | 100% |
| 随机字符串 | 手动实现 | 调用 utils.RandString | 100% |
| 时间格式化 | 记忆布局 | 调用 utils.FormatDateTime | 80% |
| 分布式锁 | 手动实现 | 调用 cache.Lock | 100% |
| HTTP请求 | 手动封装 | 调用 NewHTTPClient().Get | 100% |
| 控制台调试 | fmt.Println | console.Debug（彩色） | 50% |
### 8.2 代码简化示例
```go
// v1.1.0 - 手动实现
func GetUser(c *gin.Context) {
pageStr := c.Query("page")
page := 1
if pageStr != "" {
p, err := strconv.Atoi(pageStr)
if err == nil {
page = p
}
}
// ...
}
// v2.0 - 一行搞定
func GetUser(c *gin.Context) {
page := handler.QueryInt(c, "page", 1)
// ...
}
```
---
## 九、安全性评估（v2.0）
| 检查项 | v1.1.0 | v2.0 | 说明 |
|--------|--------|------|------|
| SQL 注入 | ✅ GORM | ✅ GORM | 保持 |
| XSS | ⚠️ 应用层 | ⚠️ 应用层 | 保持 |
| CSRF | ❌ 无 | ✅ 完善 | +1 | 多种模式：Cookie/API/DoubleSubmit |
| 密码加密 | ✅ bcrypt | ✅ bcrypt | 保持 |
| 请求验证 | ✅ validator | ✅ validator | 保持 |
| 限流防护 | ✅ 完善 | ✅ 完善 | 保持 |
| JWT 安全 | ✅ 黑名单 | ✅ 黑名单 | 保持 |
| Panic恢复 | ❌ 无 | ✅ Recover中间件 | +1 |
| 请求追踪 | ❌ 无 | ✅ RequestID | +1 |
| 类型安全 | ⚠️ 手动 | ✅ 强类型函数 | +1 |
---
## 十、综合评分（v2.0）
| 维度 | v1.1.0 | v2.0 | 提升 |
|------|--------|------|------|
| 完整性 | 8.5/10 | 9.5/10 | +1.0 |
| 性能 | 8.5/10 | 9.0/10 | +0.5 |
| 扩展性 | 7.5/10 | 9.0/10 | +1.5 |
| 易用性 | 9.0/10 | 9.5/10 | +0.5 |
| 安全性 | 8.0/10 | 9.0/10 | +1.0 |
| **总分** | **8.35/10** | **9.2/10** | **+0.85** |
---
## 十一、剩余改进建议
### 11.1 P3 - 下一步优化
| 功能 | 优先级 | 说明 |
|------|--------|------|
| Kafka 生产者 | 低 | 需重新设计连接池 |
| WebSocket 客户端 | 低 | 框架已有服务端实现 |
| 链路追踪 | 中 | OpenTelemetry集成 |
| 单元测试 | 高 | 进行中，覆盖所有包 |
| 性能基准 | 中 | 建立benchmark |
### 11.2 测试建议
```bash
# 运行现有测试
go test ./utils/... ./console/... -v
# 建议添加
go test ./cache/... ./handler/... ./middleware/...
```
---
## 十二、结论
经过本轮全面优化，xlgo 框架已从 **生产就绪** 提升至 **功能丰富** 水平。
### 12.1 核心优势
1. **工具库完善** - 111个实用函数，覆盖日常开发80%场景
2. **多站点支持** - SiteName配置解决共用Redis冲突
3. **类型安全** - QueryInt/PathInt等避免手动转换
4. **开发调试** - 彩色控制台输出，一眼识别日志级别
5. **分布式支持** - Redis分布式锁开箱即用
6. **文件处理** - Gzip/Zip压缩解压
### 12.2 适用场景
- ✅ 中大型 API 服务
- ✅ 用户管理系统
- ✅ AI 应用后端
- ✅ 实时通信应用
- ✅ 多项目共用资源
- ✅ 创业项目 MVP
- ✅ 学习 Go Web 开发
### 12.3 开发效率总结
| 场景 | 使用 xlgo v2.0 | 不使用框架 | 节省 |
|------|----------------|------------|------|
| 用户系统 | 4-5 人天 | 10-16 人天 | 60% |
| AI应用 | 4-5 人天 | 9-14 人天 | 55% |
| 通用API | 2-3 人天 | 5-8 人天 | 60% |
---
## 十三、版本历史
| 版本 | 日期 | 主要变化 |
|------|------|----------|
| v1.0.0 | 2026-04-29 | 基础框架 |
| v1.1.0 | 2026-04-29 | P0/P1/P2修复（12项） |
| v2.0.0 | 2026-04-29 | zl工具库移植、模块重构 |
---
*评估日期：2026-04-29*
*评估版本：v2.0.0*
*优化内容：新增5个包 + 增强5个包 + 配置扩展 + CLI重构 = 约120个函数*
examples/README.md
+50
View File
@@ -0,0 +1,50 @@
# xlgo 示例
两个可运行示例，帮助快速上手 xlgo。
## minimal — 最小 HTTP 服务
不依赖 MySQL / Redis / Storage，纯 HTTP + 健康检查。第一次接触 xlgo 从这里开始。
```bash
go run ./examples/minimal
```
访问 http://localhost:8081/health（健康检查）与 http://localhost:8081/api/v1/（示例路由）。
## full — 完整业务 API
包含 MySQL + Redis + JWT + 一个 user CRUD（登录发 token、认证路由、创建/查询用户）。
**运行前需准备**：
- MySQL（修改 `examples/full/config.yaml` 的 `database` 配置）
- Redis（修改 `examples/full/config.yaml` 的 `redis` 配置）
```bash
go run ./examples/full
```
启动后自动迁移 user 表，并初始化示例用户 `alice/secret`（密码以 bcrypt 哈希保存）。接口：
| 方法 | 路径 | 说明 | 认证 |
|---|---|---|---|
| POST | /api/v1/login | 登录，返回 token | 否 |
| GET | /api/v1/users/:id | 查询用户 | 是（Bearer token） |
| POST | /api/v1/users | 创建用户 | 是（Bearer token） |
登录示例：
```bash
curl -X POST http://localhost:8082/api/v1/login \
-H "Content-Type: application/json" \
-d '{"username":"alice","password":"secret"}'
```
创建用户示例：
```bash
curl -X POST http://localhost:8082/api/v1/users \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{"username":"bob","password":"s3cret"}'
```
> 示例代码为演示用途，已演示 bcrypt 密码哈希与登录校验；生产环境仍需配合 `validation` 包完善入参校验、密码强度策略与用户注册流程。
examples/full/config.yaml
+44
View File
@@ -0,0 +1,44 @@
app:
name: "xlgo-full-example"
env: "dev"
debug: true
server:
host: "" # 绑定地址，空=监听所有接口；127.0.0.1=仅本机
port: 8082
mode: development
read_timeout: 15s
write_timeout: 30s
idle_timeout: 60s
shutdown_timeout: 30s
response_mode: business # business(默认) 或 rest
database:
driver: mysql
host: localhost
port: 3306
user: root
password: your_password
name: xlgo_example
max_idle_conns: 10
max_open_conns: 100
redis:
host: localhost
port: 6379
password: ""
db: 0
jwt:
secret: change-me-to-a-long-random-secret-at-least-32-chars
expire: "24h"
refresh_expire: "168h"
issuer: xlgo
algorithm: HS256
log:
dir: ./logs
max_size: 100
max_backups: 30
max_age: 30
compress: true
examples/full/main.go
+175
View File
@@ -0,0 +1,175 @@
// Package main 是 xlgo 的完整示例：MySQL + Redis + JWT + 一个 user CRUD。
//
// 运行前需准备：
// - MySQL（config.yaml 中 database 配置）
// - Redis（config.yaml 中 redis 配置）
//
// 启动后会自动迁移 user 表。访问：
//
// POST /api/v1/login {"username":"alice","password":"secret"} → 返回 token
// GET /api/v1/users/:id （需 Authorization: Bearer <token>）
// POST /api/v1/users （需 Authorization: Bearer <token>，创建用户）
//
// 示例会在启动时初始化 alice/secret，密码以 bcrypt 哈希保存。
//
// 运行：
//
// go run ./examples/full
package main
import (
"context"
"errors"
"fmt"
"os"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/database"
"github.com/EthanCodeCraft/xlgo-core/jwt"
"github.com/EthanCodeCraft/xlgo-core/middleware"
"github.com/EthanCodeCraft/xlgo-core/repository"
"github.com/EthanCodeCraft/xlgo-core/response"
"github.com/EthanCodeCraft/xlgo-core/router"
"github.com/EthanCodeCraft/xlgo-core/validation"
"github.com/gin-gonic/gin"
"gorm.io/gorm"
)
// User 示例模型
type User struct {
gorm.Model
Username string `gorm:"uniqueIndex;size:64" json:"username"`
Password string `gorm:"size:128" json:"-"` // bcrypt 哈希，永不返回给客户端
UserType string `gorm:"size:32" json:"user_type"`
}
var userRepo *repository.BaseRepo[User]
func main() {
app := xlgo.NewFullStack(
xlgo.WithConfigPath("./examples/full/config.yaml"),
xlgo.WithModels(&User{}),
xlgo.WithMiddlewares(middleware.Logger(), middleware.CORS()),
xlgo.WithModules(router.ModuleFunc(registerRoutes)),
xlgo.WithHook(xlgo.Hook{
Name: "seed-example-user",
OnInit: func(*xlgo.App) error {
return ensureExampleUser(context.Background())
},
}),
)
if err := app.Run(); err != nil {
fmt.Printf("启动失败: %v\n", err)
os.Exit(1)
}
}
func registerRoutes(r *gin.RouterGroup) {
// 延迟初始化 repo：此时 App.Init 已完成，database.GetDB() 可用
userRepo = repository.NewBaseRepo[User](database.GetDB())
api := r.Group("/api/v1")
// 公开路由：登录
api.POST("/login", login)
// 认证路由
auth := api.Group("/", middleware.AuthRequired())
auth.GET("/users/:id", getUser)
auth.POST("/users", createUser)
}
func login(c *gin.Context) {
var req struct {
Username string `json:"username" binding:"required"`
Password string `json:"password" binding:"required"`
}
if err := c.ShouldBindJSON(&req); err != nil {
response.Fail(c, "参数错误")
return
}
u, err := userRepo.FindOne(c.Request.Context(), "username = ?", req.Username)
if err != nil {
response.Fail(c, "用户名或密码错误")
return
}
if !validation.CheckPassword(u.Password, req.Password) {
response.Fail(c, "用户名或密码错误")
return
}
token, err := jwt.GenerateToken(u.ID, u.Username, "user", u.UserType)
if err != nil {
response.ServerError(c, "生成 token 失败")
return
}
response.Success(c, gin.H{"token": token})
}
func getUser(c *gin.Context) {
id := c.Param("id")
// 示例简化：直接用 repo 查询，实际应转 uint
var uid uint
if _, err := fmt.Sscanf(id, "%d", &uid); err != nil {
response.Fail(c, "用户ID无效")
return
}
u, err := userRepo.FindByID(c.Request.Context(), uid)
if err != nil {
response.NotFound(c, "用户不存在")
return
}
response.Success(c, u)
}
func createUser(c *gin.Context) {
var req struct {
Username string `json:"username" binding:"required"`
Password string `json:"password" binding:"required"`
UserType string `json:"user_type"`
}
if err := c.ShouldBindJSON(&req); err != nil {
response.Fail(c, "参数错误")
return
}
hash, err := validation.HashPassword(req.Password)
if err != nil {
response.ServerError(c, "密码加密失败")
return
}
u := User{
Username: req.Username,
Password: hash,
UserType: req.UserType,
}
if u.UserType == "" {
u.UserType = "user"
}
if err := userRepo.Create(c.Request.Context(), &u); err != nil {
response.Fail(c, "创建失败: "+err.Error())
return
}
response.Success(c, u)
}
func ensureExampleUser(ctx context.Context) error {
_, err := userRepo.FindOne(ctx, "username = ?", "alice")
if err == nil {
return nil
}
if !errors.Is(err, gorm.ErrRecordNotFound) {
return err
}
hash, err := validation.HashPassword("secret")
if err != nil {
return err
}
return userRepo.Create(ctx, &User{
Username: "alice",
Password: hash,
UserType: "user",
})
}
examples/full/main_test.go
+160
View File
@@ -0,0 +1,160 @@
package main
import (
"bytes"
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"path/filepath"
"strings"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/database"
"github.com/EthanCodeCraft/xlgo-core/jwt"
"github.com/EthanCodeCraft/xlgo-core/validation"
"github.com/alicebob/miniredis/v2"
"github.com/gin-gonic/gin"
"github.com/glebarez/sqlite"
"github.com/redis/go-redis/v9"
"gorm.io/gorm"
)
func setupExampleRouter(t *testing.T) (*gin.Engine, *gorm.DB) {
t.Helper()
database.RegisterDialect(database.DialectSpec{
Name: "sqlite_full_example_test",
Dialector: func(dsn string) gorm.Dialector { return sqlite.Open(dsn) },
DSN: func(c *config.DatabaseConfig) string {
return c.CustomDSN
},
})
cfg := &config.Config{
Database: config.DatabaseConfig{
Driver: "sqlite_full_example_test",
CustomDSN: filepath.Join(t.TempDir(), "full-example.db"),
},
JWT: config.JWTConfig{
Secret: "test-secret-for-full-example-at-least-32-bytes",
Expire: time.Hour,
RefreshExpire: 24 * time.Hour,
Issuer: "xlgo",
Algorithm: "HS256",
},
}
if err := config.Set(cfg); err != nil {
t.Fatalf("设置测试配置失败: %v", err)
}
mgr := database.NewManager(cfg)
if err := mgr.InitDB(context.Background(), cfg); err != nil {
t.Fatalf("初始化测试数据库失败: %v", err)
}
db := mgr.Master()
if err := db.AutoMigrate(&User{}); err != nil {
t.Fatalf("迁移示例用户表失败: %v", err)
}
prev := database.SwapDefaultManager(mgr)
t.Cleanup(func() {
current := database.SwapDefaultManager(prev)
if current != nil && current != prev {
_ = current.Close()
}
})
// JWT 黑名单走 Redis（ParseToken 默认 fail-closed，无 Redis 会拒绝所有 token）。
// 测试用 miniredis 注入，避免依赖外部 Redis。
mr := miniredis.RunT(t)
redisClient := redis.NewClient(&redis.Options{Addr: mr.Addr()})
t.Cleanup(func() { _ = redisClient.Close() })
prevJWTMgr := jwt.GetDefaultJWT()
jwt.SetDefaultJWTManager(jwt.NewJWTManagerWithRedis(redisClient))
t.Cleanup(func() { jwt.SetDefaultJWTManager(prevJWTMgr) })
gin.SetMode(gin.TestMode)
r := gin.New()
registerRoutes(r.Group(""))
if err := ensureExampleUser(context.Background()); err != nil {
t.Fatalf("初始化示例用户失败: %v", err)
}
return r, db
}
func postJSON(t *testing.T, r http.Handler, path string, body string, token string) (int, map[string]any) {
t.Helper()
req := httptest.NewRequest(http.MethodPost, path, bytes.NewBufferString(body))
req.Header.Set("Content-Type", "application/json")
if token != "" {
req.Header.Set("Authorization", "Bearer "+token)
}
rec := httptest.NewRecorder()
r.ServeHTTP(rec, req)
var payload map[string]any
if err := json.Unmarshal(rec.Body.Bytes(), &payload); err != nil {
t.Fatalf("解析响应 JSON 失败: %v, body=%s", err, rec.Body.String())
}
return rec.Code, payload
}
func tokenFromResponse(t *testing.T, payload map[string]any) string {
t.Helper()
data, ok := payload["data"].(map[string]any)
if !ok {
t.Fatalf("响应缺少 data 对象: %#v", payload)
}
token, ok := data["token"].(string)
if !ok || strings.TrimSpace(token) == "" {
t.Fatalf("响应缺少 token: %#v", payload)
}
return token
}
func TestFullExampleLoginAndPasswordFlow(t *testing.T) {
r, db := setupExampleRouter(t)
var seeded User
if err := db.Where("username = ?", "alice").First(&seeded).Error; err != nil {
t.Fatalf("示例用户 alice 应在启动时初始化: %v", err)
}
if seeded.Password == "" || seeded.Password == "secret" {
t.Fatal("示例用户密码必须保存为 bcrypt 哈希，不能保存明文")
}
if !validation.CheckPassword(seeded.Password, "secret") {
t.Fatal("示例用户 alice/secret 应能通过密码校验")
}
status, wrong := postJSON(t, r, "/api/v1/login", `{"username":"alice","password":"wrong"}`, "")
if status != http.StatusOK {
t.Fatalf("业务失败模式下 HTTP 状态应为 200，got %d", status)
}
if code, _ := wrong["code"].(float64); code == 0 {
t.Fatalf("错误密码应返回业务失败: %#v", wrong)
}
_, loginPayload := postJSON(t, r, "/api/v1/login", `{"username":"alice","password":"secret"}`, "")
token := tokenFromResponse(t, loginPayload)
_, createPayload := postJSON(t, r, "/api/v1/users", `{"username":"bob","password":"s3cret"}`, token)
if code, _ := createPayload["code"].(float64); code != 0 {
t.Fatalf("带 token 创建用户应成功: %#v", createPayload)
}
var bob User
if err := db.Where("username = ?", "bob").First(&bob).Error; err != nil {
t.Fatalf("创建后的用户应写入数据库: %v", err)
}
if bob.Password == "" || bob.Password == "s3cret" {
t.Fatal("创建用户时必须保存 bcrypt 哈希，不能保存明文")
}
if !validation.CheckPassword(bob.Password, "s3cret") {
t.Fatal("创建用户的密码哈希应能通过校验")
}
_, bobLogin := postJSON(t, r, "/api/v1/login", `{"username":"bob","password":"s3cret"}`, "")
_ = tokenFromResponse(t, bobLogin)
}
examples/minimal/config.yaml
+8
View File
@@ -0,0 +1,8 @@
app:
name: "xlgo-minimal-example"
env: "dev"
debug: true
server:
port: 8081
mode: development
examples/minimal/main.go
+42
View File
@@ -0,0 +1,42 @@
// Package main 是 xlgo 的最小可运行示例。
//
// 仅依赖一个 config.yaml，不初始化 MySQL / Redis / Storage，
// 适合第一次接触 xlgo、或纯 HTTP 场景。
//
// 运行：
//
// go run ./examples/minimal
package main
import (
"fmt"
"os"
xlgo "github.com/EthanCodeCraft/xlgo-core"
"github.com/EthanCodeCraft/xlgo-core/middleware"
"github.com/EthanCodeCraft/xlgo-core/response"
"github.com/EthanCodeCraft/xlgo-core/router"
"github.com/gin-gonic/gin"
)
func main() {
app := xlgo.New(
xlgo.WithConfigPath("./examples/minimal/config.yaml"),
xlgo.WithLogger(),
xlgo.WithHealthRoutes(),
xlgo.WithMiddlewares(middleware.Logger(), middleware.CORS()),
xlgo.WithModules(router.ModuleFunc(registerRoutes)),
)
if err := app.Run(); err != nil {
fmt.Printf("启动失败: %v\n", err)
os.Exit(1)
}
}
func registerRoutes(r *gin.RouterGroup) {
api := r.Group("/api/v1")
api.GET("/", func(c *gin.Context) {
response.Success(c, gin.H{"message": "Hello xlgo!"})
})
}
glm_note_report.md
+235
View File
@@ -0,0 +1,235 @@
# xlgo 框架文档/注释/代码一致性审查报告
> 审查日期：2026-07-12
> 审查范围：60 个非测试 `.go` 源文件，25 个包目录
> 方法：每条结论均亲自读源码确认；对初筛标"无问题"的文件做抽查复审；专门核查跨函数契约。不转述初筛结论。
## 关于本次审查
本次审查对每一条结论都亲自读取了源码确认，并对标"无问题"的文件做了抽查复审，还专门查了跨函数契约。下方为经得起复核的结果。
**真实数字：23 项**，分三档，每档标了置信度。
---
## 一、整体审查概览
- **审查文件总数**：60（25 个包目录，全部非测试源文件）
- **亲自读源码确认的问题**：23 项
- **A 档·实质错误（误导下游）**：10 项 - 注释与代码逻辑矛盾，会让人按注释写错代码
- **B 档·导出符号注释缺失/不完整**：6 项 - 不致命但违反 godoc 规范或同块内风格不一
- **C 档·描述不完整**：7 项 - 边界/默认行为没写全，不算错但该补
- **代码健康度评分**：**7.5 / 10**
**整体评价**：xlgo 注释质量**两极分化**。核心安全/并发路径（`tls.go`、`validate.go`、`recover.go`、`repository.go` 的 H6 修复块、`logger` 的 H7 块）注释极其详尽且与代码逐条对应，是全仓库最好的；问题集中在两类边缘：① 历史修复后注释没同步（RandomPicker、closeResources 三连、model/base）；② 工具函数/utils 的边界行为和导出常量注释缺失。**本轮主要发现是注释/文档问题，未确认 CRITICAL/HIGH 代码缺陷**（`storage.go` 超限错误类型是唯一存疑点，见第四节）。
---
## 二、A 档·实质错误（10 项，高置信，该修）
这些全部亲自读了源码，证据确凿。
### 1. app.go:462 / 495 / 1053 - closeResources 三连契约错误（跨函数）
这是最严重的一组，**同一个契约错误散布在三处注释，互相印证却全错**：
- **【位置 1】第 462 行 `failAfterInit` 注释**：
```go
// 顺序：... -> closeResources。先停 goroutine 再关资源...
```
实际第 483-488 行调的是 `stopCron` + `rollbackReplacedResources`，**不调 `closeResources`**。
- **【位置 2】第 495 行 `closeResources` 注释**：
```go
// closeResources 关闭 db->redis->logger（M1）。...供 failAfterInit 与 doShutdown 复用。
```
grep 确认 `closeResources` 只被 `doShutdown`（第 1057 行）调用，`failAfterInit` 不调它。**"供 failAfterInit 复用"是假的**。
- **【位置 3】第 1053 行 `doShutdown` 注释**：
```go
// db/redis/logger 经 closeResources 统一关闭（与 failAfterInit 复用，M1）。
```
同样错--`failAfterInit` 走 `rollbackReplacedResources`，不复用 `closeResources`。
**建议**：把三处注释统一修正--`failAfterInit` 回滚走 `rollbackReplacedResources`（恢复 Init 前默认 manager 再关新建 manager），`closeResources` 仅供 `doShutdown` 复用。`failAfterInit` 选 `rollback` 而非 `close` 是有意的（Init 失败要恢复默认 manager 不直接关），注释应点明这个区别。
### 2. database/manager.go:64-67 - RandomPicker 注释引用了已废弃的 rand.Intn
```go
// RandomPicker 随机选择从库。
//
// D2 注释：rand.Intn 自 Go 1.20 起（go.dev/issue/54899）内部使用 per-goroutine
// 随机源，并发安全无需额外同步。本模块 go.mod 声明 go 1.25.0，满足此要求。
```
实际第 75 行：`cryptorand.Int(cryptorand.Reader, big.NewInt(...))` - 已改用 `crypto/rand`，与 `math/rand.Intn`、issue 54899、per-goroutine 随机源**全部无关**。并发安全的原因现在是 `crypto/rand` 本身线程安全。注释整段过时。
**建议修改为**：
```go
// RandomPicker 随机选择从库。
//
// 使用 crypto/rand 生成随机索引，并发安全且不可预测。len(replicas)<=0 返回 nil；
// crypto/rand 失败（极罕见，如熵池耗尽）时回退到 replicas[0]，保证可用性。
```
### 3. model/base.go:9-10 - 注释内部自相矛盾
```go
// 时间列类型（MySQL 通常为 datetime(0) 或 timestamp，保留亚秒精度）。
```
`datetime(0)` = 0 位小数秒（秒级精度），与"保留亚秒精度"直接冲突。GORM MySQL 驱动默认是 `datetime(6)`。应为 `datetime(6)`。
**建议修改为**：
```go
// BaseModel 基础模型。CreatedAt/UpdatedAt 不显式指定 type，由 GORM 按驱动选默认
// 时间列类型（MySQL 通常为 datetime(6)，保留亚秒精度）。
```
### 4. cache/keybuilder.go:47 / 75 / 156 - 三处示例分隔符全错
默认分隔符是 `:`（第 17、62 行），但三处示例都用下划线：
- 第 47 行：`WithCacheType("session") -> "session_site_a_user:1"` -> 应为 `session:site_a:user:1`
- 第 75 行：`kb.Build("user:1") -> "cache_site_a_user:1"` -> 应为 `cache:site_a:user:1`（且与同注释内格式说明 `{separator}` 矛盾）
- 第 156 行：`kb.BuildPattern("user:*") -> "cache_site_a_user:*"` -> 应为 `cache:site_a:user:*`
同文件第 44 行 `WithSeparator` 示例却正确用 `:`，说明这是历史遗留笔误。
### 5. repository/repository.go:37 - Delete 接口注释绝对化
```go
// Delete 删除记录（软删除）
Delete(ctx context.Context, id uint) error
```
实现 `BaseRepo.Delete`（第 156-160 行）契约："若 T 内嵌 gorm.DeletedAt（或 gorm.Model）为软删除；否则为硬删除"。接口注释说死"软删除"，下游按接口理解会误判。
**建议修改为**：
```go
// Delete 删除记录（T 含软删除字段时为软删除，否则为硬删除；详见 BaseRepo.Delete）
Delete(ctx context.Context, id uint) error
```
### 6. repository/repository.go:144 - UpdateFields 示例语义错误
```go
// repo.UpdateFields(ctx, &User{Name: "new"}, "name") // 仅更新 name
```
函数第 150-152 行 `db.Where(conds[0], conds[1:]...)` 把 `"name"` 当 WHERE 条件（`WHERE name`），不是"仅更新 name 字段"的选择器。struct 模式 `Updates(&User{Name:"new"})` 本就只更新非零字段，无需传 `"name"`。示例会误导人把字段名当条件传。第二行（map + `"id = ?"`）正确。
**建议修改为**：
```go
// 示例：
//
// repo.UpdateFields(ctx, &User{Name: "new"}) // struct：仅更新非零字段 name
// repo.UpdateFields(ctx, map[string]any{"status": 0}, "id = ?", id) // map：显式置零，带条件
```
### 7. middleware/csrf.go:260 - CSRFToken 注释"用于 API 模式"误导
```go
// CSRFToken 返回 CSRF Token 的处理器（用于 API 模式）
```
实现第 262-274 行：取 gin context 的 "csrf_token"（Cookie 模式中间件写入），取不到就地生成一次性 token 直接返回，**不写入 `apiTokens`**。而 API 模式可校验 token 由 `GenerateAPIToken`（第 345 行）颁发。所以 `CSRFToken` 产出的 token **不能被 `CSRFForAPI` 消费**，注释会让人误以为它产出 API 模式可校验 token。
**建议修改为**：
```go
// CSRFToken 返回当前请求上下文中的 CSRF Token；若上下文无 Token 则现场生成一个返回。
// 适用于 Cookie/双重提交模式（与 CSRF/DoubleSubmitCookie 中间件配合），
// 不与 CSRFForAPI 配套--API 模式的可校验 Token 请用 GenerateAPIToken 颁发。
```
### 8. examples/full/main.go:11 - POST /users 认证标注缺失
```go
// GET /api/v1/users/:id （需 Authorization: Bearer <token>）
// POST /api/v1/users （创建用户）
```
实际第 82-83 行：`auth := api.Group("/", middleware.AuthRequired())`，`auth.POST("/users", createUser)` 在 auth 组内，**同样需 token**。注释对 GET 标了认证，POST 没标，会让人以为 POST 是公开接口。
**建议修改为**：
```go
// POST /api/v1/login {"username":"alice","password":"secret"} -> 返回 token（公开）
// GET /api/v1/users/:id （需 Authorization: Bearer <token>）
// POST /api/v1/users （需 Authorization: Bearer <token>，创建用户）
```
### 9. utils/random.go:39 - RandInt 与 RandInt64 的 min==max 边界与区间注释矛盾
```go
// RandInt 返回 [min, max) 范围内的随机整数。
func RandInt(min, max int) int {
if min == max {
return min // 等于 max,与半开区间 [min,max) 矛盾
}
```
`[min, max)` 在 `min==max` 时应为空集，但代码返回 `min`（即 max）。`RandIntSecure`（第 112 行）与 `RandInt64Secure`（第 128 行）注释均已明确说明此例外（"min==max 返回 min；max<min 自动交换"），但 `RandInt`（第 39 行）与 `RandInt64`（第 55 行）没说。同问题影响 2 个函数。
**建议修改为**：
```go
// RandInt 返回 [min, max) 范围内的随机整数。min==max 时返回 min；max<min 自动交换。
```
### 10. examples/full/main.go:63 - `_ = app` 死代码 + 误导注释
```go
// 初始化 user repository（App.Init 之后 master DB 才可用，这里在 registerRoutes 里延迟拿）
_ = app
```
`_ = app` 是无意义空赋值（`app` 在 49 行声明、65 行 `app.Run()` 已用），注释紧贴它让人误以为二者相关。实际延迟初始化在 73 行 `registerRoutes` 内。建议删掉 `_ = app`，把注释移至 `registerRoutes` 内 repo 初始化处。
---
## 三、B 档·导出符号注释缺失/不完整（6 项，中置信，该补）
这些是导出符号（const/var 块常量及部分函数）注释缺失或不完整，不误导但违反 godoc 规范或同块内风格不一。
| 文件 | 位置 | 符号 | 说明 |
|---|---|---|---|
| ws/ws.go | 94-100 | `TypeText`/`TypeBinary`/`TypePing`/`TypePong`/`TypeClose` | 5 个导出常量无注释，类型 `MessageType` 有 |
| ws/ws.go | 352-357 | `ErrHubNotRunning`/`ErrHubStopped`/`ErrHubQueueFull`/`ErrNilConnection` | 4 个导出错误变量无注释 |
| console/console.go | 23-32 | `LevelDebug`/`LevelInfo`/`LevelSuccess`/`LevelWarn`/`LevelError` | 5 个级别常量无注释（仅 `LevelSilent` 有） |
| jwt/jwt.go | 126-129 | `BlacklistFailOpen`/`BlacklistFailClosed` | 2 个导出常量无注释，类型 `BlacklistPolicy` 有 |
| router/router.go | 680 | 包级 `GroupWithMiddlewareGroup` | 方法版（672 行）有详细注释，包级版无注释 |
| middleware/ratelimit.go | 37 | `NewRateLimiter` | 已有简短注释（"创建速率限制器（内存版）"），但未说明 `rate<=0`/`window<=0` panic（已确认 `mustValidRateLimit` 第 57-62 行真 panic）及必须 `Stop()` 释放 goroutine |
---
## 四、C 档·描述不完整（7 项，低置信，可选）
边界/默认行为没写全，注释本身不算错，建议补但不急。
| 文件 | 位置 | 符号 | 缺什么 |
|---|---|---|---|
| utils/strings.go | 105 | `Substr` | 未说 `length<=0` 返回空、`start` 越界返回空 |
| utils/convert.go | 89/97 | `CalcPageCount`/`CalcOffset` | 未说非法入参返回 0 / 默认值（1、20） |
| utils/datetime.go | 76/81 | `StartOfMonth`/`EndOfMonth` | 未说具体时刻（1日00:00 / 末日23:59:59.999999999） |
| utils/file.go | 79 | `CopyFile` | 未说自动建目录、覆盖、参数顺序 dst,src |
| utils/validator.go | 49 | `IsChinese` | 未说空串返回 false |
| utils/crypto.go | 52 | `HashFile` | 未说返回 hex 编码、`newHash` 须返回新实例 |
| response/error.go | 90 | `WithDetail` | 未文档化 nil 接收者行为（返回 `&Error{Detail:detail}`，`Code=0`/`Message=""`，不 panic） |
### 唯一存疑的代码问题（非纯文档）
**storage/storage.go:461 与 :664** - `LocalStorage.Get`/`OSSStorage.Get` 读取超 `maxReadBytes` 时返回包装 `ErrInvalidPath` 的错误。"超过最大读取限制"用 `ErrInvalidPath`（路径无效）语义不贴切，建议改 `ErrUploadTooLarge` 或新增专用错误。**这是唯一可能涉及代码（非注释）的问题**，但属错误类型选用，非功能 bug，标存疑待定夺。
---
## 五、关于"漏看/错看"的说明
本次审查纠正了初筛阶段的若干问题：
1. **虚高数字已修正**：初筛报出 55 项，其中大量为"可以写得更详细"类软问题。剔除噪声后真实硬伤 10 项。
2. **漏报已补**：初筛只报了 `failAfterInit` 一处，本次亲自 grep 确认了 `closeResources` 三连错误（第 462/495/1053 行），补上了漏掉的 2 处。这是典型的"局部对全局错"--三处注释单独看都像对，拼起来契约对不上。
3. **"无问题"文件复审**：抽查了 `cache.go`、`validation`（hash+password）、`compress`、`logger`（+field）、`test`、`uuid`、`examples/minimal`、`database/tls`、`config/validate`、`middleware`（cors/recover/timeout）。这些文件初筛标"无问题"**整体可信**--尤其 `tls.go`、`validate.go`、`recover.go` 注释质量很高。抽查中只在 `cache.go:264` `Init()` 注释发现一处边界（标"初始化全局缓存实例"但实际不启 Redis，依赖 `database.InitRedis`），属"注释过度承诺"边界，未列入硬伤，供参考。
4. **方法局限坦白**：未对全部 60 个文件逐行重读，而是对初筛报的所有问题源码逐条复核 + 抽查"无问题"文件覆盖各类情况 + 专门查跨函数契约。**仍可能存在的盲区**：① 某些没被重点提及、也没抽查的文件里可能藏着问题；② 跨文件断言只深挖了 closeResources 和 repository 路由两处，其他跨文件引用没全查。
---
## 附：审查覆盖
- **A 档 10 项**：全部亲自 Read 源码确认，含 7 项二次交叉复核（keybuilder、model/base、RandomPicker、repository Delete/UpdateFields、csrf CSRFToken、examples/full）。
- **B 档 6 项**：全部亲自 Read 确认注释缺失或不完整（含 `NewRateLimiter` 的 panic/Stop 语义缺口经 `mustValidRateLimit` 源码确认）。
- **C 档 7 项**：全部亲自 Read 确认边界行为。
- **跨函数契约**：`closeResources`/`rollbackReplacedResources` 经 grep 全仓库调用点确认；`repository` 经 Read 确认接入 `database.GetDBFromContext`（H6 修复属实）。
- **无问题文件**：抽查 10+ 个覆盖接口密集/注释最详尽/中间件/示例/工具各类型，初筛"无问题"裁定整体可信。
go.mod
+119
View File
@@ -0,0 +1,119 @@
module github.com/EthanCodeCraft/xlgo-core
go 1.25.0
require (
github.com/alicebob/miniredis/v2 v2.38.0
github.com/aliyun/aliyun-oss-go-sdk v2.2.9+incompatible
github.com/fsnotify/fsnotify v1.7.0
github.com/gin-gonic/gin v1.9.1
github.com/go-playground/validator/v10 v10.19.0
github.com/golang-jwt/jwt/v5 v5.3.1
github.com/google/uuid v1.6.0
github.com/gorilla/websocket v1.5.3
github.com/mitchellh/mapstructure v1.5.0
github.com/prometheus/client_golang v1.23.2
github.com/redis/go-redis/v9 v9.5.1
github.com/spf13/viper v1.18.2
github.com/swaggo/files v1.0.1
github.com/swaggo/gin-swagger v1.6.0
go.opentelemetry.io/contrib/propagators/b3 v1.43.0
go.opentelemetry.io/otel v1.43.0
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.43.0
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.43.0
go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.43.0
go.opentelemetry.io/otel/sdk v1.43.0
go.opentelemetry.io/otel/trace v1.43.0
go.uber.org/zap v1.27.0
golang.org/x/crypto v0.53.0
golang.org/x/text v0.38.0
gopkg.in/natefinch/lumberjack.v2 v2.2.1
gorm.io/driver/mysql v1.5.4
gorm.io/driver/postgres v1.5.9
gorm.io/gorm v1.25.10
)
require (
github.com/KyleBanks/depth v1.2.1 // indirect
github.com/PuerkitoBio/purell v1.1.1 // indirect
github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 // indirect
github.com/beorn7/perks v1.0.1 // indirect
github.com/bytedance/sonic v1.9.1 // indirect
github.com/cenkalti/backoff/v5 v5.0.3 // indirect
github.com/cespare/xxhash/v2 v2.3.0 // indirect
github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311 // indirect
github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
github.com/dustin/go-humanize v1.0.1 // indirect
github.com/gabriel-vasile/mimetype v1.4.3 // indirect
github.com/gin-contrib/sse v0.1.0 // indirect
github.com/glebarez/go-sqlite v1.21.2 // indirect
github.com/glebarez/sqlite v1.11.0 // indirect
github.com/go-logr/logr v1.4.3 // indirect
github.com/go-logr/stdr v1.2.2 // indirect
github.com/go-openapi/jsonpointer v0.19.5 // indirect
github.com/go-openapi/jsonreference v0.19.6 // indirect
github.com/go-openapi/spec v0.20.4 // indirect
github.com/go-openapi/swag v0.19.15 // indirect
github.com/go-playground/locales v0.14.1 // indirect
github.com/go-playground/universal-translator v0.18.1 // indirect
github.com/go-sql-driver/mysql v1.7.0 // indirect
github.com/goccy/go-json v0.10.2 // indirect
github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 // indirect
github.com/hashicorp/hcl v1.0.0 // indirect
github.com/jackc/pgpassfile v1.0.0 // indirect
github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a // indirect
github.com/jackc/pgx/v5 v5.5.5 // indirect
github.com/jackc/puddle/v2 v2.2.1 // indirect
github.com/jinzhu/inflection v1.0.0 // indirect
github.com/jinzhu/now v1.1.5 // indirect
github.com/josharian/intern v1.0.0 // indirect
github.com/json-iterator/go v1.1.12 // indirect
github.com/klauspost/cpuid/v2 v2.2.4 // indirect
github.com/leodido/go-urn v1.4.0 // indirect
github.com/magiconair/properties v1.8.7 // indirect
github.com/mailru/easyjson v0.7.6 // indirect
github.com/mattn/go-isatty v0.0.19 // indirect
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
github.com/modern-go/reflect2 v1.0.2 // indirect
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
github.com/pelletier/go-toml/v2 v2.1.0 // indirect
github.com/prometheus/client_model v0.6.2 // indirect
github.com/prometheus/common v0.66.1 // indirect
github.com/prometheus/procfs v0.16.1 // indirect
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
github.com/sagikazarmark/locafero v0.4.0 // indirect
github.com/sagikazarmark/slog-shim v0.1.0 // indirect
github.com/sourcegraph/conc v0.3.0 // indirect
github.com/spf13/afero v1.11.0 // indirect
github.com/spf13/cast v1.6.0 // indirect
github.com/spf13/pflag v1.0.5 // indirect
github.com/subosito/gotenv v1.6.0 // indirect
github.com/swaggo/swag v1.16.3 // indirect
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
github.com/ugorji/go/codec v1.2.11 // indirect
github.com/yuin/gopher-lua v1.1.1 // indirect
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
go.opentelemetry.io/otel/metric v1.43.0 // indirect
go.opentelemetry.io/proto/otlp v1.10.0 // indirect
go.uber.org/multierr v1.10.0 // indirect
go.yaml.in/yaml/v2 v2.4.2 // indirect
golang.org/x/arch v0.3.0 // indirect
golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
golang.org/x/net v0.55.0 // indirect
golang.org/x/sync v0.21.0 // indirect
golang.org/x/sys v0.46.0 // indirect
golang.org/x/time v0.5.0 // indirect
golang.org/x/tools v0.45.0 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20260401024825-9d38bb4040a9 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9 // indirect
google.golang.org/grpc v1.80.0 // indirect
google.golang.org/protobuf v1.36.11 // indirect
gopkg.in/ini.v1 v1.67.0 // indirect
gopkg.in/yaml.v2 v2.4.0 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
modernc.org/libc v1.22.5 // indirect
modernc.org/mathutil v1.5.0 // indirect
modernc.org/memory v1.5.0 // indirect
modernc.org/sqlite v1.23.1 // indirect
)
go.sum
+330
View File
@@ -0,0 +1,330 @@
github.com/KyleBanks/depth v1.2.1 h1:5h8fQADFrWtarTdtDudMmGsC7GPbOAu6RVB3ffsVFHc=
github.com/KyleBanks/depth v1.2.1/go.mod h1:jzSb9d0L43HxTQfT+oSA1EEp2q+ne2uh6XgeJcm8brE=
github.com/PuerkitoBio/purell v1.1.1 h1:WEQqlqaGbrPkxLJWfBwQmfEAE1Z7ONdDLqrN38tNFfI=
github.com/PuerkitoBio/purell v1.1.1/go.mod h1:c11w/QuzBsJSee3cPx9rAFu61PvFxuPbtSwDGJws/X0=
github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 h1:d+Bc7a5rLufV/sSk/8dngufqelfh6jnri85riMAaF/M=
github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578/go.mod h1:uGdkoq3SwY9Y+13GIhn11/XLaGBb4BfwItxLd5jeuXE=
github.com/alicebob/miniredis/v2 v2.38.0 h1:nZAzCR+Lj+Vxk4ZXzm2NuKq2O33RXj1XxJ2e2uP9jiw=
github.com/alicebob/miniredis/v2 v2.38.0/go.mod h1:TcL7YfarKPGDAthEtl5NBeHZfeUQj6OXMm/+iu5cLMM=
github.com/aliyun/aliyun-oss-go-sdk v2.2.9+incompatible h1:Sg/2xHwDrioHpxTN6WMiwbXTpUEinBpHsN7mG21Rc2k=
github.com/aliyun/aliyun-oss-go-sdk v2.2.9+incompatible/go.mod h1:T/Aws4fEfogEE9v+HPhhw+CntffsBHJ8nXQCwKr0/g8=
github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
github.com/bytedance/sonic v1.5.0/go.mod h1:ED5hyg4y6t3/9Ku1R6dU/4KyJ48DZ4jPhfY1O2AihPM=
github.com/bytedance/sonic v1.9.1 h1:6iJ6NqdoxCDr6mbY8h18oSO+cShGSMRGCEo7F2h0x8s=
github.com/bytedance/sonic v1.9.1/go.mod h1:i736AoUSYt75HyZLoJW9ERYxcy6eaN6h4BZXU064P/U=
github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1xcsSM=
github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw=
github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
github.com/chenzhuoyu/base64x v0.0.0-20211019084208-fb5309c8db06/go.mod h1:DH46F32mSOjUmXrMHnKwZdA8wcEefY7UVqBKYGjpdQY=
github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311 h1:qSGYFH7+jGhDF8vLC+iwCD4WpbV1EBDSzWkJODFLams=
github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311/go.mod h1:b583jCggY9gE99b6G5LEC39OIiVsWj+R97kbl5odCEk=
github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
github.com/fsnotify/fsnotify v1.7.0 h1:8JEhPFa5W2WU7YfeZzPNqzMP6Lwt7L2715Ggo0nosvA=
github.com/fsnotify/fsnotify v1.7.0/go.mod h1:40Bi/Hjc2AVfZrqy+aj+yEI+/bRxZnMJyTJwOpGvigM=
github.com/gabriel-vasile/mimetype v1.4.3 h1:in2uUcidCuFcDKtdcBxlR0rJ1+fsokWf+uqxgUFjbI0=
github.com/gabriel-vasile/mimetype v1.4.3/go.mod h1:d8uq/6HKRL6CGdk+aubisF/M5GcPfT7nKyLpA0lbSSk=
github.com/gin-contrib/gzip v0.0.6 h1:NjcunTcGAj5CO1gn4N8jHOSIeRFHIbn51z6K+xaN4d4=
github.com/gin-contrib/gzip v0.0.6/go.mod h1:QOJlmV2xmayAjkNS2Y8NQsMneuRShOU/kjovCXNuzzk=
github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE=
github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=
github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqJ+Jmg=
github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL7YrpYKXt5YId3A/Tnip5kqbEAP+KLuI3SUcPTeU=
github.com/glebarez/go-sqlite v1.21.2 h1:3a6LFC4sKahUunAmynQKLZceZCOzUthkRkEAl9gAXWo=
github.com/glebarez/go-sqlite v1.21.2/go.mod h1:sfxdZyhQjTM2Wry3gVYWaW072Ri1WMdWJi0k6+3382k=
github.com/glebarez/sqlite v1.11.0 h1:wSG0irqzP6VurnMEpFGer5Li19RpIRi2qvQz++w0GMw=
github.com/glebarez/sqlite v1.11.0/go.mod h1:h8/o8j5wiAsqSPoWELDUdJXhjAhsVliSn7bWZjOhrgQ=
github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
github.com/go-openapi/jsonpointer v0.19.3/go.mod h1:Pl9vOtqEWErmShwVjC8pYs9cog34VGT37dQOVbmoatg=
github.com/go-openapi/jsonpointer v0.19.5 h1:gZr+CIYByUqjcgeLXnQu2gHYQC9o73G2XUeOFYEICuY=
github.com/go-openapi/jsonpointer v0.19.5/go.mod h1:Pl9vOtqEWErmShwVjC8pYs9cog34VGT37dQOVbmoatg=
github.com/go-openapi/jsonreference v0.19.6 h1:UBIxjkht+AWIgYzCDSv2GN+E/togfwXUJFRTWhl2Jjs=
github.com/go-openapi/jsonreference v0.19.6/go.mod h1:diGHMEHg2IqXZGKxqyvWdfWU/aim5Dprw5bqpKkTvns=
github.com/go-openapi/spec v0.20.4 h1:O8hJrt0UMnhHcluhIdUgCLRWyM2x7QkBXRvOs7m+O1M=
github.com/go-openapi/spec v0.20.4/go.mod h1:faYFR1CvsJZ0mNsmsphTMSoRrNV3TEDoAM7FOEWeq8I=
github.com/go-openapi/swag v0.19.5/go.mod h1:POnQmlKehdgb5mhVOsnJFsivZCEZ/vjK9gh66Z9tfKk=
github.com/go-openapi/swag v0.19.15 h1:D2NRCBzS9/pEY3gP9Nl8aDqGUcPFrwG2p+CNFrLyrCM=
github.com/go-openapi/swag v0.19.15/go.mod h1:QYRuS/SOXUCsnplDa677K7+DxSOj6IPNl/eQntq43wQ=
github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
github.com/go-playground/validator/v10 v10.19.0 h1:ol+5Fu+cSq9JD7SoSqe04GMI92cbn0+wvQ3bZ8b/AU4=
github.com/go-playground/validator/v10 v10.19.0/go.mod h1:dbuPbCMFw/DrkbEynArYaCwl3amGuJotoKCe95atGMM=
github.com/go-sql-driver/mysql v1.7.0 h1:ueSltNNllEqE3qcWBTD0iQd3IpL/6U+mJxLkazJ7YPc=
github.com/go-sql-driver/mysql v1.7.0/go.mod h1:OXbVy3sEdcQ2Doequ6Z5BW6fXNQTmx+9S1MCJN5yJMI=
github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 h1:HWRh5R2+9EifMyIHV7ZV+MIZqgz+PMpZ14Jynv3O2Zs=
github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0/go.mod h1:JfhWUomR1baixubs02l85lZYYOm7LV6om4ceouMv45c=
github.com/hashicorp/hcl v1.0.0 h1:0Anlzjpi4vEasTeNFn2mLJgTSwt0+6sfsiTG8qcWGx4=
github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a h1:bbPeKD0xmW/Y25WS6cokEszi5g+S0QxI/d45PkRi7Nk=
github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
github.com/jackc/pgx/v5 v5.5.5 h1:amBjrZVmksIdNjxGW/IiIMzxMKZFelXbUoPNb+8sjQw=
github.com/jackc/pgx/v5 v5.5.5/go.mod h1:ez9gk+OAat140fv9ErkZDYFWmXLfV+++K0uAOiwgm1A=
github.com/jackc/puddle/v2 v2.2.1 h1:RhxXJtFG022u4ibrCSMSiu5aOq1i77R3OHKNJj77OAk=
github.com/jackc/puddle/v2 v2.2.1/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
github.com/klauspost/cpuid/v2 v2.2.4 h1:acbojRNwl3o09bUq+yDCtZFc1aiwaAAxtcn8YkZXnvk=
github.com/klauspost/cpuid/v2 v2.2.4/go.mod h1:RVVoqg1df56z8g3pUjL/3lE5UfnlrJX8tyFgg4nqhuY=
github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
github.com/mailru/easyjson v0.0.0-20190614124828-94de47d64c63/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc=
github.com/mailru/easyjson v0.0.0-20190626092158-b2ccc519800e/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc=
github.com/mailru/easyjson v0.7.6 h1:8yTIVnZgCoiM1TgqoeTl+LfU5Jg6/xL3QhGQnimLYnA=
github.com/mailru/easyjson v0.7.6/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
github.com/mattn/go-isatty v0.0.19 h1:JITubQf0MOLdlGRuRq+jtsDlekdYPia9ZFsB8h/APPA=
github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
github.com/pelletier/go-toml/v2 v2.1.0 h1:FnwAJ4oYMvbT/34k9zzHuZNrhlz48GB3/s6at6/MHO4=
github.com/pelletier/go-toml/v2 v2.1.0/go.mod h1:tJU2Z3ZkXwnxa4DPO899bsyIoywizdUvyaeZurnPPDc=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
github.com/prometheus/common v0.66.1 h1:h5E0h5/Y8niHc5DlaLlWLArTQI7tMrsfQjHV+d9ZoGs=
github.com/prometheus/common v0.66.1/go.mod h1:gcaUsgf3KfRSwHY4dIMXLPV0K/Wg1oZ8+SbZk/HH/dA=
github.com/prometheus/procfs v0.16.1 h1:hZ15bTNuirocR6u0JZ6BAHHmwS1p8B4P6MRqxtzMyRg=
github.com/prometheus/procfs v0.16.1/go.mod h1:teAbpZRB1iIAJYREa1LsoWUXykVXA1KlTmWl8x/U+Is=
github.com/redis/go-redis/v9 v9.5.1 h1:H1X4D3yHPaYrkL5X06Wh6xNVM/pX0Ft4RV0vMGvLBh8=
github.com/redis/go-redis/v9 v9.5.1/go.mod h1:hdY0cQFCN4fnSYT6TkisLufl/4W5UIXyv0b/CLO2V2M=
github.com/remyoudompheng/bigfft v0.0.0-20200410134404-eec4a21b6bb0/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
github.com/sagikazarmark/locafero v0.4.0 h1:HApY1R9zGo4DBgr7dqsTH/JJxLTTsOt7u6keLGt6kNQ=
github.com/sagikazarmark/locafero v0.4.0/go.mod h1:Pe1W6UlPYUk/+wc/6KFhbORCfqzgYEpgQ3O5fPuL3H4=
github.com/sagikazarmark/slog-shim v0.1.0 h1:diDBnUNK9N/354PgrxMywXnAwEr1QZcOr6gto+ugjYE=
github.com/sagikazarmark/slog-shim v0.1.0/go.mod h1:SrcSrq8aKtyuqEI1uvTDTK1arOWRIczQRv+GVI1AkeQ=
github.com/sourcegraph/conc v0.3.0 h1:OQTbbt6P72L20UqAkXXuLOj79LfEanQ+YQFNpLA9ySo=
github.com/sourcegraph/conc v0.3.0/go.mod h1:Sdozi7LEKbFPqYX2/J+iBAM6HpqSLTASQIKqDmF7Mt0=
github.com/spf13/afero v1.11.0 h1:WJQKhtpdm3v2IzqG8VMqrr6Rf3UYpEF239Jy9wNepM8=
github.com/spf13/afero v1.11.0/go.mod h1:GH9Y3pIexgf1MTIWtNGyogA5MwRIDXGUr+hbWNoBjkY=
github.com/spf13/cast v1.6.0 h1:GEiTHELF+vaR5dhz3VqZfFSzZjYbgeKDpBxQVS4GYJ0=
github.com/spf13/cast v1.6.0/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo=
github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/spf13/viper v1.18.2 h1:LUXCnvUvSM6FXAsj6nnfc8Q2tp1dIgUfY9Kc8GsSOiQ=
github.com/spf13/viper v1.18.2/go.mod h1:EKmWIqdnk5lOcmR72yw6hS+8OPYcwD0jteitLMVB+yk=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
github.com/swaggo/files v1.0.1 h1:J1bVJ4XHZNq0I46UU90611i9/YzdrF7x92oX1ig5IdE=
github.com/swaggo/files v1.0.1/go.mod h1:0qXmMNH6sXNf+73t65aKeB+ApmgxdnkQzVTAj2uaMUg=
github.com/swaggo/gin-swagger v1.6.0 h1:y8sxvQ3E20/RCyrXeFfg60r6H0Z+SwpTjMYsMm+zy8M=
github.com/swaggo/gin-swagger v1.6.0/go.mod h1:BG00cCEy294xtVpyIAHG6+e2Qzj/xKlRdOqDkvq0uzo=
github.com/swaggo/swag v1.16.3 h1:PnCYjPCah8FK4I26l2F/KQ4yz3sILcVUN3cTlBFA9Pg=
github.com/swaggo/swag v1.16.3/go.mod h1:DImHIuOFXKpMFAQjcC7FG4m3Dg4+QuUgUzJmKjI/gRk=
github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
github.com/ugorji/go/codec v1.2.11 h1:BMaWp1Bb6fHwEtbplGBGJ498wD+LKlNSl25MjdZY4dU=
github.com/ugorji/go/codec v1.2.11/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
github.com/yuin/gopher-lua v1.1.1 h1:kYKnWBjvbNP4XLT3+bPEwAXJx262OhaHDWDVOPjL46M=
github.com/yuin/gopher-lua v1.1.1/go.mod h1:GBR0iDaNXjAgGg9zfCvksxSRnQx76gclCIb7kdAd1Pw=
go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
go.opentelemetry.io/contrib/propagators/b3 v1.43.0 h1:CETqV3QLLPTy5yNrqyMr41VnAOOD4lsRved7n4QG00A=
go.opentelemetry.io/contrib/propagators/b3 v1.43.0/go.mod h1:Q4mCiCdziYzpNR0g+6UqVotAlCDZdzz6L8jwY4knOrw=
go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0 h1:88Y4s2C8oTui1LGM6bTWkw0ICGcOLCAI5l6zsD1j20k=
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0/go.mod h1:Vl1/iaggsuRlrHf/hfPJPvVag77kKyvrLeD10kpMl+A=
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.43.0 h1:RAE+JPfvEmvy+0LzyUA25/SGawPwIUbZ6u0Wug54sLc=
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.43.0/go.mod h1:AGmbycVGEsRx9mXMZ75CsOyhSP6MFIcj/6dnG+vhVjk=
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.43.0 h1:3iZJKlCZufyRzPzlQhUIWVmfltrXuGyfjREgGP3UUjc=
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.43.0/go.mod h1:/G+nUPfhq2e+qiXMGxMwumDrP5jtzU+mWN7/sjT2rak=
go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.43.0 h1:mS47AX77OtFfKG4vtp+84kuGSFZHTyxtXIN269vChY0=
go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.43.0/go.mod h1:PJnsC41lAGncJlPUniSwM81gc80GkgWJWr3cu2nKEtU=
go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw=
go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A=
go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
go.opentelemetry.io/proto/otlp v1.10.0 h1:IQRWgT5srOCYfiWnpqUYz9CVmbO8bFmKcwYxpuCSL2g=
go.opentelemetry.io/proto/otlp v1.10.0/go.mod h1:/CV4QoCR/S9yaPj8utp3lvQPoqMtxXdzn7ozvvozVqk=
go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=
go.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
go.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8=
go.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI=
go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU=
golang.org/x/arch v0.0.0-20210923205945-b76863e36670/go.mod h1:5om86z9Hs0C8fWVUuoMHwpExlXzs5Tkyp9hOrfG7pp8=
golang.org/x/arch v0.3.0 h1:02VY4/ZcO/gBOH6PUaoiptASxtXU10jazRCP865E97k=
golang.org/x/arch v0.3.0/go.mod h1:5om86z9Hs0C8fWVUuoMHwpExlXzs5Tkyp9hOrfG7pp8=
golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
golang.org/x/crypto v0.53.0 h1:QZ4Muo8THX6CizN2vPPd5fBGHyogrdK9fG4wLPFUsto=
golang.org/x/crypto v0.53.0/go.mod h1:DNLU434OwVakk9PzuwV8w62mAJpRJL3vsgcfp4Qnsio=
golang.org/x/exp v0.0.0-20230905200255-921286631fa9 h1:GoHiUyI/Tp2nVkLI2mCxVkOjsbSXD66ic0XW0js0R9g=
golang.org/x/exp v0.0.0-20230905200255-921286631fa9/go.mod h1:S2oDrQGGwySpoQPVqRShND87VCbxmc6bL1Yd2oYrm6k=
golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
golang.org/x/mod v0.36.0 h1:JJjpVx6myfUsUdAzZuOSTTmRE0PfZeNWzzvKrP7amb4=
golang.org/x/mod v0.36.0/go.mod h1:moc6ELqsWcOw5Ef3xVprK5ul/MvtVvkIXLziUOICjUQ=
golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
golang.org/x/net v0.0.0-20210421230115-4e50805a0758/go.mod h1:72T/g9IO56b78aLF+1Kcs5dz7/ng1VjMUvfKvpfy+jM=
golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
golang.org/x/net v0.7.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20210420072515-93ed5bcd2bfe/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.0.0-20220704084225-05e143d24a9e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE=
golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4=
golang.org/x/time v0.5.0 h1:o7cqy6amK/52YcAKIPlM3a+Fpj35zvRj2TP+e1xFSfk=
golang.org/x/time v0.5.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=
golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
golang.org/x/tools v0.45.0 h1:18qN3FAooORvApf5XjCXgsuayZOEtXf6JK18I3+ONa8=
golang.org/x/tools v0.45.0/go.mod h1:LuUGqqaXcXMEFEruIVJVm5mgDD8vww/z/SR1gQ4uE/0=
golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
google.golang.org/genproto/googleapis/api v0.0.0-20260401024825-9d38bb4040a9 h1:VPWxll4HlMw1Vs/qXtN7BvhZqsS9cdAittCNvVENElA=
google.golang.org/genproto/googleapis/api v0.0.0-20260401024825-9d38bb4040a9/go.mod h1:7QBABkRtR8z+TEnmXTqIqwJLlzrZKVfAUm7tY3yGv0M=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9 h1:m8qni9SQFH0tJc1X0vmnpw/0t+AImlSvp30sEupozUg=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
google.golang.org/grpc v1.80.0 h1:Xr6m2WmWZLETvUNvIUmeD5OAagMw3FiKmMlTdViWsHM=
google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4=
google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
gopkg.in/ini.v1 v1.67.0 h1:Dgnx+6+nfE+IfzjUEISNeydPJh9AXNNsWbGP9KzCsOA=
gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
gopkg.in/natefinch/lumberjack.v2 v2.2.1 h1:bBRl1b0OH9s/DuPhuXpNl+VtCaJXFZ5/uEFST95x9zc=
gopkg.in/natefinch/lumberjack.v2 v2.2.1/go.mod h1:YD8tP3GAjkrDg1eZH7EGmyESg/lsYskCTPBJVb9jqSc=
gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gorm.io/driver/mysql v1.5.4 h1:igQmHfKcbaTVyAIHNhhB888vvxh8EdQ2uSUT0LPcBso=
gorm.io/driver/mysql v1.5.4/go.mod h1:9rYxJph/u9SWkWc9yY4XJ1F/+xO0S/ChOmbk3+Z5Tvs=
gorm.io/driver/postgres v1.5.9 h1:DkegyItji119OlcaLjqN11kHoUgZ/j13E0jkJZgD6A8=
gorm.io/driver/postgres v1.5.9/go.mod h1:DX3GReXH+3FPWGrrgffdvCk3DQ1dwDPdmbenSkweRGI=
gorm.io/gorm v1.25.7-0.20240204074919-46816ad31dde/go.mod h1:hbnx/Oo0ChWMn1BIhpy1oYozzpM15i4YPuHDmfYtwg8=
gorm.io/gorm v1.25.10 h1:dQpO+33KalOA+aFYGlK+EfxcI5MbO7EP2yYygwh9h+s=
gorm.io/gorm v1.25.10/go.mod h1:hbnx/Oo0ChWMn1BIhpy1oYozzpM15i4YPuHDmfYtwg8=
modernc.org/libc v1.22.5 h1:91BNch/e5B0uPbJFgqbxXuOnxBQjlS//icfQEGmvyjE=
modernc.org/libc v1.22.5/go.mod h1:jj+Z7dTNX8fBScMVNRAYZ/jF91K8fdT2hYMThc3YjBY=
modernc.org/mathutil v1.5.0 h1:rV0Ko/6SfM+8G+yKiyI830l3Wuz1zRutdslNoQ0kfiQ=
modernc.org/mathutil v1.5.0/go.mod h1:mZW8CKdRPY1v87qxC/wUdX5O1qDzXMP5TH3wjfpga6E=
modernc.org/memory v1.5.0 h1:N+/8c5rE6EqugZwHii4IFsaJ7MUhoWX07J5tC/iI5Ds=
modernc.org/memory v1.5.0/go.mod h1:PkUhL0Mugw21sHPeskwZW4D6VscE/GQJOnIpCnW6pSU=
modernc.org/sqlite v1.23.1 h1:nrSBg4aRQQwq59JpvGEQ15tNxoO5pX/kUjcRNwSAGQM=
modernc.org/sqlite v1.23.1/go.mod h1:OrDj17Mggn6MhE+iPbBNf7RGKODDE9NFT0f3EwDzJqk=
rsc.io/pdf v0.1.1/go.mod h1:n8OzWcQ6Sp37PL01nO98y4iUCRdTGarVfzxY20ICaU4=
handler/handler.go
+199
View File
@@ -0,0 +1,199 @@
package handler
import (
"errors"
"net/http"
"strconv"
"strings"
"github.com/EthanCodeCraft/xlgo-core/response"
"github.com/EthanCodeCraft/xlgo-core/utils"
"github.com/gin-gonic/gin"
)
// DefaultMaxJSONBodyBytes 是 BindJSON 的默认请求体上限。
// 入口层无上限读 JSON 会让任意 handler 暴露 OOM 面；需要更大请求体的业务可改用
// BindJSONWithMaxBytes 显式声明上限。
const DefaultMaxJSONBodyBytes int64 = 1 << 20 // 1 MiB
// HealthCheck 健康检查
// @Summary 健康检查
// @Description 检查服务是否正常运行
// @Tags 系统
// @Accept json
// @Produce json
// @Success 200 {object} map[string]string
// @Router /health [get]
//
// 响应体与 router.RegisterHealthRoute 收敛为同一 schema（H8d）：
// 恒 200 + {"status":"ok"}，不走 response 业务信封，便于 K8s 探针直读。
// 需要依赖探活（mysql/redis…失败 503）时改用 router.RegisterHealthRoute 传入 checks。
func HealthCheck(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"status": "ok"})
}
// BindJSON 绑定 JSON 请求
func BindJSON(c *gin.Context, req any) error {
return BindJSONWithMaxBytes(c, req, DefaultMaxJSONBodyBytes)
}
// BindJSONWithMaxBytes 绑定 JSON 请求，并限制最大 body 大小。
// maxBytes<=0 时返回明确错误，避免 http.MaxBytesReader 的非正上限产生不可读语义。
func BindJSONWithMaxBytes(c *gin.Context, req any, maxBytes int64) error {
if maxBytes <= 0 {
return errors.New("handler: max JSON body bytes must be positive")
}
c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, maxBytes)
return c.ShouldBindJSON(req)
}
// BindQuery 绑定 Query 参数
func BindQuery(c *gin.Context, req any) error {
return c.ShouldBindQuery(req)
}
// MaxPage GetPage 允许的最大页码（M-D 修复：防深分页 DoS）。
// 超大 page 产生超大 OFFSET，大表上为性能灾难/DoS 面。钳制到该上限；
// 需更深度遍历的业务应改用游标/keyset 分页（框架不内置，避免功能扩张）。
const MaxPage = 10000
// GetPage 获取分页参数
func GetPage(c *gin.Context) (int, int) {
page := c.DefaultQuery("page", "1")
pageSize := c.DefaultQuery("page_size", "20")
p := utils.ToIntDefault(page, 1)
ps := utils.ToIntDefault(pageSize, 20)
if p < 1 {
p = 1
}
// M-D 修复：钳制 page 上限，防 ?page=999999999 产生超大 OFFSET 拖垮 DB。
if p > MaxPage {
p = MaxPage
}
if ps < 1 {
ps = 20
}
if ps > 100 {
ps = 100
}
return p, ps
}
// GetIDFromPath 从路径获取 ID
func GetIDFromPath(c *gin.Context, paramName string) (uint, bool) {
idStr := c.Param(paramName)
idStr = strings.Trim(idStr, "/")
id, err := strconv.ParseUint(idStr, 10, 64)
if err != nil {
return 0, false
}
return uint(id), true
}
// ===== 类型安全的参数获取函数 =====
// QueryInt 获取 Query 参数中的整数（带默认值）
func QueryInt(c *gin.Context, key string, def int) int {
return utils.ToIntDefault(c.Query(key), def)
}
// QueryInt64 获取 Query 参数中的 int64（带默认值）
func QueryInt64(c *gin.Context, key string, def int64) int64 {
return utils.ToInt64Default(c.Query(key), def)
}
// QueryFloat64 获取 Query 参数中的 float64（带默认值）
func QueryFloat64(c *gin.Context, key string, def float64) float64 {
return utils.ToFloat64Default(c.Query(key), def)
}
// QueryBool 获取 Query 参数中的布尔值（带默认值）
func QueryBool(c *gin.Context, key string, def bool) bool {
val := c.Query(key)
if val == "" {
return def
}
return val == "true" || val == "1" || val == "yes"
}
// PathInt 从路径参数获取整数（带默认值）
func PathInt(c *gin.Context, key string, def int) int {
val := strings.Trim(c.Param(key), "/")
return utils.ToIntDefault(val, def)
}
// PathInt64 从路径参数获取 int64（带默认值）
func PathInt64(c *gin.Context, key string, def int64) int64 {
val := strings.Trim(c.Param(key), "/")
return utils.ToInt64Default(val, def)
}
// PathUint64 从路径参数获取 uint64（带默认值）
func PathUint64(c *gin.Context, key string, def uint64) uint64 {
val := strings.Trim(c.Param(key), "/")
return utils.ToUint64Default(val, def)
}
// FormInt 获取 POST 表单参数中的整数（带默认值）
func FormInt(c *gin.Context, key string, def int) int {
return utils.ToIntDefault(c.PostForm(key), def)
}
// FormInt64 获取 POST 表单参数中的 int64（带默认值）
func FormInt64(c *gin.Context, key string, def int64) int64 {
return utils.ToInt64Default(c.PostForm(key), def)
}
// FormUint64 获取 POST 表单参数中的 uint64（带默认值）
func FormUint64(c *gin.Context, key string, def uint64) uint64 {
return utils.ToUint64Default(c.PostForm(key), def)
}
// FormFloat64 获取 POST 表单参数中的 float64（带默认值）
func FormFloat64(c *gin.Context, key string, def float64) float64 {
return utils.ToFloat64Default(c.PostForm(key), def)
}
// FormBool 获取 POST 表单参数中的布尔值（带默认值）
func FormBool(c *gin.Context, key string, def bool) bool {
val := c.PostForm(key)
if val == "" {
return def
}
return val == "true" || val == "1" || val == "yes" || val == "on"
}
// FormString 获取 POST 表单参数中的字符串（带默认值）
func FormString(c *gin.Context, key string, def string) string {
val := c.PostForm(key)
if val == "" {
return def
}
return val
}
// ParseInt 解析整数
func ParseInt(s string, defaultValue int) int {
return utils.ToIntDefault(s, defaultValue)
}
// BadRequest 返回参数/请求错误响应。
//
// 委托 response.FailWithCode（CodeFail），遵循当前响应模式（ModeBusiness 下 HTTP 200，
// 错误信息通过 body 中的 code 表达；ModeREST 下 CodeFail 属业务失败不映射 HTTP 错误，仍 200），
// 并写入 RequestID——与 response 模式系统一致，不再硬编 HTTP 状态码、不再丢失链路追踪。
func BadRequest(c *gin.Context, msg string) {
response.FailWithCode(c, response.CodeFail, msg)
}
// InternalError 返回服务器错误响应。
//
// 委托 response.ServerError（CodeServerError），遵循当前响应模式（ModeBusiness 下 HTTP 200，
// ModeREST 下 HTTP 500），并写入 RequestID——与 response 模式系统一致，
// 不再硬编 HTTP 状态码、不再丢失链路追踪。
func InternalError(c *gin.Context, msg string) {
response.ServerError(c, msg)
}
handler/handler_test.go
+414
View File
@@ -0,0 +1,414 @@
package handler_test
import (
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
"github.com/EthanCodeCraft/xlgo-core/handler"
"github.com/EthanCodeCraft/xlgo-core/response"
"github.com/gin-gonic/gin"
)
func setupTestRouter() *gin.Engine {
gin.SetMode(gin.TestMode)
r := gin.New()
return r
}
func TestHealthCheck(t *testing.T) {
r := setupTestRouter()
r.GET("/health", handler.HealthCheck)
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/health", nil)
r.ServeHTTP(w, req)
if w.Code != http.StatusOK {
t.Errorf("HealthCheck status = %d, want 200", w.Code)
}
}
// TestHealthCheckSchemaConverged_H8d：handler.HealthCheck 响应体应与
// router.RegisterHealthRoute 收敛为同一 schema（200 + {"status":"ok"}），
// 不再走 response 业务信封 {code,msg,data}。
func TestHealthCheckSchemaConverged_H8d(t *testing.T) {
r := setupTestRouter()
r.GET("/health", handler.HealthCheck)
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest("GET", "/health", nil))
body := w.Body.String()
if !strings.Contains(body, `"status":"ok"`) {
t.Fatalf("HealthCheck body = %s, want {\"status\":\"ok\"}", body)
}
if strings.Contains(body, `"code"`) || strings.Contains(body, `"data"`) {
t.Fatalf("HealthCheck should not use response envelope, got %s", body)
}
}
func TestQueryInt(t *testing.T) {
r := setupTestRouter()
r.GET("/test", func(c *gin.Context) {
page := handler.QueryInt(c, "page", 1)
c.JSON(200, gin.H{"page": page})
})
tests := []struct {
query string
expected int
}{
{"?page=10", 10},
{"?page=abc", 1}, // 无效返回默认
{"", 1}, // 无参数返回默认
}
for _, tt := range tests {
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/test"+tt.query, nil)
r.ServeHTTP(w, req)
// 验证响应包含正确的值
if w.Code != 200 {
t.Errorf("QueryInt status = %d", w.Code)
}
}
}
func TestQueryInt64(t *testing.T) {
r := setupTestRouter()
r.GET("/test", func(c *gin.Context) {
id := handler.QueryInt64(c, "id", 0)
c.JSON(200, gin.H{"id": id})
})
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/test?id=1234567890123", nil)
r.ServeHTTP(w, req)
if w.Code != 200 {
t.Errorf("QueryInt64 status = %d", w.Code)
}
}
func TestQueryFloat64(t *testing.T) {
r := setupTestRouter()
r.GET("/test", func(c *gin.Context) {
price := handler.QueryFloat64(c, "price", 0.0)
c.JSON(200, gin.H{"price": price})
})
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/test?price=99.99", nil)
r.ServeHTTP(w, req)
if w.Code != 200 {
t.Errorf("QueryFloat64 status = %d", w.Code)
}
}
func TestQueryBool(t *testing.T) {
r := setupTestRouter()
r.GET("/test", func(c *gin.Context) {
enabled := handler.QueryBool(c, "enabled", false)
c.JSON(200, gin.H{"enabled": enabled})
})
tests := []struct {
query string
expected bool
}{
{"?enabled=true", true},
{"?enabled=1", true},
{"?enabled=yes", true},
{"?enabled=false", false},
{"?enabled=0", false},
{"", false}, // 默认值
}
for _, tt := range tests {
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/test"+tt.query, nil)
r.ServeHTTP(w, req)
if w.Code != 200 {
t.Errorf("QueryBool status = %d", w.Code)
}
}
}
func TestPathInt(t *testing.T) {
r := setupTestRouter()
r.GET("/user/:id", func(c *gin.Context) {
id := handler.PathInt(c, "id", 0)
c.JSON(200, gin.H{"id": id})
})
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/user/123", nil)
r.ServeHTTP(w, req)
if w.Code != 200 {
t.Errorf("PathInt status = %d", w.Code)
}
}
func TestPathInt64(t *testing.T) {
r := setupTestRouter()
r.GET("/user/:id", func(c *gin.Context) {
id := handler.PathInt64(c, "id", 0)
c.JSON(200, gin.H{"id": id})
})
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/user/1234567890123", nil)
r.ServeHTTP(w, req)
if w.Code != 200 {
t.Errorf("PathInt64 status = %d", w.Code)
}
}
func TestGetPage(t *testing.T) {
r := setupTestRouter()
r.GET("/list", func(c *gin.Context) {
page, pageSize := handler.GetPage(c)
c.JSON(200, gin.H{"page": page, "pageSize": pageSize})
})
tests := []struct {
query string
expectedPage int
expectedSize int
}{
{"?page=2&page_size=50", 2, 50},
{"?page=0&page_size=0", 1, 20}, // 边界修正
{"?page=-1&page_size=200", 1, 100}, // 超限修正
{"", 1, 20}, // 默认值
}
for _, tt := range tests {
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/list"+tt.query, nil)
r.ServeHTTP(w, req)
if w.Code != 200 {
t.Errorf("GetPage status = %d", w.Code)
}
}
}
func TestGetIDFromPath(t *testing.T) {
r := setupTestRouter()
r.GET("/user/:id", func(c *gin.Context) {
id, ok := handler.GetIDFromPath(c, "id")
c.JSON(200, gin.H{"id": id, "ok": ok})
})
// 有效 ID
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/user/123", nil)
r.ServeHTTP(w, req)
if w.Code != 200 {
t.Errorf("GetIDFromPath status = %d", w.Code)
}
// 无效 ID
w2 := httptest.NewRecorder()
req2 := httptest.NewRequest("GET", "/user/abc", nil)
r.ServeHTTP(w2, req2)
if w2.Code != 200 {
t.Errorf("GetIDFromPath invalid status = %d", w2.Code)
}
}
// withResponseMode 切换响应模式并在测试结束后恢复为默认 ModeBusiness。
func withResponseMode(t *testing.T, m response.Mode) {
t.Helper()
response.SetMode(m)
t.Cleanup(func() { response.SetMode(response.ModeBusiness) })
}
// decodeBody 解析统一响应体。
func decodeBody(t *testing.T, w *httptest.ResponseRecorder) response.Response {
t.Helper()
var body response.Response
if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil {
t.Fatalf("decode body: %v (body=%q)", err, w.Body.String())
}
return body
}
func TestBadRequest(t *testing.T) {
// 默认 ModeBusiness：所有失败响应 HTTP 200，错误经 body code 表达。
withResponseMode(t, response.ModeBusiness)
r := setupTestRouter()
r.GET("/test", func(c *gin.Context) {
handler.BadRequest(c, "参数错误")
})
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/test", nil)
r.ServeHTTP(w, req)
if w.Code != http.StatusOK {
t.Errorf("BadRequest (ModeBusiness) status = %d, want 200", w.Code)
}
body := decodeBody(t, w)
if body.Code != response.CodeFail {
t.Errorf("BadRequest code = %d, want %d", body.Code, response.CodeFail)
}
if body.Msg != "参数错误" {
t.Errorf("BadRequest msg = %q, want %q", body.Msg, "参数错误")
}
}
func TestInternalError(t *testing.T) {
// 默认 ModeBusiness：服务器错误也走 HTTP 200，错误经 body code 表达。
withResponseMode(t, response.ModeBusiness)
r := setupTestRouter()
r.GET("/test", func(c *gin.Context) {
handler.InternalError(c, "服务器错误")
})
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/test", nil)
r.ServeHTTP(w, req)
if w.Code != http.StatusOK {
t.Errorf("InternalError (ModeBusiness) status = %d, want 200", w.Code)
}
body := decodeBody(t, w)
if body.Code != response.CodeServerError {
t.Errorf("InternalError code = %d, want %d", body.Code, response.CodeServerError)
}
}
// TestBadRequestRESTMode：ModeREST 下 CodeFail 属业务失败不映射 HTTP 错误，仍 200。
// 修复前 BadRequest 硬编 400 绕过 Mode；修复后委托 response.FailWithCode 遵循 Mode。
func TestBadRequestRESTMode(t *testing.T) {
withResponseMode(t, response.ModeREST)
r := setupTestRouter()
r.GET("/test", func(c *gin.Context) {
handler.BadRequest(c, "参数错误")
})
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest("GET", "/test", nil))
if w.Code != http.StatusOK {
t.Errorf("BadRequest (ModeREST) status = %d, want 200 (CodeFail 不映射)", w.Code)
}
body := decodeBody(t, w)
if body.Code != response.CodeFail {
t.Errorf("BadRequest code = %d, want %d", body.Code, response.CodeFail)
}
}
// TestInternalErrorRESTMode：ModeREST 下 CodeServerError 映射 HTTP 500。
func TestInternalErrorRESTMode(t *testing.T) {
withResponseMode(t, response.ModeREST)
r := setupTestRouter()
r.GET("/test", func(c *gin.Context) {
handler.InternalError(c, "服务器错误")
})
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest("GET", "/test", nil))
if w.Code != http.StatusInternalServerError {
t.Errorf("InternalError (ModeREST) status = %d, want 500", w.Code)
}
body := decodeBody(t, w)
if body.Code != response.CodeServerError {
t.Errorf("InternalError code = %d, want %d", body.Code, response.CodeServerError)
}
}
// TestBadRequestWritesRequestID：修复前 BadRequest 直接 c.JSON 不写 RequestID（丢链路）；
// 修复后委托 response 体系，经 writeResp 写入上下文中的 request_id。
func TestBadRequestWritesRequestID(t *testing.T) {
r := setupTestRouter()
r.Use(func(c *gin.Context) { c.Set("request_id", "req-123"); c.Next() })
r.GET("/test", func(c *gin.Context) {
handler.BadRequest(c, "参数错误")
})
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest("GET", "/test", nil))
body := decodeBody(t, w)
if body.RequestID != "req-123" {
t.Errorf("BadRequest request_id = %q, want %q (修复前为空)", body.RequestID, "req-123")
}
}
// TestInternalErrorWritesRequestID：同上，覆盖 InternalError。
func TestInternalErrorWritesRequestID(t *testing.T) {
r := setupTestRouter()
r.Use(func(c *gin.Context) { c.Set("request_id", "req-456"); c.Next() })
r.GET("/test", func(c *gin.Context) {
handler.InternalError(c, "服务器错误")
})
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest("GET", "/test", nil))
body := decodeBody(t, w)
if body.RequestID != "req-456" {
t.Errorf("InternalError request_id = %q, want %q (修复前为空)", body.RequestID, "req-456")
}
}
func TestBindJSON(t *testing.T) {
r := setupTestRouter()
r.POST("/test", func(c *gin.Context) {
var req struct {
Name string `json:"name"`
}
if err := handler.BindJSON(c, &req); err != nil {
handler.BadRequest(c, "绑定失败")
return
}
c.JSON(200, req)
})
// 有效 JSON
w := httptest.NewRecorder()
req := httptest.NewRequest("POST", "/test", strings.NewReader(`{"name":"test"}`))
req.Header.Set("Content-Type", "application/json")
r.ServeHTTP(w, req)
if w.Code != 200 {
t.Errorf("BindJSON valid status = %d", w.Code)
}
}
func TestBindJSONWithMaxBytesRejectsOversizedBody_M6(t *testing.T) {
r := setupTestRouter()
r.POST("/test", func(c *gin.Context) {
var req struct {
Name string `json:"name"`
}
if err := handler.BindJSONWithMaxBytes(c, &req, 8); err == nil {
c.JSON(http.StatusOK, req)
return
}
handler.BadRequest(c, "绑定失败")
})
w := httptest.NewRecorder()
req := httptest.NewRequest("POST", "/test", strings.NewReader(`{"name":"body-too-large"}`))
req.Header.Set("Content-Type", "application/json")
r.ServeHTTP(w, req)
body := decodeBody(t, w)
if body.Code != response.CodeFail {
t.Fatalf("oversized BindJSON code = %d, want %d", body.Code, response.CodeFail)
}
}
jwt/jwt.go
+526
View File
@@ -0,0 +1,526 @@
package jwt
import (
"context"
"crypto/rand"
"encoding/base64"
"errors"
"fmt"
"strings"
"sync"
"sync/atomic"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/database"
"github.com/EthanCodeCraft/xlgo-core/logger"
"github.com/golang-jwt/jwt/v5"
"github.com/redis/go-redis/v9"
"go.uber.org/zap"
)
// Claims JWT 声明
type Claims struct {
UserID uint `json:"user_id"`
Username string `json:"username"`
Role string `json:"role"` // admin 或 staff
UserType string `json:"user_type"` // super_admin, admin, staff
JTI string `json:"jti"` // JWT ID（唯一标识，用于黑名单）
jwt.RegisteredClaims
}
var (
//ErrTokenExpired 令牌已过期
ErrTokenExpired = errors.New("令牌已过期")
//ErrTokenInvalid 令牌无效
ErrTokenInvalid = errors.New("令牌无效")
//ErrTokenMalformed 令牌格式错误
ErrTokenMalformed = errors.New("令牌格式错误")
//ErrTokenNotValidYet 令牌尚未生效
ErrTokenNotValidYet = errors.New("令牌尚未生效")
//ErrTokenRevoked 令牌已被撤销
ErrTokenRevoked = errors.New("令牌已被撤销")
// ErrBlacklistUnavailable Redis 未初始化或不可用，黑名单功能失效（C9a 修复）。
// Add 返回此错误使调用方（RefreshToken/InvalidateToken）感知黑名单不可用并 fail-closed，
// 避免无 Redis 时静默成功致撤销/刷新失效、新旧 token 双有效。
// IsBlacklisted 在无 Redis 时仍返回 false（验证侧 fail-open 是无 Redis 部署的固有局限，
// 文档约束：安全敏感场景必须启用 Redis）。
ErrBlacklistUnavailable = errors.New("token 黑名单不可用：Redis 未初始化")
// ErrEmptySecret JWT 密钥为空（P0 修复）。空 secret 意味着以零长度 HMAC 密钥签发/校验，
// 任何以 "" 签名的 token 都会通过——签发与校验一律 fail-closed 拒绝，杜绝该空密钥绕过。
ErrEmptySecret = errors.New("jwt.secret 未配置：拒绝签发/校验（防空密钥导致任意 token 通过）")
// ErrUnsupportedAlgorithm 配置了不支持的签名算法（P0 修复）。
// 本实现仅支持 HMAC 族（HS256/HS384/HS512）；RS256 等非对称算法暂不支持，
// 不再静默回退 HS256——避免用户误以为在用非对称算法、实则 HMAC，并助长算法混淆攻击。
ErrUnsupportedAlgorithm = errors.New("jwt: 不支持的签名算法（仅支持 HS256/HS384/HS512）")
// ErrInvalidExpiry 过期时间非法。签发非正过期时间的 token 会立即失效或产生不可预期会话语义。
ErrInvalidExpiry = errors.New("jwt: 过期时间必须大于 0")
// ErrEmptyJTI 空 JTI 无法匹配任何正常 token，却会写入 jwt_bl: 这种永不命中的黑名单键。
ErrEmptyJTI = errors.New("jwt: jti 不能为空")
)
// validMethods 允许的签名算法名（HMAC 族）。ParseWithClaims 传 jwt.WithValidMethods 固定算法，
// 防算法混淆（alg confusion，P0）：拒绝 alg=none 及非 HMAC 算法——否则若部署配置为非对称算法，
// 攻击者可用公钥作为 HMAC 密钥伪造 token 通过校验。
var validMethods = []string{"HS256", "HS384", "HS512"}
// secretKey 返回 HMAC 密钥字节；cfg 为 nil 或密钥为空时 fail-closed 返回 ErrEmptySecret（P0）。
func secretKey(cfg *config.Config) ([]byte, error) {
if cfg == nil || cfg.JWT.Secret == "" {
return nil, ErrEmptySecret
}
return []byte(cfg.JWT.Secret), nil
}
// hmacKeyfunc 构造校验签名方法为 HMAC 族并返回密钥的 jwt.Keyfunc（P0：防算法混淆 + 空密钥）。
// 双重防护：① 断言 token.Method 为 *jwt.SigningMethodHMAC，拒绝非 HMAC（含 none/RS/ES）；
// ② 经 secretKey 拒绝空密钥。配合 ParseWithClaims 的 jwt.WithValidMethods(validMethods) 使用。
func hmacKeyfunc(cfg *config.Config) jwt.Keyfunc {
return func(token *jwt.Token) (any, error) {
if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
return nil, fmt.Errorf("%w: 期望 HMAC，实际 alg=%v", ErrUnsupportedAlgorithm, token.Header["alg"])
}
return secretKey(cfg)
}
}
// generateJTI 生成唯一的 JWT ID
func generateJTI() (string, error) {
bytes := make([]byte, 16)
if _, err := rand.Read(bytes); err != nil {
return "", fmt.Errorf("生成 JTI 失败: %w", err)
}
return base64.URLEncoding.EncodeToString(bytes), nil
}
// TokenBlacklist Token 黑名单管理（使用 JTI 优化）。
// client 为 nil 时回退到 database.GetRedis()，兼容存量未注入场景。
type TokenBlacklist struct {
client *redis.Client
}
// NewTokenBlacklist 创建黑名单实例，client 可为 nil（懒取全局 Redis）。
func NewTokenBlacklist(client *redis.Client) *TokenBlacklist {
return &TokenBlacklist{client: client}
}
func (tb *TokenBlacklist) redisClient() *redis.Client {
if tb != nil && tb.client != nil {
return tb.client
}
return database.GetRedis()
}
// blacklistOpTimeout 黑名单 Redis 操作的上下文超时（M-A 修复）。
// Redis 客户端已配 ReadTimeout/WriteTimeout=3s（redis.go D7），但鉴权热路径（ParseToken
// 每次调 IsBlacklisted）需更紧边界——显式 ctx 超时把鉴权阻塞上限收敛到 1s，避免 Redis
// 挂起时每个鉴权请求被长时间拖住。健康 Redis 下 Exists/SET 为亚毫秒级，1s 余量充足。
// 注：ctx 超时只约束命令往返，不影响 Set 的服务端 TTL（ttl 可远大于 1s）。
const blacklistOpTimeout = 1 * time.Second
// BlacklistPolicy 控制解析 Token 时遇到黑名单查询错误的处理策略。
// ParseToken 默认 BlacklistFailClosed（黑名单不可检查即拒绝）；
// 需显式 fail-open（仅无 Redis 或低安全场景）用 ParseTokenWithBlacklistPolicy(..., BlacklistFailOpen)。
type BlacklistPolicy int
const (
// BlacklistFailOpen 黑名单查询出错时放行 Token（仅用于无 Redis 或低安全场景，非默认）。
BlacklistFailOpen BlacklistPolicy = iota
// BlacklistFailClosed 黑名单查询出错时拒绝 Token（默认；ParseToken 即用此策略）。
BlacklistFailClosed
)
// blacklistCtx 创建带超时的 context 用于黑名单 Redis 操作（M-A）。
func blacklistCtx() (context.Context, context.CancelFunc) {
return context.WithTimeout(context.Background(), blacklistOpTimeout)
}
// Add 将 Token 的 JTI 加入黑名单
// 参数: jti JWT ID，expiry Token 过期时间
//
// 无 Redis 时返回 ErrBlacklistUnavailable（C9a 修复）：让调用方（RefreshToken/InvalidateToken）
// 感知黑名单不可用并 fail-closed，避免无 Redis 时静默成功致撤销失效。
func (tb *TokenBlacklist) Add(jti string, expiry time.Time) error {
if strings.TrimSpace(jti) == "" {
return ErrEmptyJTI
}
client := tb.redisClient()
if client == nil {
// Redis 未启用，黑名单不可用——fail-closed 让调用方决策。
return ErrBlacklistUnavailable
}
ctx, cancel := blacklistCtx()
defer cancel()
ttl := time.Until(expiry)
if ttl <= 0 {
// Token 已过期，无需加入黑名单
return nil
}
// 使用 JTI 作为键名（约24字节），而非完整 Token（数百字节）
key := fmt.Sprintf("jwt_bl:%s", jti)
return client.Set(ctx, key, "1", ttl).Err()
}
// IsBlacklisted 检查 JTI 是否在黑名单中。
// 命中返回 (true, nil)；未命中返回 (false, nil)；
// Redis 未启用或不可达返回 (false, ErrBlacklistUnavailable)，由调用方决定 fail-open/fail-closed。
func (tb *TokenBlacklist) IsBlacklisted(jti string) (bool, error) {
client := tb.redisClient()
if client == nil {
return false, ErrBlacklistUnavailable
}
ctx, cancel := blacklistCtx()
defer cancel()
key := fmt.Sprintf("jwt_bl:%s", jti)
n, err := client.Exists(ctx, key).Result()
if err != nil {
return false, err
}
return n > 0, nil
}
// Manager JWT 管理器（#10）。持有独立的 TokenBlacklist，
// 支持多实例（如区分 user-token 与 refresh-token 黑名单）。
type Manager struct {
mu sync.Mutex
blacklist *TokenBlacklist
}
// defaultManager 是全局默认 JWT 管理器的真实存储，经 atomic 读写（C9c）。
var defaultManager atomic.Pointer[Manager]
func init() {
defaultManager.Store(NewJWTManager())
}
// currentManager 返回全局默认 JWT 管理器（atomic 读取，C9c）。
// 正常情况下 init 后永不为 nil；防御性地在极罕见的 nil 情况下回退一个懒取 Redis 的实例。
func currentManager() *Manager {
if m := defaultManager.Load(); m != nil {
return m
}
m := NewJWTManager()
defaultManager.Store(m)
return m
}
// GetDefaultJWT 返回全局默认 JWT 管理器（并发安全，C9c/J1 修复）。
// 替代已删除的 DefaultJWT 包级变量。
func GetDefaultJWT() *Manager {
return currentManager()
}
// currentBlacklist 返回全局默认 Manager 持有的黑名单（atomic 读取 Manager 后经 Blacklist()，C9c）。
func currentBlacklist() *TokenBlacklist {
return currentManager().Blacklist()
}
// NewJWTManager 创建 JWT 管理器实例（blacklist 懒取全局 Redis）。
func NewJWTManager() *Manager {
return &Manager{blacklist: NewTokenBlacklist(nil)}
}
// NewJWTManagerWithRedis 创建 JWT 管理器并注入指定 Redis 客户端（用于多 Redis/测试隔离）。
func NewJWTManagerWithRedis(client *redis.Client) *Manager {
return &Manager{blacklist: NewTokenBlacklist(client)}
}
// SetDefaultJWTManager 提升指定 Manager 为全局默认（atomic 置换，并发安全，J1 修复）。
func SetDefaultJWTManager(m *Manager) {
if m == nil {
return
}
defaultManager.Store(m)
}
// Blacklist 返回 Manager 持有的黑名单实例。
func (m *Manager) Blacklist() *TokenBlacklist {
m.mu.Lock()
defer m.mu.Unlock()
return m.blacklist
}
// GenerateToken 生成 JWT Token
func GenerateToken(userID uint, username, role, userType string) (string, error) {
cfg := config.Get()
var expiry time.Duration
if cfg != nil {
expiry = cfg.JWT.Expire
}
return generateTokenWithExpiry(cfg, userID, username, role, userType, expiry)
}
func generateTokenWithExpiry(cfg *config.Config, userID uint, username, role, userType string, expiry time.Duration) (string, error) {
if expiry <= 0 {
return "", ErrInvalidExpiry
}
// P0：先校验密钥非空与算法受支持（fail-closed）。secretKey 亦守卫 cfg==nil，
// 通过后 cfg 保证非空，后续访问 cfg.JWT.* 安全。
key, err := secretKey(cfg)
if err != nil {
return "", err
}
method, err := signingMethod(cfg.JWT.Algorithm)
if err != nil {
return "", err
}
// 生成唯一的 JWT ID
jti, err := generateJTI()
if err != nil {
return "", err
}
claims := Claims{
UserID: userID,
Username: username,
Role: role,
UserType: userType,
JTI: jti,
RegisteredClaims: jwt.RegisteredClaims{
ExpiresAt: jwt.NewNumericDate(time.Now().Add(expiry)),
IssuedAt: jwt.NewNumericDate(time.Now()),
NotBefore: jwt.NewNumericDate(time.Now()),
Issuer: issuerOrDefault(cfg.JWT.Issuer),
ID: jti, // 同时设置到 RegisteredClaims.ID
},
}
token := jwt.NewWithClaims(method, claims)
return token.SignedString(key)
}
// GenerateTokenWithCustomExpiry 生成带自定义过期时间的 Token
func GenerateTokenWithCustomExpiry(userID uint, username, role, userType string, expireSeconds int) (string, error) {
cfg := config.Get()
if expireSeconds <= 0 {
return "", ErrInvalidExpiry
}
return generateTokenWithExpiry(cfg, userID, username, role, userType, time.Duration(expireSeconds)*time.Second)
}
// issuerOrDefault 返回配置的 issuer，未配置时回退 "xlgo"。
func issuerOrDefault(issuer string) string {
if issuer == "" {
return "xlgo"
}
return issuer
}
// signingMethod 根据 algorithm 配置返回 HMAC 签名方法。
// 支持 HS256（默认，空值等价）/HS384/HS512；其它值（含 RS256 等非对称算法，暂不支持）
// 返回 ErrUnsupportedAlgorithm，不再静默回退 HS256（P0：防"配 RS256 实得 HMAC"的算法混淆隐患）。
func signingMethod(algorithm string) (jwt.SigningMethod, error) {
switch strings.ToUpper(strings.TrimSpace(algorithm)) {
case "", "HS256":
return jwt.SigningMethodHS256, nil
case "HS384":
return jwt.SigningMethodHS384, nil
case "HS512":
return jwt.SigningMethodHS512, nil
default:
return nil, fmt.Errorf("%w: %q", ErrUnsupportedAlgorithm, algorithm)
}
}
func parseOptions(cfg *config.Config) []jwt.ParserOption {
issuer := "xlgo"
if cfg != nil {
issuer = issuerOrDefault(cfg.JWT.Issuer)
}
return []jwt.ParserOption{
jwt.WithValidMethods(validMethods),
jwt.WithIssuer(issuer),
}
}
func validateIssuer(cfg *config.Config, claims *Claims) error {
want := "xlgo"
if cfg != nil {
want = issuerOrDefault(cfg.JWT.Issuer)
}
if claims == nil || claims.Issuer != want {
return ErrTokenInvalid
}
return nil
}
func mapParseTokenError(err error) error {
if errors.Is(err, jwt.ErrTokenExpired) {
return ErrTokenExpired
}
if errors.Is(err, jwt.ErrTokenMalformed) {
return ErrTokenMalformed
}
if errors.Is(err, jwt.ErrTokenNotValidYet) {
return ErrTokenNotValidYet
}
if errors.Is(err, ErrEmptySecret) {
return ErrEmptySecret
}
if errors.Is(err, ErrUnsupportedAlgorithm) {
return ErrUnsupportedAlgorithm
}
return fmt.Errorf("%w: %w", ErrTokenInvalid, err)
}
func checkTokenBlacklist(claims *Claims, policy BlacklistPolicy) error {
if claims == nil || claims.JTI == "" {
return nil
}
revoked, err := currentBlacklist().IsBlacklisted(claims.JTI)
if err != nil {
if policy == BlacklistFailClosed {
return err
}
logger.Warn("JWT 黑名单检查失败，fail-open 策略放行 token", zap.String("jti", claims.JTI), zap.Error(err))
return nil
}
if revoked {
return ErrTokenRevoked
}
return nil
}
// ParseToken 解析 JWT Token。默认 fail-closed：黑名单后端不可检查时返回
// ErrBlacklistUnavailable，拒绝该 Token。需要显式 fail-open（仅无 Redis 或低安全场景）
// 请用 ParseTokenWithBlacklistPolicy(token, BlacklistFailOpen)。
func ParseToken(tokenString string) (*Claims, error) {
return ParseTokenWithBlacklistPolicy(tokenString, BlacklistFailClosed)
}
// ParseTokenWithBlacklistPolicy 使用显式黑名单查询策略解析 JWT Token。
func ParseTokenWithBlacklistPolicy(tokenString string, policy BlacklistPolicy) (*Claims, error) {
cfg := config.Get()
token, err := jwt.ParseWithClaims(tokenString, &Claims{}, hmacKeyfunc(cfg), parseOptions(cfg)...)
if err != nil {
return nil, mapParseTokenError(err)
}
if claims, ok := token.Claims.(*Claims); ok && token.Valid {
// 使用 JTI 检查黑名单（更高效）
if err := checkTokenBlacklist(claims, policy); err != nil {
return nil, err
}
return claims, nil
}
return nil, ErrTokenInvalid
}
// InvalidateToken 使 Token 失效（加入黑名单）
func InvalidateToken(tokenString string) error {
cfg := config.Get()
opts := append(parseOptions(cfg), jwt.WithoutClaimsValidation())
token, err := jwt.ParseWithClaims(tokenString, &Claims{}, hmacKeyfunc(cfg), opts...)
if err != nil {
// Token 签名/格式/issuer 无效，无需加入黑名单。
return nil
}
if claims, ok := token.Claims.(*Claims); ok {
if err := validateIssuer(cfg, claims); err != nil {
return nil
}
if strings.TrimSpace(claims.JTI) == "" {
return ErrEmptyJTI
}
if claims.ExpiresAt != nil {
return currentBlacklist().Add(claims.JTI, claims.ExpiresAt.Time)
}
}
return nil
}
// InvalidateTokenByID 直接通过 JTI 使 Token 失效
// 参数: jti JWT ID，expiry 过期时间
func InvalidateTokenByID(jti string, expiry time.Time) error {
if strings.TrimSpace(jti) == "" {
return ErrEmptyJTI
}
return currentBlacklist().Add(jti, expiry)
}
// RefreshToken 刷新 Token
//
// 安全约束（C9b 修复）：将旧 Token 加入黑名单的 Add 错误必须向上传播——若 Add 失败
// （Redis 抖动或未启用）仍签发新 token，会导致旧 token 未拉黑、新旧 token 双有效，
// 形成会话固定窗口。故 Add 失败时不签发新 token（fail-closed）。
func RefreshToken(tokenString string) (string, error) {
claims, err := ParseToken(tokenString)
if err != nil {
return "", err
}
// 将旧 Token 加入黑名单；失败则不签发新 token（C9b：禁止吞 Add 错误）。
if strings.TrimSpace(claims.JTI) == "" {
return "", ErrEmptyJTI
}
if claims.ExpiresAt != nil {
if err := currentBlacklist().Add(claims.JTI, claims.ExpiresAt.Time); err != nil {
return "", fmt.Errorf("刷新令牌失败：旧令牌撤销失败: %w", err)
}
}
cfg := config.Get()
var expiry time.Duration
if cfg != nil {
expiry = cfg.JWT.RefreshExpire
}
if expiry <= 0 && cfg != nil {
expiry = cfg.JWT.Expire
}
return generateTokenWithExpiry(cfg, claims.UserID, claims.Username, claims.Role, claims.UserType, expiry)
}
// GetJTI 从 Token 中提取 JTI（不验证签名）
// 用于需要在验证前获取 JTI 的场景
func GetJTI(tokenString string) (string, error) {
token, _, err := jwt.NewParser().ParseUnverified(tokenString, &Claims{})
if err != nil {
return "", err
}
if claims, ok := token.Claims.(*Claims); ok {
return claims.JTI, nil
}
return "", ErrTokenInvalid
}
// IsTokenRevoked 检查 Token 是否被撤销（通过 JTI）。
// 返回 (是否撤销, 错误)；黑名单后端不可用时返回 (false, ErrBlacklistUnavailable)。
func IsTokenRevoked(jti string) (bool, error) {
return currentBlacklist().IsBlacklisted(jti)
}
// GetClaimsFromToken 获取 Token 的 Claims（不验证过期）
// 用于获取已过期 Token 的信息
func GetClaimsFromToken(tokenString string) (*Claims, error) {
cfg := config.Get()
opts := append(parseOptions(cfg), jwt.WithoutClaimsValidation())
token, err := jwt.ParseWithClaims(tokenString, &Claims{}, hmacKeyfunc(cfg), opts...)
if err != nil {
return nil, err
}
if claims, ok := token.Claims.(*Claims); ok {
if err := validateIssuer(cfg, claims); err != nil {
return nil, err
}
return claims, nil
}
return nil, ErrTokenInvalid
}
jwt/jwt_c9c_internal_test.go
+142
View File
@@ -0,0 +1,142 @@
package jwt
import (
"sync"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/alicebob/miniredis/v2"
"github.com/redis/go-redis/v9"
)
// c9cSetupConfig 注入测试用 JWT 配置（内部测试无法访问 jwt_test 的 setupTestConfig）。
func c9cSetupConfig(t *testing.T) {
t.Helper()
config.Set(&config.Config{
JWT: config.JWTConfig{
Secret: "test-secret-key-1234567890123456789012", // ≥32 字节
Expire: time.Hour,
},
})
}
// TestC9cConcurrentSetDefaultAndRead 验证 SetDefaultJWTManager（写）与包级函数
// （读 currentBlacklist → currentManager → defaultManager.Load）并发无数据竞争（C9c）。
// 修复前 tokenBlacklist 为裸包级指针，SetDefaultJWTManager 裸写、ParseToken/IsTokenRevoked/
// InvalidateTokenByID 裸读，-race 必采到指针读写竞争。
func TestC9cConcurrentSetDefaultAndRead(t *testing.T) {
c9cSetupConfig(t)
t.Cleanup(func() { SetDefaultJWTManager(NewJWTManager()) }) // 还原无 Redis 基线
mr := miniredis.RunT(t)
client := redis.NewClient(&redis.Options{Addr: mr.Addr()})
t.Cleanup(func() { _ = client.Close() })
// 预生成一个合法 token 供读者 ParseToken（JTI 随机，不会被下方 InvalidateTokenByID 的固定 jti 命中）
token, err := GenerateToken(1, "u", "admin", "super_admin")
if err != nil {
t.Fatalf("GenerateToken: %v", err)
}
var wg sync.WaitGroup
stop := make(chan struct{})
// 写者：在"注入 Redis"与"无 Redis"Manager 间原子置换（模拟启动期/测试期 SetDefaultJWTManager）
wg.Add(1)
go func() {
defer wg.Done()
withRedis := NewJWTManagerWithRedis(client)
withoutRedis := NewJWTManager()
for i := 0; ; i++ {
select {
case <-stop:
return
default:
}
if i%2 == 0 {
SetDefaultJWTManager(withRedis)
} else {
SetDefaultJWTManager(withoutRedis)
}
}
}()
// 读者：并发调用经 currentBlacklist() 的包级函数 + currentManager
for range 4 {
wg.Add(1)
go func() {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
_, _ = ParseToken(token)
_, _ = IsTokenRevoked("some-jti")
_ = InvalidateTokenByID("some-jti", time.Now().Add(time.Hour))
_ = currentManager()
}
}()
}
// 让竞争窗口运行一段时间，确保 -race 能采到（若有未加锁读）
time.Sleep(50 * time.Millisecond)
close(stop)
wg.Wait()
}
// TestC9cCurrentManagerReflectsSwap 验证 SetDefaultJWTManager 原子置换后，
// 包级函数经 currentManager 读到的是新 Manager 的 blacklist（C9c 一致性）。
func TestC9cCurrentManagerReflectsSwap(t *testing.T) {
c9cSetupConfig(t)
t.Cleanup(func() { SetDefaultJWTManager(NewJWTManager()) })
// 基线：无 Redis，InvalidateTokenByID 返 ErrBlacklistUnavailable
if err := InvalidateTokenByID("jti-1", time.Now().Add(time.Hour)); !errorIsBlacklistUnavailable(err) {
t.Fatalf("baseline without Redis: want ErrBlacklistUnavailable, got %v", err)
}
// 置换为注入 Redis 的 Manager
mr := miniredis.RunT(t)
client := redis.NewClient(&redis.Options{Addr: mr.Addr()})
t.Cleanup(func() { _ = client.Close() })
SetDefaultJWTManager(NewJWTManagerWithRedis(client))
// 置换后包级函数应读到新 blacklist（Redis 可用），InvalidateTokenByID 成功
if err := InvalidateTokenByID("jti-2", time.Now().Add(time.Hour)); err != nil {
t.Fatalf("after swap to Redis Manager: InvalidateTokenByID err = %v, want nil", err)
}
// currentManager 应等于刚 Store 的 Manager
m := currentManager()
if m == nil {
t.Fatal("currentManager should not be nil")
}
}
// TestC9cDefaultJWTAliasConsistent 验证 GetDefaultJWT 与 defaultManager 真实存储一致。
func TestC9cDefaultJWTAliasConsistent(t *testing.T) {
t.Cleanup(func() { SetDefaultJWTManager(NewJWTManager()) })
// init 后 GetDefaultJWT 与 currentManager 应指向同一实例
if GetDefaultJWT() != currentManager() {
t.Fatal("GetDefaultJWT should equal currentManager after init")
}
// SetDefaultJWTManager 后同步
m := NewJWTManagerWithRedis(nil)
SetDefaultJWTManager(m)
if GetDefaultJWT() != m {
t.Fatal("GetDefaultJWT should sync after SetDefaultJWTManager")
}
if currentManager() != m {
t.Fatal("currentManager should reflect SetDefaultJWTManager")
}
}
// errorIsBlacklistUnavailable 避免内部测试依赖 errors.Is 包装判断。
func errorIsBlacklistUnavailable(err error) bool {
return err != nil && err.Error() == ErrBlacklistUnavailable.Error()
}
jwt/jwt_test.go
+578
View File
@@ -0,0 +1,578 @@
package jwt_test
import (
"errors"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/jwt"
"github.com/alicebob/miniredis/v2"
gojwt "github.com/golang-jwt/jwt/v5"
"github.com/redis/go-redis/v9"
)
func setupTestConfig() {
// 设置测试配置
cfg := &config.Config{
JWT: config.JWTConfig{
Secret: "test-secret-key-1234567890123456789012", // ≥32 字节
Expire: time.Hour, // 1小时
},
}
config.Set(cfg)
}
func TestGenerateToken(t *testing.T) {
setupTestConfig()
token, err := jwt.GenerateToken(1, "testuser", "admin", "super_admin")
if err != nil {
t.Fatalf("GenerateToken error: %v", err)
}
if token == "" {
t.Error("GenerateToken should return non-empty token")
}
// Token 应包含三部分（用 . 分隔）
parts := splitToken(token)
if len(parts) != 3 {
t.Errorf("Token should have 3 parts, got %d", len(parts))
}
}
func TestParseToken(t *testing.T) {
setupTestConfig()
setupMiniRedis(t)
// 先生成 token
token, _ := jwt.GenerateToken(1, "testuser", "admin", "super_admin")
// 解析 token
claims, err := jwt.ParseToken(token)
if err != nil {
t.Fatalf("ParseToken error: %v", err)
}
if claims.UserID != 1 {
t.Errorf("UserID = %d, want 1", claims.UserID)
}
if claims.Username != "testuser" {
t.Errorf("Username = %s, want testuser", claims.Username)
}
if claims.Role != "admin" {
t.Errorf("Role = %s, want admin", claims.Role)
}
if claims.UserType != "super_admin" {
t.Errorf("UserType = %s, want super_admin", claims.UserType)
}
}
func TestParseTokenInvalid(t *testing.T) {
setupTestConfig()
// 无效 token
_, err := jwt.ParseToken("invalid-token")
if err == nil {
t.Error("ParseToken should fail with invalid token")
}
// 空 token
_, err = jwt.ParseToken("")
if err == nil {
t.Error("ParseToken should fail with empty token")
}
}
func TestParseTokenWrongSecret(t *testing.T) {
setupTestConfig()
// 用不同 secret 生成的 token
token, _ := jwt.GenerateToken(1, "test", "admin", "admin")
// 修改 secret
cfg := &config.Config{
JWT: config.JWTConfig{
Secret: "different-secret-key-12345678901234567890",
Expire: 3600,
},
}
if err := config.Set(cfg); err != nil {
t.Fatalf("Set wrong secret config: %v", err)
}
// 应该解析失败
_, err := jwt.ParseToken(token)
if err == nil {
t.Error("ParseToken should fail with wrong secret")
}
}
func TestRefreshToken(t *testing.T) {
setupTestConfig()
// 生成 token
token, _ := jwt.GenerateToken(1, "testuser", "admin", "super_admin")
// 无 Redis 时 RefreshToken 必须 fail-closed（C9b 修复：旧 token 撤销失败不签发新 token）
_, err := jwt.RefreshToken(token)
if !errors.Is(err, jwt.ErrBlacklistUnavailable) {
t.Errorf("RefreshToken without Redis should fail with ErrBlacklistUnavailable, got %v", err)
}
}
// setupMiniRedis 启动 miniredis 并注入到 jwt 包级 tokenBlacklist（经 SetDefaultJWTManager）。
// 测试结束 cleanup 还原为无 Redis 的默认 Manager，避免污染后续测试（-shuffle 下尤其关键）。
func setupMiniRedis(t *testing.T) *miniredis.Miniredis {
t.Helper()
mr := miniredis.RunT(t)
client := redis.NewClient(&redis.Options{Addr: mr.Addr()})
t.Cleanup(func() {
_ = client.Close()
// 还原包级 tokenBlacklist 为无 Redis 默认 Manager，避免残留指向已关闭 miniredis 的 client。
jwt.SetDefaultJWTManager(jwt.NewJWTManager())
})
// 用注入 Redis 的 Manager 替换默认，使包级 tokenBlacklist 指向 miniredis。
jwt.SetDefaultJWTManager(jwt.NewJWTManagerWithRedis(client))
return mr
}
func TestClaimsStructure(t *testing.T) {
claims := jwt.Claims{
UserID: 1,
Username: "test",
Role: "admin",
UserType: "super_admin",
}
if claims.UserID != 1 {
t.Error("Claims UserID failed")
}
if claims.Username != "test" {
t.Error("Claims Username failed")
}
if claims.Role != "admin" {
t.Error("Claims Username failed")
}
if claims.UserType != "super_admin" {
t.Error("Claims Username failed")
}
}
func TestErrorDefinitions(t *testing.T) {
if jwt.ErrTokenExpired == nil {
t.Error("ErrTokenExpired should be defined")
}
if jwt.ErrTokenInvalid == nil {
t.Error("ErrTokenInvalid should be defined")
}
if jwt.ErrTokenMalformed == nil {
t.Error("ErrTokenMalformed should be defined")
}
if jwt.ErrTokenNotValidYet == nil {
t.Error("ErrTokenNotValidYet should be defined")
}
}
func TestTokenBlacklist(t *testing.T) {
tb := jwt.TokenBlacklist{}
// 无 Redis 时，Add 应返回 ErrBlacklistUnavailable（C9a 修复：fail-closed）
err := tb.Add("test-token", time.Now().Add(time.Hour))
if !errors.Is(err, jwt.ErrBlacklistUnavailable) {
t.Errorf("TokenBlacklist.Add without Redis should return ErrBlacklistUnavailable, got %v", err)
}
// 无 Redis 时，IsBlacklisted 返回 (false, ErrBlacklistUnavailable)（fail-closed：错误上抛）
revoked, err := tb.IsBlacklisted("test-token")
if revoked || !errors.Is(err, jwt.ErrBlacklistUnavailable) {
t.Errorf("TokenBlacklist.IsBlacklisted without Redis = (%v, %v), want (false, ErrBlacklistUnavailable)", revoked, err)
}
}
func TestInvalidateToken(t *testing.T) {
setupTestConfig()
token, _ := jwt.GenerateToken(1, "test", "admin", "admin")
// 无 Redis 时应返回 ErrBlacklistUnavailable（C9a 修复：fail-closed，不再静默成功）
err := jwt.InvalidateToken(token)
if !errors.Is(err, jwt.ErrBlacklistUnavailable) {
t.Errorf("InvalidateToken without Redis should return ErrBlacklistUnavailable, got %v", err)
}
}
func splitToken(token string) []string {
count := 0
for _, c := range token {
if c == '.' {
count++
}
}
if count != 2 {
return []string{}
}
start := 0
result := make([]string, 0, 3)
for i, c := range token {
if c == '.' {
result = append(result, token[start:i])
start = i + 1
}
}
result = append(result, token[start:])
return result
}
// ===== C9b 回归：刷新令牌撤销闭环 =====
// 回归 C9b：RefreshToken 成功后，旧 token 必须被拉黑（ParseToken 返 ErrTokenRevoked），
// 新 token 可用。旧实现丢弃 Add 错误仍签发新 token，旧 token 仍有效（双有效）。
func TestRefreshTokenRevokesOldToken(t *testing.T) {
setupTestConfig()
setupMiniRedis(t)
token, _ := jwt.GenerateToken(1, "testuser", "admin", "super_admin")
// 刷新
newToken, err := jwt.RefreshToken(token)
if err != nil {
t.Fatalf("RefreshToken: %v", err)
}
if newToken == "" {
t.Fatal("RefreshToken should return non-empty token")
}
// 新 token 可解析
newClaims, err := jwt.ParseToken(newToken)
if err != nil {
t.Fatalf("ParseToken new token: %v", err)
}
if newClaims.Username != "testuser" {
t.Error("new token claims should match original")
}
// 旧 token 必须已被拉黑（C9b 核心）
_, err = jwt.ParseToken(token)
if !errors.Is(err, jwt.ErrTokenRevoked) {
t.Errorf("old token after refresh err = %v, want ErrTokenRevoked (C9b: old must be blacklisted)", err)
}
}
// 回归 C9b：Redis 抖动（Add 失败）时 RefreshToken 必须 fail-closed，不签发新 token。
// 旧实现丢弃 Add 错误仍签发新 token → 旧 token 未拉黑、新旧双有效。
func TestRefreshTokenFailsOnRedisError(t *testing.T) {
setupTestConfig()
mr := setupMiniRedis(t)
token, _ := jwt.GenerateToken(1, "testuser", "admin", "super_admin")
// 模拟 Redis 抖动：关闭 miniredis，使 Add 的 Set 失败。
mr.Close()
_, err := jwt.RefreshToken(token)
if err == nil {
t.Fatal("RefreshToken should fail when Redis unavailable (C9b: must not issue new token)")
}
// 不应是 ErrBlacklistUnavailable（那是无 Redis 路径），而是 Add 的 Set 错误包装。
// 关键：未签发新 token，旧 token 未被拉黑（因 Add 失败）。
}
// 回归 C9a/b：InvalidateToken 闭环——登出后 token 被拉黑、ParseToken 返 ErrTokenRevoked。
func TestInvalidateTokenRevokesToken(t *testing.T) {
setupTestConfig()
setupMiniRedis(t)
token, _ := jwt.GenerateToken(1, "test", "admin", "admin")
// 登出前可解析
if _, err := jwt.ParseToken(token); err != nil {
t.Fatalf("ParseToken before invalidate: %v", err)
}
// 登出（拉黑）
if err := jwt.InvalidateToken(token); err != nil {
t.Fatalf("InvalidateToken: %v", err)
}
// 登出后必须被拉黑
_, err := jwt.ParseToken(token)
if !errors.Is(err, jwt.ErrTokenRevoked) {
t.Errorf("ParseToken after invalidate err = %v, want ErrTokenRevoked", err)
}
}
// 回归 C9a：无 Redis 时 InvalidateTokenByID 返 ErrBlacklistUnavailable（fail-closed）。
func TestInvalidateTokenByIDNoRedis(t *testing.T) {
setupTestConfig()
// 不 setupMiniRedis → tokenBlacklist 指向无 Redis 的 Manager
jwt.SetDefaultJWTManager(jwt.NewJWTManager())
t.Cleanup(func() { jwt.SetDefaultJWTManager(jwt.NewJWTManager()) }) // 还原基线
err := jwt.InvalidateTokenByID("some-jti", time.Now().Add(time.Hour))
if !errors.Is(err, jwt.ErrBlacklistUnavailable) {
t.Errorf("InvalidateTokenByID without Redis err = %v, want ErrBlacklistUnavailable", err)
}
}
// ===== P0 回归：算法混淆 / 空密钥 / 不支持算法 =====
// 回归 P0：alg=none 的 token 必须被拒（jwt.WithValidMethods 固定 HMAC 族）。
// 这是算法混淆攻击的一种典型形态——攻击者去掉签名并将 alg 置为 none。
func TestParseTokenRejectsAlgNone(t *testing.T) {
setupTestConfig()
claims := jwt.Claims{UserID: 1, Username: "attacker", Role: "admin", UserType: "super_admin"}
// 构造 alg=none 的未签名 token。
noneToken := gojwt.NewWithClaims(gojwt.SigningMethodNone, claims)
signed, err := noneToken.SignedString(gojwt.UnsafeAllowNoneSignatureType)
if err != nil {
t.Fatalf("构造 none token 失败: %v", err)
}
if _, err := jwt.ParseToken(signed); err == nil {
t.Error("ParseToken 必须拒绝 alg=none 的 token（算法混淆防护）")
}
}
// 回归 P0：空密钥时 GenerateToken/ParseToken 必须 fail-closed 返 ErrEmptySecret，
// 杜绝以零长度 HMAC 密钥签发/校验导致任意 token 通过。
func TestEmptySecretFailsClosed(t *testing.T) {
config.Set(&config.Config{JWT: config.JWTConfig{Secret: "", Expire: time.Hour}})
t.Cleanup(setupTestConfig) // 还原基线，避免污染其它测试
_, err := jwt.GenerateToken(1, "u", "admin", "admin")
if !errors.Is(err, jwt.ErrEmptySecret) {
t.Errorf("空密钥 GenerateToken err = %v, want ErrEmptySecret", err)
}
// 校验侧：任意 token 在空密钥下都不得通过。
if _, err := jwt.ParseToken("a.b.c"); err == nil {
t.Error("空密钥 ParseToken 不得通过任何 token")
}
}
// 回归 P0：配置不支持的算法（如 RS256）时 GenerateToken 必须返 ErrUnsupportedAlgorithm，
// 不再静默回退 HS256。
func TestUnsupportedAlgorithmFailsClosed(t *testing.T) {
config.Set(&config.Config{JWT: config.JWTConfig{
Secret: "test-secret-key-1234567890123456789012",
Algorithm: "RS256",
Expire: time.Hour,
}})
t.Cleanup(setupTestConfig)
_, err := jwt.GenerateToken(1, "u", "admin", "admin")
if !errors.Is(err, jwt.ErrUnsupportedAlgorithm) {
t.Errorf("RS256 GenerateToken err = %v, want ErrUnsupportedAlgorithm", err)
}
}
// 回归 P0：显式支持的 HS384 仍可正常签发与校验（确认算法固定未误伤合法 HMAC 族）。
func TestSupportedAlgorithmHS384(t *testing.T) {
config.Set(&config.Config{JWT: config.JWTConfig{
Secret: "test-secret-key-1234567890123456789012",
Algorithm: "HS384",
Expire: time.Hour,
}})
t.Cleanup(setupTestConfig)
setupMiniRedis(t)
token, err := jwt.GenerateToken(1, "u", "admin", "admin")
if err != nil {
t.Fatalf("HS384 GenerateToken: %v", err)
}
if _, err := jwt.ParseToken(token); err != nil {
t.Errorf("HS384 ParseToken: %v", err)
}
}
func TestParseTokenRejectsWrongIssuer(t *testing.T) {
config.Set(&config.Config{JWT: config.JWTConfig{
Secret: "test-secret-key-1234567890123456789012",
Expire: time.Hour,
Issuer: "trusted-issuer",
}})
t.Cleanup(setupTestConfig)
claims := jwt.Claims{
UserID: 1,
Username: "attacker",
Role: "admin",
UserType: "super_admin",
RegisteredClaims: gojwt.RegisteredClaims{
ExpiresAt: gojwt.NewNumericDate(time.Now().Add(time.Hour)),
IssuedAt: gojwt.NewNumericDate(time.Now()),
NotBefore: gojwt.NewNumericDate(time.Now()),
Issuer: "evil-issuer",
},
}
token := signTokenForTest(t, claims)
if _, err := jwt.ParseToken(token); !errors.Is(err, jwt.ErrTokenInvalid) {
t.Errorf("ParseToken wrong issuer err = %v, want ErrTokenInvalid", err)
}
if _, err := jwt.GetClaimsFromToken(token); !errors.Is(err, jwt.ErrTokenInvalid) {
t.Errorf("GetClaimsFromToken wrong issuer err = %v, want ErrTokenInvalid", err)
}
}
func TestRefreshTokenUsesRefreshExpire(t *testing.T) {
config.Set(&config.Config{JWT: config.JWTConfig{
Secret: "test-secret-key-1234567890123456789012",
Expire: time.Hour,
RefreshExpire: 4 * time.Hour,
}})
t.Cleanup(setupTestConfig)
setupMiniRedis(t)
token, err := jwt.GenerateToken(1, "testuser", "admin", "super_admin")
if err != nil {
t.Fatalf("GenerateToken: %v", err)
}
newToken, err := jwt.RefreshToken(token)
if err != nil {
t.Fatalf("RefreshToken: %v", err)
}
claims, err := jwt.ParseToken(newToken)
if err != nil {
t.Fatalf("ParseToken refreshed token: %v", err)
}
ttl := time.Until(claims.ExpiresAt.Time)
if ttl < 3*time.Hour || ttl > 4*time.Hour+time.Minute {
t.Errorf("refreshed token ttl = %v, want about 4h", ttl)
}
}
func TestGenerateTokenWithCustomExpiryRejectsNonPositive(t *testing.T) {
setupTestConfig()
for _, seconds := range []int{0, -1} {
if _, err := jwt.GenerateTokenWithCustomExpiry(1, "u", "admin", "admin", seconds); !errors.Is(err, jwt.ErrInvalidExpiry) {
t.Errorf("GenerateTokenWithCustomExpiry(%d) err = %v, want ErrInvalidExpiry", seconds, err)
}
}
}
func TestInvalidateTokenByIDRejectsEmptyJTI(t *testing.T) {
setupTestConfig()
if err := jwt.InvalidateTokenByID("", time.Now().Add(time.Hour)); !errors.Is(err, jwt.ErrEmptyJTI) {
t.Errorf("InvalidateTokenByID empty err = %v, want ErrEmptyJTI", err)
}
}
func TestRefreshTokenRejectsEmptyJTI(t *testing.T) {
setupTestConfig()
setupMiniRedis(t)
token := signTokenForTest(t, jwt.Claims{
UserID: 1,
Username: "legacy",
Role: "admin",
UserType: "admin",
RegisteredClaims: gojwt.RegisteredClaims{
ExpiresAt: gojwt.NewNumericDate(time.Now().Add(time.Hour)),
IssuedAt: gojwt.NewNumericDate(time.Now()),
NotBefore: gojwt.NewNumericDate(time.Now()),
Issuer: "xlgo",
},
})
if _, err := jwt.RefreshToken(token); !errors.Is(err, jwt.ErrEmptyJTI) {
t.Errorf("RefreshToken empty JTI err = %v, want ErrEmptyJTI", err)
}
}
func TestInvalidateTokenRejectsEmptyJTI(t *testing.T) {
setupTestConfig()
setupMiniRedis(t)
token := signTokenForTest(t, jwt.Claims{
UserID: 1,
Username: "legacy",
Role: "admin",
UserType: "admin",
RegisteredClaims: gojwt.RegisteredClaims{
ExpiresAt: gojwt.NewNumericDate(time.Now().Add(time.Hour)),
IssuedAt: gojwt.NewNumericDate(time.Now()),
NotBefore: gojwt.NewNumericDate(time.Now()),
Issuer: "xlgo",
},
})
if err := jwt.InvalidateToken(token); !errors.Is(err, jwt.ErrEmptyJTI) {
t.Errorf("InvalidateToken empty JTI err = %v, want ErrEmptyJTI", err)
}
}
func TestParseTokenEmptySecretReturnsSentinel(t *testing.T) {
setupTestConfig()
token, err := jwt.GenerateToken(1, "u", "admin", "admin")
if err != nil {
t.Fatalf("GenerateToken before empty secret: %v", err)
}
config.Set(&config.Config{JWT: config.JWTConfig{Secret: "", Expire: time.Hour}})
t.Cleanup(setupTestConfig)
if _, err := jwt.ParseToken(token); !errors.Is(err, jwt.ErrEmptySecret) {
t.Fatalf("ParseToken empty secret err = %v, want ErrEmptySecret", err)
}
}
func TestParseTokenBlacklistPolicy(t *testing.T) {
setupTestConfig()
jwt.SetDefaultJWTManager(jwt.NewJWTManager())
t.Cleanup(func() { jwt.SetDefaultJWTManager(jwt.NewJWTManager()) })
token, err := jwt.GenerateToken(1, "test", "admin", "admin")
if err != nil {
t.Fatalf("GenerateToken: %v", err)
}
if _, err := jwt.ParseToken(token); !errors.Is(err, jwt.ErrBlacklistUnavailable) {
t.Fatalf("ParseToken default fail-closed should reject without Redis, err = %v, want ErrBlacklistUnavailable", err)
}
if _, err := jwt.ParseTokenWithBlacklistPolicy(token, jwt.BlacklistFailOpen); err != nil {
t.Fatalf("ParseTokenWithBlacklistPolicy fail-open should pass without Redis: %v", err)
}
}
func TestInvalidateTokenAllowsFutureNotBeforeToken(t *testing.T) {
setupTestConfig()
mr := setupMiniRedis(t)
claims := jwt.Claims{
UserID: 1,
Username: "external",
Role: "admin",
UserType: "admin",
JTI: "future-jti",
RegisteredClaims: gojwt.RegisteredClaims{
ExpiresAt: gojwt.NewNumericDate(time.Now().Add(time.Hour)),
IssuedAt: gojwt.NewNumericDate(time.Now()),
NotBefore: gojwt.NewNumericDate(time.Now().Add(10 * time.Minute)),
Issuer: "xlgo",
ID: "future-jti",
},
}
token := signTokenForTest(t, claims)
if err := jwt.InvalidateToken(token); err != nil {
t.Fatalf("InvalidateToken future nbf: %v", err)
}
if !mr.Exists("jwt_bl:future-jti") {
t.Fatal("future nbf token JTI should be blacklisted")
}
}
func signTokenForTest(t *testing.T, claims jwt.Claims) string {
t.Helper()
token, err := gojwt.NewWithClaims(gojwt.SigningMethodHS256, claims).SignedString([]byte("test-secret-key-1234567890123456789012"))
if err != nil {
t.Fatalf("sign token: %v", err)
}
return token
}
logger/field.go
+30
View File
@@ -0,0 +1,30 @@
package logger
import (
"time"
"go.uber.org/zap"
)
// Field Zap 字段别名，用于简化日志字段定义
var Field = struct {
String func(key string, value string) zap.Field
Int func(key string, value int) zap.Field
Int64 func(key string, value int64) zap.Field
Bool func(key string, value bool) zap.Field
Uint func(key string, value uint) zap.Field
Float64 func(key string, value float64) zap.Field
Duration func(key string, value time.Duration) zap.Field
Error func(err error) zap.Field
}{
String: zap.String,
Int: zap.Int,
Int64: zap.Int64,
Bool: zap.Bool,
Uint: zap.Uint,
Float64: zap.Float64,
Duration: zap.Duration,
Error: func(err error) zap.Field {
return zap.Error(err)
},
}
logger/logger.go
+537
View File
@@ -0,0 +1,537 @@
package logger
import (
"errors"
"os"
"path/filepath"
"strings"
"sync"
"sync/atomic"
"github.com/EthanCodeCraft/xlgo-core/config"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
"gopkg.in/natefinch/lumberjack.v2"
)
var (
// 内部 atomic 存储——四个 logger 的真实源（H7 修复）。
// 所有包级函数（Info/Debug/.../APILog/DBLog/Sync）经 atomic Load 读取，
// 使请求 goroutine 不与 Init/Close 重新装配全局变量竞争。
// 原实现用 m.mu（实例锁）保护包级全局变量，锁与被保护对象作用域错配，
// 读侧无锁裸读 → 热重载 re-Init/Close 与请求日志存在数据竞争。
loggerPtr atomic.Pointer[zap.Logger]
sugarPtr atomic.Pointer[zap.SugaredLogger]
apiLogPtr atomic.Pointer[zap.Logger]
dbLogPtr atomic.Pointer[zap.Logger]
// defaultLoggerPtr 是包级 facade 使用的默认 manager 原子快照。
// 保留导出的 DefaultLogger *LogManager 作为兼容变量；SetDefaultLogManager
// 只替换这个内部指针，避免 facade 裸读/裸写导出变量。
defaultLoggerPtr atomic.Pointer[LogManager]
globalLogGeneration uint64
// globalMu 串行化包级 logger/writer 的发布与关闭。
// 不能仅依赖 LogManager.mu：多个 LogManager 实例并发 Init/Close 时，
// 实例锁无法保护 Logger/fileWriters 这类包级状态。
globalMu sync.Mutex
// Logger 全局通用日志实例（兼容别名）。Init 之前为 Nop，调用安全。
//
// Deprecated: 此导出变量由 Init/Close 在 globalMu 下同步维护，但直接读它在 re-Init/Close
// 期间非并发安全（L-E）。请改用包级函数 Info/Debug/Warn/Error/...（经 atomic 读取，
// 并发安全）。保留仅为向后兼容，未来大版本可能移除。
Logger = zap.NewNop()
// fileWriters 持有所有 lumberjack 实例引用，
// Close() 调用时显式释放文件句柄。
// 必要性：lumberjack 不依赖 GC 关闭文件，进程长跑或测试场景下
// 不显式关闭会持有句柄导致 Windows 上无法删除日志目录。
// 仅在 globalMu 下访问（Init/Close），无读侧竞争。
fileWriters []*lumberjack.Logger
)
func init() {
// 初始化 atomic 存储为 Nop，保证包级函数在任何时刻 Load 均非 nil。
nop := zap.NewNop()
loggerPtr.Store(nop)
sugarPtr.Store(nop.Sugar())
apiLogPtr.Store(nop)
dbLogPtr.Store(nop)
defaultLoggerPtr.Store(DefaultLogger)
}
// currentLogger 返回通用 logger 的 atomic 快照（永不 nil）。
func currentLogger() *zap.Logger {
if l := loggerPtr.Load(); l != nil {
return l
}
return zap.NewNop() // 防御：init 后不可达
}
// currentSugar 返回 sugared logger 的 atomic 快照（永不 nil）。
func currentSugar() *zap.SugaredLogger {
if s := sugarPtr.Load(); s != nil {
return s
}
return zap.NewNop().Sugar() // 防御：init 后不可达
}
// currentAPILog 返回 API logger 的 atomic 快照（永不 nil）。
func currentAPILog() *zap.Logger {
if l := apiLogPtr.Load(); l != nil {
return l
}
return zap.NewNop()
}
// currentDBLog 返回 DB logger 的 atomic 快照（永不 nil）。
func currentDBLog() *zap.Logger {
if l := dbLogPtr.Load(); l != nil {
return l
}
return zap.NewNop()
}
// LogManager 日志管理器（#10）。照 database.Manager 模式：
// 实例化 + DefaultLogger 全局默认 + 包级 facade 代理。
// 包级 Logger/sugar/apiLog/dbLog 由 Init 同步维护，下游 8 个包零改动。
type LogManager struct {
mu sync.Mutex
cfg *config.Config
// level 是所有 core 共享的 AtomicLevel，支持运行期 SetLevel 热切换（M19）。
// Init 前为 nil，SetLevel 守卫之。
level zap.AtomicLevel
generation uint64
}
// DefaultSnapshot 是默认 logger 全局状态的 opaque 快照。
// App 初始化用它实现“先安装新 logger，后续失败可恢复旧 logger”的事务边界。
type DefaultSnapshot struct {
manager *LogManager
logger *zap.Logger
sugar *zap.SugaredLogger
apiLog *zap.Logger
dbLog *zap.Logger
writers []*lumberjack.Logger
generation uint64
}
// DefaultLogger 默认日志管理器，包级 facade 代理到它。
//
// Deprecated: 直接替换该导出变量（logger.DefaultLogger = m）不会更新包级 facade
// 使用的 atomic 快照，也不是并发安全的替换方式。请用 SetDefaultLogManager(m)。
// 直接调用 DefaultLogger.Init/Close/SetLevel/GetLevel 仍保留兼容，并受 LogManager
// 自身锁保护。
var DefaultLogger = NewLogManager()
// NewLogManager 创建日志管理器实例。
func NewLogManager() *LogManager { return &LogManager{} }
// GetDefaultLogManager 返回全局默认 LogManager（atomic 读取，并发安全）。
func GetDefaultLogManager() *LogManager {
if m := defaultLoggerPtr.Load(); m != nil {
return m
}
if DefaultLogger != nil && defaultLoggerPtr.CompareAndSwap(nil, DefaultLogger) {
return DefaultLogger
}
m := NewLogManager()
if defaultLoggerPtr.CompareAndSwap(nil, m) {
return m
}
return defaultLoggerPtr.Load()
}
// SetLevel 运行期热切换日志级别（M19）。需先 Init；未 Init 时返回 false。
// 影响所有 core（app/api/db/console）——它们共享同一 AtomicLevel。
func (m *LogManager) SetLevel(l zapcore.Level) bool {
m.mu.Lock()
defer m.mu.Unlock()
if m.level == (zap.AtomicLevel{}) {
return false
}
m.level.SetLevel(l)
return true
}
// GetLevel 返回当前日志级别（未 Init 返回 InfoLevel）。
func (m *LogManager) GetLevel() zapcore.Level {
m.mu.Lock()
defer m.mu.Unlock()
if m.level == (zap.AtomicLevel{}) {
return zapcore.InfoLevel
}
return m.level.Level()
}
// SetLevel 包级 facade：运行期热切换默认日志级别（M19）。未 Init 时无操作返回 false。
func SetLevel(l zapcore.Level) bool { return GetDefaultLogManager().SetLevel(l) }
// GetLevel 包级 facade：返回默认日志当前级别。
func GetLevel() zapcore.Level { return GetDefaultLogManager().GetLevel() }
// SetDefaultLogManager 提升指定 LogManager 为全局默认（atomic.Store，并发安全）。
func SetDefaultLogManager(m *LogManager) {
if m != nil {
defaultLoggerPtr.Store(m)
}
}
// SnapshotDefault 返回默认 logger 全局状态快照。
// 快照仅用于 App 初始化回滚；调用方成功提交后必须 CloseDefaultSnapshot 释放旧 writers。
func SnapshotDefault() *DefaultSnapshot {
globalMu.Lock()
defer globalMu.Unlock()
return &DefaultSnapshot{
manager: GetDefaultLogManager(),
logger: currentLogger(),
sugar: currentSugar(),
apiLog: currentAPILog(),
dbLog: currentDBLog(),
writers: append([]*lumberjack.Logger(nil), fileWriters...),
generation: globalLogGeneration,
}
}
// RestoreDefaultSnapshot 恢复 SnapshotDefault 捕获的默认 logger 状态，并关闭当前新 writers。
func RestoreDefaultSnapshot(s *DefaultSnapshot) error {
if s == nil {
return nil
}
globalMu.Lock()
newLogger := currentLogger()
newAPILog := currentAPILog()
newDBLog := currentDBLog()
newWriters := fileWriters
loggerPtr.Store(s.logger)
sugarPtr.Store(s.sugar)
apiLogPtr.Store(s.apiLog)
dbLogPtr.Store(s.dbLog)
Logger = s.logger
fileWriters = append([]*lumberjack.Logger(nil), s.writers...)
globalLogGeneration = s.generation
globalMu.Unlock()
if s.manager != nil {
SetDefaultLogManager(s.manager)
}
return errors.Join(syncLoggers(newLogger, newAPILog, newDBLog), closeFileWriters(newWriters))
}
// CloseDefaultSnapshot 关闭 SnapshotDefault 捕获的旧 writers；用于新 logger 已提交成功后释放旧资源。
func CloseDefaultSnapshot(s *DefaultSnapshot) error {
if s == nil {
return nil
}
return errors.Join(syncLoggers(s.logger, s.apiLog, s.dbLog), closeFileWriters(s.writers))
}
// Init 初始化日志。
//
// 三个 logger 的分流策略：
// - Logger（通用）：写 console + logs/app.log
// - APILog() ：写 console + logs/api.log
// - DBLog() ：写 console + logs/database.log
//
// 关键修复（v1.0.3）：旧实现把 apiCore 和 dbCore 都 Tee 进通用 Logger，
// 导致每条 logger.Info(...) 都会同时落到 api.log + database.log + console
// 三份，磁盘占用翻倍且分流形同虚设。新实现通用 Logger 只走独立的 app.log。
func (m *LogManager) Init(cfg *config.Config) error {
return m.init(cfg, true)
}
// InitPreservingPrevious 初始化并发布 logger，但暂不关闭被替换的旧 writers。
// App.Init 使用该方法配合 SnapshotDefault，在后续 hook 失败时可恢复旧 logger。
func (m *LogManager) InitPreservingPrevious(cfg *config.Config) error {
return m.init(cfg, false)
}
func (m *LogManager) init(cfg *config.Config, closePrevious bool) error {
if cfg == nil {
return errors.New("logger: 配置为空")
}
if err := validateLogConfig(cfg.Log); err != nil {
return err
}
m.mu.Lock()
defer m.mu.Unlock()
// 确保日志目录存在（0750：owner+group 可访问，与 storage 目录权限一致）
if err := os.MkdirAll(cfg.Log.Dir, 0o750); err != nil {
return err
}
// 日志编码器配置
encoderConfig := zapcore.EncoderConfig{
TimeKey: "time",
LevelKey: "level",
NameKey: "logger",
CallerKey: "caller",
FunctionKey: zapcore.OmitKey,
MessageKey: "msg",
StacktraceKey: "stacktrace",
LineEnding: zapcore.DefaultLineEnding,
EncodeLevel: zapcore.LowercaseLevelEncoder,
EncodeTime: zapcore.ISO8601TimeEncoder,
EncodeDuration: zapcore.SecondsDurationEncoder,
EncodeCaller: zapcore.ShortCallerEncoder,
}
// 根据运行模式设置日志级别（M19：用 AtomicLevel 支持运行期 SetLevel 热切换）
level := zap.NewAtomicLevelAt(zapcore.DebugLevel)
if cfg.IsProduction() {
level = zap.NewAtomicLevelAt(zapcore.InfoLevel)
}
jsonEncoder := zapcore.NewJSONEncoder(encoderConfig)
consoleEncoder := zapcore.NewConsoleEncoder(encoderConfig)
consoleCore := zapcore.NewCore(consoleEncoder, zapcore.AddSync(os.Stdout), level)
// 通用日志独立文件，避免与 api/db 日志重复写入
appWriter := newRotatingWriter(cfg.Log, "app.log")
apiWriter := newRotatingWriter(cfg.Log, "api.log")
dbWriter := newRotatingWriter(cfg.Log, "database.log")
appCore := zapcore.NewCore(jsonEncoder, zapcore.AddSync(appWriter), level)
apiCore := zapcore.NewCore(jsonEncoder, zapcore.AddSync(apiWriter), level)
dbCore := zapcore.NewCore(jsonEncoder, zapcore.AddSync(dbWriter), level)
// 三个 logger 各写自己的文件 + console，互不 Tee
newLogger := zap.New(
zapcore.NewTee(appCore, consoleCore),
zap.AddCaller(), zap.AddCallerSkip(1),
)
newAPILog := zap.New(
zapcore.NewTee(apiCore, consoleCore),
zap.AddCaller(), zap.AddCallerSkip(1),
)
newDBLog := zap.New(
zapcore.NewTee(dbCore, consoleCore),
zap.AddCaller(), zap.AddCallerSkip(1),
)
// 全部构造成功后再原子替换全局变量，避免半初始化状态。
// 先发布新 logger，再关闭旧 writer，避免请求 goroutine 在替换窗口内
// 通过包级函数拿到仍指向已关闭 writer 的旧 logger。
// H7：四个 logger 经 atomic.Pointer Store，读侧（请求 goroutine）无锁原子 load；
// fileWriters 仅在 globalMu 下访问。Logger 兼容别名同步维护。
globalMu.Lock()
oldWriters := fileWriters
globalLogGeneration++
m.generation = globalLogGeneration
loggerPtr.Store(newLogger)
sugarPtr.Store(newLogger.Sugar())
apiLogPtr.Store(newAPILog)
dbLogPtr.Store(newDBLog)
Logger = newLogger
fileWriters = []*lumberjack.Logger{appWriter, apiWriter, dbWriter}
globalMu.Unlock()
m.level = level
m.cfg = cfg
if closePrevious {
return closeFileWriters(oldWriters)
}
return nil
}
// Init 包级 facade：初始化日志（代理到 DefaultLogger）。
func Init(cfg *config.Config) error {
return GetDefaultLogManager().Init(cfg)
}
func validateLogConfig(cfg config.LogConfig) error {
if strings.TrimSpace(cfg.Dir) == "" {
return errors.New("logger: 日志目录为空")
}
if cfg.MaxSize < 0 {
return errors.New("logger: MaxSize 不能为负数")
}
if cfg.MaxBackups < 0 {
return errors.New("logger: MaxBackups 不能为负数")
}
if cfg.MaxAge < 0 {
return errors.New("logger: MaxAge 不能为负数")
}
return nil
}
// newRotatingWriter 创建带 lumberjack 滚动归档的 writer
func newRotatingWriter(cfg config.LogConfig, filename string) *lumberjack.Logger {
return &lumberjack.Logger{
Filename: filepath.Join(cfg.Dir, filename),
MaxSize: cfg.MaxSize,
MaxBackups: cfg.MaxBackups,
MaxAge: cfg.MaxAge,
Compress: cfg.Compress,
}
}
// closeFileWriters 关闭传入的 lumberjack writer，并聚合关闭错误。
func closeFileWriters(writers []*lumberjack.Logger) error {
var errs []error
for _, w := range writers {
if w != nil {
if err := w.Close(); err != nil {
errs = append(errs, err)
}
}
}
return errors.Join(errs...)
}
func syncLoggers(loggers ...*zap.Logger) error {
var errs []error
for _, l := range loggers {
if l == nil {
continue
}
if err := l.Sync(); err != nil && !isHarmlessSyncError(err) {
errs = append(errs, err)
}
}
return errors.Join(errs...)
}
// Sync 同步全部 logger 缓冲到底层 writer。
//
// 注意：在 Windows / 部分 *nix 平台上对 stdout/stderr 调用 Sync 会返回
// "invalid argument" / "inappropriate ioctl for device"，属于 zap 已知行为，
// 这里把这类错误识别并忽略，只返回真实的写入失败。
func (m *LogManager) Sync() error {
return syncLoggers(currentLogger(), currentAPILog(), currentDBLog())
}
// Sync 包级 facade：同步全部 logger 缓冲（代理到 DefaultLogger）。
func Sync() error {
return GetDefaultLogManager().Sync()
}
// Close 关闭日志文件句柄，重置全局 logger 为 Nop。
// 通常由 App.Shutdown 在 Sync 之后调用；测试场景需要清理临时目录时也应调用。
//
// 调用后再次写日志不会 panic（fall back to nop logger），但不会写入文件。
// 如需重新启用，请再次调用 Init。
func (m *LogManager) Close() error {
m.mu.Lock()
globalMu.Lock()
if m.generation == 0 || m.generation != globalLogGeneration {
m.level = zap.AtomicLevel{}
m.cfg = nil
m.generation = 0
globalMu.Unlock()
m.mu.Unlock()
return nil
}
oldLogger := currentLogger()
oldAPILog := currentAPILog()
oldDBLog := currentDBLog()
oldWriters := fileWriters
// H7：重置为 Nop 经 atomic Store，与读侧一致；Logger 兼容别名同步。
nop := zap.NewNop()
loggerPtr.Store(nop)
sugarPtr.Store(nop.Sugar())
apiLogPtr.Store(nop)
dbLogPtr.Store(nop)
Logger = nop
fileWriters = nil
globalMu.Unlock()
m.level = zap.AtomicLevel{}
m.cfg = nil
m.generation = 0
m.mu.Unlock()
return errors.Join(
syncLoggers(oldLogger, oldAPILog, oldDBLog),
closeFileWriters(oldWriters),
)
}
// Close 包级 facade：关闭日志文件句柄，重置为 Nop（代理到 DefaultLogger）。
func Close() error {
return GetDefaultLogManager().Close()
}
// isHarmlessSyncError 识别 stdout/stderr Sync 在不同平台返回的预期错误。
// 这些错误来自 console core，对真实 writer 无影响，可安全忽略。
func isHarmlessSyncError(err error) bool {
if err == nil {
return true
}
msg := err.Error()
for _, sub := range []string{
"invalid argument", // Linux stdout
"inappropriate ioctl for device", // macOS stdout
"bad file descriptor", // Windows stdout
} {
if strings.Contains(msg, sub) {
return true
}
}
return false
}
// Debug 调试日志
func Debug(msg string, fields ...zap.Field) {
currentLogger().Debug(msg, fields...)
}
// Info 信息日志
func Info(msg string, fields ...zap.Field) {
currentLogger().Info(msg, fields...)
}
// Warn 警告日志
func Warn(msg string, fields ...zap.Field) {
currentLogger().Warn(msg, fields...)
}
// Error 错误日志
func Error(msg string, fields ...zap.Field) {
currentLogger().Error(msg, fields...)
}
// Fatal 致命错误日志（仅供应用层使用，框架内部禁止调用）
func Fatal(msg string, fields ...zap.Field) {
currentLogger().Fatal(msg, fields...)
}
// Debugf 格式化调试日志
func Debugf(template string, args ...any) {
currentSugar().Debugf(template, args...)
}
// Infof 格式化信息日志
func Infof(template string, args ...any) {
currentSugar().Infof(template, args...)
}
// Warnf 格式化警告日志
func Warnf(template string, args ...any) {
currentSugar().Warnf(template, args...)
}
// Errorf 格式化错误日志
func Errorf(template string, args ...any) {
currentSugar().Errorf(template, args...)
}
// Fatalf 格式化致命错误日志（仅供应用层使用，框架内部禁止调用）
func Fatalf(template string, args ...any) {
currentSugar().Fatalf(template, args...)
}
// APILog 返回 API 专用日志器（写 logs/api.log + console）
func APILog() *zap.Logger {
return currentAPILog()
}
// DBLog 返回数据库专用日志器（写 logs/database.log + console）
func DBLog() *zap.Logger {
return currentDBLog()
}
logger/logger_h7_internal_test.go
+482
View File
@@ -0,0 +1,482 @@
package logger
import (
"os"
"path/filepath"
"strings"
"sync"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
)
// tmpCfg 构造一个指向临时目录的日志配置，用于 Init。
func tmpCfg(dir string) *config.Config {
return &config.Config{
Server: config.ServerConfig{Mode: "production"},
Log: config.LogConfig{
Dir: dir,
MaxSize: 1,
MaxBackups: 1,
MaxAge: 1,
Compress: false,
},
}
}
// TestH7ConcurrentInitCloseAndRead 验证请求 goroutine 的包级日志读路径
// 与 Init/Close 重新装配全局 logger 无数据竞争（-race）。
//
// H7 根因：原实现 Info/Error/APILog/DBLog/Sync 裸读包级 Logger/sugar/apiLog/dbLog，
// 而 Init/Close 在 m.mu 下写这些变量——实例锁保护全局变量、读侧无锁 → re-Init/Close
// 与请求日志竞争。修复后读路径经 atomic.Pointer Load。
//
// 红/绿验证：将 currentLogger/currentSugar/currentAPILog/currentDBLog 临时改为
// 裸读 Logger/sugar/apiLog/dbLog（或等价地恢复包级裸读），-race 必复现 DATA RACE；
// 恢复 atomic 后绿。
func TestH7ConcurrentInitCloseAndRead(t *testing.T) {
dir := t.TempDir()
cfg := tmpCfg(dir)
// 确保默认 LogManager 起点干净。
_ = GetDefaultLogManager().Close()
t.Cleanup(func() { _ = GetDefaultLogManager().Close() })
stop := make(chan struct{})
var wg sync.WaitGroup
// 写者：循环 Init/Close（重新装配全局 logger）。
wg.Add(1)
go func() {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
_ = GetDefaultLogManager().Init(cfg)
_ = GetDefaultLogManager().Close()
}
}()
// 读者：并发调用读路径（包级函数 + atomic 快照读取）。
// 仅读取 logger 指针——这正是被竞态的访问；不调用 .Info/.Errorf 等写方法，
// 避免对已被 re-Init 关闭的旧 writer 触发 lumberjack 重新打开同一文件，
// 导致测试 TempDir 清理时句柄仍占用（框架不支持 re-Init 与在途写入并发，
// 该约束非 H7 范围）。
for i := 0; i < 4; i++ {
wg.Add(1)
go func() {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
// 这些调用内部经 atomic Load 读取包级 logger 指针。
_ = currentLogger()
_ = currentSugar()
_ = currentAPILog()
_ = currentDBLog()
_ = APILog()
_ = DBLog()
}
}()
}
// 运行窗口足以让 race detector 采到任何竞争。
time.Sleep(120 * time.Millisecond)
close(stop)
wg.Wait()
// 收尾到 Nop，避免后续测试持有临时目录句柄。
_ = GetDefaultLogManager().Close()
}
// TestH7CurrentLoggerReflectsInitAndClose 验证 atomic 快照随 Init/Close 正确切换：
// Init 后 currentLogger 写入文件；Close 后回到 Nop（不写文件）。
func TestH7CurrentLoggerReflectsInitAndClose(t *testing.T) {
dir := t.TempDir()
cfg := tmpCfg(dir)
_ = GetDefaultLogManager().Close()
t.Cleanup(func() { _ = GetDefaultLogManager().Close() })
// Init 前：Nop，调用安全且不写文件。
before := currentLogger()
if before == nil {
t.Fatal("currentLogger nil before Init")
}
if err := GetDefaultLogManager().Init(cfg); err != nil {
t.Fatalf("Init: %v", err)
}
// Init 后：currentLogger 与 Logger 兼容别名一致，且为非 Nop 实例。
after := currentLogger()
if after == nil {
t.Fatal("currentLogger nil after Init")
}
if after != Logger {
t.Error("after Init, currentLogger() != Logger (compat alias out of sync)")
}
// 写一条日志并 flush，验证落到文件（说明拿到的是真实 logger，非 Nop）。
const mark = "H7_INIT_REFLECT_xyz"
after.Info(mark)
_ = GetDefaultLogManager().Sync()
data, err := readFile(t, filepath.Join(dir, "app.log"))
if err != nil {
t.Fatalf("read app.log: %v", err)
}
if !strings.Contains(data, mark) {
t.Errorf("app.log missing mark %q after Init (got Nop?)", mark)
}
// Close 后：currentLogger 回到 Nop（与 Init 前实例不同，但同为 Nop 行为）。
if err := GetDefaultLogManager().Close(); err != nil {
t.Fatalf("Close: %v", err)
}
closed := currentLogger()
if closed == nil {
t.Fatal("currentLogger nil after Close")
}
// Nop logger 写不报错也不落盘；验证 Close 后再写不新增 mark。
closed.Info("H7_SHOULD_NOT_APPEAR_xyz")
_ = GetDefaultLogManager().Sync()
data2, _ := readFile(t, filepath.Join(dir, "app.log"))
if strings.Contains(data2, "H7_SHOULD_NOT_APPEAR_xyz") {
t.Error("wrote to file after Close (expected Nop)")
}
}
// TestH7AtomicPointersNonNil 验证 init 后四个 atomic 快照永不 nil，
// 且 APILog/DBLog 返回与内部 atomic 一致的实例。
func TestH7AtomicPointersNonNil(t *testing.T) {
if loggerPtr.Load() == nil {
t.Error("loggerPtr nil after init")
}
if sugarPtr.Load() == nil {
t.Error("sugarPtr nil after init")
}
if apiLogPtr.Load() == nil {
t.Error("apiLogPtr nil after init")
}
if dbLogPtr.Load() == nil {
t.Error("dbLogPtr nil after init")
}
if APILog() != apiLogPtr.Load() {
t.Error("APILog() != apiLogPtr")
}
if DBLog() != dbLogPtr.Load() {
t.Error("DBLog() != dbLogPtr")
}
if currentLogger() != loggerPtr.Load() {
t.Error("currentLogger() != loggerPtr")
}
}
// TestH7DefaultLoggerCompatibility 锁定 M3 的兼容边界：
// DefaultLogger 仍保持 *LogManager 类型，旧代码可继续直接调用其方法；
// 包级 facade 的默认 manager 替换则必须走 SetDefaultLogManager 的 atomic 快照。
func TestH7DefaultLoggerCompatibility(t *testing.T) {
var _ *LogManager = DefaultLogger
old := GetDefaultLogManager()
t.Cleanup(func() { SetDefaultLogManager(old) })
next := NewLogManager()
SetDefaultLogManager(next)
if got := GetDefaultLogManager(); got != next {
t.Fatalf("GetDefaultLogManager() = %p, want %p", got, next)
}
}
// TestM3StaleManagerCloseDoesNotCloseCurrentLogger 回归：旧 manager 的 Close
// 不得关闭另一个 manager 后续发布的全局 logger/writer。
func TestM3StaleManagerCloseDoesNotCloseCurrentLogger(t *testing.T) {
dir1 := t.TempDir()
dir2 := t.TempDir()
m1 := NewLogManager()
m2 := NewLogManager()
t.Cleanup(func() {
_ = m1.Close()
_ = m2.Close()
SetDefaultLogManager(NewLogManager())
})
if err := m1.Init(tmpCfg(dir1)); err != nil {
t.Fatalf("m1.Init: %v", err)
}
if err := m2.Init(tmpCfg(dir2)); err != nil {
t.Fatalf("m2.Init: %v", err)
}
if err := m1.Close(); err != nil {
t.Fatalf("stale m1.Close: %v", err)
}
const mark = "M3_CURRENT_LOGGER_SURVIVES_STALE_CLOSE"
currentLogger().Info(mark)
_ = syncLoggers(currentLogger())
data, err := readFile(t, filepath.Join(dir2, "app.log"))
if err != nil {
t.Fatalf("read current app.log: %v", err)
}
if !strings.Contains(data, mark) {
t.Fatal("stale manager Close closed the current logger")
}
}
// TestH7DurationFieldFix 验证 H7b：Field.Duration 签名改为
// func(key string, value time.Duration) zap.Field，且 key 不再被丢弃。
//
// 旧实现 func(key string, value interface{}) 在 case zap.Field 分支 return v
// 丢弃 key，签名与实现矛盾。修复后直接委托 zap.Duration(key, value)。
func TestH7DurationFieldFix(t *testing.T) {
f := Field.Duration("elapsed", 5*time.Second)
if f.Key != "elapsed" {
t.Errorf("Duration key lost: got %q, want %q (H7b regression)", f.Key, "elapsed")
}
// zap.Duration 用 zapcore.DurationType 编码，Integer 字段承载纳秒。
if f.Integer != int64(5*time.Second) {
t.Errorf("Duration value mismatch: got %d, want %d", f.Integer, int64(5*time.Second))
}
// 零值与其他字段不受影响。
f2 := Field.Duration("d0", 0)
if f2.Key != "d0" {
t.Errorf("Duration zero key lost: %q", f2.Key)
}
}
// TestH7DurationFieldSignature 编译期锁定 Field.Duration 的签名为
// func(string, time.Duration) zap.Field（H7b 修复的核心：类型安全签名）。
//
// 旧签名为 func(string, interface{}) zap.Field，其 case zap.Field 分支 return v
// 丢弃传入的 key。若回退旧签名，下方赋值将因参数类型不匹配（interface{} ≠ time.Duration）
// 编译失败——即"修复前红、修复后绿"由编译器强制保证。
func TestH7DurationFieldSignature(t *testing.T) {
var _ func(string, time.Duration) zap.Field = Field.Duration
}
// readFile 读取文件内容，文件不存在时返回空串（不报错）。
func readFile(t *testing.T, path string) (string, error) {
t.Helper()
b, err := os.ReadFile(path)
if err != nil {
if os.IsNotExist(err) {
return "", nil
}
return "", err
}
return string(b), nil
}
// TestSetLevelHotSwap_M19：Init 后可运行期热切换日志级别（M19）。
func TestSetLevelHotSwap_M19(t *testing.T) {
dir := t.TempDir()
cfg := tmpCfg(dir)
_ = GetDefaultLogManager().Close()
t.Cleanup(func() { _ = GetDefaultLogManager().Close() })
if err := GetDefaultLogManager().Init(cfg); err != nil {
t.Fatalf("Init: %v", err)
}
// Init 后（tmpCfg 为 production 模式，默认 InfoLevel）可热切换到 ErrorLevel。
before := GetDefaultLogManager().GetLevel()
if before != zapcore.InfoLevel {
t.Errorf("default level = %v, want InfoLevel (production)", before)
}
if ok := GetDefaultLogManager().SetLevel(zapcore.ErrorLevel); !ok {
t.Fatal("SetLevel after Init should return true")
}
if got := GetDefaultLogManager().GetLevel(); got != zapcore.ErrorLevel {
t.Errorf("after SetLevel, level = %v, want ErrorLevel", got)
}
// 包级 facade 同步。
SetLevel(zapcore.WarnLevel)
if got := GetLevel(); got != zapcore.WarnLevel {
t.Errorf("package GetLevel = %v, want WarnLevel", got)
}
}
// TestM3ConcurrentInitSetLevelAndClose 验证 Init/SetLevel/GetLevel/Close
// 共享同一个 manager 临界区，不再出现 m.level 锁外写与锁内读写竞争（-race）。
func TestM3ConcurrentInitSetLevelAndClose(t *testing.T) {
dir := t.TempDir()
cfg := tmpCfg(dir)
m := NewLogManager()
SetDefaultLogManager(m)
t.Cleanup(func() {
_ = m.Close()
SetDefaultLogManager(NewLogManager())
})
stop := make(chan struct{})
var wg sync.WaitGroup
wg.Add(1)
go func() {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
_ = m.Init(cfg)
_ = m.Close()
}
}()
for i := 0; i < 4; i++ {
wg.Add(1)
go func(i int) {
defer wg.Done()
levels := []zapcore.Level{
zapcore.DebugLevel,
zapcore.InfoLevel,
zapcore.WarnLevel,
zapcore.ErrorLevel,
}
for {
select {
case <-stop:
return
default:
}
_ = m.SetLevel(levels[i%len(levels)])
_ = m.GetLevel()
}
}(i)
}
time.Sleep(120 * time.Millisecond)
close(stop)
wg.Wait()
}
// TestM3ConcurrentSetDefaultAndFacades 验证默认 LogManager 经 atomic.Pointer
// 读写，SetDefaultLogManager 与包级 facade 并发时无裸全局指针竞态（-race）。
func TestM3ConcurrentSetDefaultAndFacades(t *testing.T) {
t.Cleanup(func() {
_ = Close()
SetDefaultLogManager(NewLogManager())
})
stop := make(chan struct{})
var wg sync.WaitGroup
wg.Add(1)
go func() {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
SetDefaultLogManager(NewLogManager())
}
}()
for i := 0; i < 4; i++ {
wg.Add(1)
go func() {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
_ = GetLevel()
_ = SetLevel(zapcore.WarnLevel)
_ = Sync()
_ = APILog()
_ = DBLog()
}
}()
}
time.Sleep(120 * time.Millisecond)
close(stop)
wg.Wait()
}
// TestM3ConcurrentManagersInitClose 验证不同 LogManager 实例并发 Init/Close 时，
// 包级 Logger/fileWriters 的发布与关闭由 globalMu 串行化，不再依赖实例锁保护包级状态。
func TestM3ConcurrentManagersInitClose(t *testing.T) {
dir := t.TempDir()
cfg := tmpCfg(dir)
stop := make(chan struct{})
var wg sync.WaitGroup
managers := make([]*LogManager, 3)
for i := 0; i < 3; i++ {
managers[i] = NewLogManager()
wg.Add(1)
go func(m *LogManager) {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
SetDefaultLogManager(m)
_ = m.Init(cfg)
_ = m.Close()
}
}(managers[i])
}
wg.Add(1)
go func() {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
_ = currentLogger()
_ = currentSugar()
_ = APILog()
_ = DBLog()
}
}()
time.Sleep(120 * time.Millisecond)
close(stop)
wg.Wait()
for _, m := range managers {
_ = m.Close()
}
_ = Close()
SetDefaultLogManager(NewLogManager())
}
// TestM3InitRejectsInvalidLogConfig 验证 logger.Init 对明显非法日志配置失败，
// 避免空目录意外把 app.log 写到进程工作目录。
func TestM3InitRejectsInvalidLogConfig(t *testing.T) {
if err := NewLogManager().Init(&config.Config{}); err == nil {
t.Fatal("Init with empty log dir should fail")
}
cfg := tmpCfg(t.TempDir())
cfg.Log.MaxAge = -1
if err := NewLogManager().Init(cfg); err == nil {
t.Fatal("Init with negative MaxAge should fail")
}
}
logger/logger_test.go
+181
View File
@@ -0,0 +1,181 @@
package logger_test
import (
"os"
"path/filepath"
"strings"
"testing"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/logger"
)
// 注意：logger 需要先初始化才能调用 Info/Debug/Warn/Error
// 这里只测试 Field 函数，不测试日志输出
func TestAPILog(t *testing.T) {
_ = logger.APILog()
// 未初始化时为 nop logger，调用安全
}
func TestDBLog(t *testing.T) {
_ = logger.DBLog()
// 未初始化时为 nop logger，调用安全
}
func TestFieldString(t *testing.T) {
field := logger.Field.String("key", "value")
if field.Key != "key" {
t.Error("Field.String key failed")
}
}
func TestFieldInt(t *testing.T) {
field := logger.Field.Int("count", 123)
if field.Key != "count" {
t.Error("Field.Int key failed")
}
}
func TestFieldInt64(t *testing.T) {
field := logger.Field.Int64("id", 1234567890)
if field.Key != "id" {
t.Error("Field.Int64 key failed")
}
}
func TestFieldBool(t *testing.T) {
field := logger.Field.Bool("enabled", true)
if field.Key != "enabled" {
t.Error("Field.Bool key failed")
}
}
func TestFieldUint(t *testing.T) {
field := logger.Field.Uint("uint_val", 100)
if field.Key != "uint_val" {
t.Error("Field.Uint key failed")
}
}
func TestFieldFloat64(t *testing.T) {
field := logger.Field.Float64("price", 99.99)
if field.Key != "price" {
t.Error("Field.Float64 key failed")
}
}
func TestFieldError(t *testing.T) {
_ = logger.Field.Error(nil)
// zap.Field 是结构体，仅验证函数调用正常
}
// initWithTempDir 使用临时目录初始化 logger，返回日志目录与读取文件内容的辅助函数。
// 验证修复 #3 之后，三个 logger 各自只写自己的文件，互不串扰。
//
// 测试退出时通过 t.Cleanup 调用 logger.Close 释放文件句柄，
// 避免 Windows 上 t.TempDir 因句柄占用而清理失败。
func initWithTempDir(t *testing.T) (dir string, read func(name string) string) {
t.Helper()
dir = t.TempDir()
cfg := &config.Config{
Server: config.ServerConfig{Mode: "production"}, // 走 InfoLevel，避免 Debug 噪音
Log: config.LogConfig{
Dir: dir,
MaxSize: 10,
MaxBackups: 1,
MaxAge: 1,
Compress: false,
},
}
if err := logger.Init(cfg); err != nil {
t.Fatalf("logger.Init failed: %v", err)
}
t.Cleanup(func() { _ = logger.Close() })
read = func(name string) string {
path := filepath.Join(dir, name)
data, err := os.ReadFile(path)
if err != nil {
if os.IsNotExist(err) {
return ""
}
t.Fatalf("read %s: %v", path, err)
}
return string(data)
}
return dir, read
}
// TestLoggerNoCrossWriting 验证 Logger / APILog / DBLog 不会重复写入彼此的日志文件。
//
// 这是 v1.0.3 修复的核心：旧实现 Logger = Tee(apiCore, dbCore, consoleCore)，
// 导致 logger.Info(...) 同时写到 api.log + database.log + console 三份。
func TestLoggerNoCrossWriting(t *testing.T) {
_, read := initWithTempDir(t)
// 三个标记字符串足够独特，分别由三个 logger 写入
const (
appMark = "MARKER_APP_LOG_ONLY_xyz"
apiMark = "MARKER_API_LOG_ONLY_xyz"
dbMark = "MARKER_DB_LOG_ONLY_xyz"
)
logger.Info(appMark)
logger.APILog().Info(apiMark)
logger.DBLog().Info(dbMark)
if err := logger.Sync(); err != nil {
t.Fatalf("Sync: %v", err)
}
app := read("app.log")
api := read("api.log")
db := read("database.log")
// 各自的日志文件必须包含自己的标记
if !strings.Contains(app, appMark) {
t.Errorf("app.log missing %q, got: %s", appMark, app)
}
if !strings.Contains(api, apiMark) {
t.Errorf("api.log missing %q, got: %s", apiMark, api)
}
if !strings.Contains(db, dbMark) {
t.Errorf("database.log missing %q, got: %s", dbMark, db)
}
// 关键：禁止串写
if strings.Contains(api, appMark) {
t.Errorf("api.log should NOT contain %q (cross-writing bug regressed)", appMark)
}
if strings.Contains(db, appMark) {
t.Errorf("database.log should NOT contain %q (cross-writing bug regressed)", appMark)
}
if strings.Contains(app, apiMark) {
t.Errorf("app.log should NOT contain %q", apiMark)
}
if strings.Contains(db, apiMark) {
t.Errorf("database.log should NOT contain %q", apiMark)
}
if strings.Contains(app, dbMark) {
t.Errorf("app.log should NOT contain %q", dbMark)
}
if strings.Contains(api, dbMark) {
t.Errorf("api.log should NOT contain %q", dbMark)
}
}
// TestLoggerInitNilConfig 验证 Init 对 nil 配置返回错误，不再 panic。
func TestLoggerInitNilConfig(t *testing.T) {
if err := logger.Init(nil); err == nil {
t.Error("Init(nil) should return error, got nil")
}
}
// TestLoggerSyncBeforeInit 验证未初始化时 Sync 不 panic（globals 仍为 Nop）。
func TestLoggerSyncBeforeInit(t *testing.T) {
// Nop logger 的 Sync 永远返回 nil
if err := logger.Sync(); err != nil {
t.Errorf("Sync on nop logger should be nil, got %v", err)
}
}
logs/app.log
+3
View File
@@ -0,0 +1,3 @@
{"level":"warn","time":"2026-07-02T23:25:17.643+0800","caller":"database/manager.go:427","msg":"数据库连接失败，第 1/5 次重试: dial tcp [::1]:3306: connectex: No connection could be made because the target machine actively refused it."}
{"level":"warn","time":"2026-07-02T23:25:18.648+0800","caller":"database/manager.go:427","msg":"数据库连接失败，第 2/5 次重试: dial tcp [::1]:3306: connectex: No connection could be made because the target machine actively refused it."}
{"level":"warn","time":"2026-07-02T23:25:20.651+0800","caller":"database/manager.go:427","msg":"数据库连接失败，第 3/5 次重试: dial tcp [::1]:3306: connectex: No connection could be made because the target machine actively refused it."}
middleware/auth.go
+258
View File
@@ -0,0 +1,258 @@
package middleware
import (
"strings"
"github.com/EthanCodeCraft/xlgo-core/jwt"
"github.com/EthanCodeCraft/xlgo-core/response"
"github.com/gin-gonic/gin"
)
const (
// ContextKeyUserID 用户ID上下文键
ContextKeyUserID = "user_id"
// ContextKeyUsername 用户名上下文键
ContextKeyUsername = "username"
// ContextKeyRole 角色上下文键
ContextKeyRole = "role"
// ContextKeyUserType 用户类型上下文键
ContextKeyUserType = "user_type"
// DefaultUserTypeSuperAdmin 默认超级管理员用户类型
DefaultUserTypeSuperAdmin = "super_admin"
// DefaultUserTypeAdmin 默认管理员用户类型
DefaultUserTypeAdmin = "admin"
// DefaultUserTypeStaff 默认员工用户类型
DefaultUserTypeStaff = "staff"
)
// AuthUser 当前认证用户
type AuthUser struct {
UserID uint
Username string
Role string
UserType string
}
// AuthChecker 自定义权限检查函数
type AuthChecker func(user AuthUser, c *gin.Context) bool
// AuthRequired JWT 认证中间件
func AuthRequired() gin.HandlerFunc {
return func(c *gin.Context) {
authHeader := c.GetHeader("Authorization")
if authHeader == "" {
response.Unauthorized(c, "请先登录")
c.Abort()
return
}
// 解析 Bearer Token
parts := strings.SplitN(authHeader, " ", 2)
if len(parts) != 2 || !strings.EqualFold(parts[0], "Bearer") {
response.Unauthorized(c, "认证格式错误")
c.Abort()
return
}
tokenString := parts[1]
claims, err := jwt.ParseToken(tokenString)
if err != nil {
response.Unauthorized(c, "登录已过期，请重新登录")
c.Abort()
return
}
// 将用户信息存入上下文
c.Set(ContextKeyUserID, claims.UserID)
c.Set(ContextKeyUsername, claims.Username)
c.Set(ContextKeyRole, claims.Role)
c.Set(ContextKeyUserType, claims.UserType)
c.Next()
}
}
// RequireAuth 自定义权限中间件
func RequireAuth(checker AuthChecker, messages ...string) gin.HandlerFunc {
return func(c *gin.Context) {
user, ok := GetAuthUser(c)
if !ok {
abortAuthContext(c)
return
}
if checker == nil || !checker(user, c) {
abortForbidden(c, messages...)
return
}
c.Next()
}
}
// RequireUserTypes 用户类型权限中间件
func RequireUserTypes(userTypes ...string) gin.HandlerFunc {
allowed := make(map[string]struct{}, len(userTypes))
for _, userType := range userTypes {
allowed[userType] = struct{}{}
}
return RequireAuth(func(user AuthUser, c *gin.Context) bool {
_, ok := allowed[user.UserType]
return ok
})
}
// RequireRoles 角色权限中间件
func RequireRoles(roles ...string) gin.HandlerFunc {
allowed := make(map[string]struct{}, len(roles))
for _, role := range roles {
allowed[role] = struct{}{}
}
return RequireAuth(func(user AuthUser, c *gin.Context) bool {
_, ok := allowed[user.Role]
return ok
})
}
// AdminRequired 管理员权限中间件
func AdminRequired() gin.HandlerFunc {
return RequireUserTypes(DefaultUserTypeSuperAdmin, DefaultUserTypeAdmin)
}
// SuperAdminRequired 超级管理员权限中间件
func SuperAdminRequired() gin.HandlerFunc {
return RequireUserTypes(DefaultUserTypeSuperAdmin)
}
// StaffRequired 员工权限中间件
func StaffRequired() gin.HandlerFunc {
return RequireUserTypes(DefaultUserTypeStaff)
}
// AnyUserRequired 任意用户权限中间件（默认允许 admin/super_admin/staff）
func AnyUserRequired() gin.HandlerFunc {
return RequireUserTypes(DefaultUserTypeSuperAdmin, DefaultUserTypeAdmin, DefaultUserTypeStaff)
}
func abortAuthContext(c *gin.Context) {
if _, exists := c.Get(ContextKeyUserID); !exists {
response.Unauthorized(c, "请先登录")
} else {
response.Unauthorized(c, "用户信息异常")
}
c.Abort()
}
func abortForbidden(c *gin.Context, messages ...string) {
if len(messages) > 0 && messages[0] != "" {
response.Fail(c, messages[0])
} else {
response.FailWithError(c, response.ErrForbidden)
}
c.Abort()
}
// GetAuthUser 从上下文获取认证用户
func GetAuthUser(c *gin.Context) (AuthUser, bool) {
userID, exists := c.Get(ContextKeyUserID)
if !exists {
return AuthUser{}, false
}
id, ok := userID.(uint)
if !ok {
return AuthUser{}, false
}
username, exists := c.Get(ContextKeyUsername)
if !exists {
return AuthUser{}, false
}
name, ok := username.(string)
if !ok {
return AuthUser{}, false
}
role, exists := c.Get(ContextKeyRole)
if !exists {
return AuthUser{}, false
}
r, ok := role.(string)
if !ok {
return AuthUser{}, false
}
userType, exists := c.Get(ContextKeyUserType)
if !exists {
return AuthUser{}, false
}
ut, ok := userType.(string)
if !ok {
return AuthUser{}, false
}
return AuthUser{
UserID: id,
Username: name,
Role: r,
UserType: ut,
}, true
}
// GetUserID 从上下文获取用户ID
func GetUserID(c *gin.Context) uint {
userID, exists := c.Get(ContextKeyUserID)
if !exists {
return 0
}
// 安全的类型断言
id, ok := userID.(uint)
if !ok {
return 0
}
return id
}
// GetUsername 从上下文获取用户名
func GetUsername(c *gin.Context) string {
username, exists := c.Get(ContextKeyUsername)
if !exists {
return ""
}
// 安全的类型断言
name, ok := username.(string)
if !ok {
return ""
}
return name
}
// GetRole 从上下文获取角色
func GetRole(c *gin.Context) string {
role, exists := c.Get(ContextKeyRole)
if !exists {
return ""
}
// 安全的类型断言
r, ok := role.(string)
if !ok {
return ""
}
return r
}
// GetUserType 从上下文获取用户类型
func GetUserType(c *gin.Context) string {
userType, exists := c.Get(ContextKeyUserType)
if !exists {
return ""
}
// 安全的类型断言
ut, ok := userType.(string)
if !ok {
return ""
}
return ut
}
middleware/auth_test.go
+198
View File
@@ -0,0 +1,198 @@
package middleware_test
import (
"net/http"
"net/http/httptest"
"strings"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/EthanCodeCraft/xlgo-core/jwt"
"github.com/EthanCodeCraft/xlgo-core/middleware"
"github.com/gin-gonic/gin"
)
func performAuthMiddlewareRequest(m gin.HandlerFunc, setup func(*gin.Context)) *httptest.ResponseRecorder {
gin.SetMode(gin.TestMode)
r := gin.New()
r.Use(func(c *gin.Context) {
if setup != nil {
setup(c)
}
})
r.Use(m)
r.GET("/test", func(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"ok": true})
})
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/test", nil)
r.ServeHTTP(w, req)
return w
}
func setAuthUser(userType, role string) func(*gin.Context) {
return func(c *gin.Context) {
c.Set(middleware.ContextKeyUserID, uint(1))
c.Set(middleware.ContextKeyUsername, "tester")
c.Set(middleware.ContextKeyRole, role)
c.Set(middleware.ContextKeyUserType, userType)
}
}
func TestAuthRequiredAcceptsCaseInsensitiveBearer_M8(t *testing.T) {
setupMiddlewareMiniRedis(t)
if err := config.Set(&config.Config{
JWT: config.JWTConfig{
Secret: "test-secret-key-1234567890123456789012",
Expire: time.Hour,
},
}); err != nil {
t.Fatalf("set config: %v", err)
}
token, err := jwt.GenerateToken(1, "tester", "owner", "tenant_admin")
if err != nil {
t.Fatalf("GenerateToken: %v", err)
}
gin.SetMode(gin.TestMode)
r := gin.New()
r.Use(middleware.AuthRequired())
r.GET("/test", func(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"ok": true})
})
w := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/test", nil)
req.Header.Set("Authorization", "bearer "+token)
r.ServeHTTP(w, req)
if w.Code != http.StatusOK {
t.Fatalf("expected status 200, got %d, body %s", w.Code, w.Body.String())
}
if !strings.Contains(w.Body.String(), `"ok":true`) {
t.Fatalf("expected request to pass, got body %s", w.Body.String())
}
}
func TestRequireUserTypes(t *testing.T) {
w := performAuthMiddlewareRequest(middleware.RequireUserTypes("tenant_admin"), setAuthUser("tenant_admin", "owner"))
if w.Code != http.StatusOK {
t.Fatalf("expected status 200, got %d", w.Code)
}
if !strings.Contains(w.Body.String(), `"ok":true`) {
t.Fatalf("expected request to pass, got body %s", w.Body.String())
}
}
func TestRequireUserTypesRejectsOtherTypes(t *testing.T) {
w := performAuthMiddlewareRequest(middleware.RequireUserTypes("tenant_admin"), setAuthUser("staff", "owner"))
if w.Code != http.StatusOK {
t.Fatalf("expected business error over status 200, got %d", w.Code)
}
if !strings.Contains(w.Body.String(), `"code":403`) {
t.Fatalf("expected forbidden response, got body %s", w.Body.String())
}
}
func TestRequireRoles(t *testing.T) {
w := performAuthMiddlewareRequest(middleware.RequireRoles("owner"), setAuthUser("tenant_admin", "owner"))
if w.Code != http.StatusOK {
t.Fatalf("expected status 200, got %d", w.Code)
}
if !strings.Contains(w.Body.String(), `"ok":true`) {
t.Fatalf("expected request to pass, got body %s", w.Body.String())
}
}
func TestRequireAuthCustomChecker(t *testing.T) {
checker := func(user middleware.AuthUser, c *gin.Context) bool {
return user.UserID == 1 && user.UserType == "merchant" && user.Role == "owner"
}
w := performAuthMiddlewareRequest(middleware.RequireAuth(checker), setAuthUser("merchant", "owner"))
if w.Code != http.StatusOK {
t.Fatalf("expected status 200, got %d", w.Code)
}
if !strings.Contains(w.Body.String(), `"ok":true`) {
t.Fatalf("expected request to pass, got body %s", w.Body.String())
}
w = performAuthMiddlewareRequest(middleware.RequireAuth(checker, "需要商户所有者权限"), setAuthUser("merchant", "staff"))
if !strings.Contains(w.Body.String(), "需要商户所有者权限") {
t.Fatalf("expected custom forbidden message, got body %s", w.Body.String())
}
}
func TestDefaultRoleShortcuts(t *testing.T) {
tests := []struct {
name string
mw gin.HandlerFunc
userType string
wantPass bool
}{
{"admin allows super admin", middleware.AdminRequired(), middleware.DefaultUserTypeSuperAdmin, true},
{"admin allows admin", middleware.AdminRequired(), middleware.DefaultUserTypeAdmin, true},
{"admin rejects staff", middleware.AdminRequired(), middleware.DefaultUserTypeStaff, false},
{"super admin allows super admin", middleware.SuperAdminRequired(), middleware.DefaultUserTypeSuperAdmin, true},
{"super admin rejects admin", middleware.SuperAdminRequired(), middleware.DefaultUserTypeAdmin, false},
{"staff allows staff", middleware.StaffRequired(), middleware.DefaultUserTypeStaff, true},
{"any allows staff", middleware.AnyUserRequired(), middleware.DefaultUserTypeStaff, true},
{"any rejects external", middleware.AnyUserRequired(), "external", false},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
w := performAuthMiddlewareRequest(tt.mw, setAuthUser(tt.userType, "role"))
body := w.Body.String()
if tt.wantPass && !strings.Contains(body, `"ok":true`) {
t.Fatalf("expected pass, got body %s", body)
}
if !tt.wantPass && !strings.Contains(body, `"code":403`) {
t.Fatalf("expected forbidden, got body %s", body)
}
})
}
}
func TestRequireAuthRejectsMissingContext(t *testing.T) {
w := performAuthMiddlewareRequest(middleware.RequireUserTypes("admin"), nil)
if !strings.Contains(w.Body.String(), `"code":401`) || !strings.Contains(w.Body.String(), "请先登录") {
t.Fatalf("expected unauthorized login response, got body %s", w.Body.String())
}
}
func TestRequireAuthRejectsMalformedContext(t *testing.T) {
w := performAuthMiddlewareRequest(middleware.RequireUserTypes("admin"), func(c *gin.Context) {
c.Set(middleware.ContextKeyUserID, uint(1))
c.Set(middleware.ContextKeyUsername, "tester")
c.Set(middleware.ContextKeyRole, "owner")
c.Set(middleware.ContextKeyUserType, 123)
})
if !strings.Contains(w.Body.String(), `"code":401`) || !strings.Contains(w.Body.String(), "用户信息异常") {
t.Fatalf("expected malformed user response, got body %s", w.Body.String())
}
}
func TestGetAuthUser(t *testing.T) {
gin.SetMode(gin.TestMode)
c, _ := gin.CreateTestContext(httptest.NewRecorder())
setAuthUser("tenant_admin", "owner")(c)
user, ok := middleware.GetAuthUser(c)
if !ok {
t.Fatal("expected auth user")
}
if user.UserID != 1 || user.Username != "tester" || user.UserType != "tenant_admin" || user.Role != "owner" {
t.Fatalf("unexpected auth user: %+v", user)
}
if middleware.GetRole(c) != "owner" {
t.Fatalf("expected role owner, got %q", middleware.GetRole(c))
}
c.Set(middleware.ContextKeyUserID, "bad")
if _, ok := middleware.GetAuthUser(c); ok {
t.Fatal("expected malformed auth user to fail")
}
}
middleware/cors.go
+217
View File
@@ -0,0 +1,217 @@
package middleware
import (
"net/http"
"net/url"
"strconv"
"strings"
"github.com/EthanCodeCraft/xlgo-core/config"
"github.com/gin-gonic/gin"
)
// CORS 跨域中间件
// 支持从配置文件读取 CORS 配置；遵循 W3C CORS 规范：
// 当 AllowCredentials=true 时，Access-Control-Allow-Origin 必须回显为具体 Origin，
// 不能使用 "*"（浏览器会拒绝携带凭证的响应）。
func CORS() gin.HandlerFunc {
return CORSWithConfig(nil)
}
// CORSWithConfig 使用自定义配置的 CORS 中间件
func CORSWithConfig(corsCfg *config.CORSConfig) gin.HandlerFunc {
return func(c *gin.Context) {
origin := c.GetHeader("Origin")
// 获取配置
cfg := config.Get()
var corsConfig *config.CORSConfig
if corsCfg != nil {
corsConfig = corsCfg
} else if cfg != nil {
corsConfig = &cfg.CORS
}
// 是否允许携带凭证（影响 Origin 回显策略）
allowCredentials := corsConfig != nil && corsConfig.AllowCredentials
// 获取允许的域名列表
allowedOrigins := getAllowedOrigins(cfg, corsConfig)
// 匹配 Origin
// 注意：当 allowCredentials=true 且匹配到通配符时，
// 必须回显具体 Origin 而非 "*"，否则浏览器会拒绝响应。
allowedOrigin := ""
matchedWildcard := false
if origin != "" {
for _, ao := range allowedOrigins {
if ao == "*" {
matchedWildcard = true
break
}
if matchOrigin(origin, ao) {
allowedOrigin = origin
break
}
}
}
// 处理通配符 + 兜底策略
if allowedOrigin == "" {
if matchedWildcard {
if allowCredentials && origin != "" {
// AllowCredentials=true 时 spec 禁止 "*"，回显具体 Origin
allowedOrigin = origin
} else {
allowedOrigin = "*"
}
} else if cfg != nil && cfg.IsDevelopment() && origin != "" && isLocalhostOrigin(origin) {
// 开发环境兜底：仅对 localhost 来源回显具体 Origin（C7b 修复）。
// 旧实现无条件回显任意 Origin，若同时 AllowCredentials=true 则构成凭据型反射。
allowedOrigin = origin
}
}
// 设置 CORS 响应头
// 仅在 origin 匹配时发送 CORS 头（C7 收尾：未匹配 origin 不发 Allow-Methods/Headers 等，
// 收敛信息泄露——避免向未授权 origin 暴露 API 允许的方法/头清单）。
if allowedOrigin != "" {
c.Header("Access-Control-Allow-Origin", allowedOrigin)
// Origin 不是 "*" 时，下游缓存（CDN / 网关）必须按 Origin 区分缓存
if allowedOrigin != "*" {
c.Header("Vary", "Origin")
}
methods := corsConfig.GetAllowedMethods()
headers := corsConfig.GetAllowedHeaders()
exposedHeaders := corsConfig.GetExposedHeaders()
maxAge := corsConfig.GetMaxAge()
c.Header("Access-Control-Allow-Methods", strings.Join(methods, ", "))
c.Header("Access-Control-Allow-Headers", strings.Join(headers, ", "))
c.Header("Access-Control-Expose-Headers", strings.Join(exposedHeaders, ", "))
c.Header("Access-Control-Max-Age", strconv.Itoa(maxAge))
}
// 仅在显式启用且 Origin 不是 "*" 时才发 Allow-Credentials
// （CORS 规范：Allow-Origin: * 时禁止携带凭证）
if allowCredentials && allowedOrigin != "" && allowedOrigin != "*" {
c.Header("Access-Control-Allow-Credentials", "true")
}
// 处理预检请求
if c.Request.Method == "OPTIONS" {
c.AbortWithStatus(http.StatusNoContent)
return
}
c.Next()
}
}
// matchOrigin 判断 origin 是否匹配允许的 Origin 模式 ao。
//
// 支持三种模式（C7a 修复）：
// 1. 精确匹配：ao == origin（scheme+host+port 全等）。
// 2. 通配子域：ao 形如 "*.example.com"，匹配 example.com 的任意子域（含 a.example.com、
// a.b.example.com），但**不匹配 apex example.com 自身**，也**不匹配 notexample.com、
// evil-example.com 等后缀相同但非真实子域的域名**。旧实现用 strings.HasSuffix(origin, domain)
// 未锚定 host 边界，导致上述绕过。
// 3. 通配 apex+子域：ao 形如 "*.example.com" 经本函数仅匹配子域；若需同时允许 apex，
// 配置中需显式列出 "https://example.com"。
//
// 解析 origin 的 host 做真实子域边界判断（而非字符串后缀），杜绝 notexample.com 类绕过。
func matchOrigin(origin, ao string) bool {
if origin == "" || ao == "" {
return false
}
// 精确匹配。
if origin == ao {
return true
}
// 通配子域 *.domain。
if strings.HasPrefix(ao, "*.") {
wildcardDomain := strings.ToLower(strings.TrimSuffix(ao[2:], ".")) // 如 "example.com"
u, err := url.Parse(origin)
if err != nil || u.Host == "" {
return false
}
// 去端口、去尾点（FQDN 尾点表示 a.example.com. 应等同 a.example.com）。
host := strings.ToLower(strings.TrimSuffix(u.Hostname(), "."))
// host 必须是 *.domain 的真实子域：host == "x." + wildcardDomain，
// 且 x 非空、不含点（即直接子域）或为多级子域（a.b.example.com）。
// 关键：host 必须以 "." + wildcardDomain 结尾（锚定边界），杜绝 notexample.com。
if !strings.HasSuffix(host, "."+wildcardDomain) {
return false
}
// 排除 host == wildcardDomain 自身（apex 不由通配匹配，需显式配置）。
if host == wildcardDomain {
return false
}
return true
}
return false
}
// isLocalhostOrigin 判断 origin 是否为 localhost 来源（开发态兜底用，C7b 修复）。
// 仅允许 localhost / 127.0.0.1 / ::1 的任意端口，杜绝开发态回显任意 Origin。
func isLocalhostOrigin(origin string) bool {
u, err := url.Parse(origin)
if err != nil || u.Host == "" {
return false
}
host := strings.TrimSuffix(u.Hostname(), ".")
return host == "localhost" || host == "127.0.0.1" || host == "::1"
}
// getAllowedOrigins 获取允许的域名列表
// 优先使用配置文件，生产环境必须显式配置，开发环境提供 localhost 兜底。
func getAllowedOrigins(cfg *config.Config, corsConfig *config.CORSConfig) []string {
// 优先使用 CORS 配置
if corsConfig != nil && len(corsConfig.AllowedOrigins) > 0 {
return corsConfig.AllowedOrigins
}
// 生产环境：必须配置具体的域名
if cfg != nil && cfg.IsProduction() {
// 返回空列表，生产环境必须配置
return []string{}
}
// 开发环境允许 localhost
return []string{
"http://localhost:3000",
"http://localhost:5173",
"http://localhost:8080",
"http://localhost:4200",
"http://127.0.0.1:3000",
"http://127.0.0.1:5173",
"http://127.0.0.1:8080",
"http://127.0.0.1:4200",
}
}
// CORSWithOrigins 使用指定域名列表的 CORS 中间件
func CORSWithOrigins(origins []string) gin.HandlerFunc {
return CORSWithConfig(&config.CORSConfig{
AllowedOrigins: origins,
})
}
// CORSWithWildcard 允许所有来源的 CORS 中间件（仅用于开发环境）
// 注意：生产环境不建议使用
func CORSWithWildcard() gin.HandlerFunc {
return CORSWithConfig(&config.CORSConfig{
AllowedOrigins: []string{"*"},
})
}
// CORSForAPI 适用于 API 的 CORS 中间件
func CORSForAPI() gin.HandlerFunc {
return CORSWithConfig(&config.CORSConfig{
AllowedOrigins: []string{"*"},
AllowedMethods: []string{"GET", "POST", "PUT", "PATCH", "DELETE"},
AllowedHeaders: []string{"Content-Type", "Authorization", "X-Requested-With"},
AllowCredentials: false, // API 模式不允许凭证
})
}
middleware/cors_internal_test.go
+94
View File
@@ -0,0 +1,94 @@
package middleware
import "testing"
// 回归 C7a：通配符子域匹配必须锚定真实子域边界，拒绝后缀相同但非子域的域名。
// 旧实现 strings.HasSuffix(origin, domain) 接受 notexample.com / evil-example.com。
func TestMatchOriginWildcardBoundary(t *testing.T) {
cases := []struct {
name string
origin string
ao string
want bool
}{
// 精确匹配
{"exact", "https://example.com", "https://example.com", true},
{"exact with port", "https://example.com:8443", "https://example.com:8443", true},
{"exact mismatch", "https://example.com", "https://other.com", false},
// 通配子域 *.example.com
{"subdomain ok", "https://a.example.com", "*.example.com", true},
{"deep subdomain ok", "https://a.b.example.com", "*.example.com", true},
{"subdomain with port ok", "https://a.example.com:3000", "*.example.com", true},
{"apex not matched by wildcard", "https://example.com", "*.example.com", false},
// C7a 核心：后缀相同但非真实子域必须拒绝
{"notexample.com rejected", "https://notexample.com", "*.example.com", false},
{"evil-example.com rejected", "https://evil-example.com", "*.example.com", false},
{"villainexample.com rejected", "https://villainexample.com", "*.example.com", false},
// 端口/协议不同的 origin host 仍按 host 判断
{"http subdomain ok", "http://a.example.com", "*.example.com", true},
// 通配仅匹配 host，scheme 不同的精确配置不被通配覆盖
{"different scheme exact not wildcard", "http://example.com", "https://example.com", false},
// 边界
{"empty origin", "", "*.example.com", false},
{"empty ao", "https://a.example.com", "", false},
{"malformed origin", "://:bad", "*.example.com", false},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
got := matchOrigin(c.origin, c.ao)
if got != c.want {
t.Errorf("matchOrigin(%q, %q) = %v, want %v", c.origin, c.ao, got, c.want)
}
})
}
}
// 回归 C7a：通配大小写不敏感（host 归一化为小写比较）。
func TestMatchOriginCaseInsensitive(t *testing.T) {
if !matchOrigin("https://A.Example.COM", "*.example.com") {
t.Error("matchOrigin should be case-insensitive on host")
}
}
// 回归 C7a：trailing dot FQDN（a.example.com.）应等同 a.example.com 被接受（功能正确性）。
func TestMatchOriginTrailingDot(t *testing.T) {
if !matchOrigin("https://a.example.com.", "*.example.com") {
t.Error("trailing-dot subdomain should match wildcard")
}
if !matchOrigin("https://a.example.com", "*.example.com.") {
t.Error("trailing-dot wildcard should match plain subdomain")
}
}
// 回归 C7b：isLocalhostOrigin 仅允许 localhost/127.0.0.1/::1，拒绝任意其他来源。
func TestIsLocalhostOrigin(t *testing.T) {
allowed := []string{
"http://localhost:3000",
"http://localhost",
"http://127.0.0.1:8080",
"http://127.0.0.1",
"http://[::1]:4000",
"http://[::1]",
}
for _, o := range allowed {
if !isLocalhostOrigin(o) {
t.Errorf("isLocalhostOrigin(%q) = false, want true", o)
}
}
denied := []string{
"https://evil.com",
"https://localhost.evil.com", // 后缀含 localhost 但非 localhost host
"https://notlocalhost.com",
"https://example.com",
"",
"://bad",
}
for _, o := range denied {
if isLocalhostOrigin(o) {
t.Errorf("isLocalhostOrigin(%q) = true, want false", o)
}
}
}
middleware/csrf.go
+465
View File
@@ -0,0 +1,465 @@
package middleware
import (
"crypto/rand"
"crypto/subtle"
"encoding/base64"
"errors"
"net/http"
"strings"
"sync"
"time"
"github.com/EthanCodeCraft/xlgo-core/response"
"github.com/gin-gonic/gin"
"github.com/gin-gonic/gin/binding"
)
const (
// CSRFTokenLength CSRF Token 长度
CSRFTokenLength = 32
// CSRFHeaderName CSRF Header 名称
CSRFHeaderName = "X-CSRF-Token"
// CSRFCookieName CSRF Cookie 名称
CSRFCookieName = "csrf_token"
// CSRFFormField 表单字段名称
CSRFFormField = "_csrf"
// CSRFMaxBodyBytes JSON body 中读取 CSRF token 的最大字节数，防止 pre-auth OOM。
CSRFMaxBodyBytes = 1 << 20 // 1 MiB
)
// CSRFConfig CSRF 配置
type CSRFConfig struct {
// TokenLength Token 长度
TokenLength int
// HeaderName Header 名称
HeaderName string
// CookieName Cookie 名称
CookieName string
// FormField 表单字段名
FormField string
// Secure Cookie 是否启用 Secure
Secure bool
// HTTPOnly Cookie 是否启用 HttpOnly
HTTPOnly bool
// SameSite Cookie SameSite 属性
SameSite http.SameSite
// Domain Cookie 域名
Domain string
// Path Cookie 路径
Path string
// MaxAge Cookie 有效期（秒）
MaxAge int
// SessionCookie 为 true 时显式使用会话 Cookie（MaxAge=0）。
// 为保持 CSRFWithConfig(CSRFConfig{}) 的默认行为，MaxAge=0 且本字段为 false 时仍使用默认 1 小时。
SessionCookie bool
// MaxBodyBytes 从 JSON body 提取 token 时允许读取的最大字节数。
// <=0 时使用默认 1MiB。Header/Form token 不受此限制。
MaxBodyBytes int64
// ErrorFunc 错误处理函数
ErrorFunc func(c *gin.Context)
// SkipFunc 跳过检查函数
SkipFunc func(c *gin.Context) bool
}
// DefaultCSRFConfig 默认 CSRF 配置
var DefaultCSRFConfig = CSRFConfig{
TokenLength: CSRFTokenLength,
HeaderName: CSRFHeaderName,
CookieName: CSRFCookieName,
FormField: CSRFFormField,
Secure: false,
HTTPOnly: true,
SameSite: http.SameSiteLaxMode,
Path: "/",
MaxAge: 3600, // 1 小时
MaxBodyBytes: CSRFMaxBodyBytes,
ErrorFunc: defaultCSRFError,
SkipFunc: nil,
}
// generateCSRFToken 生成 CSRF Token
func generateCSRFToken(length int) (string, error) {
if length <= 0 {
length = CSRFTokenLength
}
bytes := make([]byte, length)
if _, err := rand.Read(bytes); err != nil {
return "", err
}
return base64.URLEncoding.EncodeToString(bytes), nil
}
// defaultCSRFError 默认错误处理
func defaultCSRFError(c *gin.Context) {
response.Fail(c, "CSRF Token 无效，请刷新页面重试")
c.Abort()
}
func csrfBodyTooLarge(c *gin.Context) {
response.Custom(c, http.StatusRequestEntityTooLarge, response.CodeFileTooLarge, "请求体过大", nil)
c.Abort()
}
func normalizeCSRFConfig(cfg CSRFConfig) CSRFConfig {
if cfg.TokenLength <= 0 {
cfg.TokenLength = CSRFTokenLength
}
if cfg.HeaderName == "" {
cfg.HeaderName = CSRFHeaderName
}
if cfg.CookieName == "" {
cfg.CookieName = CSRFCookieName
}
if cfg.FormField == "" {
cfg.FormField = CSRFFormField
}
if cfg.Path == "" {
cfg.Path = "/"
}
if cfg.SameSite == 0 {
cfg.SameSite = DefaultCSRFConfig.SameSite
}
if cfg.MaxAge == 0 && !cfg.SessionCookie {
cfg.MaxAge = DefaultCSRFConfig.MaxAge
}
if cfg.MaxBodyBytes <= 0 {
cfg.MaxBodyBytes = CSRFMaxBodyBytes
}
if cfg.ErrorFunc == nil {
cfg.ErrorFunc = defaultCSRFError
}
return cfg
}
func pathMatchesSkip(path, prefix string) bool {
if prefix == "" {
return false
}
if prefix == "/" {
return true
}
prefix = strings.TrimRight(prefix, "/")
return path == prefix || strings.HasPrefix(path, prefix+"/")
}
// CSRF 创建 CSRF 中间件
func CSRF(config ...CSRFConfig) gin.HandlerFunc {
cfg := DefaultCSRFConfig
if len(config) > 0 {
cfg = config[0]
}
cfg = normalizeCSRFConfig(cfg)
return func(c *gin.Context) {
// 检查是否跳过
if cfg.SkipFunc != nil && cfg.SkipFunc(c) {
c.Next()
return
}
// 获取或生成 Token
cookieToken, err := c.Cookie(cfg.CookieName)
if err != nil || cookieToken == "" {
// 生成新 Token
token, err := generateCSRFToken(cfg.TokenLength)
if err != nil {
cfg.ErrorFunc(c)
return
}
cookieToken = token
// 设置 Cookie
c.SetSameSite(cfg.SameSite)
c.SetCookie(
cfg.CookieName,
token,
cfg.MaxAge,
cfg.Path,
cfg.Domain,
cfg.Secure,
cfg.HTTPOnly,
)
}
// 将 Token 存入上下文，供前端使用
c.Set("csrf_token", cookieToken)
// 安全方法（GET, HEAD, OPTIONS, TRACE）不需要验证
if isSafeMethod(c.Request.Method) {
c.Next()
return
}
// 验证 Token
clientToken := ""
// 优先从 Header 获取
clientToken = c.GetHeader(cfg.HeaderName)
// 其次从表单获取
if clientToken == "" {
clientToken = c.PostForm(cfg.FormField)
}
// 最后从 JSON body 获取。
// P1 #9：用 ShouldBindBodyWith(binding.JSON) 而非 ShouldBindJSON——后者会读干
// c.Request.Body，导致下游 handler 再 ShouldBindJSON 拿到空 body(EOF)。前者把原始
// body 缓存进 gin context，下游可重复读取。
if clientToken == "" {
var body map[string]any
c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, cfg.MaxBodyBytes)
if err := c.ShouldBindBodyWith(&body, binding.JSON); err == nil {
if token, ok := body[cfg.FormField].(string); ok {
clientToken = token
}
} else {
var maxErr *http.MaxBytesError
if errors.As(err, &maxErr) {
csrfBodyTooLarge(c)
return
}
}
}
// 验证 Token 是否匹配（H-7: 恒定时间比较防时序侧信道）
if len(clientToken) == 0 || subtle.ConstantTimeCompare([]byte(clientToken), []byte(cookieToken)) != 1 {
cfg.ErrorFunc(c)
return
}
c.Next()
}
}
// isSafeMethod 判断是否为安全方法
func isSafeMethod(method string) bool {
switch strings.ToUpper(method) {
case http.MethodGet, http.MethodHead, http.MethodOptions, http.MethodTrace:
return true
default:
return false
}
}
// GetCSRFToken 从上下文获取 CSRF Token
func GetCSRFToken(c *gin.Context) string {
token, exists := c.Get("csrf_token")
if !exists {
return ""
}
// H-7: comma-ok 防裸断言 panic。csrf_token 虽由本包以 string 写入，
// 但 gin context 是共享 map，下游误写其他类型即 panic。
s, ok := token.(string)
if !ok {
return ""
}
return s
}
// CSRFToken 返回当前请求上下文中的 CSRF Token；若上下文无 Token 则现场生成一个返回。
// 适用于 Cookie/双重提交模式（与 CSRF/DoubleSubmitCookie 中间件配合），
// 不与 CSRFForAPI 配套--API 模式的可校验 Token 请用 GenerateAPIToken 颁发。
func CSRFToken(c *gin.Context) {
token := GetCSRFToken(c)
if token == "" {
var err error
token, err = generateCSRFToken(CSRFTokenLength)
if err != nil {
response.ServerError(c, "生成 Token 失败")
return
}
}
response.Success(c, gin.H{
"csrf_token": token,
})
}
// CSRFWithSkip 跳过指定路径的 CSRF 检查
func CSRFWithSkip(skipPaths []string) gin.HandlerFunc {
cfg := DefaultCSRFConfig
cfg.SkipFunc = func(c *gin.Context) bool {
path := c.Request.URL.Path
for _, p := range skipPaths {
if pathMatchesSkip(path, p) {
return true
}
}
return false
}
return CSRF(cfg)
}
// CSRFForAPI 适用于 API 的 CSRF 中间件（不使用 Cookie）
// 客户端需要先调用 GenerateAPIToken 获取 Token，随后在每个非安全方法请求的
// X-CSRF-Token 头中携带。Token 单次消费（验证通过即删除）且受 TTL 约束，
// 防止重放与内存无限增长。
//
// 注意：存储为进程内内存，仅适用于单实例部署。多实例请自行用 Redis
// SETEX + GETDEL 实现等价语义。
func CSRFForAPI() gin.HandlerFunc {
return func(c *gin.Context) {
// 安全方法不需要验证
if isSafeMethod(c.Request.Method) {
c.Next()
return
}
// 从 Header 获取 Token
clientToken := c.GetHeader(CSRFHeaderName)
if clientToken == "" {
response.Fail(c, "缺少 CSRF Token")
c.Abort()
return
}
// 单次消费 + TTL：校验通过即删除，防止同一 token 被重放。
// 写锁内完成“查—删—过期清理”以保证原子性。
apiTokensMu.Lock()
issuedAt, ok := apiTokens[clientToken]
if ok {
delete(apiTokens, clientToken)
}
// 懒清理：map 较大时顺带淘汰过期项，避免内存无限增长。
if len(apiTokens) > 256 {
now := time.Now()
for t, at := range apiTokens {
if now.Sub(at) > apiTokenTTL {
delete(apiTokens, t)
}
}
}
apiTokensMu.Unlock()
if !ok || time.Since(issuedAt) > apiTokenTTL {
response.Fail(c, "CSRF Token 无效")
c.Abort()
return
}
c.Next()
}
}
// GenerateAPIToken 生成 API CSRF Token（用于 API 模式）
// 颁发的 Token 写入进程内存储，供 CSRFForAPI 校验。
func GenerateAPIToken(c *gin.Context) {
token, err := generateCSRFToken(CSRFTokenLength)
if err != nil {
response.ServerError(c, "生成 Token 失败")
return
}
apiTokensMu.Lock()
cleanupExpiredAPITokensLocked(time.Now())
apiTokens[token] = time.Now()
apiTokensMu.Unlock()
response.Success(c, gin.H{
"csrf_token": token,
})
}
// API 模式 CSRF Token 存储：token -> 颁发时间。
// 受 apiTokensMu 保护，单次消费 + TTL（见 CSRFForAPI）。
var (
apiTokens = make(map[string]time.Time)
apiTokensMu sync.RWMutex
)
// apiTokenTTL API 模式 CSRF Token 有效期
const apiTokenTTL = 30 * time.Minute
func cleanupExpiredAPITokensLocked(now time.Time) {
for t, at := range apiTokens {
if now.Sub(at) > apiTokenTTL {
delete(apiTokens, t)
}
}
}
// CSRFExempt 标记路由不需要 CSRF 保护
// 使用方法：在路由组上使用此中间件
func CSRFExempt() gin.HandlerFunc {
return func(c *gin.Context) {
c.Set("csrf_exempt", true)
c.Next()
}
}
// CSRFWithExempt 支持 exempt 标记的 CSRF 中间件
func CSRFWithExempt(config ...CSRFConfig) gin.HandlerFunc {
cfg := DefaultCSRFConfig
if len(config) > 0 {
cfg = config[0]
}
cfg = normalizeCSRFConfig(cfg)
originalSkipFunc := cfg.SkipFunc
cfg.SkipFunc = func(c *gin.Context) bool {
// 检查是否标记为 exempt（P1 #9：comma-ok 防裸断言 panic——gin context 为共享 map，
// 下游若误以非 bool 写入 csrf_exempt，exempt.(bool) 会 panic）。
if exempt, exists := c.Get("csrf_exempt"); exists {
if b, ok := exempt.(bool); ok && b {
return true
}
}
// 调用原始 SkipFunc
if originalSkipFunc != nil {
return originalSkipFunc(c)
}
return false
}
return CSRF(cfg)
}
// DoubleSubmitCookie 双重提交 Cookie 模式（无需服务器存储）
// 适用于无状态 API
func DoubleSubmitCookie() gin.HandlerFunc {
return func(c *gin.Context) {
// 安全方法不需要验证
if isSafeMethod(c.Request.Method) {
// 设置 Cookie（如果不存在）
cookieToken, err := c.Cookie(CSRFCookieName)
if err != nil || cookieToken == "" {
token, _ := generateCSRFToken(CSRFTokenLength)
// 双重提交模式要求前端 JS 读取 cookie 并回填 X-CSRF-Token 头，
// 故 HttpOnly 必须为 false（与 CSRF() cookie 模式相反）。
c.SetSameSite(http.SameSiteLaxMode)
c.SetCookie(CSRFCookieName, token, 3600, "/", "", false, false)
c.Set("csrf_token", token)
} else {
c.Set("csrf_token", cookieToken)
}
c.Next()
return
}
// 获取 Cookie 中的 Token
cookieToken, err := c.Cookie(CSRFCookieName)
if err != nil {
response.Fail(c, "CSRF Token 缺失")
c.Abort()
return
}
// 获取 Header 中的 Token
headerToken := c.GetHeader(CSRFHeaderName)
if headerToken == "" {
response.Fail(c, "缺少 CSRF Token")
c.Abort()
return
}
// 验证 Cookie 和 Header 中的 Token 是否一致（H-7: 恒定时间比较防时序侧信道）
if subtle.ConstantTimeCompare([]byte(cookieToken), []byte(headerToken)) != 1 {
response.Fail(c, "CSRF Token 不匹配")
c.Abort()
return
}
c.Next()
}
}
middleware/csrf_internal_test.go
+234
View File
@@ -0,0 +1,234 @@
package middleware
import (
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/response"
"github.com/gin-gonic/gin"
"github.com/gin-gonic/gin/binding"
)
// 回归 C6b：TTL 过期分支。直接向包级存储注入一个“已过期”的 token，
// 断言 CSRFForAPI 拒绝它（即使该 token 从未被消费过）。
// 这条分支（time.Since(issuedAt) > apiTokenTTL）无法靠单次消费用例覆盖，
// 必须单独构造过期时间戳。
func TestCSRFForAPITTLExpiry(t *testing.T) {
gin.SetMode(gin.TestMode)
r := gin.New()
r.Use(CSRFForAPI())
r.POST("/action", func(c *gin.Context) { c.JSON(200, gin.H{"status": "ok"}) })
expiredToken := "expired-test-token"
apiTokensMu.Lock()
// 注入一个早于 TTL 的颁发时间，模拟 token 已过期。
apiTokens[expiredToken] = time.Now().Add(-(apiTokenTTL + time.Second))
apiTokensMu.Unlock()
defer func() {
apiTokensMu.Lock()
delete(apiTokens, expiredToken)
apiTokensMu.Unlock()
}()
w := httptest.NewRecorder()
req := httptest.NewRequest("POST", "/action", nil)
req.Header.Set("X-CSRF-Token", expiredToken)
r.ServeHTTP(w, req)
var resp response.Response
if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
t.Fatalf("unmarshal response %q: %v", w.Body.String(), err)
}
if resp.Code == response.CodeSuccess {
t.Errorf("expired token must be rejected, got code=%d (success)", resp.Code)
}
}
// 回归 P1 #9：CSRF 从 JSON body 取 token 后，下游 handler 仍能读到完整请求体。
// 修复前用 ShouldBindJSON 读干 body，下游再绑定拿到 EOF；改用 ShouldBindBodyWith 缓存 body。
func TestCSRFJSONBodyPreservedForDownstream(t *testing.T) {
gin.SetMode(gin.TestMode)
r := gin.New()
r.Use(CSRF())
var gotData string
r.POST("/action", func(c *gin.Context) {
// 下游再次绑定 body，应能读到完整内容（而非被 CSRF 中间件读空）。
var payload struct {
Data string `json:"data"`
}
if err := c.ShouldBindBodyWith(&payload, binding.JSON); err != nil {
c.JSON(500, gin.H{"err": err.Error()})
return
}
gotData = payload.Data
c.JSON(200, gin.H{"status": "ok"})
})
// token 仅放在 JSON body 里（不放 header/form），触发中间件读 body 的分支。
const tok = "csrf-token-abc-1234567890"
body := `{"_csrf":"` + tok + `","data":"hello-downstream"}`
req := httptest.NewRequest("POST", "/action", strings.NewReader(body))
req.Header.Set("Content-Type", "application/json")
// cookie 携带同一 token，使 CSRF 校验通过。
req.AddCookie(&http.Cookie{Name: CSRFCookieName, Value: tok})
w := httptest.NewRecorder()
r.ServeHTTP(w, req)
if w.Code != 200 {
t.Fatalf("expected 200, got %d, body=%s", w.Code, w.Body.String())
}
if gotData != "hello-downstream" {
t.Errorf("downstream read data=%q, want 'hello-downstream' (P1 #9: body must survive CSRF)", gotData)
}
}
func TestCSRFJSONBodyTooLargeRejected(t *testing.T) {
gin.SetMode(gin.TestMode)
r := gin.New()
r.Use(CSRF(CSRFConfig{MaxBodyBytes: 16}))
r.POST("/action", func(c *gin.Context) { c.JSON(200, gin.H{"status": "ok"}) })
body := `{"_csrf":"token","data":"` + strings.Repeat("x", 64) + `"}`
req := httptest.NewRequest(http.MethodPost, "/action", strings.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.AddCookie(&http.Cookie{Name: CSRFCookieName, Value: "token"})
w := httptest.NewRecorder()
r.ServeHTTP(w, req)
if w.Code != http.StatusRequestEntityTooLarge {
t.Fatalf("status = %d, want 413; body=%s", w.Code, w.Body.String())
}
}
func TestCSRFNegativeTokenLengthFallsBack(t *testing.T) {
gin.SetMode(gin.TestMode)
r := gin.New()
r.Use(CSRF(CSRFConfig{TokenLength: -1}))
r.GET("/form", func(c *gin.Context) { c.JSON(200, gin.H{"token": GetCSRFToken(c)}) })
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/form", nil))
if w.Code != http.StatusOK {
t.Fatalf("status = %d, want 200; body=%s", w.Code, w.Body.String())
}
if len(w.Result().Cookies()) == 0 {
t.Fatal("expected csrf cookie to be set")
}
}
func TestCSRFCookieSameSiteLax(t *testing.T) {
gin.SetMode(gin.TestMode)
r := gin.New()
r.Use(CSRF())
r.GET("/form", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) })
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/form", nil))
for _, c := range w.Result().Cookies() {
if c.Name == CSRFCookieName {
if c.SameSite != http.SameSiteLaxMode {
t.Fatalf("SameSite = %v, want Lax", c.SameSite)
}
return
}
}
t.Fatal("csrf cookie not set")
}
func TestCSRFPartialConfigKeepsCookieDefaults(t *testing.T) {
gin.SetMode(gin.TestMode)
r := gin.New()
r.Use(CSRF(CSRFConfig{TokenLength: -1}))
r.GET("/form", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) })
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/form", nil))
for _, c := range w.Result().Cookies() {
if c.Name == CSRFCookieName {
if c.SameSite != http.SameSiteLaxMode {
t.Fatalf("SameSite = %v, want Lax for partial config", c.SameSite)
}
if c.MaxAge != DefaultCSRFConfig.MaxAge {
t.Fatalf("MaxAge = %d, want %d for partial config", c.MaxAge, DefaultCSRFConfig.MaxAge)
}
return
}
}
t.Fatal("csrf cookie not set")
}
func TestDoubleSubmitCookieSameSiteLax(t *testing.T) {
gin.SetMode(gin.TestMode)
r := gin.New()
r.Use(DoubleSubmitCookie())
r.GET("/get", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) })
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/get", nil))
for _, c := range w.Result().Cookies() {
if c.Name == CSRFCookieName {
if c.SameSite != http.SameSiteLaxMode {
t.Fatalf("SameSite = %v, want Lax", c.SameSite)
}
return
}
}
t.Fatal("csrf cookie not set")
}
func TestCSRFWithSkipAnchorsPathBoundary(t *testing.T) {
gin.SetMode(gin.TestMode)
r := gin.New()
r.Use(CSRFWithSkip([]string{"/api"}))
r.POST("/api", func(c *gin.Context) { c.Status(http.StatusNoContent) })
r.POST("/api/users", func(c *gin.Context) { c.Status(http.StatusNoContent) })
r.POST("/apix", func(c *gin.Context) { c.Status(http.StatusNoContent) })
for _, path := range []string{"/api", "/api/users"} {
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest(http.MethodPost, path, nil))
if w.Code != http.StatusNoContent {
t.Fatalf("%s status = %d, want skipped 204", path, w.Code)
}
}
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/apix", nil))
if w.Code == http.StatusNoContent {
t.Fatal("/apix was skipped by /api prefix; want CSRF rejection")
}
}
func TestGenerateAPITokenCleansExpiredTokens(t *testing.T) {
gin.SetMode(gin.TestMode)
expiredToken := "expired-before-issue"
apiTokensMu.Lock()
apiTokens[expiredToken] = time.Now().Add(-(apiTokenTTL + time.Second))
apiTokensMu.Unlock()
defer func() {
apiTokensMu.Lock()
delete(apiTokens, expiredToken)
apiTokensMu.Unlock()
}()
r := gin.New()
r.GET("/csrf-token", GenerateAPIToken)
w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/csrf-token", nil))
if w.Code != http.StatusOK {
t.Fatalf("status = %d, want 200; body=%s", w.Code, w.Body.String())
}
apiTokensMu.RLock()
_, exists := apiTokens[expiredToken]
apiTokensMu.RUnlock()
if exists {
t.Fatal("GenerateAPIToken did not clean expired token")
}
}
middleware/logger.go
+308
View File
@@ -0,0 +1,308 @@
package middleware
import (
"bytes"
"io"
"net/url"
"regexp"
"strings"
"time"
"github.com/EthanCodeCraft/xlgo-core/logger"
"github.com/gin-gonic/gin"
"go.uber.org/zap"
)
// LoggerConfig 日志中间件配置
type LoggerConfig struct {
// LogRequestBody 是否记录请求体
LogRequestBody bool
// LogResponseBody 是否记录响应体
LogResponseBody bool
// MaxBodyLength 最大记录的请求/响应体长度（字节）
MaxBodyLength int
// SkipPaths 不记录日志的路径
SkipPaths []string
// SkipPathPrefixes 不记录日志的路径前缀
SkipPathPrefixes []string
// SlowRequestThreshold 慢请求阈值（超过此时间记录警告）
SlowRequestThreshold time.Duration
}
// DefaultLoggerConfig 默认日志配置
var DefaultLoggerConfig = LoggerConfig{
LogRequestBody: false, // 默认不记录请求体（敏感信息风险）
LogResponseBody: false, // 默认不记录响应体
MaxBodyLength: 1024, // 最大 1KB
SkipPaths: []string{"/health", "/swagger"},
SkipPathPrefixes: []string{"/public", "/static"},
SlowRequestThreshold: 500 * time.Millisecond,
}
// Logger 日志中间件（使用默认配置）
func Logger() gin.HandlerFunc {
return LoggerWithConfig(DefaultLoggerConfig)
}
// LoggerWithConfig 使用自定义配置的日志中间件
func LoggerWithConfig(cfg LoggerConfig) gin.HandlerFunc {
// 统一封顶：MaxBodyLength<=0 时回退默认值，确保请求/响应 body 捕获均有上限（防 OOM）
if cfg.MaxBodyLength <= 0 {
cfg.MaxBodyLength = DefaultLoggerConfig.MaxBodyLength
}
return func(c *gin.Context) {
// 检查是否跳过此路径
path := c.Request.URL.Path
if shouldSkipPath(path, cfg) {
c.Next()
return
}
start := time.Now()
// 记录请求体（可选）
var requestBody []byte
if cfg.LogRequestBody && c.Request.Body != nil {
requestBody = readBodyBounded(c, cfg.MaxBodyLength)
}
// 记录响应体（可选）
var responseBody []byte
if cfg.LogResponseBody {
// 使用 ResponseWriter 包装器捕获响应体（缓冲区封顶，防止大响应 OOM）
blw := &bodyLogWriter{body: bytes.NewBufferString(""), maxLen: cfg.MaxBodyLength, ResponseWriter: c.Writer}
c.Writer = blw
c.Next()
responseBody = blw.body.Bytes()
} else {
c.Next()
}
latency := time.Since(start)
// 构建日志字段
fields := []zap.Field{
zap.Int("status", c.Writer.Status()),
zap.String("method", c.Request.Method),
zap.String("path", path),
zap.String("query", filterSensitiveQuery(c.Request.URL.RawQuery)),
zap.String("ip", c.ClientIP()),
zap.Duration("latency", latency),
zap.String("user-agent", c.Request.UserAgent()),
zap.Int("body_size", c.Writer.Size()),
zap.String("request_id", GetRequestID(c)),
}
// 添加请求体
if cfg.LogRequestBody && len(requestBody) > 0 {
// 过滤敏感字段
safeBody := filterSensitiveFields(requestBody)
fields = append(fields, zap.String("request_body", safeBody))
}
// 添加响应体
if cfg.LogResponseBody && len(responseBody) > 0 {
fields = append(fields, zap.String("response_body", string(responseBody)))
}
// 添加用户信息（如果已登录）
userID := GetUserID(c)
if userID > 0 {
fields = append(fields,
zap.Uint("user_id", userID),
zap.String("username", GetUsername(c)),
zap.String("user_type", GetUserType(c)),
)
}
// 根据状态码和延迟选择日志级别
status := c.Writer.Status()
if latency > cfg.SlowRequestThreshold {
// 慢请求警告
fields = append(fields, zap.Bool("slow_request", true))
logger.APILog().Warn("慢请求", fields...)
} else if status >= 500 {
logger.APILog().Error("请求错误", fields...)
} else if status >= 400 {
logger.APILog().Warn("客户端请求错误", fields...)
} else {
logger.APILog().Info("API 请求", fields...)
}
}
}
// readBodyBounded 读取请求体用于日志记录，封顶 maxLen 字节以防 OOM。
//
// 仅向内存读入最多 maxLen+1 字节（+1 用于检测截断），其余部分不读入内存；
// 通过 io.MultiReader 把「已读前缀 + 原始 body 剩余」复原为 c.Request.Body，
// 因此下游处理器仍能拿到完整请求体。返回的日志副本截断为 maxLen。
func readBodyBounded(c *gin.Context, maxLen int) []byte {
if maxLen <= 0 {
maxLen = DefaultLoggerConfig.MaxBodyLength
}
// io.ReadAll 永远返回非 nil 切片（即使出错也带已读部分）。LimitReader 封顶至 maxLen+1 字节。
read, _ := io.ReadAll(io.LimitReader(c.Request.Body, int64(maxLen)+1))
// 复原完整请求体供后续处理：已读前缀 + 原始 body 剩余部分（出错时保留已读字节，下游可重试读取剩余）
c.Request.Body = io.NopCloser(io.MultiReader(bytes.NewReader(read), c.Request.Body))
// 日志副本截断到 maxLen
if len(read) > maxLen {
return read[:maxLen]
}
return read
}
// bodyLogWriter 响应体记录包装器
type bodyLogWriter struct {
gin.ResponseWriter
body *bytes.Buffer
maxLen int // 缓冲区上限（字节），<=0 表示不限制
}
// appendBounded 向缓冲区追加字节，但不超过 maxLen 上限，防止大响应 OOM。
func (w *bodyLogWriter) appendBounded(b []byte) {
if w.maxLen <= 0 {
w.body.Write(b)
return
}
remaining := w.maxLen - w.body.Len()
if remaining <= 0 {
return
}
if len(b) > remaining {
b = b[:remaining]
}
w.body.Write(b)
}
// Write 捕获响应体（缓冲区封顶，完整响应仍写入下游 ResponseWriter）
func (w *bodyLogWriter) Write(b []byte) (int, error) {
w.appendBounded(b)
return w.ResponseWriter.Write(b)
}
// WriteString 捕获字符串响应
func (w *bodyLogWriter) WriteString(s string) (int, error) {
w.appendBounded([]byte(s))
return w.ResponseWriter.WriteString(s)
}
// shouldSkipPath 检查是否跳过路径
func shouldSkipPath(path string, cfg LoggerConfig) bool {
// 检查完整路径
for _, p := range cfg.SkipPaths {
if path == p {
return true
}
}
// 检查路径前缀
for _, prefix := range cfg.SkipPathPrefixes {
if pathPrefixMatch(path, prefix) {
return true
}
}
return false
}
func pathPrefixMatch(path, prefix string) bool {
if prefix == "" {
return false
}
cleanPrefix := strings.TrimRight(prefix, "/")
if cleanPrefix == "" {
return path == "/"
}
return path == cleanPrefix || strings.HasPrefix(path, cleanPrefix+"/")
}
// filterSensitiveFields 过滤敏感字段（密码、token等）
// sensitiveFieldsRE M1 修复：编译期正则，匹配 "key":"value" 整体并将 value 替换为 [FILTERED]。
// 支持 JSON 字符串中标准转义（\" \\ \/ \b \f \n \r \t \uXXXX）。
var sensitiveFieldsRE = regexp.MustCompile(
`"(password|passwd|pwd|token|access_token|refresh_token|secret|api_key|apikey|credit_card|card_number)"\s*:\s*"((?:[^"\\]|\\.)*)"`,
)
// filterSensitiveFields M1 修复后实现：将敏感字段的值替换为 [FILTERED]，完整移除原始值。
// 对非 JSON 输入原样返回。
func filterSensitiveFields(body []byte) string {
return sensitiveFieldsRE.ReplaceAllString(string(body), `"$1":"[FILTERED]"`)
}
// sensitiveQueryKeys 需要在访问日志中脱敏的 query 参数名（小写匹配，P1 #14）。
// 与 sensitiveFieldsRE 覆盖的字段保持一致。
var sensitiveQueryKeys = map[string]struct{}{
"password": {}, "passwd": {}, "pwd": {}, "token": {},
"access_token": {}, "refresh_token": {}, "secret": {},
"api_key": {}, "apikey": {}, "credit_card": {}, "card_number": {},
}
// filterSensitiveQuery 脱敏 query 字符串中的敏感参数值（P1 #14）：
// 如 ?access_token=xxx 会被记为 access_token=%5BFILTERED%5D，防止令牌等随访问日志落盘。
// 无敏感键时原样返回（不重排）；解析失败时整体标记以免原文泄露。
func filterSensitiveQuery(rawQuery string) string {
if rawQuery == "" {
return ""
}
values, err := url.ParseQuery(rawQuery)
if err != nil {
return "[redacted: unparsable query]"
}
changed := false
for k := range values {
if _, ok := sensitiveQueryKeys[strings.ToLower(k)]; ok {
values[k] = []string{"[FILTERED]"}
changed = true
}
}
if !changed {
return rawQuery
}
return values.Encode()
}
// LoggerForAPI API 专用日志中间件（更详细）
func LoggerForAPI() gin.HandlerFunc {
cfg := DefaultLoggerConfig
cfg.LogRequestBody = true
cfg.LogResponseBody = false // 响应体通常较大
return LoggerWithConfig(cfg)
}
// LoggerForDebug 调试专用日志中间件（最详细）
func LoggerForDebug() gin.HandlerFunc {
cfg := LoggerConfig{
LogRequestBody: true,
LogResponseBody: true,
MaxBodyLength: 4096, // 4KB
SkipPaths: []string{"/health"},
SkipPathPrefixes: []string{},
SlowRequestThreshold: 200 * time.Millisecond,
}
return LoggerWithConfig(cfg)
}
// LoggerMinimal 最简日志中间件（只记录基本信息）
func LoggerMinimal() gin.HandlerFunc {
return func(c *gin.Context) {
path := c.Request.URL.Path
// 跳过健康检查和静态资源
if path == "/health" || pathPrefixMatch(path, "/public") || pathPrefixMatch(path, "/static") {
c.Next()
return
}
start := time.Now()
c.Next()
logger.APILog().Info("请求",
zap.Int("status", c.Writer.Status()),
zap.String("method", c.Request.Method),
zap.String("path", path),
zap.String("ip", c.ClientIP()),
zap.Duration("latency", time.Since(start)),
)
}
}
middleware/logger_internal_test.go
+275
View File
@@ -0,0 +1,275 @@
package middleware
import (
"bytes"
"io"
"net/http/httptest"
"strings"
"testing"
"time"
"github.com/gin-gonic/gin"
)
// newCtxWithBody 构造一个带请求体的 gin.Context，仅用于 logger 内部测试。
func newCtxWithBody(body []byte) *gin.Context {
req := httptest.NewRequest("POST", "/", bytes.NewReader(body))
c := &gin.Context{}
c.Request = req
return c
}
// TestReadBodyBounded_TruncatesLogCopy 复现 H3：日志副本必须封顶到 maxLen，
// 而不是把整个 body 读入内存后再截断（原 io.ReadAll 无上限 → OOM）。
func TestReadBodyBounded_TruncatesLogCopy(t *testing.T) {
cases := []struct {
name string
bodyLen int
maxLen int
}{
{"smaller_than_limit", 100, 1024},
{"equal_to_limit", 1024, 1024},
{"larger_than_limit", 100_000, 1024},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
body := bytes.Repeat([]byte("a"), tc.bodyLen)
c := newCtxWithBody(body)
got := readBodyBounded(c, tc.maxLen)
want := tc.bodyLen
if want > tc.maxLen {
want = tc.maxLen
}
if len(got) != want {
t.Fatalf("log copy len = %d, want %d (maxLen=%d, bodyLen=%d)", len(got), want, tc.maxLen, tc.bodyLen)
}
})
}
}
// TestReadBodyBounded_RestoresFullBody 是 H3 修复的闭环断言：
// 即使日志副本被截断，下游处理器仍必须能读到完整请求体（io.MultiReader 复原）。
func TestReadBodyBounded_RestoresFullBody(t *testing.T) {
const maxLen = 64
body := []byte(strings.Repeat("ABCDEFGH", 1000)) // 8000 字节，远超 maxLen
c := newCtxWithBody(body)
logCopy := readBodyBounded(c, maxLen)
// 日志副本封顶
if len(logCopy) != maxLen {
t.Fatalf("log copy len = %d, want %d", len(logCopy), maxLen)
}
// 下游必须拿到完整原始 body
restored, err := io.ReadAll(c.Request.Body)
if err != nil {
t.Fatalf("read restored body: %v", err)
}
if !bytes.Equal(restored, body) {
t.Fatalf("downstream body corrupted: got len=%d, want len=%d", len(restored), len(body))
}
}
// TestReadBodyBounded_PreservesSmallBodyExactly 小于上限时日志副本与原始一致。
func TestReadBodyBounded_PreservesSmallBodyExactly(t *testing.T) {
body := []byte(`{"user":"alice","password":"secret"}`)
c := newCtxWithBody(body)
got := readBodyBounded(c, 1024)
if !bytes.Equal(got, body) {
t.Fatalf("log copy = %q, want %q", got, body)
}
restored, _ := io.ReadAll(c.Request.Body)
if !bytes.Equal(restored, body) {
t.Fatalf("downstream body = %q, want %q", restored, body)
}
}
// TestBodyLogWriter_Bounded 复现 H3 响应侧：响应体捕获缓冲区必须封顶，
// 完整响应仍写入下游 ResponseWriter。
func TestBodyLogWriter_Bounded(t *testing.T) {
gin.SetMode(gin.TestMode)
const maxLen = 32
rec := httptest.NewRecorder()
c, _ := gin.CreateTestContext(rec)
w := &bodyLogWriter{
ResponseWriter: c.Writer,
body: new(bytes.Buffer),
maxLen: maxLen,
}
large := bytes.Repeat([]byte("Z"), 10_000)
n, err := w.Write(large)
if err != nil {
t.Fatalf("write: %v", err)
}
if n != len(large) {
t.Fatalf("Write returned %d, want %d (下游必须收到完整响应)", n, len(large))
}
if w.body.Len() > maxLen {
t.Fatalf("captured buffer len = %d, must be <= %d (OOM 防护失效)", w.body.Len(), maxLen)
}
if w.body.Len() != maxLen {
t.Fatalf("captured buffer len = %d, want exactly %d", w.body.Len(), maxLen)
}
// 下游 ResponseWriter 收到完整内容
if rec.Body.Len() != len(large) {
t.Fatalf("downstream response len = %d, want %d", rec.Body.Len(), len(large))
}
}
// TestBodyLogWriter_NoLimit maxLen<=0 时不限制（向后兼容）。
func TestBodyLogWriter_NoLimit(t *testing.T) {
gin.SetMode(gin.TestMode)
rec := httptest.NewRecorder()
c, _ := gin.CreateTestContext(rec)
w := &bodyLogWriter{
ResponseWriter: c.Writer,
body: new(bytes.Buffer),
maxLen: 0,
}
data := []byte("hello world")
if _, err := w.Write(data); err != nil {
t.Fatalf("write: %v", err)
}
if !bytes.Equal(w.body.Bytes(), data) {
t.Fatalf("captured = %q, want %q", w.body.Bytes(), data)
}
}
// TestBodyLogWriter_MultiWriteAccumulation 多次小写累积不超过 maxLen，
// 下游仍收到完整拼接结果。
func TestBodyLogWriter_MultiWriteAccumulation(t *testing.T) {
gin.SetMode(gin.TestMode)
const maxLen = 32
rec := httptest.NewRecorder()
c, _ := gin.CreateTestContext(rec)
w := &bodyLogWriter{
ResponseWriter: c.Writer,
body: new(bytes.Buffer),
maxLen: maxLen,
}
chunks := [][]byte{[]byte("0123456789"), []byte("abcdefghij"), []byte("ABCDEFGHIJ"), []byte("zzzzzzzzzz")}
var downstream bytes.Buffer
for _, ch := range chunks {
n, err := w.Write(ch)
if err != nil || n != len(ch) {
t.Fatalf("Write chunk %q: n=%d err=%v", ch, n, err)
}
downstream.Write(ch)
}
if w.body.Len() > maxLen {
t.Fatalf("captured len = %d, must be <= %d", w.body.Len(), maxLen)
}
if w.body.Len() != maxLen {
t.Fatalf("captured len = %d, want exactly %d", w.body.Len(), maxLen)
}
if !bytes.Equal(rec.Body.Bytes(), downstream.Bytes()) {
t.Fatalf("downstream = %q, want %q", rec.Body.Bytes(), downstream.Bytes())
}
}
// TestBodyLogWriter_WriteStringBounded WriteString 路径同样封顶。
func TestBodyLogWriter_WriteStringBounded(t *testing.T) {
gin.SetMode(gin.TestMode)
const maxLen = 16
rec := httptest.NewRecorder()
c, _ := gin.CreateTestContext(rec)
w := &bodyLogWriter{
ResponseWriter: c.Writer,
body: new(bytes.Buffer),
maxLen: maxLen,
}
large := strings.Repeat("S", 500)
n, err := w.WriteString(large)
if err != nil {
t.Fatalf("WriteString: %v", err)
}
if n != len(large) {
t.Fatalf("WriteString returned %d, want %d", n, len(large))
}
if w.body.Len() > maxLen {
t.Fatalf("captured len = %d, must be <= %d", w.body.Len(), maxLen)
}
if rec.Body.Len() != len(large) {
t.Fatalf("downstream len = %d, want %d", rec.Body.Len(), len(large))
}
}
// TestFilterSensitiveQuery P1 #14：query 中的敏感参数值必须脱敏，非敏感原样保留。
func TestFilterSensitiveQuery(t *testing.T) {
cases := []struct {
name string
in string
contains string // 期望结果包含
absent string // 期望结果不含（敏感原值）
}{
{"empty", "", "", ""},
{"no sensitive", "page=1&size=20", "page=1", ""},
{"access_token redacted", "access_token=supersecret123&page=1", "FILTERED", "supersecret123"},
{"password redacted", "user=alice&password=hunter2", "FILTERED", "hunter2"},
{"case insensitive key", "Token=abc.def.ghi", "FILTERED", "abc.def.ghi"},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
got := filterSensitiveQuery(tc.in)
if tc.contains != "" && !strings.Contains(got, tc.contains) {
t.Errorf("filterSensitiveQuery(%q) = %q, want contains %q", tc.in, got, tc.contains)
}
if tc.absent != "" && strings.Contains(got, tc.absent) {
t.Errorf("filterSensitiveQuery(%q) = %q, must NOT contain sensitive value %q", tc.in, got, tc.absent)
}
})
}
}
// TestLoggerWithConfig_NormalizesMaxBodyLength MaxBodyLength<=0 时归一化为默认值，
// 确保响应侧捕获缓冲区仍有上限（H3 复审 MEDIUM：消除请求/响应侧 maxLen<=0 不对称）。
func TestLoggerWithConfig_NormalizesMaxBodyLength(t *testing.T) {
gin.SetMode(gin.TestMode)
r := gin.New()
cfg := LoggerConfig{
LogRequestBody: true,
LogResponseBody: true,
MaxBodyLength: 0, // 手滑置 0，应被归一化为默认 1024
SkipPaths: []string{},
SkipPathPrefixes: []string{},
SlowRequestThreshold: 500 * time.Millisecond,
}
r.Use(LoggerWithConfig(cfg))
r.POST("/", func(c *gin.Context) {
body, _ := io.ReadAll(c.Request.Body)
c.Data(200, "text/plain", body)
})
// 请求体 5000 字节（> 默认 1024），下游应仍得完整 body
reqBody := bytes.Repeat([]byte("a"), 5000)
w := httptest.NewRecorder()
req := httptest.NewRequest("POST", "/", bytes.NewReader(reqBody))
r.ServeHTTP(w, req)
if w.Body.Len() != len(reqBody) {
t.Fatalf("downstream body len = %d, want %d (请求体必须完整复原)", w.Body.Len(), len(reqBody))
}
if !bytes.Equal(w.Body.Bytes(), reqBody) {
t.Fatalf("downstream body corrupted")
}
}
func TestLoggerSkipPathPrefixesAnchorsBoundary_M8(t *testing.T) {
cfg := LoggerConfig{SkipPathPrefixes: []string{"/api"}}
if !shouldSkipPath("/api", cfg) {
t.Fatal("/api should be skipped")
}
if !shouldSkipPath("/api/users", cfg) {
t.Fatal("/api/users should be skipped")
}
if shouldSkipPath("/api2/users", cfg) {
t.Fatal("/api2/users should not be skipped by /api prefix")
}
}
middleware/metrics.go
+64
View File
@@ -0,0 +1,64 @@
package middleware
import (
"strconv"
"time"
"github.com/gin-gonic/gin"
"github.com/prometheus/client_golang/prometheus"
"github.com/prometheus/client_golang/prometheus/promauto"
)
// #18 Prometheus 指标。三个标配：
// - http_requests_total: 请求计数（按 method/route/status 维度）
// - http_request_duration_seconds: 请求耗时直方图（按 method/route 维度）
// - http_requests_in_flight: 当前在飞请求数
var (
httpRequestsTotal = promauto.NewCounterVec(
prometheus.CounterOpts{
Name: "http_requests_total",
Help: "HTTP 请求总数。",
},
[]string{"method", "route", "status"},
)
httpRequestDuration = promauto.NewHistogramVec(
prometheus.HistogramOpts{
Name: "http_request_duration_seconds",
Help: "HTTP 请求耗时（秒）。",
Buckets: prometheus.DefBuckets,
},
[]string{"method", "route"},
)
httpRequestsInFlight = promauto.NewGauge(
prometheus.GaugeOpts{
Name: "http_requests_in_flight",
Help: "正在处理的 HTTP 请求数。",
},
)
)
// Metrics Prometheus 指标中间件（#18）。记录请求计数、耗时、在飞数。
// route 标签用 c.FullPath()（路由模板，如 /api/v1/users/:id），避免高基数。
func Metrics() gin.HandlerFunc {
return func(c *gin.Context) {
httpRequestsInFlight.Inc()
defer httpRequestsInFlight.Dec() // M2 修复：defer 保证 panic 时也递减，不依赖 Recover 中间件顺序
start := time.Now()
c.Next()
elapsed := time.Since(start).Seconds()
status := strconv.Itoa(c.Writer.Status())
route := c.FullPath()
if route == "" {
route = "not_found"
}
method := c.Request.Method
httpRequestsTotal.WithLabelValues(method, route, status).Inc()
httpRequestDuration.WithLabelValues(method, route).Observe(elapsed)
}
}
middleware/middleware_test.go
+1548
View File
File diff suppressed because it is too large Load Diff
middleware/ratelimit.go
+654
View File
@@ -0,0 +1,654 @@
package middleware
import (
"context"
"errors"
"fmt"
"net/http"
"sync"
"sync/atomic"
"time"
"github.com/EthanCodeCraft/xlgo-core/database"
"github.com/EthanCodeCraft/xlgo-core/response"
"github.com/gin-gonic/gin"
"github.com/redis/go-redis/v9"
)
// RateLimiter 速率限制器（内存版，单实例使用）
type RateLimiter struct {
visitors map[string]*visitor
mu sync.RWMutex
rate int // 每分钟允许的请求数
window time.Duration // 时间窗口
ctx context.Context
cancel context.CancelFunc
wg sync.WaitGroup
nowFunc func() time.Time // 时间源（默认 time.Now，测试可注入可控时钟）
}
type visitor struct {
// windowStart 当前固定窗口的起点。仅在新窗口开始时设置，放行时不变更（H4a 修复）。
// 旧实现每次放行都更新 lastSeen，导致 time.Since(lastSeen) > window 重置分支对持续
// 客户端永不成立、count 单调累加，稳态客户端（低于 rate）被误限流。
windowStart time.Time
count int
}
// NewRateLimiter 创建速率限制器（内存版）。
// rate<=0 或 window<=0 时 panic。内部启动 cleanup goroutine，调用方负责在不再使用时
// 调用 (*RateLimiter).Stop 释放，否则 goroutine 泄漏。
func NewRateLimiter(rate int, window time.Duration) *RateLimiter {
mustValidRateLimit(rate, window)
ctx, cancel := context.WithCancel(context.Background())
limiter := &RateLimiter{
visitors: make(map[string]*visitor),
rate: rate,
window: window,
ctx: ctx,
cancel: cancel,
nowFunc: time.Now,
}
limiter.wg.Add(1)
go limiter.cleanupVisitors()
return limiter
}
func mustValidRateLimit(rate int, window time.Duration) {
if rate <= 0 {
panic("rate limiter: rate must be positive")
}
if window <= 0 {
panic("rate limiter: window must be positive")
}
}
// now 返回当前时间（可被测试注入 nowFunc 覆盖）。
func (rl *RateLimiter) now() time.Time {
if rl.nowFunc != nil {
return rl.nowFunc()
}
return time.Now()
}
// SetNowFunc 注入时间源（默认 time.Now），供测试用可控时钟验证窗口语义。
// 生产代码通常无需调用。
func (rl *RateLimiter) SetNowFunc(f func() time.Time) {
rl.mu.Lock()
rl.nowFunc = f
rl.mu.Unlock()
}
// Allow 检查是否允许请求。
//
// 固定窗口语义（H4a 修复）：windowStart 是当前窗口起点，仅在窗口过期重置时变更；
// 放行时不再更新 windowStart。窗口内 count 达到 rate 即拒绝，窗口过期则重置为新窗口。
// 旧实现每次放行更新 lastSeen，致重置分支对持续客户端永不成立、稳态客户端被误限流。
//
// 注意：固定窗口算法允许窗口边界突发（两窗口交界处瞬时可达 2×rate）。
// 如需平滑限流（无突发），请用 Redis 版 RedisRateLimiter（滑动窗口）。
func (rl *RateLimiter) Allow(ip string) bool {
rl.mu.Lock()
defer rl.mu.Unlock()
now := rl.now()
v, exists := rl.visitors[ip]
if !exists {
rl.visitors[ip] = &visitor{
windowStart: now,
count: 1,
}
return true
}
// 窗口过期：开新窗口，count 重置为 1。
if now.Sub(v.windowStart) > rl.window {
v.windowStart = now
v.count = 1
return true
}
// 当前窗口内已达上限：拒绝（不更新 windowStart）。
if v.count >= rl.rate {
return false
}
// 放行：count++，windowStart 不变（固定窗口语义）。
v.count++
return true
}
// cleanupVisitors 清理过期的访问者记录
func (rl *RateLimiter) cleanupVisitors() {
defer rl.wg.Done()
ticker := time.NewTicker(time.Minute)
defer ticker.Stop()
for {
select {
case <-rl.ctx.Done():
return
case <-ticker.C:
rl.mu.Lock()
for ip, v := range rl.visitors {
// 窗口起点超 window 未活跃即淘汰（H4a：windowStart 是窗口起点，不再被放行更新）。
if rl.now().Sub(v.windowStart) > rl.window {
delete(rl.visitors, ip)
}
}
rl.mu.Unlock()
}
}
}
// Stop 停止限流器（释放资源）
func (rl *RateLimiter) Stop() {
rl.cancel()
rl.wg.Wait()
}
// ===== Redis 分布式限流器 =====
// H4c: Redis 限流器故障相关错误。
var (
// ErrRedisRateLimiterUnavailable Redis 未启用（database.GetRedis() == nil）。
// fail-closed 限流器在此情况下拒绝请求；fail-open 限流器放行。
ErrRedisRateLimiterUnavailable = errors.New("redis rate limiter: redis client unavailable")
// ErrRedisRateLimiterUnexpectedResult Redis 返回非预期的结果类型（非 int64）。
// fail-closed 限流器拒绝；fail-open 限流器放行。旧实现裸断言会 panic。
ErrRedisRateLimiterUnexpectedResult = errors.New("redis rate limiter: unexpected result type")
)
// RedisRateLimiter Redis 分布式限流器
type RedisRateLimiter struct {
keyPrefix string // 键名前缀
rate int // 每分钟允许的请求数
window time.Duration // 时间窗口
failClosed atomic.Bool // H4c/H-6: Redis 错误/断言失败时是否拒绝（true=安全型 fail-closed）。atomic 以支持运行期 SetFailClosed 并发安全切换。
client *redis.Client // Phase 5: 注入的 redis client（nil 回退 database.GetRedis()，照 jwt.TokenBlacklist 模型）。App 经 WithRedisClient 注入 per-App client 实现隔离。
}
// slidingWindowLua 滑动窗口限流 Lua 脚本
// 返回: 当前窗口内的请求数
const slidingWindowLua = `
local key = KEYS[1]
local now = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local rate = tonumber(ARGV[3])
-- 移除窗口外的旧记录
redis.call('ZREMRANGEBYSCORE', key, 0, now - window)
-- 获取当前窗口内的请求数
local count = redis.call('ZCARD', key)
if count < rate then
-- 添加当前请求
redis.call('ZADD', key, now, now .. '-' .. math.random())
redis.call('PEXPIRE', key, window)
return 0
else
return count
end
`
// RedisRateLimiterOption 配置 RedisRateLimiter 的可选策略。
type RedisRateLimiterOption func(*RedisRateLimiter)
// WithFailClosed 设置 Redis 故障时 fail-closed（拒绝请求）。
// 不传或传 false 为 fail-open（放行，兼容默认）。安全敏感场景（登录防爆破等）应传 true。
func WithFailClosed(failClosed bool) RedisRateLimiterOption {
return func(rl *RedisRateLimiter) {
rl.failClosed.Store(failClosed)
}
}
// WithRedisClient 注入指定 Redis 客户端（Phase 5，多 Redis/测试隔离）。
// 不传则回退 database.GetRedis()（全局）。App 可经 app.RedisClient() 取自身 client 注入。
func WithRedisClient(client *redis.Client) RedisRateLimiterOption {
return func(rl *RedisRateLimiter) {
rl.client = client
}
}
// NewRedisRateLimiter 创建 Redis 分布式限流器。
// 默认 fail-open（Redis 故障时放行，避免影响业务）；安全敏感场景传 WithFailClosed(true)。
func NewRedisRateLimiter(keyPrefix string, rate int, window time.Duration, opts ...RedisRateLimiterOption) *RedisRateLimiter {
mustValidRateLimit(rate, window)
rl := &RedisRateLimiter{
keyPrefix: keyPrefix,
rate: rate,
window: window,
// failClosed 零值 false（fail-open，兼容默认）
}
for _, opt := range opts {
if opt != nil {
opt(rl)
}
}
return rl
}
// SetFailClosed 设置 Redis 故障时的策略：true=拒绝（安全型），false=放行（兼容默认）。
// 供已创建的限流器切换策略。并发安全（atomic.Store），可与并发 Allow 调用共存。
func (rl *RedisRateLimiter) SetFailClosed(failClosed bool) {
rl.failClosed.Store(failClosed)
}
// redisClient 返回注入的 redis client，未注入则回退 database.GetRedis()（jwt 模型）。
// M-C 教训：取一次复用，避免 nil 检查与 Eval 各调一次 GetRedis() 之间的 CloseRedis 竞态。
func (rl *RedisRateLimiter) redisClient() *redis.Client {
if rl != nil && rl.client != nil {
return rl.client
}
return database.GetRedis()
}
// Allow 检查是否允许请求。
//
// H4c 修复：
// - result.(int64) 改 comma-ok，断言失败返 ErrRedisRateLimiterUnexpectedResult 而非 panic。
// - Redis 错误/断言失败时按 failClosed 策略决定：fail-closed 返 (false, err) 拒绝，
// fail-open 返 (true, err) 放行（兼容旧行为）。中间件层据此 allowed 值决定放行/拒绝，
// 不再无条件 fail-open--登录防爆破等安全场景用 fail-closed 限流器即可在 Redis 故障时拒绝。
//
// Redis 未启用（redisClient() == nil）时：fail-closed 返 (false, ErrRedisRateLimiterUnavailable)，
// fail-open 返 (true, nil)（兼容旧行为）。安全场景必须确保 Redis 已启用。
//
// Phase 5：redisClient() 注入优先、全局兜底，App 经 WithRedisClient 注入 per-App client。
func (rl *RedisRateLimiter) Allow(ctx context.Context, identifier string) (bool, error) {
// M-C 修复：取一次复用。原实现 nil 检查与 Eval 各调一次 GetRedis()，
// 两次之间若 CloseRedis，第二次返回 nil -> nil.Eval panic。
rdb := rl.redisClient()
if rdb == nil {
if rl.failClosed.Load() {
return false, ErrRedisRateLimiterUnavailable
}
return true, nil
}
key := rl.keyPrefix + ":" + identifier
now := float64(time.Now().UnixMilli())
windowMs := float64(rl.window.Milliseconds())
result, err := rdb.Eval(ctx, slidingWindowLua, []string{key}, now, windowMs, rl.rate).Result()
if err != nil {
if rl.failClosed.Load() {
return false, err
}
return true, err // 出错时允许请求，避免影响业务（兼容旧行为）
}
// H4c: comma-ok 断言，避免 Redis 返回非 int64 时 panic。
count, ok := result.(int64)
if !ok {
if rl.failClosed.Load() {
return false, ErrRedisRateLimiterUnexpectedResult
}
return true, ErrRedisRateLimiterUnexpectedResult
}
return count == 0, nil
}
// GetCount 获取当前窗口内的请求数
func (rl *RedisRateLimiter) GetCount(ctx context.Context, identifier string) (int64, error) {
// M-C 修复（Phase 5：改 redisClient）：取一次复用（原三次调用存在 nil-deref 窗口）。
rdb := rl.redisClient()
if rdb == nil {
return 0, nil
}
key := rl.keyPrefix + ":" + identifier
now := time.Now().UnixMilli()
windowStart := now - rl.window.Milliseconds()
// 移除旧记录并获取当前计数
rdb.ZRemRangeByScore(ctx, key, "0", fmt.Sprintf("%d", windowStart))
return rdb.ZCard(ctx, key).Result()
}
// Reset 重置限流计数
func (rl *RedisRateLimiter) Reset(ctx context.Context, identifier string) error {
// M-C 修复（Phase 5：改 redisClient）：取一次复用（原两次调用存在 nil-deref 窗口）。
rdb := rl.redisClient()
if rdb == nil {
return nil
}
key := rl.keyPrefix + ":" + identifier
return rdb.Del(ctx, key).Err()
}
// ===== 全局限速器 Registry（Phase 5 实例化） =====
//
// 内存限流器（RateLimiter）持 cleanup goroutine，进程级共享会在多 App 下互相污染
// （App A Shutdown 经 StopRateLimiters 把 App B 的 loginLimiter 也停了）。故照
// cache.CacheManager / cron.Scheduler 模式引入 RateLimitRegistry：实例化 + 全局默认
// + 包级 facade 代理，App 持自己的 Registry。
//
// 包级 LoginRateLimit() 等改为"请求时解析当前默认 Registry"懒创建限流器，使 App.Init
// swap 后请求落到 App 的 Registry（避免 pre-Init 注册到 init Registry 被 swap 丢弃）。
// RateLimitRegistry 持一组内存限流器，支持 per-App 隔离。
type RateLimitRegistry struct {
mu sync.Mutex
loginLimiter *RateLimiter
apiLimiter *RateLimiter
uploadLimiter *RateLimiter
customLimiters []*RateLimiter
}
// NewRateLimitRegistry 创建限流器注册表实例。
func NewRateLimitRegistry() *RateLimitRegistry {
return &RateLimitRegistry{}
}
func (r *RateLimitRegistry) loginLimiterInstance() *RateLimiter {
r.mu.Lock()
defer r.mu.Unlock()
if r.loginLimiter == nil {
r.loginLimiter = NewRateLimiter(10, time.Minute)
}
return r.loginLimiter
}
func (r *RateLimitRegistry) apiLimiterInstance() *RateLimiter {
r.mu.Lock()
defer r.mu.Unlock()
if r.apiLimiter == nil {
r.apiLimiter = NewRateLimiter(100, time.Minute)
}
return r.apiLimiter
}
func (r *RateLimitRegistry) uploadLimiterInstance() *RateLimiter {
r.mu.Lock()
defer r.mu.Unlock()
if r.uploadLimiter == nil {
r.uploadLimiter = NewRateLimiter(20, time.Minute)
}
return r.uploadLimiter
}
// registerCustom 登记自定义限流器供 Stop 统一停止（H4b）。
func (r *RateLimitRegistry) registerCustom(l *RateLimiter) {
r.mu.Lock()
r.customLimiters = append(r.customLimiters, l)
r.mu.Unlock()
}
// Init 预初始化标准限流器（可选；不调则首次请求时懒创建）。先停旧的同名限流器释放 goroutine。
func (r *RateLimitRegistry) Init() {
r.mu.Lock()
defer r.mu.Unlock()
if r.loginLimiter != nil {
r.loginLimiter.Stop()
}
if r.apiLimiter != nil {
r.apiLimiter.Stop()
}
if r.uploadLimiter != nil {
r.uploadLimiter.Stop()
}
r.loginLimiter = NewRateLimiter(10, time.Minute)
r.apiLimiter = NewRateLimiter(100, time.Minute)
r.uploadLimiter = NewRateLimiter(20, time.Minute)
}
// Stop 停止注册表中所有限流器（释放 cleanup goroutine）。幂等。
func (r *RateLimitRegistry) Stop() {
r.mu.Lock()
defer r.mu.Unlock()
if r.loginLimiter != nil {
r.loginLimiter.Stop()
r.loginLimiter = nil
}
if r.apiLimiter != nil {
r.apiLimiter.Stop()
r.apiLimiter = nil
}
if r.uploadLimiter != nil {
r.uploadLimiter.Stop()
r.uploadLimiter = nil
}
for _, l := range r.customLimiters {
l.Stop()
}
r.customLimiters = nil
}
// --- App-bound 中间件（捕获此 Registry，不查全局默认，多 App per-App 隔离） ---
//
// 与包级 LoginRateLimit() 等的区别：包级在请求时查 GetDefaultRateLimitRegistry()（多 App 下
// 仅最后 Init 的 App 是全局默认，故包级 facade 不提供 per-App 计数隔离）；本组方法捕获 r，
// 始终用此 Registry 的 limiter。多 App 场景用 app.RateLimitRegistry().LoginRateLimit() 装配路由。
// LoginRateLimit 返回绑定到此 Registry 的登录限流中间件。
func (r *RateLimitRegistry) LoginRateLimit() gin.HandlerFunc {
return func(c *gin.Context) {
rateLimitAllow(c, r.loginLimiterInstance())
}
}
// APIRateLimit 返回绑定到此 Registry 的普通 API 限流中间件。
func (r *RateLimitRegistry) APIRateLimit() gin.HandlerFunc {
return func(c *gin.Context) {
rateLimitAllow(c, r.apiLimiterInstance())
}
}
// UploadRateLimit 返回绑定到此 Registry 的上传限流中间件。
func (r *RateLimitRegistry) UploadRateLimit() gin.HandlerFunc {
return func(c *gin.Context) {
rateLimitAllow(c, r.uploadLimiterInstance())
}
}
// CustomRateLimit 返回绑定到此 Registry 的自定义限流中间件。limiter 在首次请求时创建并
// 登记到此 Registry（r.registerCustom），由 App.Shutdown 的 registry.Stop() 收口，无泄漏。
func (r *RateLimitRegistry) CustomRateLimit(rate int, window time.Duration) gin.HandlerFunc {
var (
once sync.Once
limiter *RateLimiter
)
return func(c *gin.Context) {
once.Do(func() {
limiter = NewRateLimiter(rate, window)
r.registerCustom(limiter)
})
rateLimitAllow(c, limiter)
}
}
// defaultRateLimitRegistry 全局默认 Registry（atomic，照 cache/cron 模式）。
var defaultRateLimitRegistry atomic.Pointer[RateLimitRegistry]
func init() {
defaultRateLimitRegistry.Store(NewRateLimitRegistry())
}
// GetDefaultRateLimitRegistry 返回全局默认 Registry。
func GetDefaultRateLimitRegistry() *RateLimitRegistry {
return defaultRateLimitRegistry.Load()
}
// SwapDefaultRateLimitRegistry 置为全局默认，返回被替换的旧（照 Swap 模式）。nil 忽略，返回当前默认。
func SwapDefaultRateLimitRegistry(r *RateLimitRegistry) *RateLimitRegistry {
if r == nil {
return defaultRateLimitRegistry.Load()
}
return defaultRateLimitRegistry.Swap(r)
}
// rateLimitAllow 公共放行/拒绝逻辑（内存版）。
func rateLimitAllow(c *gin.Context, rl *RateLimiter) {
if rl == nil {
response.Custom(c, http.StatusServiceUnavailable, response.CodeServiceUnavailable,
"限流器未初始化", nil)
c.Abort()
return
}
if !rl.Allow(c.ClientIP()) {
response.RateLimit(c)
c.Abort()
return
}
c.Next()
}
// RateLimit 通用速率限制中间件（内存版，用户自持 limiter 时使用）。
func RateLimit(limiter *RateLimiter) gin.HandlerFunc {
return func(c *gin.Context) {
rateLimitAllow(c, limiter)
}
}
// LoginRateLimit 登录接口速率限制。限流器在首次请求时从当前默认 Registry 懒创建，
// 故 App.Init swap 后用的是 App 的 Registry（避免 pre-Init 注册到 init Registry 被丢弃）。
func LoginRateLimit() gin.HandlerFunc {
return func(c *gin.Context) {
rateLimitAllow(c, GetDefaultRateLimitRegistry().loginLimiterInstance())
}
}
// APIRateLimit 普通 API 速率限制。
func APIRateLimit() gin.HandlerFunc {
return func(c *gin.Context) {
rateLimitAllow(c, GetDefaultRateLimitRegistry().apiLimiterInstance())
}
}
// UploadRateLimit 上传接口速率限制。
func UploadRateLimit() gin.HandlerFunc {
return func(c *gin.Context) {
rateLimitAllow(c, GetDefaultRateLimitRegistry().uploadLimiterInstance())
}
}
// CustomRateLimit 自定义速率限制（内存版）。限流器在首次请求时创建并登记到当前默认
// Registry（供 Stop 统一停止，避免 cleanup goroutine 泄漏，H4b）。
func CustomRateLimit(rate int, window time.Duration) gin.HandlerFunc {
var (
once sync.Once
limiter *RateLimiter
)
return func(c *gin.Context) {
once.Do(func() {
limiter = NewRateLimiter(rate, window)
GetDefaultRateLimitRegistry().registerCustom(limiter)
})
rateLimitAllow(c, limiter)
}
}
// InitRateLimiters 初始化默认 Registry 的标准限流器（可选，不调则懒创建）。
func InitRateLimiters() {
GetDefaultRateLimitRegistry().Init()
}
// StopRateLimiters 停止默认 Registry 的所有限流器。注意：仅停默认 Registry--
// App 持自己的 Registry 时应在 Shutdown 调 app 自己的 Stop（Phase 5）。
func StopRateLimiters() {
GetDefaultRateLimitRegistry().Stop()
}
// ===== Redis 分布式限流中间件 =====
// redisLimitDecision 处理 RedisRateLimiter.Allow 的结果，按 allowed 值决定放行/拒绝。
//
// H4c: 不再无条件 fail-open。Allow 已按 limiter 的 failClosed 策略把 Redis 故障翻成
// allowed 值--fail-closed 时 allowed=false（拒绝），fail-open 时 allowed=true（放行）。
// 故 err 与 allowed 的组合语义：
// - err==nil, allowed==true -> 放行
// - err==nil, allowed==false -> 真超限，返 429（response.RateLimit）
// - err!=nil, allowed==false -> fail-closed 限流器在 Redis 故障下拒绝，返 503（服务不可用）
// - err!=nil, allowed==true -> fail-open 限流器在 Redis 故障下放行（兼容旧行为）
func redisLimitDecision(c *gin.Context, allowed bool, err error) {
if err != nil && !allowed {
// fail-closed：Redis 故障时拒绝（防限流静默失效）。返 503 区别于真实超限的 429。
response.Custom(c, http.StatusServiceUnavailable, response.CodeServiceUnavailable,
"限流服务暂时不可用", nil)
c.Abort()
return
}
if !allowed {
response.RateLimit(c)
c.Abort()
return
}
c.Next()
}
// RedisRateLimit Redis 分布式限流中间件。
// 默认 fail-open（Redis 故障时放行，避免影响业务）；安全敏感场景（登录防爆破等）
// 传 WithFailClosed(true)，Redis 故障时拒绝以防限流失效。
func RedisRateLimit(keyPrefix string, rate int, opts ...RedisRateLimiterOption) gin.HandlerFunc {
limiter := NewRedisRateLimiter(keyPrefix, rate, time.Minute, opts...)
return func(c *gin.Context) {
identifier := c.ClientIP()
// 可选：使用用户ID作为标识（登录后）
// userID := GetUserID(c)
// if userID > 0 {
// identifier = fmt.Sprintf("user:%d", userID)
// }
allowed, err := limiter.Allow(c.Request.Context(), identifier)
redisLimitDecision(c, allowed, err)
}
}
// RedisRateLimitWithIdentifier 自定义标识的 Redis 分布式限流。
// 参数: keyPrefix 键名前缀，rate 1 分钟窗口内允许的请求数，identifierFunc 标识获取函数。
// identifierFunc 为 nil 或返回空串时回退到 c.ClientIP()。默认 fail-open，传 WithFailClosed(true) 切换。
func RedisRateLimitWithIdentifier(keyPrefix string, rate int, identifierFunc func(c *gin.Context) string, opts ...RedisRateLimiterOption) gin.HandlerFunc {
limiter := NewRedisRateLimiter(keyPrefix, rate, time.Minute, opts...)
return func(c *gin.Context) {
identifier := ""
if identifierFunc != nil {
identifier = identifierFunc(c)
}
if identifier == "" {
identifier = c.ClientIP()
}
allowed, err := limiter.Allow(c.Request.Context(), identifier)
redisLimitDecision(c, allowed, err)
}
}
// LoginRedisRateLimit 登录接口 Redis 分布式限流（fail-closed）。
//
// H4c: 登录防爆破场景必须 fail-closed--Redis 故障时若 fail-open 则限流失效、
// 攻击者可借 Redis 抖动窗口无限爆破。改为 fail-closed：Redis 故障时返 503 拒绝。
func LoginRedisRateLimit() gin.HandlerFunc {
return RedisRateLimit("login_limit", 10, WithFailClosed(true))
}
// APIRedisRateLimit API Redis 分布式限流（fail-open，避免影响业务）。
func APIRedisRateLimit() gin.HandlerFunc {
return RedisRateLimit("api_limit", 100)
}
// UploadRedisRateLimit 上传接口 Redis 分布式限流（fail-closed）。
// 上传属资源敏感操作，Redis 故障时拒绝以防限流静默失效。
func UploadRedisRateLimit() gin.HandlerFunc {
return RedisRateLimit("upload_limit", 20, WithFailClosed(true))
}
// CustomRedisRateLimit 自定义 Redis 分布式限流。
// 默认 fail-open，传 WithFailClosed(true) 切换为 fail-closed。
func CustomRedisRateLimit(keyPrefix string, rate int, window time.Duration, opts ...RedisRateLimiterOption) gin.HandlerFunc {
limiter := NewRedisRateLimiter(keyPrefix, rate, window, opts...)
return func(c *gin.Context) {
identifier := c.ClientIP()
allowed, err := limiter.Allow(c.Request.Context(), identifier)
redisLimitDecision(c, allowed, err)
}
}
middleware/ratelimit_phase5_internal_test.go
+96
View File
@@ -0,0 +1,96 @@
package middleware
import (
"testing"
"time"
"github.com/EthanCodeCraft/xlgo-core/database"
"github.com/alicebob/miniredis/v2"
"github.com/redis/go-redis/v9"
)
// TestRedisRateLimiterInjectedClientPriority 固化 Phase 5（jwt 模型）：
// RedisRateLimiter.redisClient() 注入优先、全局兜底。
func TestRedisRateLimiterInjectedClientPriority(t *testing.T) {
mrG := miniredis.RunT(t)
clientG := redis.NewClient(&redis.Options{Addr: mrG.Addr()})
t.Cleanup(func() { _ = clientG.Close() })
origGlobal := database.SetTestRedisClient(clientG)
t.Cleanup(func() { database.SetTestRedisClient(origGlobal) })
mrA := miniredis.RunT(t)
clientA := redis.NewClient(&redis.Options{Addr: mrA.Addr()})
t.Cleanup(func() { _ = clientA.Close() })
// 注入优先
rl := NewRedisRateLimiter("test", 10, time.Minute, WithRedisClient(clientA))
if got := rl.redisClient(); got != clientA {
t.Fatalf("injected redisClient() = %v, want clientA", got)
}
// 未注入 -> 全局兜底
rl2 := NewRedisRateLimiter("test", 10, time.Minute)
if got := rl2.redisClient(); got != clientG {
t.Fatalf("fallback redisClient() = %v, want clientG (global)", got)
}
}
// TestSwapDefaultRateLimitRegistryReturnsOld 固化 Phase 5：Swap 返回被替换的旧 Registry。
func TestSwapDefaultRateLimitRegistryReturnsOld(t *testing.T) {
orig := defaultRateLimitRegistry.Load()
defer SwapDefaultRateLimitRegistry(orig)
first := NewRateLimitRegistry()
if prev := SwapDefaultRateLimitRegistry(first); prev != orig {
t.Fatalf("Swap returned %v, want orig", prev)
}
second := NewRateLimitRegistry()
if returned := SwapDefaultRateLimitRegistry(second); returned != first {
t.Fatalf("Swap returned %v, want first", returned)
}
if defaultRateLimitRegistry.Load() != second {
t.Fatal("Swap did not install second as default")
}
if got := SwapDefaultRateLimitRegistry(nil); got != second {
t.Fatalf("Swap(nil) = %v, want second (current default)", got)
}
}
// TestRateLimitRegistryStopIdempotent 固化 Phase 5：Stop 幂等，重复调用不 panic。
func TestRateLimitRegistryStopIdempotent(t *testing.T) {
r := NewRateLimitRegistry()
_ = r.loginLimiterInstance()
_ = r.apiLimiterInstance()
_ = r.uploadLimiterInstance()
r.registerCustom(NewRateLimiter(5, time.Minute))
r.Stop()
r.Stop() // 幂等
}
// TestRateLimitRegistryIsolation 固化 Phase 5：两个 Registry 实例的 limiter 互相独立。
func TestRateLimitRegistryIsolation(t *testing.T) {
rA := NewRateLimitRegistry()
rB := NewRateLimitRegistry()
defer rA.Stop()
defer rB.Stop()
la := rA.loginLimiterInstance()
lb := rB.loginLimiterInstance()
if la == lb {
t.Fatal("two registries returned the same loginLimiter instance (not isolated)")
}
// rA 用尽 10 次；rB 不受影响
for i := 0; i < 10; i++ {
if !la.Allow("1.1.1.1") {
t.Fatalf("rA request %d should be allowed", i+1)
}
}
// rA 第 11 次应被拒绝（count=10 >= rate=10）
if la.Allow("1.1.1.1") {
t.Fatal("rA 11th should be rejected (count reached limit)")
}
// rB 的 loginLimiter 独立计数，1.1.1.1 仍可放行
if !lb.Allow("1.1.1.1") {
t.Fatal("rB loginLimiter should be independent of rA (still allowed)")
}}

Some files were not shown because too many files have changed in this diff Show More