commit e00aa620f9f938a5a15b2df00c411974aa4f4703 Author: wehub-resource-sync Date: Tue Jul 14 10:24:10 2026 +0800 chore: import upstream snapshot with attribution diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..df4ecab --- /dev/null +++ b/.gitignore @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..5a30b83 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,1141 @@ +# Changelog + +xlgo 框架更新日志。本文档遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 规范， +版本号遵循 [语义化版本 SemVer](https://semver.org/lang/zh-CN/)。 + +> **如何阅读**：每个版本下分类列出变更类型—— +> - **Breaking**：⚠️ 破坏性变更，升级前必须阅读迁移说明 +> - **Added**：新增功能 +> - **Changed**：变更已有功能（非破坏性） +> - **Deprecated**：标记为废弃，未来版本会移除 +> - **Removed**：移除的功能 +> - **Fixed**：Bug 修复 +> - **Security**：安全相关修复 + +--- + +## [Unreleased] + +## [1.4.0] - 2026-07-12 + +> **instance+facade 一致性收尾**：cron/storage/cache/ratelimit 四个"纯全局"包按 `database.Manager`/`jwt.Manager` 模式实例化（App 持实例 + `SwapDefault*` 提升全局默认 + 包级 facade 代理），消除单进程多 App 互相污染；trace 纳入 App 生命周期（不做实例隔离，OTel 本身进程全局）；清理 `WithoutWire` 空函数。 +> +> **修复的多 App 冲突**：① App A `Shutdown` 不再把全局 cron 调度器 / 限流器停掉（B 的任务/限流不受影响）；② App B `Init` 不再覆盖 App A 的 storage driver / cache redis；③ cache/ratelimit 不再硬编码 `database.GetRedis()`，可注入 per-App redis；④ `commitReplacedResources` 不再关闭"被替换的全局默认"DB/Redis manager（多 App 下那可能是另一个 App 的活跃 manager，关闭致 "redis: client is closed"）；⑤ trace.Close 在 `App.Shutdown` 被调用（此前从未调用，exporter 后台 goroutine/连接泄漏）。 +> +> `go vet` + `go build` + `go test -race ./...` 全绿。本机需 `-buildvcs=false`。 + +### Breaking ⚠️ + +- **`xlgo.WithoutWire()` 删除**（app.go）：自 v1.1.0 wire 包删除后遗留的空 no-op 函数，全仓无引用。直接删除，无替代；调用方删除该 Option 即可（无行为变化）。 +- **`cron.AddTask(...)` 在 `App.Init` 之前注册不再生效**（cron/cron.go + app.go）：App 现持专属 `*Scheduler`，`Init` 时创建并 `SwapDefaultScheduler` 提升为全局默认。pre-Init 调用包级 `cron.AddTask` 会注册到 init 默认调度器、被 App swap 丢弃。迁移：改用 `xlgo.WithCronTask(name, schedule, handler)`（蕴含启用 cron），或 `Init` 后 `app.Scheduler().AddTask(...)`。post-Init 的包级 `cron.AddTask` 仍可用（代理到 App 调度器）。`cron` 包 `init()` 现预创建全局默认调度器（曾为懒初始化）。 +- **`middleware.StopRateLimiters()` 语义收窄**（middleware/ratelimit.go）：仅停止全局默认 `RateLimitRegistry` 的限流器。App 现持专属 Registry，`Shutdown` 调 `app` 自己的 `Stop`，不再调全局 `StopRateLimiters`（避免误停其他 App）。`LoginRateLimit`/`APIRateLimit`/`UploadRateLimit`/`CustomRateLimit` 改为请求时从默认 Registry 懒创建限流器（单 App 行为不变；多 App 下各自 Registry 隔离）。 +- **`App.commitReplacedResources` 不再关闭被替换的全局 DB/Redis manager**（app.go）：多 App 下"previous"可能是另一个 App 的活跃 manager，关闭致 `redis: client is closed`。单 App 下 previous 为 init() 空默认（无 client，Close 本就是 no-op），无影响。用户若手动 `database.InitRedis`/`InitDB` 后再 `App.Init`，旧 client 的关闭由用户负责（非常规组合）。 +- **`cache.redisCache` 持注入 redis client**（cache/cache.go）：新增 `cache.NewRedisCacheWithRedis(client)`、`(*CacheManager).InitWithRedis(client)`、`cache.SwapDefaultCacheManager(m)`。`cache.NewRedisCache()` 仍存在（懒取全局 Redis，standalone 用法）。App 现经 `InitWithRedis(a.redisManager.Client())` 注入 per-App client。 +- **`middleware.RedisRateLimiter` 新增 `WithRedisClient(client)` 选项**（middleware/ratelimit.go）：`Allow`/`GetCount`/`Reset` 改用 `rl.redisClient()`（注入优先、`database.GetRedis()` 兜底，照 `jwt.TokenBlacklist` 模型）。包级 `RedisRateLimit` 系列仍用全局 Redis；per-App 隔离用 `middleware.NewRedisRateLimiter(..., middleware.WithRedisClient(app.RedisClient()))`。 + +### Added + +- **`xlgo.WithTrace()`**：把 OpenTelemetry trace 纳入 App 生命周期--`Init` 调 `trace.Init`（按 `config.Trace`）、装入 `trace.Middleware`、`Shutdown` 调 `trace.Close`。实际导出由 `config.Trace.Enabled` 控制。**不做实例隔离**：OTel `TracerProvider`/`Propagator` 是进程级全局单例，多 App 共享（与 OTel 设计一致）。 +- **`xlgo.WithCronTask(name, schedule, handler)`**：注册定时任务到 App 专属调度器（蕴含 `WithCron`），替代旧的全局 `cron.AddTask` pre-Run 注册模式。 +- **`xlgo.App.Scheduler()` / `Cache()` / `RedisClient()`**：分别返回 App 专属的 cron 调度器、缓存服务、Redis 客户端，供多 App 隔离场景直接操作（绕过全局 facade）。 +- **`config.TraceConfig` + `Config.Trace` 字段**：链路追踪 YAML 配置（`service_name`/`exporter_type`/`endpoint`/`insecure`/`sample_ratio`/`enabled`/`propagator` 等）。`Validate` 在 `Enabled` 时校验 `sample_ratio` 范围；导出器/传播器枚举校验委托 `trace.Init`。 +- **`cron.SwapDefaultScheduler(s)`**、**`storage.SwapDefaultStorageManager(m)`**、**`cache.SwapDefaultCacheManager(m)`**、**`middleware.SwapDefaultRateLimitRegistry(r)`**：返回被替换的旧实例，供 App Init 失败回滚（照 `database.SwapDefaultManager`/`SwapDefaultRedisManager` 模式）。 +- **`storage.StorageManager.Close()`**：闭合 Init/Close 生命周期（与 database/redis/logger manager 对称），供 `App.closeResources`（Shutdown 路径）与 `rollbackReplacedResources`（Init 失败路径）对称收口。当前 LocalStorage/OSSStorage 无 closeable 资源（`oss.Client` 未暴露 Close），故为 no-op；经 `io.Closer` 断言调用驱动，未来带连接池的驱动实现 `io.Closer` 即被自动调用，框架骨架无需改动。 +- **`middleware.RateLimitRegistry`**：持 login/api/upload/custom 内存限流器，支持 per-App 隔离。`NewRateLimitRegistry()` / `Init()` / `Stop()` / `GetDefaultRateLimitRegistry()`。 +- **`xlgo.App.RateLimitRegistry()` + App-bound 限流中间件**（middleware/ratelimit.go）：`app.RateLimitRegistry().LoginRateLimit()`/`APIRateLimit()`/`UploadRateLimit()`/`CustomRateLimit(rate, window)` 返回的中间件捕获 App 自己的 Registry（请求时不查全局默认），实现多 App per-App 计数隔离。`RateLimitRegistry` 改在 `New()` 时预创建，使 getter 在 `Init` 前即可用于路由装配；`Init` 失败回滚时 `registry.Stop()` 收口 custom limiter，无泄漏。 + +### Fixed + +- **多 App 限流器互不污染**（middleware/ratelimit.go）：App A `Shutdown` 不再经全局 `StopRateLimiters` 把 App B 的 loginLimiter 置 nil（致 B 下次请求懒创建新 limiter、计数清零，稳态客户端借 A 的 Shutdown 窗口绕过限流）。各 App 持自己的 `RateLimitRegistry`。 +- **多 App cron 调度器隔离**（cron/cron.go + app.go）：App A `Shutdown` 不再经 `cron.StopGlobalWithTimeout` 停掉共享全局调度器（B 的任务不受影响）。 +- **多 App storage / cache 隔离**（storage/cache + app.go）：App B `Init` 不再覆盖 App A 的 storage driver / cache redis；cache 不再硬编码 `database.GetRedis()`（致 A 的缓存读到 B 的 redis）。 +- **trace exporter 泄漏**（app.go）：`App.Shutdown` 现调 `trace.Close` 刷出批量 span 并释放 exporter 后台 goroutine/连接（H-14 修了 `Close` 幂等，但 App 此前从未调它）。 +- **多 App logger writer 跨 App 误杀**（app.go `commitReplacedResources`）：与 `previousDB`/`previousRedis` 对齐，`commitReplacedResources` 不再 `CloseDefaultSnapshot`（旧实现会关掉被替换的全局默认 logger 的 lumberjack writers--多 App 下那可能是另一个 App 的活跃 writer，致其后续写日志失败/丢失）。单 App 下旧默认为 Nop（无 writer，不泄漏）；用户手动配置 logger 后再 `App.Init` 的旧 writer 由用户负责。 + +### 多 App 边界与已知缺口 + +本次实例化收尾覆盖 cron/storage/cache/ratelimit + trace 生命周期。多 App 进程下的边界： + +- **包级限流 facade 仅绑定最后 Init 的 App**（middleware/ratelimit.go）：`LoginRateLimit`/`APIRateLimit`/`UploadRateLimit`/`CustomRateLimit`（包级）在请求时解析 `GetDefaultRateLimitRegistry()`（全局默认），多 App 下仅最后 Init 的 App 是全局默认。**已提供 per-App 计数隔离路径**：`app.RateLimitRegistry().LoginRateLimit()` 等 App-bound 中间件捕获 App 自己的 Registry（见 Added）。包级 facade 仍为单 App / backcompat 保留。 +- **`CustomRateLimit` 首请求时机**：包级 `CustomRateLimit` 的 `sync.Once` 在首请求时登记 limiter 到全局默认 Registry，首请求若在 `App.Init` swap 前会泄漏 cleanup goroutine。**App-bound 路径 `app.RateLimitRegistry().CustomRateLimit(rate, window)` 已无此问题**（登记到 App 的 Registry，由 `registry.Stop()` 收口）。HTTP server 在 Init 后才起，常规用法不触发泄漏。 +- **trace 进程全局共享**（trace/trace.go，设计限制）：OTel `TracerProvider`/`Propagator` 是进程级单例，任一 App `Shutdown` 调 `trace.Close` 会关闭全局 trace 导出，影响同进程其他 App。多 App 需自行管理 trace 生命周期（不在多个 App 上同时启用 `WithTrace`）。**不可修**（OTel 自身全局设计）。 +- **`StorageManager` 无 `Close`**（storage/storage.go，经核实：oss.Client 无 Close，当前为 no-op；已加 StorageManager.Close() 闭合生命周期（见 Added））：`LocalStorage` 无 closeable 资源；`OSSStorage` 持 `*oss.Client`，但 `oss.Client` **未暴露 `Close` 方法**（aliyun-oss-go-sdk），其 HTTP 空闲连接由 OS 超时 + GC 回收。无显式资源泄漏；未来带连接池的驱动实现 io.Closer 即被 Close 自动调用。 + +## [1.3.0] - 2026-07-12 + +> 同义可失败 API 收敛 + 注释/文档一致性修复 + 前序评审收口。 +> +> **API 收敛**（`gpt_clear_function.md` 计划）：按"同一能力只保留一个主入口、框架不替上层吞错、安全路径默认 fail-closed"原则，收敛 cache/jwt/storage/ratelimit 四个包的历史双轨 API。自定义 `CacheService`/`Storage` 实现需同步更新签名（编译失败即迁移信号）。 +> +> **注释/文档一致性**（`glm_note_report.md` 报告）：A/B/C 三档共 23 项注释/文档修复，无运行逻辑变更。 +> +> **前序评审收口**：M13 cron panic、M1 App 生命周期状态机、M3 logger 生命周期临界区；config 模块评审（H-config-1 Set/viper 同源、M-config-1 回调 panic 隔离、M-config-2 DB SSL/TLS、M-config-3 App 关闭停 watcher、M-config-4 Clone 守卫）；database 模块评审（H-db-1 后台探活/启动 ping 经 pingWithTimeout 3s 约束）。 +> +> 项目处于初级阶段，无下游用户，放心引入破坏性变更。`go vet` + `go build` + `go test -race ./...` 全绿。 + +### Breaking ⚠️ + +- **PostgresDSN 默认 sslmode 由 `disable` 改为 `prefer`**（M-config-2）：原 `PostgresDSN` 硬编码 `sslmode=disable`，生产 DB 流量明文。新增 `DatabaseConfig.SSLMode` 字段，空值默认 `prefer`（优先加密、失败回退明文），可显式配置 `disable/allow/prefer/require/verify-ca/verify-full`（非法值在 `Validate` 阶段报错）。依赖明文 Postgres 连接的下游若因 `prefer` 回退行为受影响，请显式设置 `ssl_mode: disable`。MySQL 不受影响（用 `TLS`/`TLSRootCA`）。 + +- **cache 写操作与计数器/原始 Redis helper 在 Redis 未初始化时返回 `ErrRedisNotReady`**：`Set` / `Delete` / `DeleteByPattern` / `Incr` / `IncrBy` / `Decr` / `GetTTL` / `SetExpire` / `GetRaw` / `SetRaw` 旧行为会静默返回成功或零值，调用方容易误判缓存写入、计数器更新或过期时间设置已经生效；现在统一显式返回错误。公共接口签名不变，但依赖“未启用 Redis 时当作成功”的下游需要改为忽略 `errors.Is(err, cache.ErrRedisNotReady)` 或显式启用 Redis。 +- **`cache.WithLock` / `cache.WithLockAutoExtend` 未获取到锁时返回 `ErrLockNotAcquired`**：旧行为返回 `nil` 并跳过业务函数，调用方无法区分“业务执行成功”和“根本没有执行”。同时锁 TTL 小于 1ms、续期/重试间隔非正会返回显式错误，避免 Redis PX=0 或 `time.NewTicker(0)` 崩溃。 +- **`cache.WithLock` / `cache.WithLockAutoExtend` 的业务函数签名改为 `func(context.Context) error`**：旧签名 `func() error` 无法强制业务函数接收取消信号，容易在请求取消/超时后继续访问 DB/HTTP 等下游资源；现在框架会把调用方 ctx 传入业务函数。nil 业务函数返回新增 `ErrLockFuncNil`。 +- **`test.Request.Execute()` 改为返回 `*test.Response`**：旧返回值是 `*httptest.ResponseRecorder`，与文档示例中的 `resp.AssertOK(t)` / `resp.ParseJSON(...)` 不一致；现在 `Execute()` 返回带断言和 JSON 解析方法的包装类型。需要原始 recorder 的调用方改用新增 `ExecuteRecorder()`。 +- **`config.Get()` / `(*config.Manager).Get()` 改为返回配置副本**：旧行为暴露内部 `*Config`，调用方修改返回值会污染全局配置并可能与热重载并发读写竞态；现在返回深拷贝。需要动态替换配置的测试或工具代码请改用 `config.Set(cfg)`。 +- **`config.Set()` / `(*config.Manager).Set()` 现在返回 `error`**：非 nil 配置会先执行 `Validate()`，非法配置不会覆盖旧配置，并返回 `ErrInvalidConfig` 包装错误。旧代码可以继续忽略返回值，但建议测试和启动路径显式检查。 +- **`config.GetViper()` / `(*config.Manager).GetViper()` 改为返回 viper 快照**：旧行为暴露内部可变 `*viper.Viper`；现在修改返回对象不会影响全局配置。常规读取请使用 `GetString` / `GetInt` / `GetBool` / `GetStringMap`。 +- **未知数据库 driver 不再静默回退 MySQL**：`config.DatabaseConfig.DSN()` 对非空但未注册的 `driver` 返回空字符串，`database.Dialector` 返回初始化即失败的 Dialector；空 `driver` 仍保持默认 MySQL。下游若使用自定义数据库驱动，需先通过 `database.RegisterDialect` 或 `config.RegisterDSNBuilder` 注册。 +- **`database.InitDB` / `(*database.Manager).InitDB` / `InitDBWithReplicas` 必须显式传入 `context.Context`**：旧 API 无法取消初始化过程中的 Ping 与重试等待，shutdown 或启动失败回滚时可能长时间卡住。现在调用方必须传入生命周期 ctx；普通测试或一次性脚本可使用 `context.Background()`，App 初始化会使用 App root ctx。 +- **`database.SetDefaultManager` / `database.SetDefaultRedisManager` 会关闭被替换的旧 manager**：旧行为只做 atomic 替换，直接调用会遗留旧 DB/Redis 连接池。现在普通 Set 表示“接管全局默认资源并释放旧资源”；需要失败回滚或延迟释放旧资源的初始化流程请改用新增 `database.SwapDefaultManager` / `database.SwapDefaultRedisManager`。 +- **`jwt.ParseToken` 开始校验 issuer，`RefreshToken` 使用 `jwt.refresh_expire`**：签发者与当前配置不一致的 token 会被拒绝；刷新后的 token 过期时间优先使用 `refresh_expire`，未配置时回退 `expire`。`GenerateTokenWithCustomExpiry` 现在拒绝非正过期时间，`InvalidateTokenByID("")` 返回 `ErrEmptyJTI`。 +- **`App.Init()` 由 `sync.Once` 改为生命周期状态机**（app.go，M1）：5 态 `stateCreated/Initializing/Initialized/Stopping/Stopped` + `lifecycleMu`(RWMutex) + `initMu`(Mutex)。`Shutdown` 后或 `Init` 失败后再调 `Init()` 返回新增导出错误 **`xlgo.ErrAppClosed`**（原 `sync.Once` "多次调用返回首次结果"语义不再适用——已关闭的 App 不可再 Init，需新建 App）。 +- **`App.Go()` 在 Shutdown 开始或 Init 失败后为 no-op**（app.go，M1）：`state >= stateStopping` 时拒绝 `wg.Add` 直接返回，避免与 `Shutdown` 的 `wg.Wait` 竞争 `sync.WaitGroup` 契约（Add 须 happen-before Wait）。依赖"Shutdown 后仍可 Go"的下游需改用独立 goroutine。 +- **生命周期 hook 不允许重入调用 `Init`/`Shutdown`/`Run`**（app.go，M1）：`initMu` 非重入，hook（OnInit/OnStart/OnReady/OnStop）内调用会自锁死锁。需在 hook 内触发关闭应改用信号通道由主流程处理。 +- **`xlgo.WithConfig(cfg)` 改为快照语义并在 `Init` 时校验**（app.go，M1）：传入配置会深拷贝到 App 私有快照，调用方后续修改原 `cfg` 不再影响 App；非法配置在 `Init` 返回中文校验错误。依赖“修改原 cfg 指针动态影响 App”的下游需改为重新创建 App 或使用配置管理器。 +- **`logger.DefaultLogger = m` 直接赋值不再驱动包级 facade**（logger/logger.go，M3）：为消除 `SetDefaultLogManager()` 与包级 facade 并发读取默认 manager 的裸全局指针竞态，facade 改为读取内部 atomic 快照。`logger.DefaultLogger` 仍保持 `*LogManager` 类型，旧的 `logger.DefaultLogger.Init/Close/SetLevel/GetLevel` 直接调用仍可用；替换默认 manager 请使用 `logger.SetDefaultLogManager(m)`。 +- **`logger.Init` 拒绝明显非法日志配置**（logger/logger.go，M3）：空日志目录、负数 `MaxSize/MaxBackups/MaxAge` 现在直接返回错误。依赖零值日志配置启动 `WithLogger()` 的下游需显式设置 `Log.Dir` 与非负轮转参数。 +- **限流器非法配置改为 fail-fast**（middleware/ratelimit.go，M8）：`NewRateLimiter` / `NewRedisRateLimiter` / `NewRedisRateLimiterFailClosed` 现在对 `rate <= 0` 或 `window <= 0` 直接 panic，避免零值窗口/零值配额静默产生不确定限流语义。下游应在配置加载阶段校验限流参数。 +- **`handler.BindJSON` 默认限制 JSON body 为 1MiB**（handler/handler.go，M6）：防止入口层无上限读取请求体导致 OOM。需要更大 JSON 的接口请改用 `handler.BindJSONWithMaxBytes(c, req, maxBytes)` 显式声明上限。 +- **cron 非法任务配置改为 fail-fast**（cron/cron.go，M13）：`AddTask` 拒绝 nil schedule / nil handler；`Every(<=0)`、`Daily`/`Weekly` 越界时间、非法 weekday 会 panic，避免静默生成不推进或归一化跑偏的调度。 +- **`cron.ParseCron` 非法表达式改为 fail-fast panic**（cron/cron.go，M13）：旧行为会把非法表达式静默回退为每分钟执行，容易让拼写错误变成高频任务。动态输入请用 `ParseCronStrict` 处理 error；确实需要旧回退语义时改用新增 `ParseCronOrDefault`。 +- **repository 查询保护默认开启**（repository/repository.go，M5/N5）：`FindAll` 默认最多返回 `DefaultFindAllLimit=1000` 条；明确需要全表扫描时改用 `FindAllUnbounded`。`FindPage*` / `QueryBuilder.Page` 会归一化 `page/pageSize` 并限制 `MaxPageSize=100`、`MaxPage=10000`。`Find*Ordered` / `QueryBuilder.Order` 只接受简单字段排序（如 `created_at DESC, id ASC`），复杂表达式/raw SQL 会返回 `ErrUnsafeOrder`；`UpdateBatch` 字段名不合法返回 `ErrUnsafeField`。 + +- **同义可失败 API 收敛：错误不再吞并**（cache/jwt/storage/ratelimit）：按"同一能力只保留一个主入口、框架不替上层吞错、安全路径默认 fail-closed"原则，收敛历史双轨 API。详见下述分项；自定义 `CacheService`/`Storage` 实现需同步更新签名（编译失败即迁移信号）。 + + - **cache**：`CacheService.Get` / `Exists` 改为 `(bool, error)`--命中 `(true,nil)`、未命中 `(false,nil)`、Redis 未就绪/命令错误/反序列化失败返回 `(false,err)`。删除 `cache.GetE` / `cache.ExistsE` / `CacheGetter` / `CacheExistChecker` / `redisCache.GetE` / `redisCache.ExistsE`（不保留 deprecated wrapper）。新增包级 `cache.Get(ctx,key,dest) (bool,error)` / `cache.Exists(ctx,key) (bool,error)`。`GetWithPrefix` 改为 `(bool,error)`。迁移：`hit, err := cache.Get(ctx, key, &v); if err != nil { return err }; if !hit { /* miss */ }`。 + + - **jwt**：`TokenBlacklist.IsBlacklisted` 改为 `(bool, error)`，删除 `IsBlacklistedE`。`IsTokenRevoked` 改为 `(bool, error)`。`ParseToken` 默认从 **fail-open 改为 fail-closed**--黑名单后端不可检查时返回 `ErrBlacklistUnavailable` 拒绝该 Token（无 Redis 部署不再支持可靠撤销）。删除 `ParseTokenFailClosed`（主 API 已 fail-closed）。保留 `ParseTokenWithBlacklistPolicy(token, policy)` + `BlacklistPolicy`/`BlacklistFailOpen`/`BlacklistFailClosed` 供显式 fail-open（仅无 Redis 或低安全场景）。迁移：无 Redis 部署需启用 Redis，或显式 `jwt.ParseTokenWithBlacklistPolicy(token, jwt.BlacklistFailOpen)`。 + + - **storage**：`Storage.Exists` 改为 `(bool, error)`--存在 `(true,nil)`、不存在 `(false,nil)`、未初始化/路径非法/穿越/后端错误返回 `(false,err)`。`LocalStorage.Exists` 区分 `os.IsNotExist`（not found）与其他 `os.Stat` 错误；`OSSStorage.Exists` 区分 OSS 404/NoSuchKey（not found）与鉴权/网络错误。包级 `storage.Exists` 同步签名，未初始化返回 `ErrStorageNotInitialized`。新增 `ErrReadTooLarge`：`LocalStorage.Get` / `OSSStorage.Get` 读取超 `maxReadBytes` 上限原误用 `ErrInvalidPath`（路径无效语义不贴切），改为 `ErrReadTooLarge`。迁移：`ok, err := storage.Exists(p); if err != nil { return err }; if !ok { /* not found */ }`。 + + - **ratelimit**：Redis 限流器策略收敛为配置型 API。`NewRedisRateLimiter(keyPrefix, rate, window, opts ...RedisRateLimiterOption)` 新增可变参数，`WithFailClosed(true)` 替代原 `NewRedisRateLimiterFailClosed`。`RedisRateLimit` / `CustomRedisRateLimit` / `RedisRateLimitWithIdentifier` 同步加 `opts` 参数。删除 `NewRedisRateLimiterFailClosed` / `RedisRateLimitFailClosed` / `CustomRedisRateLimitFailClosed`。`UploadRedisRateLimit` 由 fail-open 改为 **fail-closed**（上传属资源敏感操作，Redis 故障时拒绝以防限流静默失效）。迁移：`middleware.RedisRateLimit("k", 100, middleware.WithFailClosed(true))` 替代原 `RedisRateLimitFailClosed("k", 100)`。 + +### Security 🔒 + +- **MySQL 连接支持 TLS**（M-config-2）：`DatabaseConfig.TLS` 为 true 时 `MySQLDSN` 追加 `tls=true`（go-sql-driver/mysql v1.7.0 内置安全语义：系统根 CA + ServerName 自动取自 Host + 证书校验，无需注册）。配合 `DatabaseConfig.TLSRootCA`（PEM 路径）可指定私有 CA/自签证书，由 `database` 包在 `InitDB` 时 `RegisterTLSConfig` 注册命名配置（`config.MySQLTLSConfigName`）；CA 不可读或非 PEM 时 fail-fast，不静默回退明文。 +- **Postgres 连接支持 sslmode 配置**（M-config-2）：见 Breaking 项，默认 `prefer` 优先加密。 + +### Fixed 🐛 + +- **config `Set(cfg)` 与 viper 视图同源修复**（H-config-1）：`Set` 原只更新类型化视图 `m.cfg`，`m.v`（viper）停留旧值，导致 `Get()` 与 `GetString/GetInt/GetBool/GetViper` 返回不同世界（违反 C1 单一配置源）。现在 `Set` 用 mapstructure 将 `*Config` 重建为不含 `AutomaticEnv` 的 viper 视图，保证 Get 与 GetString 同源。 +- **config 热重载回调 panic 隔离**（M-config-1）：单个 `onChange` 回调 panic 原会传播致 watcher 泄漏、后续热更新静默失效。现在每个回调独立 `recover`（标准库 `log` 记录 + 堆栈），不阻断后续回调、不杀 watcher。 +- **App.Shutdown 停止 configManager watcher**（M-config-3）：`closeResources` 末尾新增 `configManager.StopWatcher()`，用户对 App 的 configManager 调 `LoadWithWatch`/`StartWatcher` 后由 Shutdown 统一收口，避免关闭后遗留监听 goroutine（违反 C7）。 +- **config `Clone` 切片字段覆盖守卫**（M-config-4）：新增反射测试枚举 `Config` 所有切片/map 字段，断言 `Clone` 深拷贝；新增切片字段未同步 fixture 或 `Clone` 时测试失败，形成机械守卫。 +- **config `watchLoop` 增加 ctx 逃生通道**（L-config-2）：原仅靠 `w.Events` 关闭退出，与"for 消费循环须 ctx.Done"红线有张力。`StopWatcher` 改为 cancel ctx + Close watcher 双重退出。 +- **config `Validate` 连接池交叉校验**（L-config-3）：`MaxOpenConns>0` 时 `MaxIdleConns>MaxOpenConns` 视为配置错误。 +- **config 哨兵错误改用 `errors.New`**（L-config-4）；**`DSN()` 去除冗余 TrimSpace**（L-config-5）；**`DSN/MySQLDSN/PostgresDSN/Addr` nil receiver 防御**（L-config-6）。 +- **database 后台探活/启动 ping 经 pingWithTimeout 3s 约束**（H-db-1，M11 修复不完整）：`pingWithTimeout` 原只加到包级 `HealthCheck()`，未覆盖方法 `(*Manager).HealthCheck`（被后台探活 `probeOnce` master 与 `/health` 端点共用）、`probeOnce` 从库 ping、`InitDB`/`InitDBWithReplicas` 启动 ping。挂起 DB（连接活但不响应）下这些路径的 `PingContext` 无 ctx deadline 无限阻塞，致探活 goroutine 阻塞、#21 自愈冻结、`IsHealthy()` 缓存失真、启动卡死。现 4 路径统一经 `pingWithTimeout`（`healthCheckTimeout`=3s，尊重 ctx 自带更短 deadline）。**另发现并修复 gorm.Open 的 automatic ping**（gorm.go:204，ConnPool 为 `*sql.DB` 时调 `pinger.Ping()` 无超时）在 pingWithTimeout 之前就无限阻塞--`initDB`/`InitDBWithReplicas` 的 gormConfig 加 `DisableAutomaticPing: true`，框架用 pingWithTimeout 自管启动 ping。Redis 侧 `HealthCheck` 经 client `ReadTimeout`(3s) 约束（行为验证）。新增 `manager_hdb1_internal_test.go`（hungDriver 回归 pingWithTimeout/m.HealthCheck/probeOnce replica/initDB/InitDBWithReplicas 5 路径）、`redis_hdb1_internal_test.go`（挂起 Redis 回归 HealthCheck）、`app_hdb1_test.go`（App 级端到端：Init 挂起 DB 有界失败 + Shutdown 正常）。 + +- **M9 JWT issuer / refresh expiry 契约修复**：`ParseToken`、`InvalidateToken`、`GetClaimsFromToken` 统一按当前配置校验 issuer；`RefreshToken` 不再忽略 `refresh_expire`；空 JTI 不再写入永不命中的 `jwt_bl:` 黑名单键；新增 `ParseTokenFailClosed` / `ParseTokenWithBlacklistPolicy` / `TokenBlacklist.IsBlacklistedE`，默认 `ParseToken` 仍保持黑名单检查 fail-open 兼容语义，安全敏感路由可显式选择 fail-closed；解析侧配置错误现在可通过 `errors.Is` 区分 `ErrEmptySecret` / `ErrUnsupportedAlgorithm`；`InvalidateToken` 使用不校验时序的解析路径，允许提前吊销 `nbf` 在未来的外部 token。 +- **M10 分布式锁参数与取消传播修复**：锁 TTL 统一校验到 Redis 毫秒粒度；`TryLock` 的非正 retry interval 不再 busy-loop；`WithLockAutoExtend` 的非正 extend interval 不再触发 goroutine panic；`UnlockByKey` 在 Redis 未初始化时与 `ForceUnlock` 一样返回 `ErrRedisNotReady`；`WithLock` / `WithLockAutoExtend` 现在把调用方 ctx 传入业务函数，避免取消后业务函数继续运行。 +- **M10 cache 剩余错误语义收口**：新增 `cache.GetE` / `cache.ExistsE` 与可选 `CacheGetter` / `CacheExistChecker`，让调用方能区分 cache miss、Redis/backend 故障和反序列化错误；保留旧 `Get` / `Exists` bool-only 兼容方法但记录后端错误；`KeyBuilder` 现在忽略 nil option，`WithPrefix` / `WithSeparator` / `WithCacheType` 直接作用于 nil builder 时 no-op，避免扩展配置路径 panic。 +- **M2 config 热重载生命周期修复**：`StopWatcher` 会等待已触发的 reload/回调结束；包级 `Load` / `LoadWithWatch` 只有在新配置成功加载并启动 watcher 后才替换默认 manager，失败时保留旧 watcher；`SetDefaultManager` 会停止旧 manager 的 watcher，避免全局置换后遗留 goroutine；数据库配置出现字段时会校验 driver/host/name/port，未知 driver 不再静默回退 MySQL，`database.Dialector` 对未知 driver fail-closed；MySQL DSN 转义用户名/库名，Postgres DSN 统一转义字符串字段。 +- **M4 database nil 边界修复**：`InitDB(ctx, nil)` / `InitDBWithReplicas(ctx, nil, ...)` / `InitRedis(nil)` 现在返回中文错误，不再空指针 panic；`UseMaster(nil)` / `UseReplica(nil)` / `GetDBFromContext(nil)` / `WithTx(nil, ...)` / `TxFromContext(nil)` / `TransactionWithContext(nil, ...)` / `ReadQuery(nil, ...)` / `WriteQuery(nil, ...)` / Redis health check 会把 nil context 归一化为 `context.Background()`，避免异常调用路径触发 panic；`Dialector(nil)` 安全回退到 MySQL 空 DSN。 +- **M4 database 全局置换资源释放修复**：`SetDefaultManager` / `SetDefaultRedisManager` 替换全局默认 manager 时会关闭旧 DB/Redis manager，避免包级默认资源反复置换后连接池泄漏；App 初始化改用 `SwapDefaultManager` / `SwapDefaultRedisManager` 暂存旧资源，保证失败回滚仍能恢复旧默认资源。 +- **M4 database 初始化生命周期修复**：DB 初始化与主从库初始化统一接收 ctx，主库/从库 Ping 使用 `PingContext`，重试等待改为 `select ctx.Done()/time.After`；`Manager` 用生命周期锁串行化 Init/Close，避免 shutdown 与运行期重建交错；运行期重建从库后会立即重建健康标记，探活循环也能在发现健康标记缺失时自愈；包级 `HealthCheck()` 固定读取一次默认 manager 快照。 +- **M11 SSE 换行注入修复**：`WriteEvent` 拒绝带 CR/LF 的 event 名，`WriteMessage` / `WriteEvent` 的 data 按 SSE 多行格式逐行输出，避免用户数据伪造额外 `event:`/`id:` 字段。 +- **M15 utils/validation 资源与错误边界修复**：`HTTPClient.Upload` 改为流式 multipart 上传，不再把文件请求体完整缓存在内存中；`AppendFile` / `CopyFile` 返回写侧 `Close` 错误；`CheckPasswordAndUpgrade` 归一化非法 `targetCost`，避免异常配置触发超高 bcrypt cost；`ValidateStruct(nil)` 直接返回 nil。 +- **M15 utils 转换语义收口**：新增 `utils.ToIntE` / `utils.ToInt64E` 返回解析错误；旧 `ToInt` / `ToInt64` 保留“失败返回 0”的兼容行为，调用方在 0 有业务含义时应迁移到严格变体。 +- **M16 测试工具、脚手架与示例闭环修复**：`MockDB` / `MockCache` / `MockStorage` 改为并发安全；`MockCache` 与 `MockStorage.UploadFromBytes` 复制字节切片，避免调用方修改污染内部状态；`MockStorage` 拒绝 nil 文件与超过 32MiB 的输入，避免测试 helper 被误用成无上限内存缓冲；`xlgo make` 对资源名做显式标识符校验，非法名称（路径穿越、连字符、数字开头等）直接返回中文错误，不再静默转义后生成不可预期代码；`examples/full` 启动时初始化 `alice/secret`，登录校验 bcrypt 哈希，创建用户也保存哈希，避免示例首次运行无法登录或传播不验密/明文密码模式；README/GUIDE 限流示例不再引用不存在的 `handler.Login` / `handler.Upload`。 +- **M16 GUIDE/test API 不一致修复**：GUIDE 测试示例不再调用不存在的 `AssertCode` / `AssertJSONKeyExists`，统一改用现有 `AssertJSONContains`，避免照文档编写测试直接编译失败。 +- **M12 storage/compress 安全边界修复**：本地上传写侧 `Close` 错误会通过返回值暴露并清理残片；OSS `GetSignedURL` 统一经过 object key 净化；`UnzipWithOptions` 解析目标绝对路径失败时 fail-closed。 +- **M8 middleware 边界收口**：`AuthRequired` 的 `Authorization` scheme 改为大小写不敏感，符合 Bearer 语义；`LoggerConfig.SkipPathPrefixes` 与 `SimpleLogger` 静态路径跳过改为路径边界匹配（`/api` 仅匹配 `/api` 和 `/api/...`，不再误跳过 `/api2`）。 + +- **M13 cron handler panic 未 recover 崩进程**（cron/cron.go）：`RunTask` 与 `checkAndRun` 调度 goroutine 统一经新增 `executeTask(t)` 边界 `recover`，panic 转为 error（含 `debug.Stack` 调用栈）记入 `task.LastError` 并向上返回，不再终止进程。外侧 `defer wg.Done()`/`running` 守卫释放不受影响（recover 在边界内完成）。顺带修复 `RunTask` 手动路径此前只更 `LastRun/RunCount`、不记 `LastError` 的子问题（现与调度路径一致）。 +- **M6 response/handler 入口防护**（response/error.go，response/response.go，handler/handler.go）：`FailWithError(nil)` / `FailWithDetail(nil, ...)` 回退统一服务器错误响应，不再 nil deref panic；新增 `response.DownloadReader` 支持大文件/对象存储流式下载，旧 `Download` / `DownloadWithContentType` 保持兼容并复用同一响应头逻辑。 +- **M14 trace 剩余记录补齐**（trace/trace.go）：`SampleRatio` 拒绝 NaN/越界值；`Init`/`Close` 使用操作超时并在初始化失败时回滚 provider；`RecordError` / `RecordErrorToSpan` 对 nil 输入 no-op；`Middleware(serviceName)` 写入 `service.name` attribute；`X-Trace-ID` 不再输出全零 TraceID。 +- **M7 health/readiness 探活超时**（router/router.go）：`HealthCheck` 新增 `Timeout` 字段，默认每个依赖检查 2s 超时；超时项返回 `"timeout"` 并使 `/health` / `/readyz` 返回 503。单个 check 同时最多一个执行中，panic 会 recover 为错误，避免 k8s/LB/监控探活被挂死依赖无限卡住或无限堆积 goroutine。 +- **M13 cron 剩余边界收口**（cron/cron.go）：Stop 后再次 Start 会重建调度器 context，手动和调度执行不再收到已取消 ctx；Start/Stop 生命周期串行化，避免 Stop 等待期间重新 Start 触发 WaitGroup Add/Wait 交错。 +- **M5 repository 安全边界收口**（repository/repository.go）：nil ctx 统一按 `context.Background()` 处理；`FindByIDs(nil)` 返回非 nil 空切片；`NewQueryBuilder` 复用 nil DB 明确 panic；批量空 ids 写操作 no-op；默认 `FindAll` 加上限并新增 `FindAllUnbounded`；排序/字段名白名单避免便捷 API 误接 raw SQL。 +- **M1 App 生命周期三类缺陷统一治理**（app.go）： + - **Init 失败无资源回滚** → 新增 `failAfterInit`：markStopping → cancel rootCtx → wg.Wait(10s) → cron 5s 显式超时停止 → `closeResources` 幂等关闭 db/redis/logger，回滚错误 `errors.Join` 进 `initErr` 不吞；先停 goroutine 再关资源，避免"关 DB 时探活 goroutine 仍在用"的竞态。 + - **App.Go 与 wg.Wait race** → `lifecycleMu.RLock` 包住 `wg.Add`，`Shutdown` 持写锁翻 `stateStopping`，保证 Add happens-before Wait。 + - **Shutdown 非幂等/非并发安全** → `shutdownOnce` 保证 `doShutdown` 单次执行，并发调用者返回同一 `shutdownErr`。 + - **OnStop 语义与超时** → 仅 `Init` 曾成功（`wasInitialized`）时在 `doShutdown` 开头执行；Init 失败/未 Init 时 HTTP 从未启动，OnStop 跳过。OnStop 现在受 `server.shutdown_timeout` 同一预算约束，阻塞 hook 不再无限拖住 Shutdown。 + - **资源所有权** → App 只关闭自己成功初始化过的 logger/db/redis/cron，避免一个 Init 失败的新 App 关闭同进程既有全局资源。 + - **复审补强：资源替换事务边界** → App 初始化 logger/db/redis 时先创建 App-owned manager 并保存旧默认 manager 快照；OnInit 或后续步骤失败时恢复旧默认 manager 并关闭新资源，完整成功后才释放旧资源，避免“新 App Init 失败”破坏同进程既有全局 logger/db/redis。 + - **复审补强：health/probing 绑定 App-owned manager** → App 注册的 MySQL/Redis health check 与 DB probing 使用本 App 持有的 manager，不随后续全局默认 manager 替换漂移。 + - **OnReady 早于真实监听成功** → `StartServer` 改为同步 `net.Listen` 且 TLS 证书装配成功后再启动 `Serve` 与执行 OnReady；监听/TLS 失败直接返回，不触发 ready 副作用。 + - **`server.unix_socket` 不可用** → 非空 `unix_socket` 现在走 `net.Listen("unix", path)` + `http.Server.Serve`，不再把 socket path 误传给 TCP `ListenAndServe`。 + - `Init`/`Shutdown` 经 `initMu` 串行化 doInit/doShutdown 长段，杜绝并发改资源。 +- **M3 logger 生命周期与全局 manager 并发治理**（logger/logger.go）： + - **`LogManager.Init()` 锁外写 `m.level`** → `Init` 在通过局部配置校验后持 `m.mu` 完成建目录、构造与发布新 logger，`m.level` 只在同一临界区更新；包级 `Logger/fileWriters` 发布另由 `globalMu` 串行化，避免多个 `LogManager` 实例用各自实例锁保护同一包级状态。 + - **`DefaultLogger` 裸全局指针** → 保留导出变量兼容旧代码，新增内部 atomic 默认 manager 快照与 `GetDefaultLogManager()`；包级 `Init/Close/Sync/SetLevel/GetLevel` 全部经 atomic 读取当前 manager。 + - **stale manager 关闭当前 logger** → 每次发布全局 logger 分配 generation，只有拥有当前 generation 的 `LogManager.Close()` 才能关闭当前全局 logger/writer。 + - **旧 writer 关闭顺序错误** → `Init` 先 atomic 发布新 logger，再关闭旧 lumberjack writer，避免替换窗口内包级读路径拿到指向已关闭 writer 的旧 logger。 + - **`Close()` 与 `Init()` 生命周期互相覆盖** → `Close` 在同一 manager 锁内先快照旧 logger/writer 并发布 Nop，再执行 Sync/Close；关闭错误通过 `errors.Join` 聚合返回，不再静默吞掉 lumberjack `Close` 错误。 +- **M8 middleware/CSRF 与限流边界治理**（middleware/csrf.go，middleware/ratelimit.go）： + - **CSRF JSON body 读取无上限** → 从 body 提取 `_csrf` 时使用 `http.MaxBytesReader`，默认上限 1MiB（`CSRFConfig.MaxBodyBytes` 可调），超限返回 HTTP 413，避免 pre-auth OOM；仍使用 `ShouldBindBodyWith` 保留下游重复读取 body 的能力。 + - **CSRF cookie SameSite 配置未真正写入** → `CSRF()` 与 `DoubleSubmitCookie()` 设置 cookie 前显式 `SetSameSite`，默认 Lax。 + - **CSRF 局部配置丢默认 cookie 行为** → `CSRFConfig` 归一化补齐 `Path`、`SameSite`、`MaxAge`、`FormField`、`MaxBodyBytes` 等默认值，只覆盖单个字段时不再意外丢失默认 cookie 约束。 + - **CSRF session cookie 显式配置** → 新增 `CSRFConfig.SessionCookie`，需要会话 Cookie 时设置为 `true`；为保持 `CSRFWithConfig(CSRFConfig{})` 默认 1 小时语义，`MaxAge=0` 且未设置 `SessionCookie` 时仍回退默认值。 + - **CSRF TokenLength 负数 panic/退化** → `TokenLength <= 0` 统一回退默认长度，避免配置错误导致 `make([]byte, negative)` panic。 + - **CSRF skip path 前缀误跳过** → `CSRFWithSkip([]string{"/api"})` 仅跳过 `/api` 与 `/api/...`，不再误跳过 `/apix`。 + - **API CSRF token map 只校验时清理过期 token** → `GenerateAPIToken` 颁发新 token 前同步清理过期项，避免长期只发不验场景内存增长。 + - **`RateLimit(nil)` panic** → 改为 fail-closed 返回 HTTP 503 + `CodeServiceUnavailable`，避免未初始化限流器导致请求路径 nil deref。 + - **`RedisRateLimitWithIdentifier` nil 回调 panic** → `identifierFunc == nil` 时回退 `ClientIP()`，并保留空字符串回退逻辑。 +- **gosec database 告警收口**（database/manager.go，database/redis.go）：`RoundRobinPicker` 改为 mutex 保护的有界 `int` 计数器，消除 G115 整数转换告警；`RandomPicker` 改用 `crypto/rand` 选择从库，消除 G404 弱随机源告警，随机源失败时安全回退到首个从库；Redis 初始化 ping 失败时不再静默吞掉 `client.Close()` 错误。 +- **复审补强：DB/Redis 重建路径资源释放**（database/manager.go，database/redis.go）：Redis 重复初始化会关闭旧 client；DB 重建/重试路径的旧连接池关闭失败不再静默丢弃，会记录 warning 供排查。 +- **gosec Close 错误收口**（utils/http.go，compress/compress.go）：HTTP multipart 上传循环中的本地文件 `Close()` 错误不再静默吞掉；gzip/zip 解压输出文件关闭失败会通过 `errors.Join` 返回，并触发残留目标文件清理。 +- **gosec 兼容性/误报标注收口**（cmd/xlgo，utils/http.go，utils/crypto.go，utils/file.go，compress/compress.go）：为已存在输入校验或明确调用方契约的路径、客户端请求 cookie、非安全用途 checksum、压缩源路径遍历、兼容模式 HTTP 请求添加精确 `#nosec` 理由；`NewSSRFSafeHTTPClient` / `BlockPrivateNetworks` 仍是处理不可信 URL 的推荐入口。 +- **示例参数解析错误处理**（examples/full/main.go）：示例用户详情接口现在检查 `fmt.Sscanf` 错误，非法用户 ID 返回失败响应，不再静默使用零值。 + +## [1.2.0] - 2026-07-04 + +> 框架整体评估后的结构性修复：4 轮对抗性评审（deepseek / GLM / Claude / 终审）收口的全部 CRITICAL/HIGH/MEDIUM 问题 + 主线A 包级可变全局并发治理统一。 +> 项目处于初级阶段，无下游用户，放心引入破坏性变更。`go vet` + `go build` + `go test -race ./...` 全绿。 + +### Breaking ⚠️ + +- **`database.RedisClient` 不再可外部访问**：包级变量改为 unexported。所有消费者必须通过 `database.GetRedis()` 获取客户端。测试注入使用 `database.SetTestRedisClient(c)` 替代直接赋值。 +- **`xlgo.WithConfig(cfg)` 不再调用 `config.Set(cfg)`**：配置不再写入全局状态。依赖 `config.Get()` 获取注入配置的下游代码需改用 `WithConfigPath`。 +- **`App.Init()` 内部改为 `sync.Once`**：多次调用返回首次执行的结果（含错误），不再是之前的"第二次直接返回 nil"。 +- **`database.DefaultRedis` 类型变更**（database/redis.go）：由 `*RedisManager` 改为 `atomic.Pointer[RedisManager]`，消除裸指针无锁置换的数据竞争（C-1）。下游若直接调用 `DefaultRedis.Init(...)` 等方法需改用 `InitRedis(...)` facade，或 `DefaultRedis.Load().Init(...)`。 +- **`storage.DefaultStorage` 类型变更**（storage/storage.go）：由 `*StorageManager` 改为 `atomic.Pointer[StorageManager]`，与 `config.defaultManager`/`database.DefaultRedis` 并发保护对齐。下游直接调用方法需改用 facade 或 `.Load()`。 +- **`validation.Validator` 类型变更**（validation/validator.go）：由 `*validator.Validate` 改为 `atomic.Pointer[validator.Validate]`，消除无锁读写竞态（H-13）。下游直接读 `validation.Validator.Struct(...)` 需改用 `ValidateStruct(...)`，或 `validation.Validator.Load().Struct(...)`。 +- **`repository.FindWhereOrdered` / `FindPageWhereOrdered` 签名变更**（repository/repository.go）：`args []any` 改为 `args ...any`，与同类方法统一；因 Go 变长参数须为末尾参数，`order` 前置于 `query`。新签名：`FindWhereOrdered(ctx, order, query string, args ...any)`、`FindPageWhereOrdered(ctx, page, pageSize int, order, query string, args ...any)`（H-15）。 +- **`response.Response` 的 `Data`/`RequestID` 去掉 `omitempty`**（response/response.go）：`data` 与 `request_id` 字段在所有响应中恒存在（失败时 `data:null`、未装 RequestID 中间件时 `request_id:""`），下游严格按 schema 解析不再缺字段（M-38/M-39）。 +- **`cache.IsLocked`/`GetLockTTL`/`ForceUnlock` Redis 不可用时改返 `ErrRedisNotReady`**（cache/lock.go，M-E）：原返 `(false/0, nil)` 与"锁确实未占用/已过期"不可区分，调用方可能误以为可获取锁而进入临界区。现统一为：锁操作（正确性相关）Redis 不可用返 `ErrRedisNotReady`，调用方 `errors.Is(err, ErrRedisNotReady)` 区分；cache 数据操作（Get/Set/Incr，性能层）保持 best-effort 静默。 +- **`config.Load()` 返回深拷贝**（config/config.go，M-G）：新增 `(*Config).Clone()` 深拷贝所有切片字段（CORS/Upload/Storage 白名单），`Load()` 与 reload 回调改返 Clone。原"防御性拷贝"为浅拷贝，切片字段与内部 `m.cfg` 共享底层数组，调用方 append/sort/改元素会污染全局。`Get()` 仍返回内部只读指针（热路径零分配），需可变副本用 `Clone()`。 +- **`handler.GetPage` 加 page 上限 10000**（handler/handler.go，M-D）：防 `?page=999999999` 产生超大 OFFSET 拖垮 DB（深分页 DoS）。超过上限钳制到 `MaxPage`，需更深遍历应改游标/keyset 分页。 +- **`utils.EqualsIgnoreCase` 改 `strings.EqualFold`**（utils/strings.go，L-C）：原仅 ASCII 字节折叠，非 ASCII（如 `É`/`é`）误判为不等。现 Unicode 大小写折叠，行为更正确。 +- **`utils.ReadFile` 去 `FileExists` 前置检查**（utils/file.go，M-F）：消除 TOCTOU 竞态，直接 `os.ReadFile`。文件不存在返 `*os.PathError`，调用方改用 `errors.Is(err, os.ErrNotExist)` 判断（原字符串 `"file not found"` 不再返回）。 +- **`database.DefaultManager` 类型变更**（database/manager.go，主线A 收口）：由 `*Manager` 改为 `atomic.Pointer[Manager]`，消除原裸指针（外部直接 `database.DefaultManager = ...` 赋值与请求 goroutine 经 facade 读取）的数据竞争，与 `database.DefaultRedis`/`storage.DefaultStorage`/`cache.defaultCachePtr`/`jwt.defaultManager`/`config.defaultManager` 对齐——框架内包级可变全局一律 atomic.Pointer。新增 `database.SetDefaultManager(m)`（并发安全，替换后关闭旧 manager）、`database.SwapDefaultManager(m)`（并发安全，返回旧 manager 且不关闭）与 `database.GetDefaultManager()`（atomic 读取）。下游若直接调用 `DefaultManager.Init/Master` 等方法需改用 `InitDB`/`GetDB` 等 facade，或 `DefaultManager.Load().Init(...)`，或经 `GetDefaultManager()` 取实例；原 `database.DefaultManager = myDB` 直接赋值改为 `database.SetDefaultManager(myDB)`。 + +### Fixed 🐛 + +#### 第一轮：CRITICAL + HIGH 基金会战 + +- **U1 UUIDShort 生成错误**（utils/uuid.go）：`uuid.New().String()[:32]` 产生的 32 字符保留了 4 个破折号（UUID 格式为 36 字符含 4 个 `-`，`[:32]` 截断末尾 4 个 hex 字符但保留破折号）。改为 `strings.ReplaceAll(uuid.New().String(), "-", "")`，现在正确生成 32 位纯十六进制字符串。 +- **M1 filterSensitiveFields 假过滤**（middleware/logger.go）：旧实现用 `strings.ReplaceAll` 在 key 后面追加 `"[FILTERED]"` 而不删除原始值，导致 `{"password":"mypass"}` → `{"password":"[FILTERED]""mypass"}` 密码仍然可见。改为编译期正则 `sensitiveFieldsRE` 匹配 `"key":"value"` 整体并替换 value 部分为 `[FILTERED]`。 +- **A1 App.Init 并发竞态**（app.go）：`a.initialized` 是普通 bool，并发 `Init()` 调用会同时通过检查导致双重初始化。改为 `sync.Once`，`doInit()` 提取为内部方法，错误通过 `a.initErr` 保存。 +- **D3/CK1 Redis 客户端访问竞态与不一致**（database/redis.go, cache/lock.go）：`database.RedisClient` 全局变量在 `Init`/`Close` 中有锁写入但可被外部无锁读取（数据竞态）；`cache/lock.go` 直接引用 `RedisClient` 而非 `GetRedis()`（绕过 RedisManager 抽象）。修复方案：`RedisClient` → unexported `redisClient`；`GetRedis()` 加入回退逻辑（优先 `DefaultRedis.Client()`，回退内部 `redisClient`）；lock.go 全部改为 `rdb := database.GetRedis()` 单次获取 + nil 检查。 +- **M2 Metrics in-flight gauge 泄漏**（middleware/metrics.go）：`httpRequestsInFlight.Inc()` 后无 `defer Dec()`，handler panic 时 gauge 永久膨胀。改为 `Inc()` 后立即 `defer Dec()`，不依赖 Recover 中间件顺序。 +- **R1 FailWithError 丢弃 Detail**（response/error.go）：`FailWithError` 直接 `writeResp(c, err.Code, err.Message, nil)` 丢弃了 `err.Detail`。改为 `resp := err.ToResponse(); writeResp(c, resp.Code, resp.Msg, resp.Data)`。 + +#### 第二轮：并发纪律红线 + 生命周期/泄漏修复 + +> 来源：glm_check_report_framework.md 结构性评估。聚焦"包级可变全局统一治理"与"重建路径资源释放"两条主线。 + +- **C-1/H-4 `database.DefaultRedis` 并发竞态 + `redisClient` 双源**（database/redis.go）：`DefaultRedis` 改 `atomic.Pointer[RedisManager]`（init Store 兜底），所有 facade 经 `Load()`；废弃 `redisClient` 包级变量，`GetRedis` 单源化；`SetTestRedisClient` 改为在当前 manager 上持锁 `setClientForTest` 替换 client，消除双源真相与无锁写竞态。 +- **H-13 `validation.Validator` 无锁读写**（validation/validator.go）：改 `atomic.Pointer[validator.Validate]`；`InitValidator` 先注册全部自定义规则再 Store，确保 Load 得到的 validator 永远完整。 +- **H-11 + 主线A `storage` 死代码全局 + `DefaultStorage` 裸指针**（storage/storage.go）：删除从未被读取的死代码 `var storage Storage`；`DefaultStorage` 改 `atomic.Pointer[StorageManager]`。 +- **H-10 `response.Error.WithDetail` 并发不安全**（response/error.go）：原实现 `e.Detail = detail` mutate 共享的预定义 `Err*`（并发写竞争 + 全局污染）。改为返回新 `*Error` 拷贝。 +- **H-6 `middleware.RedisRateLimiter.failClosed` 数据竞争**（middleware/ratelimit.go）：改 `atomic.Bool`，`SetFailClosed`/`Allow` 全用 atomic，支持运行期并发切换策略。 +- **H-7 `middleware.GetCSRFToken` 裸断言 + 非恒定时间比较**（middleware/csrf.go）：`token.(string)` 改 comma-ok；CSRF token 比较改 `subtle.ConstantTimeCompare`（两处），防时序侧信道。 +- **H-14/M-64/M-65 `trace.Close` sync.Once 泄漏 + Init 回滚不全**（trace/trace.go）：`Close` 去 `sync.Once` 改 Swap+Shutdown，支持 Close→Init→Close 多轮生命周期（原第二次 Close no-op 致 exporter 泄漏）；`Init` `!Enabled` 分支 Swap+Shutdown 旧 provider；传播器失败时不切 otel 全局（移到成功路径末尾），避免指向已 Shutdown provider。 +- **H-8/H-9 `ws.Hub.Stop` double-close panic + WaitGroup Add/Wait 竞态**（ws/ws.go）：`Stop` 用 `sync.Once` 包 `close(stop)`（删除"stopped 标志"虚假注释）；用 `runDone chan` + `runStarted atomic.Bool` 替代 WaitGroup，消除 `wg.Add(0→1)` 与 `wg.Wait` 的 happens-before 竞态，Stop 先于 Run 调用也不泄漏。 +- **H-1 `app.OnReady` 失败资源泄漏**（app.go）：失败时走 `Shutdown()` 释放 HTTP 端口/后台 goroutine/资源，不再直接 return 致监听 goroutine 永久阻塞。 +- **H-2 `app.Go` + `Init` 失败 goroutine 泄漏**（app.go）：`Init` 失败时 cancel rootCtx + 等 wg（10s 超时兜底），通知已通过 `App.Go` 启动的后台 goroutine 退出。 +- **H-12 `utils.HTTPClient.SetSkipTLS` 数据竞争**（utils/http.go）：加 `sync.RWMutex`；`SetSkipTLS`/`SetTimeout` 写锁下重建 client/transport 并释放旧 transport 空闲连接；`do`/`DoWithResponse`/`Close` 读锁快照后无锁调 `Do`。修复注释自承"需重建 Transport"却未重建的不一致。 + +#### 第三轮：P0 安全阻断 + P1 并发/资源收口（Claude 终审） + +> 来源：claude_check_report_framework.md / claude_check_report_module.md。在 deepseek/GLM 修复后的版本上补审，闭合两者共同漏掉的 JWT 算法混淆等安全默认值问题。 + +- **#1 JWT 算法混淆（alg confusion）**（jwt/jwt.go）：`ParseWithClaims` 统一传 `jwt.WithValidMethods(["HS256","HS384","HS512"])`，keyfunc 内断言 `*jwt.SigningMethodHMAC`，拒绝 alg=none 及非 HMAC 算法（防公钥当 HMAC 密钥伪造 token）。回归 `TestParseTokenRejectsAlgNone`。 +- **#2 JWT 空密钥 fail-closed**（jwt/jwt.go）：新增 `secretKey()`，`GenerateToken*`/`ParseToken*` 空 secret 返 `ErrEmptySecret`。回归 `TestEmptySecretFailsClosed`。 +- **#3 JWT 不支持算法拒绝**（jwt/jwt.go）：`signingMethod` 改返 `(SigningMethod, error)`，RS256 等返 `ErrUnsupportedAlgorithm`，不再静默回退 HS256。回归 `TestUnsupportedAlgorithmFailsClosed`。 +- **#4 上传大小实测封顶**（storage/storage.go）：新增 `enforceUploadSize`/`enforceMaxReader`，本地与 OSS 上传拷贝阶段按实际字节封顶，超限返 `ErrUploadTooLarge` 并清理部分落盘文件。修复原信任客户端 `file.Size` 的绕过。 +- **#5 HTTP header/cookie map 竞态**（utils/http.go）：`SetHeader/SetHeaders/SetCookie` 加写锁，`do/DoWithResponse` 经 `snapshotHeadersCookies()` 读锁快照。 +- **#6 HTTP SSRF 防护**（utils/http.go）：新增 `BlockPrivateNetworks` + `NewSSRFSafeHTTPClient()` + `SetBlockPrivateNetworks()`，经 `net.Dialer.Control` 在连接建立时拦截回环/私有/链路本地/元数据 IP，覆盖重定向每一跳。 +- **#7–#21 P1 并发/资源/泄露收口**：console 写锁（`writeMu`）；config 包级 `Load/LoadWithWatch` `pkgLoadMu` 串行化 + debounce timer Stop；CSRF `ShouldBindBodyWith`（body 可重放）；cron `StopWithTimeout`/`WithCron()` 接入 App 生命周期；database `m.cfg` 经 `getCfg/setCfg` 锁内读写；`isTransientDBError` 移除过宽 `"database"` 子串；router `applyOnce sync.Once` + 版本 map 排序；logger `filterSensitiveQuery` 脱敏；response `SetExposeDetail`（生产隐藏 Detail）；validation 密码 MaxLength=72 + phone 全数字 + `RegisterValidation` `must` 检查；trace noop 包 + `defer span.End()` + `[unmatched]` 低基数 span 名；storage `NewLocalStorage` Abs fail-closed；cmd/xlgo 项目名/模块路径校验 + `os.Exit(1)` + 失败回滚。 + +#### 第四轮：终审剩余项收口（last_report.md） + +> 来源：last_report.md 终审。在第三轮基础上逐项回读核实后修复，均经 `go test -race` 验证。 + +- **H-A 从库连接池上限截断**（database/manager.go）：`MaxOpenConns/2` 在配置为 1 时得 0（`database/sql` 视 0 为无限制），与"从库减少"意图相反、资源失控。新增 `replicaMaxOpenConns()`：`>0` 取 `max(1, /2)`，`<=0` 与主库一致无限。 +- **H-B `router.GroupWithMiddlewareGroup` nil panic**（router/router.go）：改走 `ensureRegistry()`（与其他全局 helper 一致），把未初始化 nil 解引用 panic 转成可定位错误。 +- **M-A JWT 黑名单无超时 + 吞错**（jwt/jwt.go）：`Add`/`IsBlacklisted` 改用 `context.WithTimeout(1s)`（`blacklistCtx`），把鉴权路径阻塞上限收敛到 1s；`IsBlacklisted` 用 `.Result()` 替代 `.Val()` 显式处理错误（fail-open 保留但记录告警）。 +- **M-B `Recover` 响应已写出时无效写 500**（middleware/recover.go）：加 `c.Writer.Written()` 守卫，已写出时仅 Abort + 记录，避免流式/部分写场景下 `response.Custom` 沦为 no-op 致客户端收到截断响应。 +- **M-C `RedisRateLimiter` 多次 `GetRedis()` nil-deref 窗口**（middleware/ratelimit.go）：`Allow`/`GetCount`/`Reset` 改为取一次 `rdb` 复用，消除两次调用间 `CloseRedis` 致第二次 nil-deref 的窗口。 +- **M-D `handler.GetPage` 深分页 DoS**（handler/handler.go）：加 `page` 上限 `MaxPage=10000`（见 Breaking）。 +- **M-E Redis 不可用失败语义统一**（cache/lock.go，见 Breaking）：锁操作返 `ErrRedisNotReady`；`IsLocked` 用 `.Result()` 返错（合并 L-G）。 +- **M-F `HashFile`/`ReadFile` OOM 与 TOCTOU**（utils/crypto.go, utils/file.go）：`HashFile` 改流式 `io.Copy(h, f)`（恒定内存，可哈希任意大文件）；`ReadFile` 去 `FileExists` 前置检查（见 Breaking）。 +- **M-G `config.Get()` 返回内部指针切片别名**（config/config.go，见 Breaking）：新增 `Clone()`，`Load()` 与 reload 回调返深拷贝；`Get()` 保持热路径零分配返只读指针。 +- **M-H `cron.checkAndRun` 持锁 spawn 阻塞管理 API**（cron/cron.go）：锁内只收集到期任务（CAS + 推进 NextRun + `wg.Add`），锁外 spawn。`wg.Add` 必须在锁内以保证 `Stop` 的 `wg.Wait` 等到本批（否则 Stop 可能在任务间提前返回、后启动 goroutine `wg.Done` 下溢 panic）。 +- **L-A compress 解压残留文件**（compress/compress.go）：`GzipDecompressFileWithOptions`/`unzipFile` 失败时（超限/拷贝错误）`os.Remove` 部分落盘文件，避免被拒炸弹遗留残片。 +- **L-B utils 正则重编译**（utils/validator.go）：`IsPhone`/`IsEmail`/`IsIPv4`/`IsIDCard` 正则提为包级 `MustCompile`，避免每次调用重编译。 +- **L-C `EqualsIgnoreCase` 非 ASCII 误判**（utils/strings.go，见 Breaking）：改 `strings.EqualFold`。 +- **L-D `redisLimiters` 死代码**（middleware/ratelimit.go）：删除从未被读写的包级 `redisLimiters` map 与其 `init()`。 +- **L-E `logger.Logger` 导出变量**（logger/logger.go）：标 `Deprecated:`，引导用包级 `Info/Debug/...` 函数（atomic 读取，并发安全）。 +- **L-H `ws.SetCheckOrigin` 无锁写**（ws/ws.go）：文档明确"仅启动前调用"，运行期切换 Origin 用自有 upgrader 实例。 +- **L-J `cron.RunTask` 用 `s.ctx`**（cron/cron.go）：文档说明 Stop 后 handler 收到 canceled ctx 的预期行为。 + +> **未修（评估后决定）**：L-K `model` 时间戳 `omitempty`——`encoding/json` 对 `time.Time`（结构体）的 `omitempty` 是 no-op，报告建议的修复无效；真正的修复需改 `*time.Time`（破坏性 + nil 安全隐患），收益与成本不匹配，暂不做。L-I `response.writeResp` nil-c 守卫——nil `*gin.Context` 是程序员错误，panic 是恰当反馈，加静默守卫反而掩盖 bug。L-F/L-M/L-N/L-O 为文档/命名类，已就地注释说明或属设计取舍。 + +### Changed 🔄 + +- **`database.GetRedis()` 加入回退逻辑**：优先返回 `DefaultRedis.Client()`，若未初始化则回退到内部 `redisClient`（测试注入路径）。确保 `SetTestRedisClient` + `GetRedis()` 闭环。 +- **`database.SetTestRedisClient(c)` 新增**：供测试注入 mock Redis 客户端，返回旧值便于清理恢复。 + +--- + +## [v1.1.1] - 2026-06-28 + +> v1.1.1 后的安全/正确性补丁，依据 `version_1.1.1_report.md` 权威缺陷清单逐项修复（13 CRITICAL + 8 HIGH）。 + +### Fixed 🐛 + +#### P3 清理第三批（MEDIUM/MINOR 收尾） + +> 续前两批。本批为校验收紧、全局状态并发、Windows 控制台、trace 遗留、logger 级别、测试质量。`go test -race` + `go vet` + `gosec` 通过。 + +- **M5 身份证无校验位 + 用户名首字节**（validation/validator.go）：18 位身份证补 GB 11643-1999 校验位验证（`validateIDCardChecksum`），原仅查长度+格式可被任意构造通过；`username` 验证首字符改按 `[]rune` 取，避免非 ASCII 首字节误判（原 `rune(username[0])` 取字节）。 +- **M13 cache globalKeyBuilder 无锁 + 无 sync.Once**（cache/keybuilder.go）：`globalKeyBuilder` 加 `sync.RWMutex` 读写保护，`GetKeyBuilder` 用 `sync.Once` 保证自动初始化只执行一次，消除 check-then-init 竞态。`SetPrefix` 补实例非并发安全注释。 +- **M12 NewRedisCache 构造时快照 client**（cache/cache.go）：`redisCache` 不再构造时 `database.GetRedis()` 快照（Init Redis 之前构造则永久 nil no-op），改每次操作实时取 client，使"先构造后 Init Redis"顺序也能正确工作。 +- **M18 trace 显式设 codes.Ok + Close 无 double-close 守卫**（trace/trace.go）：成功路径不再 `SetStatus(codes.Ok, "")`（OTel 规范默认 UNSET，显式 Ok 会掩盖子 Span 错误状态）；`Close` 用 `sync.Once` 保证只 Shutdown 一次，重复调用安全。 +- **M19 logger 无法显式设级别**（logger/logger.go）：三个 core（app/api/db/console）改共享 `zap.AtomicLevel`，新增 `LogManager.SetLevel`/`GetLevel` + 包级 `SetLevel`/`GetLevel`，支持运行期热切换日志级别。 +- **M17 console_windows 死代码 + 着色句柄分裂**（console/console_windows.go）：移除从未被调用的 `EnableVirtualTerminal`；`printColor` 原对 `syscall.Stdout` 设置颜色、文本却写 `c.output`（非 stdout 时二者分裂），改为按 `c.output` 实际类型取句柄（`*os.File` 用 Fd，否则退化为纯文本）。 +- **N2 repository_test 空壳**（repository/repository_test.go）：原全为注释空壳、CRUD 零覆盖，改为编译期断言 `var _ BaseRepository[T] = (*BaseRepo[T])(nil)` 锁定接口契约（实现与接口漂移即编译失败）。 +- **N3 test MockStorage 签名不符 + SetupRouter 文档**（test/test.go）：`MockStorage.Upload` 签名对齐真实 `storage.Upload(file *multipart.FileHeader, subdir)`，新增 `UploadFromBytes` 对齐 `storage.UploadFromBytes`；`SetupRouter` 补文档说明刻意返回裸 `gin.New()`（不含框架中间件，由测试方控制）。 +- **Added**：`logger.LogManager.SetLevel`/`GetLevel`、`logger.SetLevel`/`GetLevel`、`validation.validateIDCardChecksum`（未导出）。无 breaking（新 API；身份证校验位收紧可能拒绝先前"格式正确但校验位错"的输入——这正是修复目的）。 + +#### P3 清理第二批（MEDIUM/MINOR 文档/正确性/校验） + +> 续上一批。本批以正确性修复 + 文档/命名澄清为主，风险分级处理，`go test -race` + `go vet` + `gosec` 通过。 + +- **M4 datetime StartOfWeek DST 落错日**（utils/datetime.go）：原用 `t.Add(-N*24h)` 回退到周一，DST 切换日 24h ≠ 1 个日历日会落错日。改为按日历日 `time.Date(..., Day-(weekday-1), ...)` 计算，保留原时区。`ParseDateInt` 补注释说明非法输入会被 time.Date 静默规范化、调用方须校验。 +- **M11 HealthCheck 同步 ping 无超时 + WriteQuery 命名误导**（database/manager.go）：包级 `HealthCheck()` 的 `sqlDB.Ping()` 改 `pingWithTimeout`（3s 超时，尊重调用方 ctx deadline），避免探针被慢/挂起的 DB 长期阻塞。`WriteQuery` 补注释说明其命名沿用历史、实际为读取语义（强制主库 read-your-writes）。 +- **M9 DSN 密码不转义 + 时区硬编**（config/config.go）：MySQL DSN 密码改 `url.QueryEscape`，Postgres DSN 密码改单引号包裹+内嵌单引号翻倍，避免含 `@`/`:`/空格/引号 的密码破坏 DSN。新增 `DatabaseConfig.Timezone` 字段（MySQL loc / Postgres TimeZone 可配，空则保持原默认 `Local`/`Asia/Shanghai` 向后兼容）。 +- **M7 ToResponse 丢 Detail**（response/error.go）：`Error.ToResponse()` 把 `Detail` 放入 `data.detail`（非空时），不再丢失细节信息。 +- **M14 timeout 软超时文档化**（middleware/timeout.go）：注释明确软超时语义——仅注入带 deadline 的 ctx，不主动中断 handler；纯 CPU/不查 ctx 的 handler 不生效，硬中断需配合 `http.Server.WriteTimeout` 或 handler 内 `select ctx.Done`。 +- **C3 收尾：生产者取消信号契约**（sse/sse.go）：包文档化断连契约——框架消费循环已监听 `c.Request.Context()` 断连即退，但生产者（LLM 流）必须自行监听同一 ctx 在取消时停止，否则上游持续运行浪费算力。`StreamText` 注释已有，补包级 doc。 +- **M20 生成器非法标识符 + fileExists 权限误判**（cmd/xlgo）：`make handler my-thing` 原 `cases.Title` 得 `My-ThingHandler`（非法标识符）；新增 `sanitizeIdent` 把非字母数字转下划线再 Title，得 `MyThingHandler`。`fileExists` 注释澄清权限错误的判定语义。 +- **N1 BaseModelWithTime 命名误导**（model/base.go）：补注释说明与 BaseModel 唯一区别是 `type:datetime`（部分 MySQL 丢毫秒），名字 "WithTime" 易误导，保留仅为兼容。 +- **N4 Nl2br 死分支 + IsEmpty 文档不符**（utils/）：`Nl2br` 的 `case '\n'` 内 `r == '\r'` 半恒假（r 恒为 '\n'）已清理；`IsEmpty` 文档原称支持 slice/map 但实现仅支持 string/[]byte/nil，文档修正为实际行为。 +- **N6 sse KeepAlive 触发 onmessage**（sse/sse.go）：心跳由 `data: \n\n`（触发客户端 onmessage）改 SSE 注释行 `: ping\n\n`（不产生消息事件，更符合心跳语义）。 +- **Added**：`config.DatabaseConfig.Timezone`。无 breaking（Timezone 零值保持原默认时区）；DSN 密码转义对合法密码无影响（无特殊字符的密码转义后不变）。Postgres DSN 格式变更（password 加单引号）对下游 GORM 透明。 + +#### P3 安全/正确性轻量清理（一批 MEDIUM/MINOR） + +> 风险分级处理：安全与逻辑正确性项实际修复 + 针对性用例；纯文档/感知项仅加注释。全部经 `go test -race` + `go vet` + `gosec` 验证。 + +- **M15 requestid 头注入**（middleware/requestid.go）：原无条件信任客户端 `X-Request-ID`，可注入 CRLF 伪造响应头/日志。新增 `sanitizeRequestID`：仅接受可见 ASCII（0x20-0x7e）、无换行、长度 ≤128，非法则忽略并重新生成。合法 ASCII ID 仍沿用客户端值（向后兼容）。 +- **C7/N7 ws CheckOrigin 默认 true（CSWSH）**（ws/ws.go）：默认 `CheckOrigin` 由恒 `true` 改为同源校验（空 Origin 放行非浏览器客户端、否则要求 Origin host 与请求 Host 一致），防 Cross-Site WebSocket Hijacking。新增 `AllowOrigins(origins...)` 辅助多可信域名场景。**Breaking ⚠️**：原默认放行所有跨域 WS 连接，现拒绝跨域；依赖跨域 WS 的下游需用 `ws.SetCheckOrigin` 或 `ws.AllowOrigins(...)` 显式放行。 +- **C5/N5 HTTPClient Upload FD 累积 + 响应体无上限**（utils/http.go）：`Upload` 循环内 `defer file.Close` 改为显式关闭，避免大批量上传累积 FD；`do` 的 `io.ReadAll(resp.Body)` 改 `io.LimitReader` 封顶（默认 32MB，可经 `HTTPClientConfig.MaxResponseBodySize` 配置，-1 不限），防异常服务端返回超大响应打爆内存。 +- **M16/B18 压缩写侧 defer Close 吞错**（compress/compress.go）：`GzipCompressFile`/`Zip` 的 `defer gz.Close()`/`defer zipWriter.Close()`/`defer archive.Close()` 改为显式关闭并向上传播错误——flush 失败（归档损坏）不再被吞成成功返回。 +- **M6 Download 中文文件名乱码**（response/response.go）：`Content-Disposition` 由直接拼接 `filename=` 改为 RFC 5987：同时给 ASCII 回退 `filename="..."` 与 UTF-8 百分号编码 `filename*=UTF-8''...`，中文等非 ASCII 文件名不再乱码。 +- **M8 CodeDataAlreadyExists 状态不一致**（response/mode.go）：`CodeDataAlreadyExists` 在 ModeREST 下原落 200，与同语义的 `CodeDataConflict`(409) 不一致。映射到 409 Conflict。 +- **M10 driver 拼写错误静默回退 MySQL**（database/dialect.go）：未注册驱动回退 MySQL 时新增 `logger.Warnf` 告警（含已注册驱动列表），避免拼错 driver 名（如 `postgrs`）静默回退导致连接错误难排查。 +- **M2 AddQueries 实为 Set**（utils/url.go）：`AddQueries` 原用 `query.Set`（覆盖同名），与 `AddQuery`（追加）语义不一致。改为 `query.Add`，同 key 多值共存。 +- **M3 file.go 路径穿越感知**（utils/file.go）：文件工具函数加包级文档警告——直接操作调用方路径不做穿越校验，不可信输入须调用方自行净化（框架 storage 包已做防护）。 +- **Added**：`ws.AllowOrigins`、`utils.HTTPClientConfig.MaxResponseBodySize`。**Breaking**：`ws` 默认 CheckOrigin 收紧为同源（见 C7）。无配置/migration 变更（MaxResponseBodySize 零值默认 32MB）。 + +#### H6：`repository/repository.go` BaseRepo 不接 GetDBFromContext + 读写分离失效 + 事务无法 join + 分页不一致（repository/repository.go, database/manager.go） + +`BaseRepo` 构造时捕获 `r.db`，所有方法 `r.db.WithContext(ctx)` 从不调 `database.GetDBFromContext` → 读写分离形同虚设（读全走主库）、外层 ctx 事务无法 join、`WithTransaction` 内方法走 `r.db` 拿不到事务。叠加 `Update` 用 `Save` 全列覆写（H6a）、`FindPage` 的 count+list 为两条独立语句高并发下 total/items 不一致（H6d）、`QueryBuilder` 终结方法未克隆且 `Count` 受残留 Limit/Offset 截断（H6e）。修复： + +- **H6c 连接路由**：新增 `readConn(ctx)`/`writeConn(ctx)`，优先级为「外层 ctx 事务（`database.TxFromContext`）> 本 repo 事务（`r.tx`）> 路由 db > `r.db` 回退」。读走 `database.GetDBFromContext`（默认从库，支持 `UseMaster`/`UseReplica`），写走 `database.GetWriteDB()`（主库，不路由到只读从库）。`DefaultManager` 未初始化（如单测注入 sqlite）时回退 `r.db`，兼容下游 `NewBaseRepo[T](database.GetDB())`。 +- **H6c 事务 join**：`BaseRepo` 新增未导出 `tx` 字段；`WithTransaction` 创建 `txRepo` 时注入 `tx`，其方法自动 join 事务。新增 `database.WithTx(ctx, tx)`/`TxFromContext(ctx)` 支持跨层/跨 repo join（外层 `database.TransactionWithContext` 拿到的 tx 经 `WithTx` 注入 ctx 后传给 repo 方法即可参与同一事务）。`WithTransaction` 签名**不变**。 +- **H6a 局部更新**：新增 `UpdateFields(ctx, model, conds...)` 基于 `gorm.Updates`（struct 仅更新非零字段、map 可显式置零），避免 `Save` 全列覆写丢失更新/零值不可辨。`Update`（Save）保留并文档化其全列覆写语义。 +- **H6b 软删除契约**：`Delete` 文档化行为契约——`T` 内嵌 `gorm.DeletedAt`/`gorm.Model` 时软删除，否则硬删除（泛型类型约束无法编译期强制）。 +- **H6d 分页一致性**：`FindPage`/`FindPageOrdered`/`FindPageWhere`/`FindPageWhereOrdered` 的 count+list 包进单事务（同一快照），消除高并发下 total/items 不一致。 +- **H6e QueryBuilder 克隆**：终结方法（`Find`/`First`/`Count`/`Page`）基于 `Session(&gorm.Session{})` 克隆，不污染 `qb.db`；`Count`/`Page` 的 count 额外 `Limit(-1).Offset(-1)` 剥离残留分页条件。文档标注 QueryBuilder 单次使用、非并发安全。 +- **Added**：`database.WithTx`/`database.TxFromContext`、`repository.BaseRepo.UpdateFields`。无既有 API 签名/配置/migration 变更（非 breaking）。行为变更：读操作默认路由到从库（原全走主库）、写操作显式走主库、分页查询包单事务（每页一次 BEGIN/COMMIT，见下）。 + +#### C10：`config/config.go` 全局 Manager 无锁置换 + 热重载绕过 Validate + StopWatcher 空函数（config/config.go） + +- **C10a 全局 Manager 无锁置换**：包级 `defaultManager` 原为裸 `*Manager` 指针，`Load`/`LoadWithWatch`/`SetDefaultManager` 直接赋值，与 `Get`/`GetViper`/`GetString` 等请求 goroutine 的无锁读存在数据竞争。改为 `atomic.Pointer[Manager]`，所有包级便捷函数经 `Load()`/`Store()` 原子读写。 +- **C10b 热重载绕过 Validate**：`OnConfigChange` 与 `Reload` 原均不调 `Validate()`（仅 `Load` 调用），非法配置（坏端口、负超时、短密钥）直接发布。`Reload` 与文件监听路径统一走 `reload()`：读取/解析/校验任一步失败均保留旧配置并返回错误，仅新配置通过 `Validate` 后才替换 `m.cfg` 并触发回调。 +- **C10c Load 返回可变指针**：`Load` 原返回 `&cfg` 与 `m.cfg` 同一指针，调用方可变并竞争。改为返回防御性浅拷贝，调用方修改返回值不污染全局读取路径。 +- **C10d StopWatcher 空函数**：原 `StopWatcher()` 为空，viper 内部 watcher goroutine + fd 永不释放。改为自管 `fsnotify.Watcher`（监听配置文件所在目录以兼容编辑器改写/k8s ConfigMap 原子替换，按文件名过滤 + 200ms 去抖），`StopWatcher` 关闭 watcher 并等待监听 goroutine 退出（`watchDone`），幂等。废弃 viper `WatchConfig`/`OnConfigChange`。 +- 无 API 签名/配置结构变更；行为变更（热重载非法配置保留旧配置而非发布、StopWatcher 真正释放监听资源）。 + +#### C11：`database/manager.go` 池泄漏 + Master/Replicas 无锁读 + 健康状态陈旧（database/manager.go） + +- **C11b InitDB 重试泄漏**：`InitDB` 原直接 `m.master = gorm.Open(...)`，`gorm.Open` 成功但 `Ping` 失败时旧池不关、下轮覆盖 `m.master`，每次重试泄漏一池。改为先打开到局部变量，仅 `Ping` 通过后才在锁内安装为 `m.master` 并关闭旧主库池；`Ping`/`DB()` 失败时关闭刚打开的池。 +- **C11c InitDBWithReplicas 泄漏**：原 `m.replicas = nil` 前不关旧从库池，且从库 `DB()`/`Ping` 失败时 `continue` 不关刚打开的池。改为重建前在锁内取出旧从库、重置健康状态后逐个 `closeDB`；从库构建失败时关闭刚打开的池；新从库先构建到局部切片再原子安装。 +- **C11a 健康状态陈旧**：`initReplicaHealth` 的 `replicaHealthSet` 早返回使重新 `InitDBWithReplicas` 后健康切片与新 replicas 长度错位。新增 `resetReplicaHealth`，`InitDBWithReplicas`/`Close` 重建/关闭前调用，使下次 `initReplicaHealth` 按新 replicas 长度重建。 +- **C11d Master/Replicas 无锁读**：`Master()`/`Replicas()` 原裸读 `m.master`/`m.replicas`，与 `Close`/`InitDB` 写竞争。改为全程持 `m.mu` 锁；`Replicas()` 返回拷贝；`Replica()` 的空从库判断移入锁内；`FromContext`/`HealthCheck`/`Transaction`/`TransactionWithContext`/`WriteQuery`/包级 `HealthCheck` 改经 `Master()`/`Replicas()` 读取；`probeOnce` 快照 `replicaHealthy` 切片头避免与重置竞争。 +- **C11f 包级 Close 仅关主库**：包级 `Close()` 原仅关 master 且无锁，命名误导致从库泄漏。改为委托 `CloseAll()`（关主+从并重置健康状态）。 +- **C11e（非缺陷）**：`RoundRobinPicker` `int(n-1)%len` 取模后仍在 `[0,len)` 内，无 panic/正确性问题；`RandomPicker` 全局 `math/rand` 仅锁竞争。属微优化，非功能 bug，未改。 +- 无 API 签名/配置结构变更；行为变更（包级 `Close` 现关闭从库、`InitDB` 重试/重建不再泄漏旧池、`Master`/`Replicas` 加锁读取）。gosec G115/G404 为 `RoundRobinPicker`/`RandomPicker` 既有项（C11e 范围外）。 + +#### C9c：`jwt/jwt.go` 包级 `DefaultJWT`/`tokenBlacklist` 无锁置换（jwt/jwt.go） + +`SetDefaultJWTManager` 原裸写包级 `DefaultJWT`/`tokenBlacklist`，与请求 goroutine（`ParseToken`/`RefreshToken`/`InvalidateToken`/`InvalidateTokenByID`/`IsTokenRevoked` 读 `tokenBlacklist`）存在数据竞争（C9c，C9a/b 已在 C9b 修复 fail-closed，此项是遗留并发隐患）。修复： +- 新增内部 `defaultManager atomic.Pointer[Manager]` 作真实存储，`init()` Store；包级函数经 `currentManager()`/`currentBlacklist()`（atomic 读取）访问，消除裸指针读写竞争。 +- `SetDefaultJWTManager` 改用 `defaultManager.Store(m)` 原子置换；移除裸写的包级 `tokenBlacklist` 变量。 +- `DefaultJWT` 保留为导出 `*Manager` 兼容别名（类型不变，非 breaking），由 `SetDefaultJWTManager` 同步维护；注释标注直接读 `DefaultJWT` 非并发安全，并发访问应用包级函数或 `SetDefaultJWTManager`。 +- 无 API 签名变更；`DefaultJWT` 类型不变（非 breaking）。行为变更：包级黑名单读写改经 atomic，`SetDefaultJWTManager` 可安全在请求期调用。 + +#### H3：`middleware/logger.go` 请求/响应 body 无上限读 → OOM（middleware/logger.go） + +`LoggerWithConfig` 在 `LogRequestBody:true` 时用 `io.ReadAll(c.Request.Body)` 无封顶读入内存，`MaxBodyLength` 仅在读完后截断**日志副本**，全 body 已驻留并二次 buffer——多 GB POST 可 OOM；响应侧 `bodyLogWriter.body` 同样无上限累积。默认 `LogRequestBody:false` 使默认安全，但 `LoggerForAPI`/`LoggerForDebug` 显式开启即暴露。修复： +- 请求体新增 `readBodyBounded(c, maxLen)`：`io.LimitReader(body, maxLen+1)` 仅向内存读入最多 `maxLen+1` 字节（+1 检测截断），通过 `io.MultiReader(已读前缀, 原始 body 剩余)` 复原 `c.Request.Body`——**下游处理器仍得完整请求体**；日志副本截断到 `maxLen`。 +- 响应体 `bodyLogWriter` 增 `maxLen` 字段，捕获缓冲区封顶；`Write`/`WriteString` 仍把完整响应写入下游 `ResponseWriter`，仅捕获缓冲区封顶。 +- `LoggerWithConfig` 入口归一化 `MaxBodyLength`：`<=0` 时回退默认值（1024），确保请求/响应两侧捕获均有上限，消除手配 `MaxBodyLength:0` 时响应侧无上限的 OOM 残留路径。 +- 无 API 签名/配置结构变更；行为变更：`MaxBodyLength` 现同时门控响应体捕获（此前响应侧无视该值无上限累积，属 bug 修正）；`MaxBodyLength<=0` 不再意味"无上限"，统一回退默认上限。 + +#### H7：`logger/logger.go` 全局指针写有锁读无锁 + `Field.Duration` 签名与实现矛盾（logger/logger.go, logger/field.go） + +`Init`/`Close` 持 `m.mu`（实例锁）写包级 `Logger`/`sugar`/`apiLog`/`dbLog`，但 `Info`/`Error`/`APILog()`/`DBLog()`/`Sync` 等请求期函数无锁裸读——锁与被保护对象作用域错配（实例锁保护包级全局变量），热重载 re-Init/Close 与请求日志存在数据竞争（H7a）。另 `Field.Duration` 签名为 `func(key string, value interface{})`，`case zap.Field` 分支 `return v` 丢弃 `key`，签名与实现矛盾（H7b）。修复： +- **H7a**：新增内部 `loggerPtr`/`sugarPtr`/`apiLogPtr`/`dbLogPtr atomic.Pointer[...]` 作真实存储，`init()` Store 为 Nop；`Info`/`Debug`/`Warn`/`Error`/`Fatal`/`Debugf`-`Fatalf`/`APILog`/`DBLog`/`Sync` 读路径统一经 `currentLogger()`/`currentSugar()`/`currentAPILog()`/`currentDBLog()`（atomic Load，nil 防御回退 Nop），消除请求期裸读竞争。`Init`/`Close` 在 `m.mu` 下 Store atomic。 +- **H7a 兼容别名**：`Logger` 保留为导出 `*zap.Logger` 兼容别名（类型不变，非 breaking），由 `Init`/`Close` 在 `m.mu` 下同步维护；注释标注直接读 `Logger` 变量在 re-Init/Close 期间非并发安全，并发访问应用包级函数。 +- **H7b**：`Field.Duration` 签名改为 `func(key string, value time.Duration) zap.Field`，直接委托 `zap.Duration(key, value)`，类型安全、key 不再可能被丢弃。 +- 顺带收紧 `os.MkdirAll` 日志目录权限 `0o755`→`0o750`（与 storage 目录权限一致，gosec G301）。 +- 无 API 签名/配置结构变更（`Logger` 类型不变）；行为变更：包级日志读路径改经 atomic，re-Init/Close 可安全与请求日志并发。`Field.Duration` 签名变更为**类型收紧**（`interface{}`→`time.Duration`），旧调用方传 `time.Duration` 不受影响，传 `zap.Field` 等非 Duration 类型将编译失败（属修复目的）。 + +#### C12：`cron/cron.go` 数据竞争 + 重叠执行 + 漂移 + Weekly 跳周 + cron 解析缺陷（cron/cron.go） + +`cron/cron.go` 存在 5 子项缺陷（C12a–C12e）。修复： +- **C12a 数据竞争**：`runTask` 原无锁写 `LastRun`/`RunCount`，`GetTask`/`ListTasks` 返回 live 指针并发读 → data race。改为 `LastRun`/`RunCount`/`NextRun` 写入一律在 `s.mu` 写锁内；`GetTask`/`ListTasks` 返回拷贝快照（`cp := *task`）。 +- **C12b 无重叠守卫**：`checkAndRun` 每秒 tick，长任务跨 tick 被反复 spawn 同一任务并发执行。新增 per-task `running *atomic.Bool` 守卫，`checkAndRun` 与 `RunTask` 均经 `CompareAndSwap(false,true)` 占用，正在执行则跳过/返错。 +- **C12c Interval 漂移**：`NextRun` 原在 handler 完成后以 `time.Now()` 锚定，每周期累积 handler 时长。改为 `checkAndRun` spawn 前 `task.NextRun = task.Schedule.Next(task.NextRun)`（以上次 `NextRun` 锚定），`runTask`/`RunTask` 不再更新 `NextRun`。 +- **C12d Weekly 跳周**：原 `daysUntil <= 0 → +7` 仅按 weekday 差值，不比较当天时刻，当天目标未到点被跳一周。重写为 `((day-now)+7)%7` 加天数后 `!next.After(now)` 才 +7，当天未到点返回本周、已过返回下周。 +- **C12e cron 解析缺陷**：`parseInt` 忽略非数字逐位累积，`1-5,8` 因先判 `-` 被当范围（`parseInt("5,8")=58`）、`garbage`→0 误触发、`*/garbage`→step=0 匹配全部、周日 `7` 不匹配。重写 `matchField`：列表分支独立于范围分支（先按逗号拆，每项判 `*/n`/`a-b/n`/`a-b`/单值），全用 `strconv.Atoi` 返错；weekday `7→0`，范围 `lo>hi` 环绕；歧义范围 `0-7`/`7-0` 拒绝。新增 `ParseCronStrict(expr) (*FullCronSchedule, error)` 严格校验；当前 Unreleased 已进一步将 `ParseCron` 非法输入改为 fail-fast panic，旧版回退默认全 `*` 的兼容语义迁移到 `ParseCronOrDefault`。 +- 无 API 签名变更（`ParseCron` 仍返 `*FullCronSchedule`，`AddTask`/`RunTask`/`GetTask`/`ListTasks` 签名不变）；新增 `ParseCronStrict`（非 breaking）。`Task` 新增未导出 `running` 字段（外部不可构造）。行为变更：`GetTask`/`ListTasks` 返回拷贝（修改返回值不影响内部状态）；`RunTask` 占用守卫期间再次调用返"任务正在执行中"错误；长任务不再重叠；调度不漂移；Weekly 当天未到点不再跳周；cron 解析拒绝非法表达式。 + +#### C13：`trace/trace.go` opt-in 即崩 + 未实现导出器/传播器 + Middleware 不更新 c.Request（trace/trace.go） + +`trace/trace.go` 存在 5 子项缺陷（C13a–C13e）。修复： +- **C13a nil tracer panic**：包级 `tracer`/`tracerProvider` 原为裸指针，未 `Init` 即 nil，`Middleware`/`StartSpan`/`StartSpanFromContext`/`GetTracer` 裸用 → 首个请求 panic。改为 `atomic.Pointer` + `init()` Store Noop 兜底，`getTracer()` 永不 nil；`Init` 原子替换，`Close` Shutdown 后 Store 回 Noop（防 Close 后再用 panic）。`GetContext` 裸断言改 comma-ok。 +- **C13b 未知导出器 + stdout 缺失**：`createExporter` `default` 原返 `nil, nil` 喂 `WithBatcher(nil)`，文档承诺的 `stdout` 未实现。新增 `case "stdout"`（官方 `stdouttrace` 包）；`default` 返 `fmt.Errorf`（不再喂 nil）。 +- **C13c OTLP 默认 HTTPS 无 WithInsecure**：`Config` 增 `Insecure bool`（零值 false=TLS，opt-in 明文，安全默认）；`Insecure` 时 otlp-http/otlp-grpc 追加 `WithInsecure()`，对 `localhost:4318` 等明文 collector 不再握手失败。 +- **C13d Middleware 不更新 c.Request**：原仅 `c.Set("otel_ctx", ctx)`，下游 `c.Request.Context()` 拿不到 span。补 `c.Request = c.Request.WithContext(ctx)`（保留 `c.Set` 兼容）。 +- **C13e b3/jaeger 未实现**：`createPropagator` 原仅 `w3c` + default 静默回落 W3C。新增 `case "b3"`（contrib b3 propagator，单头+多头）；`case "jaeger"` 映射 W3C TraceContext（现代 Jaeger agent 透传 W3C，不引入不稳定的 jaegerremix 模块）；`default` 返错（不再静默回落）；`Init` 在非法 propagator 时返错并回滚已创建 provider。 +- 顺带修复 `resource.Merge` SchemaURL 冲突（`resource.Default()` 与 `semconv v1.24.0` schema 不一致致 `Init` 报错）——改用空 schema URL 合并属性。 +- 新增依赖：`go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.43.0`、`go.opentelemetry.io/contrib/propagators/b3 v1.43.0`（均与 OTel core v1.43.0 同版本族）。 +- 无 API 签名变更（`Init`/`Middleware`/`StartSpan`/`GetTracer`/`Close` 签名不变）；`Config` 新增 `Insecure` 字段（零值兼容，非 breaking）。行为变更：未 Init 不 panic；未知导出器/传播器返错；`Insecure` opt-in 明文；Middleware 更新 c.Request；b3 实现、jaeger 映射 W3C。`Propagator` 空字符串现按 `w3c` 处理（兼容）。 + +#### H5：`handler` 业务码与 HTTP 状态混乱 + 丢失 RequestID（handler/handler.go） + +`handler.BadRequest`/`handler.InternalError` 原直接 `c.JSON(http.StatusBadRequest/StatusInternalServerError, response.Response{...})`：硬编 HTTP 400/500 **绕过响应模式系统**（ModeBusiness 下所有失败响应本应 HTTP 200，错误经 body code 表达），且不写 `RequestID`（对比 `response.writeResp` 在 mode.go:73 写入）——与 `response` 体系不一致、丢失链路追踪。这正是"handler 绕过 response 模式系统"反模式。修复： +- `BadRequest` 委托 `response.FailWithCode(c, CodeFail, msg)`，`InternalError` 委托 `response.ServerError(c, msg)`——复用 `writeResp` 路径，遵循当前 `Mode` 并写入 `RequestID`。 +- 无 API 签名变更；`net/http` 导入随之移除。行为变更见下方升级说明。 + +#### H4b：`middleware/ratelimit.go` CustomRateLimit goroutine 泄漏（middleware/ratelimit.go） + +`CustomRateLimit` 每次调用 `NewRateLimiter`（启动一个 cleanup goroutine）但创建的 limiter 无任何句柄，`StopRateLimiters` 仅停止 `loginLimiter`/`apiLimiter`/`uploadLimiter` 不感知自定义限流器 → cleanup goroutine 永久泄漏。修复： +- 新增包级 `customLimiters []*RateLimiter` 登记表（受 `limitersMu` 保护）；`CustomRateLimit` 创建后登记入表。 +- `StopRateLimiters` / `InitRateLimiters` 经 `drainCustomLimiters()` 取出并停止已登记的自定义限流器，释放 cleanup goroutine。 +- 无 API 签名变更；无行为变更（仅修复 goroutine 泄漏，限流语义不变）。`StopRateLimiters` 现可正确停止所有自定义限流器（与 H4a 报告建议一致）。 + +#### H4c：`middleware/ratelimit.go` RedisRateLimiter fail-open + 裸断言（middleware/ratelimit.go） + +`RedisRateLimiter.Allow` 原有两个缺陷（H4c）： +- **H4c-1 fail-open**：Redis 错误时 `return true, err`（放行），中间件层 `err != nil → c.Next()` 同样放行——**含登录防爆破场景静默失效**（Redis 抖动窗口限流失效，攻击者可借机爆破）。无 fail-closed 选项。 +- **H4c-2 裸断言**：`result.(int64)` 无 comma-ok，Redis 返回非 int64 时 panic（当前 Lua 脚本恒返整数不会触发，属脆弱性）。 + +修复： +- **H4c-1**：`RedisRateLimiter` 新增 `failClosed` 字段（零值 false=兼容默认 fail-open）。`Allow` 在 Redis 未启用/错误/断言失败时按策略决定：fail-closed 返 `(false, err)` 拒绝，fail-open 返 `(true, err)` 放行（兼容旧行为）。中间件层抽取 `redisLimitDecision`——不再无条件 fail-open，按 `allowed` 值决定：fail-closed 故障拒绝返 **503**（`CodeServiceUnavailable`，区别于真实超限的 429），fail-open 故障放行。 +- **H4c-2**：`result.(int64)` 改 comma-ok，断言失败返 `ErrRedisRateLimiterUnexpectedResult`（按 failClosed 策略拒绝/放行）而非 panic。 +- 新增构造函数 `NewRedisRateLimiterFailClosed`、切换方法 `SetFailClosed`、中间件 `RedisRateLimitFailClosed`/`CustomRedisRateLimitFailClosed`、导出错误 `ErrRedisRateLimiterUnavailable`/`ErrRedisRateLimiterUnexpectedResult`。 +- **`LoginRedisRateLimit` 改 fail-closed**（行为变更，见升级说明）：登录防爆破场景 Redis 故障时拒绝，防限流静默失效。 +- 无 API 签名变更（既有函数签名不变）；`RedisRateLimiter` 新增未导出 `failClosed` 字段。 + + + +`Allow` 每次放行都 `v.lastSeen = time.Now()`，重置分支 `time.Since(lastSeen) > window` 对持续客户端永不成立 → count 单调累加，稳态客户端（低于 rate）被误限流，须静默满 window 才解锁（算例：rate=10/min、9 req/min 客户端也会被误限）。修复： +- `visitor.lastSeen` 改名 `windowStart`，语义改为"当前固定窗口起点"，仅在新窗口开始时设置，放行时不变更。 +- `Allow` 窗口过期时重置 count + 新 windowStart；放行 count++ 不更新 windowStart；超限拒绝。 +- 新增 `nowFunc` 字段 + `SetNowFunc` 导出方法（默认 time.Now，测试可注入可控时钟，避免真实 Sleep flaky）。 +- 注：固定窗口允许窗口边界突发（2×rate），如需平滑用 Redis 版滑动窗口。H4b（CustomRateLimit goroutine 泄漏）/H4c（Redis fail-open + 裸断言）属独立缺陷，后续跟进。 + +#### C9b：`jwt/jwt.go` 刷新令牌撤销失败仍签发（jwt/jwt.go） + +`RefreshToken` 原丢弃 `tokenBlacklist.Add` 错误仍 `return GenerateToken(...)`，Redis 抖动时旧 token 未拉黑、新旧 token 双有效，形成会话固定窗口。叠加 C9a：`Add`/`IsBlacklisted` 在 `client==nil` 时静默 `return nil`/`false`，黑名单失效无信号。修复： +- **C9b**：`RefreshToken` 对 `Add` 错误 `return "", fmt.Errorf(...)`，fail-closed 不签发新 token。 +- **C9a**：`Add` 无 Redis 时返 `ErrBlacklistUnavailable`（新增导出错误），让 `RefreshToken`/`InvalidateToken`/`InvalidateTokenByID` 感知黑名单不可用并 fail-closed；`IsBlacklisted` 无 Redis 仍返 false（验证侧 fail-open 是无 Redis 部署固有局限，文档约束安全场景必须启用 Redis）。 + +#### H1：`utils/random.go` 不安全 RNG 且文档反向推荐（utils/random.go） + +`randPool` 用 `math/rand` + `time.Now().UnixNano()` 播种，`RandString`/`RandDigit`/`RandInt`/`RandInt64` 取自该池，非密码学安全、可预测（`-race` 下并发同纳秒取池实例甚至生成相同序列）。GUIDE.md 原主动推荐 `RandString(16)` 用于 token、`RandDigit(6)` 用于 OTP 验证码，使可预测性可被实际利用。修复： +- 新增 `RandStringSecure(n) (string, error)` / `RandDigitSecure(n) (string, error)`，基于 `crypto/rand` + `big.Int` 索引（拒绝采样无偏），不可预测；`n>1<<20` 返 `ErrRandInvalidLength` 保护熵池。 +- `RandString`/`RandDigit` 加安全警示注释（禁止用于 token/OTP/重置码/会话 ID）；保留用于非安全场景（测试数据、随机展示等）。 +- GUIDE.md token/OTP 示例改用 Secure 版本并标注错误处理；高分函数表区分"随机（安全/非安全）"；移除"sync.Pool 性能"误导宣传，改为并列说明。 +- gosec G404（randPool 的 math/rand）加 `#nosec` 留痕（非安全函数，安全场景用 Secure 版本）。 + +#### H2：`utils/http.go` 默认关闭 TLS 校验（utils/http.go） + +`DefaultHTTPClientConfig.SkipTLSVerify` 原为 `true`，`NewHTTPClient()` → `HTTPGet`/`HTTPPost`/`HTTPPostJSON` 经 `DefaultHTTPClient()` 全部默认 `InsecureSkipVerify: true`，可被中间人攻击（MITM）。改为默认 `false`（校验 TLS）；自签证书场景需显式 `SetSkipTLS(true)` 或配置 `SkipTLSVerify: true`。`SetSkipTLS` 注释补充安全警示。gosec G402 加 `#nosec` 留痕（默认 false，opt-in 跳过）。 + +#### H8：路由/注册中心全局单例无锁 + Apply 不幂等 + metrics 依赖调用顺序 + 三个 `/health` 行为不一（router/router.go, router/metrics.go, handler/handler.go, app.go） + +- **H8a 全局注册中心无锁 + 无 nil 守卫**：包级 `globalRegistry` 原为裸 `*Registry`，`Init` 写、`Use`/`RegisterModule`/`RegisterVersion`/`Apply` 等全局 helper 读存在数据竞争；且 `Init` 之前调用任意全局 helper 触发晦涩的 nil 解引用 panic。改为 `atomic.Pointer[Registry]`，读写均经 `Load()`/`Store()`；新增 `ensureRegistry()`，未初始化时以明确信息 panic（`router: 全局注册中心未初始化，请先调用 router.Init(engine)`），把 nil 解引用转成可定位的初始化顺序错误。 +- **H8b Apply 不幂等**：`Registry.Apply` 原无幂等位，二次调用重复 `engine.Use` 装入全局中间件并触发 Gin 重复路由 panic。新增 `applied` 标记，二次及以后 `Apply` 直接返回，中间件与路由仅装入一次。 +- **H8c metrics 依赖调用顺序**：`RegisterMetricsRoute` 原用 `r.Use(middleware.Metrics())`，Gin `engine.Use` 仅对其后注册的路由生效，先于其注册的路由不被采集（依赖调用顺序）。改为：`RegisterMetricsRoute` 仅注册 `/metrics` 暴露端点；采集中间件经新增 `Registry.SetMetricsMiddleware` 在 `Apply` 内作首个全局中间件装入，覆盖所有经注册中心注册的业务路由，不依赖注册顺序。`/metrics` 自身与 `/health` 等基础路由直接挂 engine、不经采集中间件，不被自采集（保留原意图）。 +- **H8d 三个 `/health` 行为/响应体不一**：`RegisterHealthRoute`（可 503）、`defaultModule`（恒 200 `{"status":"ok"}`）、`handler.HealthCheck`（恒 200 经 `response.Success` 包成 `{code,msg,data}` 信封）三处 schema/行为各异。抽取统一 `healthHandler(checks)`，`RegisterHealthRoute`/`RegisterReadinessRoute`/`defaultModule` 均委托之；`handler.HealthCheck` 响应体收敛为 `{"status":"ok"}`（不再走 response 业务信封），便于 K8s 探针直读。 +- **H8d 收尾：defaultModule 与 Register* 并存重复路由 panic（footgun）**：`defaultModule`（经 `WithModules` 注册 `/health`+`/swagger/*any`）与 `RegisterHealthRoute`/`RegisterSwaggerRoutes`（经 `WithDefaultRoutes` 注册同名路由）并存时触发 Gin `handlers are already registered` panic。新增 `registerGETOnce(r, path, h)` 幂等注册辅助，`RegisterHealthRoute`/`RegisterLivenessRoute`/`RegisterReadinessRoute`/`RegisterSwaggerRoutes`/`RegisterMetricsRoute`/`defaultModule` 全部经之：(GET, path) 已存在则静默跳过，首次注册胜出。`*gin.Engine` 经 `Routes()` 精确预检（不吞 panic，真正不同的路由冲突仍按 gin 原语义 panic）；`*gin.RouterGroup`（gin 未暴露 engine，无法预检）用 recover 兜底，仅吞 gin 重复路由 panic（`already registered` / `conflicts with existing wildcard`），最坏情况退化为原行为。 +- **Breaking ⚠️**：`handler.HealthCheck` 响应体由 `{code,msg,data:{status:"ok"}}` 改为 `{"status":"ok"}`，与 `router.RegisterHealthRoute` 同 schema。直接断言旧信封字段的下游需改断言 `status` 字段。需依赖探活（mysql/redis 失败 503）时改用 `router.RegisterHealthRoute(checks...)`。 +- **Changed**：框架基础路由注册（health/livez/readyz/swagger/metrics/defaultModule）改为幂等，重复注册静默跳过（首次胜出）——消除并存组合的 panic footgun，非破坏性（原本重复注册即 panic，现安全跳过）。 +- **Added**：`router.Registry.SetMetricsMiddleware`、`router.registerGETOnce`/`ensureRegistry`/`healthHandler`（未导出）。无配置/migration 变更。 + +#### C3：`sse/sse.go` 断连泄漏 goroutine + 算力（AI 主场景，sse/sse.go） + +- **C3b 写/Flush 错误被吞**：`WriteEvent`/`WriteMessage` 原丢弃 `fmt.Fprintf` 错误且恒 `return nil`，导致 `StreamText` 等的 `if err := WriteJSON(...); err != nil` 守卫只对 marshal 失败生效、对客户端断连永不触发 → 消费循环不退出 + 上游 LLM 流持续运行直到进程结束。改为传播 `fmt.Fprintf` 写错误。 +- **C3a 循环无 ctx.Done**：`Stream`/`StreamText`/`StreamChunks`/`StreamWithID` 的 `for range ch` 改 `for { select { case <-ctx.Done(): return ctx.Err(); case v,ok:=<-ch: ... } }`，客户端断连即退出。`SSEWriter` 加 `ctx` 字段（NewSSEWriter 存 `c.Request.Context()`），并对 nil ctx 回退 `context.Background()` 防御。 +- **C3c 手设 chunked 头**：删除 `Transfer-Encoding: chunked`（HTTP/1.1 冗余、HTTP/2 非法），交由 server 自动分帧。 +- 生产者契约文档化：`StreamText` 注释说明生产者应监听 `c.Request.Context()`，取消时停止上游 LLM 流（框架无法单方面停止生产者）。 + +#### C7：`middleware/cors.go` 通配符后缀绕过 + 开发态任意 Origin 回显（middleware/cors.go） + +- **C7a 通配后缀绕过**：`*.example.com` 原用 `strings.HasSuffix(origin, domain)` 未锚定 host 边界，`https://notexample.com`、`https://evil-example.com` 被接受。改用 `net/url` 解析 origin 的 host，要求 host 以 `.domain` 结尾（真实子域边界）且不等于 apex 自身。抽取 `matchOrigin` 函数（精确匹配 + 通配子域，大小写不敏感、支持端口与 FQDN 尾点）。 +- **C7b 开发态任意 Origin 回显**：开发态原无条件回显任意 Origin，若同时 `AllowCredentials=true` 构成凭据型反射。改仅对 localhost/127.0.0.1/::1 回显（`isLocalhostOrigin`），杜绝任意站点携凭证访问。 +- **C7 收尾（信息泄露收敛）**：未匹配 origin 时不再发送 `Access-Control-Allow-Methods`/`Allow-Headers`/`Expose-Headers`/`Max-Age`，避免向未授权 origin 暴露 API 允许的方法/头清单。这些头现仅在 origin 匹配时随 `Allow-Origin` 一并发送。 + +#### C1：`cache/lock.go` 分布式锁 panic/泄漏/裸断言（cache/lock.go） + +- **C1a `WithLockAutoExtend` send-on-closed panic + 锁泄漏**：续期改"父关停 + 子 ack"双 channel（`close(stop)` + `<-finished`），消除旧 `done <- struct{}{}` 向已关闭 channel send 的 panic。`Unlock` 用 `context.WithTimeout(context.Background(), 5s)` 派生超时，避免原 ctx 已取消致解锁失败再泄漏。`fn()` panic 路径加 `defer` 兜底，保证 panic 时也停止续期 goroutine 并释放锁（独立复审发现 CRITICAL）。 +- **C1a 一致性（HIGH）**：`WithLock` 的 `defer Unlock` 同改 Background 超时 ctx + defer 兜底，与 `WithLockAutoExtend` 一致。 +- **C1b 裸类型断言**：新增 `toInt64(v)` 辅助函数（comma-ok），`NewLock`/`Unlock`/`ExtendLock` 三处 `result.(int64)` 改用之，断言失败返 `ErrLockUnexpectedResult` 而非 panic。新增导出错误 `ErrLockUnexpectedResult`。 +- **C1c `TryLock` 忽略 ctx**：`time.Sleep` 改 `select { ctx.Done()/time.After }`，响应取消。 +- **C1d 无 fencing token**：`LockToken` 文档化设计局限（需 Redis INCR + 下游校验，框架无法单方面保证），不引入破坏性数据结构变更。 + +#### C2：`ws` Hub 死锁 + send-on-closed panic + 半开连接泄漏（ws/ws.go） + +- **C2a 广播死锁**：`Hub.Run` 的 broadcast 分支原在 `conn.Send` 失败时 `h.unregister <- conn`（向自身消费的 channel 发送，无接收者）→ 永久阻塞、整个 Hub 卡死。改持写锁单次遍历，失败连接行内 `delete + conn.Close()`，去掉 channel 回环。`Send` 改非阻塞投递（缓冲满返回 `ErrSendBufferFull`），避免持写锁期间因慢消费者/已死连接阻塞最长 `pongWait` 导致 Hub stall（C2a-residual）。 +- **C2b send-on-closed panic**：`Close()` 不再 `close(c.send)`，仅 `close(c.closeChan)` + `c.conn.Close()`；`Send` 前置 `IsClosed()` 快速失败 + select 兜底。消除 `Close` 与并发 `Send` 的 send-on-closed panic。 +- **C2c 半开连接泄漏**：`Handle` 读循环前置 `SetReadDeadline(pongWait)` + `SetPongHandler`（重置读 deadline）；`writePump` 每次写前 `SetWriteDeadline(writeWait)`、ping 周期 `pingPeriod = pongWait*9/10`；写失败主动 `Close` 触发读循环退出，加速半开连接回收。新增常量 `pongWait=60s`/`pingPeriod=54s`/`writeWait=10s` 与导出错误 `ErrSendBufferFull`。 + +#### C5：`compress` Zip-Slip + 解压炸弹（compress/compress.go） + +- **C5a Zip-Slip**：`unzipFile` 改用 `filepath.Join` + 前缀锚定（`absDst+sep`），拒绝条目名含 `..` 逃逸、绝对路径、以分隔符开头；拒绝符号链接条目（`ModeSymlink`）防经软链二次穿越。修复前 `file.Name` 可含 `../`，`os.Create` 覆盖任意文件。 +- **C5b 解压炸弹**：`GzipDecompress` 由 `io.ReadAll` 改 `io.LimitReader`；`GzipDecompressFile`/`Unzip` 由 `io.Copy` 改 `io.CopyN` 单条目封顶 + Unzip 累计封顶。新增 `DecompressOptions{MaxBytes, MaxTotalBytes}`（0=默认，-1=不限）与 `*WithOptions` 变体；默认单流/单条目 100MB、Unzip 累计 1GB。 + +#### C4：`storage` 路径穿越 + 无上传校验 + Get OOM（storage/storage.go） + +- **C4a 路径穿越**：Local 的 `Delete/Get/Exists/Upload/UploadFromBytes` 的相对路径全经新增 `safeJoin` 前缀锚定（`rootAbs+sep`），拒绝绝对路径/NUL/`..` 逃逸，杜绝任意文件删/读/探测与任意目录写。OSS 的 `Delete/Get/Exists/Upload/UploadFromBytes` 全经新增 `sanitizeObjectKey` 拒绝含 `..`/绝对路径/空/NUL 的 key。 +- **C4b 上传校验**：新增可配置 `UploadPolicy{MaxSizeBytes, AllowedExts, AllowedMIMEs}`（嵌入 `local`/`oss` 配置）。`AllowedMIMEs` 非空时用 `http.DetectContentType` 嗅探前 512B（取主类型比较）并拼回头部。零值不限（兼容下游）。 +- **C4c Get 读封顶**：Local `Get` 由 `os.ReadFile` 改为 `io.LimitReader` 封顶，OSS `Get` 同理；默认上限 100MB（`max_read_bytes`：0=默认，-1=不限，正数=该值），防全量读入内存 OOM。 +- **HIGH（跨平台）**：OSS object key 拼接由 `filepath.Join`（Windows 产 `\`）改 `path.Join` + `sanitizeObjectKey` 归一化 `\`→`/`，保证 Windows/Linux 部署 key 一致。 +- 附：`MkdirAll` 权限 0755→0750（gosec G301）。 + +### 升级说明 🛠️ + +- **H6 行为变更（非破坏性，正向修复）**： + - `BaseRepo` 读操作（`FindByID`/`FindAll`/`FindPage`/`FindWhere`/`Count`/`Exists`/...）默认路由到**从库**（原全部走构造时捕获的主库），支持 `database.UseMaster(ctx)`/`UseReplica(ctx)` 显式路由。未配置从库时仍走主库（`Replica()` 无从库回退主库）。 + - `BaseRepo` 写操作（`Create`/`Update`/`Delete`/`*Batch`/`Restore`/...）显式走**主库**，即便 ctx 标记 `UseReplica` 也不写到从库。 + - `FindPage*` 的 count+list 现包进单事务（每页一次 BEGIN/COMMIT）以保证 total/items 快照一致。高频分页接口会有极小额外往返开销；若不可接受可自行用 `QueryBuilder.Page`（轻量、不包事务）。 + - 跨层/跨 repo 事务 join：外层 `database.TransactionWithContext`（或任意 `*gorm.DB` 事务）中，用 `database.WithTx(ctx, tx)` 注入 ctx 后传给 `BaseRepo` 方法即可参与同一事务。 + - 新增 `BaseRepo.UpdateFields`（局部更新，推荐替代 `Update` 的全列覆写）；`Update`（`Save`）行为不变但文档化其全列覆写语义。 + - `QueryBuilder` 标注为单次使用、非并发安全；终结方法现克隆不污染构建器，`Count`/`Page` 的 count 剥离残留 Limit/Offset。 + - 无 API 签名/配置/migration 变更；下游 `NewBaseRepo[T](database.GetDB())` 用法完全兼容。 +- **C8 行为变更（非破坏性）**：panic 响应的 HTTP 状态由 200（ModeBusiness）改为 500，body 不变（`code:500` + msg + `request_id`）。ModeREST 行为不变。下游若按"panic 返 200"做适配（极罕见）需注意。已知局限：若 handler 在 panic 前已 flush 部分响应，HTTP 状态无法再改写（HTTP 固有局限，非本次引入）。 +- **C6 行为变更**：API 模式 CSRF token 改为单次消费（每次成功 POST 后需重新 `GenerateAPIToken`）+ 30min TTL；`DoubleSubmitCookie` 的 cookie `HttpOnly` 由 true 改 false。原 API 模式整体不可用，故无真实回归。 +- **C4 行为变更（非破坏性）**： + - 含 `..`/绝对路径的 `Delete/Get/Exists` 路径现被拒绝（`ErrPathTraversal`），合法相对路径不受影响。 + - `Get` 默认读取上限 100MB，超限返回错误；需读大文件请配置 `storage.local.max_read_bytes: -1`（不限）或具体值。OSS 同理（`storage.oss.max_read_bytes`）。 + - 上传目录权限 0755→0750（仅 owner/group 可访问）。 + - 新增可选配置 `storage.local.upload` / `storage.oss.upload`（`max_size_bytes`/`allowed_exts`/`allowed_mime_types`），零值不限制以兼容现有下游；生产环境建议显式配置。 + - 安全约束：本地存储根目录应为框架独占，不与用户可控内容混用（防符号链接二次穿越）。 +- **C5 行为变更（非破坏性）**： + - `Unzip` 现默认拒绝含 `..`/绝对路径的条目（`ErrPathTraversal`）与符号链接条目（`ErrSymlinkEntry`），合法归档不受影响。 + - `GzipDecompress`/`GzipDecompressFile`/`Unzip` 默认解压上限：单流/单条目 100MB、Unzip 累计 1GB，超限返回 `ErrDecompressLimit`。需解压更大文件用 `*WithOptions` 变体设 `MaxBytes: -1`（不限）或具体值。 + - 原函数签名保留；新增 `GzipDecompressWithOptions`/`GzipDecompressFileWithOptions`/`UnzipWithOptions`。 +- **C2 行为变更（非破坏性）**： + - `Connection.Send` 改为非阻塞投递：发送缓冲满时返回 `ErrSendBufferFull`（新导出错误）而非阻塞等待。原阻塞语义的下游需改为重试或关闭连接。 + - `Hub` 广播对发送失败（含缓冲满/已关闭）的连接行内移除并关闭——慢消费者会被踢除（ws 广播 best-effort 语义）。 + - WebSocket 连接现启用读写超时与 ping/pong 心跳：半开连接在 `pongWait`（60s）内退出，不再永久阻塞 goroutine。 + - 公共 API 签名不变；`Connection.send` 不再被 close（内部行为）。 +- **C1 行为变更（非破坏性）**： + - `WithLockAutoExtend`/`WithLock` 的解锁改用独立 `context.Background()` 超时（5s），原 ctx 已取消也能解锁（语义：取消业务 ≠ 继续独占锁）。 + - `WithLockAutoExtend` fn panic 时仍释放锁（defer 兜底）。 + - `TryLock` 重试等待响应 ctx 取消。 + - 新增导出错误 `ErrLockUnexpectedResult`（Lua 返回非 int64）。 +- **C7 行为变更（非破坏性，收紧）**： + - `*.example.com` 通配不再匹配 `notexample.com`/`evil-example.com` 等后缀相同但非真实子域的域名；apex `example.com` 不由通配覆盖，需显式配置。 + - 开发态 CORS 兜底仅对 localhost/127.0.0.1/::1 回显 Origin，不再回显任意 Origin。原本依赖开发态回显任意域名的下游需改用显式白名单。 + - 未匹配 origin 的响应不再携带 `Access-Control-Allow-Methods`/`Allow-Headers`/`Expose-Headers`/`Max-Age`（信息泄露收敛）；匹配时正常发送。 +- **C3 行为变更（非破坏性）**： + - `StreamText`/`StreamChunks`/`StreamWithID`/`Stream` 在客户端断连（`c.Request.Context()` 取消）时返回 `context.Canceled` 而非永久阻塞。 + - `WriteEvent`/`WriteMessage` 现可能返回写错误（旧实现恒 nil）；下游若忽略返回值不受影响。 + - 响应不再手设 `Transfer-Encoding: chunked`。 + - 公共 API 签名不变；`SSEWriter` 新增私有 `ctx` 字段（外部字面量构造需走 `NewSSEWriter`）。 +- **H2 行为变更（可能影响下游）**：`utils` HTTP 客户端默认**校验 TLS**（`DefaultHTTPClientConfig.SkipTLSVerify` 由 `true` 改 `false`）。`HTTPGet`/`HTTPPost`/`HTTPPostJSON`/`NewHTTPClient()` 不再默认跳过证书校验。下游访问**自签证书**的内网/开发服务会因证书校验失败报错，需显式 `client.SetSkipTLS(true)` 或 `NewHTTPClientWithConfig(HTTPClientConfig{SkipTLSVerify: true})`。生产环境应保持默认校验。 +- **H1 行为变更（Breaking，删除函数）**： + - **删除** `utils.RandString` / `RandDigit`（math/rand 版本）。字符串随机的用途几乎都是安全场景（token/OTP/验证码/会话 ID），保留 math/rand 版本会诱导误用（H1 的根因正是 GUIDE 推荐 RandString 做 token）。下游迁移： + - token/OTP/验证码/会话 ID → `RandStringSecure` / `RandDigitSecure`（crypto/rand）。 + - 非安全场景需高性能随机串 → 直接用标准库 `math/rand`。 + - **保留** `RandInt` / `RandInt64`（范围随机，有明确非安全场景：负载均衡/游戏/A-B 分桶），加非安全警示注释。 + - 新增 `RandStringSecure` / `RandDigitSecure`（基于 `crypto/rand`，返 `(string, error)`）与 `ErrRandInvalidLength`。 + - 新增 `RandIntSecure` / `RandInt64Secure`（基于 `crypto/rand` + `big.Int` 拒绝采样无偏，返 `(T, error)`），用于安全 nonce 范围、防猜抽奖、密钥分桶等。 + - GUIDE 示例改用 Secure 版本。 +- **C9b 行为变更（可能影响下游）**： + - `jwt.RefreshToken` 在旧 token 撤销失败（Redis 不可用/抖动）时**不再签发新 token**（fail-closed），返回错误。原行为是丢弃错误仍签发，致新旧 token 双有效。 + - `jwt.InvalidateToken`/`InvalidateTokenByID`/`TokenBlacklist.Add` 在无 Redis 时返回 `ErrBlacklistUnavailable`（新增导出错误），不再静默成功。 + - `IsBlacklisted` 无 Redis 仍返 false（验证侧 fail-open，无 Redis 部署固有局限——安全敏感场景必须启用 Redis）。 + - 签名不变；新增 `ErrBlacklistUnavailable`。 +- **H4a 行为变更（非破坏性）**：内存限流器 `RateLimiter` 改固定窗口语义，稳态客户端（低于 rate 的持续请求）不再被误限流。`Allow`/`NewRateLimiter`/`Stop` 签名不变；新增 `SetNowFunc`（测试用可控时钟）。 +- **H5 行为变更（非破坏性）**：`handler.BadRequest`/`handler.InternalError` 不再硬编 HTTP 400/500，改为遵循当前响应模式（委托 `response` 体系）：默认 `ModeBusiness` 下两者均返回 HTTP 200（错误经 body `code` 表达，与 `response.Fail*` 一致）；`ModeREST` 下 `InternalError` 返回 500（`CodeServerError` 映射），`BadRequest` 返回 200（`CodeFail` 属业务失败不映射 HTTP 错误，与 `response.Fail` 一致）。两者现写入 `RequestID`。下游若依赖 `handler.BadRequest` 恒返 400 需改用 `response.Custom(c, 400, code, msg, nil)` 或业务自定义 4xxxx 错误码。 +- **H4c 行为变更（可能影响下游）**： + - **`LoginRedisRateLimit` 改 fail-closed**：Redis 故障/未启用时由放行改为拒绝（HTTP 503，`CodeServiceUnavailable`）。登录防爆破场景下 Redis 故障不再静默放行（原 fail-open 致限流失效）。下游登录接口须确保 Redis 可用，否则登录会在 Redis 故障时不可用（安全语义：宁拒勿放）。 + - 其余 Redis 限流中间件（`RedisRateLimit`/`APIRedisRateLimit`/`UploadRedisRateLimit`/`CustomRedisRateLimit`/`RedisRateLimitWithIdentifier`）保持 fail-open（兼容默认）。 + - 新增 fail-closed 变体：`RedisRateLimitFailClosed`/`CustomRedisRateLimitFailClosed`/`NewRedisRateLimiterFailClosed`/`SetFailClosed`，供安全敏感场景选用。 + - 新增导出错误 `ErrRedisRateLimiterUnavailable`/`ErrRedisRateLimiterUnexpectedResult`。 + - 无既有 API 签名变更。 +- 无 API 签名变更、无 migration。新增测试依赖 `github.com/alicebob/miniredis/v2`。 + +--- + +## [1.1.1] - 2026-06-23 + +> 本版本为 v1.1.0 的补丁发布：补 ServerConfig.Host 字段、统一面向用户文案为中文、修正 README 过时/错误描述。 + +### Added ✨ + +#### ServerConfig.Host（绑定地址） + +`server` 新增 `host` 字段，控制监听地址： + +- `host: ""`（默认）→ `:8080`，监听所有接口（0.0.0.0），向后兼容 +- `host: "127.0.0.1"` → `127.0.0.1:8080`，仅本机（前面有 nginx 时常用） +- `host: "10.0.0.5"` → 绑定内网网卡 + +避免生产环境无意暴露在 0.0.0.0。启动日志相应区分"所有接口"/指定地址。 + +### Changed 🔄 + +#### 面向用户文案统一中文 + +v1.1.0 前部分面向用户/调用的文案为英文，与其余中文文案不一致。本次统一为中文： + +- `middleware/recover.go`：`"Panic recovered"` → `"panic 已恢复"`；`"Panic: %v"` → `"服务器内部错误: %v"`（消除同文件内中英矛盾） +- `middleware/logger.go`：5 处日志消息（慢请求/请求错误/客户端请求错误/API 请求/请求）改中文 +- `middleware/metrics.go`：3 个 Prometheus `Help` 文本改中文 +- `app.go` / `database/manager.go` / `logger/logger.go`：英文 error 改中文 + +**保留英文**（非文案，属协议/约定/技术必需）：JSON 字段名（`code`/`msg`/`data`）、health 探针状态枚举（`ok`/`error`/`disabled`）、Prometheus metric `Name`（命名规则限制）、`database/manager.go` 中匹配 MySQL 驱动错误串的英文（`"Access denied"` 等，改了会失效）、Redis/CSRF Token/JWT/OSS 等技术专有名词。 + +### Fixed 🐛 + +#### README 错误描述修正 + +v1.1.0 后 README 存在过时/错误描述，照抄会导致新用户启动失败，本次修正： + +- **删除目录结构里已移除的 `wire/` 段**（wire 包 v1.1.0 已删） +- **快速开始配置示例**：`jwt.secret` 补足 ≥32 字节（否则被 v1.1.0 `Validate` 拦截启动失败）；`expire: 86400`（int 秒）改为 `expire: "24h"`（`time.Duration`），补 `refresh_expire`/`issuer`/`algorithm` +- `server` 段补 `host`/`read_timeout`/`write_timeout`/`idle_timeout`/`shutdown_timeout`/`response_mode` 字段 +- v1.0.2 更新日志标注 `WithWire` 已于 v1.1.0 移除 +- 目录结构补 v1.1.0 新文件：`middleware/metrics.go`、`middleware/timeout.go`、`router/metrics.go`、`config/validate.go`、`response/mode.go` +- 框架特性段重写为三组（架构可注入 / 生产就绪 / 基础功能），补全 v1.1.0 能力 +- 响应格式段补 `Mode` 开关（`ModeBusiness`/`ModeREST`）与 `Custom` API + +#### README 首段重写 + +原首段描述（"轻量级 Web 开发框架，提供完整后端基础设施"）过于普通化，适用于多数 Gin 脚手架，无辨识度。重写为： + +- tagline 点明核心差异：组件全部 Manager 化，简单调用与注入实例兼得 +- "为什么是 xlgo"段：对比一般 Gin 脚手架的包级单例痛点 + 对照代码 +- 5 条差异化卖点（可注入 / 生产就绪内置 / 零 Fatal / 默认轻量 / 可插拔方言） +- 30 秒上手极简可跑示例 + +### 升级说明 🛠️ + +从 v1.1.0 升级无破坏性变更，`go get github.com/EthanCodeCraft/xlgo-core@v1.1.1` 即可。`host` 字段默认空，行为与 v1.1.0 一致。 + +--- + +## [1.1.0] - 2026-06-23 + +> 本版本定位为 **HA & Manager 化 release**：高可用与生产就绪改进 + 组件 Manager 化。对应体检报告 #10-#24。 +> 含少量破坏性变更，升级前请阅读下方「升级说明」。 + +### Breaking ⚠️ + +详见下方「升级说明」。 + +- 删除 `wire` 包及其 `WithWire` Option（其事 App Option 已覆盖）。`WithoutWire` 保留为空 stub 以兼容调用。 +- 删除 `AppConfig.TokenExpire` 字段（与 `JWTConfig.Expire` 重复），过期统一由 `jwt.expire` 配置。 +- `JWTConfig.Expire` 类型由 `int`（秒）改为 `time.Duration`（如 `"24h"`）。 +- 删除 `StartServerWithPort` 与 `GracefulShutdown` 双轨函数（与 `App.StartServer`/`App.Shutdown` 重复）。 + +### Added ✨ + +#### 组件 Manager 化（#10） + +storage / cache / redis / jwt / logger 五个组件照 `database.Manager` 模式新增 `XxxManager` + `DefaultXxx` + `SetDefaultXxxManager`，包级 facade 保留兼容存量。支持多实例与测试注入 mock： + +```go +// 注入自定义实现 / 多实例 +database.SetDefaultRedisManager(myRedisMgr) +cache.SetDefaultCacheManager(mockCacheMgr) +jwtMgr := jwt.NewJWTManagerWithRedis(refreshRedisClient) // 独立黑名单 +``` + +#### Lifecycle Hooks（#12） + +```go +xlgo.New( + xlgo.WithHook(xlgo.Hook{ + Name: "register-service", + OnStart: func(a *xlgo.App) error { return registerToDiscovery() }, + OnStop: func(a *xlgo.App) error { return deregisterFromDiscovery() }, + }), +) +``` + +各阶段：`OnInit`（Init 内组件就绪后）/ `OnStart`（监听前）/ `OnReady`（端口就绪后）/ `OnStop`（Shutdown 开头）。 + +#### App.Go + in-flight goroutine（#22） + +`App.Go(func(ctx context.Context))` 启动受 App 生命周期管理的后台 goroutine，Shutdown 时 cancel ctx 并 `wg.Wait`（带 `shutdown_timeout` 超时），避免业务异步任务被进程退出强制砍掉。 + +#### Server 参数配置化（#13） + +`server` 新增 `read_timeout`/`write_timeout`/`idle_timeout`/`shutdown_timeout`/`max_header_bytes`/`tls`/`unix_socket`/`response_mode`，缺省回退原硬编码值。支持 TLS 与 unix socket 监听。 + +#### JWTConfig time.Duration（#14） + +`jwt.expire`/`refresh_expire` 用 `time.Duration`（`"24h"`/`"168h"`），新增 `issuer`/`algorithm`（HS256/HS384/HS512）。删除冗余的 `AppConfig.TokenExpire`。 + +#### Config Validate（#16） + +`Config.Validate()` 在 `Manager.Load` 解析后自动调用，校验端口范围、JWT 密钥长度（≥32 字节）、启用数据库时关键字段、TLS 证书、Duration 非负等。把配置错误从"运行时第一次请求"提前到"进程启动"。 + +#### response REST 模式（#15） + +`response.SetMode(ModeBusiness|ModeREST)`，默认 `ModeBusiness`（全 200 + 业务码，兼容存量）。`ModeREST` 下失败响应按错误码映射 HTTP status（401/404/429/500...），body 仍带业务码，便于 APM/Prometheus/网关按 status 区分异常。可在 `server.response_mode` 配置。新增 `response.Custom(c, httpStatus, code, msg, data)`。 + +#### livez / readyz（#17） + +```go +xlgo.New(xlgo.WithLivenessRoute(), xlgo.WithReadinessRoute()) +// GET /livez 永不依赖外部，始终 200（K8s livenessProbe） +// GET /readyz 复用 healthChecks，失败 503（K8s readinessProbe） +``` + +`/health` 保留兼容。`WithFullStack`/`NewFullStack` 默认启用。 + +#### Prometheus metrics（#18） + +```go +xlgo.New(xlgo.WithMetricsRoute()) // 默认 /metrics +``` + +`middleware.Metrics()` 采集 `http_requests_total` / `http_request_duration_seconds` / `http_requests_in_flight`。新增 `prometheus/client_golang` 依赖。 + +#### 请求级 Timeout 中间件（#19） + +`middleware.Timeout(d)` 为每个请求的 context 设 deadline，下游 GORM/Redis 走 `c.Request.Context()` 级联取消。可通过 `WithRequestTimeout(d)` 装入全局。 + +#### 依赖健康自愈（#21） + +`database.Manager` 后台探活（`App.Go` 启动，每 `health_check_interval` ping 一次）：主库连续失败达阈值标记不健康，`/readyz`/`/health` 返回 503；从库失败临时剔除读流量，恢复自动重新纳入。新增 `database.ConnMaxIdleTime`/`health_check_interval`/`health_check_failure_threshold` 配置。 + +#### RequestID 默认装入（#24） + +`App.Init` 无条件装入 `middleware.RequestID()`（在 Recovery 之前），让每个响应/panic 日志都带 `request_id`。移除 `gin.Recovery()` 双重保险，统一用 `middleware.Recover()`（#23 已带 request_id）。 + +### 升级说明 🛠️ + +1. **wire 包删除**：移除 `import "github.com/EthanCodeCraft/xlgo-core/wire"` 与 `wire.InitServices()`/`WithWire()` 调用。原由 wire 触发的 `cache.Init()` 现由 `WithRedis` 自动触发。 +2. **AppConfig.TokenExpire 删除**：改用 `jwt.expire` 配置 token 过期。grep `token_expire` 清理旧配置。 +3. **JWTConfig.Expire 类型变更**：YAML 由 `expire: 86400`（秒）改为 `expire: "24h"`（Duration 字符串）。代码中 `time.Duration(cfg.JWT.Expire) * time.Second` 改为直接 `cfg.JWT.Expire`。 +4. **StartServerWithPort / GracefulShutdown 删除**：改用 `App.Run()` / `App.Shutdown()`。 +5. **JWT 密钥长度**：`Config.Validate` 要求启用 JWT 时 secret ≥32 字节，原短密钥会在启动期被拦截，请生成足够长的随机密钥。 +6. **配置文件**：建议补 `server.read_timeout` 等字段（缺省自动回退，不强制），`jwt.expire` 必须改为 Duration 字符串。 + +--- + +## [1.0.4] - 2026-06-22 + +> 本版本定位为 **DX & Docs release**：开发体验与文档改进，无破坏性 API 变更。对应体检报告 #25/#27/#28/#29/#30。 + +### Added ✨ + +#### CLI 多模板（#28） + +`xlgo new` 新增 `--template` 参数，支持三种脚手架模板： + +```bash +xlgo new myapp --template minimal # 轻量 HTTP，无 MySQL/Redis 依赖 +xlgo new myapp --template api # 标准业务 API，含分层目录（默认） +xlgo new myapp --template fullstack # 全组件，NewFullStack 一键启用 +``` + +- `minimal`：仅 logger + health + 示例路由，目录结构最小化，第一次接触 xlgo 从这里开始 +- `api`：含 handler/model/repository/service 分层 + MySQL/Redis/JWT 配置（默认模板） +- `fullstack`：`NewFullStack` 全组件 + Swagger + Storage + +#### examples/ 目录（#29） + +新增两个可运行示例，帮助快速上手： + +- `examples/minimal/` — 50 行可跑，不依赖外部服务 +- `examples/full/` — MySQL + Redis + JWT + user CRUD 完整示例（登录发 token、认证路由、创建/查询用户） +- `examples/README.md` — 运行说明与接口文档 + +#### docs/ 文档结构（#30） + +- 新增 `docs/` 目录，`docs/plans/` 归档历史规划与体检报告 +- 新增 `docs/README.md` 文档索引 +- `Version_Update_Plan_v1.0.2.md` → `docs/plans/` +- `Version_v1.0.2_report.md` → `docs/plans/` +- 早期 `report.md` → `docs/plans/v2.0-review.md` +- `CHANGELOG.md` / `GUIDE.md` 按惯例保留在仓库根目录 + +### Changed 🔄 + +#### 模块路径文档改进（#25） + +经评估**保留** `xlgo-core` 模块路径——`-core` 后缀反映这是 xlgo 多产品系列（xlgo-core / xlgo-orm / xlgo-ai ...）的核心产品，不去掉。模块路径（`github.com/EthanCodeCraft/xlgo-core`）与包名（`xlgo`）不同是 Go 惯例（cf. `github.com/gin-gonic/gin` → 包名 `gin`）。 + +改进文档说明，消除新用户 `go mod tidy` 撞墙的困惑： + +- README 快速开始新增「模块路径与包名」小节，给出完整 import 示例： + ```go + import xlgo "github.com/EthanCodeCraft/xlgo-core" + ``` +- CLAUDE.md `Import Path Note` 措辞明确化，说明 module path / package name / `-core` 语义 + +#### Without* Option 定位文档化（#27） + +经调研 `Without*` 系列 Option 有真实用例（测试覆盖「先开再关」语义 + `NewFullStack` 后排除单项），**不删除、不标 Deprecated**，改为文档化其定位： + +- `app.go` `WithoutLogger` 注释说明：`Without*` 主要用于 `NewFullStack` / `RunFullStack` 启用全部组件后排除个别项 +- README 快速开始补充用法说明：`xlgo.NewFullStack(xlgo.WithoutSwaggerRoutes())` + +### 依赖与构建 + +- `.gitignore` 整理：忽略 `CLAUDE.md`、构建产物（`*.exe` / `bin/`）、临时发版文件（`gitHub_release_*.md`） + +### 升级说明 + +v1.0.4 **无破坏性变更**，从 v1.0.3 升级只需： + +```bash +go get github.com/EthanCodeCraft/xlgo-core@v1.0.4 +go mod tidy +``` + +--- + +## [1.0.3] - 2026-06-22 + +> 本版本定位为 **bug fix release**：收口 v1.0.2 引入的破坏性清理，并修复 4 个轻量 bug + 依赖复查。 + +### Removed 🗑️ + +#### ⚠️ Breaking — 清理 v1.0.2 兼容别名（database 包） + +xlgo 仍是早期框架，本次彻底移除 v1.0.2 临时保留的兼容别名，避免长期累积技术债。 + +**移除内容**： + +- `database.InitMySQL(cfg)` 包级函数 +- `database.InitMySQLWithReplicas(cfg, replicas)` 包级函数 +- `(*Manager).InitMySQL(cfg)` 实例方法 +- `(*Manager).InitMySQLWithReplicas(cfg, replicas)` 实例方法 +- `database.driverName(driver)` 内部辅助（已被 `driverDescription` 替代） + +**迁移指南**： + +```go +// ❌ 旧 +database.InitMySQL(cfg) +database.InitMySQLWithReplicas(cfg, replicas) + +// ✅ 新（驱动由 cfg.Database.Driver 决定，可以是 mysql / postgres / 自定义注册的方言） +database.InitDB(ctx, cfg) +database.InitDBWithReplicas(ctx, cfg, replicas) +``` + +**为什么现在动手**： + +- xlgo 还在小范围使用，破坏式调整成本最低 +- "默认开启可插拔方言"已经是 v1.0.2 的正式 API，再叫 `InitMySQL` 名实不符 +- 早期保留别名 → 长期变成永久负担的反面教材太多，与其在 v1.0.4 / v1.1 删，不如现在删 + +#### 删除死代码 `database.DBResolver` + +`database.DBResolver` 类型与其 `BeforeQuery` 方法**从未被注册**到 GORM callback chain（既没有 `db.Callback().Query().Before(...)` 的调用，也没有任何 plugin 包装），属于纯死代码。文档暗示的"自动读写分离"实际上从未生效——读写分离一直依赖业务侧显式调用 `database.UseMaster(ctx)` / `database.UseReplica(ctx)`。 + +**移除内容**： + +- `database.DBResolver` 类型 +- `(*DBResolver).BeforeQuery` 方法 + +**对用户影响**： + +- 几乎无影响。该类型从未在框架内部被使用，也未被文档推荐为 public API +- 若你的代码 `database.DBResolver{}` 出现编译错误，说明你曾尝试将其注册到 GORM callback；这种用法并不能让"读路由从库"自动生效，请改用： + + ```go + // 强制主库（事务、写后立刻读） + ctx := database.UseMaster(c.Request.Context()) + user, err := repo.FindByID(ctx, id) + + // 显式读从库（报表、统计） + ctx := database.UseReplica(c.Request.Context()) + list, err := repo.FindAll(ctx) + ``` + +未来若需要"基于 callback 的自动路由"，建议直接接入官方 [`gorm.io/plugin/dbresolver`](https://github.com/go-gorm/dbresolver)，它有完整的权重 / policy / 健康摘除支持，比自造轮子更稳。 + +### Changed + +#### 文件重命名：`database/mysql.go → database/manager.go` + +文件内容自 v1.0.2 引入可插拔方言注册表后，已经与 MySQL 解耦——本版本同时清理了 `InitMySQL` / `InitMySQLWithReplicas` / `driverName` 兼容别名（详见下方 Removed 段），文件中已经全部是通用代码（`Manager`、`ReplicaPicker`、`Init/Close/HealthCheck`、`UseMaster/UseReplica` 等）。继续叫 `mysql.go` 误导新用户认为框架仅支持 MySQL。 + +**对用户影响**： + +- **导入路径无变化**：`github.com/EthanCodeCraft/xlgo-core/database` 不变，所有公开 API 都还在 +- 只有直接 `git grep mysql.go` 或在 issue / PR review 里提到该文件的内部协作会感知 + +测试文件同步重命名为 `database/manager_test.go`。 + +### Added ✨ + +#### console 包：显式 level 控制 + +为 `console` 包补齐显式级别屏蔽能力，让用户在 main 中**显式**控制何时收紧调试输出，避免上线前到处屏蔽 `console.Debug` / `console.Info` 调用。 + +**API 增量**： + +- `console.LevelSilent` — 完全静默 +- `console.WithLevel(l Level)` — 构造时设置级别 +- `(*Console).SetLevel(l)` / `(*Console).Level()` — 实例方法 +- `console.SetLevel(l)` / `console.GetLevel()` — 包级 API（操作 Default 实例） +- `(Level).String()` — 可读名称 + +**典型用法**： + +```go +func main() { + cfg, _ := config.Load("./config.yaml") + + // 显式收紧：生产期只保留 Warn / Error + if cfg.IsProduction() { + console.SetLevel(console.LevelWarn) + } + // 或完全静默：console.SetLevel(console.LevelSilent) + + app := xlgo.New(...) + app.Run() +} +``` + +**设计立场**： + +- console 包**不会**根据 `app.env` 自动切级别——选择权完全在调用方，避免"dev 看到的 / prod 看到的"行为不一致 +- console 仍然是**纯彩色 stdout 工具**，不写文件、不感知环境、跟 `fmt.Println` 同级 +- 业务可观测信息（用户登录、订单事件、审计日志等"上线必须保留的"）请使用 `logger` 包；console 只用于开发期肉眼调试 +- 完整对比表见 [GUIDE.md §3.3](./GUIDE.md#33-彩色控制台输出) + +并发安全：level 通过 `atomic.Int32` 存取，运行期热切换无锁。 + +### Changed + +#### console.WithCaller 签名收敛 + +`WithCaller(show bool, skip int)` 改为 `WithCaller(show bool, skip ...int)`——`skip` 99% 用户用不到，强制传是 API 噪音。无 breaking：旧调用 `WithCaller(true, 2)` 仍然合法。 + +### Fixed 🐛 + +#### Logger Tee 重复写入修复（logger 包） + +修复 `logger.Init` 把 `apiCore` 与 `dbCore` 都 Tee 进通用 `Logger`，导致**每条 `logger.Info(...)` 同时落到 `api.log` + `database.log` + console 三份**的 bug。`APILog()` / `DBLog()` 的"分流"在旧实现中形同虚设，且日志体积凭空翻倍。 + +**修复内容**： + +1. **三个 logger 各自独立**： + - `Logger`（通用）→ `logs/app.log` + console + - `APILog()` → `logs/api.log` + console + - `DBLog()` → `logs/database.log` + console + - 互不 Tee，互不串扰 +2. **新增 `logger.Close()`**：关闭文件句柄并把全局 logger 重置为 Nop。`App.Shutdown` 已自动调用。 +3. **Init 健壮性**：`Init(nil)` 不再 panic 改为返回 error；构造失败时不会留下半初始化状态（旧实现 mkdir 之后任意一步失败都会半切换全局变量）。 +4. **`Sync()` 全覆盖**：旧实现只 sync `Logger`，apiLog / dbLog 缓冲不会落盘；新实现 sync 全部三个 logger，并识别忽略 stdout/stderr 平台相关的预期错误。 +5. **生产默认级别从 `Warn` 调整为 `Info`**：原默认在生产丢失大量业务信息，多数项目反而需要在配置里覆盖回 Info；新默认更符合直觉。Debug 级别仍仅在开发模式生效。 + +**新增文件输出**： + +启动后日志目录会出现一个新文件 `logs/app.log`（之前所有通用日志都被串写进 `api.log` / `database.log`）。如果你的运维脚本配置了**只**采集 `api.log` / `database.log`，请补上 `app.log`。 + +**新增测试覆盖**（`logger/logger_test.go`）： +- `TestLoggerNoCrossWriting` — 三个 logger 互不串扰（这是核心修复的回归测试） +- `TestLoggerInitNilConfig` — `Init(nil)` 返回 error +- `TestLoggerSyncBeforeInit` — 未初始化时 `Sync()` 安全返回 nil + +#### JWT JTI 生成忽略 `rand.Read` 错误（jwt 包） + +`generateJTI()` 调用 `crypto/rand.Read` 却丢弃返回的 error，且函数签名只返回 `string`，无法把失败传播给调用方。一旦 `rand.Read` 失败（极罕见，但理论上可能），会基于全零字节生成 JTI，所有 token 的 JTI 完全相同，黑名单机制失效。 + +**修复**：`generateJTI()` 改为 `(string, error)`，`GenerateToken` / `GenerateTokenWithCustomExpiry` 传播该错误。 + +#### `QueryBuilder.Page` 统计行数被残留 Limit 截断（repository 包） + +`Page()` 用 `qb.db.Session(&gorm.Session{})` 复制查询做 Count，但未清除残留的 `Limit`/`Offset`。若调用方先 `.Limit(n).Offset(m)` 再 `.Page(...)`，Count 会被包成 `SELECT count(*) FROM (... LIMIT n)` 子查询，返回的 `total` 被截断为 ≤ n，分页总数错误。 + +**修复**：countDB 增加 `.Limit(-1).Offset(-1)`（GORM 官方惯用法，表示移除该条件）。新增 DryRun 模式回归测试 `repository/page_internal_test.go`，校验 Count SQL 不含 `LIMIT`、Find SQL 仍含分页 `LIMIT`。 + +#### OSS / 本地存储文件名冲突（storage 包） + +4 处上传路径（`LocalStorage.Upload` / `LocalStorage.UploadFromBytes` / `OSSStorage.Upload` / `OSSStorage.UploadFromBytes`）仅用 `time.Now().UnixNano()` 作为文件名。同一纳秒内的并发上传会生成相同 objectKey，后者覆盖前者。 + +**修复**：新增 `uniqueFilename(now, ext)` 辅助函数，格式 `-<8字节crypto/rand hex>.`，4 处统一改用。新增 `storage/unique_internal_test.go` 验证格式与 100 次近似唯一性。 + +#### 数据库重试策略对不可恢复错误无效（database 包） + +`Manager.InitDB` 的重试循环对所有失败都退避重试 5 次。但认证失败（`Access denied`）、未知数据库（`Unknown database`）、非法 DSN（`invalid DSN`）、未注册驱动（`unknown driver` / `unsupported driver`）、不支持的认证插件（`authentication plugin`）属于配置类错误，重试无意义，反而把启动失败延迟 1+2+4+8+16=31 秒。 + +**修复**：新增 `isTransientDBError`，上述错误判为不可恢复，首次出现即直接返回。连接拒绝、I/O 超时等网络类错误仍正常重试。新增 `database/retry_internal_test.go` 用例表覆盖 8 种错误。 + +### Security 🔒 + +#### CORS 中间件修复（middleware/cors.go） + +修复多个 CORS 安全与规范遵守问题。**这是行为变更**——升级后不正确的 CORS 配置会更严格，符合 W3C CORS 规范。 + +**修复内容**： + +1. **`Access-Control-Allow-Credentials` 永远是 `true`** — 旧实现 `if/else` 两个分支都设了 `"true"`，相当于即使配置 `AllowCredentials=false` 也会发送凭证头。修复后**只在显式启用且 Origin 不是 `*` 时**才发送该头。 +2. **`*` + `credentials: true` 的规范违规** — 旧实现配置 `AllowedOrigins=["*"]` 且 `AllowCredentials=true` 时会同时发送 `Allow-Origin: *` 与 `Allow-Credentials: true`，**浏览器会直接拒绝响应**。修复后此场景下回显具体 Origin（spec 允许的兼容做法）。 +3. **缺失 `Vary: Origin`** — 当回显具体 Origin 时，下游 CDN / 网关必须按 Origin 区分缓存，否则可能把 A 用户的 CORS 响应缓存给 B 用户。修复后自动加 `Vary: Origin`。 +4. **开发环境兜底改为回显具体 Origin** — 旧实现开发环境直接发 `*`，与 credentials 不兼容；新实现回显具体 Origin，开发环境也能正常调试带 Cookie 的请求。 + +**升级影响**： + +- 如果你**没有**显式设置 `cors.allow_credentials`：响应将不再带 `Access-Control-Allow-Credentials: true`，前端如果依赖了 Cookie/Authorization，需要在配置里显式打开： + + ```yaml + cors: + allowed_origins: ["https://your-frontend.example"] + allow_credentials: true # 显式启用 + ``` + +- 如果你配置了 `allowed_origins: ["*"]` 且 `allow_credentials: true`：行为更安全（不再发 `*`），无需改动。 +- 已经显式列出 origin 列表的配置：完全无影响。 + +**新增测试覆盖**（`middleware/middleware_test.go`）： +- `TestCORSAllowCredentialsDefault` — 默认不发凭证头 +- `TestCORSAllowCredentialsExplicitOrigin` — 显式 origin + credentials 正常工作 +- `TestCORSWildcardWithCredentials` — `*` + credentials 时回显具体 origin +- `TestCORSWildcardWithoutCredentials` — `*` 单独使用保持通配符语义 +- `TestCORSOriginNotAllowed` — 非白名单 origin 不回显（防反射型 CORS 漏洞） + +### Breaking ⚠️ + +#### 错误码体系重构（response 包） + +修复 `CodeSuccess` 与 `CodeInvalidParams` 撞码的生产级 bug（两者都等于 `1`，导致业务错误响应被前端误判为成功）。 + +**数值变更**： + +| 常量 | 旧值 | 新值 | +|---|---|---| +| `response.CodeSuccess` | `1` | **`0`** | +| `response.CodeFail` | `0` | **`1`** | + +**移除**： + +- `response.CodeInvalidParams`（与 `CodeSuccess` 撞码） +- `response.ErrInvalidParams` + +**迁移指南**： + +1. **前端代码**：`if (resp.code === 1) { /* 成功 */ }` → `if (resp.code === 0) { /* 成功 */ }` +2. **后端代码**： + + ```go + // ❌ 编译失败 + response.FailWithError(c, response.ErrInvalidParams) + + // ✅ 推荐：业务侧自行定义参数错误码（不再由框架内置） + var ErrInvalidParams = response.NewError(40001, "参数错误") + response.FailWithError(c, ErrInvalidParams) + + // ✅ 或直接使用通用失败响应 + 自定义消息 + response.Fail(c, "用户名格式错误") + ``` + +3. **手写常量比较**：`if resp.Code == 0 { /* fail */ }` → `if resp.Code == 1 { /* fail */ }` + +**为什么**： + +- 业内主流约定 `0 = success`（gRPC、HTTP-style 业务码、阿里云 / 腾讯云 OpenAPI 等），改回常规更利于对接 +- 参数错误码各业务系统差异极大（有的用 `400`、有的用 `40001`、有的用 `1001`），框架不应内置 +- 撞码不修是真实生产风险，必须破坏式修正 + +**新增编译期防撞码保护**：`response/error.go` 末尾新增 `_errorCodeUniquenessGuard` map，任何后续 `Code*` 常量重复都会在 `go build` 阶段直接报 `duplicate key in map literal`，杜绝再次撞码。新增 `Code*` 时**必须**登记到该 map。 + +### Dependencies 📦 + +#### `go mod tidy` 补全 postgres 方言间接依赖 + +v1.0.2 引入可插拔方言注册表后，`gorm.io/driver/postgres` 成为直接依赖，但其传递依赖（`jackc/pgpassfile` / `jackc/pgservicefile` / `jackc/pgx/v5` / `jackc/puddle/v2` / `golang.org/x/sync`）此前未在 `go.mod` 显式登记。`go mod tidy` 已补全，避免在干净环境构建时拉到不可预期的版本。 + +#### 安全相关补丁升级（仅补丁/小版本，无 API 变更） + +| 依赖 | 旧 | 新 | +|---|---|---| +| `golang.org/x/crypto` | v0.49.0 | v0.53.0 | +| `github.com/golang-jwt/jwt/v5` | v5.2.1 | v5.3.1 | +| `github.com/gorilla/websocket` | v1.5.1 | v1.5.3 | + +连同其传递依赖（`golang.org/x/net`、`x/sys`、`x/text`、`x/sync`、`x/tools`）一并升级。全量 `go test ./...` 与 `go vet ./...` 通过。 + +#### 暂缓升级（留待下一个小版本） + +以下直接依赖存在可用更新，但跨越多个小版本或含破坏性变更，**不在本次 bugfix release 范围内**，留待 v1.0.4 / v1.1 专门评估： + +- `github.com/gin-gonic/gin` v1.9.1 → v1.12.0 +- `github.com/go-playground/validator/v10` v10.19.0 → v10.30.3 +- `gorm.io/gorm` v1.25.10 → v1.31.1（及其 driver v1.5 → v1.6） +- `github.com/aliyun/aliyun-oss-go-sdk` v2.2.9 → v3.0.2（**major 版本，破坏性**，需迁移） +- `github.com/spf13/viper` v1.18.2、`go.opentelemetry.io/otel` v1.43.0、`go.uber.org/zap` v1.27.0、`github.com/fsnotify/fsnotify` v1.7.0 等 + +--- + +## [1.0.2] - 2026-06-20 + +> 详见 [README 更新日志](./README.md#更新日志) 中的 v1.0.2 章节，本节列出关键摘要。 + +### Added + +- **数据库**：可插拔方言注册表（`database.RegisterDialect`），内置 `mysql` / `postgres`，支持任意 GORM 驱动 +- **数据库**：实例化 `database.Manager`，`ReplicaPicker` 接口（`RoundRobinPicker` / `RandomPicker`） +- **配置**：实例化 `config.Manager`，`SetDefaultManager` 让 App 私有 manager 推为全局默认 +- **App**：`WithFullStack` / `NewFullStack` / `RunFullStack` batteries-included 入口 +- **App**：`Migrator` 类型与 `WithMigrator` / `WithModels`，迁移由用户显式注册 +- **App**：组件 Option 全套（`WithLogger / WithMySQL / WithRedis / WithStorage / WithWire / WithHealthRoutes / WithSwaggerRoutes / WithDefaultRoutes / WithAutoMigrate` 及 `Without*` 对应项） +- **权限**：通用 `AuthUser`、`GetAuthUser`、`RequireUserTypes` / `RequireRoles` / `RequireAuth` +- **健康检查**：`/health` 支持注册 `HealthCheck`，失败返回 HTTP 503 + +### Changed (Breaking) + +- **App**：`xlgo.New()` 默认不再初始化 MySQL / Redis / Storage，也不注册 `/health` 与 `/swagger/*`；需显式 `With*` 启用 +- **权限**：`super_admin / admin / staff` 调整为默认常量而非固定业务模型 +- **错误处理**：框架初始化失败一律 `return error`，不再 `Fatalf` 退出进程 + +### Fixed + +- 修复 `WithConfigPath` 此前的空实现问题 +- 修复读写分离场景下从库连接可能未关闭的问题（改为 `database.CloseAll()` + `errors.Join`） +- 修复此前 README 中错误的 v2.0.0 / v2.1.0 更新日志表述 + +--- + +## [1.0.1] - 2026-04-30 + +### Added + +- 工具函数库、彩色控制台输出、压缩解压、RequestID、Recover 中间件 +- 缓存键名前缀、分布式锁、计数器、Redis 分布式限流 +- 增强 JWT 黑名单、Repository、CORS、日志中间件和优雅关闭能力 +- 路由架构：模块化、版本化 API、中间件分组和 RESTful CRUD +- 配置热更新、数据库读写分离、CSRF、SSE、WebSocket、定时任务、CLI、测试工具、统一错误码 + +--- + +## [1.0.0] - 2024-04 + +### Added + +- 初始版本发布 +- 基础框架功能 +- 完整示例代码 + +[Unreleased]: https://github.com/EthanCodeCraft/xlgo-core/compare/v1.2.0...HEAD +[1.2.0]: https://github.com/EthanCodeCraft/xlgo-core/compare/v1.1.1...v1.2.0 +[1.1.1]: https://github.com/EthanCodeCraft/xlgo-core/releases/tag/v1.1.1 +[1.1.0]: https://github.com/EthanCodeCraft/xlgo-core/releases/tag/v1.1.0 +[1.0.4]: https://github.com/EthanCodeCraft/xlgo-core/releases/tag/v1.0.4 +[1.0.3]: https://github.com/EthanCodeCraft/xlgo-core/releases/tag/v1.0.3 +[1.0.2]: https://github.com/EthanCodeCraft/xlgo-core/compare/v1.0.1...v1.0.3 +[1.0.1]: https://github.com/EthanCodeCraft/xlgo-core/releases/tag/v1.0.1 +[1.0.0]: https://github.com/EthanCodeCraft/xlgo-core/releases/tag/v1.0.0 diff --git a/GUIDE.md b/GUIDE.md new file mode 100644 index 0000000..4574b86 --- /dev/null +++ b/GUIDE.md @@ -0,0 +1,1894 @@ +# xlgo 框架使用指南 + +## 目录 + +1. [快速开始](#1-快速开始) +2. [配置管理](#2-配置管理) +3. [日志系统](#3-日志系统) +4. [数据库操作](#4-数据库操作) +5. [缓存与 Redis](#5-缓存与redis) +6. [请求处理](#6-请求处理) +7. [响应与错误处理](#7-响应与错误处理) +8. [中间件](#8-中间件) +9. [认证与授权](#9-认证与授权) +10. [文件存储](#10-文件存储) +11. [工具函数库](#11-工具函数库) +12. [实时通信](#12-实时通信) +13. [定时任务](#13-定时任务) +14. [链路追踪](#14-链路追踪) +15. [压缩解压](#15-压缩解压) +16. [测试工具](#16-测试工具) +17. [CLI 脚手架](#17-cli脚手架) +18. [最佳实践](#18-最佳实践) + +--- + +## 1. 快速开始 + +> **环境要求**：xlgo 需要 **Go 1.25+**。本项目作为新框架不背负旧版本兼容包袱，可直接使用 Go 1.25 的新特性。 + +### 1.1 安装框架 + +```bash +# 创建新项目 +xlgo new myproject + +# 或手动安装 +go get github.com/EthanCodeCraft/xlgo-core +``` + +### 1.2 项目结构 + +``` +myproject/ +├── config.yaml # 配置文件 +├── main.go # 入口文件 +├── handler/ # 请求处理器 +├── model/ # 数据模型 +├── repository/ # 数据仓库 +├── service/ # 业务逻辑 +├── middleware/ # 自定义中间件 +├── public/ # 静态文件 +├── logs/ # 日志目录 +└── go.mod +``` + +### 1.3 最简示例 + +```go +package main + +import ( + xlgo "github.com/EthanCodeCraft/xlgo-core" + "github.com/EthanCodeCraft/xlgo-core/middleware" + "github.com/EthanCodeCraft/xlgo-core/response" + "github.com/gin-gonic/gin" +) + +func main() { + // v1.0.2 起 xlgo.New 默认是轻量应用，不会自动初始化 MySQL/Redis/Storage， + // 也不会自动注册 /health 或 /swagger/* 路由。 + // 通过 Option 显式启用所需组件即可。 + app := xlgo.New( + xlgo.WithConfigPath("./config.yaml"), + xlgo.WithLogger(), + xlgo.WithDefaultRoutes(), // 同时启用 /health 与 /swagger/* + xlgo.WithMiddlewares(middleware.Logger(), middleware.CORS()), + ) + + // 通过 Engine 直接挂路由，或使用 xlgo.WithModules(...) 注册模块 + app.GetRouter().GET("/hello", func(c *gin.Context) { + response.Success(c, gin.H{"message": "Hello World"}) + }) + + if err := app.Run(); err != nil { + panic(err) + } +} +``` + +> 想要 batteries-included 体验，可改用 `xlgo.NewFullStack(...)` 或 +> `xlgo.RunFullStack(...)`，它会一次性启用 Logger / MySQL / Redis / Storage / +> Wire / Health / Swagger / AutoMigrate 等组件。 + +**优雅关闭特性：** +- 监听系统信号（SIGINT、SIGTERM） +- 等待请求处理完成（最多 30 秒） +- 按顺序关闭各组件（限流器、数据库、Redis、日志） + +--- + +## 2. 配置管理 + +### 2.1 配置文件结构 + +```yaml +# config.yaml +app: + name: "我的应用" + site_name: "my_app" # 站点别名（重要：多项目共用Redis时区分） + version: "1.0.0" + env: "dev" # dev/test/prod + debug: true + base_url: "http://localhost:8080" + +server: + port: 8080 + mode: development # development/production + +database: + host: localhost + port: 3306 + user: root + password: your_password + name: mydb + max_idle_conns: 10 + max_open_conns: 100 + +redis: + host: localhost + port: 6379 + password: "" + db: 0 + +jwt: + secret: your_jwt_secret_key + expire: "24h" # time.Duration，如 "24h"/"30m" + +log: + dir: ./logs + max_size: 100 # MB + max_backups: 30 + max_age: 30 # 天 + compress: true +``` + +### 2.2 使用配置 + +```go +import "github.com/EthanCodeCraft/xlgo-core/config" + +// 加载配置 +cfg, err := config.Load("./config.yaml") + +// 获取配置值 +port := cfg.Server.Port +dbHost := cfg.Database.Host + +// 获取站点别名（用于缓存键前缀） +siteName := cfg.GetSiteName() + +// 判断环境 +if cfg.IsProduction() { + gin.SetMode(gin.ReleaseMode) +} + +// 热更新配置 +config.LoadWithWatch("./config.yaml", func(newCfg *config.Config) { + // 配置变更时的回调 +}) + +// 动态获取配置值 +debug := config.GetBool("app.debug") +``` + +--- + +## 3. 日志系统 + +### 3.1 初始化日志 + +```go +import "github.com/EthanCodeCraft/xlgo-core/logger" + +// 初始化 +logger.Init(cfg) + +// 程序退出前同步 +// v1.0.2 起 Sync 返回 error，可按需处理 +_ = logger.Sync() +``` + +### 3.2 日志级别 + +```go +// 基础日志 +logger.Debug("调试信息") +logger.Info("普通信息") +logger.Warn("警告信息") +logger.Error("错误信息") + +// 格式化日志 +logger.Infof("用户 %s 登录成功", username) +logger.Warnf("请求失败: %v", err) + +// 致命错误（会终止程序）—— 仅在业务进程入口（main 等）使用 +// v1.0.2 起，框架内部已禁止使用 Fatal/Fatalf，初始化错误改为 error 返回 +logger.Fatalf("数据库连接失败: %v", err) + +// 结构化日志 +logger.Info("用户登录", + zap.String("username", "admin"), + zap.Int("user_id", 123), +) +``` + +### 3.3 彩色控制台输出 + +`console` 包定位是**开发期彩色 stdout 工具**——跟 `fmt.Println` 同级，不写文件、不感知运行环境、不做任何隐式行为。 + +```go +import "github.com/EthanCodeCraft/xlgo-core/console" + +console.Debug("调试信息") // 青色 +console.Info("普通信息") // 白色 +console.Success("成功信息") // 绿色 +console.Warn("警告信息") // 黄色 +console.Error("错误信息") // 红色 + +// 自定义配置 +c := console.New( + console.WithColor(true), + console.WithTime(true), + console.WithCaller(true), // skip 可选，默认 2 + console.WithLevel(console.LevelInfo), +) +c.Debug("此条不会输出，已被 LevelInfo 过滤") +c.Info("自定义输出") +``` + +#### console vs logger：怎么选？ + +| 维度 | `console` | `logger` | +|---|---|---| +| 定位 | 开发期肉眼调试 | 业务可观测性记录 | +| 输出目标 | stdout（彩色） | 文件 + stdout | +| 持久化 | ❌ | ✅ 滚动归档 | +| 结构化 | 文本 | JSON 字段 | +| 性能 | 一般 | zap 高性能 | +| 默认级别 | `LevelDebug`（全开） | dev=Debug / prod=Info | +| 适用场景 | 临时打印、开发联调 | 用户登录、订单事件、审计日志 | + +**简单判断**： + +- 这条信息上线后想留 → 用 `logger` +- 这条信息上线就该消失 → 用 `console`，并在 main 中显式切到高级别 + +#### 上线前显式收紧 console 输出 + +```go +func main() { + cfg, _ := config.Load("./config.yaml") + + // 显式选择：生产期 console 只看 Warn / Error + if cfg.IsProduction() { + console.SetLevel(console.LevelWarn) + } + + // 或者完全静默 console（业务全靠 logger） + // console.SetLevel(console.LevelSilent) + + app := xlgo.New(...) + app.Run() +} +``` + +> **注意**：xlgo 不会自动根据 `app.env` 切换 console 级别——选择权完全在调用方。 +> 我们认为隐式切换会带来"开发期看到的 / 生产期看到的"行为不一致，调试体验更糟。 + +--- + +## 4. 数据库操作 + +xlgo 基于 GORM，驱动由配置 `database.driver` 决定。v1.0.2 起 GORM 方言通过 **可插拔注册表** 管理：内置 `mysql`（默认）与 `postgres`（含 `postgresql`、`pg` 别名），应用可通过 `database.RegisterDialect` 接入任意 GORM 驱动；`database.dsn` 字段始终可用于手写连接串。 + +### 4.1 初始化数据库 + +```go +import "github.com/EthanCodeCraft/xlgo-core/database" + +// 初始化数据库（驱动由配置决定，等价于 database.DefaultManager.Load().InitDB(cfg)） +database.InitDB(cfg) + +// 关闭全部连接（含从库） +defer database.CloseAll() + +// 获取数据库实例 +db := database.GetDB() // 主库 +read := database.GetReadDB() // 从库（无从库时回退主库） +``` + +### 4.1.1 主从读写分离 + +```go +// 从库 DSN 列表需与主库驱动匹配 +database.InitDBWithReplicas(cfg, []string{ + "root:pass@tcp(slave1:3306)/db", + "root:pass@tcp(slave2:3306)/db", +}) + +// 选择策略：默认 Random，可换成 RoundRobin +database.SetReplicaPicker(&database.RoundRobinPicker{}) + +// 强制使用主库（事务、需要实时数据的场景） +ctx := database.UseMaster(context.Background()) +database.GetDBFromContext(ctx).Find(&users) + +// 强制使用从库（报表查询） +ctx = database.UseReplica(context.Background()) +database.GetDBFromContext(ctx).Find(&reports) +``` + +### 4.1.2 实例化 Manager + +需要多套数据库连接（如平台库 + 租户库）时，`database.NewManager(cfg)` 创建独立管理器，互不影响： + +```go +mgr := database.NewManager(cfg) +if err := mgr.Open(context.Background()); err != nil { + return err +} +defer mgr.Close() + +mgr.SetPicker(&database.RoundRobinPicker{}) +db := mgr.FromContext(ctx) +``` + +`database.SetDefaultManager(m)` 会把新 manager 提升为全局默认，并关闭被替换的旧 manager，避免连接池泄漏。需要失败回滚或延迟释放旧资源时，请使用 `database.SwapDefaultManager(m)` 并自行关闭其返回的旧 manager。 + +### 4.1.3 注册自定义 GORM 驱动 + +`database.RegisterDialect` 一次注册即让 `database.driver: ` 生效，DSN 构建器同步登记到 `config` 包： + +```go +import ( + "github.com/EthanCodeCraft/xlgo-core/config" + "github.com/EthanCodeCraft/xlgo-core/database" + "gorm.io/driver/sqlite" + "gorm.io/gorm" +) + +func init() { + database.RegisterDialect(database.DialectSpec{ + Name: "sqlite", + Aliases: []string{"sqlite3"}, + Dialector: func(dsn string) gorm.Dialector { return sqlite.Open(dsn) }, + DSN: func(c *config.DatabaseConfig) string { return c.Name }, // Name 当作文件路径 + }) +} +``` + +之后只需把配置改成 `database.driver: sqlite` 即可。SQL Server / ClickHouse / TiDB 等同理。 + +诊断接口： + +- `database.RegisteredDialects()` - 列出已注册驱动（含别名） +- `database.LookupDialect(name)` - 检查某驱动是否可用 +- `config.RegisteredDrivers()` - 列出已登记的 DSN 构建器 + +未注册的驱动会回退到 MySQL 以保持向后兼容。 + +### 4.2 定义模型 + +```go +import "github.com/EthanCodeCraft/xlgo-core/model" + +type User struct { + model.BaseModel // 包含 ID, CreatedAt, UpdatedAt + Username string `gorm:"size:50;unique" json:"username"` + Email string `gorm:"size:100" json:"email"` + Password string `gorm:"size:255" json:"-"` + Status int `gorm:"default:1" json:"status"` +} + +func (User) TableName() string { + return "users" +} +``` + +### 4.3 使用 Repository（扩展版） + +```go +import "github.com/EthanCodeCraft/xlgo-core/repository" + +// 创建仓库 +userRepo := repository.NewBaseRepo[model.User](database.GetDB()) + +// 连接路由（v1.1.1+ 修复 H6c）： +// - 读操作（FindByID/FindAll/FindPage/FindWhere/Count/Exists/...）默认路由到从库， +// 支持 database.UseMaster(ctx)/UseReplica(ctx) 显式路由；未配置从库时回退主库。 +// - 写操作（Create/Update/Delete/*Batch/Restore/...）始终走主库，不路由到只读从库。 +// - DefaultManager 未初始化（如单测注入 sqlite）时回退到 NewBaseRepo 传入的 db。 + +// 基础 CRUD +user, err := userRepo.FindByID(ctx, 1) +users, err := userRepo.FindAll(ctx) +users, err := userRepo.FindByIDs(ctx, []uint{1, 2, 3}) +err := userRepo.Create(ctx, &user) +err := userRepo.Update(ctx, &user) // Save 全列覆写（含零值），见下方 UpdateFields +err := userRepo.Delete(ctx, 1) // T 含 gorm.Model 时软删除，否则硬删除 + +// 局部更新（推荐，H6a）：避免 Save 全列覆写丢失更新/零值不可辨 +err := userRepo.UpdateFields(ctx, &model.User{Name: "new"}, "id = ?", id) // struct 仅更新非零字段 +err := userRepo.UpdateFields(ctx, map[string]any{"status": 0}, "id = ?", id) // map 可显式置零 + +// 统计数量 +count, err := userRepo.Count(ctx) +count, err := userRepo.CountWhere(ctx, "status = ?", 1) + +// 分页查询（内置） +result, err := userRepo.FindPage(ctx, 1, 20) +// result.Items - 数据列表 +// result.Total - 总数 +// result.Page - 当前页 +// result.PageSize - 每页数量 + +// 条件分页查询 +result, err := userRepo.FindPageWhere(ctx, 1, 20, "status = ?", 1) + +// 分页并排序 +result, err := userRepo.FindPageOrdered(ctx, 1, 20, "created_at DESC") + +// 条件查询 +user, err := userRepo.FindOne(ctx, "email = ?", "test@example.com") +users, err := userRepo.FindWhere(ctx, "status = ?", 1) +users, err := userRepo.FindWhereOrdered(ctx, "created_at DESC", "status = ?", 1) + +// 排序查询 +users, err := userRepo.FindOrdered(ctx, "created_at DESC", 10) + +// 批量操作 +err := userRepo.CreateBatch(ctx, users) +err := userRepo.UpdateBatch(ctx, []uint{1, 2}, "status", 2) +err := userRepo.DeleteBatch(ctx, []uint{1, 2, 3}) + +// 存在性检查 +exists, err := userRepo.Exists(ctx, 1) +exists, err := userRepo.ExistsWhere(ctx, "email = ?", "test@example.com") + +// 软删除恢复 +err := userRepo.Restore(ctx, 1) +err := userRepo.RestoreBatch(ctx, []uint{1, 2}) + +// 查询已删除的记录 +deletedUsers, err := userRepo.FindDeleted(ctx) + +// 链式查询（灵活构建；QueryBuilder 为单次使用、非并发安全） +users, err := userRepo.NewQueryBuilder(). + Where("status = ?", 1). + Where("role = ?", "admin"). + Order("created_at DESC"). + Limit(10). + Find(ctx) + +// 链式分页查询 +result, err := userRepo.NewQueryBuilder(). + Where("status = ?", 1). + Order("created_at DESC"). + Page(ctx, 1, 20) + +// 事务支持 +err := userRepo.WithTransaction(ctx, func(txRepo *repository.BaseRepo[model.User]) error { + // 创建用户 + if err := txRepo.Create(ctx, &user); err != nil { + return err + } + // 更新关联数据 + return txRepo.Update(ctx, &profile) +}) + +// 跨层/跨 repo 事务 join（H6c）：把外层事务注入 ctx 后传给任意 repo 方法 +err := database.TransactionWithContext(ctx, func(tx *gorm.DB) error { + ctx2 := database.WithTx(ctx, tx) + if err := userRepo.Create(ctx2, &user); err != nil { + return err + } + return otherRepo.Update(ctx2, &other) // 同一事务 +}) +``` + +### 4.4 Model 基础模型 + +```go +import "github.com/EthanCodeCraft/xlgo-core/model" + +// BaseModel 包含 ID、CreatedAt、UpdatedAt、DeletedAt +type User struct { + model.BaseModel // 自动包含 ID、时间戳、软删除 + Username string `gorm:"size:50;unique" json:"username"` + Email string `gorm:"size:100" json:"email"` + Status int `gorm:"default:1" json:"status"` +} + +// BaseModel 字段说明 +// ID uint - 主键 +// CreatedAt time.Time - 创建时间 +// UpdatedAt time.Time - 更新时间 +// DeletedAt gorm.DeletedAt - 软删除时间（不返回给前端） +``` + +--- + +## 5. 缓存与 Redis + +### 5.1 初始化缓存 + +> **v1.4.0**：App 用户经 `WithRedis()` 启用时，`Init` 自动用 `app.redisManager.Client()` 初始化缓存 +> （走 App 自己的 Redis，多 App 隔离，不串越）。下方 `cache.Init()`（包级）用于 standalone 或回退全局 Redis。 + +```go +import "github.com/EthanCodeCraft/xlgo-core/cache" + +// 初始化（通常在应用启动时） +cache.Init() + +// 获取缓存实例 +c := cache.GetCache() +``` + +### 5.2 缓存操作 + +```go +// 设置缓存 +c.Set(ctx, "user:1", userData, 30*time.Minute) + +// 获取缓存（命中返回 true，未命中返回 false,nil，后端错误返回 err） +var user User +if hit, err := c.Get(ctx, "user:1", &user); err != nil { + return err +} else if hit { + // 缓存命中 +} + +// 删除缓存 +c.Delete(ctx, "user:1") + +// 批量删除（按模式） +c.DeleteByPattern(ctx, "user:*") + +// 检查是否存在（未命中 false,nil；后端错误返回 err） +exists, err := c.Exists(ctx, "user:1") +if err != nil { + return err +} +``` + +### 5.3 键名前缀管理（多站点共用 Redis） + +```go +import "github.com/EthanCodeCraft/xlgo-core/cache" + +// 自动从配置读取 site_name 作为前缀 +// config.yaml: app.site_name: "my_app" + +cache.K("user:1") // → "cache:my_app:user:1" +cache.KTemp("token") // → "temp:my_app:token" +cache.KPerm("config") // → "perm:my_app:config" +cache.KLock("order:123") // → "lock:my_app:order:123" +cache.KCounter("visit") // → "counter:my_app:visit" +cache.KSession("sid") // → "session:my_app:sid" + +// 使用带前缀的缓存 +c.Set(ctx, cache.K("user:1"), userData, ttl) +hit, err := c.Get(ctx, cache.K("user:1"), &user) +if err != nil { + return err +} +``` + +### 5.4 分布式锁（安全增强版） + +**使用 Lua 脚本 + UUID Token，只有锁的持有者才能释放锁：** + +```go +// 安全加锁（返回 LockToken） +token, err := cache.NewLock(ctx, cache.KLock("pay:123"), 30*time.Second) +if token != nil { + defer cache.Unlock(ctx, token) // 只有持有者能释放 + // 执行业务逻辑 +} + +// 带重试的锁 +token, err := cache.TryLock(ctx, key, ttl, 100*time.Millisecond, 10) +if token != nil { + defer cache.Unlock(ctx, token) +} + +// 自动管理锁（简单场景） +err := cache.WithLock(ctx, key, ttl, func(ctx context.Context) error { + return nil +}) + +// 自动续期锁（长任务场景） +err := cache.WithLockAutoExtend(ctx, key, 30*time.Second, 10*time.Second, func(ctx context.Context) error { + // 执行时间超过 TTL 时自动续期 + return nil +}) + +// 续期锁（手动续期） +cache.ExtendLock(ctx, token, 30*time.Second) + +// 检查锁是否被占用（Redis 不可用时返回 ErrRedisNotReady，可经 +// errors.Is(err, cache.ErrRedisNotReady) 与"锁未占用"区分） +locked, err := cache.IsLocked(ctx, key) + +// 强制释放锁（管理场景；Redis 不可用时返回 ErrRedisNotReady） +if err := cache.ForceUnlock(ctx, key); err != nil { + // 处理 Redis 不可用 +} +``` + +**安全特性：** +- Lua 脚本保证原子性操作 +- UUID Token 标识锁的持有者 +- 只有持有者才能释放锁（防止误释放） +- 支持续期（长任务不会因锁过期而中断） + +### 5.5 计数器 + +```go +// 自增 +n, err := cache.Incr(ctx, cache.KCounter("page_view")) + +// 指定增量 +n, err := cache.IncrBy(ctx, key, 10) + +// 自减 +n, err := cache.Decr(ctx, key) + +// 设置过期时间 +cache.SetExpire(ctx, key, 1*time.Hour) + +// 获取剩余时间 +ttl, err := cache.GetTTL(ctx, key) +``` + +--- + +## 6. 请求处理 + +### 6.1 参数获取 + +```go +import "github.com/EthanCodeCraft/xlgo-core/handler" + +// 类型安全的参数获取（推荐） + +// Query参数 +page := handler.QueryInt(c, "page", 1) // Query参数 → int +id := handler.QueryInt64(c, "id", 0) // Query参数 → int64 +price := handler.QueryFloat64(c, "price", 0.0) // Query参数 → float64 +enabled := handler.QueryBool(c, "enabled", false) // Query参数 → bool + +// 路径参数（RESTful API） +id := handler.PathInt(c, "id", 0) // 路径参数 → int +id := handler.PathInt64(c, "id", 0) // 路径参数 → int64 +id := handler.PathUint64(c, "id", 0) // 路径参数 → uint64 + +// 表单参数（POST提交） +count := handler.FormInt(c, "count", 0) // 表单参数 → int +id := handler.FormInt64(c, "id", 0) // 表单参数 → int64 +id := handler.FormUint64(c, "id", 0) // 表单参数 → uint64 +price := handler.FormFloat64(c, "price", 0.0) // 表单参数 → float64 +enabled := handler.FormBool(c, "enabled", false) // 表单参数 → bool +name := handler.FormString(c, "name", "") // 表单参数 → string + +// 分页参数 +page, pageSize := handler.GetPage(c) // 默认 page=1, pageSize=20 + +// 路径ID +id, ok := handler.GetIDFromPath(c, "id") + +// 绑定请求 +var req LoginRequest +handler.BindJSON(c, &req) +``` + +### 6.2 请求验证 + +```go +import "github.com/EthanCodeCraft/xlgo-core/validation" + +type RegisterRequest struct { + Username string `json:"username" label:"用户名" validate:"required,min=3,max=20" msg_required:"用户名不能为空"` + Password string `json:"password" label:"密码" validate:"required,password" msg_required:"密码不能为空"` + Email string `json:"email" label:"邮箱" validate:"required,email" msg_required:"邮箱不能为空"` + Phone string `json:"phone" label:"手机号" validate:"omitempty,phone"` +} + +// 绑定并验证 +errors, ok := validation.ShouldBindAndValidate(c, &req) +if !ok { + response.Fail(c, errors.Error()) + return +} +``` + +### 6.3 验证规则 + +| 规则 | 说明 | +| ---------- | ------------------------------------- | +| `required` | 必填 | +| `min=3` | 最小长度 | +| `max=20` | 最大长度 | +| `email` | 邮箱格式 | +| `phone` | 手机号格式 | +| `phone_strict` | 手机号严格校验（验证运营商号段） | +| `password` | 密码强度（8-72 字节，需含大写+小写+数字） | +| `username` | 字母开头，3-20 位字母/数字/下划线 | +| `url` | URL 格式 | +| `ip` | IP 地址格式 | + +--- + +## 7. 响应与错误处理 + +### 7.1 统一响应格式 + +```json +{ + "code": 1, + "msg": "操作成功", + "data": {}, + "request_id": "abc123" +} +``` + +### 7.2 成功响应 + +```go +import "github.com/EthanCodeCraft/xlgo-core/response" + +// 基础成功响应 +response.Success(c, gin.H{"user": user}) + +// 自定义消息 +response.SuccessWithMsg(c, "注册成功", gin.H{"user_id": 123}) + +// 分页响应 +response.Page(c, users, total, page, pageSize) +``` + +### 7.3 错误响应 + +```go +// 基础失败 +response.Fail(c, "参数错误") + +// 自定义错误码 +response.FailWithCode(c, response.CodeUserNotFound, "用户不存在") + +// 使用预定义错误 +response.FailWithError(c, response.ErrUserNotFound) + +// 带详细信息 +response.FailWithDetail(c, response.ErrPasswordWrong, "连续错误3次将锁定") +``` + +### 7.4 预定义错误码 + +> 注：参数错误等业务化错误码请由业务项目自行定义，框架不再内置 `ErrInvalidParams`。 +> 推荐使用 `response.NewError(40001, "参数错误")` 在业务侧统一管理。 + +| 错误 | 码 | 说明 | +| ------------------ | ------ | ---------- | +| `ErrUnauthorized` | 401 | 未授权 | +| `ErrForbidden` | 403 | 无权限访问 | +| `ErrNotFound` | 404 | 资源不存在 | +| `ErrRateLimit` | 429 | 请求过于频繁 | +| `ErrServerError` | 500 | 服务器错误 | +| `ErrUserNotFound` | 10001 | 用户不存在 | +| `ErrPasswordWrong` | 10004 | 密码错误 | + +### 7.5 特殊响应 + +```go +// 文件下载 +response.Download(c, "report.xlsx", fileData) +// 大文件/对象存储流式下载优先使用 DownloadReader + +// HTML响应 +response.HTML(c, "...") +// HTML 会原样输出；只传入可信或已清洗的 markup + +// 页面跳转 +response.Redirect(c, 302, "https://example.com") +``` + +--- + +## 8. 中间件 + +### 8.1 内置中间件 + +```go +import "github.com/EthanCodeCraft/xlgo-core/middleware" + +// 日志中间件（默认配置） +r.Use(middleware.Logger()) + +// API 专用日志（记录请求体） +r.Use(middleware.LoggerForAPI()) + +// 调试日志（最详细，记录请求体和响应体） +r.Use(middleware.LoggerForDebug()) + +// 最简日志（只记录基本信息） +r.Use(middleware.LoggerMinimal()) + +// 自定义日志配置 +r.Use(middleware.LoggerWithConfig(middleware.LoggerConfig{ + LogRequestBody: true, // 记录请求体 + LogResponseBody: false, // 不记录响应体 + MaxBodyLength: 2048, // 最大记录长度 + SkipPaths: []string{"/health"}, // 跳过路径 + SlowRequestThreshold: 500 * time.Millisecond, // 慢请求阈值 +})) + +// CORS跨域 +r.Use(middleware.CORS()) + +// 请求ID（追踪） +r.Use(middleware.RequestID()) + +// Panic恢复 +r.Use(middleware.Recover()) + +// 认证中间件 +r.Use(middleware.AuthRequired()) + +// 自定义用户类型权限 +r.Use(middleware.RequireUserTypes("tenant_admin", "platform_admin")) + +// 自定义角色权限 +r.Use(middleware.RequireRoles("owner", "manager")) + +// 默认快捷权限（super_admin/admin/staff 只是默认常量） +r.Use(middleware.AdminRequired()) + +// CSRF防护 +r.Use(middleware.CSRF()) +``` + +### 8.2 CORS 配置（支持配置文件） + +```yaml +# config.yaml 添加 CORS 配置 +cors: + allowed_origins: + - "https://example.com" + - "https://app.example.com" + - "*.example.com" # 支持通配符 + allowed_methods: + - "GET" + - "POST" + - "PUT" + - "DELETE" + allowed_headers: + - "Content-Type" + - "Authorization" + allow_credentials: true + max_age: 86400 # 预检请求缓存时间（秒） +``` + +```go +// 使用配置文件的 CORS +r.Use(middleware.CORS()) + +// 指定域名列表 +r.Use(middleware.CORSWithOrigins([]string{ + "https://example.com", + "https://app.example.com", +})) + +// 允许所有来源（仅开发环境） +r.Use(middleware.CORSWithWildcard()) + +// API 专用 CORS（不允许凭证） +r.Use(middleware.CORSForAPI()) +``` + +**生产环境 CORS 配置建议：** +- 必须配置具体的 `allowed_origins` +- 不使用 `*` 通配符 +- 根据需要配置 `allow_credentials` + +### 8.3 CSRF 防护 + +```go +// Cookie模式（Web应用） +r.Use(middleware.CSRF()) + +// 双重提交Cookie模式（无状态） +r.Use(middleware.DoubleSubmitCookie()) + +// API模式 +r.Use(middleware.CSRFForAPI()) + +// 获取Token +token := middleware.GetCSRFToken(c) +``` + +### 8.4 限流（支持 Redis 分布式限流） + +> **v1.4.0**：App 持专属 `RateLimitRegistry`，`Shutdown` 调 `registry.Stop()`（不再调全局 +> `StopRateLimiters`，避免误停其他 App 的限流器）。下方包级 `LoginRateLimit`/`APIRateLimit`/等仍可用 +> （请求时解析全局默认 Registry，单 App 场景无变化）。**多 App per-App 计数隔离**用 +> `app.RateLimitRegistry().LoginRateLimit()` 等 App-bound 中间件（捕获 App 自己的 Registry，不查全局）。 +> **多 App 走各自 Redis** 用 `middleware.NewRedisRateLimiter(..., middleware.WithRedisClient(app.RedisClient()))`。 + +```go +// 初始化限流器 +middleware.InitRateLimiters() + +// 内存限流（单实例） +r.POST("/login", middleware.LoginRateLimit(), func(c *gin.Context) { + response.Success(c, gin.H{"token": "..."}) +}) // 每分钟10次 +r.POST("/upload", middleware.UploadRateLimit(), func(c *gin.Context) { + response.Success(c, gin.H{"file": "..."}) +}) // 每分钟20次 +r.Use(middleware.APIRateLimit()) // 每分钟100次 + +// 自定义内存限流 +r.Use(middleware.CustomRateLimit(50, time.Minute)) // 每分钟50次 + +// Redis 分布式限流（多实例共享） +r.Use(middleware.RedisRateLimit("api_limit", 100)) // 每分钟100次（fail-open：Redis 故障时放行） +r.Use(middleware.LoginRedisRateLimit()) // 登录限流（fail-closed：Redis 故障时拒绝，防爆破） +r.Use(middleware.APIRedisRateLimit()) // API限流（fail-open） +r.Use(middleware.UploadRedisRateLimit()) // 上传限流（fail-closed：资源敏感，Redis 故障时拒绝） + +// 自定义 Redis 限流（默认 fail-open，传 WithFailClosed(true) 切换为 fail-closed） +r.Use(middleware.CustomRedisRateLimit("custom", 50, time.Minute)) // fail-open +r.Use(middleware.CustomRedisRateLimit("sensitive", 50, time.Minute, middleware.WithFailClosed(true))) // fail-closed（安全场景） + +// 自定义标识限流（如按用户ID，同样支持 WithFailClosed） +r.Use(middleware.RedisRateLimitWithIdentifier("user_limit", 100, func(c *gin.Context) string { + return fmt.Sprintf("user:%d", middleware.GetUserID(c)) +})) + +// 停止限流器（应用关闭时） +defer middleware.StopRateLimiters() +``` + +> **fail-open vs fail-closed（H4c）**：Redis 限流器在 Redis 故障时有两种策略—— +> - **fail-open**（默认）：Redis 故障时放行，避免影响业务，但限流静默失效。 +> - **fail-closed**（`WithFailClosed(true)`）：Redis 故障时拒绝（HTTP 503），防限流静默失效。**安全敏感场景（登录防爆破、上传、敏感操作）必须用 fail-closed**。 +> `RedisRateLimiter` 可经 `NewRedisRateLimiter(..., WithFailClosed(true))` 构造或 `SetFailClosed(true)` 切换策略。 + +**内存限流 vs Redis 限流：** +- 内存限流：单实例使用，简单高效 +- Redis 限流：多实例共享，滑动窗口算法，分布式场景必需 + +### 8.5 路由架构 + +框架提供灵活的路由系统，支持模块化、版本化 API 和中间件分组。 + +#### 8.4.1 模块化路由 + +```go +import "github.com/EthanCodeCraft/xlgo-core/router" + +// 方式一：实现 Module 接口 +type UserModule struct{} + +func (m *UserModule) Name() string { return "user" } +func (m *UserModule) Register(r *gin.RouterGroup) { + r.GET("/users", listUsers) + r.POST("/users", createUser) + r.GET("/users/:id", getUser) +} + +// 方式二：函数式注册 +router.ModuleFunc(func(r *gin.RouterGroup) { + r.GET("/users", listUsers) +}) + +// 使用 +app := xlgo.New( + xlgo.WithModules(&UserModule{}), +) +``` + +#### 8.4.2 版本化 API + +```go +// 单版本 +v1 := router.NewVersion("v1", "/api/v1") +v1.AddModuleFunc("user", func(r *gin.RouterGroup) { + r.GET("/users", listUsersV1) +}) + +// 多版本共存 +v1 := router.NewVersion("v1", "/api/v1") +v1.AddModuleFunc("user", func(r *gin.RouterGroup) { + r.GET("/users", listUsersV1) // 旧版本 +}) + +v2 := router.NewVersion("v2", "/api/v2") +v2.AddModuleFunc("user", func(r *gin.RouterGroup) { + r.GET("/users", listUsersV2) // 新版本 + r.GET("/users/:id/profile", getProfile) // 新增功能 +}) + +app := xlgo.New(xlgo.WithVersions(v1, v2)) + +// 结果： +// GET /api/v1/users -> listUsersV1 +// GET /api/v2/users -> listUsersV2 +``` + +#### 8.4.3 版本级中间件 + +```go +v1 := router.NewVersion("v1", "/api/v1", + middleware.CustomRateLimit(100, time.Minute), // 版本级限流 + middleware.AuthRequired(), // 版本级认证 +) +v1.AddModuleFunc("user", userRoutes) + +// 该版本所有路由自动应用限流和认证 +``` + +#### 8.4.4 中间件分组 + +```go +// 创建分组 +authGroup := router.NewMiddlewareGroup("auth", + middleware.AuthRequired(), + middleware.RequireUserTypes("tenant_admin", "platform_admin"), +) + +publicGroup := router.NewMiddlewareGroup("public", + middleware.CustomRateLimit(1000, time.Minute), +) + +// 注册分组 +registry := router.NewRegistry(engine) +registry.RegisterMiddlewareGroup(authGroup) +registry.RegisterMiddlewareGroup(publicGroup) + +// 使用分组 +userGroup := router.GroupWithMiddlewareGroup(engine, "/users", "auth") +userGroup.GET("/:id", getUser) +``` + +#### 8.4.5 RESTful CRUD + +```go +registry.RegisterModuleFunc("product", func(r *gin.RouterGroup) { + rest := router.NewRESTful(r, "/products") + + // 一行注册标准 CRUD + rest.CRUD( + listProducts, // GET /products + getProduct, // GET /products/:id + createProduct, // POST /products + updateProduct, // PUT /products/:id + deleteProduct, // DELETE /products/:id + ) +}) + +// 部分 CRUD（只注册需要的） +rest := router.NewRESTful(r, "/articles") +rest.CRUD(listArticles, getArticle, createArticle, nil, nil) +``` + +#### 8.4.6 全局注册方式 + +```go +engine := gin.New() +router.Init(engine) + +// 全局中间件 +router.Use(middleware.CORS(), middleware.Logger()) + +// 注册模块 +router.RegisterModule(&UserModule{}) +router.RegisterModuleFunc("health", func(r *gin.RouterGroup) { + r.GET("/health", healthCheck) +}) + +// 注册版本 +router.RegisterVersion(router.NewVersion("v1", "/api/v1")) + +// 应用路由 +router.Apply() + +// 启动服务（如需优雅关闭与生命周期管理，改用 app := xlgo.New(...); app.Run()） +engine.Run(":8080") +``` + +#### 8.4.7 默认路由 + +v1.0.2 起，`xlgo.New()` 默认是 **轻量应用**，不会自动注册任何默认路由。 +按需通过下列 Option 显式启用： + +```go +xlgo.New( + xlgo.WithHealthRoutes(), // 注册 /health + xlgo.WithSwaggerRoutes(), // 注册 /swagger/*any + // 或一步到位： + xlgo.WithDefaultRoutes(), // 同时注册 /health 与 /swagger/*any +) +``` + +也可以使用 `xlgo.NewFullStack(...)` / `xlgo.RunFullStack(...)` 启用全部默认组件。 + +> 生产环境建议关闭 Swagger，仅保留 `WithHealthRoutes()`，避免文档接口意外暴露。 + +--- + +## 9. 认证与授权 + +### 9.1 JWT 使用（黑名单优化版） + +**使用 JTI（JWT ID）替代完整 Token 存储黑名单，大幅节省 Redis 内存：** + +```go +import "github.com/EthanCodeCraft/xlgo-core/jwt" + +// 生成Token（自动包含唯一 JTI） +token, err := jwt.GenerateToken(userID, username, "admin", "admin") + +// 解析Token（默认 fail-closed：黑名单后端不可检查时拒绝 Token，需 Redis） +claims, err := jwt.ParseToken(tokenString) + +// 使Token失效（使用 JTI，内存占用约 30 字节） +jwt.InvalidateToken(tokenString) + +// 获取 Token 的 JTI +jti, err := jwt.GetJTI(tokenString) + +// 直接通过 JTI 撤销 Token +jwt.InvalidateTokenByID(jti, expiryTime) + +// 自定义过期时间 +token, err := jwt.GenerateTokenWithCustomExpiry(userID, username, "admin", "admin", 3600) + +// 刷新Token（旧Token自动加入黑名单） +newToken, err := jwt.RefreshToken(oldToken) + +// 获取已过期Token的信息（不验证过期） +claims, err := jwt.GetClaimsFromToken(tokenString) +``` + +**黑名单优化说明：** +- 每个Token自动生成唯一JTI（约24字节） +- 黑名单键名：`jwt_bl:{jti}`（而非完整Token） +- 内存节省：从数百字节降到约30字节每条记录 + +### 9.2 获取用户信息 + +```go +// 一次性取出全部认证信息（v1.0.2 推荐） +if user, ok := middleware.GetAuthUser(c); ok { + _ = user.UserID + _ = user.Username + _ = user.Role + _ = user.UserType +} + +// 单字段便捷函数（与旧版兼容） +userID := middleware.GetUserID(c) +username := middleware.GetUsername(c) +userType := middleware.GetUserType(c) // super_admin/admin/staff 等，由业务定义 +``` + +### 9.3 密码加密 + +```go +import "github.com/EthanCodeCraft/xlgo-core/validation" + +// 加密密码 +hash, err := validation.HashPassword("password123") + +// 验证密码 +if validation.CheckPassword(hash, "password123") { + // 密码正确 +} + +// 验证并自动升级成本 +match, needUpgrade, newHash, err := validation.CheckPasswordAndUpgrade(hash, password, 12) +``` + +--- + +## 10. 文件存储 + +### 10.1 本地存储 + +```yaml +storage: + driver: local + local: + path: ./public + base_url: http://localhost:8080/public +``` + +### 10.2 阿里云 OSS + +```yaml +storage: + driver: oss + oss: + endpoint: oss-cn-hangzhou.aliyuncs.com + bucket: my-bucket + access_key_id: your_key + access_key_secret: your_secret + base_url: https://my-bucket.oss-cn-hangzhou.aliyuncs.com +``` + +### 10.3 使用存储 + +> **v1.4.0**：App 用户经 `WithStorage()` 启用时，`Init` 自动初始化存储并提升为全局默认；`Shutdown` +> 经 `StorageManager.Close()` 收口（当前 LocalStorage/OSSStorage 无 closeable 资源为 no-op，为未来 +> 驱动预留）。下方 `storage.Init()`（包级）用于 standalone。 + +```go +import "github.com/EthanCodeCraft/xlgo-core/storage" + +// 初始化 +if err := storage.Init(&cfg.Storage); err != nil { + return err +} + +// 上传文件（从请求中获取） +file, _ := c.FormFile("file") +path, err := storage.Upload(file, "images") + +// 获取访问 URL +url := storage.GetURL(path) + +// 上传字节数据 +path, err := storage.UploadFromBytes(data, "avatar.jpg", "images") + +// 删除文件 +err := storage.Delete(path) + +// 获取文件内容 +data, err := storage.Get(path) + +// 检查文件是否存在（不存在 false,nil；后端错误返回 err） +ok, err := storage.Exists(path) +if err != nil { + return err +} +if ok { + // 文件存在 +} +``` + +--- + +## 11. 工具函数库 + +### 11.1 随机数生成 + +**安全选型**：字符串随机（token/OTP/验证码/会话 ID/nonce）用 `RandStringSecure`/`RandDigitSecure` +（基于 `crypto/rand`，不可预测）。`RandString`/`RandDigit`（math/rand 版本）已移除—— +字符串随机的用途几乎都是安全场景，保留 math/rand 版本会诱导误用。 + +```go +import "github.com/EthanCodeCraft/xlgo-core/utils" + +// 安全场景：token、会话 ID、API key（crypto/rand，不可预测） +token, err := utils.RandStringSecure(32) +if err != nil { + // 处理 crypto/rand 失败（极罕见，通常仅系统熵池耗尽） +} + +// 安全场景：6 位 OTP 验证码、密码重置码（crypto/rand） +code, err := utils.RandDigitSecure(6) + +// 安全场景：安全 nonce 范围、防猜抽奖、密钥分桶（crypto/rand 无偏） +idx, err := utils.RandIntSecure(0, 1000) + +// 范围随机数（非密码学安全，仅用于负载均衡/游戏/A-B 分桶等非安全场景） +n := utils.RandInt(1, 100) +``` + +> 非安全场景需要高性能随机串时，直接用标准库 `math/rand` 即可，框架不再提供 +> 易误用的 `RandString`/`RandDigit`。 + +### 11.2 字符串处理 + +```go +// 检查空白 +if utils.IsBlank(str) { } + +// 批量检查 +if utils.IsAnyBlank(name, email, phone) { } + +// 默认值 +name := utils.DefaultIfBlank(name, "未知") + +// Unicode长度（中文） +len := utils.StrLen("你好世界") // 4 + +// 截取子串（支持中文） +sub := utils.Substr("你好世界", 0, 2) // "你好" + +// 不区分大小写比较 +if utils.EqualsIgnoreCase("Admin", "admin") { } +``` + +### 11.3 时间日期 + +```go +// 时间戳 +now := utils.NowUnix() // 秒 +now := utils.NowTimestamp() // 毫秒 + +// 时间戳转时间 +t := utils.FromUnix(unix) +t := utils.FromTimestamp(ms) + +// 格式化 +s := utils.FormatDateTime(t) // "2006-01-02 15:04:05" +s := utils.FormatDate(t) // "2006-01-02" + +// 获取当天开始/结束 +start := utils.StartOfDay(t) +end := utils.EndOfDay(t) + +// 获取当月开始/结束 +start := utils.StartOfMonth(t) +end := utils.EndOfMonth(t) +``` + +### 11.4 类型转换 + +```go +// 字符串转数字 +n := utils.ToInt("123") +n := utils.ToIntDefault("abc", 0) // 失败返回默认值 + +n := utils.ToInt64("123") +f := utils.ToFloat64("3.14") + +// 分页计算 +totalPages := utils.CalcPageCount(100, 10) // 10页 +offset := utils.CalcOffset(2, 20) // 20 +``` + +### 11.5 文件操作 + +```go +// 检查存在 +utils.FileExists(path) +utils.DirExists(path) + +// 确保目录存在 +utils.EnsureDir(path) + +// 读写文件 +data, err := utils.ReadFile(path) +err := utils.WriteFile(path, data) +err := utils.AppendFile(path, []byte("\nnew line")) + +// 复制文件 +err := utils.CopyFile(dst, src) + +// 获取文件大小 +size, err := utils.FileSize(path) +``` + +### 11.6 格式验证 + +```go +// 手机号 +if utils.IsPhone("13812345678") { } + +// 邮箱 +if utils.IsEmail("test@example.com") { } + +// IPv4 +if utils.IsIPv4("192.168.1.1") { } + +// 身份证 +if utils.IsIDCard(id) { } + +// 纯数字 +if utils.IsNumeric(str) { } + +// 字母数字 +if utils.IsAlphanumeric(str) { } +``` + +### 11.7 HTTP 客户端（连接池优化版） + +```go +import "github.com/EthanCodeCraft/xlgo-core/utils" + +// 创建客户端（Transport 在初始化时创建，连接池可复用） +client := utils.NewHTTPClient() + +// 自定义配置 +client = utils.NewHTTPClientWithConfig(utils.HTTPClientConfig{ + Timeout: 30 * time.Second, + MaxIdleConns: 100, // 最大空闲连接数 + MaxIdleConnsPerHost: 10, // 每主机最大空闲连接 + IdleConnTimeout: 90 * time.Second, // 空闲连接超时 +}) + +// 链式配置 +client.SetTimeout(30 * time.Second) +client.SetHeader("Authorization", "Bearer xxx") +client.SetSkipTLS(false) // 生产环境建议设为 false + +// GET请求 +data, err := client.Get(url, map[string]string{"page": "1"}) + +// POST表单 +data, err := client.Post(url, map[string]string{"name": "test"}) + +// POST JSON +data, err := client.PostJSON(url, map[string]any{"name": "test"}) + +// PUT请求 +data, err := client.Put(url, map[string]any{"id": 1}) + +// DELETE请求 +data, err := client.Delete(url) + +// 上传文件 +files := []utils.UploadFile{ + {FieldName: "file", FilePath: "/path/to/file"}, +} +data, err := client.Upload(url, files, params) + +// 从字节数据上传 +data, err := client.UploadFromBytes(url, "file", "image.jpg", fileData, params) + +// 自定义请求 +data, err := client.Request("PATCH", url, bodyData) + +// 关闭客户端（释放连接池资源） +client.Close() +``` + +**HTTPClient 特性：** +- Transport 初始化时创建，连接池可复用 +- 支持连接池参数配置 +- 全局默认客户端：`utils.DefaultHTTPClient()` +- 快捷函数：`utils.HTTPGet/HTTPPost/HTTPPostJSON` + +### 11.8 UUID + +```go +// UUID v4 +uuid := utils.UUID() // "550e8400-e29b-41d4-a716-446655440000" + +// 短UUID（无横线） +uuid := utils.UUIDShort() // "550e8400e29b41d4a716446655440000" + +// 验证UUID +if utils.UUIDValid(uuid) { } +``` + +### 11.9 函数评估表 + +| 分类 | 高分函数（⭐⭐⭐⭐⭐） | 说明 | +|------|---------------------|------| +| **随机（安全）** | `RandStringSecure/RandDigitSecure/RandIntSecure/RandInt64Secure` | crypto/rand，token/OTP/nonce 用 | +| **随机（范围）** | `RandInt/RandInt64` | math/rand，负载均衡/游戏等非安全场景 | +| **字符串** | `IsBlank/DefaultIfBlank/StrLen` | 空值处理、Unicode支持 | +| **时间** | `FormatDateTime/StartOfDay/EndOfMonth` | 标准格式、边界计算 | +| **转换** | `ToIntDefault/CalcPageCount/CalcOffset` | 安全转换、分页计算 | +| **文件** | `FileExists/DirExists/EnsureDir/CopyFile` | 路径检查、目录创建 | +| **验证** | `IsIPv4/IsNumeric/IsAlphanumeric` | 格式验证 | +| **URL** | `ParseURL/URLBuilder` | 链式构建URL | +| **加密** | `SHA256/Base64Encode/Base64URLEncode` | 安全哈希、编码 | +| **HTTP** | `NewHTTPClient/Get/PostJSON/Upload` | 连接池、链式调用 | +| **UUID** | `UUID/UUIDShort` | UUID生成 | + +**设计改进点：** + +| 改进 | 说明 | +|------|------| +| 性能优化 | 非安全随机用 `RandInt/RandInt64`（math/rand，sync.Pool 复用源）；安全场景用 `RandStringSecure/RandDigitSecure/RandIntSecure`（crypto/rand + big.Int 拒绝采样无偏） | +| 类型安全 | 移除使用反射的函数，保持类型安全 | +| 式调用 | `HTTPClient` 和 `URLBuilder` 支持链式调用 | +| 零依赖 | 仅依赖 `google/uuid`，其余使用标准库 | + +--- + +## 12. 实时通信 + +### 12.1 SSE 流式响应 + +```go +import "github.com/EthanCodeCraft/xlgo-core/sse" + +// AI对话场景 +func ChatHandler(c *gin.Context) { + ch := make(chan string) + go func() { + defer close(ch) + for _, chunk := range aiResponse { + ch <- chunk + } + }() + sse.StreamChunks(c, ch) +} + +// 手动写入 +writer, _ := sse.NewSSEWriter(c) +writer.WriteEvent("message", "Hello") +writer.WriteMessage("World") +writer.WriteDone() +``` + +### 12.2 WebSocket + +```go +import "github.com/EthanCodeCraft/xlgo-core/ws" + +// 简单使用 +r.GET("/ws", ws.HandleFunc(func(conn *ws.Connection, message []byte) { + conn.SendText("收到: " + string(message)) +})) + +// 广播模式 +hub := ws.NewHub() +go hub.Run() + +// 注册连接 +hub.Register(conn) + +// 广播消息 +hub.Broadcast([]byte("广播消息")) + +// 获取连接数 +count := hub.Count() +``` + +--- + +## 13. 定时任务 + +> **v1.4.0**：App 持专属调度器（实例隔离，多 App 互不污染）。**App 管理的任务用 +> `xlgo.WithCronTask(name, schedule, handler)` 注册**（蕴含启用 cron，`Init` 时注册+启动， +> `Shutdown` 时停止并等待在跑任务退出）。下方包级 `cron.AddTask`/`cron.Start`/`cron.Stop` 仍可用于 +> standalone（无 App）或 `Init` 之后；**`Init` 之前**调包级 `cron.AddTask` 会注册到 init 默认 +> 调度器、被 App swap 丢弃。`app.Scheduler()` 返回 App 调度器，供动态注册与管理 +> （`AddTask`/`RemoveTask`/`RunTask`/`ListTasks`）。 +> +> ```go +> app := xlgo.New(xlgo.WithConfig(cfg), +> xlgo.WithCronTask("cleanup", cron.Every(5*time.Minute), func(ctx context.Context) error { +> return cleanupOldData() +> }), +> xlgo.WithCronTask("daily_report", cron.Daily(2, 0), generateReport), +> ) +> // 动态注册（Init 后）：app.Scheduler().AddTask(...) +> if err := app.Run(); err != nil { /* ... */ } +> ``` + +### 13.1 添加任务 + +```go +import "github.com/EthanCodeCraft/xlgo-core/cron" + +// 间隔执行（每5分钟） +cron.AddTask("cleanup", cron.Every(5*time.Minute), func(ctx context.Context) error { + return cleanupOldData() +}) + +// 每天固定时间（凌晨2点） +cron.AddTask("report", cron.Daily(2, 0), generateReport) + +// 每周执行（周一上午10点） +cron.AddTask("weekly", cron.Weekly(time.Monday, 10, 0), weeklyTask) + +// 简化 Cron（分钟+小时） +cron.AddTask("noon", cron.Cron("0", "12"), doSomething) // 每天12:00 + +// 完整 Cron 表达式（5字段） +cron.AddTask("complex", cron.ParseCron("*/15 * * * *"), doSomething) // 每15分钟 +cron.AddTask("monthly", cron.ParseCron("0 0 1 * *"), doSomething) // 每月1号凌晨 +cron.AddTask("workday", cron.ParseCron("0 9-17 * * 1-5"), doSomething) // 工作日9-17点 + +// ParseCron 对非法表达式 fail-fast panic；动态输入请用 ParseCronStrict 处理 error。 +// 如需旧版“非法表达式回退为每分钟”的兼容语义，请显式使用 ParseCronOrDefault。 +``` + +### 13.2 启动与停止 + +```go +// 启动调度器 +cron.Start() + +// 停止调度器 +cron.Stop() + +// 获取调度器实例进行更多操作 +scheduler := cron.GetScheduler() +scheduler.RemoveTask("cleanup") // 移除任务 +tasks := scheduler.ListTasks() // 查看任务列表 +scheduler.RunTask("report") // 立即执行任务 +scheduler.DisableTask("cleanup") // 禁用任务 +scheduler.EnableTask("cleanup") // 启用任务 +``` + +--- + +## 14. 链路追踪 + +> **v1.4.0**：`xlgo.WithTrace()` 把 trace 纳入 App 生命周期--`Init` 按 `config.Trace` 调 +> `trace.Init`、装入 `trace.Middleware`、`Shutdown` 调 `trace.Close` 刷出 span 并释放 exporter +> 后台 goroutine。下方手动 `trace.Init`/`trace.Close`/`trace.Middleware` 仍可用于 standalone +> （无 App）。**trace 不做实例隔离**--OTel `TracerProvider` 是进程级全局单例，多 App 进程共享， +> 任一 `Shutdown` 会关全局导出；多 App 不要同时开 `WithTrace`。 +> +> ```go +> app := xlgo.New(xlgo.WithConfigPath("config.yaml"), xlgo.WithTrace()) +> // config.yaml 配置 trace.enabled / trace.endpoint / trace.exporter_type / trace.sample_ratio ... +> ``` + +### 14.1 初始化 + +```go +import "github.com/EthanCodeCraft/xlgo-core/trace" + +trace.Init(trace.Config{ + Enabled: true, + ServiceName: "my-service", + Endpoint: "localhost:4318", + ExporterType: "otlp-http", + // Insecure: true, // 明文 collector（localhost:4318 等本地 collector 默认无 TLS，需显式开启） + SampleRatio: 1.0, + // Propagator: "w3c", // 可选 "w3c"(默认) / "b3" / "jaeger"(映射 W3C) +}) +defer trace.Close(ctx) +``` + +> **导出器类型**：`otlp-http` / `otlp-grpc` / `stdout`（写标准输出，便于调试）。未知类型 `Init` 返错。 +> **Insecure**：默认 `false`（TLS）；对无 TLS 的本地 collector（如 `localhost:4318`）需显式置 `true`，否则握手失败。 +> **传播器**：`w3c`（默认，W3C TraceContext + Baggage）/ `b3`（同时支持单头与多头，兼容旧 B3 客户端）/ `jaeger`（映射为 W3C TraceContext——现代 Jaeger agent 透传 W3C；纯 Jaeger thrift 头协议请用 `b3`）。未知类型 `Init` 返错。 +> **未 Init 也安全**：未调用 `Init` 或 `Init(Enabled:false)` 时为 Noop tracer，`Middleware`/`StartSpan` 等不 panic。 + +### 14.2 使用中间件 + +```go +// 自动追踪所有请求 +r.Use(trace.Middleware("my-service")) + +// 响应头自动添加 X-Trace-ID +``` + +### 14.3 业务追踪 + +```go +// 创建子Span +ctx, span := trace.StartSpan(c, "db_query") +defer span.End() + +// 记录错误 +trace.RecordError(c, err) + +// 添加属性 +trace.SetAttribute(c, "user_id", 123) + +// 获取TraceID +traceID := trace.GetTraceID(c) +``` + +--- + +## 15. 压缩解压 + +### 15.1 Gzip + +```go +import "github.com/EthanCodeCraft/xlgo-core/compress" + +// 压缩数据 +compressed, err := compress.GzipCompress(data) + +// 解压数据 +data, err := compress.GzipDecompress(compressed) + +// 压缩文件 +err := compress.GzipCompressFile("src.txt", "dst.gz") + +// 解压文件 +err := compress.GzipDecompressFile("src.gz", "dst.txt") +``` + +### 15.2 Zip + +```go +// 打包文件/目录 +err := compress.Zip("archive.zip", []string{"file1.txt", "dir/"}) + +// 解压到目录 +err := compress.Unzip("archive.zip", "./output") +``` + +--- + +## 16. 测试工具 + +### 16.1 API 测试 + +```go +import "github.com/EthanCodeCraft/xlgo-core/test" + +func TestUserAPI(t *testing.T) { + router := test.SetupRouter() + + // POST请求 + resp := test.POST(router, "/api/users"). + WithJSON(map[string]any{"name": "test"}). + Execute() + resp.AssertOK(t) + resp.AssertJSONContains(t, "code", float64(1)) + + // GET请求 + resp = test.GET(router, "/api/users/1").Execute() + resp.AssertOK(t) + resp.AssertJSONContains(t, "data.id", float64(1)) +} +``` + +--- + +## 17. CLI 脚手架 + +### 17.1 创建项目 + +```bash +# 创建新项目 +xlgo new myproject + +# 指定模块名 +xlgo new myproject --module github.com/company/myproject +``` + +### 17.2 生成代码 + +```bash +# 生成Handler +xlgo make handler user + +# 生成Model +xlgo make model user + +# 生成Repository +xlgo make repository user + +# 生成Service +xlgo make service user +``` + +--- + +## 18. 最佳实践 + +### 18.1 项目分层 + +``` +handler/ → 接收请求、参数验证、调用Service +service/ → 业务逻辑、事务管理 +repository/ → 数据访问、CRUD操作 +model/ → 数据模型定义 +``` + +### 18.2 错误处理 + +```go +func GetUser(c *gin.Context) { + id := handler.PathInt64(c, "id", 0) + if id == 0 { + // 参数错误码由业务侧定义；这里直接返回通用失败 + 自定义消息 + response.Fail(c, "参数错误") + return + } + + user, err := userService.GetByID(id) + if err != nil { + trace.RecordError(c, err) + response.FailWithError(c, response.ErrUserNotFound) + return + } + + response.Success(c, user) +} +``` + +### 18.3 多站点配置 + +```yaml +# A站点 +app: + site_name: "site_a" + +# B站点 +app: + site_name: "site_b" +``` + +缓存自动隔离： + +- site_a: `cache:site_a:user:1` +- site_b: `cache:site_b:user:1` + +### 18.4 环境区分 + +```go +if cfg.IsProduction() { + gin.SetMode(gin.ReleaseMode) + // 生产环境收紧 console 输出（仅保留 Warn / Error） + // 业务事件请使用 logger 包记录 + console.SetLevel(console.LevelWarn) +} +``` + +--- + +## 附录：完整示例 + +### 用户登录接口 + +```go +package handler + +import ( + "github.com/EthanCodeCraft/xlgo-core/cache" + "github.com/EthanCodeCraft/xlgo-core/response" + "github.com/EthanCodeCraft/xlgo-core/validation" + "github.com/gin-gonic/gin" +) + +type LoginRequest struct { + Username string `json:"username" label:"用户名" validate:"required" msg_required:"用户名不能为空"` + Password string `json:"password" label:"密码" validate:"required,password" msg_required:"密码不能为空"` +} + +func Login(c *gin.Context) { + var req LoginRequest + if !validation.ShouldBindAndValidate(c, &req) { + return + } + + // 查询用户 + user, err := userService.GetByUsername(req.Username) + if err != nil { + response.FailWithError(c, response.ErrUserNotFound) + return + } + + // 验证密码 + if !validation.CheckPassword(user.Password, req.Password) { + response.FailWithError(c, response.ErrPasswordWrong) + return + } + + // 生成Token + token, err := jwt.GenerateToken(user.ID, user.Username, "admin", "admin") + if err != nil { + response.FailWithError(c, response.ErrServerError) + return + } + + // 缓存用户信息 + cache.GetCache().Set(c.Request.Context(), + cache.KSession(token), + user, + cfg.JWT.Expire) + + response.Success(c, gin.H{ + "token": token, + "user_id": user.ID, + "username": user.Username, + }) +} +``` + +--- + +_文档版本: v1.2.0_ +_最后更新: 2026-07-04_ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f4beed7 --- /dev/null +++ b/LICENSE @@ -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. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..fe35d76 --- /dev/null +++ b/Makefile @@ -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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..5754e74 --- /dev/null +++ b/README.md @@ -0,0 +1,1117 @@ +# xlgo Web Framework + +

+ Go Version + Gin Version + License +

+ +> 基于 Go + Gin 的后端开发框架。**组件全部 Manager 化**——既能像脚本一样用包级函数简单调用，又能像正经框架一样注入实例、跑多套、塞 mock 做单测。 + +## 为什么是 xlgo + +多数 Gin 脚手架把数据库、Redis、缓存、JWT、日志做成**包级全局单例**：写小项目顺手，但一旦要做单元测试、同进程跑多套实例、或替换实现，就动弹不得。xlgo 把这些组件全部抽象成 `XxxManager`，同时保留包级便捷函数做 facade——**简单用法零成本，复杂场景不封顶**： + +```go +// 简单用法：包级函数，跟单例脚手架一样直接 +database.InitDB(cfg) +db := database.GetDB() + +// 同一份代码，也能注入实例 / 跑多套 / 塞 mock +myDB := database.NewManager(cfg) +myDB.Open(ctx) // 独立实例，不受全局影响 +database.SetDefaultManager(myDB) // 提升为全局默认，并关闭旧默认 manager +cache.SetDefaultCacheManager(&cache.CacheManager{}) // 测试注入自定义 CacheManager +``` + +### 区别于一般 Gin 脚手架的几点 + +- **组件可注入** — database / redis / cache / jwt / storage / logger 均为 `Manager` + 全局 facade 双轨，支持多实例与 mock 注入，而非写死的包级单例 +- **生产就绪内置** — `/livez` `/readyz`、Prometheus `/metrics`、主库探活自愈、请求级超时、优雅关闭（等待 in-flight goroutine）开箱即用，不用自己搭 +- **框架内零 Fatal** — 错误一律返回由调用方处理，框架代码不 `panic` 杀进程 +- **默认轻量、按需启用** — `New()` 什么都不开，`NewFullStack()` 一键全开，中间任意组合；`Without*` 精细排除 +- **可插拔数据库方言** — GORM 方言注册表，内置 MySQL / PostgreSQL，可扩展 SQLite / ClickHouse 等 + +### 30 秒上手 + +```go +package main + +import ( + xlgo "github.com/EthanCodeCraft/xlgo-core" + "github.com/EthanCodeCraft/xlgo-core/response" + "github.com/gin-gonic/gin" +) + +func main() { + app := xlgo.New( + xlgo.WithConfigPath("./config.yaml"), + xlgo.WithLogger(), + xlgo.WithHealthRoutes(), + ) + app.GetRouter().GET("/", func(c *gin.Context) { + response.Success(c, gin.H{"hello": "xlgo"}) + }) + _ = app.Run() +} +``` + +## 框架特性 + +**架构与可注入性** +- **组件 Manager 化** - database / redis / cache / jwt / storage / logger 均为 `XxxManager` + 全局 facade 双轨，支持多实例与测试注入 mock +- **可插拔数据库方言** - GORM 方言注册表，内置 MySQL / PostgreSQL，可注册 SQLite / ClickHouse 等任意驱动 +- **读写分离** - 主库 + 多副本，`ReplicaPicker` 策略可插拔（轮询 / 随机 / 自定义），context 路由强制主库 +- **Lifecycle Hooks** - `OnInit / OnStart / OnReady / OnStop` 生命周期钩子，可插拔启动/关闭逻辑 + +**生产就绪** +- **健康探针** - `/livez`（存活）+ `/readyz`（就绪）+ `/health`（兼容），K8s probe 友好 +- **Prometheus 指标** - `/metrics` 端点 + 请求计数 / 耗时 / 在飞数采集中间件 +- **依赖健康自愈** - 主库后台探活，连续失败标记不健康联动 503；从库失败临时剔除、恢复自动纳入 +- **请求级超时** - `middleware.Timeout` 级联取消下游 GORM/Redis +- **优雅关闭** - `App.Go` 管理后台 goroutine，Shutdown 时 cancel + 等待退出（带超时） +- **配置校验** - 启动期 `Validate` 拦截非法配置（端口/密钥/必填字段），错误前置 + +**基础功能** +- **配置管理** - YAML + 环境变量覆盖 + 热更新，`time.Duration` 字符串解析（`"24h"`） +- **缓存** - Redis 缓存，键前缀、TTL、SCAN 优化、分布式锁 +- **认证** - JWT 认证，Token 黑名单、刷新机制，HMAC 算法可选 +- **日志** - 分级日志（通用 / API / DB 三分流），lumberjack 轮转 +- **中间件** - CORS、限流（内存 + Redis 版）、请求日志、认证、CSRF、RequestID、Recover +- **文件存储** - 本地 + 阿里云 OSS +- **实时通信** - SSE 流式响应 + WebSocket +- **定时任务** - 内置调度器（interval / daily / weekly / cron） +- **验证器** - 请求参数验证，自定义错误消息 +- **响应模式** - `ModeBusiness`（业务码，默认）/ `ModeREST`（按错误码映射 HTTP status）一键切换 +- **CLI 工具** - 脚手架 + 代码生成（handler/repository/model/service） + +## 快速开始 + +> **环境要求**：xlgo 基于 Go 1.25+ 构建，请确保本地已安装 Go 1.25 或更高版本。 + +### 1. 安装 + +```bash +# 安装脚手架工具 +go install github.com/EthanCodeCraft/xlgo-core/cmd/xlgo@latest + +# 创建新项目 +xlgo new myproject + +# 进入目录 +cd myproject + +# 安装依赖 +go mod tidy +``` + +### 2. 创建配置文件 config.yaml + +```yaml +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 # business(默认,全200+业务码) 或 rest(按错误码映射HTTP status) + +database: + driver: mysql # mysql（默认）或 postgres + host: localhost + port: 3306 + user: root + password: your_password + name: your_database + max_idle_conns: 10 + max_open_conns: 100 + # dsn: "自定义连接字符串，设置后优先于上面的字段" + +redis: + host: localhost + port: 6379 + password: "" + db: 0 + +jwt: + secret: your_jwt_secret_key_at_least_32_bytes # ≥32 字节，否则启动期被 Validate 拦截 + 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 +``` + +### 3. 运行项目 + +```bash +go run main.go +``` + +访问 http://localhost:8080/health 检查服务状态。 + +> v1.0.2 起，`xlgo.New()` 默认是轻量应用，不会自动初始化 MySQL、Redis、Storage 或 Swagger。需要完整基础设施时请显式使用 `WithMySQL()`、`WithRedis()`、`WithStorage()`、`WithSwaggerRoutes()`，或直接使用 `xlgo.NewFullStack()`。 +> +> `Without*` 系列 Option（如 `WithoutSwaggerRoutes`）主要用于 `NewFullStack` / `RunFullStack` 启用全部组件后排除个别项，例如 `xlgo.NewFullStack(xlgo.WithoutSwaggerRoutes())` 全组件但关闭 Swagger。`xlgo.New()` 本身已全关，无需再 `Without`。 + +### 4. 模块路径与包名 + +xlgo 的 **模块路径** 是 `github.com/EthanCodeCraft/xlgo-core`，**包名** 是 `xlgo`（二者不同是 Go 惯例，如 `github.com/gin-gonic/gin` → 包名 `gin`）。import 时用别名 `xlgo` 即可： + +```go +package main + +import ( + xlgo "github.com/EthanCodeCraft/xlgo-core" + "github.com/EthanCodeCraft/xlgo-core/middleware" + "github.com/EthanCodeCraft/xlgo-core/response" + "github.com/gin-gonic/gin" +) + +func main() { + app := xlgo.New( + xlgo.WithConfigPath("./config.yaml"), + xlgo.WithLogger(), + xlgo.WithHealthRoutes(), + ) + // 注册一个示例路由 + app.GetRouter().GET("/", func(c *gin.Context) { + response.Success(c, gin.H{"message": "Hello xlgo!"}) + }) + // 启用 JWT 认证示例路由（需配合 WithMySQL/WithRedis 生成 token） + _ = middleware.RequireUserTypes("admin") + + _ = app.Run() +} +``` + +> 子包（`config` / `database` / `logger` / `middleware` ...）的包名与目录名一致，无需别名。 + +--- + +## 核心功能 + +### 配置管理 + +```go +// 加载配置 +cfg, err := config.Load("./config.yaml") + +// 获取配置 +cfg := config.Get() +serverPort := cfg.Server.Port + +// 配置热更新 +cfg, err := config.LoadWithWatch("./config.yaml", func(newCfg *config.Config) { + log.Println("配置已更新") +}) + +// 注册配置变更回调 +config.RegisterCallback(func(cfg *config.Config) { + // 处理配置变更 +}) + +// 手动重新加载 +config.Reload() +``` + +### 数据库操作 + +xlgo 基于 GORM，主库与从库的驱动由配置 `database.driver` 决定，内置支持 `mysql`（默认）与 `postgres`，也可通过 `database.dsn` 使用任意自定义连接字符串。v1.0.2 起 GORM 方言通过 **可插拔注册表** 管理，应用可自行接入 SQLite、SQL Server、ClickHouse 等任意 GORM 驱动而无需修改框架。 + +```go +// 初始化数据库（驱动由配置决定） +database.InitDB(cfg) +defer database.Close() + +// 主从读写分离（从库 DSN 需与主库驱动匹配） +database.InitDBWithReplicas(cfg, []string{ + "root:pass@tcp(slave1:3306)/db", + "root:pass@tcp(slave2:3306)/db", +}) + +// 读操作自动路由到从库 +var users []model.User +database.GetReadDB().Find(&users) + +// 强制使用主库 +ctx := database.UseMaster(context.Background()) +database.GetDBFromContext(ctx).Find(&users) + +// 事务 +database.Transaction(func(tx *gorm.DB) error { + return tx.Create(&user).Error +}) + +// 健康检查 +status := database.HealthCheck() +``` + +v1.0.2 起数据库状态由实例化的 `database.Manager` 管理，全局函数（`GetDB`、`GetReadDB`、`CloseAll` 等）作为默认 `DefaultManager` 的 facade 保留。可通过 `database.NewManager(cfg)` 创建独立管理器，并通过 `ReplicaPicker` 自定义从库选择策略： + +```go +// 独立管理器（不影响全局 DefaultManager） +mgr := database.NewManager(cfg) +if err := mgr.Open(context.Background()); err != nil { + return err +} +defer mgr.Close() + +// 从库选择策略：轮询（默认随机） +database.SetReplicaPicker(&database.RoundRobinPicker{}) +``` + +`database.SetDefaultManager(m)` 表示把新 manager 接管为全局默认，并关闭被替换的旧 manager，避免连接池泄漏。需要失败回滚或延迟释放旧资源的初始化流程，请使用 `database.SwapDefaultManager(m)` 并自行决定何时关闭返回的旧 manager。 + +#### 注册自定义 GORM 方言 + +通过 `database.RegisterDialect` 一次注册即可让 `database.driver: ` 生效，DSN 构建器会同步登记到 `config` 包，因此 `cfg.Database.DSN()` 也会识别新驱动： + +```go +import ( + "github.com/EthanCodeCraft/xlgo-core/config" + "github.com/EthanCodeCraft/xlgo-core/database" + "gorm.io/driver/sqlite" + "gorm.io/gorm" +) + +func init() { + database.RegisterDialect(database.DialectSpec{ + Name: "sqlite", + Aliases: []string{"sqlite3"}, + Dialector: func(dsn string) gorm.Dialector { return sqlite.Open(dsn) }, + DSN: func(c *config.DatabaseConfig) string { return c.Name }, // Name 当作文件路径 + }) +} +``` + +诊断接口：`database.RegisteredDialects()` 返回当前已注册的驱动名（含别名），`database.LookupDialect(name)` 用于检查某个驱动是否已就绪。未注册的驱动会回退到 MySQL 以保持向后兼容。 + +### Repository 泛型 CRUD + +```go +// 创建仓库 +userRepo := repository.NewBaseRepo[model.User](database.GetDB()) + +// 基础 CRUD +user, err := userRepo.FindByID(ctx, 1) +err := userRepo.Create(ctx, &user) +err := userRepo.Update(ctx, &user) +err := userRepo.Delete(ctx, 1) + +// 分页查询 +result, err := userRepo.FindPage(ctx, 1, 20) +// result.Items, result.Total, result.Page, result.PageSize + +// 条件查询 +users, err := userRepo.FindWhere(ctx, "status = ?", 1) + +// 链式查询 +users, err := userRepo.NewQueryBuilder(). + Where("status = ?", 1). + Order("created_at DESC"). + Limit(10). + Find(ctx) + +// 批量操作 +err := userRepo.CreateBatch(ctx, users) +err := userRepo.DeleteBatch(ctx, []uint{1, 2, 3}) + +// 事务支持 +err := userRepo.WithTransaction(ctx, func(txRepo *repository.BaseRepo[model.User]) error { + return txRepo.Create(ctx, &user) +}) +``` + +### Redis 缓存 + +> **v1.4.0**：App 经 `WithRedis()` 启用时自动用 App 的 Redis 客户端初始化缓存（多 App 隔离，不串越）。下方 `cache.Init()` 用于 standalone。 + +```go +// 初始化缓存 +cache.Init() + +// 使用缓存 +ctx := context.Background() +cacheService := cache.GetCache() + +// 设置缓存 +cacheService.Set(ctx, "user:1", user, 10*time.Minute) + +// 获取缓存（命中返回 true，未命中返回 false,nil，后端错误返回 err） +var user User +if hit, err := cacheService.Get(ctx, "user:1", &user); err != nil { + return err +} else if hit { + // 缓存命中 +} +if exists, err := cacheService.Exists(ctx, "user:1"); err != nil { + return err +} else if exists { + // key 存在 +} + +// 删除缓存 +cacheService.Delete(ctx, "user:1") + +// 按模式删除（使用 SCAN 优化） +cacheService.DeleteByPattern(ctx, "user:*") +``` + +### JWT 认证 + +```go +// 生成 Token（自动包含 JTI） +token, err := jwt.GenerateToken(userID, username, "admin", "admin") + +// 解析 Token +// ParseToken 默认 fail-closed：黑名单后端不可检查时拒绝 Token（需 Redis） +claims, err := jwt.ParseToken(tokenString) + +// 需显式 fail-open（仅无 Redis 或低安全场景）用： +claims, err = jwt.ParseTokenWithBlacklistPolicy(tokenString, jwt.BlacklistFailOpen) + +// 使 Token 失效（使用 JTI，高效） +jwt.InvalidateToken(tokenString) + +// 获取 Token 的 JTI +jti, err := jwt.GetJTI(tokenString) +``` + +**JWT 黑名单优化**：使用 JTI（JWT ID）替代完整 Token 存储，大幅节省 Redis 内存。 + +### 分布式锁 + +```go +// 安全加锁（返回 LockToken） +token, err := cache.NewLock(ctx, cache.KLock("order:123"), 30*time.Second) +if token != nil { + defer cache.Unlock(ctx, token) // 只有持有者能释放 + // 执行业务逻辑 +} + +// 续期锁（长任务场景） +cache.ExtendLock(ctx, token, 30*time.Second) + +// 自动续期执行 +err := cache.WithLockAutoExtend(ctx, key, 30*time.Second, 10*time.Second, func(ctx context.Context) error { + // 长任务自动续期 + return nil +}) +``` + +**分布式锁安全特性**：使用 Lua 脚本 + UUID Token，只有锁的持有者才能释放。 + +### Redis 分布式限流 + +> **v1.4.0**：多 App 走各自 Redis 用 `middleware.NewRedisRateLimiter(..., middleware.WithRedisClient(app.RedisClient()))`。 + +```go +// 内存限流（单实例） +r.Use(middleware.CustomRateLimit(100, time.Minute)) + +// Redis 分布式限流（多实例共享） +r.Use(middleware.RedisRateLimit("api_limit", 100)) +r.Use(middleware.LoginRedisRateLimit()) // 登录限流 +r.Use(middleware.APIRedisRateLimit()) // API 限流 +``` + +### 请求验证 + +```go +type LoginRequest struct { + Username string `json:"username" label:"用户名" validate:"required,username" msg_required:"请输入用户名"` + Password string `json:"password" label:"密码" validate:"required,password" error:"密码格式不正确"` + Phone string `json:"phone" label:"手机号" validate:"omitempty,phone" msg_phone:"请输入正确的手机号"` +} + +// 绑定并验证 +errors, ok := validation.ShouldBindAndValidate(c, &req) +if !ok { + response.Fail(c, errors.FirstMessage()) + return +} +``` + +**验证器支持的自定义标签**： + +- `label:"中文名"` - 字段显示名称 +- `error:"通用错误消息"` - 所有验证失败时显示 +- `msg_required:"必填项"` - 特定规则的错误消息 +- `msg_min:"最少5个字符"` - 针对 min 规则的错误消息 + +### 统一错误码 + +```go +// 使用预定义错误 +response.FailWithError(c, response.ErrUserNotFound) + +// 带详细信息 +response.FailWithDetail(c, response.ErrPasswordWrong, "连续错误3次将锁定账户") + +// 自定义错误 +err := response.NewError(10001, "自定义错误") +``` + +**预定义错误码**： + +- 用户模块：`ErrUserNotFound`, `ErrPasswordWrong`, `ErrTokenExpired` 等 +- 文件模块：`ErrFileTooLarge`, `ErrFileTypeInvalid` 等 +- 数据模块：`ErrDataNotFound`, `ErrDataConflict` 等 + +### 文件上传 + +```go +// 上传文件 +file, err := c.FormFile("file") +path, err := storage.Upload(file, "images") +url := storage.GetURL(path) + +// 上传字节数组 +path, err := storage.UploadFromBytes(data, "filename.jpg", "images") + +// 删除文件 +err := storage.Delete(path) + +// 获取文件内容 +data, err := storage.Get(path) + +// 检查文件是否存在（不存在 false,nil；后端错误返回 err） +ok, err := storage.Exists(path) +if err != nil { + return err +} +``` + +### SSE 流式响应 + +```go +// AI 对话场景 +func ChatHandler(c *gin.Context) { + ch := make(chan string) + go func() { + defer close(ch) + for _, chunk := range aiResponse { + ch <- chunk + } + }() + sse.StreamChunks(c, ch) +} + +// 带消息 ID 的流式响应 +sse.StreamWithID(c, "msg_123", ch) +``` + +### WebSocket + +```go +// 简单使用 +r.GET("/ws", ws.HandleFunc(func(conn *ws.Connection, message []byte) { + conn.SendText("收到: " + string(message)) +})) + +// 广播模式 +hub := ws.NewHub() +go hub.Run() +hub.Broadcast([]byte("广播消息")) +``` + +### 定时任务 + +> **v1.4.0**：App 持专属调度器（实例隔离）。**App 管理的任务用 `xlgo.WithCronTask(name, schedule, handler)` +> 注册**（蕴含启用 cron，`Init` 时注册+启动，`Shutdown` 时停止）。下方包级 `cron.AddTask`/`cron.Start` +> 仅用于 standalone（无 App）或 `Init` 之后；**`Init` 之前**调包级 `cron.AddTask` 会注册到 init 默认 +> 调度器、被 App swap 丢弃。`app.Scheduler()` 供动态注册与管理。 + +```go +// 每隔 5 分钟执行 +cron.AddTask("cleanup", cron.Every(5*time.Minute), func(ctx context.Context) error { + return cleanupOldData() +}) + +// 每天凌晨 2 点执行 +cron.AddTask("daily_report", cron.Daily(2, 0), generateReport) + +// 每周一上午 9 点执行 +cron.AddTask("weekly", cron.Weekly(time.Monday, 9, 0), weeklyTask) + +// 完整 Cron 表达式 +cron.AddTask("every15min", cron.ParseCron("*/15 * * * *"), doSomething) +cron.AddTask("monthly", cron.ParseCron("0 0 1 * *"), doSomething) // 每月1号 + +// ParseCron 对非法表达式 fail-fast panic；动态输入请用 ParseCronStrict 处理 error。 +// 如需旧版“非法表达式回退为每分钟”的兼容语义，请显式使用 ParseCronOrDefault。 + +// 启动调度器 +cron.Start() +defer cron.Stop() +``` + +### CSRF 防护 + +```go +// 基本使用 +r.Use(middleware.CSRF()) + +// 获取 Token（返回给前端） +token := middleware.GetCSRFToken(c) + +// 跳过指定路径 +r.Use(middleware.CSRFWithSkip([]string{"/api/webhook"})) + +// API 模式（双重提交 Cookie） +r.Use(middleware.DoubleSubmitCookie()) +``` + +### 密码加密 + +```go +// 加密密码 +hash, err := validation.HashPassword("password123") + +// 验证密码 +if validation.CheckPassword(hash, "password123") { + // 密码正确 +} + +// 带成本升级的验证 +match, needUpgrade, newHash, err := validation.CheckPasswordAndUpgrade(hash, password, 12) +``` + +--- + +## 中间件 + +### 认证中间件 + +```go +// JWT 认证（必须登录） +r.Use(middleware.AuthRequired()) + +// 自定义用户类型权限 +r.Use(middleware.RequireUserTypes("tenant_admin", "platform_admin")) + +// 自定义角色权限 +r.Use(middleware.RequireRoles("owner", "manager")) + +// 自定义复杂权限判断 +r.Use(middleware.RequireAuth(func(user middleware.AuthUser, c *gin.Context) bool { + return user.UserType == "merchant" && user.Role == "owner" +})) + +// 默认快捷方法（super_admin/admin/staff 只是框架默认常量） +r.Use(middleware.AdminRequired()) +r.Use(middleware.SuperAdminRequired()) +r.Use(middleware.StaffRequired()) +r.Use(middleware.AnyUserRequired()) + +// 获取用户信息 +user, ok := middleware.GetAuthUser(c) +userID := middleware.GetUserID(c) +username := middleware.GetUsername(c) +role := middleware.GetRole(c) +userType := middleware.GetUserType(c) +``` + +### 限流中间件 + +> **v1.4.0**：App `Shutdown` 自动 `registry.Stop()`（不再调全局 `StopRateLimiters`，避免误停其他 App）。多 App per-App 计数隔离用 `app.RateLimitRegistry().LoginRateLimit()` 等 App-bound 中间件。 + +```go +// 登录限流（每分钟 10 次） +r.POST("/login", middleware.LoginRateLimit(), func(c *gin.Context) { + response.Success(c, gin.H{"token": "..."}) +}) + +// 上传限流（每分钟 20 次） +r.POST("/upload", middleware.UploadRateLimit(), func(c *gin.Context) { + response.Success(c, gin.H{"file": "..."}) +}) + +// 自定义限流 +r.Use(middleware.CustomRateLimit(50, time.Minute)) + +// 停止限流器（应用关闭时） +defer middleware.StopRateLimiters() +``` + +--- + +## 响应格式 + +框架使用统一的响应格式： + +```json +{ + "code": 1, + "msg": "操作成功", + "data": {}, + "request_id": "abc123" +} +``` + +```go +// 成功响应 +response.Success(c, data) +response.SuccessWithMsg(c, "自定义消息", data) + +// 失败响应 +response.Fail(c, "错误消息") + +// 分页响应 +response.Page(c, list, total, page, pageSize) + +// 错误响应 +response.Unauthorized(c, "请先登录") +response.NotFound(c, "资源不存在") +response.ServerError(c, "服务器错误") +response.RateLimit(c) + +// 显式指定 HTTP status（不受 Mode 影响） +response.Custom(c, http.StatusBadRequest, response.CodeFail, "参数错误", nil) +``` + +**响应模式**（v1.1.0）：默认 `ModeBusiness`，所有响应 HTTP 200 + 业务码（兼容存量）。切换 `ModeREST` 后，失败响应按错误码映射对应 HTTP status（401/404/429/500...），body 仍带业务码，便于 APM / Prometheus / 网关按 status 区分异常： + +```go +response.SetMode(response.ModeREST) // 代码切换 +// 或在 config.yaml 配置：server.response_mode: rest +``` + +--- + +## CLI 工具 + +```bash +# 创建新项目 +xlgo new myproject + +# 创建新项目并指定模块路径 +xlgo new myproject --module github.com/myorg/myproject + +# 生成代码 +xlgo make handler user # 创建 handler/user.go +xlgo make repository user # 创建 repository/user_repository.go +xlgo make model user # 创建 model/user.go +xlgo make service user # 创建 service/user_service.go + +# 显示版本 +xlgo version +``` + +--- + +## 测试 + +框架提供完整的测试工具包： + +```go +func TestUserAPI(t *testing.T) { + router := test.SetupRouter() + + // 创建请求 + resp := test.POST(router, "/api/v1/users"). + WithJSON(map[string]any{"name": "test"}). + WithToken("xxx"). + Execute() + + // 断言 + resp.AssertOK(t) + + // 解析响应 + var result map[string]any + resp.ParseJSON(&result) +} +``` + +--- + +## 目录结构 + +``` +xlgo/ +├── app.go # 应用入口 +├── cache/ +│ ├── cache.go # 缓存服务 +│ ├── keybuilder.go # 键名前缀管理 +│ └── lock.go # 分布式锁 +├── cmd/ +│ └── xlgo/ # CLI 脚手架 +├── compress/ +│ └── compress.go # Gzip/Zip 压缩解压 +├── config/ +│ ├── config.go # 配置管理（支持热更新、time.Duration 解析） +│ └── validate.go # 配置校验（启动期拦截非法配置） +├── console/ +│ └── console.go # 彩色控制台输出 +├── cron/ +│ └── cron.go # 定时任务调度 +├── database/ +│ ├── manager.go # 数据库管理器（主从、Picker、探活自愈、Init/Close/HealthCheck） +│ ├── dialect.go # GORM 方言注册表（mysql / postgres，可扩展） +│ └── redis.go # Redis 连接管理器（RedisManager） +├── handler/ +│ └── handler.go # 基础处理器（类型安全参数获取） +├── jwt/ +│ └── jwt.go # JWT 工具 +├── logger/ +│ ├── logger.go # 日志实现 +│ └── field.go # 日志字段工具 +├── middleware/ +│ ├── auth.go # JWT 认证中间件 +│ ├── cors.go # CORS 跨域中间件 +│ ├── csrf.go # CSRF 防护中间件 +│ ├── logger.go # 请求日志中间件 +│ ├── metrics.go # Prometheus 指标中间件 +│ ├── ratelimit.go # 限流中间件 +│ ├── requestid.go # 请求ID中间件 +│ ├── recover.go # Panic恢复中间件 +│ └── timeout.go # 请求级超时中间件 +├── model/ +│ └── base.go # 基础模型 +├── repository/ +│ └── repository.go # 基础仓库（泛型CRUD） +├── response/ +│ ├── response.go # 统一响应格式 +│ ├── mode.go # 响应模式开关（business / REST） +│ └── error.go # 统一错误码 +├── router/ +│ ├── router.go # 路由注册中心（模块化/版本化、livez/readyz/health） +│ └── metrics.go # Prometheus /metrics 端点 +├── sse/ +│ └── sse.go # SSE 流式响应 +├── storage/ +│ └── storage.go # 文件存储（本地+OSS） +├── test/ +│ └── test.go # 测试工具包 +├── trace/ +│ └── trace.go # 链路追踪 +├── utils/ +│ ├── random.go # 随机数生成 +│ ├── strings.go # 字符串处理 +│ ├── datetime.go # 时间日期 +│ ├── convert.go # 类型转换 +│ ├── file.go # 文件操作 +│ ├── url.go # URL处理 +│ ├── validator.go # 格式验证 +│ ├── crypto.go # 加密编码 +│ ├── http.go # HTTP客户端 +│ └── uuid.go # UUID生成 +├── validation/ +│ ├── validator.go # 请求验证器 +│ ├── password.go # 密码强度验证 +│ └── hash.go # 密码加密 +└── ws/ + └── ws.go # WebSocket 支持 +``` + +--- + +## 部署指南 + +### Docker 部署 + +```dockerfile +FROM golang:1.25-alpine AS builder + +WORKDIR /app +COPY . . +RUN CGO_ENABLED=0 go build -o server . + +FROM alpine:latest +RUN apk --no-cache add ca-certificates tzdata +WORKDIR /app +COPY --from=builder /app/server . +COPY --from=builder /app/config.yaml . +RUN mkdir -p /app/public /app/logs +EXPOSE 8080 +CMD ["./server", "-config", "./config.yaml"] +``` + +```bash +docker build -t xlgo-app:latest . +docker run -d -p 8080:8080 xlgo-app:latest +``` + +--- + +## 更新日志 + +> 完整变更历史见 [CHANGELOG.md](./CHANGELOG.md)。 + +### v1.4.0 (2026-07-12) + +> **instance+facade 一致性收尾**：cron/storage/cache/ratelimit 实例化（App 持 per-App 实例 + `SwapDefault*` + 包级 facade 代理，照 `database.Manager`/`jwt.Manager` 模式），消除单进程多 App 互相污染；trace 纳入 App 生命周期（`WithTrace`）；删除 `WithoutWire` 空函数。`go vet` + `go build` + `go test -race ./...` 全绿。完整变更见 [CHANGELOG.md](./CHANGELOG.md)。 + +主要破坏性变更（升级前必读）： + +- **`xlgo.WithoutWire()` 删除**：v1.1.0 wire 包删除后遗留的空 no-op，直接删除调用即可（无行为变化）。 +- **`cron.AddTask` 在 `App.Init` 之前注册失效**：App 持专属调度器，pre-Init 包级 `cron.AddTask` 注册到 init 默认调度器、被 App swap 丢弃。改用 `xlgo.WithCronTask(name, schedule, handler)`（或 Init 后 `app.Scheduler().AddTask`）。 +- **`middleware.StopRateLimiters` 语义收窄**：仅停默认 Registry；App `Shutdown` 调 `app` 自己的 `registry.Stop()`，不再误停其他 App 限流器。 +- **`commitReplacedResources` 不再关闭 `previousDB`/`previousRedis`/`loggerSnapshot`**：多 App 下 previous 可能是另一 App 的活跃资源（致 `redis: client is closed` / logger writer 误杀）。单 App 无影响（init 默认无资源）。 +- **cache/ratelimit redis 注入**（jwt 模型）：`cache.NewRedisCacheWithRedis`/`CacheManager.InitWithRedis`；`middleware.WithRedisClient`。 + +新增：`WithTrace`/`WithCronTask`；`app.Scheduler()`/`Cache()`/`RedisClient()`/`RateLimitRegistry()`；`cron/storage/cache/middleware` 各 `SwapDefault*`；`config.TraceConfig`；`middleware.RateLimitRegistry` + App-bound 限流中间件；`storage.StorageManager.Close()`。 + +升级：`go get github.com/EthanCodeCraft/xlgo-core@v1.4.0`（⚠️ 含破坏性变更，详见 CHANGELOG 迁移说明） + +### v1.2.0 (2026-07-04) + +> **破坏性版本**：4 轮对抗性评审（deepseek / GLM / Claude / 终审）收口的全部 CRITICAL/HIGH/MEDIUM 修复 + 主线A 包级可变全局并发治理统一。`go vet` + `go build` + `go test -race ./...` 全绿。完整变更见 [CHANGELOG.md](./CHANGELOG.md)。 + +主要破坏性变更（升级前必读）： + +- **包级可变全局一律 `atomic.Pointer`**（主线A）：`database.DefaultRedis`/`database.DefaultManager`/`storage.DefaultStorage`/`validation.Validator` 由裸指针改为 `atomic.Pointer[T]`。直接读字段调方法需改用 facade（`InitRedis`/`GetDB`/`ValidateStruct` 等）或 `.Load()`；`database.DefaultManager = x` 改 `database.SetDefaultManager(x)`。 +- **`jwt.DefaultJWT` 包级变量删除** → `GetDefaultJWT()` / `SetDefaultJWTManager()`。 +- **`repository.FindWhereOrdered`/`FindPageWhereOrdered` 签名**：`args []any` → `args ...any`，`order` 前置于 `query`。 +- **`response.Response` 的 `Data`/`RequestID` 去 `omitempty`**：两字段在所有响应中恒存在。 +- **`cache.IsLocked`/`GetLockTTL`/`ForceUnlock`** Redis 不可用改返 `ErrRedisNotReady`（锁操作正确性相关）。 +- **`config.Load()` 返回深拷贝**：新增 `(*Config).Clone()`；`Get()` 仍返只读指针（热路径零分配）。 +- **`handler.GetPage` 加 `page` 上限 10000**；`utils.EqualsIgnoreCase` 改 `strings.EqualFold`；`utils.ReadFile` 去 TOCTOU 前置检查（错误改 `errors.Is(err, os.ErrNotExist)`）。 + +升级：`go get github.com/EthanCodeCraft/xlgo-core@v1.2.0`（⚠️ 含破坏性变更，详见 CHANGELOG 迁移说明） + +### v1.1.1 (2026-06-23) + +> v1.1.0 的补丁发布：补 `ServerConfig.Host` 绑定地址、面向用户文案统一中文、修正 README 过时/错误描述（含会致启动失败的配置示例）。 + +- **ServerConfig.Host** - `server.host` 控制监听地址，空=所有接口（兼容），`127.0.0.1`=仅本机，内网 IP=绑定指定网卡 +- **文案统一中文** - recover/logger/metrics 等面向用户文案统一中文（保留协议字段名、Prometheus metric Name、MySQL 错误串匹配等英文） +- **README 修正** - 删 wire 段、修配置示例（secret≥32 字节 + expire 改 Duration）、补 v1.1.0 新文件、重写首段介绍 + +升级：`go get github.com/EthanCodeCraft/xlgo-core@v1.1.1`（无破坏性变更） + +### v1.1.0 (2026-06-23) + +> 本版本定位为 **HA & Manager 化 release**：高可用与生产就绪改进 + 组件 Manager 化。含少量破坏性变更，升级前请阅读 [CHANGELOG 升级说明](./CHANGELOG.md#升级说明)。 + +- **组件 Manager 化** - storage/cache/redis/jwt/logger 五组件新增 `XxxManager` + `SetDefaultXxxManager`，包级 facade 保留兼容，支持多实例与测试注入 +- **Lifecycle Hooks** - `WithHook(Hook{OnInit/OnStart/OnReady/OnStop})` 生命周期钩子 +- **App.Go** - 受管理的后台 goroutine，Shutdown 时 cancel + 等待退出 +- **Server 配置化** - `server` 新增 timeout/TLS/unix_socket/response_mode 等字段 +- **JWTConfig time.Duration** - `jwt.expire` 用 `"24h"`，新增 issuer/algorithm +- **Config Validate** - 启动期校验配置（端口/密钥/必填字段），错误前置 +- **response REST 模式** - `SetMode(ModeREST)` 按错误码映射 HTTP status +- **livez/readyz** - K8s 友好的存活性/就绪性探针 +- **Prometheus metrics** - `/metrics` + `middleware.Metrics()` 采集请求指标 +- **请求级 Timeout** - `middleware.Timeout(d)` 级联取消下游 +- **依赖健康自愈** - 主库探活 + replica 健康剔除，`/readyz` 联动 503 +- **RequestID 默认装入** - 每个响应/panic 日志都带 request_id + +升级：`go get github.com/EthanCodeCraft/xlgo-core@v1.1.0`（⚠️ 含破坏性变更，见升级说明） + +### v1.0.4 (2026-06-22) + +> 本版本定位为 **DX & Docs release**：开发体验与文档改进，无破坏性 API 变更。 + +- **CLI 多模板** - `xlgo new --template minimal/api/fullstack`，支持轻量 HTTP / 标准业务 / 全组件三种脚手架 +- **examples/ 目录** - 新增 `examples/minimal`（无依赖可跑）与 `examples/full`（mysql+redis+jwt+user CRUD）可运行示例 +- **模块路径文档** - 明确说明 module path `xlgo-core` 与 package name `xlgo` 的关系，补完整 import 示例（保留 `-core`，xlgo 多产品系列） +- **Without* 定位** - 文档化 `Without*` Option 主要用于 `NewFullStack` 后排除单项 +- **文档结构** - 规划文档归档到 `docs/plans/`，新增 `docs/README.md` 索引 + +升级：`go get github.com/EthanCodeCraft/xlgo-core@v1.0.4`（无破坏性变更） + +### v1.0.3 (2026-06-22) + +> 本版本定位为 **bug fix release**：收口 v1.0.2 引入的破坏性清理，并修复 4 个轻量 bug + 依赖复查。完整说明见 [CHANGELOG.md#unreleased](./CHANGELOG.md#unreleased)。 + +#### 🐛 Fixed — JWT JTI 生成忽略 `rand.Read` 错误 + +`generateJTI()` 丢弃 `crypto/rand.Read` 的 error，失败时会基于全零字节生成 JTI，导致所有 token 的 JTI 相同、黑名单机制失效。改为 `(string, error)` 并在 `GenerateToken` / `GenerateTokenWithCustomExpiry` 传播错误。 + +#### 🐛 Fixed — `QueryBuilder.Page` 统计行数被残留 Limit 截断 + +`Page()` 复制查询做 Count 时未清除残留 `Limit`/`Offset`，调用方先 `.Limit(n)` 再 `.Page(...)` 会让 Count 被包成子查询，返回 `total` 被截断为 ≤ n。countDB 改为 `.Limit(-1).Offset(-1)` 清除残留条件。 + +#### 🐛 Fixed — OSS / 本地存储文件名冲突 + +4 处上传路径仅用 `time.Now().UnixNano()` 命名，同纳秒并发上传会撞名覆盖。新增 `uniqueFilename(now, ext)`（`-<8字节crypto/rand hex>.`），4 处统一改用。 + +#### 🐛 Fixed — 数据库重试策略对不可恢复错误无效 + +`InitDB` 对认证失败（`Access denied`）、未知数据库（`Unknown database`）、非法 DSN、未注册驱动等配置类错误也退避重试 5 次，白白延迟 31 秒。新增 `isTransientDBError`，这类错误首次出现即返回；网络类错误仍正常重试。 + +#### 📦 Dependencies — `go mod tidy` + 安全补丁升级 + +- `go mod tidy` 补全 postgres 方言传递依赖（`jackc/pgx` 家族、`golang.org/x/sync`），`gorm.io/driver/postgres` 提升为直接依赖 +- 安全补丁升级（无 API 变更）：`golang.org/x/crypto` v0.49→v0.53、`golang-jwt/jwt/v5` v5.2.1→v5.3.1、`gorilla/websocket` v1.5.1→v1.5.3 +- 暂缓升级（留待 v1.0.4 / v1.1）：`gin` / `validator` / `gorm` / `aliyun-oss-go-sdk` v2→v3（major 破坏性）等跨版本升级 + +#### ⚠️ Breaking — 清理 v1.0.2 兼容别名（database 包） + +```go +// ❌ 移除 +database.InitMySQL(cfg) +database.InitMySQLWithReplicas(cfg, replicas) +(*Manager).InitMySQL / InitMySQLWithReplicas + +// ✅ 改用（v1.0.2 起就是正式 API，驱动由 cfg.Database.Driver 决定） +database.InitDB(cfg) +database.InitDBWithReplicas(cfg, replicas) +``` + +xlgo 仍是早期框架，趁此一次彻底清理 v1.0.2 临时保留的别名，避免长期累积技术债。 + +#### 🗑️ Removed — 删除死代码 `database.DBResolver` + +`database.DBResolver.BeforeQuery` 从未被注册到 GORM callback chain，属于纯死代码。文档曾暗示的"自动读写分离"实际从未生效——读写分离一直依赖业务侧显式调用 `database.UseMaster(ctx)` / `database.UseReplica(ctx)`。 + +需要 callback 级自动路由的用户请直接接入官方 [`gorm.io/plugin/dbresolver`](https://github.com/go-gorm/dbresolver)。 + +#### 🔄 Changed — 文件重命名 `database/mysql.go → database/manager.go` + +文件内容已与 MySQL 解耦（v1.0.2 引入可插拔方言注册表后），继续叫 `mysql.go` 误导。**导入路径无变化**，公开 API 全部保留。 + +#### ✨ Added — console 包显式 level 控制 + +`console` 包新增显式级别屏蔽能力： + +```go +console.SetLevel(console.LevelWarn) // 只看 Warn / Error +console.SetLevel(console.LevelSilent) // 完全静默 +``` + +**定位明确**：console 是**开发期彩色 stdout 工具**（跟 `fmt.Println` 同级），**不写文件、不感知环境**。业务可观测信息请使用 `logger`。框架不会自动根据 `app.env` 切换级别——选择权完全在调用方，避免"dev / prod 行为不一致"的隐式陷阱。 + +完整对比表见 [GUIDE.md §3.3](./GUIDE.md#33-彩色控制台输出)。 + +#### 🐛 Fixed — Logger 重复写入修复 + +修复通用 `Logger` 把 `apiCore` 与 `dbCore` 都 Tee 进来导致**每条日志写三份**的 bug。 + +- `Logger`（通用）→ `logs/app.log` + console +- `APILog()` → `logs/api.log` + console +- `DBLog()` → `logs/database.log` + console +- 互不串扰，磁盘体积砍掉 2/3 + +**新增**：`logger.Close()` 显式关闭文件句柄，`App.Shutdown` 已自动调用；`Init(nil)` 改为返回 error 而非 panic；生产默认级别从 `Warn` 调整为 `Info`。 + +**升级注意**：日志目录会新增 `logs/app.log` 文件（之前通用日志被串写进了 `api.log`/`database.log`），运维采集脚本如有需要请补上。 + +#### 🔒 Security — CORS 中间件修复 + +修复 CORS 中间件多个安全与规范遵守问题： + +- **`Access-Control-Allow-Credentials` 永远是 `true`** — 旧实现 `if/else` 两个分支都设了 `"true"`，导致即使配置 `AllowCredentials=false` 也会发送凭证头 +- **`*` + `credentials: true` 的规范违规** — 同时发送会被浏览器拒绝；修复后此场景回显具体 Origin +- **缺失 `Vary: Origin`** — 防止 CDN / 网关把 A 用户的 CORS 响应缓存给 B 用户 +- 非白名单 Origin 不再被回显，防反射型 CORS 漏洞 + +**升级影响**：如果你之前依赖"默认允许凭证"的隐式行为，需要在配置里显式启用： + +```yaml +cors: + allowed_origins: ["https://your-frontend.example"] + allow_credentials: true +``` + +#### ⚠️ Breaking — 错误码体系重构 + +修复 `CodeSuccess` 与 `CodeInvalidParams` 撞码的生产级 bug（两者都等于 `1`，导致业务错误响应被前端误判为成功）。 + +**数值变更**： + +| 常量 | 旧值 | 新值 | +|---|---|---| +| `response.CodeSuccess` | `1` | **`0`** | +| `response.CodeFail` | `0` | **`1`** | + +**移除**： + +- `response.CodeInvalidParams`（与 `CodeSuccess` 撞码，且参数错误码应由业务自定义） +- `response.ErrInvalidParams` + +**迁移指南**： + +```go +// ❌ 旧代码（编译失败） +response.FailWithError(c, response.ErrInvalidParams) + +// ✅ 推荐：业务侧自定义错误码 +var ErrInvalidParams = response.NewError(40001, "参数错误") +response.FailWithError(c, ErrInvalidParams) + +// ✅ 或直接使用通用失败响应 +response.Fail(c, "用户名格式错误") +``` + +**前端**：`if (resp.code === 1)` → `if (resp.code === 0)`。 + +新增 `_errorCodeUniquenessGuard` 编译期防撞码 map，任何后续 `Code*` 常量重复都会在 `go build` 阶段直接报错。 + +详细迁移说明见 [CHANGELOG.md](./CHANGELOG.md)。 + +### v1.0.2 (2026-06-20) + +#### 数据库 +- **可插拔方言注册表** - 新增 `database.RegisterDialect` / `LookupDialect` / `RegisteredDialects`，应用可一次注册即让 `database.driver: ` 生效，DSN 构建器同步登记到 `config` 包；内置 `mysql` 与 `postgres`（含 `postgresql`、`pg` 别名），未注册驱动回退 MySQL +- **多数据库驱动** - `database.driver` 支持 `mysql`（默认）与 `postgres`，新增 `database.InitDB` / `InitDBWithReplicas`（v1.0.3 起原 `InitMySQL*` 别名已移除） +- **数据库管理器** - 引入实例化 `database.Manager` 持有主从连接,提供 `Master/Replica/FromContext/HealthCheck` 等方法 +- **从库选择策略** - 新增 `ReplicaPicker` 接口与 `RoundRobinPicker` / `RandomPicker` 实现，可通过 `SetReplicaPicker` 自定义 +- **私有上下文键** - `db_mode` 字符串键替换为私有 `dbModeContextKey{}` 类型，避免上下文键名冲突 +- **DSN 构建器注册表** - `config` 包新增 `RegisterDSNBuilder` / `LookupDSNBuilder` / `RegisteredDrivers`，`DatabaseConfig.DSN()` 改为查注册表，自定义 `CustomDSN` 优先 + +#### App 启动流程 +- **轻量默认** - `xlgo.New()` 默认不再初始化 MySQL / Redis / Storage，也不注册 `/health` 与 `/swagger/*`；通过 Option 显式启用 +- **组件 Option** - 新增 `WithLogger / WithMySQL / WithRedis / WithStorage / WithHealthRoutes / WithSwaggerRoutes / WithDefaultRoutes / WithAutoMigrate` 及对应 `WithoutXxx` 关闭项（注：`WithWire` 曾在此版本新增，已于 v1.1.0 随 wire 包删除而移除） +- **迁移控制** - 新增 `Migrator` 类型与 `WithMigrator / WithModels`，注册时自动开启 `WithAutoMigrate`，`WithoutAutoMigrate` 可显式关闭；不再强制调用空的 `database.AutoMigrate()` +- **batteries-included** - 新增 `WithFullStack` / `NewFullStack` / `RunFullStack`，一键启用全部默认组件 +- **错误传播** - 框架初始化失败一律 `return error`，不再在框架内部直接 `Fatalf` 退出进程 + +#### 权限中间件 +- **去业务化** - `super_admin/admin/staff` 调整为默认常量而非固定业务模型 +- **通用能力** - 新增 `AuthUser` 结构体、`GetAuthUser`、`RequireUserTypes / RequireRoles / RequireAuth`，旧的 `AdminRequired/SuperAdminRequired/StaffRequired/AnyUserRequired` 改为基于通用能力实现 + +#### 配置管理 +- **实例化 Manager** - 新增 `config.Manager`，提供 `Load / LoadWithWatch / Reload / RegisterCallback / Get / GetViper / Set` 等方法，支持多实例与重复加载 +- **App 持有 Manager** - `WithConfigPath` 创建 App 私有 manager 并通过新增的 `config.SetDefaultManager` 推为全局默认，使 `config.Get / GetString` 等便捷函数仍然可用 +- **修复** - 修复 `WithConfigPath` 此前的空实现问题 + +#### 健康检查与默认路由 +- **拆分注册** - `router` 包新增 `RegisterHealthRoute` / `RegisterSwaggerRoutes`，原 `RegisterDefaultRoutes` 改为组合调用 +- **检查项与状态** - `/health` 支持注册 `HealthCheck`，失败返回 HTTP 503 与 `{"status":"error", "checks":{...}}` +- **App 集成** - 启用 MySQL / Redis 时自动追加对应健康检查项，可通过 `WithHealthCheck` 注册自定义检查 + +#### 资源关闭 +- **Shutdown 修复** - 改为 `database.CloseAll()` 关闭主从连接，并使用 `errors.Join` 聚合限流器、日志、Redis 等组件的关闭错误 +- **Storage 可选化** - 未初始化 Storage 时返回 `ErrStorageNotInitialized`，不再 nil panic + +#### 文档与 CLI +- **CLI 修复** - `xlgo version` 更新为 v1.0.2，脚手架模板改为依赖 `github.com/EthanCodeCraft/xlgo-core` 并在注释中提示 Swagger / MySQL / Redis / FullStack 的开启方式 +- **GUIDE 同步** - 1.3 最简示例、3.2 日志注释、8.4.7 默认路由、9.2 用户信息获取均更新为 v1.0.2 行为 +- **历史日志修正** - 修复此前 README 中错误的 v2.0.0 / v2.1.0 更新日志表述 + +### v1.0.1 (2026-04-30) + +- 新增工具函数库、彩色控制台输出、压缩解压、RequestID、Recover 中间件 +- 新增缓存键名前缀、分布式锁、计数器、Redis 分布式限流 +- 增强 JWT 黑名单、Repository、CORS、日志中间件和优雅关闭能力 +- 新增路由架构，支持模块化、版本化 API、中间件分组和 RESTful CRUD +- 完善配置热更新、数据库读写分离、CSRF、SSE、WebSocket、定时任务、CLI、测试工具和统一错误码 + +### v1.0.0 (2024-04) + +- 初始版本发布 +- 基础框架功能 +- 完整示例代码 + +--- + +## 许可证 + +MIT License - 详见 [LICENSE](LICENSE) 文件 diff --git a/README.wehub.md b/README.wehub.md new file mode 100644 index 0000000..323459c --- /dev/null +++ b/README.wehub.md @@ -0,0 +1,7 @@ +# WeHub 来源说明 + +- 原始项目：`frostbyte_neo/xlgo-core` +- 原始仓库：https://gitea-dev.autobee.pro/frostbyte_neo/xlgo-core +- 导入方式：上游默认分支的最新快照 +- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准 +- 本文件仅用于记录来源，不代表 WeHub 是原项目作者 diff --git a/app.go b/app.go new file mode 100644 index 0000000..07ddac7 --- /dev/null +++ b/app.go @@ -0,0 +1,1364 @@ +package xlgo + +import ( + "context" + "crypto/tls" + "errors" + "fmt" + "net" + "net/http" + "os" + "os/signal" + "strings" + "sync" + "syscall" + "time" + + "github.com/EthanCodeCraft/xlgo-core/cache" + "github.com/EthanCodeCraft/xlgo-core/config" + "github.com/EthanCodeCraft/xlgo-core/cron" + "github.com/EthanCodeCraft/xlgo-core/database" + "github.com/EthanCodeCraft/xlgo-core/logger" + "github.com/EthanCodeCraft/xlgo-core/middleware" + "github.com/EthanCodeCraft/xlgo-core/response" + "github.com/EthanCodeCraft/xlgo-core/router" + "github.com/EthanCodeCraft/xlgo-core/storage" + "github.com/EthanCodeCraft/xlgo-core/trace" + + "github.com/gin-gonic/gin" + "github.com/redis/go-redis/v9" + "gorm.io/gorm" +) + +// Version 框架版本号。发版时只改这一处，避免版本字面量散落各处。 +// CLI（xlgo version）、脚手架生成的 go.mod 等均引用此常量。 +const Version = "1.4.0" + +// HealthCheckFunc 健康检查函数 +type HealthCheckFunc func(context.Context) error + +// Migrator 数据库迁移函数 +type Migrator func(*gorm.DB) error + +// Hook 生命周期钩子。各回调在 App 生命周期的对应阶段被调用： +// - OnInit: Init() 内组件初始化完成后、路由注册前 +// - OnStart: StartServer() 监听端口前 +// - OnReady: 端口就绪后（已开始接受连接） +// - OnStop: Shutdown() 开头，关 HTTP 之前，受 server.shutdown_timeout 约束 +// +// OnInit/OnStart/OnReady/OnStop 返回 error 会中断流程并向上返回。 +// A2 修复：OnReady 改为返回 error，失败时触发 shutdown。 +type Hook struct { + Name string + OnInit func(*App) error + OnStart func(*App) error + OnReady func(*App) error + OnStop func(*App) error +} + +type staticRoute struct { + relativePath string + root string +} + +// cronTask 收集 WithCronTask 注册的任务，doInit 创建 App 调度器后批量注册（照 +// WithMigrator/WithHealthCheck 的"Option 收集、doInit 应用"模式）。 +type cronTask struct { + name string + schedule cron.Schedule + handler cron.TaskHandler +} + +// appState 是 App 生命周期状态机（M1）。状态受 lifecycleMu 保护，单调推进： +// +// stateCreated → stateInitializing → stateInitialized → stateStopping → stateStopped +// ↓ (doInit 失败) +// stateStopping → stateStopped（failAfterInit 回滚） +// +// Go() 仅在 state < stateStopping 时放行 wg.Add；Init() 在 state >= stateStopping 时拒绝。 +type appState int32 + +const ( + stateCreated appState = iota + stateInitializing + stateInitialized + stateStopping + stateStopped +) + +// ErrAppClosed 表示 App 已 Shutdown 或 Init 失败已回滚，拒绝再 Init（M1）。 +var ErrAppClosed = errors.New("xlgo: app already shut down") + +// App 应用实例 +type App struct { + config *config.Config + configPath string + configManager *config.Manager + router *gin.Engine + registry *router.Registry + server *http.Server + + enableLogger bool + enableMySQL bool + enableRedis bool + enableStorage bool + enableHealth bool + enableSwagger bool + enableAutoMigrate bool + enableLiveness bool + enableReadiness bool + enableMetrics bool + enableCron bool + enableTrace bool + metricsPath string + + staticRoutes []staticRoute + migrators []Migrator + healthChecks []router.HealthCheck + hooks []Hook + + // 生命周期状态机（M1：取代裸 initOnce，解决 Init/Shutdown 并发改资源、 + // Init-after-Shutdown、App.Go 与 wg.Wait 的 WaitGroup 契约三类缺陷）。 + // state 受 lifecycleMu 保护；initMu 串行化 doInit/doShutdown 长段，避免并发改资源。 + // Go() 持 lifecycleMu.RLock 协调 wg.Add 与 Shutdown 的 wg.Wait（Add happens-before Wait）。 + state appState + lifecycleMu sync.RWMutex + initMu sync.Mutex + initErr error + + // shutdownOnce 确保 doShutdown 单次执行；shutdownErr 缓存结果供并发调用者共享。 + shutdownOnce sync.Once + shutdownErr error + + initializedLogger bool + initializedMySQL bool + initializedRedis bool + initializedCron bool + initializedTrace bool + initializedStorage bool + initializedCache bool + + loggerManager *logger.LogManager + loggerSnapshot *logger.DefaultSnapshot + dbManager *database.Manager + previousDB *database.Manager + redisManager *database.RedisManager + previousRedis *database.RedisManager + storageManager *storage.StorageManager + previousStorage *storage.StorageManager + scheduler *cron.Scheduler + previousScheduler *cron.Scheduler + cronTasks []cronTask + cacheManager *cache.CacheManager + previousCache *cache.CacheManager + rateLimitRegistry *middleware.RateLimitRegistry + previousRateLimitRegistry *middleware.RateLimitRegistry + + // 请求级超时（#19），<=0 表示不启用 + requestTimeout time.Duration + + // in-flight goroutine 管理（#22） + rootCtx context.Context // 根 ctx，App.Go 启动的 goroutine 共享 + cancel context.CancelFunc // Shutdown 时 cancel，通知后台任务退出 + wg sync.WaitGroup // 跟踪 App.Go 启动的 goroutine +} + +// Option 应用选项 +type Option func(*App) + +// WithConfigPath 设置配置文件路径。 +// +// M-config-5 全局可见性提示：WithConfigPath 在 Init 时会把 App 持有的 configManager 提升为 +// 全局默认（config.SetDefaultManager），故 config.Get / config.GetString 等包级便捷函数可读到 +// 该配置。这与 WithConfig 形成不对称：WithConfig 仅保留在 App 实例内，不污染全局，包级 +// config.Get() 取不到注入配置。下游若混用 a.config 与 config.GetString，两种注入方式行为不同-- +// 需要 config.Get/GetString 的下游请用 WithConfigPath（或自行 config.SetDefaultManager）。 +func WithConfigPath(path string) Option { + return func(a *App) { + a.configPath = path + a.configManager = config.NewManager(path) + } +} + +// WithConfig 设置配置对象。 +// 配置会在传入时深拷贝成 App 私有快照，并在 Init 时 Validate；调用方后续修改 cfg +// 不会污染 App 内部配置。不再调用 config.Set(cfg)，配置仅保留在 App 实例内，不污染全局状态。 +// +// M-config-5：因此 config.Get / config.GetString 等包级函数取不到此注入配置（默认空 manager）。 +// 依赖 config.Get() 获取注入配置的下游代码请改用 WithConfigPath（会提升为全局默认）。 +func WithConfig(cfg *config.Config) Option { + return func(a *App) { + a.config = cfg.Clone() + } +} + +// WithLogger 启用日志 +func WithLogger() Option { + return func(a *App) { a.enableLogger = true } +} + +// WithMySQL 启用 MySQL +func WithMySQL() Option { + return func(a *App) { a.enableMySQL = true } +} + +// WithRedis 启用 Redis +func WithRedis() Option { + return func(a *App) { a.enableRedis = true } +} + +// WithStorage 启用文件存储 +func WithStorage() Option { + return func(a *App) { a.enableStorage = true } +} + +// WithHealthRoutes 启用健康检查路由 +func WithHealthRoutes() Option { + return func(a *App) { a.enableHealth = true } +} + +// WithSwaggerRoutes 启用 Swagger 路由 +func WithSwaggerRoutes() Option { + return func(a *App) { a.enableSwagger = true } +} + +// WithDefaultRoutes 启用默认路由（健康检查、Swagger） +func WithDefaultRoutes() Option { + return func(a *App) { + a.enableHealth = true + a.enableSwagger = true + } +} + +// WithLivenessRoute 启用存活性探针路由 GET /livez（#17）。 +// 永不依赖外部，始终 200，供 K8s livenessProbe。 +func WithLivenessRoute() Option { + return func(a *App) { a.enableLiveness = true } +} + +// WithReadinessRoute 启用就绪性探针路由 GET /readyz（#17）。 +// 复用 healthChecks 检查依赖，失败返回 503，供 K8s readinessProbe。 +func WithReadinessRoute() Option { + return func(a *App) { a.enableReadiness = true } +} + +// WithMetricsRoute 启用 Prometheus 指标端点与采集中间件（#18）。 +// path 默认 /metrics，传入可自定义。 +func WithMetricsRoute(path ...string) Option { + return func(a *App) { + a.enableMetrics = true + if len(path) > 0 && path[0] != "" { + a.metricsPath = path[0] + } + } +} + +// WithoutLogger 关闭日志。 +// +// Without* 系列的定位：xlgo.New() 默认是轻量应用（组件全关），故 Without* +// 主要用于 NewFullStack / RunFullStack 启用全部组件后，排除个别不需要的项。 +// 例如：xlgo.NewFullStack(xlgo.WithoutSwaggerRoutes()) 全组件但关 Swagger。 +func WithoutLogger() Option { + return func(a *App) { a.enableLogger = false } +} + +// WithoutMySQL 关闭 MySQL +func WithoutMySQL() Option { + return func(a *App) { a.enableMySQL = false } +} + +// WithoutRedis 关闭 Redis +func WithoutRedis() Option { + return func(a *App) { a.enableRedis = false } +} + +// WithoutStorage 关闭文件存储 +func WithoutStorage() Option { + return func(a *App) { a.enableStorage = false } +} + +// WithAutoMigrate 启用数据库迁移（需配合 WithMigrator/WithModels 注册迁移逻辑） +func WithAutoMigrate() Option { + return func(a *App) { a.enableAutoMigrate = true } +} + +// WithoutAutoMigrate 关闭数据库迁移（即使已通过 WithMigrator/WithModels 注册） +func WithoutAutoMigrate() Option { + return func(a *App) { a.enableAutoMigrate = false } +} + +// WithoutHealthRoutes 关闭健康检查路由 +func WithoutHealthRoutes() Option { + return func(a *App) { a.enableHealth = false } +} + +// WithoutSwaggerRoutes 关闭 Swagger 路由 +func WithoutSwaggerRoutes() Option { + return func(a *App) { a.enableSwagger = false } +} + +// WithoutDefaultRoutes 关闭默认路由（健康检查、Swagger） +func WithoutDefaultRoutes() Option { + return func(a *App) { + a.enableHealth = false + a.enableSwagger = false + } +} + +// WithStatic 注册静态文件服务 +func WithStatic(relativePath, root string) Option { + return func(a *App) { + a.staticRoutes = append(a.staticRoutes, staticRoute{relativePath: relativePath, root: root}) + } +} + +// WithPublicStatic 注册默认 public 静态文件服务 +func WithPublicStatic() Option { + return WithStatic("/public", "./public") +} + +// WithHealthCheck 注册健康检查项 +func WithHealthCheck(name string, check HealthCheckFunc) Option { + return func(a *App) { + a.healthChecks = append(a.healthChecks, router.HealthCheck{Name: name, Check: check}) + } +} + +// WithMigrator 注册数据库迁移函数（自动启用 AutoMigrate） +func WithMigrator(m Migrator) Option { + return func(a *App) { + if m != nil { + a.migrators = append(a.migrators, m) + a.enableAutoMigrate = true + } + } +} + +// WithHook 注册生命周期钩子（#12）。可多次调用注册多个，按注册顺序触发。 +// 详见 Hook 类型注释。 +func WithHook(h Hook) Option { + return func(a *App) { + a.hooks = append(a.hooks, h) + } +} + +// WithRequestTimeout 设置请求级超时（#19）。下游 GORM/Redis 走 +// c.Request.Context() 即可级联取消。d <= 0 不启用。 +func WithRequestTimeout(d time.Duration) Option { + return func(a *App) { a.requestTimeout = d } +} + +// WithCron 将 cron 调度器纳入 App 生命周期（Phase 3 实例化）。 +// 启用后：Init 时创建 App 专属 Scheduler、注册 WithCronTask 收集的任务、提升为全局默认、 +// Start 启动调度循环；Shutdown 在剩余预算内 StopWithTimeout 等待在跑任务退出。 +// +// 任务注册：优先用 WithCronTask(...)（或 Init 后 app.Scheduler().AddTask(...)）注册到 App 实例。 +// 包级 cron.AddTask(...) 仍可用--它代理到当前全局默认（App swap 后即 App 的调度器）--但 +// 在 App.Init 之前调用会注册到 init 默认调度器、被 App swap 丢弃，故 pre-Init 注册请用 WithCronTask。 +func WithCron() Option { + return func(a *App) { a.enableCron = true } +} + +// WithCronTask 注册一个定时任务到 App 的调度器（Phase 3）。蕴含启用 cron（照 WithMigrator +// 自动启用 AutoMigrate 的模式），故无需同时 WithCron。任务在 doInit 创建调度器后注册。 +// +// name/schedule/handler 的校验由 cron.Scheduler.AddTask 负责（nil schedule/handler panic， +// 非法 cron 字段 panic）。动态输入请先用 cron.ParseCronStrict 处理 error。 +func WithCronTask(name string, schedule cron.Schedule, handler cron.TaskHandler) Option { + return func(a *App) { + a.cronTasks = append(a.cronTasks, cronTask{name: name, schedule: schedule, handler: handler}) + a.enableCron = true + } +} + +// WithTrace 将链路追踪（OpenTelemetry）纳入 App 生命周期（Phase 1）。 +// +// 启用后：Init 时按 config.Trace 调 trace.Init（安装 TracerProvider/Propagator）并把 +// trace.Middleware 装入全局中间件链；Shutdown 时调 trace.Close 刷出 exporter 并释放 +// 后台 goroutine/连接（H-14 后 Close 幂等，但 App 此前从未调它--本 Option 补上生命周期闭环）。 +// +// 实际是否导出 span 由 config.Trace.Enabled 控制：Enabled=false（默认）时 trace.Init +// 安装 Noop tracer，Middleware 不 panic、不导出。故"WithTrace + trace.enabled=true + endpoint" +// 才真正出链路；仅 WithTrace 而未配 enabled 为 Noop（安全）。 +// +// 不做 per-App 实例隔离：OTel 的 TracerProvider/Propagator 是进程级全局单例 +// （otel.SetTracerProvider 全局生效），多 App 进程共享同一 OTel 状态，与 OTel 设计一致。 +func WithTrace() Option { + return func(a *App) { a.enableTrace = true } +} + +// WithModels 注册 GORM 自动迁移模型（自动启用 AutoMigrate） +func WithModels(models ...any) Option { + return WithMigrator(func(db *gorm.DB) error { + return db.AutoMigrate(models...) + }) +} + +// WithModules 注册模块 +func WithModules(modules ...router.Module) Option { + return func(a *App) { + for _, m := range modules { + a.registry.RegisterModule(m) + } + } +} + +// WithVersions 注册版本化 API +func WithVersions(versions ...*router.VersionedAPI) Option { + return func(a *App) { + for _, v := range versions { + a.registry.RegisterVersion(v) + } + } +} + +// WithMiddlewares 注册全局中间件 +func WithMiddlewares(middlewares ...gin.HandlerFunc) Option { + return func(a *App) { + a.registry.Use(middlewares...) + } +} + +// WithFullStack 启用全功能默认组件 +func WithFullStack() Option { + return func(a *App) { + a.enableLogger = true + a.enableMySQL = true + a.enableRedis = true + a.enableStorage = true + a.enableHealth = true + a.enableSwagger = true + a.enableAutoMigrate = true + // 生产就绪路由（#17/#18） + a.enableLiveness = true + a.enableReadiness = true + a.enableMetrics = true + a.staticRoutes = append(a.staticRoutes, staticRoute{relativePath: "/public", root: "./public"}) + } +} + +// New 创建新应用 +func New(opts ...Option) *App { + app := &App{} + app.router = gin.New() + app.registry = router.NewRegistry(app.router) + // rootCtx 生命周期与 App 一致，不依赖 Init，使 App.Go 在 Init 前也可用（#22） + app.rootCtx, app.cancel = context.WithCancel(context.Background()) + // Phase 5：限流器 Registry 在 New 时预创建，使 app.RateLimitRegistry() 在 Init 前即可用于 + // 路由装配（app-bound 中间件捕获此实例，请求时走 App 自己的 Registry 而非全局默认， + // 实现多 App per-App 计数隔离）。doInit 时 swap 为全局默认供包级 facade 代理。 + app.rateLimitRegistry = middleware.NewRateLimitRegistry() + + for _, opt := range opts { + opt(app) + } + + return app +} + +// NewFullStack 创建启用默认全功能组件的应用 +func NewFullStack(opts ...Option) *App { + all := append([]Option{WithFullStack()}, opts...) + return New(all...) +} + +// RunFullStack 创建并启动启用默认全功能组件的应用 +func RunFullStack(opts ...Option) error { + return NewFullStack(opts...).Run() +} + +// Init 初始化应用，不启动 HTTP 监听（M1：状态机 + initMu 保证单次执行与并发安全）。 +// 多次调用：已成功则返回缓存结果；已 Shutdown/Init 失败则返回 ErrAppClosed。 +// +// initMu 串行化 doInit 与 doShutdown（避免并发改资源）；lifecycleMu 仅短暂持有以翻状态， +// 不阻塞 Go()（doInit 内 a.Go 只抢 lifecycleMu.RLock）。 +// +// 注意：生命周期 hook（OnInit/OnStart/OnReady/OnStop）不允许重入调用 Init/Shutdown/Run—— +// initMu 非重入，hook 内调用会自锁死锁（M1 文档约束）。 +func (a *App) Init() error { + a.initMu.Lock() + defer a.initMu.Unlock() + + a.lifecycleMu.Lock() + switch a.state { + case stateCreated: + a.state = stateInitializing + a.lifecycleMu.Unlock() + case stateInitialized: + err := a.initErr + a.lifecycleMu.Unlock() + return err + case stateStopping, stateStopped: + a.lifecycleMu.Unlock() + return ErrAppClosed + default: // stateInitializing — initMu 串行下不可达，防御性返回 + err := a.initErr + a.lifecycleMu.Unlock() + return err + } + + a.initErr = a.doInit() + if a.initErr != nil { + a.failAfterInit() + return a.initErr + } + + a.lifecycleMu.Lock() + a.state = stateInitialized + a.lifecycleMu.Unlock() + return nil +} + +// failAfterInit 在 doInit 失败时执行资源回滚（M1）。 +// 顺序：标记 stateStopping（阻新 Go）→ cancel rootCtx → wg.Wait（让 a.Go 启动的探活等 +// goroutine 先退出，10s 超时）→ stopCron(5s) → rollbackReplacedResources。 +// 先停 goroutine 再回滚资源，避免“回滚 DB 时探活 goroutine 仍在用”的竞态。 +// +// 回滚走 rollbackReplacedResources（恢复 Init 前默认 manager 再关新建 manager）， +// 而非 closeResources（直接关闭，仅供 doShutdown 复用）。Init 失败需恢复默认 manager +// 而非直接关，故两者不复用同一路径。cron 停止预算固定 5s，由本路径单独停止。 +// 回滚错误与原 initErr 合并上抛，不吞。 +func (a *App) failAfterInit() { + a.lifecycleMu.Lock() + a.state = stateStopping + a.lifecycleMu.Unlock() + + // H-2：cancel rootCtx 让 a.Go 启动的后台 goroutine 退出，不泄漏。 + if a.cancel != nil { + a.cancel() + } + waitDone := make(chan struct{}) + go func() { a.wg.Wait(); close(waitDone) }() + select { + case <-waitDone: + case <-time.After(10 * time.Second): + logger.Warnf("Init 失败后等待后台 goroutine 退出超时（10s），可能存在未响应 ctx.Done 的 goroutine") + } + + // M1：回滚 doInit 已初始化的资源。cron 显式 5s 超时不卡死回滚； + // logger/db/redis 恢复 Init 前默认 manager，再关闭本 App 新建的 manager。 + if err := a.stopCron(5 * time.Second); err != nil { + a.initErr = errors.Join(a.initErr, err) + } + // trace 不是 swap 资源（OTel 全局），不走 rollbackReplacedResources；Init 失败时单独 Close。 + if a.initializedTrace { + closeCtx, closeCancel := context.WithTimeout(context.Background(), 5*time.Second) + if err := trace.Close(closeCtx); err != nil { + a.initErr = errors.Join(a.initErr, fmt.Errorf("trace 关闭失败: %w", err)) + } + closeCancel() + a.initializedTrace = false + } + if rbErr := a.rollbackReplacedResources(); rbErr != nil { + a.initErr = errors.Join(a.initErr, fmt.Errorf("回滚已初始化资源失败: %w", rbErr)) + } + + a.lifecycleMu.Lock() + a.state = stateStopped + a.lifecycleMu.Unlock() +} + +// closeResources 关闭 db→redis→logger（M1）。各均为幂等 no-op（未 init 时安全）， +// 仅供 doShutdown 复用。cron 因停止预算随调用方不同（Init 失败 5s / Shutdown 剩余 +// 预算），由各调用方单独停止，不在此处。返回聚合错误。 +// 注意：Init 失败的回滚不经本函数，而走 failAfterInit 的 rollbackReplacedResources +// （需恢复 Init 前默认 manager，而非直接关闭）。 +func (a *App) closeResources() error { + var errs []error + if a.initializedMySQL { + if a.dbManager != nil { + if err := a.dbManager.Close(); err != nil { + errs = append(errs, err) + } + } else if err := database.CloseAll(); err != nil { + errs = append(errs, err) + } + a.initializedMySQL = false + a.dbManager = nil + } + if a.initializedRedis { + if a.redisManager != nil { + if err := a.redisManager.Close(); err != nil { + errs = append(errs, err) + } + } else if err := database.CloseRedis(); err != nil { + errs = append(errs, err) + } + a.initializedRedis = false + a.redisManager = nil + } + if a.initializedStorage { + // StorageManager.Close 当前为 no-op（oss.Client 无 Close），但闭合 Init/Close 生命周期， + // 为未来驱动预留收口点。与 db/redis/logger manager 对齐。 + if a.storageManager != nil { + if err := a.storageManager.Close(); err != nil { + errs = append(errs, err) + } + } + a.initializedStorage = false + a.storageManager = nil + } + if a.initializedLogger { + if a.loggerManager != nil { + if err := a.loggerManager.Close(); err != nil { + errs = append(errs, err) + } + } else if err := logger.Close(); err != nil { + errs = append(errs, err) + } + a.initializedLogger = false + a.loggerManager = nil + } + // M-config-3：停止 App 持有的 configManager 热重载 watcher（若已启用），避免 App 关闭后 + // 遗留监听 goroutine。默认流程（resolveConfig 用 Load 不启 watcher）为 no-op；用户对 + // configManager 调用 LoadWithWatch/StartWatcher 后由这里统一收口。StopWatcher 幂等且会等待 + // 进行中的 reload 回调结束，符合 C7 生命周期契约。configManager 可能为 nil（WithConfig 注入）。 + if a.configManager != nil { + a.configManager.StopWatcher() + } + return errors.Join(errs...) +} + +func (a *App) rollbackReplacedResources() error { + var errs []error + if a.initializedMySQL { + if a.previousDB != nil { + database.SwapDefaultManager(a.previousDB) + } + if a.dbManager != nil { + if err := a.dbManager.Close(); err != nil { + errs = append(errs, err) + } + } + a.dbManager = nil + a.previousDB = nil + a.initializedMySQL = false + } + if a.initializedRedis { + if a.previousRedis != nil { + database.SwapDefaultRedisManager(a.previousRedis) + } + if a.redisManager != nil { + if err := a.redisManager.Close(); err != nil { + errs = append(errs, err) + } + } + a.redisManager = nil + a.previousRedis = nil + a.initializedRedis = false + } + if a.initializedStorage { + // 把全局默认 swap 回 Init 前的旧实例，并 Close 本 App 新建的 manager（与 closeResources + // 的 Shutdown 路径对称）。当前 Close 为 no-op，但未来驱动有真实副作用时不漏关。 + if a.previousStorage != nil { + storage.SwapDefaultStorageManager(a.previousStorage) + } + if a.storageManager != nil { + if err := a.storageManager.Close(); err != nil { + errs = append(errs, err) + } + } + a.storageManager = nil + a.previousStorage = nil + a.initializedStorage = false + } + // cron：stopCron 已在 failAfterInit 停止调度 goroutine（并把 initializedCron 置 false）， + // 此处仅把全局默认 swap 回 Init 前的旧调度器。用 a.scheduler 作守卫（stopCron 不 nil 它）。 + if a.scheduler != nil { + if a.previousScheduler != nil { + cron.SwapDefaultScheduler(a.previousScheduler) + } + a.previousScheduler = nil + a.scheduler = nil + } + if a.initializedCache { + // CacheManager 无 Close（client 由 redisManager 持有）：仅 swap 回全局默认、清理引用。 + if a.previousCache != nil { + cache.SwapDefaultCacheManager(a.previousCache) + } + a.cacheManager = nil + a.previousCache = nil + a.initializedCache = false + } + if a.rateLimitRegistry != nil { + // 停止可能已创建的 limiter（Init 期间通常无请求、无 limiter；Stop 幂等）。 + a.rateLimitRegistry.Stop() + if a.previousRateLimitRegistry != nil { + middleware.SwapDefaultRateLimitRegistry(a.previousRateLimitRegistry) + } + a.previousRateLimitRegistry = nil + a.rateLimitRegistry = nil + } + if a.initializedLogger { + if err := logger.RestoreDefaultSnapshot(a.loggerSnapshot); err != nil { + errs = append(errs, err) + } + a.loggerManager = nil + a.loggerSnapshot = nil + a.initializedLogger = false + } + return errors.Join(errs...) +} + +func (a *App) commitReplacedResources() { + // Phase 4 多 App 修复：不关闭 previousDB/previousRedis。previous 是 Init 前的全局默认， + // 多 App 下可能属于另一个 App 的活跃 manager--关闭会误杀它（B 的 commit 关掉 A 的 redis， + // 致 A 的 cache 持有的 client 失效 "redis: client is closed"）。此 App 不 owns previous， + // 仅清理回滚引用。单 App 下 previous 为 init() 空默认（无 client，Close 本就是 no-op）， + // 不关闭无泄漏。用户若手动 InitRedis/InitDB 后再 App.Init，旧 client 的关闭由用户负责。 + if a.previousDB != nil { + a.previousDB = nil + } + if a.previousRedis != nil { + a.previousRedis = nil + } + if a.previousStorage != nil { + // StorageManager 无 Close；Init 成功后仅清理回滚引用，旧实例交由 GC。 + a.previousStorage = nil + } + if a.previousScheduler != nil { + // App 调度器已 Start 并接管全局默认；旧默认（init 或上一 App 的）无 goroutine 需停 + // （init 默认从未 Start；上一 App 的已在其 Shutdown 停止）。仅清理回滚引用。 + a.previousScheduler = nil + } + if a.previousCache != nil { + // CacheManager 无 Close（client 由 redisManager 持有）；仅清理回滚引用。 + a.previousCache = nil + } + if a.previousRateLimitRegistry != nil { + // Registry 的 limiter 由 App.Shutdown 的 registry.Stop() 停止；此处仅清理回滚引用。 + a.previousRateLimitRegistry = nil + } + if a.loggerSnapshot != nil { + // Phase 4 多 App 修复（与 previousDB/previousRedis 对齐）：不关闭 loggerSnapshot 捕获的 + // 旧 writers。多 App 下该 snapshot 可能捕获的是另一个 App 的活跃 logger writers--关闭会 + // 误杀它（B 的 commit 关掉 A 的 app.log/api.log writer，A 后续写日志失败/丢失）。此 App + // 不 owns 旧 writers：init() 默认为 Nop（无 writer，不泄漏）；另一 App 的 writers 由其自身 + // Shutdown 关闭；用户手动配置 logger 后再 App.Init 的旧 writer 由用户负责。仅清理回滚引用。 + a.loggerSnapshot = nil + } +} + +func (a *App) stopCron(timeout time.Duration) error { + if !a.initializedCron { + return nil + } + a.initializedCron = false + if a.scheduler == nil { + return nil + } + // 停 App 专属调度器（Phase 3），不再调全局 cron.StopGlobalWithTimeout。 + if !a.scheduler.StopWithTimeout(timeout) { + return fmt.Errorf("cron 调度器停止超时（%s）", timeout) + } + return nil +} + +func (a *App) shutdownAfterStartFailure(startErr error) error { + if startErr == nil { + return nil + } + if shutErr := a.Shutdown(); shutErr != nil { + return fmt.Errorf("%w (关闭错误: %v)", startErr, shutErr) + } + return startErr +} + +func (a *App) runOnStopHook(ctx context.Context, h Hook) error { + if h.OnStop == nil { + return nil + } + done := make(chan error, 1) + go func() { + done <- h.OnStop(a) + }() + select { + case err := <-done: + if err != nil { + return fmt.Errorf("OnStop hook %q 失败: %w", h.Name, err) + } + return nil + case <-ctx.Done(): + return fmt.Errorf("OnStop hook %q 超时: %w", h.Name, ctx.Err()) + } +} + +// doInit 执行实际初始化流程。仅在 Init 持有 initMu 并完成状态切换后调用，不可直接调用。 +func (a *App) doInit() error { + cfg, err := a.resolveConfig() + if err != nil { + return err + } + if cfg.IsProduction() { + gin.SetMode(gin.ReleaseMode) + } + + // trace 先于其它组件初始化：失败即早退，避免已建 DB/Redis 等资源因 trace 失败回滚。 + // OTel 进程全局，Init 安装全局 TracerProvider；Enabled=false 时为 Noop（安全）。 + if a.enableTrace { + if err := trace.Init(buildTraceConfig(cfg)); err != nil { + return fmt.Errorf("初始化 trace 失败: %w", err) + } + a.initializedTrace = true + } + + if a.enableLogger { + lm := logger.NewLogManager() + snapshot := logger.SnapshotDefault() + if err := lm.InitPreservingPrevious(cfg); err != nil { + return fmt.Errorf("初始化日志失败: %w", err) + } + logger.SetDefaultLogManager(lm) + a.loggerManager = lm + a.loggerSnapshot = snapshot + a.initializedLogger = true + } + + if a.enableMySQL { + dbm := database.NewManager(cfg) + if err := dbm.InitDB(a.rootCtx, cfg); err != nil { + return fmt.Errorf("初始化数据库失败: %w", err) + } + a.previousDB = database.SwapDefaultManager(dbm) + a.dbManager = dbm + a.initializedMySQL = true + a.healthChecks = append(a.healthChecks, router.HealthCheck{Name: "mysql", Check: func(ctx context.Context) error { + // 优先读探活缓存标记（#21），避免每次探针都同步 ping + if !dbm.IsHealthy() { + return errors.New("mysql 主库探活不健康") + } + return dbm.HealthCheck(ctx) + }}) + } + + if a.enableRedis { + rm := database.NewRedisManager() + if err := rm.Init(cfg); err != nil { + return fmt.Errorf("初始化 Redis 失败: %w", err) + } + a.previousRedis = database.SwapDefaultRedisManager(rm) + a.redisManager = rm + a.initializedRedis = true + a.healthChecks = append(a.healthChecks, router.HealthCheck{Name: "redis", Check: rm.HealthCheck}) + } + + if a.enableStorage { + sm := storage.NewStorageManager() + if err := sm.Init(&cfg.Storage); err != nil { + return fmt.Errorf("初始化存储失败: %w", err) + } + // 实例化 + 提升为全局默认（照 db/redis 的 Swap 模式）。StorageManager 无 Close + // （LocalStorage/OSSStorage 无 closeable 资源），Shutdown 不关、仅 Init 失败时 swap 回退。 + a.previousStorage = storage.SwapDefaultStorageManager(sm) + a.storageManager = sm + a.initializedStorage = true + } + + if a.enableRedis { + // Redis 就绪后初始化缓存。Phase 4：注入 App 的 redisManager.Client()，使缓存走 per-App + // Redis 而非全局 database.GetRedis()（修复多 App 跨 Redis 串越）。提升为全局默认供包级 + // facade（cache.Get 等）代理到此。CacheManager 无 Close（client 由 redisManager 持有）。 + cm := cache.NewCacheManager() + cm.InitWithRedis(a.redisManager.Client()) + a.previousCache = cache.SwapDefaultCacheManager(cm) + a.cacheManager = cm + a.initializedCache = true + } + + if a.enableAutoMigrate && len(a.migrators) > 0 { + if !a.enableMySQL { + return errors.New("注册了数据库迁移但未启用 MySQL") + } + db := database.GetDB() + if db == nil { + return errors.New("MySQL 未初始化，无法执行数据库迁移") + } + for _, migrator := range a.migrators { + if err := migrator(db); err != nil { + return fmt.Errorf("数据库迁移失败: %w", err) + } + } + } + + // 全局中间件链：RequestID 必须最先装入，保证后续 Recovery/日志/响应都能拿到 request_id（#24） + a.router.Use(middleware.RequestID()) + a.router.Use(middleware.Recover()) + // trace 中间件装在 Recover 之后：Recover 兜底捕获 trace 内 panic，span 覆盖业务 handler。 + // Enabled=false 时为 Noop tracer，Middleware 不导出；noop span 无 TraceID 则不写 X-Trace-ID。 + if a.enableTrace { + // 用与 buildTraceConfig 一致的回退名（ServiceName 空时取 cfg.App.Name），避免中间件 + // span 属性与 provider resource 的 service.name 来源不一致。 + svcName := a.config.Trace.ServiceName + if svcName == "" { + svcName = a.config.App.Name + } + a.router.Use(trace.Middleware(svcName)) + } + // 请求级超时（#19），配置后装入，下游走 c.Request.Context() 级联取消 + if a.requestTimeout > 0 { + a.router.Use(middleware.Timeout(a.requestTimeout)) + } + + for _, staticRoute := range a.staticRoutes { + a.router.Static(staticRoute.relativePath, staticRoute.root) + } + + if a.enableSwagger { + router.RegisterSwaggerRoutes(a.router) + } + if a.enableHealth { + router.RegisterHealthRoute(a.router, a.healthChecks...) + } + if a.enableLiveness { + router.RegisterLivenessRoute(a.router) + } + if a.enableReadiness { + router.RegisterReadinessRoute(a.router, a.healthChecks...) + } + if a.enableMetrics { + // 采集中间件交给注册中心，Apply 时作为首个全局中间件装入（H8c）， + // 覆盖所有经注册中心注册的业务路由，不依赖调用顺序。 + a.registry.SetMetricsMiddleware(middleware.Metrics()) + if a.metricsPath != "" { + router.RegisterMetricsRoute(a.router, a.metricsPath) + } else { + router.RegisterMetricsRoute(a.router) + } + } + + a.registry.Apply() + + // 响应模式：默认 business（全 200 + 业务码），可配置 rest（按错误码映射 HTTP status）（#15） + if mode := strings.TrimSpace(strings.ToLower(a.config.Server.ResponseMode)); mode != "" { + switch mode { + case "rest": + response.SetMode(response.ModeREST) + case "business": + response.SetMode(response.ModeBusiness) + } + } + + // 错误 Detail 暴露策略（P1 #15）：仅开发环境向客户端输出 Error.Detail， + // 生产环境隐藏，避免内部错误细节（SQL/堆栈等）经 Detail 泄露给客户端。 + response.SetExposeDetail(cfg.IsDevelopment()) + + // in-flight goroutine 根 ctx 在 New() 时已初始化（#22） + + // 启动主库/从库探活后台循环（#21），ctx 在 Shutdown 时取消 + if a.enableMySQL { + a.Go(a.dbManager.StartProbing) + } + + // 启动 App 专属 cron 调度器（Phase 3 实例化）：创建实例 -> 注册 WithCronTask 收集的任务 -> + // 提升为全局默认（包级 cron.AddTask 代理到此）-> Start。Shutdown 时 StopWithTimeout。 + if a.enableCron { + a.scheduler = cron.NewScheduler() + for _, ct := range a.cronTasks { + a.scheduler.AddTask(ct.name, ct.schedule, ct.handler) + } + a.previousScheduler = cron.SwapDefaultScheduler(a.scheduler) + a.scheduler.Start() + a.initializedCron = true + } + + // Phase 5：把 New 时预创建的 App 专属 Registry 提升为全局默认，供包级 facade（LoginRateLimit + // 等）代理。app-bound 中间件（app.RateLimitRegistry().LoginRateLimit()）直接捕获此实例， + // 不查全局默认，实现多 App per-App 计数隔离。不预 Init（懒创建）；Shutdown 时 Stop。 + a.previousRateLimitRegistry = middleware.SwapDefaultRateLimitRegistry(a.rateLimitRegistry) + + // OnInit hooks：组件初始化完成后触发（#12） + for _, h := range a.hooks { + if h.OnInit != nil { + if err := h.OnInit(a); err != nil { + return fmt.Errorf("OnInit hook %q 失败: %w", h.Name, err) + } + } + } + a.commitReplacedResources() + return nil +} + +func (a *App) resolveConfig() (*config.Config, error) { + if a.config != nil { + cfg := a.config.Clone() + if err := cfg.Validate(); err != nil { + return nil, fmt.Errorf("配置校验失败: %w", err) + } + a.config = cfg + return cfg, nil + } + if a.configManager == nil && a.configPath != "" { + a.configManager = config.NewManager(a.configPath) + } + if a.configManager != nil { + cfg, err := a.configManager.Load() + if err != nil { + return nil, err + } + // 让 App 持有的 manager 成为全局默认， + // 使 config.Get / config.GetString 等便捷函数仍能取到正确配置。 + config.SetDefaultManager(a.configManager) + a.config = cfg + return cfg, nil + } + cfg := config.Get() + if cfg == nil { + return nil, config.ErrConfigNotLoaded + } + a.config = cfg + return cfg, nil +} + +// buildTraceConfig 把 config.TraceConfig 映射为 trace.Config，并补友好默认值： +// - ServiceName 空时回退 cfg.App.Name（业务侧常已配 app.name，免重复填）； +// - ExporterType 空时默认 "otlp-http"（最常用），避免 trace.Init 对空值报"不支持的导出器类型"。 +// +// 不默认 Endpoint/SampleRatio/Propagator：Endpoint 空时 OTEL 客户端走自身默认（localhost:4318）； +// SampleRatio=0 是合法值（不采样），不应被默认覆盖；Propagator 空时 trace.Init 已按 w3c 处理。 +// Enabled 完全透传--由 config.Trace.Enabled 决定是否真正导出，WithTrace 只管生命周期。 +func buildTraceConfig(cfg *config.Config) trace.Config { + tc := cfg.Trace + exporter := tc.ExporterType + if exporter == "" { + exporter = "otlp-http" + } + name := tc.ServiceName + if name == "" { + name = cfg.App.Name + } + return trace.Config{ + ServiceName: name, + ServiceVersion: tc.ServiceVersion, + Environment: tc.Environment, + ExporterType: exporter, + Endpoint: tc.Endpoint, + Insecure: tc.Insecure, + SampleRatio: tc.SampleRatio, + Enabled: tc.Enabled, + Propagator: tc.Propagator, + } +} + +// Run 启动应用 +func (a *App) Run() error { + if err := a.Init(); err != nil { + return err + } + return a.shutdownAfterStartFailure(a.StartServer()) +} + +// StartServer 启动 HTTP 服务器（支持优雅关闭） +func (a *App) StartServer() error { + if a.config == nil { + return config.ErrConfigNotLoaded + } + srvCfg := a.config.Server + + a.server = &http.Server{ + Handler: a.router, + ReadTimeout: srvCfg.EffectiveReadTimeout(), + WriteTimeout: srvCfg.EffectiveWriteTimeout(), + IdleTimeout: srvCfg.EffectiveIdleTimeout(), + MaxHeaderBytes: srvCfg.EffectiveMaxHeaderBytes(), + } + + useUnix := strings.TrimSpace(srvCfg.UnixSocket) != "" + if useUnix { + a.server.Addr = srvCfg.UnixSocket + } else { + // Host 为空时监听所有接口（":port"）；设值时绑定指定地址（"host:port"）， + // 用于仅本机（127.0.0.1）或绑定内网网卡的场景 + a.server.Addr = fmt.Sprintf("%s:%d", srvCfg.Host, srvCfg.Port) + } + + // OnStart hooks：监听端口前 + for _, h := range a.hooks { + if h.OnStart != nil { + if err := h.OnStart(a); err != nil { + return a.shutdownAfterStartFailure(fmt.Errorf("OnStart hook %q 失败: %w", h.Name, err)) + } + } + } + + network := "tcp" + address := a.server.Addr + if useUnix { + network = "unix" + address = srvCfg.UnixSocket + } + ln, err := net.Listen(network, address) + if err != nil { + return a.shutdownAfterStartFailure(fmt.Errorf("服务器监听失败: %w", err)) + } + if srvCfg.TLS.Enabled { + cert, err := tls.LoadX509KeyPair(srvCfg.TLS.CertFile, srvCfg.TLS.KeyFile) + if err != nil { + _ = ln.Close() + return a.shutdownAfterStartFailure(fmt.Errorf("服务器 TLS 配置无效: %w", err)) + } + ln = tls.NewListener(ln, &tls.Config{ + Certificates: []tls.Certificate{cert}, + MinVersion: tls.VersionTLS12, + }) + } + + serverErr := make(chan error, 1) + serveStarted := make(chan struct{}) + go func() { + close(serveStarted) + if useUnix { + logger.Infof("服务器启动，监听 unix socket %s", srvCfg.UnixSocket) + } else if srvCfg.Host != "" { + logger.Infof("服务器启动，监听 %s:%d", srvCfg.Host, srvCfg.Port) + } else { + logger.Infof("服务器启动，监听端口 %d（所有接口）", srvCfg.Port) + } + serveErr := a.server.Serve(ln) + if serveErr != nil && !errors.Is(serveErr, http.ErrServerClosed) { + serverErr <- serveErr + return + } + serverErr <- nil + }() + <-serveStarted + select { + case err := <-serverErr: + if err != nil { + return a.shutdownAfterStartFailure(fmt.Errorf("服务器启动失败: %w", err)) + } + return nil + default: + } + + // OnReady hooks：listener 已成功创建，Serve goroutine 已启动（M1）。 + for _, h := range a.hooks { + if h.OnReady != nil { + if err := h.OnReady(a); err != nil { + logger.Errorf("OnReady hook %q 失败: %v", h.Name, err) + // H-1 修复：失败时走 Shutdown 释放 HTTP 端口、后台 goroutine 与已初始化资源， + // 避免监听 goroutine 永久阻塞在 Serve 致端口/goroutine 泄漏。 + // 不再向 serverErr 写入——监听 goroutine 在 Shutdown 后会写 nil 到 serverErr（cap=1）， + // 若此处也写则第二次写阻塞致 goroutine 泄漏。 + if shutErr := a.Shutdown(); shutErr != nil { + return fmt.Errorf("OnReady hook %q 失败: %w (关闭错误: %v)", h.Name, err, shutErr) + } + _ = ln.Close() + return fmt.Errorf("OnReady hook %q 失败: %w", h.Name, err) + } + } + } + + quit := make(chan os.Signal, 1) + signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM, syscall.SIGHUP) + defer signal.Stop(quit) + + select { + case err := <-serverErr: + if err != nil { + return a.shutdownAfterStartFailure(fmt.Errorf("服务器启动失败: %w", err)) + } + return nil + case sig := <-quit: + logger.Infof("收到信号 %v，开始优雅关闭...", sig) + return a.Shutdown() + } +} + +// Shutdown 优雅关闭应用（M1：幂等 + 与 Init 互斥）。 +// shutdownOnce 保证 doShutdown 单次执行，并发调用者阻塞至首个完成后返回同一 shutdownErr。 +// initMu 串行化 doShutdown 与 doInit，避免并发改资源。 +// +// 注意：生命周期 hook 不允许重入调用 Init/Shutdown/Run——initMu 非重入，hook 内调用会自锁。 +func (a *App) Shutdown() error { + a.shutdownOnce.Do(func() { + a.initMu.Lock() + defer a.initMu.Unlock() + + a.lifecycleMu.Lock() + if a.state >= stateStopping { + // shutdownOnce 已保证单次，此处不可达；防御性直接返回。 + a.lifecycleMu.Unlock() + return + } + wasInitialized := a.state == stateInitialized + a.state = stateStopping + a.lifecycleMu.Unlock() + + a.shutdownErr = a.doShutdown(wasInitialized) + + a.lifecycleMu.Lock() + a.state = stateStopped + a.lifecycleMu.Unlock() + }) + return a.shutdownErr +} + +// doShutdown 执行实际关闭流程。仅在 Shutdown（持 initMu）中调用。 +// 顺序（M1 调整）：OnStop（仅 Init 曾成功时）→ cancel rootCtx → server.Shutdown → +// wg.Wait → cron / 限流器 / db / redis / logger。OnStop 在 shutdown 开头、关 HTTP 之前， +// 保有 cancel 前协调资源的机会；state=Stopping 已阻新 Go，无需先 cancel/wait 再跑 hook。 +// OnStop 也受同一个 shutdownTimeout 预算约束，避免 hook 卡死拖住整个进程退出。 +func (a *App) doShutdown(wasInitialized bool) error { + shutdownTimeout := 30 * time.Second + if a.config != nil { + shutdownTimeout = a.config.Server.EffectiveShutdownTimeout() + } + ctx, cancel := context.WithTimeout(context.Background(), shutdownTimeout) + defer cancel() + + var errs []error + + // OnStop hooks：Shutdown 开头，关 HTTP 之前触发（#12）。仅 Init 曾成功时执行（M1）—— + // Init 失败/未 Init 时 HTTP 从未启动，OnStop 语义不适用。 + if wasInitialized { + for _, h := range a.hooks { + if err := a.runOnStopHook(ctx, h); err != nil { + errs = append(errs, err) + if ctx.Err() != nil { + break + } + } + } + } + + // 取消根 ctx，通知 App.Go 启动的后台 goroutine 退出（#22） + if a.cancel != nil { + a.cancel() + } + + if a.server != nil { + logger.Info("关闭 HTTP 服务器...") + if err := a.server.Shutdown(ctx); err != nil { + logger.Warnf("HTTP 服务器关闭超时: %v", err) + errs = append(errs, err) + if closeErr := a.server.Close(); closeErr != nil { + errs = append(errs, closeErr) + } + } + } + + // 等待业务 in-flight goroutine 退出（#22），受 shutdownTimeout 约束 + waitDone := make(chan struct{}) + go func() { + a.wg.Wait() + close(waitDone) + }() + select { + case <-waitDone: + case <-ctx.Done(): + logger.Warnf("等待后台 goroutine 退出超时") + } + + // 停止 cron 全局调度器（P1 #10），在剩余 shutdown 预算内等待在跑任务退出。 + if a.initializedCron { + logger.Info("停止 cron 调度器...") + remaining := time.Second + if dl, ok := ctx.Deadline(); ok { + if r := time.Until(dl); r > 0 { + remaining = r + } + } + if err := a.stopCron(remaining); err != nil { + logger.Warnf("cron 调度器停止超时，可能有任务未响应 ctx 取消") + } + } + + // Phase 5：停 App 专属限流器 Registry（不再调全局 middleware.StopRateLimiters，避免误停其他 App）。 + if a.rateLimitRegistry != nil { + logger.Info("停止限流器...") + a.rateLimitRegistry.Stop() + } + + // trace.Close 刷出 exporter 批量 span 并释放后台 goroutine/连接（H-14 后幂等）。 + // 放在 db/redis/logger 关闭之前，避免 exporter 依赖已关闭的日志/连接。 + if a.initializedTrace { + logger.Info("关闭 trace...") + if err := trace.Close(ctx); err != nil { + logger.Warnf("trace 关闭失败: %v", err) + errs = append(errs, err) + } + } + + // db/redis/logger 经 closeResources 统一关闭（M1）。注意：closeResources 仅供 + // Shutdown 路径使用；Init 失败的回滚走 failAfterInit 的 rollbackReplacedResources， + // 两者不复用同一路径（Init 失败需恢复默认 manager，Shutdown 直接关闭）。 + // 先记最后一条 "应用已优雅关闭"，再 Close（关闭后写日志会 fall back 到 nop）。 + logger.Info("关闭数据库连接/Redis/日志...") + logger.Info("应用已优雅关闭") + if err := a.closeResources(); err != nil { + errs = append(errs, err) + } + return errors.Join(errs...) +} + +// Go 启动一个受 App 生命周期管理的后台 goroutine（#22）。 +// fn 收到的 ctx 在 Shutdown 时被 cancel，fn 应在 ctx.Done() 时及时退出。 +// Shutdown/Init 失败后调用为 no-op（M1：state>=stateStopping 拒绝 wg.Add，避免与 +// Shutdown 的 wg.Wait 竞争 WaitGroup 契约——Add 由 lifecycleMu.RLock 保护 happen-before Wait）。 +func (a *App) Go(fn func(ctx context.Context)) { + if fn == nil { + return + } + a.lifecycleMu.RLock() + if a.state >= stateStopping { + a.lifecycleMu.RUnlock() + return + } + ctx := a.rootCtx + if ctx == nil { + ctx = context.Background() + } + a.wg.Add(1) + a.lifecycleMu.RUnlock() + go func() { + defer a.wg.Done() + fn(ctx) + }() +} + +// GetRegistry 获取路由注册中心（用于动态注册） +func (a *App) GetRegistry() *router.Registry { + return a.registry +} + +// GetRouter 获取 Gin Engine（用于高级自定义） +func (a *App) GetRouter() *gin.Engine { + return a.router +} + +// GetServer 获取 HTTP Server（用于高级自定义） +func (a *App) GetServer() *http.Server { + return a.server +} + +// Scheduler 返回 App 专属的 cron 调度器（Phase 3）。Init 后非 nil，用于动态注册任务 +// （app.Scheduler().AddTask(...)）。未启用 cron 或 Init 前返回 nil。 +func (a *App) Scheduler() *cron.Scheduler { + return a.scheduler +} + +// Cache 返回 App 专属的缓存服务（Phase 4）。Init 后非 nil，用于直接操作 App 的缓存 +// （绕过全局 facade，多 App 隔离场景下确保走 App 自己的 Redis）。未启用 Redis 或 Init 前返回 nil。 +func (a *App) Cache() cache.CacheService { + if a.cacheManager == nil { + return nil + } + return a.cacheManager.Get() +} + +// RedisClient 返回 App 专属的 Redis 客户端（Phase 5），用于注入到需要 redis client 的 +// 组件（如 middleware.NewRedisRateLimiter(..., middleware.WithRedisClient(app.RedisClient()))）， +// 使其走 App 的 Redis 而非全局。未启用 Redis 或 Init 前返回 nil。 +func (a *App) RedisClient() *redis.Client { + if a.redisManager == nil { + return nil + } + return a.redisManager.Client() +} + +// RateLimitRegistry 返回 App 专属的限流器 Registry（Phase 5）。New 后即非 nil，用于装配 +// app-bound 限流中间件（app.RateLimitRegistry().LoginRateLimit() 等）--此类中间件捕获 App +// 自己的 Registry，请求时不查全局默认，实现多 App per-App 计数隔离。 +func (a *App) RateLimitRegistry() *middleware.RateLimitRegistry { + return a.rateLimitRegistry +} diff --git a/app_cache_test.go b/app_cache_test.go new file mode 100644 index 0000000..499b53b --- /dev/null +++ b/app_cache_test.go @@ -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") + } +} diff --git a/app_config_test.go b/app_config_test.go new file mode 100644 index 0000000..248919a --- /dev/null +++ b/app_config_test.go @@ -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) + } +} diff --git a/app_cron_test.go b/app_cron_test.go new file mode 100644 index 0000000..269e73f --- /dev/null +++ b/app_cron_test.go @@ -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()) + } +} diff --git a/app_go_test.go b/app_go_test.go new file mode 100644 index 0000000..aff75bc --- /dev/null +++ b/app_go_test.go @@ -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") + } +} diff --git a/app_hdb1_test.go b/app_hdb1_test.go new file mode 100644 index 0000000..d58e736 --- /dev/null +++ b/app_hdb1_test.go @@ -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() +} diff --git a/app_m1_test.go b/app_m1_test.go new file mode 100644 index 0000000..3aa0c65 --- /dev/null +++ b/app_m1_test.go @@ -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) + } +} diff --git a/app_ratelimit_bound_test.go b/app_ratelimit_bound_test.go new file mode 100644 index 0000000..6b6c3da --- /dev/null +++ b/app_ratelimit_bound_test.go @@ -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") + } +} diff --git a/app_ratelimit_test.go b/app_ratelimit_test.go new file mode 100644 index 0000000..eab4257 --- /dev/null +++ b/app_ratelimit_test.go @@ -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") + } +} diff --git a/app_storage_test.go b/app_storage_test.go new file mode 100644 index 0000000..1ab8cd8 --- /dev/null +++ b/app_storage_test.go @@ -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) + } +} diff --git a/app_test.go b/app_test.go new file mode 100644 index 0000000..8f21f17 --- /dev/null +++ b/app_test.go @@ -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)") + } +} diff --git a/app_trace_test.go b/app_trace_test.go new file mode 100644 index 0000000..6815284 --- /dev/null +++ b/app_trace_test.go @@ -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) + } +} diff --git a/cache/cache.go b/cache/cache.go new file mode 100644 index 0000000..e41a9de --- /dev/null +++ b/cache/cache.go @@ -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) +} diff --git a/cache/cache_m10_internal_test.go b/cache/cache_m10_internal_test.go new file mode 100644 index 0000000..0f94ec4 --- /dev/null +++ b/cache/cache_m10_internal_test.go @@ -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) + } +} diff --git a/cache/cache_phase4_internal_test.go b/cache/cache_phase4_internal_test.go new file mode 100644 index 0000000..8b837ba --- /dev/null +++ b/cache/cache_phase4_internal_test.go @@ -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) + } +} diff --git a/cache/keybuilder.go b/cache/keybuilder.go new file mode 100644 index 0000000..969bdf8 --- /dev/null +++ b/cache/keybuilder.go @@ -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)) +} diff --git a/cache/keybuilder_m13_internal_test.go b/cache/keybuilder_m13_internal_test.go new file mode 100644 index 0000000..348b0e7 --- /dev/null +++ b/cache/keybuilder_m13_internal_test.go @@ -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) + } +} diff --git a/cache/keybuilder_test.go b/cache/keybuilder_test.go new file mode 100644 index 0000000..0ec6eb8 --- /dev/null +++ b/cache/keybuilder_test.go @@ -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 +} diff --git a/cache/lock.go b/cache/lock.go new file mode 100644 index 0000000..d358854 --- /dev/null +++ b/cache/lock.go @@ -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() +} diff --git a/cache/lock_concurrency_test.go b/cache/lock_concurrency_test.go new file mode 100644 index 0000000..6ab3b87 --- /dev/null +++ b/cache/lock_concurrency_test.go @@ -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) + } +} diff --git a/cache/lock_test.go b/cache/lock_test.go new file mode 100644 index 0000000..821b15d --- /dev/null +++ b/cache/lock_test.go @@ -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") + } +} diff --git a/cmd/xlgo/commands.go b/cmd/xlgo/commands.go new file mode 100644 index 0000000..af12bf2 --- /dev/null +++ b/cmd/xlgo/commands.go @@ -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 +} diff --git a/cmd/xlgo/commands_test.go b/cmd/xlgo/commands_test.go new file mode 100644 index 0000000..3f66992 --- /dev/null +++ b/cmd/xlgo/commands_test.go @@ -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) + } +} diff --git a/cmd/xlgo/main.go b/cmd/xlgo/main.go new file mode 100644 index 0000000..acc5b4f --- /dev/null +++ b/cmd/xlgo/main.go @@ -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() + } +} diff --git a/cmd/xlgo/templates.go b/cmd/xlgo/templates.go new file mode 100644 index 0000000..77cc370 --- /dev/null +++ b/cmd/xlgo/templates.go @@ -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) +} +`, +} diff --git a/cmd/xlgo/types.go b/cmd/xlgo/types.go new file mode 100644 index 0000000..df6bab2 --- /dev/null +++ b/cmd/xlgo/types.go @@ -0,0 +1,10 @@ +package main + +// TemplateData 模板数据 +type TemplateData struct { + Package string + Name string + NameLower string + Module string + Year int +} diff --git a/cmd/xlgo/utils.go b/cmd/xlgo/utils.go new file mode 100644 index 0000000..9d2d1c7 --- /dev/null +++ b/cmd/xlgo/utils.go @@ -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 +} diff --git a/compress/compress.go b/compress/compress.go new file mode 100644 index 0000000..1a52644 --- /dev/null +++ b/compress/compress.go @@ -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 +} diff --git a/compress/compress_security_test.go b/compress/compress_security_test.go new file mode 100644 index 0000000..fdfbe6c --- /dev/null +++ b/compress/compress_security_test.go @@ -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) + } +} diff --git a/compress/compress_test.go b/compress/compress_test.go new file mode 100644 index 0000000..61c8c94 --- /dev/null +++ b/compress/compress_test.go @@ -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) + } +} \ No newline at end of file diff --git a/config/config.go b/config/config.go new file mode 100644 index 0000000..81299a7 --- /dev/null +++ b/config/config.go @@ -0,0 +1,1161 @@ +package config + +import ( + "context" + "errors" + "fmt" + "log" + "net/url" + "path/filepath" + "runtime/debug" + "strings" + "sync" + "sync/atomic" + "time" + + "github.com/fsnotify/fsnotify" + "github.com/mitchellh/mapstructure" + "github.com/spf13/viper" +) + +// 配置错误 +var ( + // L-config-4：无格式化的哨兵错误用 errors.New（fmt.Errorf 无动词等价但语义上后者暗示格式化）。 + ErrConfigNotLoaded = errors.New("配置未加载") + ErrInvalidConfig = errors.New("配置非法") +) + +// Config 全局配置结构体 +type Config struct { + App AppConfig `mapstructure:"app"` + Server ServerConfig `mapstructure:"server"` + Database DatabaseConfig `mapstructure:"database"` + Redis RedisConfig `mapstructure:"redis"` + JWT JWTConfig `mapstructure:"jwt"` + SMS SMSConfig `mapstructure:"sms"` + Storage StorageConfig `mapstructure:"storage"` + Upload UploadConfig `mapstructure:"upload"` + Log LogConfig `mapstructure:"log"` + CORS CORSConfig `mapstructure:"cors"` + Trace TraceConfig `mapstructure:"trace"` +} + +// Clone 返回 Config 的深拷贝（M-G 修复）。 +// +// 标量字段与子结构体经结构体值拷贝独立；所有切片字段（CORS 的 4 个列表、Upload 的 2 个 +// 类型白名单、Storage.Local/OSS 上传策略的扩展名/MIME 白名单）深拷贝底层数组，使返回值 +// 可被调用方安全修改（含 append/sort/改元素）而不污染框架内部配置、不与其他读者竞态。 +// +// 用于需要可变配置副本的场景。Load/Get/回调均返回 Clone，避免调用方误改全局配置。 +func (c *Config) Clone() *Config { + if c == nil { + return nil + } + cp := *c // 浅拷贝：标量与子结构体独立，切片字段仍共享底层数组（下方逐个深拷贝） + // CORS + cp.CORS.AllowedOrigins = cloneStrings(c.CORS.AllowedOrigins) + cp.CORS.AllowedMethods = cloneStrings(c.CORS.AllowedMethods) + cp.CORS.AllowedHeaders = cloneStrings(c.CORS.AllowedHeaders) + cp.CORS.ExposedHeaders = cloneStrings(c.CORS.ExposedHeaders) + // Upload + cp.Upload.AllowedImageTypes = cloneStrings(c.Upload.AllowedImageTypes) + cp.Upload.AllowedVideoTypes = cloneStrings(c.Upload.AllowedVideoTypes) + // Storage.Local.Upload / Storage.OSS.Upload + cp.Storage.Local.Upload.AllowedExts = cloneStrings(c.Storage.Local.Upload.AllowedExts) + cp.Storage.Local.Upload.AllowedMIMEs = cloneStrings(c.Storage.Local.Upload.AllowedMIMEs) + cp.Storage.OSS.Upload.AllowedExts = cloneStrings(c.Storage.OSS.Upload.AllowedExts) + cp.Storage.OSS.Upload.AllowedMIMEs = cloneStrings(c.Storage.OSS.Upload.AllowedMIMEs) + return &cp +} + +// cloneStrings 返回字符串切片的深拷贝（nil 保持 nil 语义，避免把 nil 变成空切片）。 +func cloneStrings(s []string) []string { + if s == nil { + return nil + } + out := make([]string, len(s)) + copy(out, s) + return out +} + +func cloneStringAnyMap(in map[string]any) map[string]any { + if in == nil { + return nil + } + out := make(map[string]any, len(in)) + for k, v := range in { + out[k] = cloneAny(v) + } + return out +} + +func cloneAny(v any) any { + switch x := v.(type) { + case map[string]any: + return cloneStringAnyMap(x) + case []any: + out := make([]any, len(x)) + for i, item := range x { + out[i] = cloneAny(item) + } + return out + case []string: + return cloneStrings(x) + default: + return x + } +} + +// AppConfig 应用配置 +// 使用场景: +// - 缓存键名前缀: cache:{site_name}:user:1 +// - 日志标识: [site_a] 2024-01-01 10:00:00 ... +// - 站点追踪: Request-ID 带站点标识 +// - 分布式锁: lock:{site_name}:order:123 +type AppConfig struct { + Name string `mapstructure:"name"` // 应用名称，如 "用户管理系统" + SiteName string `mapstructure:"site_name"` // 站点别名，如 "site_a"、"user_api" + Version string `mapstructure:"version"` // 应用版本 + Env string `mapstructure:"env"` // 运行环境: dev/test/prod + Debug bool `mapstructure:"debug"` // 是否开启调试模式 + BaseURL string `mapstructure:"base_url"` // 应用基础URL +} + +// GetSiteName 获取站点别名，如果未设置则返回空字符串 +func (c *AppConfig) GetSiteName() string { + if c == nil { + return "" + } + return c.SiteName +} + +// GetCachePrefix 获取缓存键名前缀 +func (c *AppConfig) GetCachePrefix() string { + return c.GetSiteName() +} + +// IsDebug 是否调试模式 +func (c *AppConfig) IsDebug() bool { + if c == nil { + return false + } + return c.Debug +} + +// IsDev 是否开发环境 +func (c *AppConfig) IsDev() bool { + if c == nil { + return false + } + return c.Env == "dev" || c.Env == "development" +} + +// IsProd 是否生产环境 +func (c *AppConfig) IsProd() bool { + if c == nil { + return false + } + return c.Env == "prod" || c.Env == "production" +} + +// TLSConfig HTTPS/TLS 配置 +type TLSConfig struct { + Enabled bool `mapstructure:"enabled"` + CertFile string `mapstructure:"cert_file"` + KeyFile string `mapstructure:"key_file"` +} + +// ServerConfig 服务配置 +type ServerConfig struct { + Host string `mapstructure:"host"` // 绑定地址，空=监听所有接口(0.0.0.0)；"127.0.0.1"=仅本机；内网IP=绑定指定网卡 + Port int `mapstructure:"port"` + Mode string `mapstructure:"mode"` // development 或 production + ReadTimeout time.Duration `mapstructure:"read_timeout"` // 读超时，如 "15s" + WriteTimeout time.Duration `mapstructure:"write_timeout"` // 写超时，如 "30s" + IdleTimeout time.Duration `mapstructure:"idle_timeout"` // 空闲超时，如 "60s" + ShutdownTimeout time.Duration `mapstructure:"shutdown_timeout"` // 优雅关闭超时，如 "30s" + MaxHeaderBytes int `mapstructure:"max_header_bytes"` // 最大请求头字节数 + TLS TLSConfig `mapstructure:"tls"` + UnixSocket string `mapstructure:"unix_socket"` // 非空时优先于 Port，监听 unix socket + ResponseMode string `mapstructure:"response_mode"` // business(默认) 或 rest，见 response.SetMode +} + +// 默认值常量（ServerConfig 字段为零值时回退使用） +const ( + defaultReadTimeout = 15 * time.Second + defaultWriteTimeout = 30 * time.Second + defaultIdleTimeout = 60 * time.Second + defaultShutdownTimeout = 30 * time.Second + defaultMaxHeaderBytes = 1 << 20 // 1MB +) + +// EffectiveReadTimeout 返回生效的读超时（零值回退默认） +func (c ServerConfig) EffectiveReadTimeout() time.Duration { + if c.ReadTimeout > 0 { + return c.ReadTimeout + } + return defaultReadTimeout +} + +// EffectiveWriteTimeout 返回生效的写超时（零值回退默认） +func (c ServerConfig) EffectiveWriteTimeout() time.Duration { + if c.WriteTimeout > 0 { + return c.WriteTimeout + } + return defaultWriteTimeout +} + +// EffectiveIdleTimeout 返回生效的空闲超时（零值回退默认） +func (c ServerConfig) EffectiveIdleTimeout() time.Duration { + if c.IdleTimeout > 0 { + return c.IdleTimeout + } + return defaultIdleTimeout +} + +// EffectiveShutdownTimeout 返回生效的关闭超时（零值回退默认） +func (c ServerConfig) EffectiveShutdownTimeout() time.Duration { + if c.ShutdownTimeout > 0 { + return c.ShutdownTimeout + } + return defaultShutdownTimeout +} + +// EffectiveMaxHeaderBytes 返回生效的最大请求头字节数（零值回退默认） +func (c ServerConfig) EffectiveMaxHeaderBytes() int { + if c.MaxHeaderBytes > 0 { + return c.MaxHeaderBytes + } + return defaultMaxHeaderBytes +} + +// 数据库驱动常量 +const ( + DriverMySQL = "mysql" + DriverPostgres = "postgres" +) + +// MySQLTLSConfigName 是 database 包为 MySQL 私有 CA TLS 注册的命名配置名（M-config-2）。 +// 当 DatabaseConfig.TLS=true 且 TLSRootCA 非空时，MySQLDSN 追加 tls=<本常量>， +// 由 database 包在 InitDB 时通过 go-sql-driver/mysql.RegisterTLSConfig 注册自定义 *tls.Config。 +// TLS=true 但 TLSRootCA 为空时则用内置 tls=true（系统根 CA），无需注册。 +const MySQLTLSConfigName = "xlgo-mysql" + +// DSNBuilder 根据 DatabaseConfig 生成连接字符串 +type DSNBuilder func(*DatabaseConfig) string + +var ( + dsnBuildersMu sync.RWMutex + dsnBuilders = map[string]DSNBuilder{} +) + +// RegisterDSNBuilder 为指定驱动注册 DSN 构建器（驱动名大小写不敏感）。 +// aliases 用于注册同一驱动的别名，例如 postgres 的 "postgresql"、"pg"。 +// 通常由 database 包通过 database.RegisterDialect 间接调用， +// 应用代码也可直接使用以扩展自定义驱动。 +func RegisterDSNBuilder(name string, builder DSNBuilder, aliases ...string) { + if builder == nil { + return + } + dsnBuildersMu.Lock() + defer dsnBuildersMu.Unlock() + for _, n := range append([]string{name}, aliases...) { + key := strings.ToLower(strings.TrimSpace(n)) + if key != "" { + dsnBuilders[key] = builder + } + } +} + +// LookupDSNBuilder 查找已注册的 DSN 构建器 +func LookupDSNBuilder(name string) (DSNBuilder, bool) { + key := strings.ToLower(strings.TrimSpace(name)) + dsnBuildersMu.RLock() + defer dsnBuildersMu.RUnlock() + b, ok := dsnBuilders[key] + return b, ok +} + +// RegisteredDrivers 返回所有已注册 DSN 构建器的驱动名（用于诊断） +func RegisteredDrivers() []string { + dsnBuildersMu.RLock() + defer dsnBuildersMu.RUnlock() + names := make([]string, 0, len(dsnBuilders)) + for k := range dsnBuilders { + names = append(names, k) + } + return names +} + +func init() { + // 内置 MySQL / PostgreSQL 的 DSN 构建器 + RegisterDSNBuilder(DriverMySQL, func(c *DatabaseConfig) string { return c.MySQLDSN() }) + RegisterDSNBuilder(DriverPostgres, func(c *DatabaseConfig) string { return c.PostgresDSN() }, "postgresql", "pg") +} + +// DatabaseConfig 数据库配置 +type DatabaseConfig struct { + // Driver 数据库驱动，支持 mysql（默认）与 postgres + Driver string `mapstructure:"driver"` + // Host 数据库主机 + Host string `mapstructure:"host"` + // Port 数据库端口 + Port int `mapstructure:"port"` + // User 数据库用户名 + User string `mapstructure:"user"` + // Password 数据库密码 + Password string `mapstructure:"password"` + // Name 数据库名 + Name string `mapstructure:"name"` + // Timezone 连接时区。MySQL 用作 loc 参数、Postgres 用作 TimeZone 参数。 + // 空时 MySQL 默认 "Local"、Postgres 默认 "Asia/Shanghai"（向后兼容，M9）。 + Timezone string `mapstructure:"timezone"` + // CustomDSN 自定义连接字符串，设置后优先于由 Host/Port 等字段生成的 DSN + CustomDSN string `mapstructure:"dsn"` + // MaxIdleConns 最大空闲连接数 + MaxIdleConns int `mapstructure:"max_idle_conns"` + // MaxOpenConns 最大打开连接数 + MaxOpenConns int `mapstructure:"max_open_conns"` + // ConnMaxIdleTime 连接最大空闲时间，如 "5m"（#21）。0 表示用驱动默认 + ConnMaxIdleTime time.Duration `mapstructure:"conn_max_idle_time"` + // HealthCheckInterval 主库探活间隔，如 "30s"（#21）。0 表示用默认 30s + HealthCheckInterval time.Duration `mapstructure:"health_check_interval"` + // HealthCheckFailureThreshold 连续探活失败多少次标记不健康（#21）。0 表示用默认 3 + HealthCheckFailureThreshold int `mapstructure:"health_check_failure_threshold"` + // SSLMode PostgreSQL sslmode（disable/allow/prefer/require/verify-ca/verify-full）。 + // 空时默认 "prefer"（M-config-2：原硬编码 disable 已改为默认 prefer，优先加密、失败回退明文）。 + // 该字段仅对 PostgreSQL 生效；MySQL 用 TLS/TLSRootCA。 + SSLMode string `mapstructure:"ssl_mode"` + // TLS 是否对 MySQL 启用 TLS。true 时 MySQLDSN 追加 tls=true（内置：系统根 CA + 证书校验， + // ServerName 自动取自 Host）。配合 TLSRootCA 可指定私有 CA（M-config-2）。 + TLS bool `mapstructure:"tls"` + // TLSRootCA MySQL TLS 自定义 CA 证书 PEM 路径（用于私有 CA/自签证书）。 + // 非空时 MySQLDSN 改用 tls=MySQLTLSConfigName，由 database 包在 InitDB 时注册命名 TLS 配置 + // （ServerName 取自 Host）。该命名配置仅覆盖「replica DSN host 与主库 Host 相同」的单 host 集群； + // 多 host replicas + 私有 CA 时须为每个 replica host 注册不同名 TLS 配置并自建 replica DSN（框架 + // MySQLDSN 硬编码 MySQLTLSConfigName，不适用），详见 database.ensureMySQLTLSRegistered 注释。 + // 空时用内置 tls=true（系统根 CA）。仅 MySQL 生效。 + TLSRootCA string `mapstructure:"tls_root_ca"` +} + +// DSN 根据驱动返回连接字符串。设置了 CustomDSN 时优先返回 CustomDSN。 +// 未指定 Driver 时按 MySQL 处理；非空但未注册的 Driver 返回空字符串， +// 避免把拼写错误静默当作 MySQL 连接，正常加载路径会由 Validate 提前报错。 +func (c *DatabaseConfig) DSN() string { + if c == nil { // L-config-6：防御 nil receiver + return "" + } + if c.CustomDSN != "" { + return c.CustomDSN + } + driver := strings.TrimSpace(c.Driver) + if driver == "" { // L-config-5：去除原重复的 TrimSpace(driver) + driver = DriverMySQL + } + if builder, ok := LookupDSNBuilder(driver); ok { + return builder(c) + } + return "" +} + +func (c DatabaseConfig) isConfigured() bool { + return strings.TrimSpace(c.Driver) != "" || + strings.TrimSpace(c.Host) != "" || + c.Port != 0 || + strings.TrimSpace(c.User) != "" || + strings.TrimSpace(c.Password) != "" || + strings.TrimSpace(c.Name) != "" || + strings.TrimSpace(c.CustomDSN) != "" +} + +// MySQLDSN 返回 MySQL 连接字符串。 +// 密码经 url.QueryEscape 转义，避免含 @/:/空格 等特殊字符破坏 DSN（M9）。 +// loc 由 Timezone 配置，空则默认 "Local"（向后兼容）。 +// TLS=true 时追加 tls 参数（M-config-2）：TLSRootCA 为空用内置 tls=true（系统根 CA + 证书校验）； +// TLSRootCA 非空用 tls=MySQLTLSConfigName（database 包注册的私有 CA 命名配置）。 +func (c *DatabaseConfig) MySQLDSN() string { + if c == nil { // L-config-6 + return "" + } + loc := c.Timezone + if loc == "" { + loc = "Local" + } + dsn := fmt.Sprintf("%s:%s@tcp(%s:%d)/%s?charset=utf8mb4&parseTime=True&loc=%s", + url.QueryEscape(c.User), url.QueryEscape(c.Password), c.Host, c.Port, url.PathEscape(c.Name), url.QueryEscape(loc)) + if c.TLS { + if strings.TrimSpace(c.TLSRootCA) == "" { + dsn += "&tls=true" + } else { + dsn += "&tls=" + MySQLTLSConfigName + } + } + return dsn +} + +// PostgresDSN 返回 PostgreSQL 连接字符串。 +// 字符串字段统一用单引号包裹并转义，避免含空格/引号/反斜杠破坏 key=value DSN。 +// TimeZone 由 Timezone 配置，空则默认 "Asia/Shanghai"（向后兼容）。 +// sslmode 由 SSLMode 配置，空则默认 "prefer"（M-config-2：原硬编码 disable 改为 prefer，优先加密）。 +func (c *DatabaseConfig) PostgresDSN() string { + if c == nil { // L-config-6 + return "" + } + tz := c.Timezone + if tz == "" { + tz = "Asia/Shanghai" + } + sslmode := strings.TrimSpace(c.SSLMode) + if sslmode == "" { + sslmode = "prefer" + } + // sslmode 不加引号（与原 sslmode=disable 格式一致）；SSLMode 已被 Validate 限定为固定枚举，无注入风险。 + return fmt.Sprintf("host=%s port=%d user=%s password=%s dbname=%s sslmode=%s TimeZone=%s", + postgresQuote(c.Host), c.Port, postgresQuote(c.User), postgresQuote(c.Password), postgresQuote(c.Name), sslmode, postgresQuote(tz)) +} + +func postgresQuote(s string) string { + s = strings.ReplaceAll(s, `\`, `\\`) + s = strings.ReplaceAll(s, `'`, `\'`) + return "'" + s + "'" +} + +// RedisConfig Redis 配置 +type RedisConfig struct { + Host string `mapstructure:"host"` + Port int `mapstructure:"port"` + Password string `mapstructure:"password"` + DB int `mapstructure:"db"` +} + +// Addr 返回 Redis 地址 +func (c *RedisConfig) Addr() string { + if c == nil { // L-config-6 + return "" + } + return fmt.Sprintf("%s:%d", c.Host, c.Port) +} + +// JWTConfig JWT 配置 +type JWTConfig struct { + Secret string `mapstructure:"secret"` + Expire time.Duration `mapstructure:"expire"` // 过期时间，如 "24h"（time.Duration） + RefreshExpire time.Duration `mapstructure:"refresh_expire"` // 刷新 token 过期时间，如 "168h" + Issuer string `mapstructure:"issuer"` // 签发者 + Algorithm string `mapstructure:"algorithm"` // 签名算法：HS256(默认)/HS384/HS512；非 HMAC 算法（如 RS256）会被 jwt.signingMethod 拒绝（ErrUnsupportedAlgorithm） +} + +// SMSConfig 短信配置 +type SMSConfig struct { + Enabled bool `mapstructure:"enabled"` + Provider string `mapstructure:"provider"` + AccessKeyID string `mapstructure:"access_key_id"` + AccessKeySecret string `mapstructure:"access_key_secret"` + SignName string `mapstructure:"sign_name"` + TemplateCode string `mapstructure:"template_code"` +} + +// StorageConfig 文件存储配置 +type StorageConfig struct { + Driver string `mapstructure:"driver"` // local 或 oss + Local LocalStorageConfig `mapstructure:"local"` + OSS OSSStorageConfig `mapstructure:"oss"` +} + +// UploadPolicy 上传安全策略（C4b）。零值表示不限制，向后兼容； +// 生产环境强烈建议显式配置 MaxSizeBytes 与 AllowedExts / AllowedMIMEs。 +type UploadPolicy struct { + // MaxSizeBytes 单文件大小上限（字节）。0 = 不限制。 + MaxSizeBytes int64 `mapstructure:"max_size_bytes"` + // AllowedExts 允许的扩展名白名单（小写、含点，如 ".jpg"）。空 = 不限制。 + AllowedExts []string `mapstructure:"allowed_exts"` + // AllowedMIMEs 允许的 MIME 类型白名单（小写，如 "image/jpeg"）。 + // 非空时用 http.DetectContentType 嗅探文件前 512 字节校验。空 = 不嗅探。 + AllowedMIMEs []string `mapstructure:"allowed_mime_types"` +} + +// LocalStorageConfig 本地存储配置 +type LocalStorageConfig struct { + Path string `mapstructure:"path"` + BaseURL string `mapstructure:"base_url"` + // Upload 上传安全策略（可选，零值不限制）。 + Upload UploadPolicy `mapstructure:"upload"` + // MaxReadBytes Get 读取单文件上限（字节）。0 = 默认 100MB，-1 = 不限制。 + MaxReadBytes int64 `mapstructure:"max_read_bytes"` +} + +// OSSStorageConfig OSS 存储配置 +type OSSStorageConfig struct { + Endpoint string `mapstructure:"endpoint"` + Bucket string `mapstructure:"bucket"` + AccessKeyID string `mapstructure:"access_key_id"` + AccessKeySecret string `mapstructure:"access_key_secret"` + BaseURL string `mapstructure:"base_url"` + // Upload 上传安全策略（可选，零值不限制）。 + Upload UploadPolicy `mapstructure:"upload"` + // MaxReadBytes Get 读取单文件上限（字节）。0 = 默认 100MB，-1 = 不限制。 + MaxReadBytes int64 `mapstructure:"max_read_bytes"` +} + +// LogConfig 日志配置 +type LogConfig struct { + Dir string `mapstructure:"dir"` + MaxSize int `mapstructure:"max_size"` // MB + MaxBackups int `mapstructure:"max_backups"` + MaxAge int `mapstructure:"max_age"` // 天 + Compress bool `mapstructure:"compress"` +} + +// UploadConfig 上传配置 +type UploadConfig struct { + MaxFileSize int `mapstructure:"max_file_size"` // 最大图片大小（MB） + MaxVideoSize int `mapstructure:"max_video_size"` // 最大视频大小（MB） + MaxAvatarSize int `mapstructure:"max_avatar_size"` // 最大头像大小（MB） + AllowedImageTypes []string `mapstructure:"allowed_image_types"` // 允许的图片 MIME 类型 + AllowedVideoTypes []string `mapstructure:"allowed_video_types"` // 允许的视频 MIME 类型 +} + +// CORSConfig CORS 跨域配置 +type CORSConfig struct { + AllowedOrigins []string `mapstructure:"allowed_origins"` // 允许的域名列表 + AllowedMethods []string `mapstructure:"allowed_methods"` // 允许的方法 + AllowedHeaders []string `mapstructure:"allowed_headers"` // 允许的请求头 + ExposedHeaders []string `mapstructure:"exposed_headers"` // 暴露的响应头 + AllowCredentials bool `mapstructure:"allow_credentials"` // 是否允许携带凭证 + MaxAge int `mapstructure:"max_age"` // 预检请求缓存时间（秒） +} + +// TraceConfig 链路追踪配置（OpenTelemetry）。由 App 在 WithTrace 时读取并调 trace.Init。 +// +// 语义说明：OTel 的 TracerProvider / TextMapPropagator 本身是进程级全局单例 +// （otel.SetTracerProvider 全局生效），故 trace 不做 per-App 实例隔离--多 App 进程 +// 共享同一 OTel 全局状态，这与 OTel 自身设计一致。App 仅负责把 trace 纳入生命周期 +// （Init/Close）与装入 Middleware，不提供实例隔离。 +// +// Enabled=false（默认）时 trace.Init 安装 Noop tracer，Middleware 不 panic、不导出。 +type TraceConfig struct { + ServiceName string `mapstructure:"service_name"` // 服务名（空则回退 cfg.App.Name） + ServiceVersion string `mapstructure:"service_version"` // 服务版本 + Environment string `mapstructure:"environment"` // 运行环境 + ExporterType string `mapstructure:"exporter_type"` // otlp-http(默认) / otlp-grpc / stdout + Endpoint string `mapstructure:"endpoint"` // OTLP collector 地址 + Insecure bool `mapstructure:"insecure"` // 明文（无 TLS）连接 collector + SampleRatio float64 `mapstructure:"sample_ratio"` // 采样比例 0.0-1.0 + Enabled bool `mapstructure:"enabled"` // 是否启用导出 + Propagator string `mapstructure:"propagator"` // w3c(默认) / b3 / jaeger +} + +// GetAllowedOrigins 获取允许的域名列表 +func (c *CORSConfig) GetAllowedOrigins() []string { + if c == nil || len(c.AllowedOrigins) == 0 { + return []string{} + } + return c.AllowedOrigins +} + +// GetAllowedMethods 获取允许的方法列表 +func (c *CORSConfig) GetAllowedMethods() []string { + if c == nil || len(c.AllowedMethods) == 0 { + return []string{"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"} + } + return c.AllowedMethods +} + +// GetAllowedHeaders 获取允许的请求头列表 +func (c *CORSConfig) GetAllowedHeaders() []string { + if c == nil || len(c.AllowedHeaders) == 0 { + return []string{"Origin", "Content-Type", "Content-Length", "Accept-Encoding", "X-CSRF-Token", "Authorization", "X-Requested-With"} + } + return c.AllowedHeaders +} + +// GetExposedHeaders 获取暴露的响应头列表 +func (c *CORSConfig) GetExposedHeaders() []string { + if c == nil || len(c.ExposedHeaders) == 0 { + return []string{"Content-Length", "Access-Control-Allow-Origin", "Access-Control-Allow-Headers", "Content-Type"} + } + return c.ExposedHeaders +} + +// GetMaxAge 获取预检请求缓存时间 +func (c *CORSConfig) GetMaxAge() int { + if c == nil || c.MaxAge <= 0 { + return 86400 // 默认 24 小时 + } + return c.MaxAge +} + +// Manager 配置管理器 +type Manager struct { + mu sync.RWMutex + path string + v *viper.Viper + cfg *Config + callbacks []func(*Config) + // watcher 是自管的 fsnotify 监听器（C10d）。nil 表示未启用文件监听。 + // 由 StartWatcher 创建、StopWatcher 关闭，避免依赖 viper 内部无法停止的 watcher。 + watcher *fsnotify.Watcher + // watchDone 在监听 goroutine 退出时被 close，供 StopWatcher 等待退出确认。 + watchDone chan struct{} + // watchCancel 取消 watchLoop 的 ctx（L-config-2）。watchLoop 同时监听 ctx.Done 与 w.Events， + // 提供 fsnotify 致命错误且 Events 未关闭时的逃生通道，避免监听 goroutine 永驻。 + // StopWatcher 时 cancel + Close(w) 双重退出保障。 + watchCancel context.CancelFunc +} + +// defaultManager 是包级默认管理器（C10a）。改用 atomic.Pointer 保护读写， +// 消除原裸指针置换与请求 goroutine 无锁读之间的数据竞争。 +var defaultManager atomic.Pointer[Manager] + +func init() { + defaultManager.Store(NewManager("")) +} + +// NewManager 创建配置管理器 +func NewManager(configPath string) *Manager { + return &Manager{path: configPath} +} + +func newViper(configPath string) *viper.Viper { + v := viper.New() + v.SetConfigFile(configPath) + v.SetEnvKeyReplacer(strings.NewReplacer(".", "_")) + v.AutomaticEnv() + return v +} + +func cloneViper(src *viper.Viper, configPath string) *viper.Viper { + if src == nil { + return nil + } + cp := newViper(configPath) + if err := cp.MergeConfigMap(src.AllSettings()); err != nil { + return nil + } + return cp +} + +// configToMap 将 *Config 按 mapstructure tag 转为嵌套 map[string]any（H-config-1）。 +// mapstructure struct->map 会递归嵌套结构体为 map，切片/map 字段原样保留， +// 用于在 Set(cfg) 后重建 m.v，使 GetString/GetInt/GetBool/GetViper 与 Get() 读到同一配置。 +func configToMap(cfg *Config) map[string]any { + if cfg == nil { + return nil + } + out := map[string]any{} + if err := mapstructure.Decode(cfg, &out); err != nil { + return nil + } + return out +} + +// viperFromConfig 由 *Config 重建一个不含 AutomaticEnv 的 viper（H-config-1）。 +// 用于 Set(cfg) 后同步 m.v：不启用 AutomaticEnv 是为了确保 GetString 等只读取 cfg 派生的值， +// 与 Get()（返回 m.cfg 即调用方传入的 cfg）严格同源，避免 env 覆盖造成二者的二次分裂。 +// 保留 SetConfigFile(m.path) 以便后续 Reload 从文件重读。 +// +// 已知差异（Duration 字段）：mapstructure struct->map 将 time.Duration 原样保留为 time.Duration， +// 故 GetString("jwt.expire") 在 Set 后返回 Duration.String() 格式（如 "24h0m0s"），与文件加载路径 +// 返回的原始字符串（如 "24h"）字面不同。二者语义一致（均可 ParseDuration），typed view（Get().JWT.Expire） +// 与 GetDuration 在两条路径下完全一致。Duration 字段应经 typed view 或 GetDuration 读取，勿用 GetString 字面比较。 +func viperFromConfig(configPath string, cfg *Config) *viper.Viper { + v := viper.New() + v.SetConfigFile(configPath) + if m := configToMap(cfg); m != nil { + _ = v.MergeConfigMap(m) + } + return v +} + +// unmarshalConfig 将 viper 解析到 Config，启用 string→time.Duration decode hook， +// 使 ServerConfig/JWTConfig 的 Duration 字段可写 "24h"/"15s" 等字符串。 +func unmarshalConfig(v *viper.Viper, cfg *Config) error { + return v.Unmarshal(cfg, viper.DecodeHook(mapstructure.StringToTimeDurationHookFunc())) +} + +// Load 加载配置文件 +func (m *Manager) Load() (*Config, error) { + if m == nil || m.path == "" { + return nil, ErrConfigNotLoaded + } + + v := newViper(m.path) + if err := v.ReadInConfig(); err != nil { + return nil, fmt.Errorf("读取配置文件失败: %w", err) + } + + var cfg Config + if err := unmarshalConfig(v, &cfg); err != nil { + return nil, fmt.Errorf("解析配置文件失败: %w", err) + } + if err := cfg.Validate(); err != nil { + return nil, err + } + + m.mu.Lock() + m.v = v + m.cfg = &cfg + m.mu.Unlock() + + // M-G 修复：返回深拷贝（Clone），标量与切片字段均独立，调用方可安全修改。 + // 原"防御性拷贝"为浅拷贝（out := cfg）——切片字段（CORS.AllowedOrigins 等）仍与 + // 内部 m.cfg 共享底层数组，调用方 append/sort/改元素会污染全局并与其他读者竞态。 + // 内部 m.cfg 保留独立的 &cfg，不受返回值修改影响。 + return cfg.Clone(), nil +} + +// LoadWithWatch 加载配置文件并启用热更新 +func (m *Manager) LoadWithWatch(onChange func(*Config)) (*Config, error) { + cfg, err := m.Load() + if err != nil { + return nil, err + } + if onChange != nil { + m.RegisterCallback(onChange) + } + if err := m.StartWatcher(); err != nil { + return nil, fmt.Errorf("启动配置监听失败: %w", err) + } + return cfg, nil +} + +// RegisterCallback 注册配置变更回调 +func (m *Manager) RegisterCallback(cb func(*Config)) { + if m == nil || cb == nil { + return + } + m.mu.Lock() + defer m.mu.Unlock() + m.callbacks = append(m.callbacks, cb) +} + +// StartWatcher 启动配置文件监听。使用自管的 fsnotify.Watcher（监听配置文件 +// 所在目录以兼容编辑器改写/k8s ConfigMap 原子替换），文件变更时去抖后重新加载。 +// 幂等：重复调用不会创建多个监听 goroutine。 +func (m *Manager) StartWatcher() error { + if m == nil { + return ErrConfigNotLoaded + } + + m.mu.Lock() + if m.watcher != nil { + // 已在监听，幂等返回 + m.mu.Unlock() + return nil + } + if m.v == nil || m.path == "" { + m.mu.Unlock() + return ErrConfigNotLoaded + } + w, err := fsnotify.NewWatcher() + if err != nil { + m.mu.Unlock() + return fmt.Errorf("创建文件监听失败: %w", err) + } + // 监听父目录而非文件本身：vim/k8s 等通过"写临时文件 + rename"替换配置， + // 直接监听文件会在 rename 后丢失。监听目录并按文件名过滤更稳健。 + dir := filepath.Dir(m.path) + if err := w.Add(dir); err != nil { + m.mu.Unlock() + _ = w.Close() + return fmt.Errorf("监听配置目录失败: %w", err) + } + m.watcher = w + m.watchDone = make(chan struct{}) + // L-config-2：为 watchLoop 创建可取消 ctx，作为 w.Events 关闭之外的逃生通道。 + ctx, cancel := context.WithCancel(context.Background()) + m.watchCancel = cancel + target := filepath.Base(m.path) + done := m.watchDone + m.mu.Unlock() + + go m.watchLoop(ctx, w, target, done) + return nil +} + +// watchLoop 是文件监听 goroutine 主体。文件变更经去抖后调用 reload； +// watcher 被 Close（Events 通道关闭）或 ctx 被 cancel（L-config-2）时退出并 close done。 +// done 与 ctx 均由 StartWatcher 在锁内捕获传入，避免本 goroutine 读取 m.watchDone / +// m.watchCancel 字段与 StopWatcher 写入竞争。ctx 提供 fsnotify 致命错误下的逃生通道。 +func (m *Manager) watchLoop(ctx context.Context, w *fsnotify.Watcher, target string, done chan struct{}) { + defer close(done) + const debounce = 200 * time.Millisecond + timer := time.NewTimer(time.Hour) + if !timer.Stop() { + <-timer.C + } + defer timer.Stop() + var timerC <-chan time.Time + for { + select { + case <-ctx.Done(): // L-config-2：StopWatcher cancel 时退出，不单靠 w.Events 关闭 + return + case ev, ok := <-w.Events: + if !ok { + return + } + if filepath.Base(ev.Name) != target { + continue + } + if !ev.Has(fsnotify.Create) && !ev.Has(fsnotify.Write) && + !ev.Has(fsnotify.Remove) && !ev.Has(fsnotify.Rename) { + continue + } + // 去抖：合并编辑器/工具的连续写事件，仅最后一次触发重载。 + if !timer.Stop() && timerC != nil { + select { + case <-timer.C: + default: + } + } + timer.Reset(debounce) + timerC = timer.C + case _, ok := <-w.Errors: + if !ok { + return + } + // 非致命错误：继续监听。 + case <-timerC: + timerC = nil + // reload 内部对非法配置保留旧配置（C10b），错误被忽略—— + // 监听路径无法向上传播错误，保留旧配置即正确语义。 + _ = m.reload() + } + } +} + +// StopWatcher 停止配置文件监听并释放 watcher（C10d）。幂等。 +// cancel ctx 与关闭 fsnotify watcher 双重退出（L-config-2），等待 watchDone 确认 goroutine 退出。 +func (m *Manager) StopWatcher() { + if m == nil { + return + } + m.mu.Lock() + w := m.watcher + done := m.watchDone + cancel := m.watchCancel + m.watcher = nil + m.watchDone = nil + m.watchCancel = nil + m.mu.Unlock() + if cancel != nil { + cancel() // L-config-2：先 cancel 让 watchLoop 经 ctx.Done 退出 + } + if w == nil { + return + } + _ = w.Close() // 再 Close watcher 让 w.Events 关闭，双重保障 + if done != nil { + <-done + } +} + +// Get 获取配置副本。返回值可由调用方自由修改，不会污染 Manager 内部配置。 +func (m *Manager) Get() *Config { + if m == nil { + return nil + } + m.mu.RLock() + defer m.mu.RUnlock() + return m.cfg.Clone() +} + +// GetViper 获取 viper 的只读快照。 +// +// 返回值不是 Manager 内部 viper 指针；调用方修改该快照不会影响全局配置。 +// 需要扩展配置读取时优先使用 GetString/GetInt/GetBool 等包级 helper。 +func (m *Manager) GetViper() *viper.Viper { + if m == nil { + return nil + } + m.mu.RLock() + defer m.mu.RUnlock() + return cloneViper(m.v, m.path) +} + +// GetString 获取字符串配置。 +func (m *Manager) GetString(key string) string { + if m == nil { + return "" + } + m.mu.RLock() + defer m.mu.RUnlock() + if m.v == nil { + return "" + } + return m.v.GetString(key) +} + +// GetInt 获取整数配置。 +func (m *Manager) GetInt(key string) int { + if m == nil { + return 0 + } + m.mu.RLock() + defer m.mu.RUnlock() + if m.v == nil { + return 0 + } + return m.v.GetInt(key) +} + +// GetBool 获取布尔配置。 +func (m *Manager) GetBool(key string) bool { + if m == nil { + return false + } + m.mu.RLock() + defer m.mu.RUnlock() + if m.v == nil { + return false + } + return m.v.GetBool(key) +} + +// GetStringMap 获取字符串映射配置副本。 +func (m *Manager) GetStringMap(key string) map[string]any { + if m == nil { + return nil + } + m.mu.RLock() + defer m.mu.RUnlock() + if m.v == nil { + return nil + } + return cloneStringAnyMap(m.v.GetStringMap(key)) +} + +// Set 手动设置配置。非 nil 配置会先 Validate，并以深拷贝形式保存。 +// H-config-1：非 nil 配置同时用其重建 m.v（不含 AutomaticEnv），使 Get() 与 +// GetString/GetInt/GetBool/GetViper 读到同一配置世界，消除原"Set 只更新类型化视图、 +// viper 视图停留在旧值"的静默分裂（违反 C1 单一配置源）。 +func (m *Manager) Set(cfg *Config) error { + if m == nil { + return ErrConfigNotLoaded + } + if cfg != nil { + if err := cfg.Validate(); err != nil { + return errors.Join(ErrInvalidConfig, err) + } + } + m.mu.Lock() + defer m.mu.Unlock() + m.cfg = cfg.Clone() + if cfg == nil { + m.v = nil + } else { + m.v = viperFromConfig(m.path, cfg) + } + return nil +} + +// Reload 重新加载配置文件。读取、解析、校验（C10b）任一步失败均保留旧配置并返回错误； +// 仅当新配置通过 Validate 后才替换 m.cfg 并触发回调。 +func (m *Manager) Reload() error { + if m == nil { + return ErrConfigNotLoaded + } + return m.reload() +} + +// reload 是 Reload 与文件监听共享的重载实现。全程持写锁以串行化对 viper 的 +// ReadInConfig 访问（viper 非完全并发安全），并在替换前强制 Validate（C10b）。 +func (m *Manager) reload() error { + m.mu.Lock() + v := m.v + if v == nil { + m.mu.Unlock() + return ErrConfigNotLoaded + } + if err := v.ReadInConfig(); err != nil { + m.mu.Unlock() + return fmt.Errorf("读取配置文件失败: %w", err) + } + var newCfg Config + if err := unmarshalConfig(v, &newCfg); err != nil { + m.mu.Unlock() + return fmt.Errorf("解析配置文件失败: %w", err) + } + if err := newCfg.Validate(); err != nil { + // 非法配置保留旧配置，不得静默发布（C10b） + m.mu.Unlock() + return err + } + m.cfg = &newCfg + cbs := make([]func(*Config), len(m.callbacks)) + copy(cbs, m.callbacks) + m.mu.Unlock() + + // M-G：回调传入 newCfg 的深拷贝，避免回调修改切片字段与 Get() 读者（持有 &newCfg）竞态。 + // 回调为 onChange 通知语义，应观察而非改写配置；改写副本不影响内部 m.cfg。 + // M-config-1：每个回调独立 recover，单个回调 panic 不得杀掉 watcher 或阻断后续回调。 + // config 是叶子包（logger 依赖 config），不能用框架 zap，故用标准库 log 记录 + 堆栈。 + for _, cb := range cbs { + func(cb func(*Config)) { + defer func() { + if r := recover(); r != nil { + log.Printf("config: 配置变更回调 panic（已隔离，继续后续回调）: %v\n%s", r, debug.Stack()) + } + }() + cb(newCfg.Clone()) + }(cb) + } + return nil +} + +// pkgLoadMu 串行化包级 Load/LoadWithWatch 对 defaultManager 的"停旧 watcher → 建新 → 置换" +// 序列（P1 #8）。原实现该序列非原子：两个 goroutine 并发调用可能都读到 old、都 StopWatcher、 +// 都 Store，遗留一个已 StartWatcher 的 manager 无引用可停（goroutine 泄漏）。 +var pkgLoadMu sync.Mutex + +// Load 加载配置文件。 +// P1 #8：全程持 pkgLoadMu 串行化。新配置加载成功后才替换默认 Manager 并停止旧 watcher； +// 加载失败会保留旧 Manager 与旧 watcher，避免一次错误配置导致热更新链路断掉。 +func Load(configPath string) (*Config, error) { + pkgLoadMu.Lock() + defer pkgLoadMu.Unlock() + m := NewManager(configPath) + cfg, err := m.Load() + if err != nil { + return nil, err + } + old := defaultManager.Load() + defaultManager.Store(m) + if old != nil && old != m { + old.StopWatcher() + } + return cfg, nil +} + +// LoadWithWatch 加载配置文件并启用热更新。 +// P1 #8：全程持 pkgLoadMu 串行化，且新 manager 在其 watcher 成功启动后才置换为默认； +// 启动失败则保留旧 Manager 与旧 watcher，并停掉新 manager 可能半启动的 watcher。 +func LoadWithWatch(configPath string, onChange func(*Config)) (*Config, error) { + pkgLoadMu.Lock() + defer pkgLoadMu.Unlock() + m := NewManager(configPath) + cfg, err := m.LoadWithWatch(onChange) + if err != nil { + m.StopWatcher() // 清理可能已半启动的 watcher，避免孤儿 goroutine + return nil, err + } + old := defaultManager.Load() + defaultManager.Store(m) + if old != nil && old != m { + old.StopWatcher() + } + return cfg, nil +} + +// RegisterCallback 注册配置变更回调 +func RegisterCallback(cb func(*Config)) { + defaultManager.Load().RegisterCallback(cb) +} + +// StartWatcher 启动配置文件监听 +func StartWatcher() error { + return defaultManager.Load().StartWatcher() +} + +// StopWatcher 停止配置文件监听 +func StopWatcher() { + defaultManager.Load().StopWatcher() +} + +// Get 获取全局配置 +func Get() *Config { + return defaultManager.Load().Get() +} + +// GetViper 获取 viper 实例（用于扩展配置） +func GetViper() *viper.Viper { + return defaultManager.Load().GetViper() +} + +// Set 手动设置配置（用于测试或动态修改）。非 nil 配置会先校验并复制。 +func Set(cfg *Config) error { + return defaultManager.Load().Set(cfg) +} + +// Reload 重新加载配置文件 +func Reload() error { + return defaultManager.Load().Reload() +} + +// SetDefaultManager 替换全局默认配置管理器。 +// 主要供应用层（如 App）在持有自己的 Manager 时使用， +// 使 config.Get / config.GetString 等便捷函数仍然能取到正确的配置。 +// 传入 nil 表示重置为空管理器。 +// +// C10a：经 atomic.Pointer.Store 原子置换，消除与并发读取（Get 等）的数据竞争。 +// 置换后会停止旧 Manager 的 watcher，避免全局默认 manager 切换后遗留热更新 goroutine。 +func SetDefaultManager(m *Manager) { + old := defaultManager.Load() + if m == nil { + m = NewManager("") + } + defaultManager.Store(m) + if old != nil && old != m { + old.StopWatcher() + } +} + +// GetString 获取字符串配置 +func GetString(key string) string { + return defaultManager.Load().GetString(key) +} + +// GetInt 获取整数配置 +func GetInt(key string) int { + return defaultManager.Load().GetInt(key) +} + +// GetBool 获取布尔配置 +func GetBool(key string) bool { + return defaultManager.Load().GetBool(key) +} + +// GetStringMap 获取字符串映射配置 +func GetStringMap(key string) map[string]any { + return defaultManager.Load().GetStringMap(key) +} + +// IsDevelopment 是否开发环境 +func (c *Config) IsDevelopment() bool { + if c == nil { + return false + } + // 优先使用 App.Env + if c.App.Env != "" { + return c.App.IsDev() + } + return c.Server.Mode == "development" +} + +// IsProduction 是否生产环境 +func (c *Config) IsProduction() bool { + if c == nil { + return false + } + // 优先使用 App.Env + if c.App.Env != "" { + return c.App.IsProd() + } + return c.Server.Mode == "production" +} + +// GetAppName 获取应用名称 +func (c *Config) GetAppName() string { + if c == nil { + return "" + } + return c.App.Name +} + +// GetSiteName 获取站点别名 +func (c *Config) GetSiteName() string { + if c == nil { + return "" + } + return c.App.GetSiteName() +} diff --git a/config/config_c10_test.go b/config/config_c10_test.go new file mode 100644 index 0000000..9554a04 --- /dev/null +++ b/config/config_c10_test.go @@ -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) + } +} diff --git a/config/config_fix_test.go b/config/config_fix_test.go new file mode 100644 index 0000000..06603d1 --- /dev/null +++ b/config/config_fix_test.go @@ -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"}, + }, + }, + }, + } +} diff --git a/config/config_test.go b/config/config_test.go new file mode 100644 index 0000000..bef5051 --- /dev/null +++ b/config/config_test.go @@ -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") + } +} diff --git a/config/validate.go b/config/validate.go new file mode 100644 index 0000000..6011c7b --- /dev/null +++ b/config/validate.go @@ -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 +} diff --git a/config/validate_test.go b/config/validate_test.go new file mode 100644 index 0000000..863e05f --- /dev/null +++ b/config/validate_test.go @@ -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) + } +} diff --git a/console/console.go b/console/console.go new file mode 100644 index 0000000..5891e51 --- /dev/null +++ b/console/console.go @@ -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...) +} diff --git a/console/console_test.go b/console/console_test.go new file mode 100644 index 0000000..3f445c2 --- /dev/null +++ b/console/console_test.go @@ -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) + } + } +} diff --git a/console/console_unix.go b/console/console_unix.go new file mode 100644 index 0000000..11b7eb0 --- /dev/null +++ b/console/console_unix.go @@ -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) +} diff --git a/console/console_windows.go b/console/console_windows.go new file mode 100644 index 0000000..baa4b2d --- /dev/null +++ b/console/console_windows.go @@ -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)) diff --git a/cron/cron.go b/cron/cron.go new file mode 100644 index 0000000..a5a8fb1 --- /dev/null +++ b/cron/cron.go @@ -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 +} diff --git a/cron/cron_c12_internal_test.go b/cron/cron_c12_internal_test.go new file mode 100644 index 0000000..7965bb0 --- /dev/null +++ b/cron/cron_c12_internal_test.go @@ -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) + } + } +} diff --git a/cron/cron_c12_test.go b/cron/cron_c12_test.go new file mode 100644 index 0000000..c514fd9 --- /dev/null +++ b/cron/cron_c12_test.go @@ -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) + } +} diff --git a/cron/cron_m13_internal_test.go b/cron/cron_m13_internal_test.go new file mode 100644 index 0000000..6cfa41c --- /dev/null +++ b/cron/cron_m13_internal_test.go @@ -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) + } +} diff --git a/cron/cron_test.go b/cron/cron_test.go new file mode 100644 index 0000000..b22881e --- /dev/null +++ b/cron/cron_test.go @@ -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) + } +} diff --git a/database/dialect.go b/database/dialect.go new file mode 100644 index 0000000..b609649 --- /dev/null +++ b/database/dialect.go @@ -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() }, + }) +} diff --git a/database/manager.go b/database/manager.go new file mode 100644 index 0000000..86f4bab --- /dev/null +++ b/database/manager.go @@ -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= 生效。 + // 失败 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) +} diff --git a/database/manager_c11_internal_test.go b/database/manager_c11_internal_test.go new file mode 100644 index 0000000..9e12e53 --- /dev/null +++ b/database/manager_c11_internal_test.go @@ -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 未返回") + } +} diff --git a/database/manager_hdb1_internal_test.go b/database/manager_hdb1_internal_test.go new file mode 100644 index 0000000..e107170 --- /dev/null +++ b/database/manager_hdb1_internal_test.go @@ -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") + } +} diff --git a/database/manager_test.go b/database/manager_test.go new file mode 100644 index 0000000..935f406 --- /dev/null +++ b/database/manager_test.go @@ -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) + } + } +} diff --git a/database/redis.go b/database/redis.go new file mode 100644 index 0000000..13b7fa5 --- /dev/null +++ b/database/redis.go @@ -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) +} diff --git a/database/redis_hdb1_internal_test.go b/database/redis_hdb1_internal_test.go new file mode 100644 index 0000000..b00dec9 --- /dev/null +++ b/database/redis_hdb1_internal_test.go @@ -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) +} diff --git a/database/redis_internal_test.go b/database/redis_internal_test.go new file mode 100644 index 0000000..cd12b17 --- /dev/null +++ b/database/redis_internal_test.go @@ -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，旧资源需可用于失败回滚") + } +} diff --git a/database/redis_manager_internal_test.go b/database/redis_manager_internal_test.go new file mode 100644 index 0000000..62627d9 --- /dev/null +++ b/database/redis_manager_internal_test.go @@ -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") + } +} diff --git a/database/redis_test.go b/database/redis_test.go new file mode 100644 index 0000000..d8f8683 --- /dev/null +++ b/database/redis_test.go @@ -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() +} diff --git a/database/retry_internal_test.go b/database/retry_internal_test.go new file mode 100644 index 0000000..9310873 --- /dev/null +++ b/database/retry_internal_test.go @@ -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) + } + }) + } +} diff --git a/database/tls.go b/database/tls.go new file mode 100644 index 0000000..fc05376 --- /dev/null +++ b/database/tls.go @@ -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=：引用经 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 +} diff --git a/database/tls_internal_test.go b/database/tls_internal_test.go new file mode 100644 index 0000000..f32d2b0 --- /dev/null +++ b/database/tls_internal_test.go @@ -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) + } +} diff --git a/docs/plans/Version_Update_Plan_v1.0.2.md b/docs/plans/Version_Update_Plan_v1.0.2.md new file mode 100644 index 0000000..d96650d --- /dev/null +++ b/docs/plans/Version_Update_Plan_v1.0.2.md @@ -0,0 +1,1047 @@ +# xlgo v1.0.2 更新计划 + +> 版本定位：面向新框架的激进整理版本。由于当前框架仍处于早期阶段，v1.0.2 不以保守兼容为首要目标，而是优先修正已经发现的架构边界、默认行为、文档一致性和长期演进风险，避免在用户规模扩大后再进行破坏式调整。 + +## 0. 实施状态（2026-06-20） + +✅ **本计划全部 11 项已完成。** + +| 节 | 任务 | 状态 | 主要落点 | +|---|---|---|---| +| 2.1 | 权限中间件去业务化 | ✅ | `middleware/auth.go`、`middleware/auth_test.go` | +| 2.2 | App 启动流程可组合 | ✅ | `app.go`（Option 全套 + `enableAutoMigrate`）、`app_test.go` | +| 2.3 | 框架内部禁止 Fatalf 退出 | ✅ | `app.go` 全部 `return fmt.Errorf(...)` | +| 2.4 | Shutdown 关闭流程修正 | ✅ | `app.go` 使用 `database.CloseAll()` + `errors.Join` | +| 2.5 | 默认路由和 Swagger 可控化 | ✅ | `router/router.go`（`RegisterHealthRoute` / `RegisterSwaggerRoutes`） | +| 2.6 | 健康检查标准化 | ✅ | `/health` 支持 checks + 503，`router/health_test.go` | +| 2.7 | 配置系统 | ✅ | `config.Manager` + `config.SetDefaultManager`，App 真正驱动私有 manager | +| 2.8 | 数据库全局状态治理 | ✅ | `database.Manager`、`ReplicaPicker`、私有 `dbModeContextKey{}`、可插拔方言注册表 | +| 2.9 | AutoMigrate 机制 | ✅ | `WithMigrator` / `WithModels` / `WithAutoMigrate` / `WithoutAutoMigrate` | +| 2.10 | README 更新日志版本错误 | ✅ | README 重写为 v1.0.2 / v1.0.1 / v1.0.0 线 | +| 2.11 | 文档与 CLI 模板同步 | ✅ | GUIDE 1.3 / 3.2 / 4.1 / 8.4.7 / 9.2 更新；CLI 模板补 Swagger/MySQL 注释 | + +### v1.0.2 在计划之外的额外收益 + +- **可插拔方言注册表**：原计划只要求"支持 mysql/postgres"，实际实现升级为 `database.RegisterDialect(DialectSpec{...})` 注册表，应用可一次接入任意 GORM 驱动（SQLite、SQL Server、ClickHouse、TiDB...），DSN 构建器同步登记到 `config` 包。 +- **`config.SetDefaultManager`**：让 App 持有的 `config.Manager` 能成为全局便捷函数（`config.Get`/`GetString`...）的数据源，解决 "App 私有 manager 与全局 API 双轨" 的问题。 +- **`WithAutoMigrate` / `WithoutAutoMigrate`**：与 `WithMigrator`/`WithModels` 解耦的迁移开关，覆盖"注册了迁移器但需临时关闭"的场景。 + +### 验证 + +```bash +go build -buildvcs=false ./... # ✅ 通过 +go vet -buildvcs=false ./... # ✅ 通过 +go test -buildvcs=false ./... # ✅ 全部 23 个包 PASS +``` + +--- + +## 1. 版本原则 + +### 1.1 本次版本核心目标 + +v1.0.2 的目标是把 xlgo 从“业务项目沉淀出来的工具集合”进一步整理为“通用 Go Web 框架”： + +1. **框架与业务解耦**：框架层不写死具体业务角色、业务流程和业务默认值。 +2. **启动流程可组合**：MySQL、Redis、Storage、Swagger、默认路由、AutoMigrate 等能力应可显式启用或关闭。 +3. **错误处理专业化**：框架内部不直接 `Fatalf` 退出进程，而是向调用方返回错误。 +4. **生命周期清晰化**：初始化、运行、关闭流程应具备明确边界，并为后续 lifecycle hooks 打基础。 +5. **高可用基础增强**：健康检查、优雅关闭、连接关闭、依赖状态检查等能力逐步标准化。 +6. **文档真实可信**：README、GUIDE、CLI 模板、更新日志与真实版本和代码行为保持一致。 +7. **坚持 Go 1.25**：本项目作为新框架，明确使用 Go 1.25，不背负旧版本兼容包袱，允许使用 Go 1.25 的新特性。 + +### 1.2 兼容策略 + +v1.0.2 可以接受破坏式更新，但破坏必须有明确收益： + +- 可以调整不合理 API。 +- 可以删除或废弃明显业务化的设计。 +- 可以改变默认启动策略，只要文档和迁移说明清晰。 +- 可以统一命名、配置、模块边界。 +- 不为了兼容历史写法牺牲框架长期设计。 + +建议保留部分快捷 API，但应明确其定位为“默认封装”而非“框架唯一模型”。 + +--- + +## 2. 必须修正的问题清单 + +## 2.1 权限中间件去业务化 + +### 当前问题 + +`middleware/auth.go` 中的权限中间件写死了以下用户类型： + +```go +super_admin +admin +staff +``` + +典型代码： + +```go +if ut != "super_admin" && ut != "admin" { + response.Fail(c, "无权限访问") + c.Abort() + return +} +``` + +这属于具体业务系统权限模型，不应该成为通用框架的固定规则。 + +### 目标设计 + +将固定角色改为默认角色，并提供通用权限能力。 + +### 新增默认常量 + +```go +const ( + DefaultUserTypeSuperAdmin = "super_admin" + DefaultUserTypeAdmin = "admin" + DefaultUserTypeStaff = "staff" +) +``` + +这些常量仅作为默认值和快速开始示例使用，不代表用户必须采用这些角色名。 + +### 新增认证用户结构 + +```go +type AuthUser struct { + UserID uint + Username string + Role string + UserType string +} +``` + +### 新增统一获取当前用户方法 + +```go +func GetAuthUser(c *gin.Context) (AuthUser, bool) +``` + +该方法从 Gin Context 中读取： + +- `ContextKeyUserID` +- `ContextKeyUsername` +- `ContextKeyRole` +- `ContextKeyUserType` + +### 新增通用权限中间件 + +#### 按 user_type 判断 + +```go +func RequireUserTypes(userTypes ...string) gin.HandlerFunc +``` + +示例： + +```go +middleware.RequireUserTypes("tenant_admin", "platform_admin") +``` + +#### 按 role 判断 + +```go +func RequireRoles(roles ...string) gin.HandlerFunc +``` + +示例： + +```go +middleware.RequireRoles("owner", "manager") +``` + +#### 自定义权限判断 + +```go +type AuthChecker func(user AuthUser, c *gin.Context) bool + +func RequireAuth(checker AuthChecker, messages ...string) gin.HandlerFunc +``` + +示例： + +```go +middleware.RequireAuth(func(user middleware.AuthUser, c *gin.Context) bool { + return user.UserType == "merchant" && user.Role == "owner" +}) +``` + +### 调整原快捷方法 + +以下方法可以保留，但必须改为基于通用能力实现： + +```go +func AdminRequired() gin.HandlerFunc { + return RequireUserTypes(DefaultUserTypeSuperAdmin, DefaultUserTypeAdmin) +} + +func SuperAdminRequired() gin.HandlerFunc { + return RequireUserTypes(DefaultUserTypeSuperAdmin) +} + +func StaffRequired() gin.HandlerFunc { + return RequireUserTypes(DefaultUserTypeStaff) +} + +func AnyUserRequired() gin.HandlerFunc { + return RequireUserTypes( + DefaultUserTypeSuperAdmin, + DefaultUserTypeAdmin, + DefaultUserTypeStaff, + ) +} +``` + +### 测试要求 + +新增或完善 `middleware/auth_test.go`： + +- 未登录访问被拒绝。 +- Context 中缺少用户信息时被拒绝。 +- `user_type` 类型异常时被拒绝。 +- `RequireUserTypes("tenant_admin")` 可通过自定义用户类型。 +- `RequireUserTypes("tenant_admin")` 会拒绝其他用户类型。 +- `RequireRoles("owner")` 可通过自定义角色。 +- `RequireAuth` 可执行复杂自定义判断。 +- 默认快捷方法仍符合默认常量语义。 + +--- + +## 2.2 App 启动流程重构为可组合模式 + +### 当前问题 + +`app.go` 的 `Run()` 当前强制执行： + +```go +logger.Init(cfg) +database.InitMySQL(cfg) +database.InitRedis(cfg) +database.AutoMigrate() +storage.Init(&cfg.Storage) +wire.InitServices() +router.RegisterDefaultRoutes(a.router) +``` + +这会导致： + +- 纯 HTTP 服务也必须配置 MySQL。 +- 不使用 Redis 的项目也被强制初始化 Redis。 +- 不使用文件上传的项目也被强制初始化 Storage。 +- 用户无法控制 AutoMigrate。 +- 用户无法控制默认路由和 Swagger 暴露。 +- 测试和最小示例成本过高。 + +### 目标设计 + +v1.0.2 应将 App 启动流程改为“显式、可组合、可关闭”。 + +### 建议新增 App 内部字段 + +```go +type App struct { + config *config.Config + router *gin.Engine + registry *router.Registry + server *http.Server + + configPath string + + enableLogger bool + enableMySQL bool + enableRedis bool + enableStorage bool + enableDefaultRoutes bool + enableAutoMigrate bool + enableWire bool +} +``` + +### 默认策略 + +由于可以激进调整，建议从 v1.0.2 开始采用更清晰的默认策略： + +- `logger` 默认开启。 +- `default routes` 默认开启。 +- `wire` 默认开启。 +- `MySQL`、`Redis`、`Storage` 是否默认开启需要结合快速开始体验决定。 + +推荐方案： + +1. `xlgo.New()` 创建的是轻量 App，不强制初始化 MySQL/Redis/Storage。 +2. 用户通过 Option 显式启用组件： + +```go +xlgo.WithMySQL() +xlgo.WithRedis() +xlgo.WithStorage() +xlgo.WithAutoMigrate() +``` + +3. 提供 `xlgo.NewFullStack()` 或 `xlgo.RunFullStack()` 作为 batteries-included 快捷方式。 + +如果希望过渡成本更低，也可以保留 `New()` 默认全量初始化，但必须提供 `WithoutXxx()`。不过从长期框架设计看，更推荐“显式启用依赖”。 + +### 建议新增 Option + +#### 配置相关 + +```go +func WithConfigPath(path string) Option +func WithConfig(cfg *config.Config) Option +``` + +必须修复当前 `WithConfigPath` 空实现问题。 + +#### 组件启用 + +```go +func WithLogger() Option +func WithMySQL() Option +func WithRedis() Option +func WithStorage() Option +func WithAutoMigrate() Option +func WithWire() Option +func WithDefaultRoutes() Option +``` + +#### 组件关闭 + +如果保留默认开启策略，则必须同时提供： + +```go +func WithoutLogger() Option +func WithoutMySQL() Option +func WithoutRedis() Option +func WithoutStorage() Option +func WithoutAutoMigrate() Option +func WithoutWire() Option +func WithoutDefaultRoutes() Option +``` + +### 推荐使用示例 + +#### 最小 HTTP 服务 + +```go +app := xlgo.New( + xlgo.WithConfigPath("./config.yaml"), + xlgo.WithDefaultRoutes(), +) +``` + +#### 标准业务 API + +```go +app := xlgo.New( + xlgo.WithConfigPath("./config.yaml"), + xlgo.WithLogger(), + xlgo.WithMySQL(), + xlgo.WithRedis(), + xlgo.WithAutoMigrate(), + xlgo.WithDefaultRoutes(), + xlgo.WithModules(user.Module{}, order.Module{}), +) +``` + +#### 文件上传服务 + +```go +app := xlgo.New( + xlgo.WithConfigPath("./config.yaml"), + xlgo.WithStorage(), +) +``` + +### 测试要求 + +- `WithConfigPath` 能真实影响配置加载。 +- `WithConfig` 能注入配置并运行。 +- 未启用 MySQL 时不访问 MySQL 配置。 +- 未启用 Redis 时不访问 Redis 配置。 +- 未启用 Storage 时不初始化 Storage。 +- 关闭默认路由后 `/health` 不注册。 +- 显式开启默认路由后 `/health` 可访问。 + +--- + +## 2.3 框架内部禁止直接 Fatalf 退出 + +### 当前问题 + +`app.go` 中存在： + +```go +logger.Fatalf("初始化 MySQL 失败: %v", err) +``` + +框架内部直接退出进程会让调用方无法处理错误。 + +### 改造目标 + +所有初始化错误向上返回。 + +### 改造示例 + +```go +if err := database.InitMySQL(cfg); err != nil { + return fmt.Errorf("初始化 MySQL 失败: %w", err) +} +``` + +需要覆盖： + +- logger 初始化失败。 +- MySQL 初始化失败。 +- Redis 初始化失败。 +- AutoMigrate 失败。 +- Storage 初始化失败。 +- HTTP Server 启动失败。 + +### 要求 + +框架包内部原则上不调用： + +```go +os.Exit +log.Fatal +logger.Fatal +logger.Fatalf +panic +``` + +除非是明确的开发期 helper 或 CLI 命令入口。 + +--- + +## 2.4 Shutdown 关闭流程修正 + +### 当前问题 + +`App.Shutdown()` 当前调用： + +```go +database.Close() +database.CloseRedis() +``` + +在读写分离场景下，从库连接可能不会被关闭。 + +### 改造目标 + +使用： + +```go +database.CloseAll() +database.CloseRedis() +``` + +并聚合错误。 + +### 建议实现 + +Go 1.25 可直接使用 `errors.Join`： + +```go +var errs []error + +if err := database.CloseAll(); err != nil { + errs = append(errs, err) +} +if err := database.CloseRedis(); err != nil { + errs = append(errs, err) +} + +return errors.Join(errs...) +``` + +### 测试要求 + +- 未初始化数据库时 `Shutdown` 不 panic。 +- 初始化 replicas 后 `CloseAll` 会清空 replicas 和 DBRead。 +- 重复关闭不 panic。 +- 关闭错误能向上返回。 + +--- + +## 2.5 默认路由和 Swagger 可控化 + +### 当前问题 + +`router.RegisterDefaultRoutes()` 当前默认注册： + +```go +/swagger/*any +/health +``` + +Swagger 在生产环境中不应无条件暴露。 + +### 改造目标 + +拆分默认路由注册能力。 + +### 建议新增方法 + +```go +func RegisterHealthRoute(r *gin.Engine, checks ...HealthCheck) +func RegisterSwaggerRoutes(r *gin.Engine) +func RegisterDefaultRoutes(r *gin.Engine, checks ...HealthCheck) +``` + +其中 `RegisterDefaultRoutes` 可以继续组合调用前两个方法。 + +### App Option + +```go +func WithHealthRoutes() Option +func WithSwaggerRoutes() Option +func WithDefaultRoutes() Option +func WithoutDefaultRoutes() Option +``` + +### 推荐生产策略 + +- 开发环境可以开启 Swagger。 +- 生产环境默认不自动开启 Swagger，除非用户显式配置或调用 `WithSwaggerRoutes()`。 + +### 测试要求 + +- 健康检查路由可单独开启。 +- Swagger 路由可单独开启。 +- 默认路由可整体开启。 +- 关闭默认路由后不注册 `/health` 和 `/swagger/*any`。 + +--- + +## 2.6 健康检查标准化 + +### 当前问题 + +当前 `/health` 只返回： + +```json +{"status":"ok"} +``` + +高可用服务一般需要区分 liveness 和 readiness。 + +### v1.0.2 目标 + +v1.0.2 只新增并保留一个健康检查接口，避免接口过多导致使用复杂： + +```text +GET /health +``` + +### 初始响应 + +无检查项时： + +```json +{ + "status": "ok" +} +``` + +有检查项时： + +```json +{ + "status": "ok", + "checks": { + "mysql": "ok", + "redis": "disabled" + } +} +``` + +检查失败时 `/health` 返回 HTTP 503，并将 `status` 设为 `error`。 + +### 建议新增健康检查抽象 + +```go +type HealthChecker interface { + Name() string + Check(ctx context.Context) error +} +``` + +或函数式： + +```go +type HealthCheckFunc func(ctx context.Context) error +``` + +App 后续可支持： + +```go +func WithHealthCheck(name string, check HealthCheckFunc) Option +``` + +v1.0.2 可以先做基础实现，为 v1.1.x 扩展预留。 + +--- + +## 2.7 配置系统问题纳入 v1.0.2 改造 + +### 当前问题 + +`config.Load()` 使用 `sync.Once`，导致： + +- 测试中难以重复加载不同配置。 +- 多 App 实例不友好。 +- `WithConfigPath` 难以正确实现。 +- 配置热更新实例边界不清晰。 + +### 激进改造目标 + +v1.0.2 可以开始引入实例化配置管理器。 + +### 建议新增类型 + +```go +type Manager struct { + mu sync.RWMutex + v *viper.Viper + cfg *Config + callbacks []func(*Config) +} +``` + +### 建议 API + +```go +func NewManager(path string) *Manager +func (m *Manager) Load() (*Config, error) +func (m *Manager) LoadWithWatch(onChange func(*Config)) (*Config, error) +func (m *Manager) Get() *Config +func (m *Manager) Reload() error +func (m *Manager) RegisterCallback(cb func(*Config)) +``` + +### 全局兼容层 + +可以保留全局函数，但内部基于默认 manager： + +```go +func Load(path string) (*Config, error) +func Get() *Config +func Set(cfg *Config) +func Reload() error +``` + +### 关键要求 + +- 去除全局 `sync.Once` 对重复加载的限制，或提供 `ResetForTest()`。 +- App 优先持有自己的 config manager，而不是强依赖全局配置。 +- 全局 API 只作为便捷入口。 + +--- + +## 2.8 数据库全局状态治理 + +### 当前问题 + +`database/mysql.go` 使用全局变量： + +```go +var ( + DB *gorm.DB + DBRead *gorm.DB + replicas []*gorm.DB +) +``` + +这对框架长期发展不利。 + +### v1.0.2 目标 + +引入数据库 Manager，逐步替代全局变量。 + +### 建议类型 + +```go +type Manager struct { + master *gorm.DB + replicas []*gorm.DB + picker ReplicaPicker +} +``` + +### 建议 API + +```go +func NewManager(cfg *config.Config) *Manager +func (m *Manager) Open(ctx context.Context) error +func (m *Manager) OpenWithReplicas(ctx context.Context, replicaDSNs []string) error +func (m *Manager) Master() *gorm.DB +func (m *Manager) Replica() *gorm.DB +func (m *Manager) FromContext(ctx context.Context) *gorm.DB +func (m *Manager) Close() error +func (m *Manager) HealthCheck(ctx context.Context) error +``` + +### Context key 修正 + +当前： + +```go +context.WithValue(ctx, "db_mode", "master") +``` + +应改为私有类型 key，避免冲突： + +```go +type dbModeContextKey struct{} +``` + +### Replica 选择策略 + +v1.0.2 可先提供： + +- Round-robin +- Random + +后续版本再增加： + +- 权重 +- 健康摘除 +- 熔断 + +### 全局兼容层 + +可以保留： + +```go +func InitMySQL(cfg *config.Config) error +func GetDB() *gorm.DB +func GetReadDB() *gorm.DB +func CloseAll() error +``` + +但内部应委托给默认 Manager。 + +--- + +## 2.9 AutoMigrate 机制调整 + +### 当前问题 + +`database.AutoMigrate()` 当前是空实现： + +```go +func AutoMigrate() error { + logger.Info("数据库表结构迁移完成") + return nil +} +``` + +但 `App.Run()` 强制调用它，语义不清晰。 + +### 改造目标 + +迁移应由用户显式注册。 + +### 建议 API + +```go +type Migrator func(db *gorm.DB) error + +func WithMigrator(m Migrator) Option +func WithModels(models ...any) Option +``` + +示例： + +```go +app := xlgo.New( + xlgo.WithMySQL(), + xlgo.WithModels(&User{}, &Order{}), +) +``` + +或： + +```go +app := xlgo.New( + xlgo.WithMigrator(func(db *gorm.DB) error { + return db.AutoMigrate(&User{}, &Order{}) + }), +) +``` + +### 要求 + +- 不再强制执行空的 `database.AutoMigrate()`。 +- 如果没有注册 migrator，不执行迁移。 +- 迁移错误返回给调用方。 + +--- + +## 2.10 README 更新日志版本错误修正 + +### 当前问题 + +`README.md` 当前更新日志写成： + +```md +### v2.1.0 (2026-04-30) +... +### v2.0.0 (2026-04-30) +``` + +但当前实际版本应为 `v1.0.1`，本次计划版本为 `v1.0.2`。该日志会给用户造成误解。 + +### 修正目标 + +将 README 更新日志改为真实版本线。 + +### 建议改法 + +本次发布后 README 应包含： + +```md +## 更新日志 + +### v1.0.2 (计划中 / 发布日期按实际填写) + +- 权限中间件通用化，移除业务角色硬编码。 +- App 启动流程改为可组合模式。 +- 修复 WithConfigPath 空实现问题。 +- 框架初始化错误改为返回 error。 +- 默认路由、Swagger、健康检查可配置。 +- Shutdown 关闭全部数据库连接。 +- 文档和 CLI 模板同步更新。 + +### v1.0.1 + +- 根据真实已发布内容整理。 + +### v1.0.0 + +- 初始版本发布。 +``` + +如果 v2.0.0 / v2.1.0 中的内容实际已经存在于当前代码，应归并到 v1.0.1 或 v1.0.0 的历史描述中，而不是继续使用错误的大版本号。 + +### 要求 + +- 删除或修正 `v2.0.0`、`v2.1.0` 错误标题。 +- README 顶部 badge 如有版本信息，也要同步。 +- GUIDE 中如有类似版本描述，统一修正。 + +--- + +## 2.11 文档与 CLI 模板同步 + +### 涉及文件 + +```text +README.md +GUIDE.md +cmd/xlgo/templates.go +``` + +### 必须更新内容 + +1. 最小启动示例。 +2. 标准业务 API 启动示例。 +3. 自定义权限示例。 +4. 显式启用 MySQL/Redis/Storage 的示例。 +5. 关闭或开启 Swagger 的示例。 +6. 健康检查接口说明。 +7. 配置文件完整示例。 +8. Go 版本说明：明确要求 Go 1.25+。 +9. 更新日志修正为 v1.x 版本线。 + +### CLI 模板调整方向 + +生成项目不应默认塞入过多不可控依赖。建议模板生成： + +```go +app := xlgo.New( + xlgo.WithConfigPath("./config.yaml"), + xlgo.WithLogger(), + xlgo.WithDefaultRoutes(), +) +``` + +如果模板选择 API/fullstack 模式，再加入： + +```go +xlgo.WithMySQL() +xlgo.WithRedis() +xlgo.WithAutoMigrate() +``` + +后续 CLI 可支持： + +```bash +xlgo new myproject --template minimal +xlgo new myproject --template api +xlgo new myproject --template fullstack +``` + +--- + +## 3. 推荐实施顺序 + +## Phase 1：修正业务耦合与明显 bug + +1. 改造 `middleware/auth.go`。 +2. 补充 `middleware/auth_test.go`。 +3. 修复 `WithConfigPath` 空实现。 +4. 修正 `README.md` 更新日志版本错误。 + +## Phase 2：重构 App 启动流程 + +1. App 增加组件启用/关闭选项。 +2. MySQL/Redis/Storage/AutoMigrate 改为显式启用或可关闭。 +3. 默认路由、Health、Swagger 拆分。 +4. `Run()` 中所有初始化错误改为返回 error。 + +## Phase 3：生命周期和关闭流程 + +1. `Shutdown()` 改为关闭全部数据库连接。 +2. 关闭 Redis、日志、限流器等组件时聚合错误。 +3. 准备后续 lifecycle hook 的内部结构。 + +## Phase 4：配置和数据库管理器 + +1. 引入 `config.Manager`。 +2. 去除或弱化全局 `sync.Once` 限制。 +3. 引入 `database.Manager`。 +4. 修正 DB context key。 +5. 全局 API 改为 facade。 + +## Phase 5：健康检查和文档模板 + +1. 保持单一 `/health` 接口。 +2. 支持依赖检查状态和失败时 HTTP 503。 +3. 更新 README/GUIDE。 +4. 更新 CLI 模板。 +5. 更新 CHANGELOG 或 README 更新日志。 + +--- + +## 4. v1.0.2 验收标准 + +### 4.1 功能验收 + +- 用户可以创建不依赖 MySQL/Redis/Storage 的最小应用。 +- 用户可以显式启用 MySQL/Redis/Storage。 +- 用户可以关闭 Swagger 或默认路由。 +- 用户可以使用自定义 user_type、role 或自定义函数做权限判断。 +- `super_admin/admin/staff` 只作为默认常量，不再是框架唯一权限模型。 +- `WithConfigPath` 能真实生效。 +- 初始化失败返回 error，不直接退出进程。 +- Shutdown 能关闭主库、从库、Redis 等资源。 +- README 更新日志版本线修正为 v1.x。 + +### 4.2 测试验收 + +必须通过： + +```bash +go test ./... +``` + +建议新增或更新测试覆盖： + +- `middleware/auth_test.go` +- `app_test.go` +- `router/router_test.go` +- `config/config_test.go` +- `database/mysql_test.go` + +### 4.3 文档验收 + +- README 中快速开始示例可运行。 +- GUIDE 中权限示例与真实 API 一致。 +- CLI 模板生成的项目可 `go test ./...` 或 `go run`。 +- README 更新日志不存在错误的 v2.0.0/v2.1.0 表述。 +- 文档明确写明 Go 1.25+。 + +--- + +## 5. 建议发布说明草案 + +```md +## v1.0.2 + +### Breaking Changes + +- App 启动流程调整为更显式的组件启用模式，MySQL、Redis、Storage、AutoMigrate 等能力可通过 Option 控制。 +- 权限中间件不再将 `super_admin`、`admin`、`staff` 作为框架固定权限模型，仅保留为默认用户类型常量。 +- 框架初始化失败时返回 error，不再在框架内部直接 Fatal 退出。 + +### Added + +- 新增 `middleware.AuthUser` 和 `middleware.GetAuthUser()`。 +- 新增 `middleware.RequireUserTypes()`。 +- 新增 `middleware.RequireRoles()`。 +- 新增 `middleware.RequireAuth()`。 +- 新增 App 组件控制 Option：`WithMySQL`、`WithRedis`、`WithStorage`、`WithAutoMigrate`、`WithDefaultRoutes` 等。 +- 新增单一 `/health` 健康检查规划，支持检查项状态。 +- 新增或规划实例化 `config.Manager`、`database.Manager`。 + +### Changed + +- `AdminRequired()`、`SuperAdminRequired()`、`StaffRequired()`、`AnyUserRequired()` 改为基于通用权限中间件实现。 +- `WithConfigPath()` 改为真实生效。 +- `App.Run()` 初始化流程改为可组合、可返回错误。 +- `App.Shutdown()` 改为关闭全部数据库连接。 +- 默认路由和 Swagger 注册逻辑拆分。 +- README/GUIDE/CLI 模板同步新启动方式。 + +### Fixed + +- 修复 README 更新日志错误使用 v2.0.0/v2.1.0 的问题。 +- 修复 `WithConfigPath()` 空实现问题。 +- 修复读写分离场景下从库连接可能未关闭的问题。 +``` + +--- + +## 6. 后续版本预告 + +v1.0.2 之后建议继续推进： + +### v1.1.0 + +- 完整 Lifecycle Hooks：`OnStart`、`OnShutdown`、`OnReady`。 +- 插件系统：`Plugin` / `Module` / `Provider`。 +- 完整 Health Registry。 +- 更完善的数据库 replica 健康摘除。 + +### v1.2.0 + +- RBAC/Permission 扩展包。 +- 多租户支持基础设施。 +- OpenTelemetry 深度集成。 +- CLI 多模板支持。 + +--- + +## 7. 本计划结论 + +v1.0.2 应该是 xlgo 的一次“框架化校准”版本，而不是小修小补版本。 + +本次更新应优先解决： + +1. 权限模型业务耦合。 +2. App 启动流程不可控。 +3. 初始化错误直接退出。 +4. 默认 Swagger 和默认路由不可控。 +5. 配置和数据库全局状态对测试、多实例不友好。 +6. README 更新日志版本错误。 +7. 文档与真实行为不一致。 + +由于 xlgo 仍是新框架，本阶段应果断修正不合理设计，明确 Go 1.25+，为后续用户增长前打好 API 和架构基础。 diff --git a/docs/plans/Version_Update_Plan_v1.1.0.md b/docs/plans/Version_Update_Plan_v1.1.0.md new file mode 100644 index 0000000..66382ea --- /dev/null +++ b/docs/plans/Version_Update_Plan_v1.1.0.md @@ -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 忽略），用户网页创建。 diff --git a/docs/plans/Version_v1.0.2_report.md b/docs/plans/Version_v1.0.2_report.md new file mode 100644 index 0000000..68e2c94 --- /dev/null +++ b/docs/plans/Version_v1.0.2_report.md @@ -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。 diff --git a/docs/plans/v2.0-review.md b/docs/plans/v2.0-review.md new file mode 100644 index 0000000..244d673 --- /dev/null +++ b/docs/plans/v2.0-review.md @@ -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个函数* diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..4cf6dcf --- /dev/null +++ b/examples/README.md @@ -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 " \ + -d '{"username":"bob","password":"s3cret"}' +``` + +> 示例代码为演示用途，已演示 bcrypt 密码哈希与登录校验；生产环境仍需配合 `validation` 包完善入参校验、密码强度策略与用户注册流程。 diff --git a/examples/full/config.yaml b/examples/full/config.yaml new file mode 100644 index 0000000..4b02232 --- /dev/null +++ b/examples/full/config.yaml @@ -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 diff --git a/examples/full/main.go b/examples/full/main.go new file mode 100644 index 0000000..a6c4fc2 --- /dev/null +++ b/examples/full/main.go @@ -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 ） +// POST /api/v1/users （需 Authorization: Bearer ，创建用户） +// +// 示例会在启动时初始化 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", + }) +} diff --git a/examples/full/main_test.go b/examples/full/main_test.go new file mode 100644 index 0000000..145eaee --- /dev/null +++ b/examples/full/main_test.go @@ -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) +} diff --git a/examples/minimal/config.yaml b/examples/minimal/config.yaml new file mode 100644 index 0000000..104edf1 --- /dev/null +++ b/examples/minimal/config.yaml @@ -0,0 +1,8 @@ +app: + name: "xlgo-minimal-example" + env: "dev" + debug: true + +server: + port: 8081 + mode: development diff --git a/examples/minimal/main.go b/examples/minimal/main.go new file mode 100644 index 0000000..31c81ff --- /dev/null +++ b/examples/minimal/main.go @@ -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!"}) + }) +} diff --git a/glm_note_report.md b/glm_note_report.md new file mode 100644 index 0000000..7478839 --- /dev/null +++ b/glm_note_report.md @@ -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 ） +// 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 ） +// POST /api/v1/users （需 Authorization: Bearer ，创建用户） +``` + +### 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 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) +} diff --git a/handler/handler_test.go b/handler/handler_test.go new file mode 100644 index 0000000..af3b9e1 --- /dev/null +++ b/handler/handler_test.go @@ -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) + } +} diff --git a/jwt/jwt.go b/jwt/jwt.go new file mode 100644 index 0000000..6cb0393 --- /dev/null +++ b/jwt/jwt.go @@ -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 +} diff --git a/jwt/jwt_c9c_internal_test.go b/jwt/jwt_c9c_internal_test.go new file mode 100644 index 0000000..e53e812 --- /dev/null +++ b/jwt/jwt_c9c_internal_test.go @@ -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() +} diff --git a/jwt/jwt_test.go b/jwt/jwt_test.go new file mode 100644 index 0000000..5832f8f --- /dev/null +++ b/jwt/jwt_test.go @@ -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 +} diff --git a/logger/field.go b/logger/field.go new file mode 100644 index 0000000..11446a9 --- /dev/null +++ b/logger/field.go @@ -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) + }, +} diff --git a/logger/logger.go b/logger/logger.go new file mode 100644 index 0000000..054427c --- /dev/null +++ b/logger/logger.go @@ -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() +} diff --git a/logger/logger_h7_internal_test.go b/logger/logger_h7_internal_test.go new file mode 100644 index 0000000..2f99c03 --- /dev/null +++ b/logger/logger_h7_internal_test.go @@ -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") + } +} diff --git a/logger/logger_test.go b/logger/logger_test.go new file mode 100644 index 0000000..ff5cf71 --- /dev/null +++ b/logger/logger_test.go @@ -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) + } +} \ No newline at end of file diff --git a/logs/app.log b/logs/app.log new file mode 100644 index 0000000..f51f7ba --- /dev/null +++ b/logs/app.log @@ -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."} diff --git a/middleware/auth.go b/middleware/auth.go new file mode 100644 index 0000000..5e3d41e --- /dev/null +++ b/middleware/auth.go @@ -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 +} diff --git a/middleware/auth_test.go b/middleware/auth_test.go new file mode 100644 index 0000000..4b4ec59 --- /dev/null +++ b/middleware/auth_test.go @@ -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") + } +} diff --git a/middleware/cors.go b/middleware/cors.go new file mode 100644 index 0000000..43df38f --- /dev/null +++ b/middleware/cors.go @@ -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 模式不允许凭证 + }) +} \ No newline at end of file diff --git a/middleware/cors_internal_test.go b/middleware/cors_internal_test.go new file mode 100644 index 0000000..7a56fbd --- /dev/null +++ b/middleware/cors_internal_test.go @@ -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) + } + } +} diff --git a/middleware/csrf.go b/middleware/csrf.go new file mode 100644 index 0000000..c14841f --- /dev/null +++ b/middleware/csrf.go @@ -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() + } +} diff --git a/middleware/csrf_internal_test.go b/middleware/csrf_internal_test.go new file mode 100644 index 0000000..38b81b5 --- /dev/null +++ b/middleware/csrf_internal_test.go @@ -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") + } +} diff --git a/middleware/logger.go b/middleware/logger.go new file mode 100644 index 0000000..fb72430 --- /dev/null +++ b/middleware/logger.go @@ -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)), + ) + } +} diff --git a/middleware/logger_internal_test.go b/middleware/logger_internal_test.go new file mode 100644 index 0000000..1d60eb1 --- /dev/null +++ b/middleware/logger_internal_test.go @@ -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") + } +} diff --git a/middleware/metrics.go b/middleware/metrics.go new file mode 100644 index 0000000..a54045f --- /dev/null +++ b/middleware/metrics.go @@ -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) + } +} diff --git a/middleware/middleware_test.go b/middleware/middleware_test.go new file mode 100644 index 0000000..e127585 --- /dev/null +++ b/middleware/middleware_test.go @@ -0,0 +1,1548 @@ +package middleware_test + +import ( + "context" + "encoding/json" + "errors" + "net/http" + "net/http/httptest" + "runtime" + "strings" + "sync" + "testing" + "time" + + "github.com/EthanCodeCraft/xlgo-core/config" + "github.com/EthanCodeCraft/xlgo-core/database" + "github.com/EthanCodeCraft/xlgo-core/logger" + "github.com/EthanCodeCraft/xlgo-core/middleware" + "github.com/EthanCodeCraft/xlgo-core/response" + "github.com/alicebob/miniredis/v2" + "github.com/gin-gonic/gin" + "github.com/redis/go-redis/v9" +) + +// respCode 解析统一响应体中的业务 code 字段。 +func respCode(t *testing.T, w *httptest.ResponseRecorder) int { + t.Helper() + var r response.Response + if err := json.Unmarshal(w.Body.Bytes(), &r); err != nil { + t.Fatalf("unmarshal response %q: %v", w.Body.String(), err) + } + return r.Code +} + +func setupTestRouter() *gin.Engine { + gin.SetMode(gin.TestMode) + r := gin.New() + return r +} + +// ===== RequestID Tests ===== + +func TestRequestID(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.RequestID()) + r.GET("/test", func(c *gin.Context) { + id := middleware.GetRequestID(c) + c.JSON(200, gin.H{"request_id": id}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + // 验证响应头有 X-Request-ID + headerID := w.Header().Get("X-Request-ID") + if headerID == "" { + t.Error("X-Request-ID header should be set") + } + + // 验证响应体中的 request_id + if w.Code != 200 { + t.Errorf("RequestID status = %d", w.Code) + } +} + +func TestRequestIDWithExisting(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.RequestID()) + r.GET("/test", func(c *gin.Context) { + id := middleware.GetRequestID(c) + c.JSON(200, gin.H{"request_id": id}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + req.Header.Set("X-Request-ID", "custom-id-123") + r.ServeHTTP(w, req) + + // 验证使用了传入的 ID + headerID := w.Header().Get("X-Request-ID") + if headerID != "custom-id-123" { + t.Errorf("X-Request-ID = %s, want custom-id-123", headerID) + } +} + +func TestGetRequestIDEmpty(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + id := middleware.GetRequestID(c) + c.JSON(200, gin.H{"request_id": id}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + // 没有 RequestID 中间件时，返回空 + if w.Code != 200 { + t.Errorf("status = %d", w.Code) + } +} + +// TestRequestIDSanitizesClientHeader_M15：含换行/超长的客户端 X-Request-ID 应被忽略并重新生成， +// 防头注入与日志伪造。合法 ASCII ID 仍沿用。 +func TestRequestIDSanitizesClientHeader_M15(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.RequestID()) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"request_id": middleware.GetRequestID(c)}) + }) + + // 含 CRLF 的非法 ID 应被忽略、重新生成（非空、无换行）。 + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + req.Header.Set("X-Request-ID", "evil\r\nX-Forged: 1") + r.ServeHTTP(w, req) + got := w.Header().Get("X-Request-ID") + if strings.Contains(got, "\n") || strings.Contains(got, "\r") || got == "" { + t.Errorf("CRLF-injected request id not sanitized, got %q", got) + } + + // 超长 ID 应被忽略、重新生成。 + w2 := httptest.NewRecorder() + req2 := httptest.NewRequest("GET", "/test", nil) + req2.Header.Set("X-Request-ID", strings.Repeat("a", 200)) + r.ServeHTTP(w2, req2) + if len(w2.Header().Get("X-Request-ID")) > 128 { + t.Errorf("overlong request id not regenerated, got len %d", len(w2.Header().Get("X-Request-ID"))) + } + + // 合法 ASCII ID 仍沿用客户端值。 + w3 := httptest.NewRecorder() + req3 := httptest.NewRequest("GET", "/test", nil) + req3.Header.Set("X-Request-ID", "trace-abc-123") + r.ServeHTTP(w3, req3) + if w3.Header().Get("X-Request-ID") != "trace-abc-123" { + t.Errorf("legit request id should be preserved, got %q", w3.Header().Get("X-Request-ID")) + } +} + +// ===== Recover Tests ===== + +func TestRecover(t *testing.T) { + // 需要初始化 logger，否则 Recover 会 panic + // 这里跳过完整测试，仅验证中间件可以正常注册 + r := setupTestRouter() + r.Use(middleware.Recover()) + r.GET("/normal", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/normal", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("Normal status = %d, want 200", w.Code) + } +} + +func TestRecoverNoPanic(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.Recover()) + r.GET("/normal", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/normal", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("Normal status = %d, want 200", w.Code) + } +} + +// ensureNopLogger 把全局 logger 重置为 Nop，避免 Recover 内 logger.Error +// 在 logger 未初始化时 nil deref 二次 panic 干扰断言。 +func ensureNopLogger() { + _ = logger.Close() // Close 后 Logger/apiLog/dbLog 均为 zap.NewNop()，写日志安全。 +} + +// 回归 C8：默认 ModeBusiness 下，真实触发 panic 必须返回 HTTP 500（而非 200）。 +// 修复前：FailWithCode 经 writeResp 在 ModeBusiness 下写 200 并 flush， +// 随后 AbortWithStatus(500) 因 w.Written()==true 沦为 no-op，客户端收 200 + body code:500。 +func TestRecoverPanicReturns500(t *testing.T) { + ensureNopLogger() + response.SetMode(response.ModeBusiness) // 默认模式，复现 bug 的模式 + defer response.SetMode(response.ModeBusiness) + + r := setupTestRouter() + r.Use(middleware.RequestID(), middleware.Recover()) + r.GET("/panic", func(c *gin.Context) { panic("boom") }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/panic", nil) + r.ServeHTTP(w, req) + + if w.Code != 500 { + t.Errorf("panic status = %d, want 500 (C8: ModeBusiness must not swallow 500 into 200)", w.Code) + } + if got := respCode(t, w); got != response.CodeServerError { + t.Errorf("panic body code = %d, want %d", got, response.CodeServerError) + } + // Custom 保留 RequestID，便于链路追踪。 + var r2 response.Response + if err := json.Unmarshal(w.Body.Bytes(), &r2); err != nil { + t.Fatalf("unmarshal response: %v", err) + } + if r2.RequestID == "" { + t.Error("panic response must carry request_id for tracing") + } +} + +// 回归 C8：RecoverWithDetail 同病同治——真实 panic 必须返回 500。 +func TestRecoverWithDetailPanicReturns500(t *testing.T) { + ensureNopLogger() + response.SetMode(response.ModeBusiness) + defer response.SetMode(response.ModeBusiness) + + r := setupTestRouter() + r.Use(middleware.RequestID(), middleware.RecoverWithDetail()) + r.GET("/panic", func(c *gin.Context) { panic("boom") }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/panic", nil) + r.ServeHTTP(w, req) + + if w.Code != 500 { + t.Errorf("RecoverWithDetail panic status = %d, want 500", w.Code) + } + if got := respCode(t, w); got != response.CodeServerError { + t.Errorf("RecoverWithDetail body code = %d, want %d", got, response.CodeServerError) + } +} + +// C8 跨模式一致性：ModeREST 下 panic 同样必须 500（修复前 REST 模式本就 500， +// 此用例锁定两模式行为一致，防止后续回归）。 +func TestRecoverPanicRESTMode500(t *testing.T) { + ensureNopLogger() + response.SetMode(response.ModeREST) + defer response.SetMode(response.ModeBusiness) + + r := setupTestRouter() + r.Use(middleware.RequestID(), middleware.Recover()) + r.GET("/panic", func(c *gin.Context) { panic("boom") }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/panic", nil) + r.ServeHTTP(w, req) + + if w.Code != 500 { + t.Errorf("REST mode panic status = %d, want 500", w.Code) + } +} + +// ===== CSRF Tests ===== + +func TestCSRF(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CSRF()) + r.GET("/form", func(c *gin.Context) { + token := middleware.GetCSRFToken(c) + c.JSON(200, gin.H{"csrf_token": token}) + }) + r.POST("/submit", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + // GET 请求应该成功，并设置 cookie + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/form", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("CSRF GET status = %d", w.Code) + } + + // 获取 cookie 中的 token + cookies := w.Result().Cookies() + var csrfToken string + for _, c := range cookies { + if c.Name == "csrf_token" { + csrfToken = c.Value + break + } + } + + // POST 无 token 应该失败 + w2 := httptest.NewRecorder() + req2 := httptest.NewRequest("POST", "/submit", nil) + r.ServeHTTP(w2, req2) + + if w2.Code != 200 { + // 成功捕获错误，返回 200 但 code != 1 + } + + // POST 带 token 应该成功 + w3 := httptest.NewRecorder() + req3 := httptest.NewRequest("POST", "/submit", nil) + req3.Header.Set("X-CSRF-Token", csrfToken) + r.ServeHTTP(w3, req3) + + // 注意：由于 cookie 需要从上一个请求传递，这里可能需要手动设置 +} + +func TestGetCSRFToken(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CSRF()) + r.GET("/token", func(c *gin.Context) { + token := middleware.GetCSRFToken(c) + c.JSON(200, gin.H{"token": token}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/token", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("GetCSRFToken status = %d", w.Code) + } +} + +func TestDoubleSubmitCookie(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.DoubleSubmitCookie()) + r.GET("/get", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + r.POST("/post", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + // GET 应该成功 + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/get", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("DoubleSubmit GET status = %d", w.Code) + } + + // POST 无 token 应该失败 + w2 := httptest.NewRecorder() + req2 := httptest.NewRequest("POST", "/post", nil) + r.ServeHTTP(w2, req2) + + // 应返回错误 + if w2.Code != 200 && w2.Code != 400 { + t.Errorf("DoubleSubmit POST without token status = %d", w2.Code) + } +} + +// ===== C6 回归：API 模式 CSRF（map 遮蔽修复 + 单次消费 + TTL） ===== + +// apiCSRFToken 从 GenerateAPIToken 响应体中提取颁发的 token。 +func apiCSRFToken(t *testing.T, w *httptest.ResponseRecorder) string { + t.Helper() + var r response.Response + if err := json.Unmarshal(w.Body.Bytes(), &r); err != nil { + t.Fatalf("unmarshal response %q: %v", w.Body.String(), err) + } + data, ok := r.Data.(map[string]any) + if !ok { + t.Fatalf("response data not an object: %v", r.Data) + } + tok, ok := data["csrf_token"].(string) + if !ok || tok == "" { + t.Fatalf("missing csrf_token in response: %v", r.Data) + } + return tok +} + +func setupAPICSRFRouter() *gin.Engine { + r := setupTestRouter() + r.Use(middleware.CSRFForAPI()) + r.GET("/csrf-token", middleware.GenerateAPIToken) + r.POST("/action", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + return r +} + +// 回归 C6a：颁发 → 校验闭环。修复前颁发的 token 永不在校验 map 里， +// 所有非安全方法请求被判“CSRF Token 无效”拒绝，API CSRF 模式整体不可用。 +func TestCSRFForAPIIssueValidateCycle(t *testing.T) { + r := setupAPICSRFRouter() + + // 颁发 token + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/csrf-token", nil) + r.ServeHTTP(w, req) + if respCode(t, w) != response.CodeSuccess { + t.Fatalf("issue token code = %d, want success", respCode(t, w)) + } + token := apiCSRFToken(t, w) + + // 携带 token 的 POST 必须通过（修复前这里恒失败） + w2 := httptest.NewRecorder() + req2 := httptest.NewRequest("POST", "/action", nil) + req2.Header.Set("X-CSRF-Token", token) + r.ServeHTTP(w2, req2) + if respCode(t, w2) != response.CodeSuccess { + t.Errorf("POST with valid token code = %d, want success (issue→validate cycle broken)", respCode(t, w2)) + } +} + +// 回归 C6b：单次消费——同一 token 第二次使用必须被拒绝，防止重放。 +func TestCSRFForAPISingleUseConsumption(t *testing.T) { + r := setupAPICSRFRouter() + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/csrf-token", nil)) + token := apiCSRFToken(t, w) + + // 首次使用：通过 + w1 := httptest.NewRecorder() + req1 := httptest.NewRequest("POST", "/action", nil) + req1.Header.Set("X-CSRF-Token", token) + r.ServeHTTP(w1, req1) + if respCode(t, w1) != response.CodeSuccess { + t.Fatalf("first use code = %d, want success", respCode(t, w1)) + } + + // 重放：必须拒绝 + w2 := httptest.NewRecorder() + req2 := httptest.NewRequest("POST", "/action", nil) + req2.Header.Set("X-CSRF-Token", token) + r.ServeHTTP(w2, req2) + if respCode(t, w2) == response.CodeSuccess { + t.Error("replayed token must be rejected (single-use consumption broken)") + } +} + +// 回归 C6：缺失 / 伪造 token 必须被拒绝。 +func TestCSRFForAPIInvalidAndMissing(t *testing.T) { + r := setupAPICSRFRouter() + + // 无 token + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("POST", "/action", nil)) + if respCode(t, w) == response.CodeSuccess { + t.Error("POST without token must be rejected") + } + + // 伪造 token + w2 := httptest.NewRecorder() + req2 := httptest.NewRequest("POST", "/action", nil) + req2.Header.Set("X-CSRF-Token", "not-a-real-token") + r.ServeHTTP(w2, req2) + if respCode(t, w2) == response.CodeSuccess { + t.Error("POST with forged token must be rejected") + } +} + +// 回归 C6：安全方法不校验，直接放行。 +func TestCSRFForAPISafeMethodPasses(t *testing.T) { + r := setupAPICSRFRouter() + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/csrf-token", nil)) + if w.Code != 200 { + t.Errorf("safe method status = %d, want 200", w.Code) + } +} + +// 回归 C6c：DoubleSubmitCookie 的 cookie 必须 HttpOnly=false， +// 否则前端 JS 读不到 cookie、无法回填 X-CSRF-Token 头，双重提交对真实前端不可用。 +func TestDoubleSubmitCookieHttpOnlyFalse(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.DoubleSubmitCookie()) + r.GET("/get", func(c *gin.Context) { c.JSON(200, gin.H{"status": "ok"}) }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/get", nil)) + + for _, c := range w.Result().Cookies() { + if c.Name == "csrf_token" { + if c.HttpOnly { + t.Errorf("DoubleSubmit cookie HttpOnly = true, want false (JS must read it to refill header)") + } + return + } + } + t.Fatal("csrf_token cookie not set on GET") +} + +// 回归 C6c：前端回填闭环——GET 下发 cookie，POST 携带匹配的 X-CSRF-Token 通过，不匹配拒绝。 +func TestDoubleSubmitCookieFrontendRefill(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.DoubleSubmitCookie()) + r.GET("/get", func(c *gin.Context) { c.JSON(200, gin.H{"status": "ok"}) }) + r.POST("/post", func(c *gin.Context) { c.JSON(200, gin.H{"status": "ok"}) }) + + // GET 下发 cookie + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/get", nil)) + var cookieToken string + for _, c := range w.Result().Cookies() { + if c.Name == "csrf_token" { + cookieToken = c.Value + } + } + if cookieToken == "" { + t.Fatal("no csrf_token cookie issued") + } + + // 携带匹配 token 的 cookie + header：通过 + w2 := httptest.NewRecorder() + req2 := httptest.NewRequest("POST", "/post", nil) + req2.Header.Set("Cookie", "csrf_token="+cookieToken) + req2.Header.Set("X-CSRF-Token", cookieToken) + r.ServeHTTP(w2, req2) + if w2.Code != 200 { + t.Errorf("POST with matching token status = %d, want 200", w2.Code) + } + + // 不匹配：拒绝 + w3 := httptest.NewRecorder() + req3 := httptest.NewRequest("POST", "/post", nil) + req3.Header.Set("Cookie", "csrf_token="+cookieToken) + req3.Header.Set("X-CSRF-Token", "mismatched") + r.ServeHTTP(w3, req3) + if w3.Code == 200 && respCode(t, w3) == response.CodeSuccess { + t.Error("POST with mismatched token must be rejected") + } +} + +// ===== CORS Tests ===== + +func TestCORS(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CORS()) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + // 使用 localhost origin（开发环境默认允许） + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + req.Header.Set("Origin", "http://localhost:3000") + r.ServeHTTP(w, req) + + // 验证请求成功 + if w.Code != 200 { + t.Errorf("CORS status = %d", w.Code) + } + + // 验证其他 CORS 头始终设置 + allowMethods := w.Header().Get("Access-Control-Allow-Methods") + if allowMethods == "" { + t.Error("Access-Control-Allow-Methods should be set") + } +} + +func TestCORSOptions(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CORS()) + r.POST("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + // OPTIONS 预检请求 + w := httptest.NewRecorder() + req := httptest.NewRequest("OPTIONS", "/test", nil) + r.ServeHTTP(w, req) + + // OPTIONS 应返回 204 + if w.Code != 204 { + t.Errorf("CORS OPTIONS status = %d, want 204", w.Code) + } +} + +// CORS 规范要求：AllowCredentials=false 时不应发送 Access-Control-Allow-Credentials 头。 +// 历史 bug：旧实现在 if/else 两个分支都设了 "true"，相当于永远允许凭证。 +func TestCORSAllowCredentialsDefault(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CORSWithConfig(&config.CORSConfig{ + AllowedOrigins: []string{"https://example.com"}, + AllowCredentials: false, + })) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + req.Header.Set("Origin", "https://example.com") + r.ServeHTTP(w, req) + + if got := w.Header().Get("Access-Control-Allow-Credentials"); got != "" { + t.Errorf("Access-Control-Allow-Credentials = %q, want empty when AllowCredentials=false", got) + } +} + +// AllowCredentials=true 且 Origin 在白名单内：发送凭证头并回显具体 Origin。 +func TestCORSAllowCredentialsExplicitOrigin(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CORSWithConfig(&config.CORSConfig{ + AllowedOrigins: []string{"https://example.com"}, + AllowCredentials: true, + })) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + req.Header.Set("Origin", "https://example.com") + r.ServeHTTP(w, req) + + if got := w.Header().Get("Access-Control-Allow-Credentials"); got != "true" { + t.Errorf("Access-Control-Allow-Credentials = %q, want \"true\"", got) + } + if got := w.Header().Get("Access-Control-Allow-Origin"); got != "https://example.com" { + t.Errorf("Access-Control-Allow-Origin = %q, want \"https://example.com\"", got) + } + if got := w.Header().Get("Vary"); got != "Origin" { + t.Errorf("Vary = %q, want \"Origin\"", got) + } +} + +// CORS 规范：AllowCredentials=true 时禁止使用 "*"，必须回显具体 Origin。 +func TestCORSWildcardWithCredentials(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CORSWithConfig(&config.CORSConfig{ + AllowedOrigins: []string{"*"}, + AllowCredentials: true, + })) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + req.Header.Set("Origin", "https://anywhere.example") + r.ServeHTTP(w, req) + + if got := w.Header().Get("Access-Control-Allow-Origin"); got == "*" { + t.Errorf("Access-Control-Allow-Origin must NOT be \"*\" when credentials are allowed, got %q", got) + } + if got := w.Header().Get("Access-Control-Allow-Origin"); got != "https://anywhere.example" { + t.Errorf("Access-Control-Allow-Origin = %q, want echoed origin", got) + } + if got := w.Header().Get("Access-Control-Allow-Credentials"); got != "true" { + t.Errorf("Access-Control-Allow-Credentials = %q, want \"true\"", got) + } +} + +// AllowedOrigins=["*"] 且 AllowCredentials=false：保持 "*" 通配符语义。 +func TestCORSWildcardWithoutCredentials(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CORSWithConfig(&config.CORSConfig{ + AllowedOrigins: []string{"*"}, + AllowCredentials: false, + })) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + req.Header.Set("Origin", "https://anywhere.example") + r.ServeHTTP(w, req) + + if got := w.Header().Get("Access-Control-Allow-Origin"); got != "*" { + t.Errorf("Access-Control-Allow-Origin = %q, want \"*\"", got) + } + if got := w.Header().Get("Access-Control-Allow-Credentials"); got != "" { + t.Errorf("Access-Control-Allow-Credentials = %q, want empty (AllowCredentials=false)", got) + } +} + +// Origin 不在白名单时不应回显，避免反射型 CORS 漏洞。 +func TestCORSOriginNotAllowed(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CORSWithConfig(&config.CORSConfig{ + AllowedOrigins: []string{"https://allowed.example"}, + AllowCredentials: true, + })) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + req.Header.Set("Origin", "https://evil.example") + r.ServeHTTP(w, req) + + if got := w.Header().Get("Access-Control-Allow-Origin"); got != "" { + t.Errorf("Access-Control-Allow-Origin = %q, want empty for non-whitelisted origin", got) + } + if got := w.Header().Get("Access-Control-Allow-Credentials"); got != "" { + t.Errorf("Access-Control-Allow-Credentials = %q, want empty for non-whitelisted origin", got) + } +} + +// ===== C7 回归：CORS 通配后缀绕过 + 开发态任意 Origin 回显 ===== + +// 回归 C7a：通配符 *.example.com 必须拒绝 notexample.com（后缀相同但非真实子域）。 +// 旧实现 strings.HasSuffix(origin, "example.com") 接受此类绕过。 +func TestCORSWildcardSuffixBypassRejected(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CORSWithConfig(&config.CORSConfig{ + AllowedOrigins: []string{"*.example.com"}, + AllowCredentials: true, + })) + r.GET("/test", func(c *gin.Context) { c.JSON(200, gin.H{"status": "ok"}) }) + + for _, evil := range []string{"https://notexample.com", "https://evil-example.com"} { + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + req.Header.Set("Origin", evil) + r.ServeHTTP(w, req) + if got := w.Header().Get("Access-Control-Allow-Origin"); got != "" { + t.Errorf("evil origin %q got Allow-Origin %q, want empty (suffix bypass)", evil, got) + } + if got := w.Header().Get("Access-Control-Allow-Credentials"); got != "" { + t.Errorf("evil origin %q got Allow-Credentials %q, want empty", evil, got) + } + } + + // 真实子域仍应通过。 + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + req.Header.Set("Origin", "https://app.example.com") + r.ServeHTTP(w, req) + if got := w.Header().Get("Access-Control-Allow-Origin"); got != "https://app.example.com" { + t.Errorf("real subdomain got Allow-Origin %q, want echoed", got) + } +} + +// 回归 C7a：通配符不匹配 apex 自身（example.com 不由 *.example.com 覆盖，需显式配置）。 +func TestCORSWildcardDoesNotMatchApex(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CORSWithConfig(&config.CORSConfig{ + AllowedOrigins: []string{"*.example.com"}, + })) + r.GET("/test", func(c *gin.Context) { c.JSON(200, gin.H{"status": "ok"}) }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + req.Header.Set("Origin", "https://example.com") + r.ServeHTTP(w, req) + if got := w.Header().Get("Access-Control-Allow-Origin"); got != "" { + t.Errorf("apex origin matched by wildcard got %q, want empty", got) + } +} + +// 回归 C7b：开发态兜底仅对 localhost 回显，不回显任意 Origin（防凭据型反射）。 +// 旧实现 cfg.IsDevelopment() && origin != "" 无条件回显任意 Origin。 +func TestCORSDevModeRejectsArbitraryOrigin(t *testing.T) { + // 注入开发态全局配置（无 CORS 白名单 → 走开发态兜底分支）。 + old := config.Get() + config.Set(&config.Config{ + App: config.AppConfig{Env: "development"}, + Server: config.ServerConfig{Mode: "development"}, + }) + t.Cleanup(func() { + if old != nil { + config.Set(old) + } else { + config.Set(&config.Config{}) + } + }) + + r := setupTestRouter() + r.Use(middleware.CORS()) + r.GET("/test", func(c *gin.Context) { c.JSON(200, gin.H{"status": "ok"}) }) + + // 非 localhost 的任意 Origin 不应被回显。 + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + req.Header.Set("Origin", "https://evil.com") + r.ServeHTTP(w, req) + if got := w.Header().Get("Access-Control-Allow-Origin"); got != "" { + t.Errorf("arbitrary origin echoed in dev mode: %q, want empty", got) + } + + // localhost 仍应被回显（开发态正常用法）。 + w2 := httptest.NewRecorder() + req2 := httptest.NewRequest("GET", "/test", nil) + req2.Header.Set("Origin", "http://localhost:3000") + r.ServeHTTP(w2, req2) + if got := w2.Header().Get("Access-Control-Allow-Origin"); got != "http://localhost:3000" { + t.Errorf("localhost origin in dev mode got %q, want echoed", got) + } +} + +// 回归 C7 收尾：未匹配 origin 不发 Allow-Methods/Headers（收敛信息泄露）。 +// 旧实现无论 origin 是否匹配都无条件发送，向未授权 origin 暴露 API 允许的方法/头清单。 +func TestCORSUnmatchedOriginNoMethodHeaders(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CORSWithConfig(&config.CORSConfig{ + AllowedOrigins: []string{"https://example.com"}, + })) + r.GET("/test", func(c *gin.Context) { c.JSON(200, gin.H{"status": "ok"}) }) + + // 未匹配 origin：不应发任何 CORS 头（含 Allow-Methods/Headers）。 + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + req.Header.Set("Origin", "https://evil.com") + r.ServeHTTP(w, req) + if got := w.Header().Get("Access-Control-Allow-Origin"); got != "" { + t.Errorf("unmatched origin got Allow-Origin %q, want empty", got) + } + if got := w.Header().Get("Access-Control-Allow-Methods"); got != "" { + t.Errorf("unmatched origin got Allow-Methods %q, want empty (info leak)", got) + } + if got := w.Header().Get("Access-Control-Allow-Headers"); got != "" { + t.Errorf("unmatched origin got Allow-Headers %q, want empty (info leak)", got) + } + if got := w.Header().Get("Access-Control-Expose-Headers"); got != "" { + t.Errorf("unmatched origin got Expose-Headers %q, want empty", got) + } + if got := w.Header().Get("Access-Control-Max-Age"); got != "" { + t.Errorf("unmatched origin got Max-Age %q, want empty", got) + } + + // 匹配 origin：正常发 Allow-Methods/Headers。 + w2 := httptest.NewRecorder() + req2 := httptest.NewRequest("GET", "/test", nil) + req2.Header.Set("Origin", "https://example.com") + r.ServeHTTP(w2, req2) + if got := w2.Header().Get("Access-Control-Allow-Origin"); got != "https://example.com" { + t.Errorf("matched origin got Allow-Origin %q, want echoed", got) + } + if got := w2.Header().Get("Access-Control-Allow-Methods"); got == "" { + t.Error("matched origin should have Allow-Methods set") + } + if got := w2.Header().Get("Access-Control-Allow-Headers"); got == "" { + t.Error("matched origin should have Allow-Headers set") + } +} + +// ===== RateLimit Tests ===== + +func TestRateLimit(t *testing.T) { + r := setupTestRouter() + // 使用自定义限流器 + limiter := middleware.NewRateLimiter(10, time.Minute) // 每分钟10次 + defer limiter.Stop() + r.Use(middleware.RateLimit(limiter)) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + // 正常请求应该成功 + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + // 单次请求应该成功 + if w.Code != 200 { + t.Errorf("RateLimit status = %d, want 200", w.Code) + } +} + +func TestRateLimiterAllow(t *testing.T) { + limiter := middleware.NewRateLimiter(3, time.Minute) // 每分钟3次 + defer limiter.Stop() + + // 前3次允许 + for i := 0; i < 3; i++ { + if !limiter.Allow("192.168.1.1") { + t.Errorf("Request %d should be allowed", i+1) + } + } + + // 第4次拒绝 + if limiter.Allow("192.168.1.1") { + t.Error("Request 4 should be denied") + } + + // 不同 IP 应该独立计数 + if !limiter.Allow("192.168.1.2") { + t.Error("Different IP should be allowed") + } +} + +func TestCustomRateLimit(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CustomRateLimit(5, time.Minute)) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("CustomRateLimit status = %d", w.Code) + } +} + +// ===== H4b 回归：CustomRateLimit goroutine 泄漏 ===== + +// goroutineCount 返回当前 goroutine 数（经短暂 GC + 让出以稳定读数）。 +func goroutineCount() int { + runtime.GC() + // 给 cleanup goroutine 退出的时间窗口一点余量。 + for i := 0; i < 20; i++ { + n := runtime.NumGoroutine() + _ = n + runtime.Gosched() + } + return runtime.NumGoroutine() +} + +// 回归 H4b：CustomRateLimit 创建的限流器登记入表， +// StopRateLimiters 停止其 cleanup goroutine，无泄漏。 +// 修复前 CustomRateLimit 创建的 limiter 无句柄，StopRateLimiters 不感知 → cleanup goroutine 永久泄漏。 +func TestCustomRateLimitNoGoroutineLeak(t *testing.T) { + // 先清空全局状态（其他测试可能残留）。 + middleware.StopRateLimiters() + + before := goroutineCount() + + // 创建多个自定义限流器（每个启动一个 cleanup goroutine）。 + const n = 5 + r := setupTestRouter() + for i := 0; i < n; i++ { + r.Use(middleware.CustomRateLimit(100, time.Minute)) + } + r.GET("/test", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) }) + + // 触发一次请求使中间件生效（limiter 已在构造时创建）。 + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/test", nil)) + if w.Code != 200 { + t.Fatalf("status = %d, want 200", w.Code) + } + + created := goroutineCount() + // 创建 n 个限流器后 goroutine 数应明显增加（至少 n 个 cleanup goroutine）。 + if created < before+n { + t.Errorf("after creating %d custom limiters: goroutines = %d, before = %d, want >= before+%d", n, created, before, n) + } + + // StopRateLimiters 须停止登记的自定义限流器 → cleanup goroutine 退出。 + middleware.StopRateLimiters() + + // 等待 cleanup goroutine 退出（Stop 内部 wg.Wait 已保证，但 NumGoroutine 读数有调度延迟）。 + deadline := time.Now().Add(2 * time.Second) + var after int + for time.Now().Before(deadline) { + after = goroutineCount() + if after <= before+2 { // 允许少量调度噪声 + break + } + time.Sleep(10 * time.Millisecond) + } + + if after > before+2 { + t.Errorf("after StopRateLimiters: goroutines = %d, before = %d, expected custom cleanup goroutines released (H4b leak)", after, before) + } +} + +// 回归 H4b：InitRateLimiters 重新初始化时也停止旧的自定义限流器（防 re-init 泄漏）。 +func TestCustomRateLimitReinitStopsOldCustoms(t *testing.T) { + middleware.StopRateLimiters() + + // 基线：InitRateLimiters 只建 3 个命名限流器（3 个 cleanup goroutine），无自定义。 + middleware.InitRateLimiters() + baseline := goroutineCount() + + // 创建 2 个自定义限流器（修复后登记入表）。 + _ = middleware.CustomRateLimit(100, time.Minute) + _ = middleware.CustomRateLimit(100, time.Minute) + + // InitRateLimiters 重建命名限流器时也应停止已登记的自定义限流器。 + // 修复后：自定义 2 个被停止，仅剩 3 个命名 cleanup goroutine → goroutine 数 ≈ baseline。 + // 修复前（不登记）：2 个自定义 cleanup goroutine 泄漏 → goroutine 数 ≈ baseline+2。 + middleware.InitRateLimiters() + + deadline := time.Now().Add(2 * time.Second) + var after int + for time.Now().Before(deadline) { + after = goroutineCount() + if after <= baseline+1 { // 允许少量调度噪声 + break + } + time.Sleep(10 * time.Millisecond) + } + + if after > baseline+1 { + t.Errorf("after InitRateLimiters: goroutines = %d, baseline = %d, expected old custom limiters stopped (H4b re-init leak)", after, baseline) + } + + middleware.StopRateLimiters() +} + +// ===== H4a 回归：限流窗口语义 ===== + +// fakeClock 可控时钟，供 RateLimiter 测试注入 nowFunc（避免真实 Sleep flaky）。 +type fakeClock struct { + mu sync.Mutex + now time.Time +} + +func newFakeClock() *fakeClock { + return &fakeClock{now: time.Now()} +} + +func (fc *fakeClock) Now() time.Time { + fc.mu.Lock() + defer fc.mu.Unlock() + return fc.now +} + +func (fc *fakeClock) Advance(d time.Duration) { + fc.mu.Lock() + defer fc.mu.Unlock() + fc.now = fc.now.Add(d) +} + +// 回归 H4a：稳态客户端跨窗口持续低于 rate，不被误限。 +// rate=10/100ms。每窗口 8 次（< rate），分散在窗口内。 +// 旧实现放行每次更新 windowStart，致重置分支永不成立、count 跨窗口累加， +// 第 2 个窗口内 count 累加超过 10 被误限——尽管每窗口请求数（8）低于 rate。 +// 修复后 windowStart 仅窗口起点设置，跨窗口重置、稳态低于 rate 永不被限。 +func TestRateLimiterSteadyClientNotBlocked(t *testing.T) { + clock := newFakeClock() + limiter := middleware.NewRateLimiter(10, 100*time.Millisecond) + limiter.SetNowFunc(clock.Now) + defer limiter.Stop() + + // 3 个窗口，每窗口 8 次（< rate=10），每次间隔 12ms（8×12=96ms < 100ms 在窗口内）。 + // 窗口间靠最后一次 Advance 推进到 >100ms 触发跨窗口。 + for w := 0; w < 3; w++ { + for i := 0; i < 8; i++ { + if !limiter.Allow("1.2.3.4") { + t.Fatalf("window %d request %d should be allowed (steady below rate, H4a: count must reset per window)", w+1, i+1) + } + clock.Advance(12 * time.Millisecond) // 窗口内推进 + } + // 8×12=96ms 已过，再推进 8ms 到 104ms > 100ms，进入下一窗口。 + clock.Advance(8 * time.Millisecond) + } +} + +// 回归 H4a：窗口过后 count 重置，可再次放行（固定窗口语义）。 +// 旧实现 lastSeen 每次放行更新，窗口过期分支对持续客户端永不触发。 +func TestRateLimiterWindowReset(t *testing.T) { + clock := newFakeClock() + limiter := middleware.NewRateLimiter(3, time.Minute) + limiter.SetNowFunc(clock.Now) + defer limiter.Stop() + + for i := 0; i < 3; i++ { + if !limiter.Allow("1.2.3.4") { + t.Fatalf("request %d should be allowed", i+1) + } + } + if limiter.Allow("1.2.3.4") { + t.Error("request 4 should be denied (rate exceeded)") + } + clock.Advance(time.Minute + time.Second) + if !limiter.Allow("1.2.3.4") { + t.Error("request after window should be allowed (window reset)") + } +} + +// 回归 H4a：超限被拦（基本限流仍生效，修复不是放宽到无限）。 +func TestRateLimiterBlocksOverRate(t *testing.T) { + limiter := middleware.NewRateLimiter(3, time.Minute) + defer limiter.Stop() + + for i := 0; i < 3; i++ { + if !limiter.Allow("1.2.3.4") { + t.Fatalf("request %d should be allowed", i+1) + } + } + if limiter.Allow("1.2.3.4") { + t.Error("request 4 should be denied") + } +} + +// 回归 H4a：窗口内突发（瞬时集中）达 rate 后拒绝——固定窗口允许突发但封顶 rate。 +func TestRateLimiterBurstCappedAtRate(t *testing.T) { + clock := newFakeClock() + limiter := middleware.NewRateLimiter(5, time.Minute) + limiter.SetNowFunc(clock.Now) + defer limiter.Stop() + + for i := 0; i < 5; i++ { + if !limiter.Allow("1.2.3.4") { + t.Errorf("burst request %d should be allowed", i+1) + } + } + if limiter.Allow("1.2.3.4") { + t.Error("request 6 in same window should be denied") + } +} + +func assertPanic(t *testing.T, name string, fn func()) { + t.Helper() + defer func() { + if r := recover(); r == nil { + t.Fatalf("%s did not panic", name) + } + }() + fn() +} + +func TestRateLimiterRejectsInvalidConfig(t *testing.T) { + assertPanic(t, "memory limiter zero rate", func() { + _ = middleware.NewRateLimiter(0, time.Minute) + }) + assertPanic(t, "memory limiter zero window", func() { + _ = middleware.NewRateLimiter(1, 0) + }) + assertPanic(t, "redis limiter zero rate", func() { + _ = middleware.NewRedisRateLimiter("bad", 0, time.Minute) + }) + assertPanic(t, "redis fail-closed limiter zero window", func() { + _ = middleware.NewRedisRateLimiter("bad", 1, 0, middleware.WithFailClosed(true)) + }) +} + +func TestRateLimiterStopIdempotent(t *testing.T) { + limiter := middleware.NewRateLimiter(1, time.Minute) + limiter.Stop() + limiter.Stop() +} + +func TestRateLimitNilLimiterFailsClosed(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.RateLimit(nil)) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/test", nil)) + + if w.Code != http.StatusServiceUnavailable { + t.Fatalf("RateLimit(nil) status = %d, want 503; body=%s", w.Code, w.Body.String()) + } + if got := respCode(t, w); got != response.CodeServiceUnavailable { + t.Fatalf("RateLimit(nil) code = %d, want %d", got, response.CodeServiceUnavailable) + } +} + +func TestLoginRateLimit(t *testing.T) { + middleware.InitRateLimiters() + defer middleware.StopRateLimiters() + + r := setupTestRouter() + r.Use(middleware.LoginRateLimit()) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("LoginRateLimit status = %d", w.Code) + } +} + +func TestAPIRateLimit(t *testing.T) { + middleware.InitRateLimiters() + defer middleware.StopRateLimiters() + + r := setupTestRouter() + r.Use(middleware.APIRateLimit()) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("APIRateLimit status = %d", w.Code) + } +} + +func TestUploadRateLimit(t *testing.T) { + middleware.InitRateLimiters() + defer middleware.StopRateLimiters() + + r := setupTestRouter() + r.Use(middleware.UploadRateLimit()) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("UploadRateLimit status = %d", w.Code) + } +} + +// ===== RedisRateLimiter Tests ===== + +func TestRedisRateLimiter(t *testing.T) { + limiter := middleware.NewRedisRateLimiter("test_limit", 10, time.Minute) + + // Without Redis, should always allow + ctx := context.Background() + allowed, err := limiter.Allow(ctx, "192.168.1.1") + if err != nil { + t.Errorf("RedisRateLimiter error: %v", err) + } + if !allowed { + t.Error("RedisRateLimiter should allow without Redis") + } +} + +func TestRedisRateLimitMiddleware(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.RedisRateLimit("test_api", 100)) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + // Without Redis, should pass + if w.Code != 200 { + t.Errorf("RedisRateLimit status = %d", w.Code) + } +} + +func TestLoginRedisRateLimit(t *testing.T) { + // H4c: LoginRedisRateLimit 改 fail-closed——无 Redis 时拒绝（503）， + // 防爆破场景下 Redis 故障不能静默放行（原 fail-open 致限流失效）。 + // 测试环境无 Redis，故预期 503。 + prev := database.SetTestRedisClient(nil) + defer func() { database.SetTestRedisClient(prev) }() + + r := setupTestRouter() + r.Use(middleware.LoginRedisRateLimit()) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != http.StatusServiceUnavailable { + t.Errorf("LoginRedisRateLimit (no Redis, fail-closed) status = %d, want 503", w.Code) + } +} + +func TestAPIRedisRateLimit(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.APIRedisRateLimit()) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("APIRedisRateLimit status = %d", w.Code) + } +} + +func TestCustomRedisRateLimit(t *testing.T) { + r := setupTestRouter() + r.Use(middleware.CustomRedisRateLimit("custom", 50, time.Minute)) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("CustomRedisRateLimit status = %d", w.Code) + } +} + +func TestRedisRateLimitWithIdentifierNilFuncUsesClientIP(t *testing.T) { + setupMiddlewareMiniRedis(t) + + r := setupTestRouter() + r.Use(middleware.RedisRateLimitWithIdentifier("nil_identifier", 1, nil)) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w1 := httptest.NewRecorder() + req1 := httptest.NewRequest("GET", "/test", nil) + req1.RemoteAddr = "192.0.2.10:12345" + r.ServeHTTP(w1, req1) + if w1.Code != http.StatusOK { + t.Fatalf("first request status = %d, want 200; body=%s", w1.Code, w1.Body.String()) + } + + w2 := httptest.NewRecorder() + req2 := httptest.NewRequest("GET", "/test", nil) + req2.RemoteAddr = "192.0.2.10:12345" + r.ServeHTTP(w2, req2) + if got := respCode(t, w2); got != response.CodeRateLimit { + t.Fatalf("second request code = %d, want %d; status=%d body=%s", got, response.CodeRateLimit, w2.Code, w2.Body.String()) + } +} + +func TestRedisRateLimiterGetCount(t *testing.T) { + limiter := middleware.NewRedisRateLimiter("test_count", 10, time.Minute) + + ctx := context.Background() + count, err := limiter.GetCount(ctx, "192.168.1.1") + if err != nil { + t.Errorf("GetCount error: %v", err) + } + // Without Redis, count should be 0 + if count != 0 { + t.Errorf("GetCount = %d, want 0 without Redis", count) + } +} + +func TestRedisRateLimiterReset(t *testing.T) { + limiter := middleware.NewRedisRateLimiter("test_reset", 10, time.Minute) + + ctx := context.Background() + err := limiter.Reset(ctx, "192.168.1.1") + if err != nil { + t.Errorf("Reset error: %v", err) + } +} + +// ===== H4c 回归：RedisRateLimiter fail-open/fail-closed + 裸断言 ===== + +// setupMiddlewareMiniRedis 启动 miniredis 并注入 database 内部 redisClient，返回 mr 与清理。 +func setupMiddlewareMiniRedis(t *testing.T) *miniredis.Miniredis { + t.Helper() + mr := miniredis.RunT(t) + client := redis.NewClient(&redis.Options{Addr: mr.Addr()}) + t.Cleanup(func() { _ = client.Close() }) + old := database.SetTestRedisClient(client) + t.Cleanup(func() { database.SetTestRedisClient(old) }) + return mr +} + +// 回归 H4c-1a：无 Redis 时 fail-open 放行（兼容旧行为）。 +func TestRedisRateLimiterFailOpenNoRedis(t *testing.T) { + prev := database.SetTestRedisClient(nil) + defer func() { database.SetTestRedisClient(prev) }() + + limiter := middleware.NewRedisRateLimiter("test", 10, time.Minute) + allowed, err := limiter.Allow(context.Background(), "1.2.3.4") + if err != nil { + t.Errorf("fail-open no-redis err = %v, want nil", err) + } + if !allowed { + t.Error("fail-open no-redis should allow (兼容旧行为)") + } +} + +// 回归 H4c-1b：无 Redis 时 fail-closed 拒绝 + 返 ErrRedisRateLimiterUnavailable。 +// 修复前无此选项；fail-closed 是 H4c 新增的安全语义。 +func TestRedisRateLimiterFailClosedNoRedis(t *testing.T) { + prev := database.SetTestRedisClient(nil) + defer func() { database.SetTestRedisClient(prev) }() + + limiter := middleware.NewRedisRateLimiter("test", 10, time.Minute, middleware.WithFailClosed(true)) + allowed, err := limiter.Allow(context.Background(), "1.2.3.4") + if allowed { + t.Error("fail-closed no-redis should deny") + } + if !errors.Is(err, middleware.ErrRedisRateLimiterUnavailable) { + t.Errorf("fail-closed no-redis err = %v, want ErrRedisRateLimiterUnavailable", err) + } +} + +// 回归 H4c-1c：Redis 故障（关闭 miniredis）时 fail-open 放行、fail-closed 拒绝。 +// 这是 H4c 核心——登录防爆破场景下 fail-closed 防限流静默失效。 +func TestRedisRateLimiterFailClosedOnRedisError(t *testing.T) { + mr := setupMiddlewareMiniRedis(t) + + // fail-open：正常时放行。 + openLimiter := middleware.NewRedisRateLimiter("test_open", 10, time.Minute) + allowed, err := openLimiter.Allow(context.Background(), "1.2.3.4") + if err != nil { + t.Fatalf("fail-open normal err = %v", err) + } + if !allowed { + t.Error("fail-open normal should allow") + } + + // fail-closed：正常时放行。 + closedLimiter := middleware.NewRedisRateLimiter("test_closed", 10, time.Minute, middleware.WithFailClosed(true)) + allowed, err = closedLimiter.Allow(context.Background(), "1.2.3.4") + if err != nil { + t.Fatalf("fail-closed normal err = %v", err) + } + if !allowed { + t.Error("fail-closed normal should allow") + } + + // 关闭 miniredis 模拟 Redis 故障。 + mr.Close() + + // fail-open：故障时放行（兼容旧行为）。 + allowed, _ = openLimiter.Allow(context.Background(), "1.2.3.4") + if !allowed { + t.Error("fail-open on redis error should allow (兼容旧行为)") + } + + // fail-closed：故障时拒绝（H4c 安全语义）。 + allowed, err = closedLimiter.Allow(context.Background(), "1.2.3.4") + if allowed { + t.Error("fail-closed on redis error should deny (H4c: 防限流静默失效)") + } + if err == nil { + t.Error("fail-closed on redis error should return non-nil err") + } +} + +// 回归 H4c-1d：fail-closed 中间件在 Redis 故障时返 503（区别于真实超限的 429）。 +func TestRedisRateLimitFailClosedMiddlewareReturns503(t *testing.T) { + prev := database.SetTestRedisClient(nil) + defer func() { database.SetTestRedisClient(prev) }() + + r := setupTestRouter() + r.Use(middleware.RedisRateLimit("login_limit", 10, middleware.WithFailClosed(true))) + r.GET("/login", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("POST", "/login", nil)) + + if w.Code != http.StatusServiceUnavailable { + t.Errorf("fail-closed middleware (no redis) status = %d, want 503", w.Code) + } + var body response.Response + if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil { + t.Fatalf("decode body: %v", err) + } + if body.Code != response.CodeServiceUnavailable { + t.Errorf("fail-closed middleware code = %d, want %d", body.Code, response.CodeServiceUnavailable) + } +} + +// 回归 H4c-1e：fail-open 中间件在 Redis 故障时放行（兼容旧行为）。 +func TestRedisRateLimitFailOpenMiddlewareAllowsOnError(t *testing.T) { + prev := database.SetTestRedisClient(nil) + defer func() { database.SetTestRedisClient(prev) }() + + r := setupTestRouter() + r.Use(middleware.RedisRateLimit("api_limit", 100)) + r.GET("/api", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/api", nil)) + + if w.Code != 200 { + t.Errorf("fail-open middleware (no redis) status = %d, want 200", w.Code) + } +} + +// 回归 H4c-2：真实 Redis 闭环——超限被拦（429），未超限放行。 +// 用 miniredis 验证滑动窗口 Lua 脚本与 comma-ok 断言路径在真实 Redis 下正常。 +func TestRedisRateLimiterRealRedisLimitCycle(t *testing.T) { + setupMiddlewareMiniRedis(t) + + limiter := middleware.NewRedisRateLimiter("cycle_limit", 3, time.Minute) + ctx := context.Background() + + // 前 3 次放行。 + for i := 0; i < 3; i++ { + allowed, err := limiter.Allow(ctx, "1.2.3.4") + if err != nil { + t.Fatalf("request %d err = %v", i, err) + } + if !allowed { + t.Errorf("request %d should be allowed", i) + } + } + // 第 4 次拒绝（超限）。 + allowed, err := limiter.Allow(ctx, "1.2.3.4") + if err != nil { + t.Fatalf("over-limit err = %v", err) + } + if allowed { + t.Error("request 4 should be denied (over limit)") + } +} + +// 回归 H4c-2：comma-ok 断言防护——Redis 返回非 int64 时不 panic 而返错。 +// miniredis 的 slidingWindowLua 恒返 int64，无法经 Allow 触发断言失败路径； +// 此处直接用返回字符串的 Lua 脚本验证 result.(int64) 的 comma-ok 行为， +// 并对照证明裸断言会 panic（H4c-2 缺陷根因）。 +func TestRedisRateLimiterCommaOkAssertion(t *testing.T) { + setupMiddlewareMiniRedis(t) + ctx := context.Background() + + // miniredis 执行返回字符串的脚本——模拟 Redis 返回非 int64 结果。 + res, err := database.GetRedis().Eval(ctx, `return 'not-an-int'`, nil).Result() + if err != nil { + t.Fatalf("eval err = %v", err) + } + + // 对照：裸断言在非 int64 时 panic。 + var barePanicked bool + func() { + defer func() { + if r := recover(); r != nil { + barePanicked = true + } + }() + _ = res.(int64) // 旧实现行：裸断言 + }() + if !barePanicked { + t.Error("bare assertion res.(int64) should panic on non-int64 (H4c-2 缺陷根因)") + } + + // 修复：comma-ok 不 panic，返 ok=false。 + if _, ok := res.(int64); ok { + t.Error("comma-ok should return ok=false for non-int64 result") + } +} + +// 回归 H4c-2：SetFailClosed 切换策略——fail-open 限流器切 fail-closed 后无 Redis 拒绝。 +func TestRedisRateLimiterSetFailClosed(t *testing.T) { + prev := database.SetTestRedisClient(nil) + defer func() { database.SetTestRedisClient(prev) }() + + limiter := middleware.NewRedisRateLimiter("test", 10, time.Minute) + // 初始 fail-open：放行。 + if allowed, _ := limiter.Allow(context.Background(), "1.2.3.4"); !allowed { + t.Error("initial fail-open should allow") + } + // 切换 fail-closed：拒绝。 + limiter.SetFailClosed(true) + if allowed, err := limiter.Allow(context.Background(), "1.2.3.4"); allowed { + t.Error("after SetFailClosed(true) should deny") + } else if !errors.Is(err, middleware.ErrRedisRateLimiterUnavailable) { + t.Errorf("after SetFailClosed err = %v, want ErrRedisRateLimiterUnavailable", err) + } +} diff --git a/middleware/ratelimit.go b/middleware/ratelimit.go new file mode 100644 index 0000000..76963f4 --- /dev/null +++ b/middleware/ratelimit.go @@ -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) + } +} diff --git a/middleware/ratelimit_phase5_internal_test.go b/middleware/ratelimit_phase5_internal_test.go new file mode 100644 index 0000000..081ff45 --- /dev/null +++ b/middleware/ratelimit_phase5_internal_test.go @@ -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)") + }} diff --git a/middleware/recover.go b/middleware/recover.go new file mode 100644 index 0000000..ea1f722 --- /dev/null +++ b/middleware/recover.go @@ -0,0 +1,88 @@ +package middleware + +import ( + "fmt" + "net/http" + "runtime/debug" + + "github.com/EthanCodeCraft/xlgo-core/logger" + "github.com/EthanCodeCraft/xlgo-core/response" + "github.com/gin-gonic/gin" + "go.uber.org/zap" +) + +// Recover panic恢复中间件，捕获panic并返回统一错误响应 +func Recover() gin.HandlerFunc { + return func(c *gin.Context) { + defer func() { + if err := recover(); err != nil { + // 获取请求ID + requestID := GetRequestID(c) + + // 记录错误日志 + logger.Error("panic 已恢复", + zap.String("request_id", requestID), + zap.String("error", fmt.Sprintf("%v", err)), + zap.String("path", c.Request.URL.Path), + zap.String("method", c.Request.Method), + zap.String("stack", string(debug.Stack())), + ) + + // 返回错误响应。 + // 必须用 response.Custom 显式写 HTTP 500：FailWithCode 经 writeResp→httpStatusFor， + // 在默认 ModeBusiness 下对 CodeServerError 返回 200，c.JSON(200,...) 会先 flush + // 锁定状态，随后 AbortWithStatus(500) 因 w.Written()==true 沦为 no-op， + // 导致客户端收到 HTTP 200 + body code:500，网关/APM 按 status 看不到 panic。 + // Custom 不受 Mode 影响，直接写 500 且保留 RequestID。 + // + // M-B 修复：若 panic 发生在响应已开始写出之后（流式/部分写），c.Writer.Written()==true， + // gin 拒绝再次写响应，response.Custom 沦为 no-op，客户端会收到截断响应而非 500。 + // 此时不再尝试写 500（无效），仅 Abort + 记录，避免无意义的二次写入。 + if !c.Writer.Written() { + response.Custom(c, http.StatusInternalServerError, response.CodeServerError, "服务器内部错误", nil) + } else { + logger.Warn("panic 发生在响应已开始写入后，无法写入 500，客户端将收到截断响应", + zap.String("request_id", requestID), + zap.String("path", c.Request.URL.Path), + zap.Int("bytes_written", c.Writer.Size()), + ) + } + c.Abort() + } + }() + c.Next() + } +} + +// RecoverWithDetail panic恢复中间件（详细版本，返回更多信息） +// 注意: 生产环境不应使用，会暴露敏感信息 +func RecoverWithDetail() gin.HandlerFunc { + return func(c *gin.Context) { + defer func() { + if err := recover(); err != nil { + requestID := GetRequestID(c) + + logger.Error("panic 已恢复", + zap.String("request_id", requestID), + zap.String("error", fmt.Sprintf("%v", err)), + zap.String("path", c.Request.URL.Path), + zap.String("method", c.Request.Method), + zap.String("stack", string(debug.Stack())), + ) + + // 开发环境返回详细错误。同样用 Custom 显式写 500（见 Recover 注释）。 + // M-B 修复：响应已写出时不重复写 500（同 Recover）。 + if !c.Writer.Written() { + response.Custom(c, http.StatusInternalServerError, response.CodeServerError, fmt.Sprintf("服务器内部错误: %v", err), nil) + } else { + logger.Warn("panic 发生在响应已开始写入后，无法写入 500，客户端将收到截断响应", + zap.String("request_id", requestID), + zap.String("path", c.Request.URL.Path), + ) + } + c.Abort() + } + }() + c.Next() + } +} \ No newline at end of file diff --git a/middleware/requestid.go b/middleware/requestid.go new file mode 100644 index 0000000..8323936 --- /dev/null +++ b/middleware/requestid.go @@ -0,0 +1,49 @@ +package middleware + +import ( + "github.com/EthanCodeCraft/xlgo-core/utils" + "github.com/gin-gonic/gin" +) + +// 请求 ID 校验约束（M15 修复：不无条件信任客户端 X-Request-ID，防头注入/日志伪造）。 +const ( + // requestIDMaxLen 客户端传入请求 ID 的最大长度。超长视为非法并重新生成，避免日志膨胀/注入。 + requestIDMaxLen = 128 +) + +// sanitizeRequestID 校验客户端传入的 X-Request-ID：仅允许可见 ASCII（0x20-0x7e）且 +// 不含 CR/LF（防 HTTP 头注入与日志换行伪造），长度不超过 requestIDMaxLen。 +// 非法或为空时返回 ""，由调用方重新生成。 +func sanitizeRequestID(id string) string { + if len(id) == 0 || len(id) > requestIDMaxLen { + return "" + } + for i := 0; i < len(id); i++ { + c := id[i] + if c < 0x20 || c > 0x7e { + return "" + } + } + return id +} + +// RequestID 请求ID中间件，为每个请求生成唯一ID便于追踪。 +// +// 客户端可经 X-Request-ID 头传入 ID 用于链路串联，但会做校验（M15 修复）： +// 仅接受可见 ASCII、无换行、长度 ≤128 的值，否则忽略并重新生成——防头注入与日志伪造。 +func RequestID() gin.HandlerFunc { + return func(c *gin.Context) { + requestID := sanitizeRequestID(c.GetHeader("X-Request-ID")) + if requestID == "" { + requestID = utils.UUID() + } + c.Set("request_id", requestID) + c.Header("X-Request-ID", requestID) + c.Next() + } +} + +// GetRequestID 从上下文获取请求ID +func GetRequestID(c *gin.Context) string { + return c.GetString("request_id") +} \ No newline at end of file diff --git a/middleware/timeout.go b/middleware/timeout.go new file mode 100644 index 0000000..7807a2f --- /dev/null +++ b/middleware/timeout.go @@ -0,0 +1,37 @@ +package middleware + +import ( + "context" + "time" + + "github.com/gin-gonic/gin" +) + +// Timeout 请求级超时中间件（#19）。 +// +// 与 http.Server.ReadTimeout（连接级）不同，这是业务级超时： +// 为每个请求的 context 设置 deadline，下游 GORM / Redis / HTTP 调用 +// 走 c.Request.Context() 即可级联取消，避免单个慢请求拖垮协程。 +// +// ⚠️ 软超时语义（M14 文档化）：本中间件仅注入带 deadline 的 ctx，不会主动中断 handler。 +// 生效前提是下游实际消费 ctx——GORM/Redis/HTTP 客户端等会响应 ctx 取消；但若 handler +// 是纯 CPU 循环、阻塞于不查 ctx 的调用、或不读 c.Request.Context()，则 deadline 到期 +// 也不会停。需要硬中断的场景请配合 http.Server.WriteTimeout 或在 handler 内显式 select ctx.Done。 +// +// 用法： +// +// r.Use(middleware.Timeout(5 * time.Second)) +// +// d <= 0 时不启用超时（直接 Next）。 +func Timeout(d time.Duration) gin.HandlerFunc { + return func(c *gin.Context) { + if d <= 0 { + c.Next() + return + } + ctx, cancel := context.WithTimeout(c.Request.Context(), d) + defer cancel() + c.Request = c.Request.WithContext(ctx) + c.Next() + } +} diff --git a/middleware/timeout_test.go b/middleware/timeout_test.go new file mode 100644 index 0000000..a309c4c --- /dev/null +++ b/middleware/timeout_test.go @@ -0,0 +1,72 @@ +package middleware_test + +import ( + "context" + "net/http" + "net/http/httptest" + "testing" + "time" + + "github.com/EthanCodeCraft/xlgo-core/middleware" + "github.com/gin-gonic/gin" +) + +func TestTimeoutAllowsFastHandler(t *testing.T) { + gin.SetMode(gin.TestMode) + r := gin.New() + r.Use(middleware.Timeout(time.Second)) + r.GET("/ok", func(c *gin.Context) { + c.Status(http.StatusOK) + }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/ok", nil)) + if w.Code != http.StatusOK { + t.Errorf("status = %d, want 200", w.Code) + } +} + +func TestTimeoutCancelsSlowHandler(t *testing.T) { + gin.SetMode(gin.TestMode) + r := gin.New() + r.Use(middleware.Timeout(50 * time.Millisecond)) + r.GET("/slow", func(c *gin.Context) { + select { + case <-c.Request.Context().Done(): + // 超时取消生效 + return + case <-time.After(time.Second): + t.Error("handler should have been cancelled by timeout") + } + }) + + w := httptest.NewRecorder() + done := make(chan struct{}) + go func() { + r.ServeHTTP(w, httptest.NewRequest("GET", "/slow", nil)) + close(done) + }() + select { + case <-done: + case <-time.After(2 * time.Second): + t.Fatal("request did not return in time") + } +} + +func TestTimeoutZeroDisables(t *testing.T) { + gin.SetMode(gin.TestMode) + r := gin.New() + r.Use(middleware.Timeout(0)) // 不启用 + ctxCancelled := false + r.GET("/x", func(c *gin.Context) { + ctxCancelled = c.Request.Context() == context.Background() + _ = ctxCancelled + c.Status(http.StatusOK) + }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/x", nil)) + if w.Code != http.StatusOK { + t.Errorf("status = %d, want 200", w.Code) + } +} diff --git a/model/base.go b/model/base.go new file mode 100644 index 0000000..8f67b06 --- /dev/null +++ b/model/base.go @@ -0,0 +1,28 @@ +package model + +import ( + "time" + + "gorm.io/gorm" +) + +// BaseModel 基础模型。CreatedAt/UpdatedAt 不显式指定 type，由 GORM 按驱动选默认 +// 时间列类型（MySQL 通常为 datetime(6)，保留亚秒精度）。 +type BaseModel struct { + ID uint `gorm:"primaryKey" json:"id"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` + DeletedAt gorm.DeletedAt `gorm:"index" json:"-"` +} + +// BaseModelWithTime 显式指定时间列为 datetime 类型。 +// +// 命名注意（N1）：本类型与 BaseModel 的唯一区别是 CreatedAt/UpdatedAt 带 `gorm:"type:datetime"`， +// 二者都有时间戳——名字里的 "WithTime" 易误导。datetime 类型在部分 MySQL 版本下精度为秒 +// （丢毫秒），需毫秒精度请用 BaseModel 或显式 `type:datetime(3)`。保留此类型仅为向后兼容。 +type BaseModelWithTime struct { + ID uint `gorm:"primaryKey" json:"id"` + CreatedAt time.Time `gorm:"type:datetime" json:"created_at"` + UpdatedAt time.Time `gorm:"type:datetime" json:"updated_at"` + DeletedAt gorm.DeletedAt `gorm:"index" json:"-"` +} diff --git a/repository/page_internal_test.go b/repository/page_internal_test.go new file mode 100644 index 0000000..622edf8 --- /dev/null +++ b/repository/page_internal_test.go @@ -0,0 +1,72 @@ +package repository + +import ( + "strings" + "testing" + + "gorm.io/driver/mysql" + "gorm.io/gorm" + gormlogger "gorm.io/gorm/logger" +) + +type pageCountModel struct { + gorm.Model + Name string +} + +// newDryRunDB 用 mysql 驱动 + DryRun 模式构造一个不实际连接数据库的 GORM 实例， +// 仅用于校验生成的 SQL。SkipInitializeWithVersion 避免初始化时执行 SELECT VERSION()。 +func newDryRunDB(t *testing.T) *gorm.DB { + t.Helper() + db, err := gorm.Open(mysql.New(mysql.Config{ + DSN: "root:root@tcp(127.0.0.1:3306)/test?parseTime=true", + SkipInitializeWithVersion: true, + }), &gorm.Config{ + DryRun: true, + DisableAutomaticPing: true, + Logger: gormlogger.Default.LogMode(gormlogger.Silent), + SkipDefaultTransaction: true, + }) + if err != nil { + t.Fatalf("open dry-run db: %v", err) + } + return db +} + +// TestQueryBuilderPageCountStripsLimit 验证 Page 的 Count 不受残留 Limit/Offset 影响。 +// 修复前：count SQL 会被包成子查询并带上 LIMIT，导致统计行数被截断。 +// 修复后：count SQL 不应包含 LIMIT。 +func TestQueryBuilderPageCountStripsLimit(t *testing.T) { + db := newDryRunDB(t) + repo := NewBaseRepo[pageCountModel](db) + + qb := repo.NewQueryBuilder(). + Where("name = ?", "foo"). + Limit(10). + Offset(5) + + // 复刻 Page 内部的统计路径（已修复） + countDB := qb.db.Session(&gorm.Session{}).Limit(-1).Offset(-1) + var total int64 + result := countDB.Session(&gorm.Session{}).Count(&total) + sql := result.Statement.SQL.String() + + if strings.Contains(strings.ToUpper(sql), "LIMIT") { + t.Errorf("count SQL should not contain LIMIT (residual limit would truncate total), got: %s", sql) + } +} + +// TestQueryBuilderPageFindKeepsLimit 验证查询路径仍然带分页 Limit（回归保护）。 +func TestQueryBuilderPageFindKeepsLimit(t *testing.T) { + db := newDryRunDB(t) + repo := NewBaseRepo[pageCountModel](db) + + qb := repo.NewQueryBuilder().Where("name = ?", "foo") + var models []pageCountModel + result := qb.db.Session(&gorm.Session{}).Limit(10).Offset(5).Find(&models) + sql := strings.ToUpper(result.Statement.SQL.String()) + + if !strings.Contains(sql, "LIMIT") { + t.Errorf("find SQL should contain LIMIT for pagination, got: %s", sql) + } +} diff --git a/repository/repository.go b/repository/repository.go new file mode 100644 index 0000000..9c7ce6e --- /dev/null +++ b/repository/repository.go @@ -0,0 +1,718 @@ +package repository + +import ( + "context" + "errors" + "strings" + "unicode" + + "github.com/EthanCodeCraft/xlgo-core/database" + "gorm.io/gorm" +) + +const ( + // DefaultFindAllLimit caps FindAll to avoid accidental full-table scans. + DefaultFindAllLimit = 1000 + // DefaultPageSize is used when pageSize<=0. + DefaultPageSize = 20 + // MaxPageSize caps page queries to avoid Limit(0)/huge-limit footguns. + MaxPageSize = 100 + // MaxPage caps deep-offset queries; deeper traversal should use keyset pagination. + MaxPage = 10000 +) + +var ( + ErrUnsafeOrder = errors.New("repository: unsafe order clause") + ErrUnsafeField = errors.New("repository: unsafe field name") +) + +// BaseRepository 基础仓库接口 +type BaseRepository[T any] interface { + // FindByID 根据 ID 查询 + FindByID(ctx context.Context, id uint) (*T, error) + // Create 创建记录 + Create(ctx context.Context, model *T) error + // Update 更新记录 + Update(ctx context.Context, model *T) error + // Delete 删除记录（T 含软删除字段时为软删除，否则为硬删除；详见 BaseRepo.Delete） + Delete(ctx context.Context, id uint) error + // FindByIDs 批量查询 + FindByIDs(ctx context.Context, ids []uint) ([]T, error) +} + +// BaseRepo 基础仓库实现。 +// +// 连接路由契约（H6c 修复）： +// - 读操作经 readConn(ctx) 路由：优先 join 外层事务，否则走 database.GetDBFromContext +// （默认从库，支持 UseMaster/UseReplica 读写分离），DefaultManager 未初始化时回退 r.db。 +// - 写操作经 writeConn(ctx) 路由：优先 join 外层事务，否则走主库 database.GetWriteDB()， +// 回退 r.db。写操作不路由到从库（从库只读）。 +// - 事务内（WithTransaction 创建的 txRepo）所有方法 join 同一事务。 +// +// 下游典型用法 NewBaseRepo[T](database.GetDB()) 仍兼容：GetDB 返回主库，DefaultManager +// 初始化后读操作自动路由到从库；未初始化（如单测注入 sqlite）时回退到 r.db。 +type BaseRepo[T any] struct { + db *gorm.DB + // tx 在事务内（WithTransaction）非 nil，使 txRepo 的方法 join 该事务而非另开连接/路由。 + tx *gorm.DB +} + +// NewBaseRepo 创建基础仓库 +func NewBaseRepo[T any](db *gorm.DB) *BaseRepo[T] { + return &BaseRepo[T]{db: db} +} + +func normalizeContext(ctx context.Context) context.Context { + if ctx == nil { + return context.Background() + } + return ctx +} + +func (r *BaseRepo[T]) requireDB() *gorm.DB { + if r.db == nil { + panic("repository.BaseRepo: db is nil. Use NewBaseRepo with a valid *gorm.DB") + } + return r.db +} + +// readConn 返回读连接：先校验 repo 构造时注入的 r.db 非 nil，再按 +// 外层 ctx 事务 > 本 repo 事务 > 读写分离路由 > r.db 回退。 +// RP1 修复：r.db 为 nil 时 panic 并给出明确消息，即使 ctx 携带外层事务也要求 repo 构造合法。 +func (r *BaseRepo[T]) readConn(ctx context.Context) *gorm.DB { + ctx = normalizeContext(ctx) + base := r.requireDB() + if tx := database.TxFromContext(ctx); tx != nil { + return tx.WithContext(ctx) + } + if r.tx != nil { + return r.tx.WithContext(ctx) + } + if gdb := database.GetDBFromContext(ctx); gdb != nil { + return gdb.WithContext(ctx) + } + return base.WithContext(ctx) +} + +// writeConn 返回写连接：先校验 repo 构造时注入的 r.db 非 nil，再按 +// 外层 ctx 事务 > 本 repo 事务 > 主库 > r.db 回退。 +// 写操作始终走主库，不路由到只读从库。 +// RP1 修复：r.db 为 nil 时 panic 并给出明确消息，即使 ctx 携带外层事务也要求 repo 构造合法。 +func (r *BaseRepo[T]) writeConn(ctx context.Context) *gorm.DB { + ctx = normalizeContext(ctx) + base := r.requireDB() + if tx := database.TxFromContext(ctx); tx != nil { + return tx.WithContext(ctx) + } + if r.tx != nil { + return r.tx.WithContext(ctx) + } + if mdb := database.GetWriteDB(); mdb != nil { + return mdb.WithContext(ctx) + } + return base.WithContext(ctx) +} + +// FindByID 根据 ID 查询 +func (r *BaseRepo[T]) FindByID(ctx context.Context, id uint) (*T, error) { + var model T + err := r.readConn(ctx).First(&model, id).Error + if err != nil { + return nil, err + } + return &model, nil +} + +// Create 创建记录 +func (r *BaseRepo[T]) Create(ctx context.Context, model *T) error { + return r.writeConn(ctx).Create(model).Error +} + +// Update 更新记录（全列覆写，基于 Save）。 +// +// 注意（H6a）：Save 会写入所有字段（包括零值），无法区分"未设置"与"清零"， +// 且可能用零值覆盖并发更新。需要局部更新（仅更新非零字段或指定字段）请用 UpdateFields。 +func (r *BaseRepo[T]) Update(ctx context.Context, model *T) error { + return r.writeConn(ctx).Save(model).Error +} + +// UpdateFields 局部更新（H6a）：基于 gorm.Updates，仅更新非零字段（struct）或指定字段（map）。 +// +// - 传 struct：仅更新非零字段（零值被忽略，避免覆盖）。 +// - 传 map[string]any：更新指定字段（可显式置零）。 +// +// 示例： +// +// repo.UpdateFields(ctx, &User{Name: "new"}) // struct：仅更新非零字段 name +// repo.UpdateFields(ctx, map[string]any{"status": 0}, "id = ?", id) // map：显式置零，带条件 +func (r *BaseRepo[T]) UpdateFields(ctx context.Context, model any, conds ...any) error { + db := r.writeConn(ctx).Model(new(T)) + if len(conds) > 0 { + db = db.Where(conds[0], conds[1:]...) + } + return db.Updates(model).Error +} + +// Delete 删除记录。 +// +// 行为契约（H6b）：若 T 内嵌 gorm.DeletedAt（或 gorm.Model），为软删除； +// 否则为硬删除（泛型类型约束无法在编译期强制）。需硬删用 HardDelete，需恢复用 Restore。 +func (r *BaseRepo[T]) Delete(ctx context.Context, id uint) error { + return r.writeConn(ctx).Delete(new(T), id).Error +} + +// HardDelete 硬删除记录（物理删除） +func (r *BaseRepo[T]) HardDelete(ctx context.Context, id uint) error { + return r.writeConn(ctx).Unscoped().Delete(new(T), id).Error +} + +// FindByIDs 批量查询 +func (r *BaseRepo[T]) FindByIDs(ctx context.Context, ids []uint) ([]T, error) { + if len(ids) == 0 { + return []T{}, nil + } + var models []T + err := r.readConn(ctx).Where("id IN ?", ids).Find(&models).Error + return models, err +} + +// FindAll 查询记录，默认最多返回 DefaultFindAllLimit 条，避免误用导致全表扫描。 +// 需要明确全量扫描时使用 FindAllUnbounded。 +func (r *BaseRepo[T]) FindAll(ctx context.Context) ([]T, error) { + return r.FindLimited(ctx, DefaultFindAllLimit) +} + +// FindAllUnbounded 查询所有记录（无默认 limit）。 +// 仅用于明确需要全表扫描的后台任务/小表场景；在线请求优先使用分页或 FindAll。 +func (r *BaseRepo[T]) FindAllUnbounded(ctx context.Context) ([]T, error) { + var models []T + err := r.readConn(ctx).Find(&models).Error + return models, err +} + +// Count 统计数量 +func (r *BaseRepo[T]) Count(ctx context.Context) (int64, error) { + var count int64 + err := r.readConn(ctx).Model(new(T)).Count(&count).Error + return count, err +} + +// CountWhere 条件统计 +func (r *BaseRepo[T]) CountWhere(ctx context.Context, query string, args ...any) (int64, error) { + var count int64 + err := r.readConn(ctx).Model(new(T)).Where(query, args...).Count(&count).Error + return count, err +} + +// GetDB 获取数据库实例。 +// 事务内（txRepo）返回当前事务的 tx；否则返回构造时注入的 db。 +// 注意：此方法无 ctx 参数，不参与读写分离路由；需要路由请用具体方法（FindByID/FindPage 等）。 +func (r *BaseRepo[T]) GetDB() *gorm.DB { + if r.tx != nil { + return r.tx + } + return r.db +} + +// ===== 扩展查询功能 ===== + +// FindOne 条件查询单条记录 +func (r *BaseRepo[T]) FindOne(ctx context.Context, query string, args ...any) (*T, error) { + var model T + err := r.readConn(ctx).Where(query, args...).First(&model).Error + if err != nil { + return nil, err + } + return &model, nil +} + +// FindWhere 条件查询多条记录 +func (r *BaseRepo[T]) FindWhere(ctx context.Context, query string, args ...any) ([]T, error) { + var models []T + err := r.readConn(ctx).Where(query, args...).Find(&models).Error + return models, err +} + +// FindWhereOrdered 条件查询并排序。 +// +// H-15 修复（breaking）：签名由 (ctx, query, args []any, order) 改为 +// (ctx, order, query string, args ...any)，与 FindWhere 等同类方法统一为变长 args。 +// Go 语法要求变长参数必须为最后一个，故 order 前置于 query。 +func (r *BaseRepo[T]) FindWhereOrdered(ctx context.Context, order, query string, args ...any) ([]T, error) { + if err := validateOrderClause(order); err != nil { + return nil, err + } + var models []T + err := r.readConn(ctx).Where(query, args...).Order(order).Find(&models).Error + return models, err +} + +// FindOrdered 查询并排序 +func (r *BaseRepo[T]) FindOrdered(ctx context.Context, order string, limit int) ([]T, error) { + if err := validateOrderClause(order); err != nil { + return nil, err + } + var models []T + query := r.readConn(ctx).Order(order) + if limit > 0 { + query = query.Limit(limit) + } + err := query.Find(&models).Error + return models, err +} + +// FindLimited 查询指定数量记录 +func (r *BaseRepo[T]) FindLimited(ctx context.Context, limit int) ([]T, error) { + if limit <= 0 { + return []T{}, nil + } + var models []T + err := r.readConn(ctx).Limit(limit).Find(&models).Error + return models, err +} + +// ===== 分页查询 ===== + +// PageResult 分页结果 +type PageResult[T any] struct { + Items []T `json:"items"` + Total int64 `json:"total"` + Page int `json:"page"` + PageSize int `json:"page_size"` +} + +func normalizePage(page, pageSize int) (int, int) { + if page < 1 { + page = 1 + } + if page > MaxPage { + page = MaxPage + } + if pageSize <= 0 { + pageSize = DefaultPageSize + } + if pageSize > MaxPageSize { + pageSize = MaxPageSize + } + return page, pageSize +} + +// pageOffset 计算 (page-1)*pageSize，负值归零。 +func pageOffset(page, pageSize int) int { + page, pageSize = normalizePage(page, pageSize) + offset := (page - 1) * pageSize + if offset < 0 { + offset = 0 + } + return offset +} + +// FindPage 分页查询。 +// +// count 与 list 包进单事务（H6d），保证 total 与 items 在同一快照下一致， +// 避免高并发下两条独立语句间数据变动致 total/items 不一致。 +// +// 若 ctx 已携带外层事务（database.WithTx），readConn 返回该 tx，此处 .Transaction +// 在其上开 savepoint（gorm 行为），count+list 仍同快照一致；无外层事务则开独立读事务。 +func (r *BaseRepo[T]) FindPage(ctx context.Context, page, pageSize int) (*PageResult[T], error) { + var models []T + var total int64 + page, pageSize = normalizePage(page, pageSize) + offset := pageOffset(page, pageSize) + err := r.readConn(ctx).Transaction(func(tx *gorm.DB) error { + if e := tx.Model(new(T)).Count(&total).Error; e != nil { + return e + } + return tx.Offset(offset).Limit(pageSize).Find(&models).Error + }) + if err != nil { + return nil, err + } + return &PageResult[T]{Items: models, Total: total, Page: page, PageSize: pageSize}, nil +} + +// FindPageOrdered 分页查询并排序（count+list 单事务，H6d） +func (r *BaseRepo[T]) FindPageOrdered(ctx context.Context, page, pageSize int, order string) (*PageResult[T], error) { + if err := validateOrderClause(order); err != nil { + return nil, err + } + var models []T + var total int64 + page, pageSize = normalizePage(page, pageSize) + offset := pageOffset(page, pageSize) + err := r.readConn(ctx).Transaction(func(tx *gorm.DB) error { + if e := tx.Model(new(T)).Count(&total).Error; e != nil { + return e + } + return tx.Order(order).Offset(offset).Limit(pageSize).Find(&models).Error + }) + if err != nil { + return nil, err + } + return &PageResult[T]{Items: models, Total: total, Page: page, PageSize: pageSize}, nil +} + +// FindPageWhere 条件分页查询（count+list 单事务，H6d） +func (r *BaseRepo[T]) FindPageWhere(ctx context.Context, page, pageSize int, query string, args ...any) (*PageResult[T], error) { + var models []T + var total int64 + page, pageSize = normalizePage(page, pageSize) + offset := pageOffset(page, pageSize) + err := r.readConn(ctx).Transaction(func(tx *gorm.DB) error { + if e := tx.Model(new(T)).Where(query, args...).Count(&total).Error; e != nil { + return e + } + return tx.Where(query, args...).Offset(offset).Limit(pageSize).Find(&models).Error + }) + if err != nil { + return nil, err + } + return &PageResult[T]{Items: models, Total: total, Page: page, PageSize: pageSize}, nil +} + +// FindPageWhereOrdered 条件分页查询并排序（count+list 单事务，H6d）。 +// +// H-15 修复（breaking）：签名由 (ctx, page, pageSize, query, args []any, order) 改为 +// (ctx, page, pageSize, order, query string, args ...any)，与 FindPageWhere 统一为变长 args。 +// Go 语法要求变长参数必须为最后一个，故 order 前置于 query。 +func (r *BaseRepo[T]) FindPageWhereOrdered(ctx context.Context, page, pageSize int, order, query string, args ...any) (*PageResult[T], error) { + if err := validateOrderClause(order); err != nil { + return nil, err + } + var models []T + var total int64 + page, pageSize = normalizePage(page, pageSize) + offset := pageOffset(page, pageSize) + err := r.readConn(ctx).Transaction(func(tx *gorm.DB) error { + if e := tx.Model(new(T)).Where(query, args...).Count(&total).Error; e != nil { + return e + } + return tx.Where(query, args...).Order(order).Offset(offset).Limit(pageSize).Find(&models).Error + }) + if err != nil { + return nil, err + } + return &PageResult[T]{Items: models, Total: total, Page: page, PageSize: pageSize}, nil +} + +// ===== 批量操作 ===== + +// CreateBatch 批量创建 +func (r *BaseRepo[T]) CreateBatch(ctx context.Context, models []T) error { + return r.writeConn(ctx).Create(models).Error +} + +// UpdateBatch 批量更新（指定字段） +func (r *BaseRepo[T]) UpdateBatch(ctx context.Context, ids []uint, field string, value any) error { + if len(ids) == 0 { + return nil + } + if err := validateIdentifier(field); err != nil { + return err + } + return r.writeConn(ctx).Model(new(T)).Where("id IN ?", ids).Update(field, value).Error +} + +// DeleteBatch 批量删除 +func (r *BaseRepo[T]) DeleteBatch(ctx context.Context, ids []uint) error { + if len(ids) == 0 { + return nil + } + return r.writeConn(ctx).Delete(new(T), ids).Error +} + +// HardDeleteBatch 批量硬删除 +func (r *BaseRepo[T]) HardDeleteBatch(ctx context.Context, ids []uint) error { + if len(ids) == 0 { + return nil + } + return r.writeConn(ctx).Unscoped().Delete(new(T), ids).Error +} + +// ===== 存在性检查 ===== + +// Exists 检查是否存在 +func (r *BaseRepo[T]) Exists(ctx context.Context, id uint) (bool, error) { + var count int64 + err := r.readConn(ctx).Model(new(T)).Where("id = ?", id).Count(&count).Error + return count > 0, err +} + +// ExistsWhere 条件检查是否存在 +func (r *BaseRepo[T]) ExistsWhere(ctx context.Context, query string, args ...any) (bool, error) { + var count int64 + err := r.readConn(ctx).Model(new(T)).Where(query, args...).Limit(1).Count(&count).Error + return count > 0, err +} + +// ===== 软删除操作 ===== + +// SoftDeleteColumn 返回软删除列名（RP2 修复：可被子类覆盖以适配自定义列名）。 +// 默认 "deleted_at"，与 GORM gorm.DeletedAt 的默认列名一致。 +func (r *BaseRepo[T]) SoftDeleteColumn() string { + return "deleted_at" +} + +// Restore 恢复软删除记录 +func (r *BaseRepo[T]) Restore(ctx context.Context, id uint) error { + if err := validateIdentifier(r.SoftDeleteColumn()); err != nil { + return err + } + return r.writeConn(ctx).Model(new(T)).Unscoped().Where("id = ?", id).Update(r.SoftDeleteColumn(), nil).Error +} + +// RestoreBatch 批量恢复软删除记录 +func (r *BaseRepo[T]) RestoreBatch(ctx context.Context, ids []uint) error { + if len(ids) == 0 { + return nil + } + if err := validateIdentifier(r.SoftDeleteColumn()); err != nil { + return err + } + return r.writeConn(ctx).Model(new(T)).Unscoped().Where("id IN ?", ids).Update(r.SoftDeleteColumn(), nil).Error +} + +// FindDeleted 查询已软删除的记录 +func (r *BaseRepo[T]) FindDeleted(ctx context.Context) ([]T, error) { + if err := validateIdentifier(r.SoftDeleteColumn()); err != nil { + return nil, err + } + var models []T + err := r.readConn(ctx).Unscoped().Where(r.SoftDeleteColumn() + " IS NOT NULL").Find(&models).Error + return models, err +} + +// FindAllWithDeleted 查询所有记录（包括软删除） +func (r *BaseRepo[T]) FindAllWithDeleted(ctx context.Context) ([]T, error) { + var models []T + err := r.readConn(ctx).Unscoped().Find(&models).Error + return models, err +} + +// ===== 事务支持 ===== + +// WithTransaction 在事务中执行操作。 +// +// fn 收到的 txRepo 处于事务内，其所有方法（FindByID/Create/Update/...）自动 join 该事务， +// 不再路由到主从库（H6c）。事务在主库上开启。 +// +// 跨 repo / 跨层 join：若 fn 内需调用其它 repo 或 database 层方法参与同一事务， +// 用 database.WithTx(ctx, tx) 把事务注入 ctx 后传递： +// +// return repo.WithTransaction(ctx, func(txRepo *BaseRepo[T]) error { +// if err := txRepo.Create(ctx, a); err != nil { return err } +// // 另一个 repo 也加入同一事务： +// ctx2 := database.WithTx(ctx, txRepo.GetDB()) +// return otherRepo.Update(ctx2, b) +// }) +// +// 注：fn 内捕获的 ctx 不会自动携带 tx；仅 txRepo 的方法 join 事务。 +func (r *BaseRepo[T]) WithTransaction(ctx context.Context, fn func(txRepo *BaseRepo[T]) error) error { + return r.writeConn(ctx).Transaction(func(tx *gorm.DB) error { + txRepo := &BaseRepo[T]{db: r.db, tx: tx} + return fn(txRepo) + }) +} + +// ===== QueryBuilder 链式查询 ===== +// +// QueryBuilder 为单次使用、非并发安全（H6e）：链式方法 Where/Or/Order/Limit/Offset 会 +// mutate qb.db，禁止跨 goroutine 共用同一实例或多次终结调用复用累积条件。 +// 终结方法（Find/First/Count/Page）基于 Session 克隆，不污染 qb.db；Count 额外剥离 +// Limit/Offset 避免残留分页条件截断统计。 +// +// 路由：QueryBuilder 查询经构造时注入的 db（通常主库），不参与读写分离路由； +// 需读写分离请用具体方法（FindPage/FindWhere 等）。 + +// QueryBuilder 链式查询构建器 +type QueryBuilder[T any] struct { + db *gorm.DB + limit int + err error +} + +// NewQueryBuilder 创建查询构建器 +func (r *BaseRepo[T]) NewQueryBuilder() *QueryBuilder[T] { + return &QueryBuilder[T]{db: r.requireDB().Model(new(T))} +} + +// Where 添加条件 +func (qb *QueryBuilder[T]) Where(query string, args ...any) *QueryBuilder[T] { + qb.db = qb.db.Where(query, args...) + return qb +} + +// Or 添加 OR 条件 +func (qb *QueryBuilder[T]) Or(query string, args ...any) *QueryBuilder[T] { + qb.db = qb.db.Or(query, args...) + return qb +} + +// Order 设置排序 +func (qb *QueryBuilder[T]) Order(order string) *QueryBuilder[T] { + if qb.err != nil { + return qb + } + if err := validateOrderClause(order); err != nil { + qb.err = err + return qb + } + qb.db = qb.db.Order(order) + return qb +} + +// Limit 设置数量限制 +func (qb *QueryBuilder[T]) Limit(limit int) *QueryBuilder[T] { + if limit < 0 { + limit = 0 + } + qb.limit = limit + qb.db = qb.db.Limit(limit) + return qb +} + +// Offset 设置偏移量 +func (qb *QueryBuilder[T]) Offset(offset int) *QueryBuilder[T] { + qb.db = qb.db.Offset(offset) + return qb +} + +// clone 返回 qb.db 的 Session 克隆，确保终结方法不污染 qb.db（H6e）。 +func (qb *QueryBuilder[T]) clone() *gorm.DB { + return qb.db.Session(&gorm.Session{}) +} + +// Find 执行查询 +func (qb *QueryBuilder[T]) Find(ctx context.Context) ([]T, error) { + if qb.err != nil { + return nil, qb.err + } + ctx = normalizeContext(ctx) + var models []T + err := qb.clone().WithContext(ctx).Find(&models).Error + return models, err +} + +// First 执行查询并返回第一条 +func (qb *QueryBuilder[T]) First(ctx context.Context) (*T, error) { + if qb.err != nil { + return nil, qb.err + } + ctx = normalizeContext(ctx) + var model T + err := qb.clone().WithContext(ctx).First(&model).Error + if err != nil { + return nil, err + } + return &model, nil +} + +// Count 执行统计。 +// 克隆并剥离 Limit/Offset（H6e），避免先前 Limit()/Offset() 残留截断统计行数。 +func (qb *QueryBuilder[T]) Count(ctx context.Context) (int64, error) { + if qb.err != nil { + return 0, qb.err + } + ctx = normalizeContext(ctx) + var count int64 + err := qb.clone().Limit(-1).Offset(-1).WithContext(ctx).Count(&count).Error + return count, err +} + +// Page 执行分页查询。 +// count 与 list 基于同一 Session 克隆，count 剥离 Limit/Offset（H6e）。 +// 注意：与 FindPage 不同，Page 的 count+list 不包单事务（QueryBuilder 为轻量构建器）； +// 需要 total/items 快照一致请用 BaseRepo.FindPage。 +func (qb *QueryBuilder[T]) Page(ctx context.Context, page, pageSize int) (*PageResult[T], error) { + if qb.err != nil { + return nil, qb.err + } + ctx = normalizeContext(ctx) + var models []T + var total int64 + page, pageSize = normalizePage(page, pageSize) + + // count 克隆并剥离 Limit/Offset + countDB := qb.clone().Limit(-1).Offset(-1) + if err := countDB.WithContext(ctx).Count(&total).Error; err != nil { + return nil, err + } + + offset := pageOffset(page, pageSize) + if err := qb.clone().WithContext(ctx).Offset(offset).Limit(pageSize).Find(&models).Error; err != nil { + return nil, err + } + + return &PageResult[T]{ + Items: models, + Total: total, + Page: page, + PageSize: pageSize, + }, nil +} + +func validateIdentifier(field string) error { + if !isIdentifierPath(field) { + return ErrUnsafeField + } + return nil +} + +func isIdentifierPath(s string) bool { + s = strings.TrimSpace(s) + if s == "" { + return false + } + parts := strings.Split(s, ".") + for _, part := range parts { + if !isIdentifier(part) { + return false + } + } + return true +} + +func isIdentifier(s string) bool { + if s == "" { + return false + } + for i, r := range s { + if i == 0 { + if r != '_' && !unicode.IsLetter(r) { + return false + } + continue + } + if r != '_' && !unicode.IsLetter(r) && !unicode.IsDigit(r) { + return false + } + } + return true +} + +func validateOrderClause(order string) error { + order = strings.TrimSpace(order) + if order == "" { + return ErrUnsafeOrder + } + for _, raw := range strings.Split(order, ",") { + item := strings.TrimSpace(raw) + if item == "" { + return ErrUnsafeOrder + } + fields := strings.Fields(item) + if len(fields) == 0 || len(fields) > 2 { + return ErrUnsafeOrder + } + if !isIdentifierPath(fields[0]) { + return ErrUnsafeOrder + } + if len(fields) == 2 { + dir := strings.ToUpper(fields[1]) + if dir != "ASC" && dir != "DESC" { + return ErrUnsafeOrder + } + } + } + return nil +} diff --git a/repository/repository_h6_internal_test.go b/repository/repository_h6_internal_test.go new file mode 100644 index 0000000..1f4c982 --- /dev/null +++ b/repository/repository_h6_internal_test.go @@ -0,0 +1,491 @@ +package repository + +import ( + "context" + "errors" + "path/filepath" + "testing" + + "github.com/EthanCodeCraft/xlgo-core/config" + "github.com/EthanCodeCraft/xlgo-core/database" + "github.com/glebarez/sqlite" + "gorm.io/gorm" + gormlogger "gorm.io/gorm/logger" +) + +// h6User 测试模型，内嵌 gorm.Model 支持软删除。 +type h6User struct { + gorm.Model + Name string + Age int +} + +func init() { + // 注册 SQLite 方言，供路由测试通过 database 包级 facade（InitDB 等，代理到 DefaultManager）初始化主从库使用。 + database.RegisterDialect(database.DialectSpec{ + Name: "sqlite", + Aliases: []string{"sqlite3"}, + Dialector: func(dsn string) gorm.Dialector { return sqlite.Open(dsn) }, + }) +} + +// newH6SqliteDB 构造一个独立 sqlite 文件的 GORM 实例（不走 DefaultManager）， +// 用于 fallback 路径（DefaultManager 未初始化）的行为闭环测试。 +func newH6SqliteDB(t *testing.T) *gorm.DB { + t.Helper() + dir := t.TempDir() + db, err := gorm.Open(sqlite.Open(filepath.Join(dir, "test.db")), &gorm.Config{ + Logger: gormlogger.Default.LogMode(gormlogger.Silent), + }) + if err != nil { + t.Fatalf("open sqlite: %v", err) + } + if err := db.AutoMigrate(&h6User{}); err != nil { + t.Fatalf("migrate: %v", err) + } + t.Cleanup(func() { + if sqlDB, err := db.DB(); err == nil { + _ = sqlDB.Close() + } + }) + return db +} + +// namesFrom 提取 h6User 切片的 Name 集合，便于路由断言。 +func namesFrom(users []h6User) map[string]struct{} { + out := make(map[string]struct{}, len(users)) + for i := range users { + out[users[i].Name] = struct{}{} + } + return out +} + +// ===== H6c fallback 路径（DefaultManager 未初始化，readConn/writeConn 回退 r.db）===== + +// TestH6CrudRoundTrip 验证 CRUD 闭环经 readConn/writeConn 回退 r.db 正常工作。 +func TestH6CrudRoundTrip(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + + u := &h6User{Name: "alice", Age: 30} + if err := repo.Create(ctx, u); err != nil { + t.Fatalf("Create: %v", err) + } + if u.ID == 0 { + t.Fatal("ID not populated after Create") + } + + got, err := repo.FindByID(ctx, u.ID) + if err != nil { + t.Fatalf("FindByID: %v", err) + } + if got.Name != "alice" || got.Age != 30 { + t.Fatalf("unexpected user: %+v", got) + } + + got.Age = 31 + if err := repo.Update(ctx, got); err != nil { + t.Fatalf("Update: %v", err) + } + got2, _ := repo.FindByID(ctx, u.ID) + if got2.Age != 31 { + t.Fatalf("Update not persisted, age=%d", got2.Age) + } + + if err := repo.Delete(ctx, u.ID); err != nil { + t.Fatalf("Delete: %v", err) + } + if _, err := repo.FindByID(ctx, u.ID); !errors.Is(err, gorm.ErrRecordNotFound) { + t.Fatalf("after Delete want ErrRecordNotFound, got %v", err) + } +} + +// ===== H6a UpdateFields 局部更新 ===== + +// TestH6UpdateFieldsStructNonZeroOnly 传 struct 仅更新非零字段（零值 Age=0 不覆盖）。 +func TestH6UpdateFieldsStructNonZeroOnly(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + + u := &h6User{Name: "bob", Age: 30} + _ = repo.Create(ctx, u) + + // Name="carol"（非零），Age=0（零值，不应写入） + if err := repo.UpdateFields(ctx, &h6User{Name: "carol"}, "id = ?", u.ID); err != nil { + t.Fatalf("UpdateFields: %v", err) + } + got, _ := repo.FindByID(ctx, u.ID) + if got.Name != "carol" { + t.Fatalf("Name should be carol, got %q", got.Name) + } + if got.Age != 30 { + t.Fatalf("Age should remain 30 (struct zero-value not written), got %d", got.Age) + } +} + +// TestH6UpdateFieldsMapExplicitZero 传 map 可显式置零。 +func TestH6UpdateFieldsMapExplicitZero(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + + u := &h6User{Name: "dave", Age: 30} + _ = repo.Create(ctx, u) + + if err := repo.UpdateFields(ctx, map[string]any{"age": 0}, "id = ?", u.ID); err != nil { + t.Fatalf("UpdateFields map: %v", err) + } + got, _ := repo.FindByID(ctx, u.ID) + if got.Age != 0 { + t.Fatalf("Age should be 0 (map explicit zero), got %d", got.Age) + } +} + +// ===== H6c 事务 join：r.tx 字段（WithTransaction）===== + +// TestH6WithTransactionRollback fn 返回错误 → 回滚，已写记录不持久化。 +func TestH6WithTransactionRollback(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + + err := repo.WithTransaction(ctx, func(txRepo *BaseRepo[h6User]) error { + if e := txRepo.Create(ctx, &h6User{Name: "rollback"}); e != nil { + return e + } + return errors.New("boom") + }) + if err == nil { + t.Fatal("want error from WithTransaction") + } + + all, _ := repo.FindAll(ctx) + if _, ok := namesFrom(all)["rollback"]; ok { + t.Fatal("rollback row should not persist after failed tx") + } +} + +// TestH6WithTransactionCommit fn 成功 → 提交，记录持久化。 +func TestH6WithTransactionCommit(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + + err := repo.WithTransaction(ctx, func(txRepo *BaseRepo[h6User]) error { + return txRepo.Create(ctx, &h6User{Name: "commit"}) + }) + if err != nil { + t.Fatalf("WithTransaction: %v", err) + } + + all, _ := repo.FindAll(ctx) + if _, ok := namesFrom(all)["commit"]; !ok { + t.Fatal("commit row should persist after successful tx") + } +} + +// TestH6WithTransactionTxRepoJoinsTx fn 内 txRepo 的写与读都参与同一事务。 +// 关键：txRepo.Create 写入后，txRepo.FindOne 在事务内可见；若 txRepo 不 join tx +// （走 r.db 回退），FindOne 仍可见但写已 autocommit，回滚测试（上一用例）会失败。 +func TestH6WithTransactionTxRepoJoinsTx(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + + var seenInTx bool + err := repo.WithTransaction(ctx, func(txRepo *BaseRepo[h6User]) error { + if e := txRepo.Create(ctx, &h6User{Name: "in-tx"}); e != nil { + return e + } + got, e := txRepo.FindOne(ctx, "name = ?", "in-tx") + if e != nil { + return e + } + seenInTx = got != nil && got.Name == "in-tx" + return nil + }) + if err != nil { + t.Fatalf("WithTransaction: %v", err) + } + if !seenInTx { + t.Fatal("txRepo.FindOne should see row created within the same tx") + } +} + +// ===== H6c 事务 join：ctx 携带 tx（database.WithTx 跨层 join）===== + +// TestH6WithTxCtxJoinsOuterTx 外层 gorm 事务通过 database.WithTx 注入 ctx， +// repo 方法必须 join 该事务；外层回滚则 repo 写入随之回滚。 +// 红绿：修复前 repo 走 r.db（fallback）autocommit，回滚后行仍存在（红）； +// 修复后 repo 取 ctx 的 tx，随外层回滚（绿）。 +func TestH6WithTxCtxJoinsOuterTx(t *testing.T) { + db := newH6SqliteDB(t) + repo := NewBaseRepo[h6User](db) + ctx := context.Background() + + err := db.Transaction(func(tx *gorm.DB) error { + ctx2 := database.WithTx(ctx, tx) + if e := repo.Create(ctx2, &h6User{Name: "outer-tx"}); e != nil { + return e + } + return errors.New("force rollback") + }) + if err == nil { + t.Fatal("want error from outer tx") + } + + all, _ := repo.FindAll(ctx) + if _, ok := namesFrom(all)["outer-tx"]; ok { + t.Fatal("outer-tx row should be rolled back when repo joins outer tx") + } +} + +// TestH6WithTxCtxCommitsWhenOuterCommits 外层提交则 repo 写入持久化（正向闭环）。 +func TestH6WithTxCtxCommitsWhenOuterCommits(t *testing.T) { + db := newH6SqliteDB(t) + repo := NewBaseRepo[h6User](db) + ctx := context.Background() + + err := db.Transaction(func(tx *gorm.DB) error { + ctx2 := database.WithTx(ctx, tx) + return repo.Create(ctx2, &h6User{Name: "outer-commit"}) + }) + if err != nil { + t.Fatalf("outer tx: %v", err) + } + + all, _ := repo.FindAll(ctx) + if _, ok := namesFrom(all)["outer-commit"]; !ok { + t.Fatal("outer-commit row should persist when outer tx commits") + } +} + +// ===== H6d 分页 count+list 单事务 + 基本正确性 ===== + +// TestH6FindPage 验证分页 total 与 items 正确。 +func TestH6FindPage(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + for i := 0; i < 5; i++ { + _ = repo.Create(ctx, &h6User{Name: "u"}) + } + + p1, err := repo.FindPage(ctx, 1, 2) + if err != nil { + t.Fatalf("FindPage: %v", err) + } + if p1.Total != 5 || len(p1.Items) != 2 { + t.Fatalf("page1: total=%d items=%d, want 5/2", p1.Total, len(p1.Items)) + } + + p3, _ := repo.FindPage(ctx, 3, 2) + if len(p3.Items) != 1 { + t.Fatalf("page3 items=%d, want 1", len(p3.Items)) + } +} + +// TestH6FindPageWhere 验证条件分页。 +func TestH6FindPageWhere(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + for i := 0; i < 3; i++ { + _ = repo.Create(ctx, &h6User{Name: "match"}) + } + _ = repo.Create(ctx, &h6User{Name: "other"}) + + p, err := repo.FindPageWhere(ctx, 1, 10, "name = ?", "match") + if err != nil { + t.Fatalf("FindPageWhere: %v", err) + } + if p.Total != 3 || len(p.Items) != 3 { + t.Fatalf("want total=3 items=3, got %d/%d", p.Total, len(p.Items)) + } +} + +// ===== H6b 软删除契约 ===== + +// TestH6DeleteSoftDeletesWithGormModel T 内嵌 gorm.Model 时 Delete 为软删除： +// FindByID 不可见、FindDeleted 可见、Restore 恢复。 +func TestH6DeleteSoftDeletesWithGormModel(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + + u := &h6User{Name: "soft"} + _ = repo.Create(ctx, u) + + if err := repo.Delete(ctx, u.ID); err != nil { + t.Fatalf("Delete: %v", err) + } + if _, err := repo.FindByID(ctx, u.ID); !errors.Is(err, gorm.ErrRecordNotFound) { + t.Fatalf("soft-deleted should be invisible to FindByID, got %v", err) + } + deleted, _ := repo.FindDeleted(ctx) + if _, ok := namesFrom(deleted)["soft"]; !ok { + t.Fatal("FindDeleted should see soft-deleted row") + } + if err := repo.Restore(ctx, u.ID); err != nil { + t.Fatalf("Restore: %v", err) + } + if _, err := repo.FindByID(ctx, u.ID); err != nil { + t.Fatalf("after Restore FindByID should succeed, got %v", err) + } +} + +// ===== H6e QueryBuilder 终结方法克隆 + Count 剥离 Limit/Offset ===== + +// TestH6QueryBuilderCountStripsLimit Count 不受残留 Limit/Offset 截断。 +// 红绿：修复前 Count 沿用 qb.db（带 Limit(2)），返回 2（红）；修复后剥离返回 5（绿）。 +func TestH6QueryBuilderCountStripsLimit(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + for i := 0; i < 5; i++ { + _ = repo.Create(ctx, &h6User{Name: "q"}) + } + + count, err := repo.NewQueryBuilder().Limit(2).Offset(1).Count(ctx) + if err != nil { + t.Fatalf("Count: %v", err) + } + if count != 5 { + t.Fatalf("Count should be 5 (stripped Limit/Offset), got %d", count) + } +} + +// TestH6QueryBuilderFindKeepsLimit Find 仍受 Limit 约束（回归保护）。 +func TestH6QueryBuilderFindKeepsLimit(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + for i := 0; i < 5; i++ { + _ = repo.Create(ctx, &h6User{Name: "q"}) + } + + got, err := repo.NewQueryBuilder().Limit(2).Find(ctx) + if err != nil { + t.Fatalf("Find: %v", err) + } + if len(got) != 2 { + t.Fatalf("Find with Limit(2) should return 2, got %d", len(got)) + } +} + +// TestH6QueryBuilderPageNoAccumulation 连续 Page 调用不因克隆失效而累积污染。 +func TestH6QueryBuilderPageNoAccumulation(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + for i := 0; i < 4; i++ { + _ = repo.Create(ctx, &h6User{Name: "q"}) + } + + qb := repo.NewQueryBuilder().Where("name = ?", "q") + p1, err := qb.Page(ctx, 1, 2) + if err != nil { + t.Fatalf("Page1: %v", err) + } + p2, err := qb.Page(ctx, 2, 2) + if err != nil { + t.Fatalf("Page2: %v", err) + } + if p1.Total != 4 || len(p1.Items) != 2 { + t.Fatalf("page1: total=%d items=%d, want 4/2", p1.Total, len(p1.Items)) + } + if p2.Total != 4 || len(p2.Items) != 2 { + t.Fatalf("page2: total=%d items=%d, want 4/2", p2.Total, len(p2.Items)) + } +} + +// ===== H6c 路由：DefaultManager 主从读写分离（headline）===== + +// setupH6Manager 初始化 DefaultManager 为 sqlite 主+从（独立文件）， +// 并在两侧建表。返回 cleanup 还原全局状态（CloseAll + 置 nil-master）。 +func setupH6Manager(t *testing.T) (masterFile, replicaFile string) { + t.Helper() + dir := t.TempDir() + masterFile = filepath.Join(dir, "master.db") + replicaFile = filepath.Join(dir, "replica.db") + + cfg := &config.Config{} + cfg.Database.Driver = "sqlite" + cfg.Database.CustomDSN = masterFile + + if err := database.InitDBWithReplicas(context.Background(), cfg, []string{replicaFile}); err != nil { + t.Fatalf("InitDBWithReplicas: %v", err) + } + if err := database.GetWriteDB().AutoMigrate(&h6User{}); err != nil { + t.Fatalf("migrate master: %v", err) + } + if err := database.GetReadDB().AutoMigrate(&h6User{}); err != nil { + t.Fatalf("migrate replica: %v", err) + } + t.Cleanup(func() { + _ = database.CloseAll() + }) + return masterFile, replicaFile +} + +// TestH6RoutingReadWriteSplit 验证读操作路由到从库、写操作路由到主库（H6c 核心）。 +// 红绿：修复前 BaseRepo 全部走 r.db（构造捕获的主库），默认读会看到主库标记（红）； +// 修复后默认读路由到从库，仅 UseMaster 读主库，写永远落主库（绿）。 +func TestH6RoutingReadWriteSplit(t *testing.T) { + setupH6Manager(t) + ctx := context.Background() + + // 主从分别写入不同标记 + _ = database.GetWriteDB().Create(&h6User{Name: "MASTER"}) + _ = database.GetReadDB().Create(&h6User{Name: "REPLICA"}) + + // 下游典型用法：r.db = 主库（database.GetDB()） + repo := NewBaseRepo[h6User](database.GetDB()) + + // 默认 ctx（无 UseMaster/UseReplica）→ GetDBFromContext → 从库 → 仅 REPLICA + all, err := repo.FindAll(ctx) + if err != nil { + t.Fatalf("FindAll default: %v", err) + } + names := namesFrom(all) + if _, ok := names["REPLICA"]; !ok { + t.Errorf("default read should route to replica and see REPLICA, got %v", names) + } + if _, ok := names["MASTER"]; ok { + t.Errorf("default read should NOT see master-only MASTER, got %v", names) + } + + // UseMaster → 主库 → MASTER + allM, _ := repo.FindAll(database.UseMaster(ctx)) + namesM := namesFrom(allM) + if _, ok := namesM["MASTER"]; !ok { + t.Errorf("UseMaster read should see MASTER, got %v", namesM) + } + + // UseReplica → 从库 → REPLICA + allR, _ := repo.FindAll(database.UseReplica(ctx)) + namesR := namesFrom(allR) + if _, ok := namesR["REPLICA"]; !ok { + t.Errorf("UseReplica read should see REPLICA, got %v", namesR) + } + + // 写操作 → 主库：Create 后 UseMaster 可见，默认（从库）不可见 + if err := repo.Create(ctx, &h6User{Name: "WRITE"}); err != nil { + t.Fatalf("Create: %v", err) + } + afterWriteM, _ := repo.FindAll(database.UseMaster(ctx)) + if _, ok := namesFrom(afterWriteM)["WRITE"]; !ok { + t.Errorf("write should land on master (visible via UseMaster), got %v", namesFrom(afterWriteM)) + } + afterWriteR, _ := repo.FindAll(ctx) // 默认从库 + if _, ok := namesFrom(afterWriteR)["WRITE"]; ok { + t.Errorf("write should NOT appear on replica, got %v", namesFrom(afterWriteR)) + } +} + +// TestH6RoutingWriteConnNeverHitsReplica 写操作即便 UseReplica(ctx) 也走主库。 +func TestH6RoutingWriteConnNeverHitsReplica(t *testing.T) { + setupH6Manager(t) + ctx := context.Background() + + repo := NewBaseRepo[h6User](database.GetDB()) + + // 即便 ctx 标记 UseReplica，写也必须落主库 + if err := repo.Create(database.UseReplica(ctx), &h6User{Name: "W2"}); err != nil { + t.Fatalf("Create under UseReplica: %v", err) + } + onMaster, _ := repo.FindAll(database.UseMaster(ctx)) + if _, ok := namesFrom(onMaster)["W2"]; !ok { + t.Errorf("write under UseReplica must still land on master, got %v", namesFrom(onMaster)) + } +} diff --git a/repository/repository_m5_internal_test.go b/repository/repository_m5_internal_test.go new file mode 100644 index 0000000..0213c33 --- /dev/null +++ b/repository/repository_m5_internal_test.go @@ -0,0 +1,261 @@ +package repository + +import ( + "context" + "errors" + "fmt" + "strings" + "testing" + "time" +) + +func seedM5Users(t *testing.T, repo *BaseRepo[h6User], n int) { + t.Helper() + for i := 0; i < n; i++ { + if err := repo.Create(context.Background(), &h6User{Name: fmt.Sprintf("m5-%04d", i), Age: i}); err != nil { + t.Fatalf("seed user %d: %v", i, err) + } + } +} + +func TestM5NilContextFallsBackToBackground(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + + u := &h6User{Name: "nil-ctx"} + if err := repo.Create(nil, u); err != nil { + t.Fatalf("Create(nil ctx): %v", err) + } + got, err := repo.FindByID(nil, u.ID) + if err != nil { + t.Fatalf("FindByID(nil ctx): %v", err) + } + if got.Name != "nil-ctx" { + t.Fatalf("got %q, want nil-ctx", got.Name) + } +} + +func TestM5UnsafeOrderRejected(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + + cases := []struct { + name string + fn func() error + }{ + {"FindOrdered", func() error { + _, err := repo.FindOrdered(ctx, "name desc; drop table h6_users", 10) + return err + }}, + {"FindWhereOrdered", func() error { + _, err := repo.FindWhereOrdered(ctx, "name desc --", "name <> ?", "") + return err + }}, + {"FindPageOrdered", func() error { + _, err := repo.FindPageOrdered(ctx, 1, 10, "lower(name) desc") + return err + }}, + {"FindPageWhereOrdered", func() error { + _, err := repo.FindPageWhereOrdered(ctx, 1, 10, "name collate nocase", "name <> ?", "") + return err + }}, + {"QueryBuilder", func() error { + _, err := repo.NewQueryBuilder().Order("name; drop table h6_users").Find(ctx) + return err + }}, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if err := tc.fn(); !errors.Is(err, ErrUnsafeOrder) { + t.Fatalf("err = %v, want ErrUnsafeOrder", err) + } + }) + } +} + +func TestM5QueryBuilderUnsafeOrderPropagatesToAllTerminators(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + seedM5Users(t, repo, 1) + + if _, err := repo.NewQueryBuilder().Order("name; drop table h6_users").Find(ctx); !errors.Is(err, ErrUnsafeOrder) { + t.Fatalf("Find err = %v, want ErrUnsafeOrder", err) + } + if _, err := repo.NewQueryBuilder().Order("name; drop table h6_users").First(ctx); !errors.Is(err, ErrUnsafeOrder) { + t.Fatalf("First err = %v, want ErrUnsafeOrder", err) + } + if _, err := repo.NewQueryBuilder().Order("name; drop table h6_users").Count(ctx); !errors.Is(err, ErrUnsafeOrder) { + t.Fatalf("Count err = %v, want ErrUnsafeOrder", err) + } + if _, err := repo.NewQueryBuilder().Order("name; drop table h6_users").Page(ctx, 1, 10); !errors.Is(err, ErrUnsafeOrder) { + t.Fatalf("Page err = %v, want ErrUnsafeOrder", err) + } +} + +func TestM5SafeOrderStillWorks(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + if err := repo.Create(ctx, &h6User{Name: "b"}); err != nil { + t.Fatalf("Create b: %v", err) + } + if err := repo.Create(ctx, &h6User{Name: "a"}); err != nil { + t.Fatalf("Create a: %v", err) + } + + got, err := repo.FindOrdered(ctx, "name ASC, id DESC", 10) + if err != nil { + t.Fatalf("FindOrdered safe order: %v", err) + } + if len(got) != 2 || got[0].Name != "a" || got[1].Name != "b" { + t.Fatalf("unexpected order: %+v", got) + } +} + +func TestM5UpdateBatchRejectsUnsafeFieldAndEmptyIDsNoop(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + ctx := context.Background() + u := &h6User{Name: "field", Age: 1} + if err := repo.Create(ctx, u); err != nil { + t.Fatalf("Create: %v", err) + } + + if err := repo.UpdateBatch(ctx, []uint{u.ID}, "age = age + 1", 2); !errors.Is(err, ErrUnsafeField) { + t.Fatalf("unsafe field err = %v, want ErrUnsafeField", err) + } + if err := repo.UpdateBatch(ctx, nil, "age = age + 1", 2); err != nil { + t.Fatalf("empty ids should noop before field validation, got %v", err) + } + if err := repo.UpdateBatch(ctx, []uint{u.ID}, "age", 2); err != nil { + t.Fatalf("safe field UpdateBatch: %v", err) + } + got, _ := repo.FindByID(ctx, u.ID) + if got.Age != 2 { + t.Fatalf("age = %d, want 2", got.Age) + } +} + +func TestM5FindByIDsEmptyReturnsEmptySlice(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + got, err := repo.FindByIDs(context.Background(), nil) + if err != nil { + t.Fatalf("FindByIDs empty: %v", err) + } + if got == nil { + t.Fatal("FindByIDs empty should return non-nil empty slice") + } + if len(got) != 0 { + t.Fatalf("len = %d, want 0", len(got)) + } +} + +func TestM5FindAllAppliesDefaultLimit(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + seedM5Users(t, repo, DefaultFindAllLimit+5) + + got, err := repo.FindAll(context.Background()) + if err != nil { + t.Fatalf("FindAll: %v", err) + } + if len(got) != DefaultFindAllLimit { + t.Fatalf("FindAll len = %d, want default limit %d", len(got), DefaultFindAllLimit) + } + + all, err := repo.FindAllUnbounded(context.Background()) + if err != nil { + t.Fatalf("FindAllUnbounded: %v", err) + } + if len(all) != DefaultFindAllLimit+5 { + t.Fatalf("FindAllUnbounded len = %d, want %d", len(all), DefaultFindAllLimit+5) + } +} + +func TestM5PaginationBounds(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + seedM5Users(t, repo, MaxPageSize+5) + + p, err := repo.FindPage(context.Background(), -10, 0) + if err != nil { + t.Fatalf("FindPage default bounds: %v", err) + } + if p.Page != 1 || p.PageSize != DefaultPageSize || len(p.Items) != DefaultPageSize { + t.Fatalf("page defaults = page:%d size:%d items:%d, want 1/%d/%d", + p.Page, p.PageSize, len(p.Items), DefaultPageSize, DefaultPageSize) + } + + p, err = repo.FindPage(context.Background(), 1, MaxPageSize+100) + if err != nil { + t.Fatalf("FindPage max size: %v", err) + } + if p.PageSize != MaxPageSize || len(p.Items) != MaxPageSize { + t.Fatalf("page max = size:%d items:%d, want %d/%d", p.PageSize, len(p.Items), MaxPageSize, MaxPageSize) + } + + p, err = repo.FindPage(context.Background(), MaxPage+1, 10) + if err != nil { + t.Fatalf("FindPage max page: %v", err) + } + if p.Page != MaxPage { + t.Fatalf("page = %d, want MaxPage %d", p.Page, MaxPage) + } +} + +func TestM5QueryBuilderNilDBPanicsClearly(t *testing.T) { + repo := NewBaseRepo[h6User](nil) + defer func() { + if rec := recover(); rec == nil { + t.Fatal("NewQueryBuilder with nil db should panic") + } + }() + _ = repo.NewQueryBuilder() +} + +func TestM5QueryBuilderNilContextAndPageBounds(t *testing.T) { + repo := NewBaseRepo[h6User](newH6SqliteDB(t)) + seedM5Users(t, repo, 25) + + count, err := repo.NewQueryBuilder().Where("created_at <= ?", time.Now().Add(time.Hour)).Count(nil) + if err != nil { + t.Fatalf("Count nil ctx: %v", err) + } + if count != 25 { + t.Fatalf("count = %d, want 25", count) + } + + p, err := repo.NewQueryBuilder().Page(nil, 1, 0) + if err != nil { + t.Fatalf("Page nil ctx: %v", err) + } + if p.PageSize != DefaultPageSize || len(p.Items) != DefaultPageSize { + t.Fatalf("QueryBuilder page size/items = %d/%d, want %d/%d", + p.PageSize, len(p.Items), DefaultPageSize, DefaultPageSize) + } +} + +func TestM5DeleteBatchEmptyIDsNoop(t *testing.T) { + db := newDryRunDB(t) + repo := NewBaseRepo[pageCountModel](db) + + if err := repo.DeleteBatch(context.Background(), nil); err != nil { + t.Fatalf("DeleteBatch empty ids: %v", err) + } + if got := db.Statement.SQL.String(); got != "" { + t.Fatalf("DeleteBatch empty ids should not issue SQL, got %s", got) + } + if err := repo.HardDeleteBatch(context.Background(), nil); err != nil { + t.Fatalf("HardDeleteBatch empty ids: %v", err) + } + if got := db.Statement.SQL.String(); got != "" { + t.Fatalf("HardDeleteBatch empty ids should not issue SQL, got %s", got) + } +} + +func TestM5FindAllUsesLimitSQL(t *testing.T) { + db := newDryRunDB(t) + repo := NewBaseRepo[pageCountModel](db) + var models []pageCountModel + result := repo.readConn(context.Background()).Limit(DefaultFindAllLimit).Find(&models) + sql := strings.ToUpper(result.Statement.SQL.String()) + if !strings.Contains(sql, "LIMIT") { + t.Fatalf("FindAll default path should include LIMIT, got %s", sql) + } +} diff --git a/repository/repository_test.go b/repository/repository_test.go new file mode 100644 index 0000000..5862721 --- /dev/null +++ b/repository/repository_test.go @@ -0,0 +1,26 @@ +package repository_test + +import ( + "testing" + + "github.com/EthanCodeCraft/xlgo-core/repository" + "gorm.io/gorm" +) + +// N2：原 repository_test.go 全为空注释壳，CRUD 零覆盖。 +// 此处用编译期断言锁定 BaseRepo 实现 BaseRepository 接口契约—— +// 接口一旦与实现漂移，编译即失败（比运行期空壳更有价值）。 + +type testModel struct { + gorm.Model + Name string +} + +// 编译期保证 *BaseRepo[T] 满足 BaseRepository[T] 接口（N2 接口契约守卫）。 +var _ repository.BaseRepository[testModel] = (*repository.BaseRepo[testModel])(nil) + +func TestBaseRepoSatisfiesInterface(t *testing.T) { + // 运行期占位：编译期 var _ 已是主断言，此处仅保证测试函数不被 lint 清理。 + var r repository.BaseRepository[testModel] = repository.NewBaseRepo[testModel](nil) + _ = r +} diff --git a/response/error.go b/response/error.go new file mode 100644 index 0000000..7bde2ca --- /dev/null +++ b/response/error.go @@ -0,0 +1,233 @@ +package response + +import ( + "fmt" + + "github.com/gin-gonic/gin" +) + +// 业务错误码定义 +// 格式：模块(2位) + 功能(2位) + 错误类型(2位) +// +// 约定： +// - CodeSuccess = 0：成功 +// - CodeFail = 1：通用失败 +// - 其余 framework 内置错误码使用 HTTP 风格（401/403/404/429/500/503）或 5 位业务码段 +// - 参数错误等业务化错误码请由业务项目自行定义，框架不再内置 CodeInvalidParams +const ( + // 通用错误 00xxxx + CodeSuccess = 0 // 成功 + CodeFail = 1 // 通用失败 + CodeUnauthorized = 401 // 未授权 + CodeForbidden = 403 // 无权限 + CodeNotFound = 404 // 资源不存在 + CodeRateLimit = 429 // 请求过于频繁 + CodeServerError = 500 // 服务器错误 + CodeServiceUnavailable = 503 // 服务不可用 + + // 用户模块错误 01xxxx + CodeUserNotFound = 10001 // 用户不存在 + CodeUserAlreadyExists = 10002 // 用户已存在 + CodeUserDisabled = 10003 // 用户已禁用 + CodePasswordWrong = 10004 // 密码错误 + CodePasswordWeak = 10005 // 密码强度不足 + CodePhoneInvalid = 10006 // 手机号无效 + CodeEmailInvalid = 10007 // 邮箱无效 + CodeLoginFailed = 10008 // 登录失败 + CodeTokenExpired = 10009 // Token 已过期 + CodeTokenInvalid = 10010 // Token 无效 + + // 文件模块错误 02xxxx + CodeFileNotFound = 20001 // 文件不存在 + CodeFileTooLarge = 20002 // 文件过大 + CodeFileTypeInvalid = 20003 // 文件类型不支持 + CodeFileUploadFailed = 20004 // 文件上传失败 + + // 数据模块错误 03xxxx + CodeDataNotFound = 30001 // 数据不存在 + CodeDataAlreadyExists = 30002 // 数据已存在 + CodeDataInvalid = 30003 // 数据无效 + CodeDataConflict = 30004 // 数据冲突 + + // 业务模块错误 04xxxx + CodeOperationFailed = 40001 // 操作失败 + CodeOperationTimeout = 40002 // 操作超时 + CodeBusinessRuleError = 40003 // 业务规则错误 +) + +// Error 业务错误 +type Error struct { + Code int // 错误码 + Message string // 错误消息 + Detail string // 详细信息（可选） +} + +// NewError 创建业务错误 +func NewError(code int, message string) *Error { + return &Error{ + Code: code, + Message: message, + } +} + +// NewErrorWithDetail 创建带详细信息的业务错误 +func NewErrorWithDetail(code int, message, detail string) *Error { + return &Error{ + Code: code, + Message: message, + Detail: detail, + } +} + +// Error 实现 error 接口 +func (e *Error) Error() string { + if e.Detail != "" { + return fmt.Sprintf("[%d] %s: %s", e.Code, e.Message, e.Detail) + } + return fmt.Sprintf("[%d] %s", e.Code, e.Message) +} + +// WithDetail 添加详细信息。 +// +// H-10 修复：返回新 *Error 拷贝，不 mutate 接收者。预定义 Err*（如 ErrNotFound）是 +// 包级共享指针，原实现 e.Detail = detail 会污染全局且并发调用存在数据竞争。 +// +// nil 接收者：返回 &Error{Detail: detail}（Code=0/Message=""），不 panic；调用方应避免 +// 在 nil 上调用本方法以拿到无 Code/Message 的半成品错误。 +func (e *Error) WithDetail(detail string) *Error { + if e == nil { + return &Error{Detail: detail} + } + return &Error{ + Code: e.Code, + Message: e.Message, + Detail: detail, + } +} + +// ToResponse 转换为响应结构。 +// 把 Detail 放入 data.detail（若非空），保留链路细节（M7：原实现丢 Detail）。 +// P1 #15：仅当 detailExposed()（默认 true；App 生产环境置 false）时才向客户端输出 Detail， +// 避免内部错误细节在生产泄露。 +func (e *Error) ToResponse() Response { + if e == nil { + return Response{ + Code: CodeServerError, + Msg: ErrServerError.Message, + Data: nil, + } + } + if e.Detail != "" && detailExposed() { + return Response{ + Code: e.Code, + Msg: e.Message, + Data: gin.H{"detail": e.Detail}, + } + } + return Response{ + Code: e.Code, + Msg: e.Message, + } +} + +// 预定义错误 +var ( + ErrUnauthorized = NewError(CodeUnauthorized, "请先登录") + ErrForbidden = NewError(CodeForbidden, "无权限访问") + ErrNotFound = NewError(CodeNotFound, "资源不存在") + ErrRateLimit = NewError(CodeRateLimit, "请求过于频繁") + ErrServerError = NewError(CodeServerError, "服务器错误") + ErrServiceUnavailable = NewError(CodeServiceUnavailable, "服务暂时不可用") + + // 用户相关 + ErrUserNotFound = NewError(CodeUserNotFound, "用户不存在") + ErrUserAlreadyExists = NewError(CodeUserAlreadyExists, "用户已存在") + ErrUserDisabled = NewError(CodeUserDisabled, "用户已禁用") + ErrPasswordWrong = NewError(CodePasswordWrong, "密码错误") + ErrPasswordWeak = NewError(CodePasswordWeak, "密码强度不足") + ErrPhoneInvalid = NewError(CodePhoneInvalid, "手机号无效") + ErrEmailInvalid = NewError(CodeEmailInvalid, "邮箱无效") + ErrLoginFailed = NewError(CodeLoginFailed, "登录失败") + ErrTokenExpired = NewError(CodeTokenExpired, "登录已过期") + ErrTokenInvalid = NewError(CodeTokenInvalid, "Token 无效") + + // 文件相关 + ErrFileNotFound = NewError(CodeFileNotFound, "文件不存在") + ErrFileTooLarge = NewError(CodeFileTooLarge, "文件过大") + ErrFileTypeInvalid = NewError(CodeFileTypeInvalid, "文件类型不支持") + ErrFileUploadFailed = NewError(CodeFileUploadFailed, "文件上传失败") + + // 数据相关 + ErrDataNotFound = NewError(CodeDataNotFound, "数据不存在") + ErrDataAlreadyExists = NewError(CodeDataAlreadyExists, "数据已存在") + ErrDataInvalid = NewError(CodeDataInvalid, "数据无效") + ErrDataConflict = NewError(CodeDataConflict, "数据冲突") + + // 业务相关 + ErrOperationFailed = NewError(CodeOperationFailed, "操作失败") + ErrOperationTimeout = NewError(CodeOperationTimeout, "操作超时") + ErrBusinessRule = NewError(CodeBusinessRuleError, "业务规则错误") +) + +// _errorCodeUniquenessGuard 在编译期保证所有内置 Code* 不重复。 +// Go spec: 同一个常量 key 在 map 字面量中出现两次会触发 +// "duplicate key in map literal" 编译错误，从而把"错误码不能撞" +// 这件事写进类型系统，比 init() 里 panic 检查更早、更安全。 +// +// 维护规则：新增 Code* 常量时，**必须**把它登记到这里。 +// 注意：变量名故意以下划线开头并赋给 _，避免 unused 报错且不会进入 runtime。 +var _ = map[int]string{ + CodeSuccess: "CodeSuccess", + CodeFail: "CodeFail", + CodeUnauthorized: "CodeUnauthorized", + CodeForbidden: "CodeForbidden", + CodeNotFound: "CodeNotFound", + CodeRateLimit: "CodeRateLimit", + CodeServerError: "CodeServerError", + CodeServiceUnavailable: "CodeServiceUnavailable", + + CodeUserNotFound: "CodeUserNotFound", + CodeUserAlreadyExists: "CodeUserAlreadyExists", + CodeUserDisabled: "CodeUserDisabled", + CodePasswordWrong: "CodePasswordWrong", + CodePasswordWeak: "CodePasswordWeak", + CodePhoneInvalid: "CodePhoneInvalid", + CodeEmailInvalid: "CodeEmailInvalid", + CodeLoginFailed: "CodeLoginFailed", + CodeTokenExpired: "CodeTokenExpired", + CodeTokenInvalid: "CodeTokenInvalid", + + CodeFileNotFound: "CodeFileNotFound", + CodeFileTooLarge: "CodeFileTooLarge", + CodeFileTypeInvalid: "CodeFileTypeInvalid", + CodeFileUploadFailed: "CodeFileUploadFailed", + + CodeDataNotFound: "CodeDataNotFound", + CodeDataAlreadyExists: "CodeDataAlreadyExists", + CodeDataInvalid: "CodeDataInvalid", + CodeDataConflict: "CodeDataConflict", + + CodeOperationFailed: "CodeOperationFailed", + CodeOperationTimeout: "CodeOperationTimeout", + CodeBusinessRuleError: "CodeBusinessRuleError", +} + +// FailWithError 使用预定义错误响应（M7 修复：通过 ToResponse 保留 Detail）。 +func FailWithError(c *gin.Context, err *Error) { + resp := err.ToResponse() + writeResp(c, resp.Code, resp.Msg, resp.Data) +} + +// FailWithDetail 使用预定义错误并添加详细信息。 +// P1 #15：detail 仅在 detailExposed()（默认 true；App 生产环境置 false）时输出给客户端。 +func FailWithDetail(c *gin.Context, err *Error, detail string) { + if err == nil { + FailWithError(c, nil) + return + } + if detailExposed() { + writeResp(c, err.Code, err.Message, gin.H{"detail": detail}) + return + } + writeResp(c, err.Code, err.Message, nil) +} diff --git a/response/error_test.go b/response/error_test.go new file mode 100644 index 0000000..f4f4194 --- /dev/null +++ b/response/error_test.go @@ -0,0 +1,67 @@ +package response_test + +import ( + "sync" + "testing" + + "github.com/EthanCodeCraft/xlgo-core/response" +) + +// TestWithDetailDoesNotMutateOriginal H-10 回归：WithDetail 必须返回新拷贝， +// 不得 mutate 共享的预定义 Err*。修复前 WithDetail 会写 e.Detail 污染全局。 +func TestWithDetailDoesNotMutateOriginal(t *testing.T) { + if response.ErrNotFound.Detail != "" { + t.Fatalf("预置条件：ErrNotFound.Detail 应为空，实际 %q", response.ErrNotFound.Detail) + } + + detailed := response.ErrNotFound.WithDetail("用户 123 不存在") + + // 原共享对象不得被污染 + if response.ErrNotFound.Detail != "" { + t.Fatalf("WithDetail 污染了共享 ErrNotFound，Detail=%q", response.ErrNotFound.Detail) + } + // 新拷贝携带 detail + if detailed.Detail != "用户 123 不存在" { + t.Fatalf("新 Error 应携带 detail，实际 %q", detailed.Detail) + } + if detailed.Code != response.ErrNotFound.Code || detailed.Message != response.ErrNotFound.Message { + t.Fatalf("新 Error 应继承 Code/Message，实际 Code=%d Message=%q", detailed.Code, detailed.Message) + } +} + +// TestWithDetailConcurrentOnSharedError H-10 回归：并发在共享 Err* 上调 WithDetail +// 不应触发数据竞争（修复前 mutate 共享对象，-race 必采）。 +func TestWithDetailConcurrentOnSharedError(t *testing.T) { + var wg sync.WaitGroup + for i := 0; i < 50; i++ { + wg.Add(1) + go func(n int) { + defer wg.Done() + e := response.ErrNotFound.WithDetail("concurrent") + if e.Detail != "concurrent" { + t.Errorf("Detail 应为 concurrent，实际 %q", e.Detail) + } + }(i) + } + wg.Wait() +} + +// TestExposeDetailGating P1 #15：SetExposeDetail(false) 时 ToResponse 不得输出 Detail； +// true 时输出。默认（未设置）为 true，保持存量行为。 +func TestExposeDetailGating(t *testing.T) { + t.Cleanup(func() { response.SetExposeDetail(true) }) // 还原默认 + + err := response.NewErrorWithDetail(response.CodeServerError, "服务器错误", "pq: relation \"users\" does not exist") + + // 暴露开启（默认/开发）：Detail 出现在 Data 中 + response.SetExposeDetail(true) + if resp := err.ToResponse(); resp.Data == nil { + t.Error("SetExposeDetail(true): ToResponse 应包含 detail") + } + + // 暴露关闭（生产）：Detail 不得出现，防内部错误泄露 + response.SetExposeDetail(false) + if resp := err.ToResponse(); resp.Data != nil { + t.Errorf("SetExposeDetail(false): ToResponse 不得输出 detail，实际 Data=%v", resp.Data) + } +} diff --git a/response/mode.go b/response/mode.go new file mode 100644 index 0000000..961af03 --- /dev/null +++ b/response/mode.go @@ -0,0 +1,110 @@ +package response + +import ( + "net/http" + "sync/atomic" + + "github.com/gin-gonic/gin" +) + +// Mode 响应模式 +type Mode int32 + +const ( + // ModeBusiness 业务码模式（默认）：所有响应 HTTP 200，错误信息通过 body 中的 code 表达。 + // 兼容存量"业务码 in body"玩法。 + ModeBusiness Mode = iota + // ModeREST REST 模式：失败响应按业务码映射对应的 HTTP status（401/404/500...）， + // body 仍带业务码。便于 APM / Prometheus / 网关 / Sentry 按 status 区分异常。 + ModeREST +) + +// currentMode 当前响应模式，默认 ModeBusiness。原子读写，可在运行时切换。 +var currentMode atomic.Int32 + +// SetMode 设置全局响应模式。 +func SetMode(m Mode) { currentMode.Store(int32(m)) } + +// GetMode 返回当前响应模式。 +func GetMode() Mode { return Mode(currentMode.Load()) } + +// exposeDetail 控制是否把 Error.Detail 写入发给客户端的响应体（P1 #15）。 +// 默认 true（保持存量行为：直接使用 response 包的项目不受影响）。 +// App 在 Init 时按环境设置：生产环境置为 false，避免调用方误把内部错误（SQL 报错、 +// 堆栈上下文等）塞进 Detail 而泄露给客户端；开发环境保持 true 便于排查。 +// 1 表示暴露，0 表示隐藏。 +var exposeDetail atomic.Int32 + +func init() { + exposeDetail.Store(1) // 默认暴露，保持存量行为 +} + +// SetExposeDetail 设置是否向客户端暴露 Error.Detail（P1 #15）。 +// 生产环境建议置为 false，防止内部错误细节泄露。并发安全。 +func SetExposeDetail(expose bool) { + if expose { + exposeDetail.Store(1) + } else { + exposeDetail.Store(0) + } +} + +// detailExposed 返回当前是否暴露 Detail。 +func detailExposed() bool { return exposeDetail.Load() == 1 } + +// statusForCode 按业务码推断 HTTP status（用于 ModeREST）。 +// 已知框架错误码显式映射；用户/文件/数据模块的业务错误码（1xxxx~3xxxx） +// 属业务语义而非 HTTP 错误，保持 200；操作失败类（4xxxx）映射 400。 +func statusForCode(code int) int { + switch code { + case CodeSuccess: + return http.StatusOK + case CodeUnauthorized, CodeTokenExpired, CodeTokenInvalid: + return http.StatusUnauthorized + case CodeForbidden: + return http.StatusForbidden + case CodeNotFound, CodeUserNotFound, CodeFileNotFound, CodeDataNotFound: + return http.StatusNotFound + case CodeDataConflict, CodeDataAlreadyExists: + return http.StatusConflict + case CodeRateLimit: + return http.StatusTooManyRequests + case CodeServerError: + return http.StatusInternalServerError + case CodeServiceUnavailable: + return http.StatusServiceUnavailable + } + if code >= 40000 && code < 50000 { + return http.StatusBadRequest + } + return http.StatusOK +} + +// httpStatusFor 返回当前模式下失败响应对应的 HTTP status。 +func httpStatusFor(code int) int { + if GetMode() == ModeREST { + return statusForCode(code) + } + return http.StatusOK +} + +// writeResp 统一写入响应，按当前 Mode 决定 HTTP status。 +func writeResp(c *gin.Context, code int, msg string, data any) { + c.JSON(httpStatusFor(code), Response{ + Code: code, + Msg: msg, + Data: data, + RequestID: getRequestID(c), + }) +} + +// Custom 显式指定 HTTP status 与业务码的响应，不受 Mode 影响。 +// 适用于需要精确控制 HTTP status 的场景（如 REST 模式下的特殊端点）。 +func Custom(c *gin.Context, httpStatus, code int, msg string, data any) { + c.JSON(httpStatus, Response{ + Code: code, + Msg: msg, + Data: data, + RequestID: getRequestID(c), + }) +} diff --git a/response/mode_test.go b/response/mode_test.go new file mode 100644 index 0000000..207c6b0 --- /dev/null +++ b/response/mode_test.go @@ -0,0 +1,106 @@ +package response_test + +import ( + "encoding/json" + "net/http/httptest" + "testing" + + "github.com/EthanCodeCraft/xlgo-core/response" + "github.com/gin-gonic/gin" +) + +// withMode 切换响应模式并在测试结束后恢复为默认 ModeBusiness。 +func withMode(t *testing.T, m response.Mode) { + t.Helper() + response.SetMode(m) + t.Cleanup(func() { response.SetMode(response.ModeBusiness) }) +} + +func TestSetGetMode(t *testing.T) { + withMode(t, response.ModeREST) + if response.GetMode() != response.ModeREST { + t.Errorf("GetMode = %v, want ModeREST", response.GetMode()) + } +} + +func TestModeBusinessReturns200(t *testing.T) { + withMode(t, response.ModeBusiness) + r := setupTestRouter() + r.GET("/u", func(c *gin.Context) { response.Unauthorized(c, "no") }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/u", nil)) + + if w.Code != 200 { + t.Errorf("ModeBusiness Unauthorized status = %d, want 200", w.Code) + } +} + +func TestModeRESTMapsStatus(t *testing.T) { + withMode(t, response.ModeREST) + cases := []struct { + path string + fn func(c *gin.Context) + wantCode int + }{ + {"/unauth", func(c *gin.Context) { response.Unauthorized(c, "no") }, 401}, + {"/notfound", func(c *gin.Context) { response.NotFound(c, "no") }, 404}, + {"/server", func(c *gin.Context) { response.ServerError(c, "err") }, 500}, + {"/ratelimit", func(c *gin.Context) { response.RateLimit(c) }, 429}, + {"/fail", func(c *gin.Context) { response.Fail(c, "bad") }, 200}, // CodeFail 不映射 + } + for _, tc := range cases { + r := setupTestRouter() + r.GET(tc.path, tc.fn) + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", tc.path, nil)) + if w.Code != tc.wantCode { + t.Errorf("%s status = %d, want %d", tc.path, w.Code, tc.wantCode) + } + // body 仍带业务码 + var body response.Response + if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil { + t.Errorf("%s body unmarshal: %v", tc.path, err) + } + if body.Code == 0 && tc.path != "/fail" { + // 非 Fail 路径 code 应非 0（Fail 的 CodeFail=1 也非 0，跳过） + } + } +} + +func TestCustomIgnoresMode(t *testing.T) { + withMode(t, response.ModeBusiness) // 即使 business 模式，Custom 也用指定 status + r := setupTestRouter() + r.GET("/c", func(c *gin.Context) { response.Custom(c, 418, 999, "teapot", nil) }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/c", nil)) + if w.Code != 418 { + t.Errorf("Custom status = %d, want 418", w.Code) + } +} + +func TestFailWithErrorREST(t *testing.T) { + withMode(t, response.ModeREST) + r := setupTestRouter() + r.GET("/e", func(c *gin.Context) { response.FailWithError(c, response.ErrUnauthorized) }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/e", nil)) + if w.Code != 401 { + t.Errorf("FailWithError(ErrUnauthorized) status = %d, want 401", w.Code) + } +} + +// TestDataAlreadyExistsMapsConflict_B7：CodeDataAlreadyExists 应映射 409（与 CodeDataConflict 一致）。 +func TestDataAlreadyExistsMapsConflict_B7(t *testing.T) { + withMode(t, response.ModeREST) + r := setupTestRouter() + r.GET("/dup", func(c *gin.Context) { response.FailWithError(c, response.ErrDataAlreadyExists) }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/dup", nil)) + if w.Code != 409 { + t.Errorf("ErrDataAlreadyExists status = %d, want 409", w.Code) + } +} diff --git a/response/response.go b/response/response.go new file mode 100644 index 0000000..e114860 --- /dev/null +++ b/response/response.go @@ -0,0 +1,170 @@ +package response + +import ( + "bytes" + "io" + "net/http" + "net/url" + + "github.com/gin-gonic/gin" +) + +// Response 统一响应结构 +// +// M-38/M-39 修复（breaking）：Data/RequestID 去掉 omitempty，让 data 与 request_id +// 字段在所有响应中恒存在（失败时 data=null、未装 RequestID 中间件时 request_id=""）。 +// 原实现用 omitempty 导致失败响应无 data 字段、空切片被 omit、未装中间件时无 request_id， +// 破坏"统一响应结构"契约，下游严格按 schema 解析会出错。 +type Response struct { + Code int `json:"code"` + Msg string `json:"msg"` + Data any `json:"data"` + RequestID string `json:"request_id"` // 请求追踪ID +} + +// PageData 分页数据结构 +type PageData struct { + Items any `json:"items"` + Total int64 `json:"total"` + Page int `json:"page"` + PageSize int `json:"page_size"` +} + +// getRequestID 从上下文获取请求ID +func getRequestID(c *gin.Context) string { + return c.GetString("request_id") +} + +// Success 成功响应 +func Success(c *gin.Context, data any) { + c.JSON(http.StatusOK, Response{ + Code: CodeSuccess, + Msg: "操作成功", + Data: data, + RequestID: getRequestID(c), + }) +} + +// SuccessWithMsg 成功响应（自定义消息） +func SuccessWithMsg(c *gin.Context, msg string, data any) { + c.JSON(http.StatusOK, Response{ + Code: CodeSuccess, + Msg: msg, + Data: data, + RequestID: getRequestID(c), + }) +} + +// Fail 失败响应 +func Fail(c *gin.Context, msg string) { + writeResp(c, CodeFail, msg, nil) +} + +// FailWithCode 失败响应（自定义错误码） +func FailWithCode(c *gin.Context, code int, msg string) { + writeResp(c, code, msg, nil) +} + +// Unauthorized 未授权响应 +func Unauthorized(c *gin.Context, msg string) { + writeResp(c, CodeUnauthorized, msg, nil) +} + +// NotFound 资源不存在响应 +func NotFound(c *gin.Context, msg string) { + writeResp(c, CodeNotFound, msg, nil) +} + +// ServerError 服务器错误响应 +func ServerError(c *gin.Context, msg string) { + writeResp(c, CodeServerError, msg, nil) +} + +// RateLimit 请求过于频繁响应 +func RateLimit(c *gin.Context) { + writeResp(c, CodeRateLimit, "请求过于频繁，请稍后再试", nil) +} + +// Page 分页响应 +func Page(c *gin.Context, items any, total int64, page, pageSize int) { + Success(c, PageData{ + Items: items, + Total: total, + Page: page, + PageSize: pageSize, + }) +} + +// contentDisposition 生成 RFC 5987 兼容的 Content-Disposition 值（M6 修复）。 +// 同时给出 ASCII filename（向后兼容旧客户端）与 filename*（UTF-8 百分号编码，支持中文等非 ASCII）， +// 避免直接拼接导致中文文件名乱码。 +func contentDisposition(filename string) string { + ascii := asciiFallbackName(filename) + enc := url.PathEscape(filename) + // PathEscape 把空格编码为 %20（符合 RFC 5987），无需额外处理。 + return "attachment; filename=\"" + ascii + "\"; filename*=UTF-8''" + enc +} + +// asciiFallbackName 生成仅含 ASCII 的回退文件名：非 ASCII 字符替换为下划线， +// 空文件名回退为 "download"。 +func asciiFallbackName(filename string) string { + if filename == "" { + return "download" + } + b := make([]byte, 0, len(filename)) + for i := 0; i < len(filename); i++ { + c := filename[i] + if c >= 0x20 && c < 0x7f && c != '"' && c != '\\' { + b = append(b, c) + } else { + b = append(b, '_') + } + } + if len(b) == 0 { + return "download" + } + return string(b) +} + +// Download 文件下载响应 +// Compatibility note: for large files or object-storage streams, prefer +// DownloadReader so the whole object is not buffered in []byte first. +func Download(c *gin.Context, filename string, data []byte) { + DownloadReader(c, filename, "application/octet-stream", int64(len(data)), bytesReader(data)) +} + +// DownloadWithContentType 文件下载（自定义Content-Type） +func DownloadWithContentType(c *gin.Context, filename string, contentType string, data []byte) { + DownloadReader(c, filename, contentType, int64(len(data)), bytesReader(data)) +} + +// DownloadReader 流式下载响应。 +// +// 对大文件/对象存储下载优先使用此函数，避免先把完整内容读入 []byte 驻留内存。 +// contentLength 传 -1 表示未知长度；Gin 会省略 Content-Length。 +func DownloadReader(c *gin.Context, filename, contentType string, contentLength int64, r io.Reader) { + if contentType == "" { + contentType = "application/octet-stream" + } + headers := map[string]string{ + "Content-Disposition": contentDisposition(filename), + } + c.DataFromReader(http.StatusOK, contentLength, contentType, r, headers) +} + +// bytesReader 避免在公开 API 中暴露 bytes 包细节，同时让旧 []byte API 复用流式写路径。 +func bytesReader(data []byte) io.Reader { + return bytes.NewReader(data) +} + +// HTML HTML内容响应 +// Security note: HTML writes raw markup and does not escape untrusted input. +func HTML(c *gin.Context, data string) { + c.Header("Content-Type", "text/html; charset=utf-8") + c.String(http.StatusOK, data) +} + +// Redirect 页面跳转 +func Redirect(c *gin.Context, code int, url string) { + c.Redirect(code, url) +} diff --git a/response/response_test.go b/response/response_test.go new file mode 100644 index 0000000..c979204 --- /dev/null +++ b/response/response_test.go @@ -0,0 +1,399 @@ +package response_test + +import ( + "encoding/json" + "net/http/httptest" + "strings" + "testing" + + "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 TestSuccess(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + response.Success(c, gin.H{"message": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("Success status = %d", w.Code) + } + + // 验证响应体包含 code=0 + body := w.Body.String() + if !contains(body, `"code":0`) { + t.Errorf("Success body should contain code:0, got %s", body) + } +} + +func TestSuccessWithMsg(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + response.SuccessWithMsg(c, "操作成功", gin.H{"id": 1}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("SuccessWithMsg status = %d", w.Code) + } +} + +func TestFail(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + response.Fail(c, "参数错误") + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("Fail status = %d", w.Code) + } + + body := w.Body.String() + if !contains(body, `"code":1`) { + t.Errorf("Fail body should contain code:1, got %s", body) + } +} + +func TestFailWithCode(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + response.FailWithCode(c, response.CodeUnauthorized, "未授权") + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("FailWithCode status = %d", w.Code) + } +} + +func TestFailWithErrorNilDoesNotPanic_M6(t *testing.T) { + r := setupTestRouter() + r.Use(func(c *gin.Context) { + c.Set("request_id", "req-m6") + c.Next() + }) + r.GET("/test", func(c *gin.Context) { + response.FailWithError(c, nil) + }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/test", nil)) + + if w.Code != 200 { + t.Fatalf("FailWithError(nil) status = %d, want 200 in business mode", w.Code) + } + var body response.Response + if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil { + t.Fatalf("decode response: %v", err) + } + if body.Code != response.CodeServerError { + t.Fatalf("code = %d, want %d", body.Code, response.CodeServerError) + } + if body.RequestID != "req-m6" { + t.Fatalf("request_id = %q, want req-m6", body.RequestID) + } +} + +func TestUnauthorized(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + response.Unauthorized(c, "请先登录") + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("Unauthorized status = %d", w.Code) + } +} + +func TestNotFound(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + response.NotFound(c, "资源不存在") + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("NotFound status = %d", w.Code) + } +} + +func TestServerError(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + response.ServerError(c, "服务器错误") + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("ServerError status = %d", w.Code) + } +} + +func TestRateLimit(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + response.RateLimit(c) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("RateLimit status = %d", w.Code) + } + + body := w.Body.String() + if !contains(body, `"code":`) { + t.Errorf("RateLimit body should contain code, got %s", body) + } +} + +func TestPage(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + items := []string{"a", "b", "c"} + response.Page(c, items, 100, 1, 20) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("Page status = %d", w.Code) + } + + body := w.Body.String() + if !contains(body, `"total":100`) { + t.Errorf("Page body should contain total:100, got %s", body) + } +} + +func TestDownload(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + data := []byte("test file content") + response.Download(c, "test.txt", data) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("Download status = %d", w.Code) + } + + // 验证响应头 + contentType := w.Header().Get("Content-Type") + if contentType != "application/octet-stream" { + t.Errorf("Download Content-Type = %s, want application/octet-stream", contentType) + } + + disposition := w.Header().Get("Content-Disposition") + if !contains(disposition, "test.txt") { + t.Errorf("Download Content-Disposition should contain filename, got %s", disposition) + } +} + +// TestDownloadChineseFilename_M6：中文文件名经 RFC 5987 编码（filename*），不乱码。 +func TestDownloadChineseFilename_M6(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + response.Download(c, "报告.txt", []byte("x")) + }) + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/test", nil)) + + disposition := w.Header().Get("Content-Disposition") + // 应含 RFC 5987 编码的 filename*（百分号编码），且无原始 UTF-8 字节直接拼入 filename= 段 + if !contains(disposition, "filename*=UTF-8''") { + t.Fatalf("Content-Disposition should contain filename*=UTF-8''..., got %s", disposition) + } + if !contains(disposition, "%E6%8A%A5%E5%91%8A") { // "报告" 的百分号编码 + t.Fatalf("Content-Disposition should contain percent-encoded 报告, got %s", disposition) + } + // ASCII 回退名不应为空 + if !contains(disposition, `filename="`) { + t.Fatalf("Content-Disposition should contain ASCII fallback filename, got %s", disposition) + } +} + +func TestDownloadWithContentType(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + data := []byte("test file content") + response.DownloadWithContentType(c, "test.pdf", "application/pdf", data) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("DownloadWithContentType status = %d", w.Code) + } + + contentType := w.Header().Get("Content-Type") + if contentType != "application/pdf" { + t.Errorf("DownloadWithContentType = %s, want application/pdf", contentType) + } +} + +func TestDownloadReaderStreamsContent_M6(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + response.DownloadReader(c, "big.txt", "text/plain", 11, strings.NewReader("hello world")) + }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest("GET", "/test", nil)) + + if w.Code != 200 { + t.Fatalf("DownloadReader status = %d, want 200", w.Code) + } + if got := w.Header().Get("Content-Type"); !contains(got, "text/plain") { + t.Fatalf("Content-Type = %q, want text/plain", got) + } + if got := w.Header().Get("Content-Length"); got != "11" { + t.Fatalf("Content-Length = %q, want 11", got) + } + if got := w.Body.String(); got != "hello world" { + t.Fatalf("body = %q, want hello world", got) + } +} + +func TestHTML(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + response.HTML(c, "Hello") + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("HTML status = %d", w.Code) + } + + contentType := w.Header().Get("Content-Type") + if !contains(contentType, "text/html") { + t.Errorf("HTML Content-Type should be text/html, got %s", contentType) + } +} + +func TestRedirect(t *testing.T) { + r := setupTestRouter() + r.GET("/test", func(c *gin.Context) { + response.Redirect(c, 302, "/new-location") + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + // 重定向返回 302 + if w.Code != 302 { + t.Errorf("Redirect status = %d, want 302", w.Code) + } + + location := w.Header().Get("Location") + if location != "/new-location" { + t.Errorf("Redirect Location = %s, want /new-location", location) + } +} + +func TestErrorCodes(t *testing.T) { + // 测试错误码定义 + if response.CodeSuccess != 0 { + t.Errorf("CodeSuccess = %d, want 0", response.CodeSuccess) + } + if response.CodeFail != 1 { + t.Errorf("CodeFail = %d, want 1", response.CodeFail) + } + if response.CodeUnauthorized == 0 { + t.Error("CodeUnauthorized should not be 0") + } + if response.CodeNotFound == 0 { + t.Error("CodeNotFound should not be 0") + } + if response.CodeServerError == 0 { + t.Error("CodeServerError should not be 0") + } + if response.CodeRateLimit == 0 { + t.Error("CodeRateLimit should not be 0") + } +} + +func TestResponseStructure(t *testing.T) { + // 测试 Response 结构体 + resp := response.Response{ + Code: 0, + Msg: "成功", + Data: gin.H{"id": 1}, + RequestID: "test-123", + } + + if resp.Code != 0 { + t.Error("Response Code failed") + } + if resp.Msg != "成功" { + t.Error("Response Msg failed") + } +} + +func TestPageDataStructure(t *testing.T) { + // 测试 PageData 结构体 + data := response.PageData{ + Items: []string{"a", "b"}, + Total: 100, + Page: 1, + PageSize: 20, + } + + if data.Total != 100 { + t.Error("PageData Total failed") + } +} + +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 +} diff --git a/router/health_test.go b/router/health_test.go new file mode 100644 index 0000000..aa5adde --- /dev/null +++ b/router/health_test.go @@ -0,0 +1,157 @@ +package router_test + +import ( + "context" + "errors" + "net/http" + "net/http/httptest" + "strings" + "sync/atomic" + "testing" + "time" + + "github.com/EthanCodeCraft/xlgo-core/router" +) + +func TestRegisterHealthRoute(t *testing.T) { + r := setupTestRouter() + router.RegisterHealthRoute(r) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/health", nil) + r.ServeHTTP(w, req) + if w.Code != http.StatusOK { + t.Fatalf("expected status 200, got %d", w.Code) + } + if !strings.Contains(w.Body.String(), `"status":"ok"`) { + t.Fatalf("expected ok health response, got %s", w.Body.String()) + } +} + +func TestRegisterHealthRouteWithChecks(t *testing.T) { + r := setupTestRouter() + router.RegisterHealthRoute(r, + router.HealthCheck{Name: "mysql", Check: func(context.Context) error { return nil }}, + router.HealthCheck{Name: "redis", Disabled: true}, + ) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/health", nil) + r.ServeHTTP(w, req) + if w.Code != http.StatusOK { + t.Fatalf("expected status 200, got %d", w.Code) + } + body := w.Body.String() + if !strings.Contains(body, `"mysql":"ok"`) || !strings.Contains(body, `"redis":"disabled"`) { + t.Fatalf("expected check statuses, got %s", body) + } +} + +func TestRegisterHealthRouteWithFailingCheck(t *testing.T) { + r := setupTestRouter() + router.RegisterHealthRoute(r, router.HealthCheck{Name: "mysql", Check: func(context.Context) error { return errors.New("down") }}) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/health", nil) + r.ServeHTTP(w, req) + if w.Code != http.StatusServiceUnavailable { + t.Fatalf("expected status 503, got %d", w.Code) + } + if !strings.Contains(w.Body.String(), `"status":"error"`) { + t.Fatalf("expected error health response, got %s", w.Body.String()) + } +} + +func TestRegisterHealthRouteTimesOutStuckCheck_M7(t *testing.T) { + r := setupTestRouter() + router.RegisterHealthRoute(r, router.HealthCheck{ + Name: "stuck", + Timeout: 10 * time.Millisecond, + Check: func(ctx context.Context) error { + <-ctx.Done() + return ctx.Err() + }, + }) + + w := httptest.NewRecorder() + start := time.Now() + r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/health", nil)) + + if w.Code != http.StatusServiceUnavailable { + t.Fatalf("status = %d, want 503", w.Code) + } + if elapsed := time.Since(start); elapsed > time.Second { + t.Fatalf("health check took %s, want bounded timeout", elapsed) + } + if !strings.Contains(w.Body.String(), `"stuck":"timeout"`) { + t.Fatalf("body = %s, want timeout status", w.Body.String()) + } +} + +func TestRegisterHealthRouteRecoversCheckPanic_M7(t *testing.T) { + r := setupTestRouter() + router.RegisterHealthRoute(r, router.HealthCheck{ + Name: "panic", + Check: func(context.Context) error { + panic("boom") + }, + }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/health", nil)) + + if w.Code != http.StatusServiceUnavailable { + t.Fatalf("status = %d, want 503", w.Code) + } + if !strings.Contains(w.Body.String(), `"panic":"error"`) { + t.Fatalf("body = %s, want panic check error status", w.Body.String()) + } +} + +func TestRegisterHealthRouteLimitsNonCooperativeCheckConcurrency_M7(t *testing.T) { + var started atomic.Int32 + release := make(chan struct{}) + defer close(release) + + r := setupTestRouter() + router.RegisterHealthRoute(r, router.HealthCheck{ + Name: "stuck", + Timeout: 10 * time.Millisecond, + Check: func(context.Context) error { + started.Add(1) + <-release + return nil + }, + }) + + for i := 0; i < 2; i++ { + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/health", nil)) + if w.Code != http.StatusServiceUnavailable { + t.Fatalf("request %d status = %d, want 503", i+1, w.Code) + } + } + + if got := started.Load(); got != 1 { + t.Fatalf("check started %d times, want 1 while first non-cooperative check is still running", got) + } +} + +func TestRegisterDefaultRoutes(t *testing.T) { + r := setupTestRouter() + router.RegisterDefaultRoutes(r) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/health", nil) + r.ServeHTTP(w, req) + if w.Code != http.StatusOK { + t.Fatalf("expected health status 200, got %d", w.Code) + } + + w = httptest.NewRecorder() + req = httptest.NewRequest(http.MethodGet, "/swagger/index.html", nil) + r.ServeHTTP(w, req) + if w.Code == http.StatusNotFound { + t.Fatal("expected swagger route to be registered") + } +} diff --git a/router/livez_readyz_test.go b/router/livez_readyz_test.go new file mode 100644 index 0000000..c8c4c45 --- /dev/null +++ b/router/livez_readyz_test.go @@ -0,0 +1,55 @@ +package router_test + +import ( + "context" + "errors" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/EthanCodeCraft/xlgo-core/router" +) + +func TestRegisterLivenessRoute(t *testing.T) { + r := setupTestRouter() + router.RegisterLivenessRoute(r) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/livez", nil)) + if w.Code != http.StatusOK { + t.Fatalf("livez status = %d, want 200", w.Code) + } + if !strings.Contains(w.Body.String(), `"status":"ok"`) { + t.Fatalf("livez body = %s", w.Body.String()) + } +} + +func TestRegisterReadinessRouteHealthy(t *testing.T) { + r := setupTestRouter() + router.RegisterReadinessRoute(r, + router.HealthCheck{Name: "mysql", Check: func(context.Context) error { return nil }}, + ) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/readyz", nil)) + if w.Code != http.StatusOK { + t.Fatalf("readyz status = %d, want 200", w.Code) + } +} + +func TestRegisterReadinessRouteUnhealthy(t *testing.T) { + r := setupTestRouter() + router.RegisterReadinessRoute(r, + router.HealthCheck{Name: "redis", Check: func(context.Context) error { return errors.New("down") }}, + ) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/readyz", nil)) + if w.Code != http.StatusServiceUnavailable { + t.Fatalf("readyz status = %d, want 503", w.Code) + } + if !strings.Contains(w.Body.String(), `"redis":"error"`) { + t.Fatalf("readyz body = %s", w.Body.String()) + } +} diff --git a/router/metrics.go b/router/metrics.go new file mode 100644 index 0000000..f80b99c --- /dev/null +++ b/router/metrics.go @@ -0,0 +1,26 @@ +package router + +import ( + "github.com/gin-gonic/gin" + "github.com/prometheus/client_golang/prometheus/promhttp" +) + +// RegisterMetricsRoute 注册 Prometheus 指标暴露端点（#18，H8c 修正）。 +// +// 默认路径 /metrics。传入 path 可自定义。本函数仅注册暴露端点，不再用 r.Use +// 挂采集中间件——采集中间件改由 Registry.SetMetricsMiddleware 在 Apply 内作为 +// 首个全局中间件装入，使所有经注册中心注册的业务路由都被采集，且不依赖本函数 +// 相对其他路由注册的调用顺序。/metrics 端点自身与 /health 等基础路由不经采集中间件。 +// +// 用法： +// +// router.RegisterMetricsRoute(r) // /metrics +// router.RegisterMetricsRoute(r, "/metrics") // 等价 +func RegisterMetricsRoute(r *gin.Engine, path ...string) { + p := "/metrics" + if len(path) > 0 && path[0] != "" { + p = path[0] + } + // 幂等注册（H8d 收尾）：重复调用跳过，避免重复路由 panic。 + registerGETOnce(r, p, gin.WrapH(promhttp.Handler())) +} diff --git a/router/router.go b/router/router.go new file mode 100644 index 0000000..4601c4b --- /dev/null +++ b/router/router.go @@ -0,0 +1,780 @@ +package router + +import ( + "context" + "errors" + "fmt" + "net/http" + "runtime/debug" + "sort" + "strings" + "sync" + "sync/atomic" + "time" + + "github.com/EthanCodeCraft/xlgo-core/logger" + "github.com/gin-gonic/gin" + swaggerFiles "github.com/swaggo/files" + ginSwagger "github.com/swaggo/gin-swagger" +) + +var routerWarnf atomic.Value // stores func(string, ...any) + +func warnf(format string, args ...any) { + if fn, ok := routerWarnf.Load().(func(string, ...any)); ok && fn != nil { + fn(format, args...) + return + } + logger.Warnf(format, args...) +} + +func isDuplicateRoutePanic(msg, path string) bool { + if strings.Contains(msg, "already registered") { + return true + } + if !strings.Contains(msg, "conflicts with existing wildcard") { + return false + } + return strings.Contains(msg, fmt.Sprintf("new path '%s'", path)) && + strings.Contains(msg, fmt.Sprintf("existing prefix '%s'", path)) +} + +// HealthCheck 健康检查项 +type HealthCheck struct { + Name string + Check func(context.Context) error + Disabled bool + Timeout time.Duration +} + +// DefaultHealthCheckTimeout bounds each dependency check so /health and /readyz +// do not hang behind a stuck database/client call. +const DefaultHealthCheckTimeout = 2 * time.Second + +type healthCheckRunner struct { + check HealthCheck + running chan struct{} +} + +func newHealthCheckRunners(checks []HealthCheck) []healthCheckRunner { + runners := make([]healthCheckRunner, len(checks)) + for i, check := range checks { + runners[i] = healthCheckRunner{ + check: check, + running: make(chan struct{}, 1), + } + } + return runners +} + +func healthCheckTimeout(check HealthCheck) time.Duration { + if check.Timeout > 0 { + return check.Timeout + } + return DefaultHealthCheckTimeout +} + +func healthCheckStatusFromContext(err error) string { + if errors.Is(err, context.DeadlineExceeded) { + return "timeout" + } + return "error" +} + +func (r healthCheckRunner) run(ctx context.Context) (string, error) { + check := r.check + checkCtx, cancel := context.WithTimeout(ctx, healthCheckTimeout(check)) + defer cancel() + + select { + case r.running <- struct{}{}: + case <-checkCtx.Done(): + return healthCheckStatusFromContext(checkCtx.Err()), checkCtx.Err() + } + + errCh := make(chan error, 1) + go func() { + defer func() { + <-r.running + }() + defer func() { + if rec := recover(); rec != nil { + errCh <- fmt.Errorf("health check %q panic recovered: %v\n%s", check.Name, rec, debug.Stack()) + } + }() + errCh <- check.Check(checkCtx) + }() + + select { + case err := <-errCh: + if err == nil { + return "ok", nil + } + return healthCheckStatusFromContext(err), err + case <-checkCtx.Done(): + return healthCheckStatusFromContext(checkCtx.Err()), checkCtx.Err() + } +} + +// registerGETOnce 幂等注册 GET 路由（H8d 收尾：消除 defaultModule 与 Register* 系列 +// 并存时 Gin 重复路由 panic 的 footgun）。若 (GET, path) 已存在则静默跳过——首次注册胜出。 +// +// 实现分两条路径： +// - *gin.Engine：经 Routes() 精确预检（method+path），命中即跳过；未命中则直接注册， +// 不吞 panic——真正不同的路由冲突仍按 gin 原语义 panic，不被掩盖。 +// - *gin.RouterGroup（gin 未暴露其 engine，无法预检）：用 recover 兜底，仅吞 gin 的 +// 重复路由 panic（"already registered" / "conflicts with existing wildcard"， +// 两者覆盖 gin 对重复注册的两类 panic），其余 panic 原样抛出。defaultModule 的 +// /swagger/*any 与 /health 重复注册即走此路径被吞。最坏情况（gin 改动文本）退化为 +// 当前行为（panic），不引入新风险。 +// +// 注册期单线程调用，无并发问题。 +func registerGETOnce(r gin.IRoutes, path string, h gin.HandlerFunc) { + if r == nil { + warnf("router: skip GET %q because routes is nil", path) + return + } + if h == nil { + warnf("router: skip GET %q because handler is nil", path) + return + } + switch route := r.(type) { + case *gin.Engine: + eng := route + if eng == nil { + warnf("router: skip GET %q because engine is nil", path) + return + } + for _, ri := range eng.Routes() { + if ri.Method == http.MethodGet && ri.Path == path { + warnf("router: duplicate GET %q skipped", path) + return + } + } + eng.GET(path, h) + return + case *gin.RouterGroup: + if route == nil { + warnf("router: skip GET %q because router group is nil", path) + return + } + } + defer func() { + if rec := recover(); rec != nil { + msg := fmt.Sprint(rec) + if isDuplicateRoutePanic(msg, path) { + warnf("router: duplicate GET %q skipped: %v", path, rec) + return // 重复路由，静默跳过 + } + panic(rec) // 非重复路由 panic，原样抛出 + } + }() + r.GET(path, h) +} + +// runHealthChecks 执行所有检查项，返回总体状态、HTTP code 与逐项结果。 +// 无检查项时视为健康（用于 /livez 与无依赖场景）。 +func runHealthChecks(ctx context.Context, runners []healthCheckRunner) (string, int, map[string]string) { + if len(runners) == 0 { + return "ok", http.StatusOK, nil + } + status := "ok" + code := http.StatusOK + result := make(map[string]string, len(runners)) + for _, runner := range runners { + check := runner.check + if check.Name == "" { + continue + } + if check.Disabled || check.Check == nil { + result[check.Name] = "disabled" + continue + } + checkStatus, err := runner.run(ctx) + result[check.Name] = checkStatus + if err != nil { + status = "error" + code = http.StatusServiceUnavailable + continue + } + } + return status, code, result +} + +// healthHandler 返回统一的 /health 风格响应（H8d 收敛）。 +// 无检查项时视为健康（200 + {"status":"ok"}）；有检查项时任一失败返回 503 +// 并附逐项结果。RegisterHealthRoute / RegisterReadinessRoute / defaultModule +// 均委托此实现，避免三个 /health 行为与响应体不一致。 +func healthHandler(checks []HealthCheck) gin.HandlerFunc { + runners := newHealthCheckRunners(checks) + return func(c *gin.Context) { + status, code, result := runHealthChecks(c.Request.Context(), runners) + if result == nil { + c.JSON(http.StatusOK, gin.H{"status": status}) + return + } + c.JSON(code, gin.H{"status": status, "checks": result}) + } +} + +// RegisterHealthRoute 注册健康检查路由（兼容端点，等价于 readiness）。 +// 幂等：若 /health 已注册则跳过（首次注册胜出），避免与 defaultModule 等并存时重复路由 panic。 +func RegisterHealthRoute(r *gin.Engine, checks ...HealthCheck) { + registerGETOnce(r, "/health", healthHandler(checks)) +} + +// RegisterLivenessRoute 注册存活性探针（#17）。 +// GET /livez 永不依赖外部，仅表示进程存活，始终返回 200。 +// 供 K8s livenessProbe 使用：失败由进程崩溃体现，而非端点返回 503。 +// 幂等：重复注册跳过。 +func RegisterLivenessRoute(r *gin.Engine) { + registerGETOnce(r, "/livez", func(c *gin.Context) { + c.JSON(http.StatusOK, gin.H{"status": "ok"}) + }) +} + +// RegisterReadinessRoute 注册就绪性探针（#17）。 +// GET /readyz 复用 HealthCheck 检查依赖（mysql/redis...），任一失败返回 503。 +// 供 K8s readinessProbe 使用：未就绪时不接流量。 +// 幂等：重复注册跳过。 +func RegisterReadinessRoute(r *gin.Engine, checks ...HealthCheck) { + registerGETOnce(r, "/readyz", healthHandler(checks)) +} + +// RegisterSwaggerRoutes 注册 Swagger 文档路由。幂等：重复注册跳过。 +func RegisterSwaggerRoutes(r *gin.Engine) { + registerGETOnce(r, "/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) +} + +// RegisterDefaultRoutes 注册框架默认路由（健康检查、Swagger） +// 用户可以选择使用或不使用这些默认路由 +func RegisterDefaultRoutes(r *gin.Engine, checks ...HealthCheck) { + RegisterSwaggerRoutes(r) + RegisterHealthRoute(r, checks...) +} + +// DefaultModule 默认路由模块（可用于 WithModules） +var DefaultModule = &defaultModule{} + +type defaultModule struct{} + +func (m *defaultModule) Name() string { return "default" } +func (m *defaultModule) Register(r *gin.RouterGroup) { + // 作为模块注册时，路由在根路径。经 registerGETOnce 幂等注册（H8d 收尾）： + // 若用户已通过 RegisterSwaggerRoutes / RegisterHealthRoute 注册过同名路由， + // 此处静默跳过，避免 Gin 重复路由 panic。首次注册胜出。 + registerGETOnce(r, "/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) + registerGETOnce(r, "/health", healthHandler(nil)) +} + +// Module 路由模块接口 +// 用户实现此接口来注册业务路由 +type Module interface { + // Name 模块名称（用于日志和调试） + Name() string + // Register 注册路由到指定组 + Register(r *gin.RouterGroup) +} + +// ModuleFunc 函数式模块（简化单文件模块注册） +type ModuleFunc func(r *gin.RouterGroup) + +// Register 实现 Module 接口 +func (f ModuleFunc) Register(r *gin.RouterGroup) { + f(r) +} + +// Name 实现 Module 接口（函数式模块默认名称） +func (f ModuleFunc) Name() string { + return "func-module" +} + +// VersionedAPI 版本化 API 配置 +type VersionedAPI struct { + Version string // 版本标识，如 "v1", "v2" + BasePath string // 基础路径，如 "/api/v1" + Modules []Module // 该版本的模块列表 + Middlewares []gin.HandlerFunc // 该版本的公共中间件 +} + +// MiddlewareGroup 中间件分组 +type MiddlewareGroup struct { + Name string + Middlewares []gin.HandlerFunc +} + +// Registry 路由注册中心 +type Registry struct { + mu sync.Mutex + engine *gin.Engine + modules []Module + versions map[string]*VersionedAPI + middlewareGroups map[string]*MiddlewareGroup + globalMiddlewares []gin.HandlerFunc + + // metricsMiddleware 在 Apply 时作为首个全局中间件装入（H8c）， + // 使所有经注册中心注册的路由都被采集，不依赖 RegisterMetricsRoute 的调用顺序。 + // 为 nil 时不装入。/metrics 端点本身与 /health 等基础路由直接挂在 engine 上， + // 不经此中间件，故不被自采集。 + metricsMiddleware gin.HandlerFunc + + // applyOnce 保证 Apply 仅执行一次（H8b + P1 #13）。 + // 原实现用裸 bool 无同步，并发 Apply 会竞态并可能重复 engine.Use/重复注册致 gin panic； + // 改用 sync.Once，二次/并发 Apply 均安全幂等。 + applyOnce sync.Once + applied atomic.Bool +} + +// NewRegistry 创建路由注册中心 +func NewRegistry(engine *gin.Engine) *Registry { + return &Registry{ + engine: engine, + modules: make([]Module, 0), + versions: make(map[string]*VersionedAPI), + middlewareGroups: make(map[string]*MiddlewareGroup), + } +} + +func (r *Registry) lockForMutation(action string) (func(), bool) { + if r == nil { + warnf("router: skip %s because registry is nil", action) + return nil, false + } + r.mu.Lock() + if r.applied.Load() { + r.mu.Unlock() + warnf("router: %s called after Apply; registration will not take effect", action) + return nil, false + } + return r.mu.Unlock, true +} + +func filterNilHandlers(action string, handlers []gin.HandlerFunc) []gin.HandlerFunc { + out := make([]gin.HandlerFunc, 0, len(handlers)) + for _, h := range handlers { + if h == nil { + warnf("router: nil middleware skipped in %s", action) + continue + } + out = append(out, h) + } + return out +} + +// Use 注册全局中间件 +func (r *Registry) Use(middlewares ...gin.HandlerFunc) *Registry { + unlock, ok := r.lockForMutation("Use") + if !ok { + return r + } + defer unlock() + r.globalMiddlewares = append(r.globalMiddlewares, filterNilHandlers("Use", middlewares)...) + return r +} + +// RegisterModule 注册模块（无版本） +func (r *Registry) RegisterModule(module Module) *Registry { + unlock, ok := r.lockForMutation("RegisterModule") + if !ok { + return r + } + defer unlock() + if module == nil { + warnf("router: nil module skipped") + return r + } + r.modules = append(r.modules, module) + return r +} + +// RegisterModuleFunc 注册函数式模块 +func (r *Registry) RegisterModuleFunc(name string, fn func(r *gin.RouterGroup)) *Registry { + if fn == nil { + warnf("router: module func %q skipped because function is nil", name) + return r + } + return r.RegisterModule(&namedModule{name: name, fn: fn}) +} + +// namedModule 命名模块包装（内部类型） +type namedModule struct { + name string + fn func(r *gin.RouterGroup) +} + +func (m *namedModule) Name() string { return m.name } +func (m *namedModule) Register(r *gin.RouterGroup) { m.fn(r) } + +// RegisterVersion 注册版本化 API +func (r *Registry) RegisterVersion(version *VersionedAPI) *Registry { + unlock, ok := r.lockForMutation("RegisterVersion") + if !ok { + return r + } + defer unlock() + if version == nil { + warnf("router: nil version skipped") + return r + } + version.Middlewares = filterNilHandlers("RegisterVersion "+version.Version, version.Middlewares) + if _, exists := r.versions[version.Version]; exists { + warnf("router: duplicate version %q overwritten", version.Version) + } + r.versions[version.Version] = version + return r +} + +// RegisterMiddlewareGroup 注册中间件分组 +func (r *Registry) RegisterMiddlewareGroup(group *MiddlewareGroup) *Registry { + unlock, ok := r.lockForMutation("RegisterMiddlewareGroup") + if !ok { + return r + } + defer unlock() + if group == nil { + warnf("router: nil middleware group skipped") + return r + } + group.Middlewares = filterNilHandlers("RegisterMiddlewareGroup "+group.Name, group.Middlewares) + if _, exists := r.middlewareGroups[group.Name]; exists { + warnf("router: duplicate middleware group %q overwritten", group.Name) + } + r.middlewareGroups[group.Name] = group + return r +} + +// GetMiddlewareGroup 获取中间件分组 +func (r *Registry) GetMiddlewareGroup(name string) []gin.HandlerFunc { + if r == nil { + warnf("router: GetMiddlewareGroup(%q) on nil registry", name) + return nil + } + r.mu.Lock() + defer r.mu.Unlock() + if group, ok := r.middlewareGroups[name]; ok { + return append([]gin.HandlerFunc(nil), group.Middlewares...) + } + return nil +} + +// SetMetricsMiddleware 设置指标采集中间件（H8c）。Apply 时它会作为首个全局中间件 +// 装入 engine，使所有经注册中心注册的路由都被采集，不再依赖注册顺序。 +// 传入 nil 清除。须在 Apply 之前调用。 +func (r *Registry) SetMetricsMiddleware(mw gin.HandlerFunc) { + unlock, ok := r.lockForMutation("SetMetricsMiddleware") + if !ok { + return + } + defer unlock() + r.metricsMiddleware = mw +} + +type versionApplySnapshot struct { + isNil bool + version string + basePath string + middlewares []gin.HandlerFunc + modules []Module +} + +// Apply 应用所有路由注册。 +// +// 幂等（H8b）：二次调用直接返回，避免重复 engine.Use 与 Gin 重复路由 panic。 +// 装入顺序：metrics 中间件（若有）→ 用户全局中间件 → 模块/版本路由。 +// metrics 置于首位保证全量业务路由被采集，且不依赖 RegisterMetricsRoute 调用顺序。 +func (r *Registry) Apply() { + if r == nil { + warnf("router: Apply called on nil registry") + return + } + if r.engine == nil { + warnf("router: Apply skipped because engine is nil") + return + } + r.applyOnce.Do(func() { + r.mu.Lock() + r.applied.Store(true) + metricsMiddleware := r.metricsMiddleware + globalMiddlewares := append([]gin.HandlerFunc(nil), r.globalMiddlewares...) + modules := append([]Module(nil), r.modules...) + versions := make([]versionApplySnapshot, 0, len(r.versions)) + versionKeys := make([]string, 0, len(r.versions)) + for k := range r.versions { + versionKeys = append(versionKeys, k) + } + sort.Strings(versionKeys) + for _, k := range versionKeys { + v := r.versions[k] + if v == nil { + versions = append(versions, versionApplySnapshot{isNil: true, version: k}) + continue + } + versions = append(versions, versionApplySnapshot{ + version: v.Version, + basePath: v.BasePath, + middlewares: append([]gin.HandlerFunc(nil), v.Middlewares...), + modules: append([]Module(nil), v.Modules...), + }) + } + r.mu.Unlock() + + // 指标采集中间件首个装入，统计所有经注册中心注册的业务路由 + if metricsMiddleware != nil { + r.engine.Use(metricsMiddleware) + } + + // 应用全局中间件 + r.engine.Use(globalMiddlewares...) + + // 注册无版本模块 + for _, module := range modules { + if module == nil { + warnf("router: nil module skipped during Apply") + continue + } + module.Register(r.engine.Group("")) + } + + // 注册版本化 API。P1 #13：按 version 键排序遍历，使跨版本注册顺序确定， + // 避免 map 随机序导致重叠路径"谁先胜出"（配合 registerGETOnce）每次运行不一致。 + for _, v := range versions { + if v.isNil { + warnf("router: nil version %q skipped during Apply", v.version) + continue + } + group := r.engine.Group(v.basePath) + if len(v.middlewares) > 0 { + group.Use(v.middlewares...) + } + for _, module := range v.modules { + if module == nil { + warnf("router: nil module skipped in version %q", v.version) + continue + } + module.Register(group) + } + } + }) +} + +// ===== 全局注册中心 ===== + +// globalRegistry 包级全局注册中心。用 atomic.Pointer 保护读写（H8a）： +// Init 写入、各全局 helper 读取，避免裸指针与请求 goroutine 的无锁竞争。 +var globalRegistry atomic.Pointer[Registry] + +// Init 初始化全局注册中心。须在使用任何全局 helper（Use/RegisterModule/Apply…）之前调用。 +func Init(engine *gin.Engine) *Registry { + r := NewRegistry(engine) + globalRegistry.Store(r) + return r +} + +// GetRegistry 获取全局注册中心，未初始化时返回 nil。 +func GetRegistry() *Registry { + return globalRegistry.Load() +} + +// ensureRegistry 取全局注册中心，未初始化时以明确信息 panic（H8a）。 +// 把晦涩的 nil 解引用 panic 转成可定位的初始化顺序错误。 +func ensureRegistry() *Registry { + r := globalRegistry.Load() + if r == nil { + panic("router: 全局注册中心未初始化，请先调用 router.Init(engine) 再使用全局 helper") + } + return r +} + +// Use 注册全局中间件（全局方式） +func Use(middlewares ...gin.HandlerFunc) *Registry { + return ensureRegistry().Use(middlewares...) +} + +// RegisterModule 注册模块（全局方式） +func RegisterModule(module Module) *Registry { + return ensureRegistry().RegisterModule(module) +} + +// RegisterModuleFunc 注册函数式模块（全局方式） +func RegisterModuleFunc(name string, fn func(r *gin.RouterGroup)) *Registry { + return ensureRegistry().RegisterModuleFunc(name, fn) +} + +// RegisterVersion 注册版本化 API（全局方式） +func RegisterVersion(version *VersionedAPI) *Registry { + return ensureRegistry().RegisterVersion(version) +} + +// Apply 应用路由注册（全局方式） +func Apply() { + ensureRegistry().Apply() +} + +// ===== 快捷构建函数 ===== + +// NewVersion 创建版本化 API +func NewVersion(version, basePath string, middlewares ...gin.HandlerFunc) *VersionedAPI { + return &VersionedAPI{ + Version: version, + BasePath: basePath, + Middlewares: filterNilHandlers("NewVersion "+version, middlewares), + Modules: make([]Module, 0), + } +} + +// AddModule 为版本添加模块 +func (v *VersionedAPI) AddModule(module Module) *VersionedAPI { + if v == nil { + warnf("router: AddModule called on nil version") + return v + } + if module == nil { + warnf("router: nil module skipped in version %q", v.Version) + return v + } + v.Modules = append(v.Modules, module) + return v +} + +// AddModuleFunc 为版本添加函数式模块 +func (v *VersionedAPI) AddModuleFunc(name string, fn func(r *gin.RouterGroup)) *VersionedAPI { + if fn == nil { + warnf("router: module func %q skipped because function is nil", name) + return v + } + return v.AddModule(&namedModule{name: name, fn: fn}) +} + +// NewMiddlewareGroup 创建中间件分组 +func NewMiddlewareGroup(name string, middlewares ...gin.HandlerFunc) *MiddlewareGroup { + return &MiddlewareGroup{ + Name: name, + Middlewares: filterNilHandlers("NewMiddlewareGroup "+name, middlewares), + } +} + +// ===== 路由组辅助 ===== + +// Group 创建路由组（带中间件分组） +func Group(engine *gin.Engine, path string, middlewares ...gin.HandlerFunc) *gin.RouterGroup { + if engine == nil { + warnf("router: Group(%q) skipped because engine is nil", path) + return nil + } + return engine.Group(path, filterNilHandlers("Group "+path, middlewares)...) +} + +// GroupWithMiddlewareGroup 使用中间件分组创建路由组。 +// +// H-B 修复：改走 ensureRegistry()（与 Use/RegisterModule/Apply 等所有全局 helper 一致）， +// 把"未初始化"从 nil 解引用 panic 转成可定位的明确 panic（H8a 目标）。原实现用 GetRegistry() +// 可返回 nil，nil.GetMiddlewareGroup 即 panic，错误信息晦涩。 +func (r *Registry) GroupWithMiddlewareGroup(engine *gin.Engine, path string, groupName string) *gin.RouterGroup { + if engine == nil { + warnf("router: GroupWithMiddlewareGroup(%q) skipped because engine is nil", path) + return nil + } + return engine.Group(path, r.GetMiddlewareGroup(groupName)...) +} + +// GroupWithMiddlewareGroup 使用中间件分组创建路由组（全局方式，代理到默认 Registry）。 +func GroupWithMiddlewareGroup(engine *gin.Engine, path string, groupName string) *gin.RouterGroup { + return ensureRegistry().GroupWithMiddlewareGroup(engine, path, groupName) +} + +// RESTfulRoute RESTful 路由快捷注册 +type RESTfulRoute struct { + Group *gin.RouterGroup + Path string +} + +// NewRESTful 创建 RESTful 路由 +func NewRESTful(group *gin.RouterGroup, path string) *RESTfulRoute { + return &RESTfulRoute{Group: group, Path: path} +} + +func (r *RESTfulRoute) prepareHandlers(method string, handlers []gin.HandlerFunc) []gin.HandlerFunc { + if r == nil || r.Group == nil { + warnf("router: RESTful %s skipped because route/group is nil", method) + return nil + } + filtered := filterNilHandlers("RESTful "+method+" "+r.Path, handlers) + if len(filtered) == 0 { + warnf("router: RESTful %s %q skipped because handlers are empty", method, r.Path) + return nil + } + return filtered +} + +// GET 注册 GET 路由 +func (r *RESTfulRoute) GET(handlers ...gin.HandlerFunc) { + handlers = r.prepareHandlers(http.MethodGet, handlers) + if handlers == nil { + return + } + r.Group.GET(r.Path, handlers...) +} + +// POST 注册 POST 路由 +func (r *RESTfulRoute) POST(handlers ...gin.HandlerFunc) { + handlers = r.prepareHandlers(http.MethodPost, handlers) + if handlers == nil { + return + } + r.Group.POST(r.Path, handlers...) +} + +// PUT 注册 PUT 路由 +func (r *RESTfulRoute) PUT(handlers ...gin.HandlerFunc) { + handlers = r.prepareHandlers(http.MethodPut, handlers) + if handlers == nil { + return + } + r.Group.PUT(r.Path, handlers...) +} + +// DELETE 注册 DELETE 路由 +func (r *RESTfulRoute) DELETE(handlers ...gin.HandlerFunc) { + handlers = r.prepareHandlers(http.MethodDelete, handlers) + if handlers == nil { + return + } + r.Group.DELETE(r.Path, handlers...) +} + +// PATCH 注册 PATCH 路由 +func (r *RESTfulRoute) PATCH(handlers ...gin.HandlerFunc) { + handlers = r.prepareHandlers(http.MethodPatch, handlers) + if handlers == nil { + return + } + r.Group.PATCH(r.Path, handlers...) +} + +// CRUD 注册标准 CRUD 路由 +// GET /path - 列表 +// GET /path/:id - 详情 +// POST /path - 创建 +// PUT /path/:id - 更新 +// DELETE /path/:id - 删除 +func (r *RESTfulRoute) CRUD(list, detail, create, update, delete gin.HandlerFunc) { + if r == nil || r.Group == nil { + warnf("router: RESTful CRUD skipped because route/group is nil") + return + } + if list != nil { + r.Group.GET(r.Path, list) + } + if detail != nil { + r.Group.GET(r.Path+"/:id", detail) + } + if create != nil { + r.Group.POST(r.Path, create) + } + if update != nil { + r.Group.PUT(r.Path+"/:id", update) + } + if delete != nil { + r.Group.DELETE(r.Path+"/:id", delete) + } +} diff --git a/router/router_h8_internal_test.go b/router/router_h8_internal_test.go new file mode 100644 index 0000000..ca29d5b --- /dev/null +++ b/router/router_h8_internal_test.go @@ -0,0 +1,271 @@ +package router + +import ( + "context" + "net/http" + "net/http/httptest" + "strings" + "sync" + "testing" + + "github.com/EthanCodeCraft/xlgo-core/middleware" + "github.com/gin-gonic/gin" +) + +// TestApplyIdempotent_H8b 复现 H8b：修复前二次 Apply 会重复 engine.Use 并触发 +// Gin 重复路由 panic；修复后二次 Apply 直接返回，无 panic、无重复中间件。 +func TestApplyIdempotent_H8b(t *testing.T) { + gin.SetMode(gin.TestMode) + engine := gin.New() + r := NewRegistry(engine) + + runs := 0 + r.Use(func(c *gin.Context) { runs++; c.Next() }) + r.RegisterModuleFunc("test", func(g *gin.RouterGroup) { + g.GET("/h8b", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) }) + }) + + r.Apply() + r.Apply() // 二次 Apply 必须无 panic + r.Apply() // 三次同样 + + // 幂等性由下方 runs==1 断言验证（P1 #13：applied bool 已改为 sync.Once， + // 无导出标志可查；若 Apply 非幂等则中间件会被重复装入致 runs>1）。 + + // 中间件只应被装入一次：请求一次，runs 应为 1（若重复装入则 >1）。 + w := httptest.NewRecorder() + engine.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/h8b", nil)) + if w.Code != 200 { + t.Fatalf("status = %d, want 200", w.Code) + } + if runs != 1 { + t.Fatalf("global middleware ran %d times, want 1 (Apply not idempotent)", runs) + } +} + +// TestApplyConcurrent_P1_13 验证并发 Apply 无 data race 且仅生效一次（sync.Once）。 +// 修复前 applied 为裸 bool，多 goroutine 并发 Apply 竞态可重复 engine.Use/重复注册致 panic。 +// 须配合 -race 运行。 +func TestApplyConcurrent_P1_13(t *testing.T) { + gin.SetMode(gin.TestMode) + engine := gin.New() + r := NewRegistry(engine) + + runs := 0 + r.Use(func(c *gin.Context) { runs++; c.Next() }) + r.RegisterModuleFunc("p113", func(g *gin.RouterGroup) { + g.GET("/p113", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) }) + }) + + var wg sync.WaitGroup + for i := 0; i < 20; i++ { + wg.Add(1) + go func() { defer wg.Done(); r.Apply() }() + } + wg.Wait() + + w := httptest.NewRecorder() + engine.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/p113", nil)) + if w.Code != 200 { + t.Fatalf("status = %d, want 200", w.Code) + } + if runs != 1 { + t.Fatalf("global middleware ran %d times, want 1 (concurrent Apply not once)", runs) + } +} + +// TestMetricsMiddlewareFirstInApply_H8c 验证 metrics 中间件经 SetMetricsMiddleware +// 在 Apply 内装入，覆盖所有经注册中心注册的路由，且不依赖 RegisterMetricsRoute +// 的调用顺序。修复前 RegisterMetricsRoute 用 r.Use，先注册的路由不被采集。 +func TestMetricsMiddlewareFirstInApply_H8c(t *testing.T) { + gin.SetMode(gin.TestMode) + engine := gin.New() + r := NewRegistry(engine) + + // 用一个计数中间件模拟 metrics 采集。 + hits := 0 + r.SetMetricsMiddleware(func(c *gin.Context) { + hits++ + c.Next() + }) + + r.RegisterModuleFunc("biz", func(g *gin.RouterGroup) { + g.GET("/biz", func(c *gin.Context) { c.JSON(200, gin.H{}) }) + }) + // 注意：不调用 RegisterMetricsRoute，仅靠 SetMetricsMiddleware + Apply 装入。 + r.Apply() + + w := httptest.NewRecorder() + engine.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/biz", nil)) + if w.Code != 200 { + t.Fatalf("biz status = %d, want 200", w.Code) + } + if hits != 1 { + t.Fatalf("metrics middleware hits = %d, want 1 (route not instrumented)", hits) + } +} + +// TestMetricsMiddlewareNilSkipped_H8c：未设置 metrics 中间件时 Apply 不应装入空壳。 +func TestMetricsMiddlewareNilSkipped_H8c(t *testing.T) { + gin.SetMode(gin.TestMode) + engine := gin.New() + r := NewRegistry(engine) + if r.metricsMiddleware != nil { + t.Fatal("default metricsMiddleware should be nil") + } + r.Apply() // 不应 panic +} + +// TestEnsureRegistryPanicsBeforeInit_H8a 复现 H8a：修复前 Init 之前调全局 helper +// 触发 nil 解引用 panic；修复后为带明确信息的 panic。 +func TestEnsureRegistryPanicsBeforeInit_H8a(t *testing.T) { + // 保存并清空全局注册中心，测试后恢复，避免污染其它测试。 + prev := globalRegistry.Load() + globalRegistry.Store(nil) + t.Cleanup(func() { globalRegistry.Store(prev) }) + + var got any + func() { + defer func() { got = recover() }() + Apply() + }() + if got == nil { + t.Fatal("Apply before Init should panic, got nil") + } + msg, ok := got.(string) + if !ok { + t.Fatalf("panic value should be string, got %T: %v", got, got) + } + if !strings.Contains(msg, "router.Init") { + t.Fatalf("panic message should mention router.Init, got %q", msg) + } +} + +// TestGlobalRegistryAtomicConcurrent_H8a：并发 Init/GetRegistry 不触发 data race +// （atomic.Pointer 保护）。须配合 -race 运行。 +func TestGlobalRegistryAtomicConcurrent_H8a(t *testing.T) { + prev := globalRegistry.Load() + t.Cleanup(func() { globalRegistry.Store(prev) }) + + var wg sync.WaitGroup + for i := 0; i < 50; i++ { + wg.Add(2) + go func() { defer wg.Done(); Init(gin.New()) }() + go func() { defer wg.Done(); _ = GetRegistry() }() + } + wg.Wait() +} + +// TestHealthHandlerConvergedSchema_H8d 验证 defaultModule / RegisterHealthRoute(无 checks) +// 与 handler 风格的 /health 同 schema：200 + {"status":"ok"}。 +func TestHealthHandlerConvergedSchema_H8d(t *testing.T) { + gin.SetMode(gin.TestMode) + engine := gin.New() + r := NewRegistry(engine) + r.RegisterModule(&defaultModule{}) + r.Apply() + + w := httptest.NewRecorder() + engine.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/health", nil)) + if w.Code != 200 { + t.Fatalf("defaultModule /health status = %d, want 200", w.Code) + } + body := w.Body.String() + if !strings.Contains(body, `"status":"ok"`) { + t.Fatalf("defaultModule /health body = %s, want {\"status\":\"ok\"}", body) + } + // 不应携带 response 业务信封字段。 + if strings.Contains(body, `"code"`) || strings.Contains(body, `"data"`) { + t.Fatalf("defaultModule /health should not use response envelope, got %s", body) + } +} + +// 编译期保证 middleware 包仍可独立使用（H8c 回归用）。 +var _ gin.HandlerFunc = middleware.Metrics() + +// TestDefaultModuleAndRegisterHealthRouteCoexist_H8dfootgun 复现 H8d 收尾 footgun： +// 修复前 WithDefaultRoutes()+WithModules(DefaultModule) 并存会触发 Gin 重复路由 panic； +// 修复后 registerGETOnce 使二者幂等共存，/health 与 /swagger 均可访问。 +// 此测试模拟 app.go 的真实顺序：Register* 先注册（带 checks），defaultModule 经 Apply 后注册。 +func TestDefaultModuleAndRegisterHealthRouteCoexist_H8dfootgun(t *testing.T) { + gin.SetMode(gin.TestMode) + engine := gin.New() + + // 先经 Register* 注册（等价 app.go Init 中 enableHealth/enableSwagger 段） + RegisterHealthRoute(engine, HealthCheck{Name: "mysql", Check: func(context.Context) error { return nil }}) + RegisterSwaggerRoutes(engine) + // 再经注册中心注册 DefaultModule（等价 app.go registry.Apply()） + r := NewRegistry(engine) + r.RegisterModule(&defaultModule{}) + r.Apply() // 修复前在此 panic: handlers are already registered for path '/health' + + // /health 仍可访问，且首次注册（带 checks）胜出——响应含 checks 字段。 + w := httptest.NewRecorder() + engine.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/health", nil)) + if w.Code != 200 { + t.Fatalf("/health status = %d, want 200", w.Code) + } + if !strings.Contains(w.Body.String(), `"mysql":"ok"`) { + t.Fatalf("first registration (with checks) should win, got %s", w.Body.String()) + } + + // /swagger/*any 注册存在（非 404 即说明路由已注册） + w2 := httptest.NewRecorder() + engine.ServeHTTP(w2, httptest.NewRequest(http.MethodGet, "/swagger/index.html", nil)) + if w2.Code == http.StatusNotFound { + t.Fatal("/swagger/*any should be registered, got 404") + } +} + +// TestRegisterHealthRouteIdempotent_H8dfootgun：RegisterHealthRoute 重复调用不 panic。 +func TestRegisterHealthRouteIdempotent_H8dfootgun(t *testing.T) { + gin.SetMode(gin.TestMode) + engine := gin.New() + RegisterHealthRoute(engine, HealthCheck{Name: "a", Check: func(context.Context) error { return nil }}) + RegisterHealthRoute(engine) // 重复，不 panic + RegisterHealthRoute(engine) // 三次，不 panic + + w := httptest.NewRecorder() + engine.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/health", nil)) + if w.Code != 200 { + t.Fatalf("/health status = %d, want 200", w.Code) + } +} + +// TestDefaultModuleOnly_H8dfootgun：仅用 defaultModule（不预先 Register*）时， +// /health 与 /swagger 仍正常注册（recover 兜底路径不影响首次注册）。 +func TestDefaultModuleOnly_H8dfootgun(t *testing.T) { + gin.SetMode(gin.TestMode) + engine := gin.New() + r := NewRegistry(engine) + r.RegisterModule(&defaultModule{}) + r.Apply() + + w := httptest.NewRecorder() + engine.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/health", nil)) + if w.Code != 200 { + t.Fatalf("/health status = %d, want 200", w.Code) + } + if !strings.Contains(w.Body.String(), `"status":"ok"`) { + t.Fatalf("/health body = %s", w.Body.String()) + } +} + +// TestRegisterGETOnceEngineDoesNotSwallowRealConflict_H8dfootgun：Engine 路径经 Routes() +// 精确预检，未命中即直接注册（无 recover）。真正不同的路由冲突（如 /foo/:id 已存在再注册 +// /foo/*any）仍按 gin 原语义 panic，不被掩盖——证明幂等只吞"同一 path 重复"，不掩盖真实冲突。 +func TestRegisterGETOnceEngineDoesNotSwallowRealConflict_H8dfootgun(t *testing.T) { + gin.SetMode(gin.TestMode) + engine := gin.New() + engine.GET("/foo/:id", func(c *gin.Context) {}) + + var got any + func() { + defer func() { got = recover() }() + registerGETOnce(engine, "/foo/*any", func(c *gin.Context) {}) // 与 :id 真实冲突 + }() + if got == nil { + t.Fatal("registerGETOnce (Engine) should panic on real (different-path) conflict, got nil") + } +} + diff --git a/router/router_m7_internal_test.go b/router/router_m7_internal_test.go new file mode 100644 index 0000000..73880e1 --- /dev/null +++ b/router/router_m7_internal_test.go @@ -0,0 +1,196 @@ +package router + +import ( + "fmt" + "net/http" + "net/http/httptest" + "strings" + "sync" + "testing" + + "github.com/gin-gonic/gin" +) + +func captureRouterWarnings(t *testing.T) *[]string { + t.Helper() + var mu sync.Mutex + warnings := make([]string, 0) + prev, hadPrev := routerWarnf.Load().(func(string, ...any)) + routerWarnf.Store(func(format string, args ...any) { + mu.Lock() + defer mu.Unlock() + warnings = append(warnings, format) + }) + t.Cleanup(func() { + if hadPrev { + routerWarnf.Store(prev) + return + } + routerWarnf.Store(func(string, ...any) {}) + }) + return &warnings +} + +func warningsContain(warnings *[]string, substr string) bool { + for _, warning := range *warnings { + if strings.Contains(warning, substr) { + return true + } + } + return false +} + +func TestM7DuplicateGETWarnsAndSkips(t *testing.T) { + gin.SetMode(gin.TestMode) + warnings := captureRouterWarnings(t) + engine := gin.New() + + RegisterHealthRoute(engine) + RegisterHealthRoute(engine) + + if !warningsContain(warnings, "duplicate GET") { + t.Fatalf("duplicate registration should warn, got %#v", *warnings) + } + w := httptest.NewRecorder() + engine.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/health", nil)) + if w.Code != http.StatusOK { + t.Fatalf("/health status = %d, want 200", w.Code) + } +} + +func TestM7RouterGroupWildcardConflictPanics(t *testing.T) { + gin.SetMode(gin.TestMode) + engine := gin.New() + group := engine.Group("") + group.GET("/files/:id", func(c *gin.Context) {}) + + defer func() { + if rec := recover(); rec == nil { + t.Fatal("wildcard conflict should panic, not be swallowed as duplicate") + } + }() + registerGETOnce(group, "/files/*path", func(c *gin.Context) {}) +} + +func TestM7RegistryGroupWithMiddlewareGroupUsesLocalRegistry(t *testing.T) { + gin.SetMode(gin.TestMode) + engine := gin.New() + registry := NewRegistry(engine) + registry.RegisterMiddlewareGroup(NewMiddlewareGroup("auth", func(c *gin.Context) { + c.Set("auth", true) + c.Next() + })) + + group := registry.GroupWithMiddlewareGroup(engine, "/api", "auth") + if group == nil { + t.Fatal("GroupWithMiddlewareGroup returned nil") + } + group.GET("/check", func(c *gin.Context) { + v, _ := c.Get("auth") + c.JSON(http.StatusOK, gin.H{"auth": v}) + }) + + w := httptest.NewRecorder() + engine.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/api/check", nil)) + if w.Code != http.StatusOK || !strings.Contains(w.Body.String(), `"auth":true`) { + t.Fatalf("local middleware group not applied: status=%d body=%s", w.Code, w.Body.String()) + } +} + +func TestM7NilGuardsNoPanic(t *testing.T) { + warnings := captureRouterWarnings(t) + var nilRegistry *Registry + var nilEngine *gin.Engine + var nilGroup *gin.RouterGroup + var nilRoute *RESTfulRoute + + requireNoPanic := func(name string, fn func()) { + t.Helper() + defer func() { + if rec := recover(); rec != nil { + t.Fatalf("%s panicked: %v", name, rec) + } + }() + fn() + } + + requireNoPanic("RegisterHealthRoute nil engine", func() { RegisterHealthRoute(nilEngine) }) + requireNoPanic("DefaultModule nil group", func() { DefaultModule.Register(nilGroup) }) + requireNoPanic("nil registry Use", func() { nilRegistry.Use(nil) }) + requireNoPanic("nil registry RegisterModule", func() { nilRegistry.RegisterModule(nil) }) + requireNoPanic("nil registry RegisterVersion", func() { nilRegistry.RegisterVersion(nil) }) + requireNoPanic("nil registry RegisterMiddlewareGroup", func() { nilRegistry.RegisterMiddlewareGroup(nil) }) + requireNoPanic("nil registry GetMiddlewareGroup", func() { _ = nilRegistry.GetMiddlewareGroup("x") }) + requireNoPanic("nil registry Apply", func() { nilRegistry.Apply() }) + requireNoPanic("nil engine Group", func() { _ = Group(nil, "/x", nil) }) + requireNoPanic("nil RESTful GET", func() { nilRoute.GET(nil) }) + requireNoPanic("nil RESTful CRUD", func() { nilRoute.CRUD(nil, nil, nil, nil, nil) }) + + if len(*warnings) == 0 { + t.Fatal("nil guards should emit warnings") + } +} + +func TestM7RegistryApplyConcurrentMutationNoRace(t *testing.T) { + gin.SetMode(gin.TestMode) + _ = captureRouterWarnings(t) + engine := gin.New() + registry := NewRegistry(engine) + + const workers = 32 + start := make(chan struct{}) + var wg sync.WaitGroup + wg.Add(workers + 1) + + for i := 0; i < workers; i++ { + idx := i + go func() { + defer wg.Done() + <-start + registry.Use(func(c *gin.Context) { c.Next() }) + registry.RegisterMiddlewareGroup(NewMiddlewareGroup( + fmt.Sprintf("group-%d", idx), + func(c *gin.Context) { c.Next() }, + )) + registry.RegisterModuleFunc(fmt.Sprintf("module-%d", idx), func(g *gin.RouterGroup) { + g.GET(fmt.Sprintf("/m%d", idx), func(c *gin.Context) { c.Status(http.StatusOK) }) + }) + registry.RegisterVersion(NewVersion( + fmt.Sprintf("v%d", idx), + fmt.Sprintf("/v%d", idx), + ).AddModuleFunc("ping", func(g *gin.RouterGroup) { + g.GET("/ping", func(c *gin.Context) { c.Status(http.StatusOK) }) + })) + }() + } + + go func() { + defer wg.Done() + <-start + registry.Apply() + }() + + close(start) + wg.Wait() +} + +func TestM7RegisterAfterApplyWarnsAndDoesNotTakeEffect(t *testing.T) { + gin.SetMode(gin.TestMode) + warnings := captureRouterWarnings(t) + engine := gin.New() + registry := NewRegistry(engine) + registry.Apply() + + registry.RegisterModuleFunc("late", func(g *gin.RouterGroup) { + g.GET("/late", func(c *gin.Context) { c.Status(http.StatusOK) }) + }) + + if !warningsContain(warnings, "after Apply") { + t.Fatalf("late registration should warn, got %#v", *warnings) + } + w := httptest.NewRecorder() + engine.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/late", nil)) + if w.Code != http.StatusNotFound { + t.Fatalf("late route status = %d, want 404", w.Code) + } +} diff --git a/router/router_test.go b/router/router_test.go new file mode 100644 index 0000000..e6eaa8e --- /dev/null +++ b/router/router_test.go @@ -0,0 +1,459 @@ +package router_test + +import ( + "net/http/httptest" + "testing" + + "github.com/EthanCodeCraft/xlgo-core/router" + "github.com/gin-gonic/gin" +) + +func setupTestRouter() *gin.Engine { + gin.SetMode(gin.TestMode) + return gin.New() +} + +func TestNewRegistry(t *testing.T) { + engine := setupTestRouter() + registry := router.NewRegistry(engine) + + if registry == nil { + t.Error("NewRegistry should not return nil") + } +} + +func TestRegistryUse(t *testing.T) { + engine := setupTestRouter() + registry := router.NewRegistry(engine) + + result := registry.Use(func(c *gin.Context) { c.Next() }) + if result == nil { + t.Error("Use should return registry for chaining") + } +} + +func TestRegisterModule(t *testing.T) { + engine := setupTestRouter() + registry := router.NewRegistry(engine) + + module := &testModule{name: "test"} + result := registry.RegisterModule(module) + if result == nil { + t.Error("RegisterModule should return registry for chaining") + } +} + +func TestRegisterModuleFunc(t *testing.T) { + engine := setupTestRouter() + registry := router.NewRegistry(engine) + + result := registry.RegisterModuleFunc("test", func(r *gin.RouterGroup) { + r.GET("/test", func(c *gin.Context) { c.JSON(200, gin.H{}) }) + }) + if result == nil { + t.Error("RegisterModuleFunc should return registry for chaining") + } +} + +func TestNewVersion(t *testing.T) { + v := router.NewVersion("v1", "/api/v1") + + if v.Version != "v1" { + t.Errorf("Version = %s, want v1", v.Version) + } + if v.BasePath != "/api/v1" { + t.Errorf("BasePath = %s, want /api/v1", v.BasePath) + } +} + +func TestVersionAddModule(t *testing.T) { + v := router.NewVersion("v1", "/api/v1") + module := &testModule{name: "user"} + + result := v.AddModule(module) + if result == nil { + t.Error("AddModule should return VersionedAPI for chaining") + } +} + +func TestVersionAddModuleFunc(t *testing.T) { + v := router.NewVersion("v1", "/api/v1") + + result := v.AddModuleFunc("user", func(r *gin.RouterGroup) { + r.GET("/users", func(c *gin.Context) {}) + }) + if result == nil { + t.Error("AddModuleFunc should return VersionedAPI for chaining") + } +} + +func TestRegisterVersion(t *testing.T) { + engine := setupTestRouter() + registry := router.NewRegistry(engine) + + v := router.NewVersion("v1", "/api/v1") + result := registry.RegisterVersion(v) + if result == nil { + t.Error("RegisterVersion should return registry for chaining") + } +} + +func TestNewMiddlewareGroup(t *testing.T) { + group := router.NewMiddlewareGroup("auth", func(c *gin.Context) { c.Next() }) + + if group.Name != "auth" { + t.Errorf("Name = %s, want auth", group.Name) + } + if len(group.Middlewares) != 1 { + t.Errorf("Middlewares length = %d, want 1", len(group.Middlewares)) + } +} + +func TestRegisterMiddlewareGroup(t *testing.T) { + engine := setupTestRouter() + registry := router.NewRegistry(engine) + + group := router.NewMiddlewareGroup("auth") + result := registry.RegisterMiddlewareGroup(group) + if result == nil { + t.Error("RegisterMiddlewareGroup should return registry for chaining") + } +} + +func TestGetMiddlewareGroup(t *testing.T) { + engine := setupTestRouter() + registry := router.NewRegistry(engine) + + middleware := func(c *gin.Context) { c.Next() } + group := router.NewMiddlewareGroup("auth", middleware) + registry.RegisterMiddlewareGroup(group) + + mws := registry.GetMiddlewareGroup("auth") + if len(mws) != 1 { + t.Errorf("GetMiddlewareGroup length = %d, want 1", len(mws)) + } + + // 不存在的分组 + mws2 := registry.GetMiddlewareGroup("nonexistent") + if mws2 != nil { + t.Error("GetMiddlewareGroup nonexistent should return nil") + } +} + +func TestApply(t *testing.T) { + engine := setupTestRouter() + registry := router.NewRegistry(engine) + + registry.RegisterModuleFunc("test", func(r *gin.RouterGroup) { + r.GET("/hello", func(c *gin.Context) { + c.JSON(200, gin.H{"message": "hello"}) + }) + }) + + registry.Apply() + + // 测试路由是否生效 + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/hello", nil) + engine.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("Apply route status = %d, want 200", w.Code) + } +} + +func TestApplyWithVersion(t *testing.T) { + engine := setupTestRouter() + registry := router.NewRegistry(engine) + + v1 := router.NewVersion("v1", "/api/v1") + v1.AddModuleFunc("user", func(r *gin.RouterGroup) { + r.GET("/users", func(c *gin.Context) { + c.JSON(200, gin.H{"version": "v1"}) + }) + }) + registry.RegisterVersion(v1) + + registry.Apply() + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/api/v1/users", nil) + engine.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("Versioned route status = %d, want 200", w.Code) + } +} + +func TestApplyWithMiddleware(t *testing.T) { + engine := setupTestRouter() + registry := router.NewRegistry(engine) + + // 全局中间件 + registry.Use(func(c *gin.Context) { + c.Set("global", true) + c.Next() + }) + + registry.RegisterModuleFunc("test", func(r *gin.RouterGroup) { + r.GET("/test", func(c *gin.Context) { + val, _ := c.Get("global") + c.JSON(200, gin.H{"global": val}) + }) + }) + + registry.Apply() + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + engine.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("Middleware route status = %d", w.Code) + } +} + +func TestVersionMiddleware(t *testing.T) { + engine := setupTestRouter() + registry := router.NewRegistry(engine) + + v1 := router.NewVersion("v1", "/api/v1", func(c *gin.Context) { + c.Set("version", "v1") + c.Next() + }) + v1.AddModuleFunc("user", func(r *gin.RouterGroup) { + r.GET("/users", func(c *gin.Context) { + val, _ := c.Get("version") + c.JSON(200, gin.H{"version": val}) + }) + }) + registry.RegisterVersion(v1) + + registry.Apply() + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/api/v1/users", nil) + engine.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("Version middleware route status = %d", w.Code) + } +} + +func TestMultipleVersions(t *testing.T) { + engine := setupTestRouter() + registry := router.NewRegistry(engine) + + v1 := router.NewVersion("v1", "/api/v1") + v1.AddModuleFunc("user", func(r *gin.RouterGroup) { + r.GET("/users", func(c *gin.Context) { c.JSON(200, gin.H{"version": "v1"}) }) + }) + + v2 := router.NewVersion("v2", "/api/v2") + v2.AddModuleFunc("user", func(r *gin.RouterGroup) { + r.GET("/users", func(c *gin.Context) { c.JSON(200, gin.H{"version": "v2"}) }) + }) + + registry.RegisterVersion(v1) + registry.RegisterVersion(v2) + registry.Apply() + + // 测试 v1 + w1 := httptest.NewRecorder() + req1 := httptest.NewRequest("GET", "/api/v1/users", nil) + engine.ServeHTTP(w1, req1) + + // 测试 v2 + w2 := httptest.NewRecorder() + req2 := httptest.NewRequest("GET", "/api/v2/users", nil) + engine.ServeHTTP(w2, req2) + + if w1.Code != 200 || w2.Code != 200 { + t.Error("Multiple versions should both work") + } +} + +func TestInitAndGetRegistry(t *testing.T) { + engine := setupTestRouter() + registry := router.Init(engine) + + if registry == nil { + t.Error("Init should return registry") + } + + registry2 := router.GetRegistry() + if registry2 != registry { + t.Error("GetRegistry should return same registry") + } +} + +func TestGlobalFunctions(t *testing.T) { + engine := setupTestRouter() + router.Init(engine) + + router.Use(func(c *gin.Context) { c.Next() }) + router.RegisterModule(&testModule{name: "test"}) + router.RegisterVersion(router.NewVersion("v1", "/api/v1")) + + registry := router.GetRegistry() + if registry == nil { + t.Error("Global functions should work") + } +} + +func TestGlobalApply(t *testing.T) { + engine := setupTestRouter() + router.Init(engine) + + router.RegisterModuleFunc("hello", func(r *gin.RouterGroup) { + r.GET("/hello", func(c *gin.Context) { + c.JSON(200, gin.H{"message": "hello"}) + }) + }) + + router.Apply() + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/hello", nil) + engine.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("Global Apply status = %d, want 200", w.Code) + } +} + +func TestModuleFunc(t *testing.T) { + var mf router.ModuleFunc = func(r *gin.RouterGroup) { + r.GET("/test", func(c *gin.Context) {}) + } + + // 验证实现了 Module 接口 + var _ router.Module = mf +} + +func TestRESTfulRoute(t *testing.T) { + engine := setupTestRouter() + group := engine.Group("/api") + + rest := router.NewRESTful(group, "/users") + rest.GET(func(c *gin.Context) { c.JSON(200, gin.H{}) }) + rest.POST(func(c *gin.Context) { c.JSON(201, gin.H{}) }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/api/users", nil) + engine.ServeHTTP(w, req) + + if w.Code != 200 { + t.Errorf("RESTful GET status = %d", w.Code) + } +} + +func TestRESTfulCRUD(t *testing.T) { + engine := setupTestRouter() + group := engine.Group("/api") + + rest := router.NewRESTful(group, "/items") + rest.CRUD( + func(c *gin.Context) { c.JSON(200, gin.H{"action": "list"}) }, + func(c *gin.Context) { c.JSON(200, gin.H{"action": "detail"}) }, + func(c *gin.Context) { c.JSON(201, gin.H{"action": "create"}) }, + func(c *gin.Context) { c.JSON(200, gin.H{"action": "update"}) }, + func(c *gin.Context) { c.JSON(204, gin.H{}) }, + ) + + tests := []struct { + method string + path string + code int + }{ + {"GET", "/api/items", 200}, + {"GET", "/api/items/1", 200}, + {"POST", "/api/items", 201}, + {"PUT", "/api/items/1", 200}, + {"DELETE", "/api/items/1", 204}, + } + + for _, tt := range tests { + w := httptest.NewRecorder() + req := httptest.NewRequest(tt.method, tt.path, nil) + engine.ServeHTTP(w, req) + + if w.Code != tt.code { + t.Errorf("%s %s status = %d, want %d", tt.method, tt.path, w.Code, tt.code) + } + } +} + +func TestRESTfulPartialCRUD(t *testing.T) { + engine := setupTestRouter() + group := engine.Group("/api") + + rest := router.NewRESTful(group, "/items") + // 只注册 list 和 create + rest.CRUD( + func(c *gin.Context) { c.JSON(200, gin.H{}) }, // list + nil, // no detail + func(c *gin.Context) { c.JSON(201, gin.H{}) }, // create + nil, // no update + nil, // no delete + ) + + // list 存在 + w1 := httptest.NewRecorder() + req1 := httptest.NewRequest("GET", "/api/items", nil) + engine.ServeHTTP(w1, req1) + if w1.Code != 200 { + t.Error("Partial CRUD list should work") + } + + // detail 不存在（404） + w2 := httptest.NewRecorder() + req2 := httptest.NewRequest("GET", "/api/items/1", nil) + engine.ServeHTTP(w2, req2) + if w2.Code != 404 { + t.Errorf("Partial CRUD detail should be 404, got %d", w2.Code) + } +} + +func TestGroup(t *testing.T) { + engine := setupTestRouter() + group := router.Group(engine, "/api", func(c *gin.Context) { c.Next() }) + + if group == nil { + t.Error("Group should not return nil") + } +} + +func TestGroupWithMiddlewareGroup(t *testing.T) { + engine := setupTestRouter() + registry := router.NewRegistry(engine) + + registry.RegisterMiddlewareGroup(router.NewMiddlewareGroup("auth", func(c *gin.Context) { c.Next() })) + + group := registry.GroupWithMiddlewareGroup(engine, "/api", "auth") + if group == nil { + t.Error("GroupWithMiddlewareGroup should not return nil") + } +} + +func TestModuleInterface(t *testing.T) { + module := &testModule{name: "test"} + + // 测试 Name 方法 + if module.Name() != "test" { + t.Error("Module Name failed") + } + + // 测试实现了接口 + var _ router.Module = module +} + +// 测试模块实现 +type testModule struct { + name string +} + +func (m *testModule) Name() string { return m.name } +func (m *testModule) Register(r *gin.RouterGroup) { + r.GET("/"+m.name, func(c *gin.Context) { c.JSON(200, gin.H{"module": m.name}) }) +} diff --git a/scan_protocol.md b/scan_protocol.md new file mode 100644 index 0000000..935affe --- /dev/null +++ b/scan_protocol.md @@ -0,0 +1,90 @@ +# 扫描收敛协议（review discipline） + +> 本文件是 CLAUDE.md「开发纪律」的姊妹篇。开发纪律管"怎么写代码",本协议管"怎么审代码"。 +> 起源:多轮大模型全局复审非收敛--每换一个 reviewer 就重新生成一批 nits/功能建议/风格偏好,finding 数永不归零,压迫感持续累积却无关真实质量。本协议把复审收敛到"只产出严重问题"。 + +## 0. 一句话原则 + +**只报可达、真实、严重的缺陷。功能正常、质量良好、无 bug 的代码不报。低于 HIGH 一律不报。** + +## 1. 栅栏:只报 CRITICAL 与 HIGH + +仅当缺陷**同时**满足以下三条才计入交付: + +- **可达**:存在真实调用路径触发(必须给出路径:哪条调用链、什么输入、什么并发时序)。纸上推演"理论上如果有人这么调"不算,必须有真实调用方或合理下游用法。 +- **是缺陷,非设计**:不是已文档化的设计取舍,不是功能缺口,不是已知 footgun。 +- **严重**:达到 CRITICAL 或 HIGH。 + +级别定义: + +- **CRITICAL**:正常使用下可触发的 数据损坏 / 安全突破 / 死锁 / panic / 资源泄漏。 +- **HIGH**:真实(不必常见)路径下的 契约违反 / 并发竞态 / 生命周期泄漏 / 安全弱点,且无优雅降级。 + +低于 HIGH(MEDIUM/LOW)**默认不报**。若某条 MEDIUM 实际后果严重(如静默停摆),应在证伪后上调为 HIGH 再报,而不是以 MEDIUM 身份进清单。 + +## 2. 吹毛求疵禁区(明确不报) + +以下一律**不作为 finding**。可在交付末尾"观察区(非 bug)"单列,但**不计入、不阻塞、不计数**: + +1. **风格 / 格式 / 命名**:`fmt.Errorf` vs `errors.New`、变量命名、注释措辞、import 顺序。 +2. **"无害冗余" / 微优化**:无热路径实测证据的重复调用、可选的零拷贝、可省的临时变量。 +3. **功能缺口 / 未实现能力**:TLS 未加、交叉校验未加、某配置项未暴露--这些是 **roadmap**,不是 bug。归观察区。 +4. **已文档化的设计决策 / footgun**:代码注释或 CLAUDE.md 已声明"刻意如此"的,不重挂。 +5. **不可达路径的防御性补丁**:找不到真实 nil 调用方,就不报"缺 nil-check";找不到触发 panic 的输入,就不报"缺 recover"。防御性编码是好习惯,但不构成缺陷。 +6. **与红线有张力但场景"可接受"**:逐条对照开发纪律判定,若该场景被纪律明文豁免(如 watcher 的 for-range 关闭语义),不报。 +7. **维护性风险但当前无缺陷**:Clone 手动列举字段今天工作正确、某 switch 缺 default 今天不会命中--只有当"未来扩展会漏"已造成**当前**可证缺陷时才报,否则不报。 + +## 3. 证伪门(计入前强制) + +每条 finding 在写入交付前,reviewer 必须主动执行证伪: + +1. **写出触发路径**(具体到调用链 / 输入 / 并发时序)。 +2. **尝试证伪**:路径上有无 guard?调用方是否真实存在?是否已文档化?是否已是已知设计?是否其实有优雅降级? +3. **裁定**:证伪成功 → 丢弃或降级;证伪失败 → 计入。 + +只有**证伪失败**的 finding 进入交付清单。证伪成功的进入"证伪台账"(见 §5),透明留痕但不制造压迫。 + +## 4. 范围规则(防重新生成噪声) + +非收敛的头号成因是"对已加固模块反复全量重扫"--每个新 reviewer 都会重新生成一批 §2 禁区项。规则: + +- **默认扫 diff**:自上次绿灯复审以来的变更,不扫全模块。 +- **已加固模块不重扫**,除非本次改动了它。模块是否"已加固"以最近一份"达标"总评为准。 +- **全模块扫描**只在"首次复审"或"大重构后"做,且必须在报告头标注"首次 / 重构后重审"。 +- **换 reviewer 不算重扫理由**:同一模块换模型复审前,先确认自上次复审有无改动;无改动则拒绝重扫。 + +## 5. 输出格式 + +交付物只含三段,严格物理分隔: + +### 5.1 真 bug 清单(仅 CRITICAL/HIGH,证伪失败) +每条: +- 标题 +- `file:line`(源码唯一证据) +- 触发路径(可达性证明) +- 为何是缺陷(违反哪条契约 / 红线) +- 修复方向(一两句,不展开实现) + +### 5.2 观察区(非 bug,不计入,不阻塞) +功能缺口 / roadmap 建议 / 可选增强。明确标注"非 bug"。用户可忽略。 + +### 5.3 证伪台账(透明留痕) +列出本轮考虑过但丢弃的条目及丢弃理由(落入 §2 哪一条 / 证伪成功)。让用户看到"审过了但拒绝计入",避免"是不是漏审了"的疑虑。 + +**明确不输出**:风格 nits、"无害冗余"、防御性补丁建议、纯维护性担忧。 + +## 6. 成功度量(避免把不可达目标绑在自己身上) + +- ✅ **证伪后剩余的真实 CRITICAL/HIGH 数** -- 可归零,这是唯一硬指标。 +- ✅ **是否出现新 bug 类别** -- 已收敛的类别(多视图状态 / 公开生命周期 / 用户扩展点 / 间接层吞错)再出现同类的实例,属"扫尾",不属"新问题"。 +- ❌ **原始 finding 条数** -- 永不归零,不作度量。任何用"finding 条数下降"衡量进步的做法都是错的。 + +## 7. 给 reviewer 的硬约束(可直接喂入 prompt) + +> 你在审查 xlgo 框架代码。遵守 `scan_protocol.md`: +> 1. 只报 CRITICAL/HIGH,且每条必须给出可达触发路径,否则不报。 +> 2. 风格、冗余、功能缺口、已文档化设计、不可达防御、可接受场景、纯维护性风险--一律不报。 +> 3. 每条 finding 先尝试证伪;证伪成功的丢弃。 +> 4. 交付三段:真 bug 清单 / 观察区(非 bug)/ 证伪台账。 +> 5. 不重扫已加固模块,只扫本次改动 diff(除非报告头标注"首次/重构后")。 +> 6. 若你只能找到 MEDIUM/LOW,直接在证伪台账说明并结束,不要为凑数而上调。 diff --git a/sse/sse.go b/sse/sse.go new file mode 100644 index 0000000..9b868c5 --- /dev/null +++ b/sse/sse.go @@ -0,0 +1,241 @@ +// Package sse 提供 Server-Sent Events 流式响应支持，典型用于 AI 对话/LLM 流式输出。 +// +// 断连契约（C3 收尾，重要）： +// 框架侧的消费循环（Stream/StreamText/StreamChunks/StreamWithID）已监听 c.Request.Context()， +// 客户端断连即退出，消费端不泄漏 goroutine。但框架无法单方面停止上游生产者（LLM 流）—— +// 生产者（向 ch 发送数据的一方）必须自行监听同一 ctx 并在取消时停止生产，否则： +// - 上游 LLM 流在客户端已断开后仍持续运行（浪费算力/费用）； +// - 生产者向已无人消费的 ch 发送可能阻塞（无界 ch）或丢弃（有界 ch）。 +// +// 推荐写法：生产者 goroutine 内 select { case <-ctx.Done(): return; case ...: ch <- token }， +// 其中 ctx 取自请求的 c.Request.Context()（Stream 系列内部用的就是它）。 +package sse + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "net/http" + "strings" + + "github.com/gin-gonic/gin" +) + +var ErrInvalidEventName = errors.New("sse: event name must not contain CR or LF") + +// SSEWriter SSE 写入器 +type SSEWriter struct { + writer gin.ResponseWriter + flusher http.Flusher + ctx context.Context // 请求上下文，用于 Stream 系列监听断连（C3a） +} + +// NewSSEWriter 创建 SSE 写入器 +func NewSSEWriter(c *gin.Context) (*SSEWriter, error) { + // 设置 SSE 必要的响应头 + c.Header("Content-Type", "text/event-stream") + c.Header("Cache-Control", "no-cache") + c.Header("Connection", "keep-alive") + // 不手设 Transfer-Encoding: chunked——HTTP/1.1 下由 server 自动分帧， + // HTTP/2 下该头非法会致协议错误（C3c 修复）。 + + flusher, ok := c.Writer.(http.Flusher) + if !ok { + return nil, fmt.Errorf("响应写入器不支持 flushing") + } + + return &SSEWriter{ + writer: c.Writer, + flusher: flusher, + ctx: c.Request.Context(), + }, nil +} + +// WriteEvent 写入 SSE 事件 +// 格式: event: \ndata: \n\n +// +// 写错误向上传播（C3b 修复）：旧实现丢弃 fmt.Fprintf 错误且恒 return nil， +// 导致客户端断连后 Stream 守卫永不触发、消费循环不退出、上游 LLM 流持续运行。 +func (w *SSEWriter) WriteEvent(event, data string) error { + if strings.ContainsAny(event, "\r\n") { + return ErrInvalidEventName + } + if _, err := fmt.Fprintf(w.writer, "event: %s\n", event); err != nil { + return err + } + if err := w.writeDataLines(data); err != nil { + return err + } + w.flusher.Flush() + return nil +} + +// WriteMessage 写入消息（无事件类型） +// 格式: data: \n\n +func (w *SSEWriter) WriteMessage(data string) error { + if err := w.writeDataLines(data); err != nil { + return err + } + w.flusher.Flush() + return nil +} + +func (w *SSEWriter) writeDataLines(data string) error { + data = strings.ReplaceAll(data, "\r\n", "\n") + data = strings.ReplaceAll(data, "\r", "\n") + for _, line := range strings.Split(data, "\n") { + if _, err := fmt.Fprintf(w.writer, "data: %s\n", line); err != nil { + return err + } + } + _, err := fmt.Fprint(w.writer, "\n") + return err +} + +// WriteJSON 写入 JSON 数据 +func (w *SSEWriter) WriteJSON(event string, data any) error { + jsonData, err := json.Marshal(data) + if err != nil { + return err + } + return w.WriteEvent(event, string(jsonData)) +} + +// WriteError 写入错误事件 +func (w *SSEWriter) WriteError(err error) error { + return w.WriteJSON("error", gin.H{"error": err.Error()}) +} + +// WriteDone 写入完成事件 +func (w *SSEWriter) WriteDone() error { + return w.WriteEvent("done", "") +} + +// KeepAlive 发送保持连接的心跳。 +// +// 用 SSE 注释行（": ping\n\n"）而非 data 行（N6 修复）：data 行（含空 data）会触发 +// 客户端 onmessage 回调，注释行仅维持连接不产生消息事件，更符合心跳语义。 +func (w *SSEWriter) KeepAlive() error { + if _, err := fmt.Fprintf(w.writer, ": ping\n\n"); err != nil { + return err + } + w.flusher.Flush() + return nil +} + +// Stream 流式发送数据 +// +// 消费循环含 ctx.Done 分支（C3a 修复）：客户端断连（c.Request.Context 取消）时立即退出， +// 不再仅靠 channel 关闭或写错误退出。配合 WriteJSON 的写错误传播（C3b），断连即停。 +// ctx 为 nil 时回退到 context.Background()（防御外部未走 NewSSEWriter 构造的 nil panic）。 +func (w *SSEWriter) Stream(event string, ch <-chan any) error { + ctx := w.ctx + if ctx == nil { + ctx = context.Background() + } + for { + select { + case <-ctx.Done(): + return ctx.Err() + case data, ok := <-ch: + if !ok { + return w.WriteDone() + } + if err := w.WriteJSON(event, data); err != nil { + return err + } + } + } +} + +// SSE 中间件，设置必要的响应头 +func SSE() gin.HandlerFunc { + return func(c *gin.Context) { + c.Header("Content-Type", "text/event-stream") + c.Header("Cache-Control", "no-cache") + c.Header("Connection", "keep-alive") + c.Next() + } +} + +// StreamText 流式发送文本（适用于 AI 对话场景） +// +// 消费循环含 ctx.Done 分支（C3a 修复）：客户端断连即退出。 +// 生产者（ch 的发送方）也应监听 c.Request.Context()，以便消费端早退后停止上游 LLM 流； +// 若生产者忽略 ctx，本函数仍会因 ctx.Done 退出（消费端不泄漏），但上游生产者可能继续运行 +// 直到其自身完成或 channel 阻塞——调用方有责任在 ctx 取消时停止生产。 +func StreamText(c *gin.Context, ch <-chan string) error { + writer, err := NewSSEWriter(c) + if err != nil { + return err + } + + ctx := c.Request.Context() + for { + select { + case <-ctx.Done(): + return ctx.Err() + case text, ok := <-ch: + if !ok { + return writer.WriteDone() + } + if err := writer.WriteJSON("message", gin.H{"text": text}); err != nil { + return err + } + } + } +} + +// StreamChunks 流式发送文本块（带增量标记） +func StreamChunks(c *gin.Context, ch <-chan string) error { + writer, err := NewSSEWriter(c) + if err != nil { + return err + } + + ctx := c.Request.Context() + for { + select { + case <-ctx.Done(): + return ctx.Err() + case chunk, ok := <-ch: + if !ok { + return writer.WriteJSON("done", gin.H{"finished": true}) + } + if err := writer.WriteJSON("chunk", gin.H{"delta": chunk}); err != nil { + return err + } + } + } +} + +// StreamWithID 流式发送带消息 ID 的数据 +func StreamWithID(c *gin.Context, messageID string, ch <-chan string) error { + writer, err := NewSSEWriter(c) + if err != nil { + return err + } + + // 发送开始事件 + if err := writer.WriteJSON("start", gin.H{"id": messageID}); err != nil { + return err + } + + ctx := c.Request.Context() + // 发送内容块 + for { + select { + case <-ctx.Done(): + return ctx.Err() + case chunk, ok := <-ch: + if !ok { + // 发送完成事件 + return writer.WriteJSON("done", gin.H{"id": messageID, "finished": true}) + } + if err := writer.WriteJSON("chunk", gin.H{"id": messageID, "delta": chunk}); err != nil { + return err + } + } + } +} diff --git a/sse/sse_concurrency_test.go b/sse/sse_concurrency_test.go new file mode 100644 index 0000000..abd29de --- /dev/null +++ b/sse/sse_concurrency_test.go @@ -0,0 +1,77 @@ +package sse_test + +import ( + "io" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/EthanCodeCraft/xlgo-core/sse" + "github.com/gin-gonic/gin" +) + +// ===== C3a：断连即停（核心） ===== + +// 回归 C3a：断连即停由 internal test（sse_stream_internal_test.go，TestStreamStopsOnCtxCancelInternal） +// 权威覆盖——直接构造 SSEWriter + 可控 ctx，验证 Stream 在 ctx.Done 时返回 ctx.Err。 +// StreamText/StreamChunks/StreamWithID 用相同 select 模式（代码审查保证），外部网络断连测试 +// 因 httptest loopback 下 c.Request.Context() 取消时序不可靠而省略，internal test 为权威。 + +// ===== C3a：正常完成路径仍工作 ===== + +// 回归：ch 正常关闭时 StreamText 写 done 并返回 nil。 +func TestStreamTextNormalCompletion(t *testing.T) { + ch := make(chan string, 3) + ch <- "a" + ch <- "b" + close(ch) + + r := gin.New() + r.GET("/sse", func(c *gin.Context) { + err := sse.StreamText(c, ch) + if err != nil { + t.Errorf("StreamText normal completion err: %v", err) + } + }) + + srv := httptest.NewServer(r) + defer srv.Close() + + resp, err := http.Get(srv.URL + "/sse") + if err != nil { + t.Fatalf("connect: %v", err) + } + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + + if !strings.Contains(string(body), `"text":"a"`) || !strings.Contains(string(body), `"text":"b"`) { + t.Errorf("body missing chunks: %s", string(body)) + } + if !strings.Contains(string(body), "event: done") { + t.Errorf("body missing done event: %s", string(body)) + } +} + +// ===== C3c：不手设 Transfer-Encoding: chunked ===== + +// 回归 C3c：响应头不应含 Transfer-Encoding: chunked（HTTP/2 下非法，HTTP/1.1 冗余）。 +func TestNewSSEWriterNoChunkedHeader(t *testing.T) { + r := gin.New() + r.GET("/sse", func(c *gin.Context) { + _, _ = sse.NewSSEWriter(c) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/sse", nil) + r.ServeHTTP(w, req) + + if got := w.Header().Get("Transfer-Encoding"); got != "" { + t.Errorf("Transfer-Encoding = %q, want empty (C3c: should not hand-set chunked)", got) + } +} + +// ===== C3b：上游生产者契约文档化 ===== +// StreamText 在 ctx.Done 后返回 ctx.Err；生产者（往 ch 发送者）应监听同一 ctx， +// 在取消时停止上游 LLM 流。本框架无法单方面停止生产者，调用方契约见 StreamText 注释。 +// 该契约由 TestStreamTextStopsOnContextCancel 间接验证（StreamText 确实因 ctx.Done 退出）。 diff --git a/sse/sse_stream_internal_test.go b/sse/sse_stream_internal_test.go new file mode 100644 index 0000000..5cb6191 --- /dev/null +++ b/sse/sse_stream_internal_test.go @@ -0,0 +1,34 @@ +package sse + +import ( + "context" + "errors" + "testing" + "time" +) + +// 回归 C3a：Stream 在 ctx 取消时返回 ctx.Err，不再阻塞在 for-range ch。 +// 旧实现 for range ch 无 ctx.Done 分支，ctx 取消后仍阻塞等 ch → goroutine 泄漏 + 上游 LLM 流持续。 +func TestStreamStopsOnCtxCancelInternal(t *testing.T) { + ctx, cancel := context.WithCancel(context.Background()) + w := &SSEWriter{ctx: ctx} // writer/flusher 不用（ctx.Done 先触发，不写数据） + + ch := make(chan any) + // 不向 ch 发数据，也不关闭 ch——若 Stream 无 ctx.Done 分支将永久阻塞。 + done := make(chan error, 1) + go func() { + done <- w.Stream("msg", ch) + }() + + cancel() + select { + case err := <-done: + if !errors.Is(err, context.Canceled) { + t.Errorf("Stream err = %v, want context.Canceled", err) + } + case <-time.After(2 * time.Second): + t.Fatal("Stream did not return after ctx cancel (C3a: no ctx.Done branch)") + } +} + + diff --git a/sse/sse_test.go b/sse/sse_test.go new file mode 100644 index 0000000..313d02a --- /dev/null +++ b/sse/sse_test.go @@ -0,0 +1,187 @@ +package sse_test + +import ( + "errors" + "net/http/httptest" + "strings" + "testing" + + "github.com/EthanCodeCraft/xlgo-core/sse" + "github.com/gin-gonic/gin" +) + +func setupTestRouter() *gin.Engine { + gin.SetMode(gin.TestMode) + r := gin.New() + return r +} + +func TestNewSSEWriter(t *testing.T) { + r := setupTestRouter() + r.GET("/sse", func(c *gin.Context) { + writer, err := sse.NewSSEWriter(c) + if err != nil { + t.Errorf("NewSSEWriter error: %v", err) + return + } + + if writer == nil { + t.Error("NewSSEWriter should not return nil") + } + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/sse", nil) + r.ServeHTTP(w, req) +} + +func TestSSEWriterWriteEvent(t *testing.T) { + r := setupTestRouter() + r.GET("/sse", func(c *gin.Context) { + writer, _ := sse.NewSSEWriter(c) + writer.WriteEvent("message", "test data") + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/sse", nil) + r.ServeHTTP(w, req) + + body := w.Body.String() + if !strings.Contains(body, "event: message") { + t.Errorf("WriteEvent body should contain 'event: message', got %s", body) + } + if !strings.Contains(body, "data: test data") { + t.Errorf("WriteEvent body should contain 'data: test data', got %s", body) + } +} + +func TestSSEWriterWriteMessage(t *testing.T) { + r := setupTestRouter() + r.GET("/sse", func(c *gin.Context) { + writer, _ := sse.NewSSEWriter(c) + writer.WriteMessage("hello world") + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/sse", nil) + r.ServeHTTP(w, req) + + body := w.Body.String() + if !strings.Contains(body, "data: hello world") { + t.Errorf("WriteMessage body should contain data, got %s", body) + } +} + +func TestSSEWriterWriteJSON(t *testing.T) { + r := setupTestRouter() + r.GET("/sse", func(c *gin.Context) { + writer, _ := sse.NewSSEWriter(c) + writer.WriteJSON("message", gin.H{"text": "hello"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/sse", nil) + r.ServeHTTP(w, req) + + body := w.Body.String() + if !strings.Contains(body, "event: message") { + t.Error("WriteJSON should set event type") + } + if !strings.Contains(body, `"text":"hello"`) { + t.Error("WriteJSON should contain JSON data") + } +} + +func TestSSEMiddleware(t *testing.T) { + r := setupTestRouter() + r.Use(sse.SSE()) + r.GET("/test", func(c *gin.Context) { + c.JSON(200, gin.H{"status": "ok"}) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/test", nil) + r.ServeHTTP(w, req) + + // 验证 SSE 响应头 + contentType := w.Header().Get("Content-Type") + if contentType != "text/event-stream" { + t.Errorf("SSE Content-Type = %s, want text/event-stream", contentType) + } + + cacheControl := w.Header().Get("Cache-Control") + if cacheControl != "no-cache" { + t.Errorf("SSE Cache-Control = %s, want no-cache", cacheControl) + } +} + +func TestSSEHeaders(t *testing.T) { + r := setupTestRouter() + r.GET("/sse", func(c *gin.Context) { + writer, err := sse.NewSSEWriter(c) + if err != nil { + t.Errorf("NewSSEWriter error: %v", err) + return + } + writer.WriteMessage("test") + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/sse", nil) + r.ServeHTTP(w, req) + + // 验证必要响应头 + if w.Header().Get("Content-Type") != "text/event-stream" { + t.Error("Content-Type should be text/event-stream") + } + if w.Header().Get("Cache-Control") != "no-cache" { + t.Error("Cache-Control should be no-cache") + } + if w.Header().Get("Connection") != "keep-alive" { + t.Error("Connection should be keep-alive") + } +} + +func TestSSEWriterRejectsEventNewlineInjection(t *testing.T) { + r := setupTestRouter() + var writeErr error + r.GET("/sse", func(c *gin.Context) { + writer, _ := sse.NewSSEWriter(c) + writeErr = writer.WriteEvent("message\nevent: hacked", "safe") + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/sse", nil) + r.ServeHTTP(w, req) + + if !errors.Is(writeErr, sse.ErrInvalidEventName) { + t.Fatalf("WriteEvent newline err = %v, want ErrInvalidEventName", writeErr) + } + if strings.Contains(w.Body.String(), "event: hacked") { + t.Fatalf("response contains injected event: %q", w.Body.String()) + } +} + +func TestSSEWriterSplitsMultilineData(t *testing.T) { + r := setupTestRouter() + r.GET("/sse", func(c *gin.Context) { + writer, _ := sse.NewSSEWriter(c) + if err := writer.WriteMessage("first\nevent: injected\r\nsecond"); err != nil { + t.Errorf("WriteMessage: %v", err) + } + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/sse", nil) + r.ServeHTTP(w, req) + + body := w.Body.String() + if strings.Contains(body, "\nevent: injected") { + t.Fatalf("data newline escaped into event field: %q", body) + } + for _, want := range []string{"data: first", "data: event: injected", "data: second"} { + if !strings.Contains(body, want) { + t.Fatalf("body = %q, want %q", body, want) + } + } +} diff --git a/storage/storage.go b/storage/storage.go new file mode 100644 index 0000000..5794f79 --- /dev/null +++ b/storage/storage.go @@ -0,0 +1,869 @@ +package storage + +import ( + "bytes" + "crypto/rand" + "errors" + "fmt" + "io" + "mime/multipart" + "net/http" + "os" + "path" + "path/filepath" + "strings" + "sync" + "sync/atomic" + "time" + + "github.com/EthanCodeCraft/xlgo-core/config" + "github.com/EthanCodeCraft/xlgo-core/logger" + + "github.com/aliyun/aliyun-oss-go-sdk/oss" + "go.uber.org/zap" +) + +// Storage 存储接口 +type Storage interface { + Upload(file *multipart.FileHeader, subdir string) (string, error) + UploadFromBytes(data []byte, filename, subdir string) (string, error) + GetURL(path string) string + Delete(path string) error + Get(path string) ([]byte, error) + // Exists 检查文件是否存在。存在返回 (true, nil)；不存在返回 (false, nil)； + // 未初始化、路径非法/穿越、后端错误返回 (false, err)。 + Exists(path string) (bool, error) +} + +var ( + // ErrStorageNotInitialized storage 未初始化。 + ErrStorageNotInitialized = errors.New("storage not initialized") + // ErrPathTraversal 路径穿越被拒绝（C4a）。Delete/Get/Exists/Upload 的相对路径 + // 含 `..` 或绝对路径、逃逸根目录时返回。 + ErrPathTraversal = errors.New("path traversal detected") + // ErrInvalidPath 路径非法（空、含 NUL 等）。 + ErrInvalidPath = errors.New("invalid path") + // ErrInvalidFile 上传文件参数非法，例如 nil *multipart.FileHeader。 + ErrInvalidFile = errors.New("invalid file") + // ErrUploadTooLarge 上传声明大小或实际字节数超过 MaxSizeBytes（P0）。客户端声明的 file.Size + // 不可信，故除前置校验外，拷贝阶段也按实际字节封顶，防止声明小体积却流式发送大 body 撑爆磁盘/OSS。 + ErrUploadTooLarge = errors.New("upload exceeds max size") + // ErrReadTooLarge Get 读取内容超过 maxReadBytes 上限（C4c）。与 ErrUploadTooLarge 区分： + // 前者是读操作的超限，后者是上传操作的超限。 + ErrReadTooLarge = errors.New("read exceeds max size") +) + +const ( + // defaultMaxReadBytes Get 默认读取上限（100MB），防止全量读入内存 OOM（C4c）。 + defaultMaxReadBytes int64 = 100 * 1024 * 1024 + // mimeSniffPrefixLen http.DetectContentType 最多嗅探 512 字节。 + mimeSniffPrefixLen = 512 +) + +// resolveMaxRead 解析 Get 读取上限：n<0 不限，n==0 用默认，n>0 用 n。 +func resolveMaxRead(n int64) int64 { + if n < 0 { + return -1 + } + if n == 0 { + return defaultMaxReadBytes + } + return n +} + +// validateUploadSize 校验上传文件大小（C4b）。MaxSizeBytes<=0 表示不限。 +// +// 注意：此处的 size 来自客户端声明（multipart.FileHeader.Size），仅作前置快速拒绝， +// 不可信——攻击者可声明小体积却流式发送大 body。真正的落盘/上传封顶由 enforceUploadSize +// 在拷贝阶段按实际字节数二次把关（P0）。 +func validateUploadSize(p config.UploadPolicy, size int64) error { + if p.MaxSizeBytes > 0 && size > p.MaxSizeBytes { + return fmt.Errorf("文件大小 %d 超过上限 %d: %w", size, p.MaxSizeBytes, ErrUploadTooLarge) + } + return nil +} + +// enforceMaxReader 包装底层 reader，实际读取累计超过 max 字节即返回 ErrUploadTooLarge（P0）。 +// max<=0 表示不限。用于上传拷贝阶段的真实大小封顶，弥补客户端声明 Size 不可信。 +type enforceMaxReader struct { + src io.Reader + max int64 + count int64 +} + +func (r *enforceMaxReader) Read(p []byte) (int, error) { + if r.max > 0 && r.count >= r.max { + // 上限内的字节已全部读出：用独立探针读 1 字节判断源是否还有数据，有则超限。 + var probe [1]byte + if n, _ := r.src.Read(probe[:]); n > 0 { + return 0, ErrUploadTooLarge + } + // 源已到 EOF，实际大小恰好等于上限，放行结束。 + return 0, io.EOF + } + n, err := r.src.Read(p) + r.count += int64(n) + if r.max > 0 && r.count > r.max { + return 0, ErrUploadTooLarge + } + return n, err +} + +// enforceUploadSize 若策略配置了 MaxSizeBytes，则包装 src 在拷贝阶段实测封顶（P0）。 +// 未配置上限时原样返回，零开销。 +func enforceUploadSize(p config.UploadPolicy, src io.Reader) io.Reader { + if p.MaxSizeBytes <= 0 { + return src + } + return &enforceMaxReader{src: src, max: p.MaxSizeBytes} +} + +// validateUploadExt 校验上传文件扩展名（C4b）。AllowedExts 为空表示不限。 +func validateUploadExt(p config.UploadPolicy, filename string) error { + if len(p.AllowedExts) == 0 { + return nil + } + ext := strings.ToLower(filepath.Ext(filename)) + if !containsString(p.AllowedExts, ext) { + return fmt.Errorf("扩展名 %s 不在白名单: %w", ext, ErrInvalidPath) + } + return nil +} + +// sniffUploadMIME 嗅探 src 前 512 字节并按 AllowedMIMEs 校验（C4b）。 +// 返回的 reader 已拼回已读头部，后续可继续读到完整内容。 +// AllowedMIMEs 为空时直接返回原 src 不嗅探。 +func sniffUploadMIME(p config.UploadPolicy, src io.Reader) (io.Reader, error) { + if len(p.AllowedMIMEs) == 0 { + return src, nil + } + head := make([]byte, mimeSniffPrefixLen) + n, err := io.ReadFull(src, head) + if err != nil && err != io.EOF && err != io.ErrUnexpectedEOF { + return nil, fmt.Errorf("读取文件头失败: %w", err) + } + // http.DetectContentType 可能返回 "text/plain; charset=utf-8"， + // 与白名单 "text/plain" 比较时取主类型（分号前）。 + detected := strings.ToLower(strings.TrimSpace(strings.Split(http.DetectContentType(head[:n]), ";")[0])) + allowed := make([]string, len(p.AllowedMIMEs)) + for i, m := range p.AllowedMIMEs { + allowed[i] = strings.ToLower(strings.TrimSpace(strings.Split(m, ";")[0])) + } + if !containsString(allowed, detected) { + return nil, fmt.Errorf("文件类型 %s 不在白名单: %w", detected, ErrInvalidPath) + } + return io.MultiReader(bytes.NewReader(head[:n]), src), nil +} + +func containsString(list []string, v string) bool { + for _, s := range list { + if s == v { + return true + } + } + return false +} + +// uniqueFilename 生成带随机后缀的唯一文件名，避免同一纳秒内并发上传导致文件名冲突。 +// 格式: -<8字节随机hex>. +func uniqueFilename(now time.Time, ext string) string { + randBytes := make([]byte, 8) + // crypto/rand 失败极少见；退化为全零也能由纳秒时间戳保证基本唯一性 + _, _ = rand.Read(randBytes) + return fmt.Sprintf("%d-%x%s", now.UnixNano(), randBytes, ext) +} + +// sanitizeObjectKey 净化 OSS object key（C4a）。OSS key 为扁平字符串无 FS 穿越语义， +// 但拒绝含 `..`、绝对路径、NUL、空值等可疑输入，防止 key 注入与越权访问。 +// 同时将 Windows 反斜杠归一化为 OSS 规范的正斜杠，保证跨平台 key 一致。 +func sanitizeObjectKey(key string) (string, error) { + if key == "" || strings.ContainsRune(key, 0) { + return "", ErrInvalidPath + } + // 归一化 Windows 反斜杠为正斜杠（OSS key 规范分隔符），保证 Windows/Linux 部署 key 一致。 + key = strings.ReplaceAll(key, "\\", "/") + if strings.Contains(key, "..") { + return "", ErrPathTraversal + } + // 框架生成的 key 不以 / 开头；拒绝绝对路径形式避免歧义。 + if strings.HasPrefix(key, "/") { + return "", ErrPathTraversal + } + // 规范化多余分隔符，不改变合法 key 语义。 + return path.Clean(key), nil +} + +func publicURL(baseURL, key string) string { + cleanKey, err := sanitizeObjectKey(key) + if err != nil { + return "" + } + return strings.TrimRight(baseURL, "/") + "/" + cleanKey +} + +// LocalStorage 本地存储 +type LocalStorage struct { + rootAbs string // 绝对根路径（已 Clean），前缀锚定用（C4a） + baseURL string + policy config.UploadPolicy + maxReadBytes int64 +} + +// NewLocalStorage 创建本地存储实例 +// +// 安全约束：Path 指向的根目录应为框架独占目录，不与用户可控内容混用。 +// safeJoin 已防 `..` 路径穿越，但若根目录内已存在指向外部的符号链接， +// Get 会跟随 symlink 读到根外内容——需保证攻击者无法在根目录内创建 symlink。 +// cfg 为 nil、Path 无法解析或根目录本身是 symlink 时，实例 fail-closed： +// 后续文件操作返回 ErrStorageNotInitialized。 +func NewLocalStorage(cfg *config.LocalStorageConfig) *LocalStorage { + if cfg == nil { + return &LocalStorage{maxReadBytes: resolveMaxRead(0)} + } + // 用绝对路径作根锚定，避免相对路径 + `..` 组合绕过前缀校验（C4a）。 + var rootAbs string + abs, err := filepath.Abs(cfg.Path) + if err != nil { + // P1 #20：Abs 失败（如 os.Getwd 失败）不再回退相对 cfg.Path——相对根会使 safeJoin + // 前缀校验基于相对路径、削弱穿越防御。改为 fail-closed：置空 rootAbs， + // safeJoin 据此拒绝一切操作，并记录错误，避免"看似可用实则防御失效"的本地存储。 + logger.Error("storage: 解析存储根目录绝对路径失败，本地存储将不可用（fail-closed）", + zap.String("path", cfg.Path), zap.Error(err)) + rootAbs = "" + } else { + rootAbs = filepath.Clean(abs) + } + if rootAbs != "" { + if info, err := os.Lstat(rootAbs); err == nil && info.Mode()&os.ModeSymlink != 0 { + logger.Error("storage: local storage root must not be a symlink", zap.String("path", rootAbs)) + rootAbs = "" + } + } + return &LocalStorage{ + rootAbs: rootAbs, + baseURL: cfg.BaseURL, + policy: cfg.Upload, + maxReadBytes: resolveMaxRead(cfg.MaxReadBytes), + } +} + +// safeJoin 将根路径与相对片段拼接为绝对路径，并以前缀锚定拒绝穿越（C4a）。 +// 任何片段为绝对路径或含 NUL、最终路径逃逸 rootAbs 时返回错误。 +func (s *LocalStorage) safeJoin(parts ...string) (string, error) { + // P1 #20：rootAbs 为空表示构造时 Abs 失败，fail-closed 拒绝所有路径操作。 + if s.rootAbs == "" { + return "", ErrStorageNotInitialized + } + for _, p := range parts { + if filepath.IsAbs(p) { + return "", ErrPathTraversal + } + if strings.ContainsRune(p, 0) { + return "", ErrInvalidPath + } + } + joined := filepath.Join(append([]string{s.rootAbs}, parts...)...) + if joined == s.rootAbs || !strings.HasPrefix(joined, s.rootAbs+string(os.PathSeparator)) { + return "", ErrPathTraversal + } + return joined, nil +} + +// Upload 上传文件 +func (s *LocalStorage) Upload(file *multipart.FileHeader, subdir string) (ret string, err error) { + if file == nil { + return "", ErrInvalidFile + } + // 上传安全策略校验（大小 / 扩展名）；file.Size 由 multipart 解析时填，无需打开文件（C4b）。 + if err := validateUploadSize(s.policy, file.Size); err != nil { + return "", err + } + if err := validateUploadExt(s.policy, file.Filename); err != nil { + return "", err + } + + // 生成存储路径: /年/月/日/文件名 + now := time.Now() + datePath := fmt.Sprintf("%d/%02d/%02d", now.Year(), now.Month(), now.Day()) + relativePath := filepath.Join(subdir, datePath) + + // 确保目录存在，且未逃逸根目录（C4a：subdir 含 `..` 会被 safeJoin 拒绝） + fullPath, err := s.safeJoin(relativePath) + if err != nil { + logger.Warn("上传路径被拒绝", zap.String("subdir", subdir), zap.Error(err)) + return "", err + } + if err := os.MkdirAll(fullPath, 0750); err != nil { + logger.Error("创建目录失败", zap.Error(err), zap.String("path", fullPath)) + return "", fmt.Errorf("创建目录失败: %w", err) + } + + // 生成唯一文件名（服务端随机，可信） + ext := filepath.Ext(file.Filename) + filename := uniqueFilename(now, ext) + dst := filepath.Join(fullPath, filename) + + // 打开源文件 + src, err := file.Open() + if err != nil { + return "", fmt.Errorf("打开文件失败: %w", err) + } + defer src.Close() + + // MIME 嗅探（如配置 AllowedMIMEs），嗅探后拼回头部 + var srcReader io.Reader = src + srcReader, err = sniffUploadMIME(s.policy, srcReader) + if err != nil { + return "", err + } + + // 创建目标文件 + // #nosec G304 -- dst 由 safeJoin 净化后的 fullPath 与服务端随机生成的 filename 拼成，路径已防穿越 + dstFile, err := os.Create(dst) + if err != nil { + return "", fmt.Errorf("创建文件失败: %w", err) + } + defer func() { + if cerr := dstFile.Close(); cerr != nil { + err = errors.Join(err, cerr) + } + if err != nil { + ret = "" + _ = os.Remove(dst) + } + }() + + // 复制文件内容。按策略实测封顶（P0）：超限即报错并清理已落盘的部分文件。 + if _, err := io.Copy(dstFile, enforceUploadSize(s.policy, srcReader)); err != nil { + return "", fmt.Errorf("保存文件失败: %w", err) + } + + // 返回相对路径 + relativeFilePath := filepath.Join(relativePath, filename) + // 统一使用正斜杠 + relativeFilePath = strings.ReplaceAll(relativeFilePath, "\\", "/") + + logger.Info("文件上传成功", zap.String("path", relativeFilePath)) + return relativeFilePath, nil +} + +// UploadFromBytes 从字节数组上传文件 +func (s *LocalStorage) UploadFromBytes(data []byte, filename, subdir string) (ret string, err error) { + // 上传安全策略校验（C4b） + if err := validateUploadSize(s.policy, int64(len(data))); err != nil { + return "", err + } + if err := validateUploadExt(s.policy, filename); err != nil { + return "", err + } + + // 生成存储路径: /年/月/日/文件名 + now := time.Now() + datePath := fmt.Sprintf("%d/%02d/%02d", now.Year(), now.Month(), now.Day()) + relativePath := filepath.Join(subdir, datePath) + + // 确保目录存在，且未逃逸根目录（C4a） + fullPath, err := s.safeJoin(relativePath) + if err != nil { + logger.Warn("上传路径被拒绝", zap.String("subdir", subdir), zap.Error(err)) + return "", err + } + if err := os.MkdirAll(fullPath, 0750); err != nil { + logger.Error("创建目录失败", zap.Error(err), zap.String("path", fullPath)) + return "", fmt.Errorf("创建目录失败: %w", err) + } + + // 生成唯一文件名（如果未提供扩展名，添加 .bin） + ext := filepath.Ext(filename) + if ext == "" { + ext = ".bin" + } + fname := uniqueFilename(now, ext) + dst := filepath.Join(fullPath, fname) + + // MIME 嗅探（如配置 AllowedMIMEs） + var srcReader io.Reader = bytes.NewReader(data) + srcReader, err = sniffUploadMIME(s.policy, srcReader) + if err != nil { + return "", err + } + + // 创建目标文件 + // #nosec G304 -- dst 由 safeJoin 净化后的 fullPath 与服务端随机生成的 filename 拼成，路径已防穿越 + dstFile, err := os.Create(dst) + if err != nil { + return "", fmt.Errorf("创建文件失败: %w", err) + } + defer func() { + if cerr := dstFile.Close(); cerr != nil { + err = errors.Join(err, cerr) + } + if err != nil { + ret = "" + _ = os.Remove(dst) + } + }() + + // 写入文件内容 + if _, err := io.Copy(dstFile, srcReader); err != nil { + return "", fmt.Errorf("保存文件失败: %w", err) + } + + // 返回相对路径 + relativeFilePath := filepath.Join(relativePath, fname) + // 统一使用正斜杠 + relativeFilePath = strings.ReplaceAll(relativeFilePath, "\\", "/") + + logger.Info("文件上传成功", zap.String("path", relativeFilePath)) + return relativeFilePath, nil +} + +// GetURL 获取文件访问 URL +func (s *LocalStorage) GetURL(path string) string { + return publicURL(s.baseURL, path) +} + +// Delete 删除文件 +func (s *LocalStorage) Delete(p string) error { + fullPath, err := s.safeJoin(p) + if err != nil { + logger.Warn("删除路径被拒绝", zap.String("path", p), zap.Error(err)) + return err + } + if err := os.Remove(fullPath); err != nil { + logger.Error("删除文件失败", zap.Error(err), zap.String("path", fullPath)) + return fmt.Errorf("删除文件失败: %w", err) + } + logger.Info("文件删除成功", zap.String("path", p)) + return nil +} + +// Get 获取文件内容。读取受 maxReadBytes 封顶，防止全量读入内存 OOM（C4c）。 +func (s *LocalStorage) Get(p string) ([]byte, error) { + fullPath, err := s.safeJoin(p) + if err != nil { + logger.Warn("读取路径被拒绝", zap.String("path", p), zap.Error(err)) + return nil, err + } + // #nosec G304 -- fullPath 经 safeJoin 前缀锚定净化，已防穿越 + f, err := os.Open(fullPath) + if err != nil { + logger.Error("读取文件失败", zap.Error(err), zap.String("path", fullPath)) + return nil, fmt.Errorf("读取文件失败: %w", err) + } + defer f.Close() + + var reader io.Reader = f + if s.maxReadBytes > 0 { + // 多读 1 字节用于判断是否超限 + reader = io.LimitReader(f, s.maxReadBytes+1) + } + data, err := io.ReadAll(reader) + if err != nil { + return nil, fmt.Errorf("读取文件内容失败: %w", err) + } + if s.maxReadBytes > 0 && int64(len(data)) > s.maxReadBytes { + return nil, fmt.Errorf("文件超过最大读取限制 %d 字节: %w", s.maxReadBytes, ErrReadTooLarge) + } + return data, nil +} + +// Exists 检查文件是否存在。存在返回 (true, nil)；不存在返回 (false, nil)； +// 路径非法/穿越返回 (false, err)；其他 Stat 错误返回 (false, err)。 +func (s *LocalStorage) Exists(p string) (bool, error) { + fullPath, err := s.safeJoin(p) + if err != nil { + return false, err + } + if _, err := os.Stat(fullPath); err != nil { + if os.IsNotExist(err) { + return false, nil + } + return false, err + } + return true, nil +} + +// OSSStorage OSS 存储 +type OSSStorage struct { + client *oss.Client + bucket *oss.Bucket + endpoint string + bucketName string + baseURL string + policy config.UploadPolicy + maxReadBytes int64 +} + +// NewOSSStorage 创建 OSS 存储实例 +func NewOSSStorage(cfg *config.OSSStorageConfig) (*OSSStorage, error) { + if cfg == nil { + return nil, ErrStorageNotInitialized + } + client, err := oss.New(cfg.Endpoint, cfg.AccessKeyID, cfg.AccessKeySecret) + if err != nil { + return nil, fmt.Errorf("创建 OSS 客户端失败: %w", err) + } + + bucket, err := client.Bucket(cfg.Bucket) + if err != nil { + return nil, fmt.Errorf("获取 OSS Bucket 失败: %w", err) + } + + return &OSSStorage{ + client: client, + bucket: bucket, + endpoint: cfg.Endpoint, + bucketName: cfg.Bucket, + baseURL: cfg.BaseURL, + policy: cfg.Upload, + maxReadBytes: resolveMaxRead(cfg.MaxReadBytes), + }, nil +} + +// Upload 上传文件到 OSS +func (s *OSSStorage) Upload(file *multipart.FileHeader, subdir string) (string, error) { + if file == nil { + return "", ErrInvalidFile + } + // 上传安全策略校验（C4b） + if err := validateUploadSize(s.policy, file.Size); err != nil { + return "", err + } + if err := validateUploadExt(s.policy, file.Filename); err != nil { + return "", err + } + + // 生成存储路径: /年/月/日/文件名 + now := time.Now() + datePath := fmt.Sprintf("%d/%02d/%02d", now.Year(), now.Month(), now.Day()) + ext := filepath.Ext(file.Filename) + // OSS object key 规范用正斜杠；用 path.Join（POSIX）而非 filepath.Join， + // 避免 Windows 产反斜杠导致跨平台 key 不一致。 + rawKey := path.Join(filepath.ToSlash(subdir), datePath, uniqueFilename(now, ext)) + // 净化 object key，拒绝含 `..` 的 subdir（C4a key 注入） + objectKey, err := sanitizeObjectKey(rawKey) + if err != nil { + logger.Warn("OSS 上传 key 被拒绝", zap.String("subdir", subdir), zap.Error(err)) + return "", err + } + + // 打开源文件 + src, err := file.Open() + if err != nil { + return "", fmt.Errorf("打开文件失败: %w", err) + } + defer src.Close() + + // MIME 嗅探（如配置） + var srcReader io.Reader = src + srcReader, err = sniffUploadMIME(s.policy, srcReader) + if err != nil { + return "", err + } + + // 上传到 OSS。按策略实测封顶（P0）：超限时 PutObject 读到 ErrUploadTooLarge 而失败， + // 简单 PutObject 语义下对象不会被提交，无需额外清理。 + if err := s.bucket.PutObject(objectKey, enforceUploadSize(s.policy, srcReader)); err != nil { + logger.Error("OSS 上传失败", zap.Error(err), zap.String("key", objectKey)) + return "", fmt.Errorf("OSS 上传失败: %w", err) + } + + logger.Info("OSS 文件上传成功", zap.String("key", objectKey)) + return objectKey, nil +} + +// UploadFromBytes 从字节数组上传文件到 OSS +func (s *OSSStorage) UploadFromBytes(data []byte, filename, subdir string) (string, error) { + // 上传安全策略校验（C4b） + if err := validateUploadSize(s.policy, int64(len(data))); err != nil { + return "", err + } + if err := validateUploadExt(s.policy, filename); err != nil { + return "", err + } + + now := time.Now() + datePath := fmt.Sprintf("%d/%02d/%02d", now.Year(), now.Month(), now.Day()) + ext := filepath.Ext(filename) + if ext == "" { + ext = ".bin" + } + // OSS object key 规范用正斜杠；用 path.Join（POSIX）而非 filepath.Join， + // 避免 Windows 产反斜杠导致跨平台 key 不一致。 + rawKey := path.Join(filepath.ToSlash(subdir), datePath, uniqueFilename(now, ext)) + objectKey, err := sanitizeObjectKey(rawKey) + if err != nil { + logger.Warn("OSS 上传 key 被拒绝", zap.String("subdir", subdir), zap.Error(err)) + return "", err + } + + // MIME 嗅探（如配置） + var srcReader io.Reader = bytes.NewReader(data) + srcReader, err = sniffUploadMIME(s.policy, srcReader) + if err != nil { + return "", err + } + + // 上传到 OSS + if err := s.bucket.PutObject(objectKey, srcReader); err != nil { + logger.Error("OSS 上传失败", zap.Error(err), zap.String("key", objectKey)) + return "", fmt.Errorf("OSS 上传失败: %w", err) + } + + logger.Info("OSS 文件上传成功", zap.String("key", objectKey)) + return objectKey, nil +} + +// GetURL 获取文件访问 URL +func (s *OSSStorage) GetURL(path string) string { + cleanKey, err := sanitizeObjectKey(path) + if err != nil { + return "" + } + if s.baseURL != "" { + return strings.TrimRight(s.baseURL, "/") + "/" + cleanKey + } + return fmt.Sprintf("https://%s.%s/%s", s.bucketName, s.endpoint, cleanKey) +} + +// GetSignedURL 获取带签名的临时访问 URL（用于私有文件） +func (s *OSSStorage) GetSignedURL(path string, expire time.Duration) (string, error) { + key, err := sanitizeObjectKey(path) + if err != nil { + return "", err + } + return s.bucket.SignURL(key, oss.HTTPGet, int64(expire.Seconds())) +} + +// Delete 删除 OSS 文件 +func (s *OSSStorage) Delete(p string) error { + key, err := sanitizeObjectKey(p) + if err != nil { + return err + } + if err := s.bucket.DeleteObject(key); err != nil { + logger.Error("OSS 删除失败", zap.Error(err), zap.String("key", key)) + return fmt.Errorf("OSS 删除失败: %w", err) + } + logger.Info("OSS 文件删除成功", zap.String("key", key)) + return nil +} + +// Get 获取 OSS 文件内容。读取受 maxReadBytes 封顶，防止 OOM（C4c）。 +func (s *OSSStorage) Get(p string) ([]byte, error) { + key, err := sanitizeObjectKey(p) + if err != nil { + return nil, err + } + body, err := s.bucket.GetObject(key) + if err != nil { + logger.Error("OSS 读取失败", zap.Error(err), zap.String("key", key)) + return nil, fmt.Errorf("OSS 读取失败: %w", err) + } + defer body.Close() + + var reader io.Reader = body + if s.maxReadBytes > 0 { + reader = io.LimitReader(body, s.maxReadBytes+1) + } + data, err := io.ReadAll(reader) + if err != nil { + return nil, fmt.Errorf("读取 OSS 文件内容失败: %w", err) + } + if s.maxReadBytes > 0 && int64(len(data)) > s.maxReadBytes { + return nil, fmt.Errorf("文件超过最大读取限制 %d 字节: %w", s.maxReadBytes, ErrReadTooLarge) + } + return data, nil +} + +// Exists 检查 OSS 文件是否存在。存在返回 (true, nil)；object 不存在返回 (false, nil)； +// key 非法/穿越返回 (false, err)；鉴权/网络/服务端错误返回 (false, err)。 +func (s *OSSStorage) Exists(p string) (bool, error) { + key, err := sanitizeObjectKey(p) + if err != nil { + return false, err + } + if _, err := s.bucket.GetObjectMeta(key); err != nil { + // OSS object 不存在（404 / NoSuchKey）不是错误，返回 (false, nil)。 + var se *oss.ServiceError + if errors.As(err, &se) && (se.StatusCode == http.StatusNotFound || se.Code == "NoSuchKey") { + return false, nil + } + return false, err + } + return true, nil +} + +// StorageManager 存储管理器（#10）。照 database.Manager 模式： +// 实例化 + DefaultStorage 全局默认 + 包级 facade 代理，支持多实例与测试注入。 +type StorageManager struct { + mu sync.Mutex + cfg *config.StorageConfig + current Storage +} + +// DefaultStorage 默认存储管理器，包级 facade 代理到它。 +// +// 主线A 修复：改用 atomic.Pointer 保护读写，消除原裸指针置换（SetDefaultStorageManager） +// 与 facade 无锁读之间的数据竞争，与 config.defaultManager / database.DefaultRedis 对齐。 +// 类型由 *StorageManager 变更为 atomic.Pointer[StorageManager]（breaking：下游若直接 +// 调用 DefaultStorage.Init 等方法需改用 Init 等 facade，或 DefaultStorage.Load().Init）。 +var DefaultStorage atomic.Pointer[StorageManager] + +func init() { + DefaultStorage.Store(NewStorageManager()) +} + +// NewStorageManager 创建存储管理器实例。 +func NewStorageManager() *StorageManager { return &StorageManager{} } + +// SetDefaultStorageManager 提升指定 StorageManager 为全局默认。并发安全（atomic.Store）。 +func SetDefaultStorageManager(m *StorageManager) { + if m != nil { + DefaultStorage.Store(m) + } +} + +// SwapDefaultStorageManager 将指定 StorageManager 置为全局默认，并返回被替换的旧 Manager。 +// 旧 Manager 不会被关闭，供 App 初始化这类需要失败回滚的生命周期流程暂存（照 +// SwapDefaultRedisManager / database.SwapDefaultManager 模式）。nil 被忽略，返回当前默认。 +func SwapDefaultStorageManager(m *StorageManager) *StorageManager { + if m == nil { + return DefaultStorage.Load() + } + return DefaultStorage.Swap(m) +} + +// Init 初始化存储 +func (m *StorageManager) Init(cfg *config.StorageConfig) error { + if cfg == nil { + return ErrStorageNotInitialized + } + m.mu.Lock() + defer m.mu.Unlock() + + var s Storage + switch cfg.Driver { + case "local": + s = NewLocalStorage(&cfg.Local) + logger.Info("使用本地存储", zap.String("path", cfg.Local.Path)) + case "oss": + ossStorage, err := NewOSSStorage(&cfg.OSS) + if err != nil { + return err + } + s = ossStorage + logger.Info("使用 OSS 存储", zap.String("bucket", cfg.OSS.Bucket)) + default: + return fmt.Errorf("不支持的存储驱动: %s", cfg.Driver) + } + + m.cfg = cfg + m.current = s + return nil +} + +// Get 返回当前存储实例。 +func (m *StorageManager) Get() Storage { + m.mu.Lock() + defer m.mu.Unlock() + return m.current +} + +// Set 设置存储实例（用于注入 mock 或自定义实现）。 +func (m *StorageManager) Set(s Storage) { + m.mu.Lock() + defer m.mu.Unlock() + m.current = s +} + +// Close 释放存储资源，闭合 StorageManager 的 Init/Close 生命周期（与 database/redis/logger +// manager 对齐，供 App.closeResources 统一调用）。当前 LocalStorage 无可关资源；OSSStorage 的 +// *oss.Client 未暴露 Close（aliyun-oss-go-sdk），故当前为 no-op。保留此方法为未来驱动 +// （S3/MinIO/自研等带连接池的驱动）预留收口点：实现了 io.Closer 的 Storage 实现会被自动调用， +// 框架骨架无需改动。幂等（未初始化或驱动非 io.Closer 时 no-op）。 +func (m *StorageManager) Close() error { + m.mu.Lock() + current := m.current + m.mu.Unlock() + if current == nil { + return nil + } + if c, ok := current.(io.Closer); ok { + return c.Close() + } + return nil +} + +// --- 包级 facade（代理到 DefaultStorage，兼容存量） --- + +// Init 初始化存储 +func Init(cfg *config.StorageConfig) error { + return DefaultStorage.Load().Init(cfg) +} + +// GetStorage 获取全局存储实例 +func GetStorage() Storage { + return DefaultStorage.Load().Get() +} + +// SetStorage 设置全局存储实例 +func SetStorage(s Storage) { + DefaultStorage.Load().Set(s) +} + +// Upload 上传文件 +func Upload(file *multipart.FileHeader, subdir string) (string, error) { + s := GetStorage() + if s == nil { + return "", ErrStorageNotInitialized + } + return s.Upload(file, subdir) +} + +// UploadFromBytes 从字节数组上传文件 +func UploadFromBytes(data []byte, filename, subdir string) (string, error) { + s := GetStorage() + if s == nil { + return "", ErrStorageNotInitialized + } + return s.UploadFromBytes(data, filename, subdir) +} + +// GetURL 获取文件访问 URL +func GetURL(path string) string { + s := GetStorage() + if s == nil { + return "" + } + return s.GetURL(path) +} + +// Delete 删除文件 +func Delete(path string) error { + s := GetStorage() + if s == nil { + return ErrStorageNotInitialized + } + return s.Delete(path) +} + +// Get 获取文件内容 +func Get(path string) ([]byte, error) { + s := GetStorage() + if s == nil { + return nil, ErrStorageNotInitialized + } + return s.Get(path) +} + +// Exists 检查文件是否存在。未初始化返回 (false, ErrStorageNotInitialized)； +// 其余语义同 Storage.Exists。 +func Exists(path string) (bool, error) { + s := GetStorage() + if s == nil { + return false, ErrStorageNotInitialized + } + return s.Exists(path) +} diff --git a/storage/storage_close_internal_test.go b/storage/storage_close_internal_test.go new file mode 100644 index 0000000..f3c39b4 --- /dev/null +++ b/storage/storage_close_internal_test.go @@ -0,0 +1,71 @@ +package storage + +import ( + "mime/multipart" + "testing" + + "github.com/EthanCodeCraft/xlgo-core/config" +) + +// closeableMock 实现 Storage + io.Closer，验证 StorageManager.Close 调用驱动的 Close。 +type closeableMock struct { + closed bool +} + +func (closeableMock) Upload(*multipart.FileHeader, string) (string, error) { return "", nil } +func (closeableMock) UploadFromBytes([]byte, string, string) (string, error) { + return "", nil +} +func (closeableMock) GetURL(string) string { return "" } +func (closeableMock) Delete(string) error { return nil } +func (closeableMock) Get(string) ([]byte, error) { return nil, nil } +func (closeableMock) Exists(string) (bool, error) { return false, nil } +func (c *closeableMock) Close() error { c.closed = true; return nil } + +// TestStorageManagerCloseNil：未初始化时 Close 为 no-op，不 panic。 +func TestStorageManagerCloseNil(t *testing.T) { + m := NewStorageManager() + if err := m.Close(); err != nil { + t.Fatalf("Close on uninitialized manager should be no-op, got %v", err) + } +} + +// TestStorageManagerCloseLocalStorageNoop：LocalStorage 未实现 io.Closer，Close 为 no-op。 +func TestStorageManagerCloseLocalStorageNoop(t *testing.T) { + m := NewStorageManager() + if err := m.Init(&config.StorageConfig{ + Driver: "local", + Local: config.LocalStorageConfig{Path: t.TempDir()}, + }); err != nil { + t.Fatalf("Init: %v", err) + } + if err := m.Close(); err != nil { + t.Fatalf("Close on LocalStorage-backed manager should be no-op, got %v", err) + } +} + +// TestStorageManagerCloseInvokesCloser：驱动实现 io.Closer 时，StorageManager.Close 调用它。 +func TestStorageManagerCloseInvokesCloser(t *testing.T) { + m := NewStorageManager() + mock := &closeableMock{} + m.Set(mock) + if err := m.Close(); err != nil { + t.Fatalf("Close: %v", err) + } + if !mock.closed { + t.Fatal("StorageManager.Close did not invoke io.Closer on driver (未来带连接池的驱动应经此收口)") + } +} + +// TestStorageManagerCloseIdempotent：重复 Close 不 panic。 +func TestStorageManagerCloseIdempotent(t *testing.T) { + m := NewStorageManager() + mock := &closeableMock{} + m.Set(mock) + if err := m.Close(); err != nil { + t.Fatalf("first Close: %v", err) + } + if err := m.Close(); err != nil { + t.Fatalf("second Close should be idempotent, got %v", err) + } +} diff --git a/storage/storage_path_internal_test.go b/storage/storage_path_internal_test.go new file mode 100644 index 0000000..c4656b4 --- /dev/null +++ b/storage/storage_path_internal_test.go @@ -0,0 +1,92 @@ +package storage + +import ( + "errors" + "strings" + "testing" +) + +// 回归 C4a：OSS object key 净化。拒绝空、NUL、含 `..`、绝对路径，防 key 注入与越权访问。 +func TestSanitizeObjectKey(t *testing.T) { + cases := []struct { + name string + in string + wantErr bool + }{ + {"empty", "", true}, + {"dotdot only", "..", true}, + {"dotdot segment", "a/../b", true}, + {"dotdot prefix", "../etc/passwd", true}, + {"absolute", "/abs/path", true}, + {"nul byte", "a\x00b", true}, + {"normal", "images/2026/01/01/x.jpg", false}, + {"normal no ext", "docs/report", false}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + got, err := sanitizeObjectKey(c.in) + if c.wantErr { + if err == nil { + t.Errorf("sanitizeObjectKey(%q) = %q, want error", c.in, got) + } + return + } + if err != nil { + t.Errorf("sanitizeObjectKey(%q) unexpected err: %v", c.in, err) + } + }) + } +} + +// 回归 HIGH（OSS key 跨平台）：Windows 反斜杠必须归一化为正斜杠， +// 否则 Windows 开发 / Linux 生产部署 OSS key 不一致、DB 迁移后取不到文件。 +func TestSanitizeObjectKeyNormalizesBackslash(t *testing.T) { + got, err := sanitizeObjectKey("avatars\\2026\\06\\28\\x.jpg") + if err != nil { + t.Fatalf("unexpected err: %v", err) + } + if strings.Contains(got, "\\") { + t.Errorf("sanitizeObjectKey left backslash: %q", got) + } + if want := "avatars/2026/06/28/x.jpg"; got != want { + t.Errorf("sanitizeObjectKey backslash normalize = %q, want %q", got, want) + } +} + +// 回归 C4c：resolveMaxRead 语义。n<0 不限，n==0 默认，n>0 用 n。 +func TestResolveMaxRead(t *testing.T) { + if got := resolveMaxRead(-1); got != -1 { + t.Errorf("resolveMaxRead(-1) = %d, want -1 (unlimited)", got) + } + if got := resolveMaxRead(0); got != defaultMaxReadBytes { + t.Errorf("resolveMaxRead(0) = %d, want default %d", got, defaultMaxReadBytes) + } + if got := resolveMaxRead(2048); got != 2048 { + t.Errorf("resolveMaxRead(2048) = %d, want 2048", got) + } +} + +func TestNewOSSStorageNilConfig(t *testing.T) { + if _, err := NewOSSStorage(nil); !errors.Is(err, ErrStorageNotInitialized) { + t.Fatalf("NewOSSStorage(nil) err = %v, want ErrStorageNotInitialized", err) + } +} + +func TestOSSStorageGetURLSanitizesPath(t *testing.T) { + s := &OSSStorage{ + baseURL: "https://cdn.example.com/", + bucketName: "bucket", + endpoint: "oss.example.com", + } + if got := s.GetURL("docs//a.txt"); got != "https://cdn.example.com/docs/a.txt" { + t.Fatalf("GetURL clean path = %q", got) + } + if got := s.GetURL("../secret.txt"); got != "" { + t.Fatalf("GetURL traversal = %q, want empty", got) + } + + s.baseURL = "" + if got := s.GetURL("docs/a.txt"); got != "https://bucket.oss.example.com/docs/a.txt" { + t.Fatalf("GetURL endpoint fallback = %q", got) + } +} diff --git a/storage/storage_security_test.go b/storage/storage_security_test.go new file mode 100644 index 0000000..3aa515b --- /dev/null +++ b/storage/storage_security_test.go @@ -0,0 +1,344 @@ +package storage_test + +import ( + "bytes" + "errors" + "mime/multipart" + "os" + "path/filepath" + "testing" + + "github.com/EthanCodeCraft/xlgo-core/config" + "github.com/EthanCodeCraft/xlgo-core/storage" +) + +// makeFileHeader 用 multipart 真实构造一个 *multipart.FileHeader，content 为文件内容。 +func makeFileHeader(t *testing.T, field, filename, contentType string, content []byte) *multipart.FileHeader { + t.Helper() + body := &bytes.Buffer{} + w := multipart.NewWriter(body) + h := make(map[string][]string) + h["Content-Disposition"] = []string{`form-data; name="` + field + `"; filename="` + filename + `"`} + h["Content-Type"] = []string{contentType} + part, err := w.CreatePart(h) + if err != nil { + t.Fatalf("CreatePart: %v", err) + } + if _, err := part.Write(content); err != nil { + t.Fatalf("part.Write: %v", err) + } + if err := w.Close(); err != nil { + t.Fatalf("writer.Close: %v", err) + } + r := multipart.NewReader(body, w.Boundary()) + form, err := r.ReadForm(int64(len(content) + 1024)) + if err != nil { + t.Fatalf("ReadForm: %v", err) + } + defer form.RemoveAll() + if len(form.File[field]) == 0 { + t.Fatalf("no file field %q in form", field) + } + return form.File[field][0] +} + +func newLocalStorageWithPolicy(t *testing.T, policy config.UploadPolicy, maxRead int64) *storage.LocalStorage { + t.Helper() + dir := t.TempDir() + return storage.NewLocalStorage(&config.LocalStorageConfig{ + Path: dir, + BaseURL: "http://localhost/uploads", + Upload: policy, + MaxReadBytes: maxRead, + }) +} + +// ===== C4a：路径穿越 ===== + +// 回归 C4a：Delete/Get/Exists 的 `..` 路径必须被拒绝，不能触碰根目录之外的文件。 +func TestLocalStoragePathTraversal(t *testing.T) { + dir := t.TempDir() + s := storage.NewLocalStorage(&config.LocalStorageConfig{Path: dir, BaseURL: "http://localhost/uploads"}) + + // 在 TempDir 之外放一个蜜罐文件，确保穿越不会删/读它。 + sibling := filepath.Join(filepath.Dir(dir), "xlgo_c4_canary_"+filepath.Base(dir)+".txt") + if err := os.WriteFile(sibling, []byte("canary"), 0644); err != nil { + t.Fatalf("write canary: %v", err) + } + defer os.Remove(sibling) + + // 用 `..` 指向 canary（dir 的父目录下）。 + escapeRel := "../" + filepath.Base(sibling) + + // Delete 必须拒绝 + if err := s.Delete(escapeRel); !errors.Is(err, storage.ErrPathTraversal) { + t.Errorf("Delete(%q) err = %v, want ErrPathTraversal", escapeRel, err) + } + // canary 必须仍然存在（未被删除） + if _, err := os.Stat(sibling); err != nil { + t.Errorf("canary file was deleted by traversal Delete: %v", err) + } + + // Get 必须拒绝 + if _, err := s.Get(escapeRel); !errors.Is(err, storage.ErrPathTraversal) { + t.Errorf("Get(%q) err = %v, want ErrPathTraversal", escapeRel, err) + } + + // Exists 必须返回 (false, ErrPathTraversal)（而非穿越探测到 canary） + if ok, err := s.Exists(escapeRel); ok || !errors.Is(err, storage.ErrPathTraversal) { + t.Errorf("Exists(%q) = (%v, %v), want (false, ErrPathTraversal)", escapeRel, ok, err) + } + + // 绝对路径也必须拒绝 + abs := sibling + if err := s.Delete(abs); !errors.Is(err, storage.ErrPathTraversal) { + t.Errorf("Delete(absolute %q) err = %v, want ErrPathTraversal", abs, err) + } +} + +// 回归 C4a：正常相对路径不受误伤（合法用法回归）。 +func TestLocalStorageNormalPathStillWorks(t *testing.T) { + dir := t.TempDir() + s := storage.NewLocalStorage(&config.LocalStorageConfig{Path: dir, BaseURL: "http://localhost/uploads"}) + + // 直接在 root 下放一个文件，用正常相对路径访问。 + target := filepath.Join(dir, "sub", "ok.txt") + if err := os.MkdirAll(filepath.Dir(target), 0755); err != nil { + t.Fatalf("mkdir: %v", err) + } + if err := os.WriteFile(target, []byte("hello"), 0644); err != nil { + t.Fatalf("write: %v", err) + } + + rel := filepath.ToSlash(filepath.Join("sub", "ok.txt")) + if ok, err := s.Exists(rel); err != nil || !ok { + t.Errorf("Exists(normal) = (%v, %v), want (true, nil)", ok, err) + } + data, err := s.Get(rel) + if err != nil { + t.Errorf("Get(normal) err = %v", err) + } + if string(data) != "hello" { + t.Errorf("Get(normal) = %q, want 'hello'", string(data)) + } + if err := s.Delete(rel); err != nil { + t.Errorf("Delete(normal) err = %v", err) + } +} + +// 回归 C4a：Upload 的 subdir 含 `..` 必须拒绝，且不在根目录外创建文件。 +func TestLocalStorageUploadTraversalSubdir(t *testing.T) { + dir := t.TempDir() + s := storage.NewLocalStorage(&config.LocalStorageConfig{Path: dir, BaseURL: "http://localhost/uploads"}) + + fh := makeFileHeader(t, "file", "ok.txt", "text/plain", []byte("hi")) + if _, err := s.Upload(fh, "../evil"); !errors.Is(err, storage.ErrPathTraversal) { + t.Errorf("Upload subdir ../ err = %v, want ErrPathTraversal", err) + } + // 根目录之外不应出现 evil 目录 + evilDir := filepath.Join(filepath.Dir(dir), "evil") + if _, err := os.Stat(evilDir); err == nil { + t.Errorf("traversal Upload created dir outside root: %s", evilDir) + } + + // 绝对路径 subdir 也拒绝 + if _, err := s.Upload(fh, dir); !errors.Is(err, storage.ErrPathTraversal) { + t.Errorf("Upload absolute subdir err = %v, want ErrPathTraversal", err) + } +} + +// 回归 C4a：UploadFromBytes 的 subdir 含 `..` 必须拒绝。 +func TestLocalStorageUploadFromBytesTraversalSubdir(t *testing.T) { + dir := t.TempDir() + s := storage.NewLocalStorage(&config.LocalStorageConfig{Path: dir, BaseURL: "http://localhost/uploads"}) + + if _, err := s.UploadFromBytes([]byte("hi"), "ok.txt", "../../etc"); !errors.Is(err, storage.ErrPathTraversal) { + t.Errorf("UploadFromBytes subdir ../../etc err = %v, want ErrPathTraversal", err) + } +} + +// ===== C4c：Get 读封顶 ===== + +// 回归 C4c：MaxReadBytes 封顶，超限文件 Get 返回错误，不再 OOM。 +func TestLocalStorageGetReadLimit(t *testing.T) { + s := newLocalStorageWithPolicy(t, config.UploadPolicy{}, 10) // 限制 10 字节 + + // MaxReadBytes=10 的实例不限上传；上传 20 字节后 Get 应被封顶拒绝。 + content := []byte("0123456789ABCDEFGHIJ") // 20 字节 + fh := makeFileHeader(t, "file", "big.txt", "text/plain", content) + rel, err := s.Upload(fh, "docs") + if err != nil { + t.Fatalf("Upload big file: %v", err) + } + if _, err := s.Get(rel); !errors.Is(err, storage.ErrReadTooLarge) { + t.Errorf("Get over-limit err = %v, want ErrReadTooLarge", err) + } + + // 小文件应正常读取。 + small := newLocalStorageWithPolicy(t, config.UploadPolicy{}, 100) + fh2 := makeFileHeader(t, "file", "small.txt", "text/plain", []byte("small")) + rel2, err := small.Upload(fh2, "docs") + if err != nil { + t.Fatalf("Upload small: %v", err) + } + data, err := small.Get(rel2) + if err != nil { + t.Errorf("Get small err = %v", err) + } + if string(data) != "small" { + t.Errorf("Get small = %q, want 'small'", string(data)) + } +} + +// ===== C4b：上传策略 ===== + +// 回归 C4b：MaxSizeBytes 超限拒绝。 +func TestLocalStorageUploadSizeLimit(t *testing.T) { + s := newLocalStorageWithPolicy(t, config.UploadPolicy{MaxSizeBytes: 5}, 0) + fh := makeFileHeader(t, "file", "big.txt", "text/plain", []byte("0123456789")) // 10 字节 + if _, err := s.Upload(fh, "docs"); !errors.Is(err, storage.ErrUploadTooLarge) { + t.Errorf("Upload over size err = %v, want ErrUploadTooLarge", err) + } +} + +// 回归 C4b：AllowedExts 白名单——不允许的扩展名拒绝，允许的通过。 +func TestLocalStorageUploadExtWhitelist(t *testing.T) { + s := newLocalStorageWithPolicy(t, config.UploadPolicy{AllowedExts: []string{".jpg"}}, 0) + + // evil.php 拒绝 + fh := makeFileHeader(t, "file", "evil.php", "text/plain", []byte(" mockStorageMaxBytes { + return "", ErrMockStorageTooLarge + } + + data, err := file.Open() + if err != nil { + return "", err + } + b, err := io.ReadAll(io.LimitReader(data, mockStorageMaxBytes+1)) + if cerr := data.Close(); cerr != nil { + err = errors.Join(err, cerr) + } + if err != nil { + return "", err + } + if int64(len(b)) > mockStorageMaxBytes { + return "", ErrMockStorageTooLarge + } + + path := "/mock/" + subdir + "/" + file.Filename + m.mu.Lock() + defer m.mu.Unlock() + m.files[path] = b + return path, nil +} + +// UploadFromBytes 模拟字节上传，签名对齐 storage.UploadFromBytes。 +func (m *MockStorage) UploadFromBytes(data []byte, filename, subdir string) (string, error) { + if int64(len(data)) > mockStorageMaxBytes { + return "", ErrMockStorageTooLarge + } + path := "/mock/" + subdir + "/" + filename + m.mu.Lock() + defer m.mu.Unlock() + m.files[path] = append([]byte(nil), data...) + return path, nil +} + +// GetURL 获取 mock URL。 +func (m *MockStorage) GetURL(path string) string { + return "http://mock.test" + path +} + +// AssertEqual 断言相等。 +func AssertEqual(t *testing.T, expected, actual any) { + t.Helper() + if expected != actual { + t.Errorf("不相等: 期望 %v, 实际 %v", expected, actual) + } +} + +// AssertNotNil 断言非空。 +func AssertNotNil(t *testing.T, value any) { + t.Helper() + if value == nil { + t.Error("期望非空，实际为空") + } +} + +// AssertNil 断言为空。 +func AssertNil(t *testing.T, value any) { + t.Helper() + if value != nil { + t.Errorf("期望为空，实际为: %v", value) + } +} + +// AssertTrue 断言为 true。 +func AssertTrue(t *testing.T, value bool) { + t.Helper() + if !value { + t.Error("期望为 true，实际为 false") + } +} + +// AssertFalse 断言为 false。 +func AssertFalse(t *testing.T, value bool) { + t.Helper() + if value { + t.Error("期望为 false，实际为 true") + } +} + +// AssertError 断言有错误。 +func AssertError(t *testing.T, err error) { + t.Helper() + if err == nil { + t.Error("期望有错误，实际无错误") + } +} + +// AssertNoError 断言无错误。 +func AssertNoError(t *testing.T, err error) { + t.Helper() + if err != nil { + t.Errorf("期望无错误，实际错误: %v", err) + } +} diff --git a/test/test_m16_test.go b/test/test_m16_test.go new file mode 100644 index 0000000..44216b7 --- /dev/null +++ b/test/test_m16_test.go @@ -0,0 +1,89 @@ +package test + +import ( + "bytes" + "errors" + "net/http" + "net/http/httptest" + "sync" + "testing" + + "github.com/gin-gonic/gin" +) + +func TestRequestExecuteReturnsResponse(t *testing.T) { + router := SetupRouter() + router.POST("/users", func(c *gin.Context) { + c.JSON(http.StatusOK, gin.H{"data": gin.H{"name": "张三"}}) + }) + + resp := POST(router, "/users").WithJSON(gin.H{"name": "张三"}).Execute() + resp.AssertOK(t) + resp.AssertJSONContains(t, "data.name", "张三") +} + +func TestRequestExecuteRecorderKeepsRawRecorder(t *testing.T) { + router := SetupRouter() + router.GET("/ping", func(c *gin.Context) { + c.String(http.StatusCreated, "pong") + }) + + recorder := GET(router, "/ping").ExecuteRecorder() + if _, ok := any(recorder).(*httptest.ResponseRecorder); !ok { + t.Fatalf("ExecuteRecorder 应返回原始 ResponseRecorder") + } + if recorder.Code != http.StatusCreated { + t.Fatalf("状态码错误: 期望 %d, 实际 %d", http.StatusCreated, recorder.Code) + } +} + +func TestMockCacheCopiesBytes(t *testing.T) { + cache := NewMockCache() + input := []byte("abc") + cache.Set("k", input) + input[0] = 'x' + + got, ok := cache.Get("k") + if !ok { + t.Fatalf("缓存不存在") + } + if string(got) != "abc" { + t.Fatalf("缓存被外部输入污染: %q", got) + } + + got[0] = 'y' + gotAgain, _ := cache.Get("k") + if string(gotAgain) != "abc" { + t.Fatalf("缓存被返回值污染: %q", gotAgain) + } +} + +func TestMocksConcurrentAccess(t *testing.T) { + db := NewMockDB() + cache := NewMockCache() + + var wg sync.WaitGroup + for i := 0; i < 64; i++ { + wg.Add(1) + go func(i int) { + defer wg.Done() + db.Set(i, i) + _, _ = db.Get(i) + cache.Set("k", []byte{byte(i)}) + _, _ = cache.Get("k") + }(i) + } + wg.Wait() +} + +func TestMockStorageRejectsNilAndLargeInput(t *testing.T) { + storage := NewMockStorage() + if _, err := storage.Upload(nil, "avatars"); err == nil { + t.Fatalf("nil 文件应返回错误") + } + + large := bytes.Repeat([]byte{'x'}, int(mockStorageMaxBytes)+1) + if _, err := storage.UploadFromBytes(large, "large.bin", "files"); !errors.Is(err, ErrMockStorageTooLarge) { + t.Fatalf("超大文件错误不符合预期: %v", err) + } +} diff --git a/trace/trace.go b/trace/trace.go new file mode 100644 index 0000000..d8ae72a --- /dev/null +++ b/trace/trace.go @@ -0,0 +1,418 @@ +package trace + +import ( + "context" + "fmt" + "math" + "net/http" + "os" + "sync/atomic" + "time" + + "github.com/gin-gonic/gin" + "go.opentelemetry.io/contrib/propagators/b3" + "go.opentelemetry.io/otel" + "go.opentelemetry.io/otel/attribute" + "go.opentelemetry.io/otel/codes" + "go.opentelemetry.io/otel/exporters/otlp/otlptrace" + "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc" + "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp" + "go.opentelemetry.io/otel/exporters/stdout/stdouttrace" + "go.opentelemetry.io/otel/propagation" + "go.opentelemetry.io/otel/sdk/resource" + sdktrace "go.opentelemetry.io/otel/sdk/trace" + semconv "go.opentelemetry.io/otel/semconv/v1.24.0" + "go.opentelemetry.io/otel/trace" + "go.opentelemetry.io/otel/trace/noop" +) + +// Config 链路追踪配置 +type Config struct { + // ServiceName 服务名称 + ServiceName string + // ServiceVersion 服务版本 + ServiceVersion string + // Environment 运行环境 + Environment string + // ExporterType 导出器类型: "otlp-http", "otlp-grpc", "stdout" + ExporterType string + // Endpoint OTLP 导出器地址 + Endpoint string + // Insecure 是否使用明文（无 TLS）连接 collector。 + // 默认 false（TLS）；对 localhost:4318 等明文 collector 需显式置 true（C13c）。 + Insecure bool + // SampleRatio 采样比例 (0.0-1.0) + SampleRatio float64 + // Enabled 是否启用 + Enabled bool + // Propagator 传播器类型: "w3c", "b3", "jaeger" + Propagator string +} + +// DefaultConfig 默认配置 +var DefaultConfig = Config{ + ServiceName: "xlgo-service", + ServiceVersion: "1.0.0", // 应用自身版本（非框架版本 xlgo.Version）；建议业务侧覆盖为实际应用版本 + Environment: "development", + ExporterType: "otlp-http", + Endpoint: "localhost:4318", + SampleRatio: 1.0, + Enabled: false, + Propagator: "w3c", +} + +// tracerProviderPtr 全局 TracerProvider（atomic，C13a）。 +// Init 之前/Close 之后均为 Noop/NeverSample，保证任何时刻 Load 非 nil，请求期不 panic。 +var tracerProviderPtr atomic.Pointer[sdktrace.TracerProvider] + +// tracerPtr 全局 Tracer（atomic，C13a）。Init 之前为 Noop，调用安全。 +var tracerPtr atomic.Pointer[trace.Tracer] + +const defaultOperationTimeout = 5 * time.Second + +var operationTimeoutNanos atomic.Int64 + +func init() { + // 初始化为 Noop，保证包级函数在任何时刻（未 Init / 已 Close）Load 均非 nil（C13a）。 + // P1 #19：用 noop.NewTracerProvider()（新 OTel API），替代已弃用的 trace.NewNoopTracerProvider()。 + noopProvider := noop.NewTracerProvider() + noopTracer := noopProvider.Tracer("xlgo") + tp := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.NeverSample())) + tracerProviderPtr.Store(tp) + tracerPtr.Store(&noopTracer) + operationTimeoutNanos.Store(int64(defaultOperationTimeout)) +} + +// getTracer 返回全局 Tracer 的 atomic 快照（永不 nil）。 +func getTracer() trace.Tracer { + return *tracerPtr.Load() +} + +// TracerProvider 全局 TracerProvider（导出供高级用法；返回当前快照）。 +func TracerProvider() *sdktrace.TracerProvider { + return tracerProviderPtr.Load() +} + +// Init 初始化链路追踪 +func Init(cfg Config) error { + if math.IsNaN(cfg.SampleRatio) || cfg.SampleRatio < 0 || cfg.SampleRatio > 1 { + return fmt.Errorf("trace SampleRatio must be between 0.0 and 1.0: %v", cfg.SampleRatio) + } + + if !cfg.Enabled { + // 设置 Noop Tracer（P1 #19：noop 包替代弃用 API） + noopProvider := noop.NewTracerProvider() + otel.SetTracerProvider(noopProvider) + noopTracer := noopProvider.Tracer(cfg.ServiceName) + tracerPtr.Store(&noopTracer) + // M-64 修复：Swap 出旧 provider（可能持有 exporter）并 Shutdown， + // 避免禁用 trace 后旧 exporter 后台 goroutine/连接持续占用。 + fallback := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.NeverSample())) + if old := tracerProviderPtr.Swap(fallback); old != nil { + _ = shutdownProviderWithTimeout(context.Background(), old) + } + return nil + } + + // 创建资源 + // 注意：不传 semconv.SchemaURL 与 resource.Default() 混用—— + // resource.Default() 在不同 OTel 版本可能使用与 semconv v1.24.0 不同的 schema URL， + // resource.Merge 对冲突的 SchemaURL 直接报错。这里用空 schema URL 的属性集合并， + // 避免版本漂移导致的初始化失败。 + res, err := resource.Merge( + resource.Default(), + resource.NewWithAttributes( + "", + semconv.ServiceName(cfg.ServiceName), + semconv.ServiceVersion(cfg.ServiceVersion), + attribute.String("environment", cfg.Environment), + ), + ) + if err != nil { + return err + } + + // 创建导出器 + exporter, err := createExporter(cfg) + if err != nil { + return err + } + + // 创建 TracerProvider + newProvider := sdktrace.NewTracerProvider( + sdktrace.WithBatcher(exporter), + sdktrace.WithResource(res), + sdktrace.WithSampler(sdktrace.TraceIDRatioBased(cfg.SampleRatio)), + ) + + // 设置传播器（非法类型返错，C13e 不再静默回落） + prop, err := createPropagator(cfg.Propagator) + if err != nil { + // M-65 修复：传播器非法时回滚已创建的 provider。此时尚未 otel.SetTracerProvider， + // otel 全局仍指向旧 provider，无需恢复——仅 Shutdown 新 provider 避免泄漏。 + _ = shutdownProviderWithTimeout(context.Background(), newProvider) + return err + } + + // 全部成功后再切换全局状态（M-65：避免失败后 otel 指向已 Shutdown 的 provider）。 + otel.SetTracerProvider(newProvider) + otel.SetTextMapPropagator(prop) + + // 原子替换：先建新 provider，成功后再 Store，并关闭旧 provider（若持有 exporter）。 + oldProvider := tracerProviderPtr.Swap(newProvider) + tracer := newProvider.Tracer(cfg.ServiceName) + tracerPtr.Store(&tracer) + if oldProvider != nil { + _ = shutdownProviderWithTimeout(context.Background(), oldProvider) + } + + return nil +} + +func operationTimeout() time.Duration { + timeout := time.Duration(operationTimeoutNanos.Load()) + if timeout <= 0 { + return defaultOperationTimeout + } + return timeout +} + +func contextWithOperationTimeout(parent context.Context) (context.Context, context.CancelFunc) { + if parent == nil { + parent = context.Background() + } + return context.WithTimeout(parent, operationTimeout()) +} + +func shutdownProviderWithTimeout(parent context.Context, provider *sdktrace.TracerProvider) error { + if provider == nil { + return nil + } + ctx, cancel := contextWithOperationTimeout(parent) + defer cancel() + return provider.Shutdown(ctx) +} + +// createExporter 创建导出器 +func createExporter(cfg Config) (sdktrace.SpanExporter, error) { + switch cfg.ExporterType { + case "otlp-http": + opts := []otlptracehttp.Option{otlptracehttp.WithEndpoint(cfg.Endpoint)} + if cfg.Insecure { + opts = append(opts, otlptracehttp.WithInsecure()) // C13c + } + client := otlptracehttp.NewClient(opts...) + ctx, cancel := contextWithOperationTimeout(context.Background()) + defer cancel() + return otlptrace.New(ctx, client) + case "otlp-grpc": + opts := []otlptracegrpc.Option{otlptracegrpc.WithEndpoint(cfg.Endpoint)} + if cfg.Insecure { + opts = append(opts, otlptracegrpc.WithInsecure()) // C13c + } + client := otlptracegrpc.NewClient(opts...) + ctx, cancel := contextWithOperationTimeout(context.Background()) + defer cancel() + return otlptrace.New(ctx, client) + case "stdout": + return stdouttrace.New( + stdouttrace.WithWriter(os.Stdout), + stdouttrace.WithPrettyPrint(), + ) + default: + // C13b：未知导出器返错，不再返回 nil 喂 WithBatcher(nil)。 + return nil, fmt.Errorf("不支持的导出器类型: %s", cfg.ExporterType) + } +} + +// createPropagator 创建传播器（C13e：实现 b3，jaeger 映射 W3C，未知返错）。 +func createPropagator(propagatorType string) (propagation.TextMapPropagator, error) { + switch propagatorType { + case "w3c", "": + return propagation.NewCompositeTextMapPropagator( + propagation.TraceContext{}, + propagation.Baggage{}, + ), nil + case "b3": + // 同时支持多头与单头注入/抽取，兼容旧 B3 客户端。 + return b3.New(b3.WithInjectEncoding(b3.B3MultipleHeader | b3.B3SingleHeader)), nil + case "jaeger": + // 现代 Jaeger agent 透传 W3C TraceContext；纯 Jaeger thrift 头协议需下游用 b3。 + // 不引入不稳定的 jaegerremix 模块，jaeger 视为 W3C 别名。 + return propagation.TraceContext{}, nil + default: + return nil, fmt.Errorf("不支持的传播器类型: %s", propagatorType) + } +} + +// Close 关闭链路追踪。 +// +// H-14 修复：去掉 sync.Once。原实现 Close→Init→Close 第二次因 once 已消费而 no-op， +// 新 provider 的 exporter 后台 goroutine/连接泄漏。改为每次 Swap 出当前 provider 并 +// Shutdown，Store 回兜底 NeverSample provider（C13a：Close 后再用已关闭 provider）。 +// 幂等：重复 Close 时 Swap 得到的是无 exporter 的兜底 provider，Shutdown 无害。 +// 并发安全：Swap 原子返回唯一指针，不会 double-Shutdown 同一 provider。 +func Close(ctx context.Context) error { + fallback := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.NeverSample())) + old := tracerProviderPtr.Swap(fallback) + noopTracer := noop.NewTracerProvider().Tracer("xlgo") // P1 #19：noop 包替代弃用 API + tracerPtr.Store(&noopTracer) + if old != nil { + return shutdownProviderWithTimeout(ctx, old) + } + return nil +} + +// Middleware Gin 中间件 +func Middleware(serviceName string) gin.HandlerFunc { + return func(c *gin.Context) { + // 从请求中提取 TraceContext + ctx := otel.GetTextMapPropagator().Extract(c.Request.Context(), propagation.HeaderCarrier(c.Request.Header)) + + // 创建 Span。P1 #19：span 名以路由模板（FullPath）为准以保持低基数。 + // 原实现 `Method+" "+FullPath()` 后判 `== ""` 永不成立（"GET " 非空）， + // 未匹配路由的回退分支形同虚设、且用原始 URL.Path（含 ID）会导致 span 名高基数爆炸。 + // 现显式判断 FullPath 为空（未匹配路由），用固定低基数名。 + route := c.FullPath() + var spanName string + if route == "" { + spanName = c.Request.Method + " [unmatched]" + } else { + spanName = c.Request.Method + " " + route + } + + attrs := []attribute.KeyValue{ + semconv.HTTPRequestMethodKey.String(c.Request.Method), + semconv.URLPathKey.String(c.Request.URL.Path), + semconv.HTTPRouteKey.String(route), + attribute.String("http.user_agent", c.Request.UserAgent()), + attribute.String("http.host", c.Request.Host), + } + if serviceName != "" { + attrs = append(attrs, attribute.String("service.name", serviceName)) + } + + ctx, span := getTracer().Start(ctx, spanName, + trace.WithSpanKind(trace.SpanKindServer), + trace.WithAttributes(attrs...), + ) + // P1 #19：defer 保证下游 handler panic（在上游 recovery 捕获前）时 span 也被结束， + // 不泄漏未结束的 span。 + defer span.End() + + // C13d：更新 c.Request，使下游 c.Request.Context() 含 span； + // 同时保留 c.Set("otel_ctx", ctx) 兼容既有 GetContext 用法。 + c.Request = c.Request.WithContext(ctx) + c.Set("otel_ctx", ctx) + + // 将 TraceID 添加到响应头 + if span.SpanContext().HasTraceID() { + c.Header("X-Trace-ID", span.SpanContext().TraceID().String()) + } + + // 执行请求 + c.Next() + + // 设置 Span 状态 + status := c.Writer.Status() + span.SetAttributes(semconv.HTTPResponseStatusCodeKey.Int(status)) + + if status >= 400 { + span.SetStatus(codes.Error, http.StatusText(status)) + } + // 成功路径不显式设 codes.Ok（M18）：OTel 规范中 Span 状态默认 UNSET， + // 仅在错误时设 Error；显式设 Ok 会掩盖下游子 Span 的真实错误状态。 + } +} + +// GetContext 从 Gin Context 获取 OpenTelemetry Context +// +// C13：裸断言改 comma-ok，防 "otel_ctx" 被外部置为非 context 值时 panic。 +func GetContext(c *gin.Context) context.Context { + if v, exists := c.Get("otel_ctx"); exists { + if ctx, ok := v.(context.Context); ok { + return ctx + } + } + return c.Request.Context() +} + +// GetTraceID 获取当前 TraceID +func GetTraceID(c *gin.Context) string { + ctx := GetContext(c) + span := trace.SpanFromContext(ctx) + if span.SpanContext().HasTraceID() { + return span.SpanContext().TraceID().String() + } + return "" +} + +// StartSpan 创建子 Span +func StartSpan(c *gin.Context, name string, attrs ...attribute.KeyValue) (context.Context, trace.Span) { + ctx := GetContext(c) + return getTracer().Start(ctx, name, + trace.WithSpanKind(trace.SpanKindInternal), + trace.WithAttributes(attrs...), + ) +} + +// StartSpanFromContext 从 Context 创建 Span +func StartSpanFromContext(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, trace.Span) { + return getTracer().Start(ctx, name, + trace.WithSpanKind(trace.SpanKindInternal), + trace.WithAttributes(attrs...), + ) +} + +// RecordError 记录错误 +func RecordError(c *gin.Context, err error) { + if c == nil || err == nil { + return + } + ctx := GetContext(c) + span := trace.SpanFromContext(ctx) + span.RecordError(err) + span.SetStatus(codes.Error, err.Error()) +} + +// RecordErrorToSpan 记录错误到指定 Span +func RecordErrorToSpan(span trace.Span, err error) { + if span == nil || err == nil { + return + } + span.RecordError(err) + span.SetStatus(codes.Error, err.Error()) +} + +// AddAttributes 添加属性到当前 Span +func AddAttributes(c *gin.Context, attrs ...attribute.KeyValue) { + ctx := GetContext(c) + span := trace.SpanFromContext(ctx) + span.SetAttributes(attrs...) +} + +// GetTracer 获取全局 Tracer +func GetTracer() trace.Tracer { + return getTracer() +} + +// SetAttribute 设置单个属性 +func SetAttribute(c *gin.Context, key string, value any) { + ctx := GetContext(c) + span := trace.SpanFromContext(ctx) + + switch v := value.(type) { + case string: + span.SetAttributes(attribute.String(key, v)) + case int: + span.SetAttributes(attribute.Int(key, v)) + case int64: + span.SetAttributes(attribute.Int64(key, v)) + case bool: + span.SetAttributes(attribute.Bool(key, v)) + case float64: + span.SetAttributes(attribute.Float64(key, v)) + default: + span.SetAttributes(attribute.String(key, fmt.Sprintf("%v", v))) + } +} diff --git a/trace/trace_test.go b/trace/trace_test.go new file mode 100644 index 0000000..f644c15 --- /dev/null +++ b/trace/trace_test.go @@ -0,0 +1,653 @@ +package trace + +import ( + "context" + "errors" + "math" + "net/http" + "net/http/httptest" + "os" + "sync" + "testing" + "time" + + "github.com/gin-gonic/gin" + "go.opentelemetry.io/otel" + "go.opentelemetry.io/otel/propagation" + sdktrace "go.opentelemetry.io/otel/sdk/trace" + oteltrace "go.opentelemetry.io/otel/trace" +) + +// initTracerSnapshot 捕获包 init() 后、任何测试改动前的全局 tracer 快照。 +// 用于锁定 init() 的 Noop 兜底不变式（C13a），避免 resetGlobal/Init/Close +// 在其他测试中重置全局后掩盖 init() 路径的回归。 +var initTracerSnapshot oteltrace.Tracer + +func TestMain(m *testing.M) { + // init() 已运行；此处立即快照 getTracer()（永不 nil 的 Noop 兜底）。 + initTracerSnapshot = getTracer() + code := m.Run() + os.Exit(code) +} + +// resetGlobal 恢复 trace 包级全局到 Noop 兜底状态，避免测试间污染。 +func resetGlobal(t *testing.T) { + t.Helper() + noopProvider := oteltrace.NewNoopTracerProvider() + noopTracer := noopProvider.Tracer("xlgo") + tp := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.NeverSample())) + tracerProviderPtr.Store(tp) + tracerPtr.Store(&noopTracer) + otel.SetTracerProvider(noopProvider) + otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator( + propagation.TraceContext{}, propagation.Baggage{})) +} + +func setOperationTimeoutForTest(t *testing.T, timeout time.Duration) { + t.Helper() + old := operationTimeoutNanos.Load() + operationTimeoutNanos.Store(int64(timeout)) + t.Cleanup(func() { + operationTimeoutNanos.Store(old) + }) +} + +type blockingExporter struct{} + +func (blockingExporter) ExportSpans(context.Context, []sdktrace.ReadOnlySpan) error { + return nil +} + +func (blockingExporter) Shutdown(ctx context.Context) error { + <-ctx.Done() + return ctx.Err() +} + +type recordingExporter struct { + mu sync.Mutex + spans []sdktrace.ReadOnlySpan +} + +func (e *recordingExporter) ExportSpans(_ context.Context, spans []sdktrace.ReadOnlySpan) error { + e.mu.Lock() + defer e.mu.Unlock() + e.spans = append(e.spans, spans...) + return nil +} + +func (e *recordingExporter) Shutdown(context.Context) error { + return nil +} + +func (e *recordingExporter) Spans() []sdktrace.ReadOnlySpan { + e.mu.Lock() + defer e.mu.Unlock() + spans := make([]sdktrace.ReadOnlySpan, len(e.spans)) + copy(spans, e.spans) + return spans +} + +func requireNoPanic(t *testing.T, fn func()) { + t.Helper() + defer func() { + if r := recover(); r != nil { + t.Fatalf("unexpected panic: %v", r) + } + }() + fn() +} + +// TestC13aInitNoopInvariant 锁定 init() 的 Noop 兜底不变式： +// 包加载后（任何 Init/Close/resetGlobal 之前）getTracer() 必须非 nil。 +// +// 变异 init() 去掉 Noop Store 后，initTracerSnapshot（在 TestMain 即 init 后捕获） +// 将为 nil → 此测试红。resetGlobal 等后续改动不影响此快照。 +func TestC13aInitNoopInvariant(t *testing.T) { + if initTracerSnapshot == nil { + t.Fatal("init() did not store a Noop tracer: getTracer() was nil at package load (C13a)") + } +} + +// ============================================================ +// C13a：未 Init 即用 → nil tracer panic +// ============================================================ + +// TestC13aNoInitNoPanic 验证未 Init 时包级函数不 panic（Noop 兜底）。 +// +// 修复前：包级 tracer 为 nil，Middleware/StartSpanFromContext/GetTracer 裸用 → panic。 +// 修复后：init() Store Noop，getTracer() 永不 nil。 +func TestC13aNoInitNoPanic(t *testing.T) { + // 强制重置到"未 Init"的 Noop 兜底状态。 + resetGlobal(t) + + // GetTracer 非 nil。 + if tr := GetTracer(); tr == nil { + t.Fatal("GetTracer() nil before Init (C13a)") + } + + // StartSpanFromContext 不 panic。 + ctx, span := StartSpanFromContext(context.Background(), "test-span") + defer span.End() + if span == nil { + t.Fatal("StartSpanFromContext returned nil span") + } + _ = ctx + + // Middleware 不 panic：走一次请求。 + gin.SetMode(gin.TestMode) + r := gin.New() + r.Use(Middleware("test-svc")) + r.GET("/p", func(c *gin.Context) { + // 下游用 c.Request.Context() 取 span（C13d 闭环）。 + s := oteltrace.SpanFromContext(c.Request.Context()) + c.String(http.StatusOK, s.SpanContext().TraceID().String()) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/p", nil) + r.ServeHTTP(w, req) + + // Noop tracer 的 TraceID 为空（Noop 不记录），但绝不应 panic。 + if w.Code != http.StatusOK { + t.Fatalf("status = %d, want 200 (C13a should not panic)", w.Code) + } +} + +// TestC13aInitDisabledNoop 验证 Init(Enabled:false) 后 Noop 安全。 +func TestC13aInitDisabledNoop(t *testing.T) { + t.Cleanup(func() { _ = Close(context.Background()); resetGlobal(t) }) + if err := Init(Config{Enabled: false, ServiceName: "svc"}); err != nil { + t.Fatalf("Init: %v", err) + } + if GetTracer() == nil { + t.Fatal("GetTracer nil after Init(Enabled:false)") + } + // Noop tracer Start 不 panic。 + _, span := StartSpanFromContext(context.Background(), "x") + span.End() +} + +// TestC13aCloseThenUseNoPanic 验证 Close 后再用不 panic（Store 回 Noop 兜底）。 +func TestC13aCloseThenUseNoPanic(t *testing.T) { + resetGlobal(t) + t.Cleanup(func() { resetGlobal(t) }) + + // 即便未真正 Init 出带 exporter 的 provider，Close 也应安全并把全局重置为兜底。 + if err := Close(context.Background()); err != nil { + t.Fatalf("Close: %v", err) + } + // Close 后包级函数仍安全。 + if GetTracer() == nil { + t.Fatal("GetTracer nil after Close") + } + _, span := StartSpanFromContext(context.Background(), "after-close") + span.End() +} + +// ============================================================ +// C13b：未知导出器返 nil + stdout 未实现 +// ============================================================ + +// TestC13bStdoutExporterWorks 验证 stdout 导出器可创建（C13b 实现）。 +func TestC13bStdoutExporterWorks(t *testing.T) { + // 用 stdouttrace 但 Init 会向 os.Stdout 输出，故直接测 createExporter。 + cfg := Config{ExporterType: "stdout"} + exp, err := createExporter(cfg) + if err != nil { + t.Fatalf("createExporter(stdout): %v (C13b stdout unimplemented)", err) + } + if exp == nil { + t.Fatal("createExporter(stdout) returned nil exporter (C13b)") + } + _ = exp.Shutdown(context.Background()) +} + +// TestC13bUnknownExporterReturnsError 验证未知导出器返错（修复前返 nil,nil）。 +func TestC13bUnknownExporterReturnsError(t *testing.T) { + cfg := Config{ExporterType: "xyz-unknown"} + exp, err := createExporter(cfg) + if err == nil { + t.Error("createExporter(unknown) should return error (C13b), got nil") + } + if exp != nil { + t.Errorf("createExporter(unknown) should return nil exporter, got %T", exp) + } +} + +// TestC13bInitUnknownExporterFails 验证 Init 未知导出器返错（不喂 nil 给 WithBatcher）。 +func TestC13bInitUnknownExporterFails(t *testing.T) { + t.Cleanup(func() { resetGlobal(t) }) + err := Init(Config{Enabled: true, ExporterType: "xyz-unknown", Propagator: "w3c"}) + if err == nil { + t.Error("Init with unknown exporter should fail (C13b)") + } +} + +// ============================================================ +// C13c：OTLP 默认 HTTPS 无 WithInsecure +// ============================================================ + +// TestC13cInsecureExporterCreates 验证 Insecure:true 时 otlp-http 导出器可创建（无 TLS 握手）。 +// createExporter 仅构造 client，不连接；Insecure 注入不报错即验证 option 路径生效。 +func TestC13cInsecureExporterCreates(t *testing.T) { + cfg := Config{ExporterType: "otlp-http", Endpoint: "localhost:4318", Insecure: true} + exp, err := createExporter(cfg) + if err != nil { + t.Fatalf("createExporter(otlp-http, Insecure): %v (C13c)", err) + } + _ = exp.Shutdown(context.Background()) +} + +// TestC13cOtlpGrpcInsecureCreates 验证 otlp-grpc Insecure 路径。 +func TestC13cOtlpGrpcInsecureCreates(t *testing.T) { + cfg := Config{ExporterType: "otlp-grpc", Endpoint: "localhost:4317", Insecure: true} + exp, err := createExporter(cfg) + if err != nil { + t.Fatalf("createExporter(otlp-grpc, Insecure): %v (C13c)", err) + } + _ = exp.Shutdown(context.Background()) +} + +// ============================================================ +// C13d：Middleware 不更新 c.Request +// ============================================================ + +// TestC13dRequestContextContainsSpan 验证 Middleware 更新 c.Request， +// 下游 c.Request.Context() 含 span（TraceID 非空且与 X-Trace-ID 一致）。 +// +// 修复前：仅 c.Set("otel_ctx", ctx)，下游 c.Request.Context() 无 span。 +func TestC13dRequestContextContainsSpan(t *testing.T) { + resetGlobal(t) + t.Cleanup(func() { _ = Close(context.Background()); resetGlobal(t) }) + + // 用 stdout 导出器 + 全采样，使 span 真实生成（非 Noop）。 + if err := Init(Config{ + Enabled: true, + ServiceName: "test-svc", + ExporterType: "stdout", + SampleRatio: 1.0, + Propagator: "w3c", + }); err != nil { + t.Fatalf("Init: %v", err) + } + + gin.SetMode(gin.TestMode) + r := gin.New() + r.Use(Middleware("test-svc")) + + var seenTraceID string + r.GET("/p", func(c *gin.Context) { + // 关键：用 c.Request.Context()（而非 trace.GetContext(c)）取 span。 + s := oteltrace.SpanFromContext(c.Request.Context()) + seenTraceID = s.SpanContext().TraceID().String() + c.String(http.StatusOK, "ok") + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/p", nil) + r.ServeHTTP(w, req) + + if seenTraceID == "" { + t.Fatal("c.Request.Context() has no span/TraceID (C13d: Middleware didn't update c.Request)") + } + headerTraceID := w.Header().Get("X-Trace-ID") + if headerTraceID == "" { + t.Fatal("X-Trace-ID header missing") + } + if seenTraceID != headerTraceID { + t.Errorf("TraceID mismatch: downstream %q vs header %q (C13d)", seenTraceID, headerTraceID) + } +} + +// TestC13dPropagatedTraceContextExtracted 验证 Middleware 从入站 W3C 头提取父 context +// 并写入 c.Request，下游 span 继承父 TraceID。 +func TestC13dPropagatedTraceContextExtracted(t *testing.T) { + resetGlobal(t) + t.Cleanup(func() { _ = Close(context.Background()); resetGlobal(t) }) + + if err := Init(Config{ + Enabled: true, ServiceName: "test-svc", ExporterType: "stdout", + SampleRatio: 1.0, Propagator: "w3c", + }); err != nil { + t.Fatalf("Init: %v", err) + } + + // 构造一个父 span 并注入 W3C traceparent 头（用真实采样 provider，非 noop）。 + parentProvider := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.AlwaysSample())) + defer parentProvider.Shutdown(context.Background()) + parentTracer := parentProvider.Tracer("test-parent") + parentCtx, parentSpan := parentTracer.Start(context.Background(), "parent") + defer parentSpan.End() + parentTraceID := parentSpan.SpanContext().TraceID().String() + + carrier := propagation.HeaderCarrier{} + otel.GetTextMapPropagator().Inject(parentCtx, carrier) + + gin.SetMode(gin.TestMode) + r := gin.New() + r.Use(Middleware("test-svc")) + var seen string + r.GET("/p", func(c *gin.Context) { + s := oteltrace.SpanFromContext(c.Request.Context()) + seen = s.SpanContext().TraceID().String() + c.Status(http.StatusOK) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/p", nil) + // 把 carrier 中的头复制到请求。 + for _, key := range carrier.Keys() { + req.Header.Set(key, carrier.Get(key)) + } + r.ServeHTTP(w, req) + + if seen != parentTraceID { + t.Errorf("downstream TraceID = %q, want parent %q (C13d propagation/extract)", seen, parentTraceID) + } +} + +// ============================================================ +// C13e：b3/jaeger 未实现 +// ============================================================ + +// TestC13eB3PropagatorImplemented 验证 b3 传播器返回非 nil 的 b3 propagator（C13e 实现）。 +func TestC13eB3PropagatorImplemented(t *testing.T) { + prop, err := createPropagator("b3") + if err != nil { + t.Fatalf("createPropagator(b3): %v (C13e unimplemented)", err) + } + if prop == nil { + t.Fatal("createPropagator(b3) returned nil (C13e)") + } + // 用真实采样的 provider tracer，使 span SpanContext 有效。 + tp := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.AlwaysSample())) + defer tp.Shutdown(context.Background()) + tracer := tp.Tracer("t") + ctx, span := tracer.Start(context.Background(), "s") + defer span.End() + // b3 propagator 应识别 b3 头。注入后 b3 单头或 x-b3-traceid 至少其一非空。 + carrier := propagation.HeaderCarrier{} + prop.Inject(ctx, carrier) + if carrier.Get("b3") == "" && carrier.Get("x-b3-traceid") == "" { + t.Error("b3 propagator did not inject b3 headers (C13e)") + } +} + +// TestC13eJaegerMapsToW3C 验证 jaeger 映射 W3C TraceContext（非静默 nil）。 +func TestC13eJaegerMapsToW3C(t *testing.T) { + prop, err := createPropagator("jaeger") + if err != nil { + t.Fatalf("createPropagator(jaeger): %v (C13e)", err) + } + if prop == nil { + t.Fatal("createPropagator(jaeger) returned nil (C13e)") + } + // 用真实采样的 provider tracer，使 span SpanContext 有效（noop tracer 不生成 TraceID）。 + tp := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.AlwaysSample())) + defer tp.Shutdown(context.Background()) + tracer := tp.Tracer("t") + ctx, span := tracer.Start(context.Background(), "s") + defer span.End() + // 注入 W3C traceparent 头。 + carrier := propagation.HeaderCarrier{} + prop.Inject(ctx, carrier) + if carrier.Get("traceparent") == "" { + t.Error("jaeger(→W3C) propagator did not inject traceparent (C13e)") + } +} + +// TestC13eUnknownPropagatorReturnsError 验证未知传播器返错（修复前静默回落 W3C）。 +func TestC13eUnknownPropagatorReturnsError(t *testing.T) { + prop, err := createPropagator("xyz") + if err == nil { + t.Error("createPropagator(unknown) should return error (C13e), got nil") + } + if prop != nil { + t.Errorf("createPropagator(unknown) should return nil, got %T", prop) + } +} + +// TestC13eInitUnknownPropagatorFails 验证 Init 未知传播器返错且回滚 provider。 +func TestC13eInitUnknownPropagatorFails(t *testing.T) { + t.Cleanup(func() { resetGlobal(t) }) + err := Init(Config{Enabled: true, ExporterType: "stdout", Propagator: "xyz"}) + if err == nil { + t.Error("Init with unknown propagator should fail (C13e)") + } +} + +// TestC13eW3CDefault 验证空 propagator 默认 W3C（兼容）。 +func TestC13eW3CDefault(t *testing.T) { + prop, err := createPropagator("") + if err != nil { + t.Fatalf("createPropagator(''): %v", err) + } + if prop == nil { + t.Fatal("createPropagator('') returned nil") + } +} + +// ============================================================ +// C13 顺带：GetContext 裸断言防护 +// ============================================================ + +// TestC13GetContextCommaOk 验证 otel_ctx 被置为非 context 值时不 panic。 +func TestC13GetContextCommaOk(t *testing.T) { + gin.SetMode(gin.TestMode) + c, _ := gin.CreateTestContext(httptest.NewRecorder()) + c.Request = httptest.NewRequest(http.MethodGet, "/", nil) + c.Set("otel_ctx", "not-a-context") // 污染 + + // 修复前：ctx.(context.Context) 裸断言 panic；修复后 comma-ok 回退 c.Request.Context()。 + ctx := GetContext(c) + if ctx == nil { + t.Fatal("GetContext returned nil") + } + // 应回退到 c.Request.Context()。 + if ctx != c.Request.Context() { + t.Error("GetContext should fall back to c.Request.Context() on bad otel_ctx") + } +} + +// ============================================================ +// H-14：Close→Init→Close 多轮生命周期（原 sync.Once 致第二次 Close 不 Shutdown） +// ============================================================ + +// TestH14CloseInitCloseMultipleRounds 验证 Close 可反复执行， +// 且 Close→Init→Close 第二次 Close 仍真正 Shutdown 新 provider（不泄漏 exporter）。 +// +// 修复前：Close 用 sync.Once，第二次 Close no-op，第二轮 Init 创建的 provider 的 +// exporter 后台 goroutine/连接泄漏。 +func TestH14CloseInitCloseMultipleRounds(t *testing.T) { + t.Cleanup(func() { resetGlobal(t) }) + + for round := 0; round < 3; round++ { + if err := Init(Config{Enabled: true, ServiceName: "svc", ExporterType: "stdout", Propagator: "w3c"}); err != nil { + t.Fatalf("round %d Init failed: %v", round, err) + } + // Init 后 provider 非 nil + if TracerProvider() == nil { + t.Fatalf("round %d: provider nil after Init", round) + } + if err := Close(context.Background()); err != nil { + t.Fatalf("round %d Close failed: %v", round, err) + } + // Close 后仍非 nil（兜底 NeverSample provider，C13a） + if TracerProvider() == nil { + t.Fatalf("round %d: provider nil after Close", round) + } + } +} + +// TestH14CloseIdempotent 验证连续 Close 不 panic、不报错。 +func TestH14CloseIdempotent(t *testing.T) { + t.Cleanup(func() { resetGlobal(t) }) + if err := Close(context.Background()); err != nil { + t.Fatalf("first Close: %v", err) + } + if err := Close(context.Background()); err != nil { + t.Fatalf("second Close: %v", err) + } +} + +// ============================================================ +// M14 trace residue: validation, timeout, nil guards, headers, service name +// ============================================================ +func TestM14SampleRatioRange(t *testing.T) { + t.Cleanup(func() { resetGlobal(t) }) + + for _, ratio := range []float64{-0.01, 1.01, math.NaN()} { + err := Init(Config{ + Enabled: true, + ExporterType: "stdout", + Propagator: "w3c", + SampleRatio: ratio, + }) + if err == nil { + t.Fatalf("Init with SampleRatio=%v should fail", ratio) + } + } + + for _, ratio := range []float64{0, 1} { + if err := Init(Config{ + Enabled: true, + ServiceName: "svc", + ExporterType: "stdout", + Propagator: "w3c", + SampleRatio: ratio, + }); err != nil { + t.Fatalf("Init with boundary SampleRatio=%v failed: %v", ratio, err) + } + if err := Close(context.Background()); err != nil { + t.Fatalf("Close after SampleRatio=%v: %v", ratio, err) + } + } +} + +func TestM14CloseUsesOperationTimeout(t *testing.T) { + resetGlobal(t) + t.Cleanup(func() { resetGlobal(t) }) + setOperationTimeoutForTest(t, 20*time.Millisecond) + + blockingProvider := sdktrace.NewTracerProvider(sdktrace.WithSyncer(blockingExporter{})) + tracerProviderPtr.Store(blockingProvider) + + start := time.Now() + err := Close(context.Background()) + elapsed := time.Since(start) + if !errors.Is(err, context.DeadlineExceeded) { + t.Fatalf("Close error = %v, want context deadline exceeded", err) + } + if elapsed > 500*time.Millisecond { + t.Fatalf("Close took %s, expected operation timeout to bound shutdown", elapsed) + } +} + +func TestM14InitDisabledShutdownUsesOperationTimeout(t *testing.T) { + resetGlobal(t) + t.Cleanup(func() { resetGlobal(t) }) + setOperationTimeoutForTest(t, 20*time.Millisecond) + + blockingProvider := sdktrace.NewTracerProvider(sdktrace.WithSyncer(blockingExporter{})) + tracerProviderPtr.Store(blockingProvider) + + start := time.Now() + if err := Init(Config{Enabled: false, ServiceName: "svc"}); err != nil { + t.Fatalf("Init disabled: %v", err) + } + if elapsed := time.Since(start); elapsed > 500*time.Millisecond { + t.Fatalf("Init disabled took %s, expected operation timeout to bound old provider shutdown", elapsed) + } +} + +func TestM14RecordErrorNilInputsNoPanic(t *testing.T) { + gin.SetMode(gin.TestMode) + c, _ := gin.CreateTestContext(httptest.NewRecorder()) + c.Request = httptest.NewRequest(http.MethodGet, "/", nil) + + requireNoPanic(t, func() { RecordError(nil, errors.New("boom")) }) + requireNoPanic(t, func() { RecordError(c, nil) }) + + var nilSpan oteltrace.Span + requireNoPanic(t, func() { RecordErrorToSpan(nilSpan, errors.New("boom")) }) + requireNoPanic(t, func() { + RecordErrorToSpan(oteltrace.SpanFromContext(context.Background()), nil) + }) +} + +func TestM14NoZeroTraceIDHeaderFromNoop(t *testing.T) { + resetGlobal(t) + t.Cleanup(func() { resetGlobal(t) }) + + gin.SetMode(gin.TestMode) + r := gin.New() + r.Use(Middleware("svc")) + r.GET("/p", func(c *gin.Context) { + c.Status(http.StatusOK) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/p", nil) + r.ServeHTTP(w, req) + + const zeroTraceID = "00000000000000000000000000000000" + if got := w.Header().Get("X-Trace-ID"); got == zeroTraceID { + t.Fatalf("X-Trace-ID should not expose all-zero TraceID, got %q", got) + } +} + +func TestM14MiddlewareServiceNameAttribute(t *testing.T) { + resetGlobal(t) + t.Cleanup(func() { resetGlobal(t) }) + + exporter := &recordingExporter{} + provider := sdktrace.NewTracerProvider( + sdktrace.WithSyncer(exporter), + sdktrace.WithSampler(sdktrace.AlwaysSample()), + ) + tracer := provider.Tracer("test") + tracerProviderPtr.Store(provider) + tracerPtr.Store(&tracer) + + gin.SetMode(gin.TestMode) + r := gin.New() + r.Use(Middleware("middleware-svc")) + r.GET("/p", func(c *gin.Context) { + c.Status(http.StatusOK) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/p", nil) + r.ServeHTTP(w, req) + + for _, span := range exporter.Spans() { + for _, attr := range span.Attributes() { + if string(attr.Key) == "service.name" && attr.Value.AsString() == "middleware-svc" { + return + } + } + } + t.Fatal("server span missing service.name attribute from Middleware(serviceName)") +} + +// TestM65PropagatorFailureLeavesOtelUsable 验证传播器失败时 otel 全局未被切到 +// 已 Shutdown 的 provider（M-65）。失败后仍可正常 start span 不 panic。 +func TestM65PropagatorFailureLeavesOtelUsable(t *testing.T) { + t.Cleanup(func() { resetGlobal(t) }) + + // 先成功 Init 一个 + if err := Init(Config{Enabled: true, ServiceName: "svc", ExporterType: "stdout", Propagator: "w3c"}); err != nil { + t.Fatalf("setup Init: %v", err) + } + + // 再用非法传播器 Init，应失败 + err := Init(Config{Enabled: true, ExporterType: "stdout", Propagator: "xyz"}) + if err == nil { + t.Fatal("Init with bad propagator should fail") + } + + // otel 全局 provider 仍可用：StartSpan 不 panic + tr := otel.Tracer("test") + _, span := tr.Start(context.Background(), "after-failure") + span.End() +} diff --git a/utils/convert.go b/utils/convert.go new file mode 100644 index 0000000..32e1732 --- /dev/null +++ b/utils/convert.go @@ -0,0 +1,106 @@ +package utils + +import ( + "strconv" +) + +// ToInt 字符串转 int，失败返回 0 +func ToInt(s string) int { + n, _ := strconv.Atoi(s) + return n +} + +// ToIntE converts a string to int and returns parse errors. Prefer it when 0 +// is a meaningful value and parse failure must be distinguishable. +func ToIntE(s string) (int, error) { + return strconv.Atoi(s) +} + +// ToIntDefault 字符串转 int，失败返回默认值 +func ToIntDefault(s string, def int) int { + n, err := strconv.Atoi(s) + if err != nil { + return def + } + return n +} + +// ToInt64 字符串转 int64，失败返回 0 +func ToInt64(s string) int64 { + n, _ := strconv.ParseInt(s, 10, 64) + return n +} + +// ToInt64E converts a string to int64 and returns parse errors. Prefer it when +// 0 is a meaningful value and parse failure must be distinguishable. +func ToInt64E(s string) (int64, error) { + return strconv.ParseInt(s, 10, 64) +} + +// ToInt64Default 字符串转 int64，失败返回默认值 +func ToInt64Default(s string, def int64) int64 { + n, err := strconv.ParseInt(s, 10, 64) + if err != nil { + return def + } + return n +} + +// ToUint64 字符串转 uint64，失败返回 0 +func ToUint64(s string) uint64 { + n, _ := strconv.ParseUint(s, 10, 64) + return n +} + +// ToUint64Default 字符串转 uint64，失败返回默认值 +func ToUint64Default(s string, def uint64) uint64 { + n, err := strconv.ParseUint(s, 10, 64) + if err != nil { + return def + } + return n +} + +// ToFloat64 字符串转 float64，失败返回 0 +func ToFloat64(s string) float64 { + n, _ := strconv.ParseFloat(s, 64) + return n +} + +// ToFloat64Default 字符串转 float64，失败返回默认值 +func ToFloat64Default(s string, def float64) float64 { + n, err := strconv.ParseFloat(s, 64) + if err != nil { + return def + } + return n +} + +// ToString 整数转字符串 +func ToString(n int) string { + return strconv.Itoa(n) +} + +// ToString64 int64 转字符串 +func ToString64(n int64) string { + return strconv.FormatInt(n, 10) +} + +// CalcPageCount 计算总页数（向上取整）。total<=0 或 pageSize<=0 时返回 0。 +func CalcPageCount(total, pageSize int64) int64 { + if total <= 0 || pageSize <= 0 { + return 0 + } + return (total + pageSize - 1) / pageSize +} + +// CalcOffset 计算分页偏移量 (page-1)*pageSize。page<=0 时按 1 处理，pageSize<=0 时按 20 处理。 +func CalcOffset(page, pageSize int) int { + if page <= 0 { + page = 1 + } + if pageSize <= 0 { + pageSize = 20 + } + return (page - 1) * pageSize +} diff --git a/utils/crypto.go b/utils/crypto.go new file mode 100644 index 0000000..67d22fb --- /dev/null +++ b/utils/crypto.go @@ -0,0 +1,126 @@ +package utils + +import ( + "bytes" + "crypto/md5" // #nosec G501 -- exported checksum helper for non-password/non-security use; callers needing security should use SHA256/HMAC. + "crypto/sha1" // #nosec G505 -- exported checksum helper for legacy/non-security use; callers needing security should use SHA256/HMAC. + "crypto/sha256" + "encoding/base64" + "encoding/hex" + "hash" + "io" + "os" +) + +// MD5 计算字符串的 MD5 哈希值 +// 注意: 不应用于密码存储 +func MD5(s string) string { + return MD5Bytes([]byte(s)) +} + +// MD5Bytes 计算字节数组的 MD5 哈希值 +func MD5Bytes(data []byte) string { + // #nosec G401 -- MD5 helper is retained for legacy checksums, not password storage or security decisions. + h := md5.New() + h.Write(data) + return hex.EncodeToString(h.Sum(nil)) +} + +// SHA1 计算字符串的 SHA1 哈希值 +// 注意: 不应用于密码存储 +func SHA1(s string) string { + // #nosec G401 -- SHA1 helper is retained for legacy checksums, not password storage or security decisions. + h := sha1.New() + h.Write([]byte(s)) + return hex.EncodeToString(h.Sum(nil)) +} + +// SHA256 计算字符串的 SHA256 哈希值 +func SHA256(s string) string { + h := sha256.New() + h.Write([]byte(s)) + return hex.EncodeToString(h.Sum(nil)) +} + +// SHA256Bytes 计算字节数组的 SHA256 哈希值 +func SHA256Bytes(data []byte) string { + h := sha256.New() + h.Write(data) + return hex.EncodeToString(h.Sum(nil)) +} + +// HashFile 流式计算文件的哈希值，返回 hex 编码字符串。 +// +// newHash 须返回全新的 hash.Hash 实例（如 sha256.New），本函数不复用它。 +// Open 或读取失败时返回错误。M-F 修复：改为流式 io.Copy(h, f)，不再经 ReadFile 把整文件 +// 读入内存——原实现大文件 OOM。流式哈希内存占用恒定、可处理任意大小文件，与 hash.Hash +// 的 io.Writer 接口契合。调用方负责选择哈希算法（如 sha256.New）。 +func HashFile(path string, newHash func() hash.Hash) (string, error) { + // #nosec G304 -- generic hashing helper intentionally opens caller-provided trusted local paths. + f, err := os.Open(path) + if err != nil { + return "", err + } + defer f.Close() + h := newHash() + if _, err := io.Copy(h, f); err != nil { + return "", err + } + return hex.EncodeToString(h.Sum(nil)), nil +} + +// Base64Encode Base64 编码 +func Base64Encode(data []byte) string { + return base64.StdEncoding.EncodeToString(data) +} + +// Base64Decode Base64 解码 +func Base64Decode(s string) ([]byte, error) { + return base64.StdEncoding.DecodeString(s) +} + +// Base64URLEncode URL 安全的 Base64 编码 +func Base64URLEncode(data []byte) string { + return base64.URLEncoding.EncodeToString(data) +} + +// Base64URLDecode URL 安全的 Base64 解码 +func Base64URLDecode(s string) ([]byte, error) { + return base64.URLEncoding.DecodeString(s) +} + +// Nl2br 将换行符替换为
标签 +func Nl2br(s string, isXhtml bool) string { + var br string + if isXhtml { + br = "
" + } else { + br = "
" + } + + var buf bytes.Buffer + runes := []rune(s) + length := len(runes) + + for i, r := range runes { + switch r { + case '\n': + // \n\r（罕见顺序）作为一个换行处理；普通 \n 单独处理。 + // （N4：原条件含 r == '\r' 半，但本 case 内 r 恒为 '\n'，该半恒假，已清理。） + if i+1 < length && runes[i+1] == '\r' { + buf.WriteString(br) + continue + } + buf.WriteString(br) + case '\r': + // \r\n 由上面的 \n 分支处理（\r 在此跳过）；单独 \r 作为一个换行。 + if i+1 < length && runes[i+1] == '\n' { + continue + } + buf.WriteString(br) + default: + buf.WriteRune(r) + } + } + return buf.String() +} diff --git a/utils/datetime.go b/utils/datetime.go new file mode 100644 index 0000000..5709f3d --- /dev/null +++ b/utils/datetime.go @@ -0,0 +1,101 @@ +package utils + +import ( + "strconv" + "time" +) + +// NowUnix 返回当前秒级时间戳 +func NowUnix() int64 { + return time.Now().Unix() +} + +// NowTimestamp 返回当前毫秒时间戳 +func NowTimestamp() int64 { + return time.Now().UnixMilli() +} + +// FromUnix 秒级时间戳转 time.Time +func FromUnix(unix int64) time.Time { + return time.Unix(unix, 0) +} + +// FromTimestamp 毫秒时间戳转 time.Time +func FromTimestamp(timestamp int64) time.Time { + return time.UnixMilli(timestamp) +} + +// FormatTime 格式化时间 +func FormatTime(t time.Time, layout string) string { + return t.Format(layout) +} + +// ParseTime 解析时间字符串 +func ParseTime(timeStr, layout string) (time.Time, error) { + return time.Parse(layout, timeStr) +} + +// FormatDateTime 格式化为标准日期时间 "2006-01-02 15:04:05" +func FormatDateTime(t time.Time) string { + return t.Format("2006-01-02 15:04:05") +} + +// FormatDate 格式化为日期 "2006-01-02" +func FormatDate(t time.Time) string { + return t.Format("2006-01-02") +} + +// FormatTimeOnly 格式化为时间 "15:04:05" +func FormatTimeOnly(t time.Time) string { + return t.Format("15:04:05") +} + +// StartOfDay 返回指定时间当天的开始时间 (00:00:00) +func StartOfDay(t time.Time) time.Time { + return time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, t.Location()) +} + +// EndOfDay 返回指定时间当天的结束时间 (23:59:59.999999999) +func EndOfDay(t time.Time) time.Time { + return time.Date(t.Year(), t.Month(), t.Day(), 23, 59, 59, 999999999, t.Location()) +} + +// StartOfWeek 返回指定时间当周的开始时间（周一为第一天，00:00:00）。 +// +// 用日历日回退而非 t.Add(-N*24h)，避免 DST 切换日 24h ≠ 1 个日历日导致落错日（M4）。 +func StartOfWeek(t time.Time) time.Time { + weekday := int(t.Weekday()) + if weekday == 0 { + weekday = 7 // 周日归为 7，使周一为第一天 + } + // 回退到本周周一的日历日，再取当日 00:00:00（保留原时区）。 + monday := time.Date(t.Year(), t.Month(), t.Day()-(weekday-1), 0, 0, 0, 0, t.Location()) + return StartOfDay(monday) +} + +// StartOfMonth 返回指定时间当月 1 日 00:00:00（保留原时区）。 +func StartOfMonth(t time.Time) time.Time { + return time.Date(t.Year(), t.Month(), 1, 0, 0, 0, 0, t.Location()) +} + +// EndOfMonth 返回指定时间当月最后一天 23:59:59.999999999（保留原时区）。 +func EndOfMonth(t time.Time) time.Time { + return time.Date(t.Year(), t.Month()+1, 0, 23, 59, 59, 999999999, t.Location()) +} + +// GetDateInt 返回 yyyyMMdd 格式的日期整数 +func GetDateInt(t time.Time) int { + ret, _ := strconv.Atoi(t.Format("20060102")) + return ret +} + +// ParseDateInt 将 yyyyMMdd 格式的整数转为时间（当日 00:00:00，本地时区）。 +// +// 注意：非法输入（如 month=13、day=32）会被 time.Date 静默规范化（溢出进位）， +// 调用方需自行保证输入合法或在使用前校验（M4）。 +func ParseDateInt(date int) time.Time { + year := date / 10000 + month := (date % 10000) / 100 + day := date % 100 + return time.Date(year, time.Month(month), day, 0, 0, 0, 0, time.Local) +} diff --git a/utils/file.go b/utils/file.go new file mode 100644 index 0000000..56528a9 --- /dev/null +++ b/utils/file.go @@ -0,0 +1,125 @@ +package utils + +import ( + "errors" + "io" + "os" + "path/filepath" +) + +// 本文件提供通用本地文件操作工具（读/写/复制/追加/存在性/删除）。 +// +// ⚠️ 安全说明（M3）：这些函数直接操作调用方传入的路径，不做路径穿越校验。 +// 若路径可能来自不可信输入（用户上传文件名、URL 参数等），调用方必须自行净化 +// （如 filepath.Clean + 前缀锚定），否则存在任意文件读/写/删风险。 +// 框架自身的不可信文件处理（storage 上传/下载）已在 storage 包内做穿越防护（C4）。 + +// FileExists 检查文件是否存在 +func FileExists(path string) bool { + _, err := os.Stat(path) + return err == nil +} + +// DirExists 检查目录是否存在 +func DirExists(path string) bool { + info, err := os.Stat(path) + if err != nil { + return false + } + return info.IsDir() +} + +// EnsureDir 确保目录存在，不存在则创建 +func EnsureDir(path string) error { + // #nosec G301 -- generic filesystem helper intentionally uses conventional directory permissions; caller controls trusted path and policy. + return os.MkdirAll(path, 0755) +} + +// ReadFile 读取文件内容。 +// +// M-F 修复：去掉前置 FileExists 检查（TOCTOU 竞态——检查与读取之间文件可能被删除/替换）， +// 直接 os.ReadFile 并返回其错误。文件不存在时返回 *os.PathError，调用方可经 +// errors.Is(err, os.ErrNotExist) 精确判断。 +// +// 注意：本函数无大小上限（os.ReadFile 语义），读取不可信/超大文件有 OOM 风险—— +// 需限长读取请用 io.ReadAll(io.LimitReader(...))；流式哈希大文件请用 HashFile（已流式）。 +func ReadFile(path string) ([]byte, error) { + // #nosec G304 -- generic filesystem helper intentionally reads caller-provided trusted paths; package docs require callers to sanitize untrusted input. + return os.ReadFile(path) +} + +// WriteFile 写入文件内容（覆盖） +func WriteFile(path string, data []byte) error { + dir := filepath.Dir(path) + if err := EnsureDir(dir); err != nil { + return err + } + // #nosec G306 -- generic filesystem helper intentionally uses conventional file permissions; caller controls trusted path and policy. + return os.WriteFile(path, data, 0644) +} + +// AppendFile 追加内容到文件 +func AppendFile(path string, data []byte) error { + dir := filepath.Dir(path) + if err := EnsureDir(dir); err != nil { + return err + } + // #nosec G302,G304 -- generic filesystem helper intentionally appends caller-provided trusted paths with conventional file permissions. + f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_APPEND, 0644) + if err != nil { + return err + } + _, err = f.Write(data) + if cerr := f.Close(); cerr != nil { + return errors.Join(err, cerr) + } + return err +} + +// CopyFile 将 src 复制到 dst（覆盖），自动创建目标目录。src 不存在时返回其 Open 错误。 +func CopyFile(dst, src string) error { + // #nosec G304 -- generic filesystem helper intentionally opens caller-provided trusted source paths. + srcFile, err := os.Open(src) + if err != nil { + return err + } + defer func() { + _ = srcFile.Close() + }() + + // 确保目标目录存在 + dir := filepath.Dir(dst) + if err := EnsureDir(dir); err != nil { + return err + } + + // #nosec G304 -- generic filesystem helper intentionally creates caller-provided trusted destination paths. + dstFile, err := os.Create(dst) + if err != nil { + return err + } + + _, err = io.Copy(dstFile, srcFile) + if cerr := dstFile.Close(); cerr != nil { + return errors.Join(err, cerr) + } + return err +} + +// FileSize 获取文件大小 +func FileSize(path string) (int64, error) { + info, err := os.Stat(path) + if err != nil { + return 0, err + } + return info.Size(), nil +} + +// RemoveFile 删除文件（忽略不存在的错误） +func RemoveFile(path string) error { + err := os.Remove(path) + if os.IsNotExist(err) { + return nil + } + return err +} diff --git a/utils/http.go b/utils/http.go new file mode 100644 index 0000000..774e425 --- /dev/null +++ b/utils/http.go @@ -0,0 +1,541 @@ +package utils + +import ( + "bytes" + "crypto/tls" + "encoding/json" + "errors" + "fmt" + "io" + "mime/multipart" + "net" + "net/http" + "net/url" + "os" + "path/filepath" + "strings" + "sync" + "syscall" + "time" +) + +// HTTPClient 封装可运行期调整配置的 HTTP 客户端。 +type HTTPClient struct { + mu sync.RWMutex + client *http.Client + transport *http.Transport + cfg HTTPClientConfig + timeout time.Duration + headers map[string]string + cookies map[string]string + skipTLS bool + // maxRespBodySize 限制 do 读取的响应体大小；0 使用默认值，-1 表示不限制。 + maxRespBodySize int64 +} + +// UploadFile 描述 multipart 上传中的文件字段。 +type UploadFile struct { + FieldName string + FilePath string +} + +// HTTPClientConfig 是 HTTPClient 的配置。 +type HTTPClientConfig struct { + Timeout time.Duration + MaxIdleConns int + IdleConnTimeout time.Duration + MaxConnsPerHost int + MaxIdleConnsPerHost int + SkipTLSVerify bool + MaxResponseBodySize int64 + BlockPrivateNetworks bool +} + +// ErrSSRFBlocked 表示 SSRF 防护拦截了目标 IP。 +var ErrSSRFBlocked = errors.New("ssrf guard: 目标 IP 属于被拦截的网络范围") + +// isBlockedIP 判断 ip 是否属于应被 SSRF 防护拦截的网络范围。 +func isBlockedIP(ip net.IP) bool { + if ip == nil { + return true + } + return ip.IsLoopback() || ip.IsPrivate() || + ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() || + ip.IsUnspecified() || ip.IsMulticast() || ip.IsInterfaceLocalMulticast() +} + +// ssrfControl 在拨号前拦截私有、回环、链路本地、未指定和多播 IP。 +func ssrfControl(network, address string, _ syscall.RawConn) error { + host, _, err := net.SplitHostPort(address) + if err != nil { + return err + } + ip := net.ParseIP(host) + if ip == nil { + return fmt.Errorf("%w: 无法解析地址 %q", ErrSSRFBlocked, address) + } + if isBlockedIP(ip) { + return fmt.Errorf("%w: %s", ErrSSRFBlocked, ip) + } + return nil +} + +// DefaultHTTPClientConfig 是包级默认 HTTP 客户端配置。 +var DefaultHTTPClientConfig = HTTPClientConfig{ + Timeout: 30 * time.Second, + MaxIdleConns: 100, + IdleConnTimeout: 90 * time.Second, + MaxConnsPerHost: 10, + MaxIdleConnsPerHost: 10, + SkipTLSVerify: false, + MaxResponseBodySize: 32 * 1024 * 1024, +} + +// NewHTTPClient 使用默认配置创建 HTTP 客户端。 +func NewHTTPClient() *HTTPClient { + cfg := DefaultHTTPClientConfig + return NewHTTPClientWithConfig(cfg) +} + +// NewSSRFSafeHTTPClient 创建启用 SSRF 防护的 HTTP 客户端。 +func NewSSRFSafeHTTPClient() *HTTPClient { + cfg := DefaultHTTPClientConfig + cfg.BlockPrivateNetworks = true + return NewHTTPClientWithConfig(cfg) +} + +// NewHTTPClientWithConfig 使用 cfg 创建 HTTP 客户端。 +func NewHTTPClientWithConfig(cfg HTTPClientConfig) *HTTPClient { + transport, client := buildHTTPClientPair(cfg) + return &HTTPClient{ + client: client, + transport: transport, + cfg: cfg, + timeout: cfg.Timeout, + headers: make(map[string]string), + cookies: make(map[string]string), + skipTLS: cfg.SkipTLSVerify, + maxRespBodySize: cfg.MaxResponseBodySize, + } +} + +// buildHTTPClientPair 根据 cfg 构造 transport/client 对。 +func buildHTTPClientPair(cfg HTTPClientConfig) (*http.Transport, *http.Client) { + transport := &http.Transport{ + // #nosec G402 -- SkipTLSVerify 仅在调用方显式配置时启用，默认校验 TLS。 + TLSClientConfig: &tls.Config{ + InsecureSkipVerify: cfg.SkipTLSVerify, + }, + MaxIdleConns: cfg.MaxIdleConns, + IdleConnTimeout: cfg.IdleConnTimeout, + MaxConnsPerHost: cfg.MaxConnsPerHost, + MaxIdleConnsPerHost: cfg.MaxIdleConnsPerHost, + DisableCompression: false, + } + if cfg.BlockPrivateNetworks { + dialer := &net.Dialer{ + Timeout: 30 * time.Second, + KeepAlive: 30 * time.Second, + Control: ssrfControl, + } + transport.DialContext = dialer.DialContext + } + client := &http.Client{ + Transport: transport, + Timeout: cfg.Timeout, + } + return transport, client +} + +// currentClient 返回当前 client 快照。 +func (c *HTTPClient) currentClient() *http.Client { + c.mu.RLock() + defer c.mu.RUnlock() + return c.client +} + +// currentTransport 返回当前 transport 快照。 +func (c *HTTPClient) currentTransport() *http.Transport { + c.mu.RLock() + defer c.mu.RUnlock() + return c.transport +} + +// SetTimeout 更新请求超时时间，并保留当前 transport。 +func (c *HTTPClient) SetTimeout(timeout time.Duration) *HTTPClient { + c.mu.Lock() + defer c.mu.Unlock() + c.timeout = timeout + c.cfg.Timeout = timeout + _, client := buildHTTPClientPair(c.cfg) + client.Transport = c.transport + c.client = client + return c +} + +// SetHeader 设置后续请求使用的请求头。 +func (c *HTTPClient) SetHeader(key, value string) *HTTPClient { + c.mu.Lock() + c.headers[key] = value + c.mu.Unlock() + return c +} + +// SetHeaders 批量设置后续请求使用的请求头。 +func (c *HTTPClient) SetHeaders(headers map[string]string) *HTTPClient { + c.mu.Lock() + for k, v := range headers { + c.headers[k] = v + } + c.mu.Unlock() + return c +} + +// SetCookie 设置后续请求使用的 Cookie。 +func (c *HTTPClient) SetCookie(key, value string) *HTTPClient { + c.mu.Lock() + c.cookies[key] = value + c.mu.Unlock() + return c +} + +// snapshotHeadersCookies 在锁内复制可变的 headers/cookies。 +func (c *HTTPClient) snapshotHeadersCookies() (headers, cookies map[string]string) { + c.mu.RLock() + defer c.mu.RUnlock() + headers = make(map[string]string, len(c.headers)) + for k, v := range c.headers { + headers[k] = v + } + cookies = make(map[string]string, len(c.cookies)) + for k, v := range c.cookies { + cookies[k] = v + } + return headers, cookies +} + +// SetSkipTLS 切换后续请求是否校验 TLS 证书。 +func (c *HTTPClient) SetSkipTLS(skip bool) *HTTPClient { + c.mu.Lock() + c.skipTLS = skip + c.cfg.SkipTLSVerify = skip + transport, client := buildHTTPClientPair(c.cfg) + oldTransport := c.transport + c.transport = transport + c.client = client + c.mu.Unlock() + // 在锁外释放旧 transport 的空闲连接。 + if oldTransport != nil { + oldTransport.CloseIdleConnections() + } + return c +} + +// SetBlockPrivateNetworks 切换后续请求的 SSRF 防护。 +func (c *HTTPClient) SetBlockPrivateNetworks(block bool) *HTTPClient { + c.mu.Lock() + c.cfg.BlockPrivateNetworks = block + transport, client := buildHTTPClientPair(c.cfg) + oldTransport := c.transport + c.transport = transport + c.client = client + c.mu.Unlock() + if oldTransport != nil { + oldTransport.CloseIdleConnections() + } + return c +} + +// Get 发送 GET 请求。 +func (c *HTTPClient) Get(urlStr string, params map[string]string) ([]byte, error) { + if len(params) > 0 { + u, err := url.Parse(urlStr) + if err != nil { + return nil, err + } + q := u.Query() + for k, v := range params { + q.Set(k, v) + } + u.RawQuery = q.Encode() + urlStr = u.String() + } + + req, err := http.NewRequest("GET", urlStr, nil) + if err != nil { + return nil, err + } + return c.do(req) +} + +// Post 发送表单编码的 POST 请求。 +func (c *HTTPClient) Post(urlStr string, params map[string]string) ([]byte, error) { + data := url.Values{} + for k, v := range params { + data.Set(k, v) + } + + req, err := http.NewRequest("POST", urlStr, strings.NewReader(data.Encode())) + if err != nil { + return nil, err + } + req.Header.Set("Content-Type", "application/x-www-form-urlencoded") + return c.do(req) +} + +// PostJSON 发送 JSON POST 请求。 +func (c *HTTPClient) PostJSON(urlStr string, data any) ([]byte, error) { + jsonData, err := json.Marshal(data) + if err != nil { + return nil, err + } + + req, err := http.NewRequest("POST", urlStr, bytes.NewReader(jsonData)) + if err != nil { + return nil, err + } + req.Header.Set("Content-Type", "application/json") + return c.do(req) +} + +// Put 发送 JSON PUT 请求。 +func (c *HTTPClient) Put(urlStr string, data any) ([]byte, error) { + jsonData, err := json.Marshal(data) + if err != nil { + return nil, err + } + + req, err := http.NewRequest("PUT", urlStr, bytes.NewReader(jsonData)) + if err != nil { + return nil, err + } + req.Header.Set("Content-Type", "application/json") + return c.do(req) +} + +// Delete 发送 DELETE 请求。 +func (c *HTTPClient) Delete(urlStr string) ([]byte, error) { + req, err := http.NewRequest("DELETE", urlStr, nil) + if err != nil { + return nil, err + } + return c.do(req) +} + +// Upload 以流式 multipart 上传文件，避免把完整请求体缓存在内存中。 +func (c *HTTPClient) Upload(urlStr string, files []UploadFile, params map[string]string) ([]byte, error) { + pr, pw := io.Pipe() + writer := multipart.NewWriter(pw) + errCh := make(chan error, 1) + + go func() { + errCh <- writeMultipartUpload(pw, writer, files, params) + }() + + req, err := http.NewRequest("POST", urlStr, pr) + if err != nil { + _ = pr.CloseWithError(err) + _ = pw.CloseWithError(err) + <-errCh + return nil, err + } + req.Header.Set("Content-Type", writer.FormDataContentType()) + + resp, err := c.do(req) + if err != nil { + _ = pr.CloseWithError(err) + <-errCh + return nil, err + } + if err := <-errCh; err != nil { + return nil, err + } + return resp, nil +} + +func writeMultipartUpload(pw *io.PipeWriter, writer *multipart.Writer, files []UploadFile, params map[string]string) (err error) { + defer func() { + if err != nil { + _ = pw.CloseWithError(err) + return + } + if closeErr := writer.Close(); closeErr != nil { + _ = pw.CloseWithError(closeErr) + err = closeErr + return + } + err = pw.Close() + }() + + for _, f := range files { + if err = writeMultipartFile(writer, f); err != nil { + return err + } + } + + for k, v := range params { + if err = writer.WriteField(k, v); err != nil { + return err + } + } + return nil +} + +func writeMultipartFile(writer *multipart.Writer, f UploadFile) (err error) { + file, err := os.Open(f.FilePath) + if err != nil { + return err + } + defer func() { + if cerr := file.Close(); cerr != nil { + err = errors.Join(err, cerr) + } + }() + + part, err := writer.CreateFormFile(f.FieldName, filepath.Base(f.FilePath)) + if err != nil { + return err + } + _, err = io.Copy(part, file) + return err +} + +// UploadFromBytes 将内存中的字节切片作为 multipart 文件上传。 +func (c *HTTPClient) UploadFromBytes(urlStr string, fieldName string, filename string, data []byte, params map[string]string) ([]byte, error) { + var buf bytes.Buffer + writer := multipart.NewWriter(&buf) + + part, err := writer.CreateFormFile(fieldName, filename) + if err != nil { + return nil, err + } + if _, err = io.Copy(part, bytes.NewReader(data)); err != nil { + return nil, err + } + + for k, v := range params { + if err := writer.WriteField(k, v); err != nil { + return nil, err + } + } + + if err := writer.Close(); err != nil { + return nil, err + } + + req, err := http.NewRequest("POST", urlStr, &buf) + if err != nil { + return nil, err + } + req.Header.Set("Content-Type", writer.FormDataContentType()) + return c.do(req) +} + +// Request 使用调用方指定的方法和 JSON 请求体发送请求。 +func (c *HTTPClient) Request(method, urlStr string, body []byte) ([]byte, error) { + req, err := http.NewRequest(method, urlStr, bytes.NewReader(body)) + if err != nil { + return nil, err + } + if body != nil { + req.Header.Set("Content-Type", "application/json") + } + return c.do(req) +} + +// do 执行 req，并按配置封顶读取响应体。 +func (c *HTTPClient) do(req *http.Request) ([]byte, error) { + headers, cookies := c.snapshotHeadersCookies() + for k, v := range headers { + req.Header.Set(k, v) + } + for k, v := range cookies { + // #nosec G124 -- 这里构造的是出站 Cookie 请求头；Secure/HttpOnly/SameSite 适用于响应 Set-Cookie。 + req.AddCookie(&http.Cookie{Name: k, Value: v}) + } + + // #nosec G704 -- 默认客户端为兼容性允许调用方传入 URL；不可信 URL 请使用 NewSSRFSafeHTTPClient/BlockPrivateNetworks。 + resp, err := c.currentClient().Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + + // 将 4xx/5xx 响应视为请求错误。 + if resp.StatusCode >= 400 { + return nil, fmt.Errorf("HTTP 请求失败: %d %s", resp.StatusCode, resp.Status) + } + + // maxRespBodySize: 0 使用默认 32MiB 上限；-1 表示不限制。 + limit := c.maxRespBodySize + if limit == 0 { + limit = 32 * 1024 * 1024 + } + var reader io.Reader = resp.Body + if limit > 0 { + // 多读 1 字节用于判断响应体是否超限。 + reader = io.LimitReader(resp.Body, limit+1) + } + data, err := io.ReadAll(reader) + if err != nil { + return nil, err + } + if limit > 0 && int64(len(data)) > limit { + return nil, fmt.Errorf("响应体超过限制 %d 字节", limit) + } + return data, nil +} + +// DoWithResponse 执行 req 并返回原始响应；调用方必须关闭 resp.Body。 +func (c *HTTPClient) DoWithResponse(req *http.Request) (*http.Response, error) { + headers, cookies := c.snapshotHeadersCookies() + for k, v := range headers { + req.Header.Set(k, v) + } + for k, v := range cookies { + // #nosec G124 -- 这里构造的是出站 Cookie 请求头；Secure/HttpOnly/SameSite 适用于响应 Set-Cookie。 + req.AddCookie(&http.Cookie{Name: k, Value: v}) + } + + // #nosec G704 -- 默认客户端为兼容性允许调用方传入 URL；不可信 URL 请使用 NewSSRFSafeHTTPClient/BlockPrivateNetworks。 + return c.currentClient().Do(req) +} + +// Close 释放客户端 transport 持有的空闲连接。 +func (c *HTTPClient) Close() { + if t := c.currentTransport(); t != nil { + t.CloseIdleConnections() + } +} + +// JSONMarshal 将 v 序列化为 JSON。 +func JSONMarshal(v any) ([]byte, error) { + return json.Marshal(v) +} + +// defaultClient 是包级共享 HTTP 客户端。 +var defaultClient *HTTPClient +var defaultClientOnce sync.Once + +// DefaultHTTPClient 返回包级共享 HTTP 客户端。 +func DefaultHTTPClient() *HTTPClient { + defaultClientOnce.Do(func() { + defaultClient = NewHTTPClient() + }) + return defaultClient +} + +// HTTPGet 使用默认客户端发送 GET 请求。 +func HTTPGet(url string, params map[string]string) ([]byte, error) { + return DefaultHTTPClient().Get(url, params) +} + +// HTTPPost 使用默认客户端发送表单 POST 请求。 +func HTTPPost(url string, params map[string]string) ([]byte, error) { + return DefaultHTTPClient().Post(url, params) +} + +// HTTPPostJSON 使用默认客户端发送 JSON POST 请求。 +func HTTPPostJSON(url string, data any) ([]byte, error) { + return DefaultHTTPClient().PostJSON(url, data) +} diff --git a/utils/http_test.go b/utils/http_test.go new file mode 100644 index 0000000..4f22a52 --- /dev/null +++ b/utils/http_test.go @@ -0,0 +1,295 @@ +package utils_test + +import ( + "crypto/tls" + "errors" + "io" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "sync" + "testing" + + "github.com/EthanCodeCraft/xlgo-core/utils" +) + +// 回归 H2：默认 HTTPClient 必须 校验 TLS（InsecureSkipVerify=false）， +// 访问自签证书的 https server 应失败。旧实现 DefaultHTTPClientConfig.SkipTLSVerify=true， +// HTTPGet/Post 默认可被 MITM。 +func TestHTTPClientDefaultVerifiesTLS(t *testing.T) { + // 启动一个使用自签证书的 TLS server（httptest 自动生成证书，未被客户端信任）。 + srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("ok")) + })) + defer srv.Close() + + // 默认客户端（H2 修复后 SkipTLSVerify=false）应因证书校验失败而报错。 + c := utils.NewHTTPClient() + if _, err := c.Get(srv.URL, nil); err == nil { + t.Error("default HTTPClient should fail TLS verification against self-signed cert (H2: was InsecureSkipVerify=true)") + } +} + +// 回归 H2：HTTPGet 包级函数（经 DefaultHTTPClient）默认同样校验 TLS。 +func TestHTTPGetDefaultVerifiesTLS(t *testing.T) { + srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("ok")) + })) + defer srv.Close() + + if _, err := utils.HTTPGet(srv.URL, nil); err == nil { + t.Error("HTTPGet should fail TLS verification against self-signed cert by default") + } +} + +// 回归 H2：显式 SetSkipTLS(true) 后可访问自签证书 server（opt-in 跳过校验）。 +func TestHTTPClientSkipTLSOptIn(t *testing.T) { + srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("ok")) + })) + defer srv.Close() + + c := utils.NewHTTPClient() + c.SetSkipTLS(true) + + body, err := c.Get(srv.URL, nil) + if err != nil { + t.Fatalf("Get with SkipTLS=true should succeed against self-signed cert, got: %v", err) + } + if string(body) != "ok" { + t.Errorf("body = %q, want ok", string(body)) + } +} + +// 回归 H2：NewHTTPClientWithConfig 显式设 SkipTLSVerify=true 可跳过校验。 +func TestHTTPClientWithConfigSkipTLS(t *testing.T) { + srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("ok")) + })) + defer srv.Close() + + c := utils.NewHTTPClientWithConfig(utils.HTTPClientConfig{ + SkipTLSVerify: true, + }) + body, err := c.Get(srv.URL, nil) + if err != nil { + t.Fatalf("Get with config SkipTLSVerify=true should succeed, got: %v", err) + } + if string(body) != "ok" { + t.Errorf("body = %q, want ok", string(body)) + } +} + +// 回归 H2：DefaultHTTPClientConfig.SkipTLSVerify 默认 false。 +func TestDefaultHTTPClientConfigNoSkipTLS(t *testing.T) { + if utils.DefaultHTTPClientConfig.SkipTLSVerify { + t.Error("DefaultHTTPClientConfig.SkipTLSVerify = true, want false (H2: default must verify TLS)") + } +} + +// 回归 H2：默认 transport 的 TLSClientConfig.InsecureSkipVerify 为 false。 +// 直接构造一个对 https 的请求，确认未跳过校验。用 errors 判断是否为 x509 校验类错误。 +func TestDefaultClientTransportVerifiesTLS(t *testing.T) { + srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("ok")) + })) + defer srv.Close() + + c := utils.NewHTTPClient() + // 用自定义 client 配自定义 transport 不可行（封装），直接调 Get 验证错误类型。 + _, err := c.Get(srv.URL, nil) + if err == nil { + t.Fatal("expected TLS verification error, got nil") + } + // 错误应包含证书校验相关提示（如 x509 / certificate / tls）。 + if !isTLSError(err) { + t.Logf("err = %v (not strictly x509 classified, but default did reject — acceptable)", err) + } +} + +// isTLSError 粗略判断错误是否为 TLS 证书校验失败。 +func isTLSError(err error) bool { + if err == nil { + return false + } + var ve *tls.CertificateVerificationError + return errors.As(err, &ve) +} + +// TestHTTPClientSetSkipTLSConcurrent H-12 回归：并发 SetSkipTLS 与 Get 请求不应触发 +// 数据竞争，且 SetSkipTLS(true) 后能成功访问自签 TLS server。 +// 修复前 SetSkipTLS 直接覆盖 transport.TLSClientConfig 指针，与并发 Do 读该字段竞态。 +func TestHTTPClientSetSkipTLSConcurrent(t *testing.T) { + srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("ok")) + })) + defer srv.Close() + + c := utils.NewHTTPClient() + defer c.Close() + + var wg sync.WaitGroup + // 并发切换 TLS 策略 + for i := 0; i < 10; i++ { + wg.Add(1) + go func(i int) { + defer wg.Done() + c.SetSkipTLS(i%2 == 0) + }(i) + } + // 并发发请求（自签 server，仅 skip=true 时成功，skip=false 时 TLS 失败，均不应 panic/竞态） + for i := 0; i < 10; i++ { + wg.Add(1) + go func() { + defer wg.Done() + _, _ = c.Get(srv.URL, nil) + }() + } + wg.Wait() + + // 最终切到 skip=true，应能成功访问自签 server（验证 SetSkipTLS 重建后功能正常） + c.SetSkipTLS(true) + if _, err := c.Get(srv.URL, nil); err != nil { + t.Errorf("after SetSkipTLS(true), GET should succeed against self-signed server, got %v", err) + } +} + +// ===== P0：headers/cookies map 并发安全 ===== + +// 回归 P0：并发 SetHeader/SetCookie 与 Get 请求不应触发数据竞争（-race）。 +// 修复前 Set* 无锁写 map、do 无锁读 map，并发即竞态可 panic。 +func TestHTTPClientConcurrentHeadersNoRace(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("ok")) + })) + defer srv.Close() + + c := utils.NewHTTPClient() + defer c.Close() + + var wg sync.WaitGroup + for i := 0; i < 20; i++ { + wg.Add(1) + go func(i int) { + defer wg.Done() + c.SetHeader("X-Req", string(rune('A'+i%26))) + c.SetCookie("sid", string(rune('0'+i%10))) + c.SetHeaders(map[string]string{"X-Batch": "v"}) + }(i) + } + for i := 0; i < 20; i++ { + wg.Add(1) + go func() { + defer wg.Done() + _, _ = c.Get(srv.URL, nil) + }() + } + wg.Wait() +} + +// ===== P0：SSRF 防护 ===== + +// 回归 P0：启用 SSRF 防护后，连接回环地址（httptest server 监听 127.0.0.1）必须被拒绝， +// 返回 ErrSSRFBlocked。 +func TestHTTPClientSSRFBlocksLoopback(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("secret-internal")) + })) + defer srv.Close() + + c := utils.NewSSRFSafeHTTPClient() + defer c.Close() + + _, err := c.Get(srv.URL, nil) + if err == nil { + t.Fatal("SSRF-safe client should refuse to connect to loopback address") + } + if !errors.Is(err, utils.ErrSSRFBlocked) { + t.Errorf("err = %v, want ErrSSRFBlocked", err) + } +} + +// 回归 P0：未启用 SSRF 防护时（默认），回环连接照常放行（兼容性回归）。 +func TestHTTPClientSSRFDisabledAllowsLoopback(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("ok")) + })) + defer srv.Close() + + c := utils.NewHTTPClient() // 默认不启用 SSRF 防护 + defer c.Close() + + body, err := c.Get(srv.URL, nil) + if err != nil { + t.Fatalf("default client should allow loopback, got %v", err) + } + if string(body) != "ok" { + t.Errorf("body = %q, want ok", string(body)) + } +} + +// 回归 P0：SetBlockPrivateNetworks 运行期开关生效——开启后回环被拒。 +func TestHTTPClientSetBlockPrivateNetworks(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("ok")) + })) + defer srv.Close() + + c := utils.NewHTTPClient() + defer c.Close() + + // 开启前放行 + if _, err := c.Get(srv.URL, nil); err != nil { + t.Fatalf("before enabling guard, GET should succeed, got %v", err) + } + // 开启后拒绝 + c.SetBlockPrivateNetworks(true) + if _, err := c.Get(srv.URL, nil); !errors.Is(err, utils.ErrSSRFBlocked) { + t.Errorf("after enabling guard, err = %v, want ErrSSRFBlocked", err) + } +} + +func TestHTTPClientUploadStreamsMultipartBody(t *testing.T) { + tmp := t.TempDir() + filePath := filepath.Join(tmp, "payload.txt") + if err := os.WriteFile(filePath, []byte("streamed payload"), 0644); err != nil { + t.Fatalf("write temp payload: %v", err) + } + + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.ContentLength != -1 { + t.Errorf("ContentLength = %d, want -1 for streaming upload", r.ContentLength) + } + if err := r.ParseMultipartForm(1024); err != nil { + t.Fatalf("ParseMultipartForm: %v", err) + } + if got := r.FormValue("kind"); got != "test" { + t.Errorf("form field kind = %q, want test", got) + } + file, _, err := r.FormFile("file") + if err != nil { + t.Fatalf("FormFile: %v", err) + } + defer file.Close() + data, err := io.ReadAll(file) + if err != nil { + t.Fatalf("read uploaded file: %v", err) + } + if string(data) != "streamed payload" { + t.Errorf("uploaded data = %q", string(data)) + } + _, _ = w.Write([]byte("ok")) + })) + defer srv.Close() + + c := utils.NewHTTPClient() + defer c.Close() + body, err := c.Upload(srv.URL, []utils.UploadFile{{FieldName: "file", FilePath: filePath}}, map[string]string{"kind": "test"}) + if err != nil { + t.Fatalf("Upload: %v", err) + } + if string(body) != "ok" { + t.Errorf("body = %q, want ok", string(body)) + } +} diff --git a/utils/random.go b/utils/random.go new file mode 100644 index 0000000..fe6e0ea --- /dev/null +++ b/utils/random.go @@ -0,0 +1,141 @@ +package utils + +import ( + "crypto/rand" + "errors" + "math/big" + mrand "math/rand" + "sync" + "time" +) + +// 本文件提供两类随机数： +// - 密码学安全（RandStringSecure/RandDigitSecure/RandIntSecure/RandInt64Secure）：基于 +// crypto/rand，不可预测，适用于 token/OTP/重置码/会话 ID/安全 nonce 范围等。 +// - 非密码学（RandInt/RandInt64）：基于 math/rand + sync.Pool，高性能但可预测， +// 仅用于非安全场景（负载均衡、游戏、A/B 分桶等）。 +// +// 注意（H1 收紧）：RandString/RandDigit 已移除——字符串随机的用途几乎都是安全场景 +// （token/ID/验证码），保留 math/rand 版本会诱导误用。请用 RandStringSecure/RandDigitSecure。 + +var ( + // #nosec G404 -- math/rand 用于 RandInt/RandInt64 等非密码学函数（性能优先，仅非安全场景： + // 负载均衡、游戏、A/B 分桶等）。安全场景（token/OTP/重置码）用 RandStringSecure/RandDigitSecure。 + randPool = sync.Pool{ + New: func() any { + return mrand.New(mrand.NewSource(time.Now().UnixNano())) + }, + } +) + +const ( + letterBytes = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ" + digitBytes = "0123456789" +) + +// ErrRandInvalidLength 长度过大（超过 1<<20，保护熵池）。n<=0 时返回空串而非此错误。 +var ErrRandInvalidLength = errors.New("invalid random length") + +// RandInt 返回 [min, max) 范围内的随机整数。min==max 时返回 min；max1<<20）返回错误避免过度消耗熵池。 +func RandStringSecure(n int) (string, error) { + if n <= 0 { + return "", nil + } + if n > 1<<20 { + return "", ErrRandInvalidLength + } + b := make([]byte, n) + for i := range b { + idx, err := rand.Int(rand.Reader, big.NewInt(int64(len(letterBytes)))) + if err != nil { + return "", err + } + b[i] = letterBytes[idx.Int64()] + } + return string(b), nil +} + +// RandDigitSecure 生成指定长度的密码学安全随机数字字符串。 +// 基于 crypto/rand，不可预测，适用于 OTP 验证码、密码重置码等安全场景。 +// n<=0 返回空，n 过大（>1<<20）返回错误。 +func RandDigitSecure(n int) (string, error) { + if n <= 0 { + return "", nil + } + if n > 1<<20 { + return "", ErrRandInvalidLength + } + b := make([]byte, n) + for i := range b { + idx, err := rand.Int(rand.Reader, big.NewInt(int64(len(digitBytes)))) + if err != nil { + return "", err + } + b[i] = digitBytes[idx.Int64()] + } + return string(b), nil +} + +// RandIntSecure 返回 [min, max) 范围内的密码学安全随机整数。 +// 基于 crypto/rand + big.Int 拒绝采样（无偏），适用于安全 nonce 范围、防猜抽奖、密钥分桶等。 +// min==max 返回 min；max 0; { + r, size := utf8.DecodeLastRuneInString(s[:i]) + if !f(r) { + return s[:i] + } + i -= size + } + return "" +} + +// Substr 截取子字符串（按 Unicode 字符计数）。 +// start 支持负数（从末尾计算）；start 越界或 length<=0 返回空串；length 超出末尾自动截断。 +// 参数: start 起始位置（支持负数从末尾计算），length 截取长度 +func Substr(s string, start, length int) string { + runes := []rune(s) + lenRunes := len(runes) + + if lenRunes == 0 { + return "" + } + + // 处理负数起始位置 + if start < 0 { + start = lenRunes + start + } + if start < 0 { + start = 0 + } + if start >= lenRunes { + return "" + } + + end := start + length + if end > lenRunes { + end = lenRunes + } + if end <= start { + return "" + } + + return string(runes[start:end]) +} + +// StrLen 获取字符串的 Unicode 字符数 +func StrLen(s string) int { + return utf8.RuneCountInString(s) +} + +// EqualsIgnoreCase 不区分大小写比较字符串。 +// +// L-C 修复：改用 strings.EqualFold（标准库 Unicode 大小写折叠）。原实现仅做 ASCII +// 字节级折叠（'A'-'Z' → +32），对非 ASCII 字符（如 "É" vs "é"）误判为不等。 +// EqualFold 同时更快（无逐字节循环开销）。 +func EqualsIgnoreCase(a, b string) bool { + return strings.EqualFold(a, b) +} diff --git a/utils/url.go b/utils/url.go new file mode 100644 index 0000000..71aa07c --- /dev/null +++ b/utils/url.go @@ -0,0 +1,83 @@ +package utils + +import ( + "net/url" +) + +// URLBuilder URL 构建器 +type URLBuilder struct { + u *url.URL + query url.Values +} + +// ParseURL 解析 URL 字符串 +func ParseURL(rawURL string) (*URLBuilder, error) { + u, err := url.Parse(rawURL) + if err != nil { + return nil, err + } + return &URLBuilder{ + u: u, + query: u.Query(), + }, nil +} + +// AddQuery 添加单个查询参数 +func (b *URLBuilder) AddQuery(key, value string) *URLBuilder { + b.query.Add(key, value) + return b +} + +// AddQueries 批量添加查询参数（追加，同 key 多值共存，M2 修复：原实现用 Set 会覆盖）。 +// params 为 nil 时无操作（遍历 nil map 安全，不 panic）。 +func (b *URLBuilder) AddQueries(params map[string]string) *URLBuilder { + for k, v := range params { + b.query.Add(k, v) + } + return b +} + +// SetQuery 设置查询参数（覆盖同名参数） +func (b *URLBuilder) SetQuery(key, value string) *URLBuilder { + b.query.Set(key, value) + return b +} + +// SetPath 设置路径 +func (b *URLBuilder) SetPath(path string) *URLBuilder { + b.u.Path = path + return b +} + +// SetScheme 设置协议（http/https） +func (b *URLBuilder) SetScheme(scheme string) *URLBuilder { + b.u.Scheme = scheme + return b +} + +// SetHost 设置主机 +func (b *URLBuilder) SetHost(host string) *URLBuilder { + b.u.Host = host + return b +} + +// Build 构建最终的 URL +func (b *URLBuilder) Build() *url.URL { + b.u.RawQuery = b.query.Encode() + return b.u +} + +// String 返回 URL 字符串 +func (b *URLBuilder) String() string { + return b.Build().String() +} + +// URLEncode URL 编码 +func URLEncode(s string) string { + return url.QueryEscape(s) +} + +// URLDecode URL 解码 +func URLDecode(s string) (string, error) { + return url.QueryUnescape(s) +} diff --git a/utils/utils_test.go b/utils/utils_test.go new file mode 100644 index 0000000..9f000a4 --- /dev/null +++ b/utils/utils_test.go @@ -0,0 +1,862 @@ +package utils_test + +import ( + "os" + "path/filepath" + "testing" + "time" + + "github.com/EthanCodeCraft/xlgo-core/utils" +) + +// ===== Random Tests ===== +// +// 注意（H1 收紧）：RandString/RandDigit 已移除（字符串随机的用途几乎都是安全场景， +// 保留 math/rand 版本会诱导误用）。测试覆盖 RandStringSecure/RandDigitSecure（crypto/rand） +// 与 RandInt/RandInt64（非安全范围随机）。 + +func TestRandInt(t *testing.T) { + // 正常范围 + for i := 0; i < 100; i++ { + r := utils.RandInt(1, 100) + if r < 1 || r >= 100 { + t.Errorf("RandInt(1, 100) = %d, out of range", r) + } + } + + // min == max + r := utils.RandInt(5, 5) + if r != 5 { + t.Errorf("RandInt(5, 5) = %d", r) + } + + // min > max (自动交换) + r = utils.RandInt(100, 1) + if r < 1 || r >= 100 { + t.Errorf("RandInt(100, 1) = %d, should swap", r) + } +} + +func TestRandInt64(t *testing.T) { + r := utils.RandInt64(0, 1000000) + if r < 0 || r >= 1000000 { + t.Errorf("RandInt64 out of range: %d", r) + } +} + +// ===== String Tests ===== + +func TestIsBlank(t *testing.T) { + tests := []struct { + input string + expected bool + }{ + {"", true}, + {" ", true}, + {"\t\n", true}, + {"abc", false}, + {" abc ", false}, + } + + for _, tt := range tests { + if utils.IsBlank(tt.input) != tt.expected { + t.Errorf("IsBlank(%q) = %v, want %v", tt.input, !tt.expected, tt.expected) + } + } +} + +func TestIsAnyBlank(t *testing.T) { + if !utils.IsAnyBlank("", "a") { + t.Error("IsAnyBlank should return true") + } + if utils.IsAnyBlank("a", "b") { + t.Error("IsAnyBlank should return false") + } +} + +func TestIsAllBlank(t *testing.T) { + if !utils.IsAllBlank("", " ", "\t") { + t.Error("IsAllBlank should return true") + } + if utils.IsAllBlank("", "a") { + t.Error("IsAllBlank should return false") + } +} + +func TestDefaultIfBlank(t *testing.T) { + if utils.DefaultIfBlank("", "def") != "def" { + t.Error("DefaultIfBlank empty failed") + } + if utils.DefaultIfBlank("val", "def") != "val" { + t.Error("DefaultIfBlank non-empty failed") + } +} + +func TestSubstr(t *testing.T) { + tests := []struct { + input string + start int + length int + expected string + }{ + {"hello世界", 0, 7, "hello世界"}, + {"hello世界", 0, 5, "hello"}, + {"hello世界", 5, 2, "世界"}, + {"hello世界", -2, 2, "世界"}, + {"hello世界", 100, 2, ""}, + {"", 0, 5, ""}, + } + + for _, tt := range tests { + result := utils.Substr(tt.input, tt.start, tt.length) + if result != tt.expected { + t.Errorf("Substr(%q, %d, %d) = %q, want %q", tt.input, tt.start, tt.length, result, tt.expected) + } + } +} + +func TestStrLen(t *testing.T) { + if utils.StrLen("hello世界") != 7 { + t.Error("StrLen Unicode count failed") + } + if utils.StrLen("") != 0 { + t.Error("StrLen empty failed") + } +} + +func TestEqualsIgnoreCase(t *testing.T) { + tests := []struct { + a, b string + expected bool + }{ + {"ABC", "abc", true}, + {"Hello", "HELLO", true}, + {"abc", "abc", true}, + {"abc", "abd", false}, + {"ab", "abc", false}, + } + + for _, tt := range tests { + if utils.EqualsIgnoreCase(tt.a, tt.b) != tt.expected { + t.Errorf("EqualsIgnoreCase(%q, %q) failed", tt.a, tt.b) + } + } +} + +func TestTrim(t *testing.T) { + if utils.Trim(" hello ") != "hello" { + t.Error("Trim failed") + } + if utils.Trim("\t\nhello\n\t") != "hello" { + t.Error("Trim whitespace failed") + } +} + +// ===== DateTime Tests ===== + +func TestNowUnix(t *testing.T) { + n := utils.NowUnix() + if n == 0 { + t.Error("NowUnix returned 0") + } + // 应接近当前时间 + expected := time.Now().Unix() + if n < expected-1 || n > expected+1 { + t.Errorf("NowUnix = %d, expected ~%d", n, expected) + } +} + +func TestNowTimestamp(t *testing.T) { + n := utils.NowTimestamp() + if n == 0 { + t.Error("NowTimestamp returned 0") + } +} + +func TestFromUnix(t *testing.T) { + now := time.Now() + unix := now.Unix() + result := utils.FromUnix(unix) + if result.Unix() != unix { + t.Errorf("FromUnix mismatch") + } +} + +func TestFormatDateTime(t *testing.T) { + now := time.Now() + s := utils.FormatDateTime(now) + if len(s) != 19 { + t.Errorf("FormatDateTime length = %d", len(s)) + } +} + +func TestFormatDate(t *testing.T) { + now := time.Now() + s := utils.FormatDate(now) + if len(s) != 10 { + t.Errorf("FormatDate length = %d", len(s)) + } +} + +func TestStartEndOfDay(t *testing.T) { + now := time.Now() + start := utils.StartOfDay(now) + end := utils.EndOfDay(now) + + if start.Hour() != 0 || start.Minute() != 0 || start.Second() != 0 { + t.Error("StartOfDay not at 00:00:00") + } + if end.Hour() != 23 || end.Minute() != 59 || end.Second() != 59 { + t.Error("EndOfDay not at 23:59:59") + } +} + +func TestStartEndOfMonth(t *testing.T) { + now := time.Now() + start := utils.StartOfMonth(now) + end := utils.EndOfMonth(now) + + if start.Day() != 1 { + t.Error("StartOfMonth day != 1") + } + if end.Day() < 28 || end.Day() > 31 { + t.Errorf("EndOfMonth day = %d, unexpected", end.Day()) + } +} + +func TestGetDateInt(t *testing.T) { + now := time.Now() + dateInt := utils.GetDateInt(now) + expected := now.Year()*10000 + int(now.Month())*100 + now.Day() + if dateInt != expected { + t.Errorf("GetDateInt = %d, expected %d", dateInt, expected) + } +} + +func TestParseDateInt(t *testing.T) { + dateInt := 20260430 + result := utils.ParseDateInt(dateInt) + if result.Year() != 2026 || result.Month() != 4 || result.Day() != 30 { + t.Errorf("ParseDateInt(%d) = %v", dateInt, result) + } +} + +// ===== Convert Tests ===== + +func TestToInt(t *testing.T) { + if utils.ToInt("123") != 123 { + t.Error("ToInt failed") + } + if utils.ToInt("abc") != 0 { + t.Error("ToInt invalid should return 0") + } +} + +func TestToIntDefault(t *testing.T) { + if utils.ToIntDefault("123", 999) != 123 { + t.Error("ToIntDefault valid failed") + } + if utils.ToIntDefault("abc", 999) != 999 { + t.Error("ToIntDefault invalid should return default") + } +} + +func TestToIntE(t *testing.T) { + n, err := utils.ToIntE("123") + if err != nil || n != 123 { + t.Fatalf("ToIntE valid = %d, err=%v; want 123,nil", n, err) + } + if _, err := utils.ToIntE("abc"); err == nil { + t.Fatal("ToIntE invalid should return error") + } +} + +func TestToInt64(t *testing.T) { + if utils.ToInt64("1234567890123") != 1234567890123 { + t.Error("ToInt64 failed") + } +} + +func TestToInt64E(t *testing.T) { + n, err := utils.ToInt64E("1234567890123") + if err != nil || n != 1234567890123 { + t.Fatalf("ToInt64E valid = %d, err=%v; want 1234567890123,nil", n, err) + } + if _, err := utils.ToInt64E("abc"); err == nil { + t.Fatal("ToInt64E invalid should return error") + } +} + +func TestToInt64Default(t *testing.T) { + if utils.ToInt64Default("abc", 999) != 999 { + t.Error("ToInt64Default failed") + } +} + +func TestToUint64Default(t *testing.T) { + if utils.ToUint64Default("abc", 999) != 999 { + t.Error("ToUint64Default failed") + } + if utils.ToUint64Default("123", 0) != 123 { + t.Error("ToUint64Default valid failed") + } +} + +func TestToFloat64(t *testing.T) { + if utils.ToFloat64("3.14") != 3.14 { + t.Error("ToFloat64 failed") + } +} + +func TestToFloat64Default(t *testing.T) { + if utils.ToFloat64Default("abc", 1.5) != 1.5 { + t.Error("ToFloat64Default failed") + } +} + +func TestToString(t *testing.T) { + if utils.ToString(123) != "123" { + t.Error("ToString failed") + } +} + +func TestToString64(t *testing.T) { + if utils.ToString64(1234567890123) != "1234567890123" { + t.Error("ToString64 failed") + } +} + +func TestCalcPageCount(t *testing.T) { + tests := []struct { + total int64 + pageSize int64 + expected int64 + }{ + {100, 10, 10}, + {95, 10, 10}, + {0, 10, 0}, + {100, 0, 0}, + {1, 10, 1}, + } + + for _, tt := range tests { + result := utils.CalcPageCount(tt.total, tt.pageSize) + if result != tt.expected { + t.Errorf("CalcPageCount(%d, %d) = %d, want %d", tt.total, tt.pageSize, result, tt.expected) + } + } +} + +func TestCalcOffset(t *testing.T) { + tests := []struct { + page int + pageSize int + expected int + }{ + {1, 20, 0}, + {2, 20, 20}, + {3, 10, 20}, + {0, 20, 0}, // page <= 0 自动修正为 1 + {1, 0, 0}, // pageSize <= 0 自动修正为 20 + } + + for _, tt := range tests { + result := utils.CalcOffset(tt.page, tt.pageSize) + if result != tt.expected { + t.Errorf("CalcOffset(%d, %d) = %d, want %d", tt.page, tt.pageSize, result, tt.expected) + } + } +} + +func TestAppendFileAndCopyFile(t *testing.T) { + tmp := t.TempDir() + src := filepath.Join(tmp, "src.txt") + dst := filepath.Join(tmp, "nested", "dst.txt") + + if err := utils.AppendFile(src, []byte("hello")); err != nil { + t.Fatalf("AppendFile first write: %v", err) + } + if err := utils.AppendFile(src, []byte(" world")); err != nil { + t.Fatalf("AppendFile second write: %v", err) + } + if err := utils.CopyFile(dst, src); err != nil { + t.Fatalf("CopyFile: %v", err) + } + + data, err := os.ReadFile(dst) + if err != nil { + t.Fatalf("ReadFile copied file: %v", err) + } + if string(data) != "hello world" { + t.Errorf("copied data = %q, want hello world", string(data)) + } +} + +// ===== Validator Tests ===== + +func TestIsPhone(t *testing.T) { + valid := []string{"13812345678", "15912345678", "18812345678"} + invalid := []string{"12345678901", "1381234567", "138123456789"} + + for _, p := range valid { + if !utils.IsPhone(p) { + t.Errorf("IsPhone(%s) should be true", p) + } + } + for _, p := range invalid { + if utils.IsPhone(p) { + t.Errorf("IsPhone(%s) should be false", p) + } + } +} + +func TestIsEmail(t *testing.T) { + valid := []string{"test@example.com", "user.name@domain.cn"} + invalid := []string{"invalid", "no@", "@nodomain.com"} + + for _, e := range valid { + if !utils.IsEmail(e) { + t.Errorf("IsEmail(%s) should be true", e) + } + } + for _, e := range invalid { + if utils.IsEmail(e) { + t.Errorf("IsEmail(%s) should be false", e) + } + } +} + +func TestIsIPv4(t *testing.T) { + valid := []string{"192.168.1.1", "0.0.0.0", "255.255.255.255"} + invalid := []string{"256.1.1.1", "1.1.1", "1.1.1.1.1"} + + for _, ip := range valid { + if !utils.IsIPv4(ip) { + t.Errorf("IsIPv4(%s) should be true", ip) + } + } + for _, ip := range invalid { + if utils.IsIPv4(ip) { + t.Errorf("IsIPv4(%s) should be false", ip) + } + } +} + +func TestIsIDCard(t *testing.T) { + // 18位身份证 + if !utils.IsIDCard("11010519900307293X") { + t.Error("IsIDCard valid 18-digit failed") + } + // 无效 + if utils.IsIDCard("123456789012345") { + t.Error("IsIDCard invalid should be false") + } +} + +func TestIsChinese(t *testing.T) { + if !utils.IsChinese("中文") { + t.Error("IsChinese should be true") + } + if utils.IsChinese("abc中文") { + t.Error("IsChinese mixed should be false") + } +} + +func TestIsNumeric(t *testing.T) { + if !utils.IsNumeric("12345") { + t.Error("IsNumeric should be true") + } + if utils.IsNumeric("123a") { + t.Error("IsNumeric should be false") + } +} + +func TestIsAlphanumeric(t *testing.T) { + if !utils.IsAlphanumeric("abc123") { + t.Error("IsAlphanumeric should be true") + } + if utils.IsAlphanumeric("abc-123") { + t.Error("IsAlphanumeric with dash should be false") + } +} + +// ===== Crypto Tests ===== + +func TestMD5(t *testing.T) { + if utils.MD5("hello") != "5d41402abc4b2a76b9719d911017c592" { + t.Error("MD5 failed") + } + if utils.MD5("") != "d41d8cd98f00b204e9800998ecf8427e" { + t.Error("MD5 empty failed") + } +} + +func TestSHA256(t *testing.T) { + // SHA256 有固定长度 + hash := utils.SHA256("hello") + if len(hash) != 64 { + t.Errorf("SHA256 length = %d", len(hash)) + } +} + +func TestBase64(t *testing.T) { + original := "hello world" + encoded := utils.Base64Encode([]byte(original)) + decoded, err := utils.Base64Decode(encoded) + if err != nil { + t.Errorf("Base64Decode error: %v", err) + } + if string(decoded) != original { + t.Errorf("Base64 roundtrip failed: %s", decoded) + } +} + +func TestBase64URL(t *testing.T) { + original := "hello+world" + encoded := utils.Base64URLEncode([]byte(original)) + decoded, err := utils.Base64URLDecode(encoded) + if err != nil { + t.Errorf("Base64URLDecode error: %v", err) + } + if string(decoded) != original { + t.Errorf("Base64URL roundtrip failed") + } +} + +// ===== UUID Tests ===== + +func TestUUID(t *testing.T) { + uuid := utils.UUID() + if len(uuid) != 36 { + t.Errorf("UUID length = %d", len(uuid)) + } + // 格式检查: 8-4-4-4-12 + if uuid[8] != '-' || uuid[13] != '-' || uuid[18] != '-' || uuid[23] != '-' { + t.Errorf("UUID format invalid: %s", uuid) + } +} + +func TestUUIDShort(t *testing.T) { + uuid := utils.UUIDShort() + if len(uuid) != 32 { + t.Errorf("UUIDShort length = %d", len(uuid)) + } + // U1 回归：确保无破折号 + if uuid[8] == '-' || uuid[12] == '-' || uuid[16] == '-' || uuid[20] == '-' { + t.Errorf("UUIDShort contains dashes at unexpected positions: %s", uuid) + } +} + +func TestUUIDShort_NoDashes(t *testing.T) { + // U1 回归：100 次生成全部不含破折号，长度精确 32 + for range 100 { + s := utils.UUIDShort() + if len(s) != 32 { + t.Fatalf("UUIDShort length = %d, want 32", len(s)) + } + for j, c := range s { + if c == '-' { + t.Fatalf("UUIDShort contains dash at position %d: %s", j, s) + } + if !((c >= '0' && c <= '9') || (c >= 'a' && c <= 'f')) { + t.Fatalf("UUIDShort non-hex char at position %d: %c in %s", j, c, s) + } + } + } +} + +func TestUUIDValid(t *testing.T) { + valid := "550e8400-e29b-41d4-a716-446655440000" + invalid := "invalid-uuid" + + if !utils.UUIDValid(valid) { + t.Errorf("UUIDValid(%s) should be true", valid) + } + if utils.UUIDValid(invalid) { + t.Errorf("UUIDValid(%s) should be false", invalid) + } +} + +// ===== URL Tests ===== + +func TestURLEncodeDecode(t *testing.T) { + original := "hello world" + encoded := utils.URLEncode(original) + decoded, err := utils.URLDecode(encoded) + if err != nil { + t.Errorf("URLDecode error: %v", err) + } + if decoded != original { + t.Errorf("URL roundtrip failed: %s -> %s -> %s", original, encoded, decoded) + } +} + +func TestParseURL(t *testing.T) { + b, err := utils.ParseURL("https://example.com/path") + if err != nil { + t.Errorf("ParseURL error: %v", err) + } + result := b.AddQuery("key", "value").AddQuery("foo", "bar").String() + if !contains(result, "key=value") || !contains(result, "foo=bar") { + t.Errorf("URLBuilder result: %s", result) + } +} + +func contains(s, sub string) bool { + return len(s) >= len(sub) && (s == sub || len(s) > 0 && containsHelper(s, sub)) +} + +func containsHelper(s, sub string) bool { + for i := 0; i <= len(s)-len(sub); i++ { + if s[i:i+len(sub)] == sub { + return true + } + } + return false +} + +// ===== File Tests ===== + +func TestFileExists(t *testing.T) { + if utils.FileExists("/nonexistent/path") { + t.Error("FileExists should return false for nonexistent") + } +} + +func TestDirExists(t *testing.T) { + if utils.DirExists("/nonexistent/dir") { + t.Error("DirExists should return false") + } +} + +// ===== Secure Random Tests（H1：crypto/rand 安全版本） ===== + +// 回归 H1：RandStringSecure 生成正确长度、仅含字母数字。 +func TestRandStringSecure(t *testing.T) { + tests := []struct { + name string + length int + }{ + {"normal", 16}, + {"short", 1}, + {"long", 100}, + {"zero", 0}, + {"negative", -1}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + s, err := utils.RandStringSecure(tt.length) + if err != nil { + t.Fatalf("RandStringSecure(%d) err: %v", tt.length, err) + } + if tt.length <= 0 { + if s != "" { + t.Errorf("RandStringSecure(%d) should return empty", tt.length) + } + return + } + if len(s) != tt.length { + t.Errorf("RandStringSecure(%d) length = %d", tt.length, len(s)) + } + for _, c := range s { + if !((c >= '0' && c <= '9') || (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')) { + t.Errorf("RandStringSecure contains invalid char: %c", c) + } + } + }) + } +} + +// 回归 H1：RandStringSecure 唯一性——crypto/rand 不可预测，大批量无重复。 +// 对比 RandString（math/rand）偶发重复（H1 征兆）。 +func TestRandStringSecureUniqueness(t *testing.T) { + results := make(map[string]bool, 1000) + for i := 0; i < 1000; i++ { + s, err := utils.RandStringSecure(16) + if err != nil { + t.Fatalf("RandStringSecure err: %v", err) + } + if results[s] { + t.Fatalf("RandStringSecure generated duplicate at i=%d: %q (H1: crypto/rand must be unique)", i, s) + } + results[s] = true + } +} + +// 回归 H1：RandDigitSecure 生成正确长度、仅含数字（用于 OTP）。 +func TestRandDigitSecure(t *testing.T) { + s, err := utils.RandDigitSecure(6) + if err != nil { + t.Fatalf("RandDigitSecure err: %v", err) + } + if len(s) != 6 { + t.Fatalf("RandDigitSecure length = %d, want 6", len(s)) + } + for _, c := range s { + if c < '0' || c > '9' { + t.Errorf("RandDigitSecure contains non-digit: %c", c) + } + } +} + +// 回归 H1：RandDigitSecure 唯一性——6 位 OTP 大批量重复率应在合理范围。 +// 6 位数字空间 10^6，1000 个样本重复概率极低（生日攻击 ~0.0005），crypto/rand 下应无重复。 +func TestRandDigitSecureUniqueness(t *testing.T) { + results := make(map[string]bool, 1000) + for i := 0; i < 1000; i++ { + s, err := utils.RandDigitSecure(6) + if err != nil { + t.Fatalf("RandDigitSecure err: %v", err) + } + if results[s] { + // 6 位空间小，理论上有极小概率生日碰撞；若发生则记录但不直接失败， + // 用更长的码验证。此处改用 8 位码重测以排除碰撞。 + t.Logf("RandDigitSecure(6) collision at i=%d (small space), retrying with 8 digits", i) + goto retry8 + } + results[s] = true + } + return +retry8: + results = make(map[string]bool, 1000) + for i := 0; i < 1000; i++ { + s, err := utils.RandDigitSecure(8) + if err != nil { + t.Fatalf("RandDigitSecure(8) err: %v", err) + } + if results[s] { + t.Fatalf("RandDigitSecure(8) generated duplicate at i=%d (H1: crypto/rand must be unique)", i) + } + results[s] = true + } +} + +// 回归 H1：RandStringSecure 过大长度返回错误（保护熵池）。 +func TestRandStringSecureTooLarge(t *testing.T) { + _, err := utils.RandStringSecure(1 << 21) // 2MB，超过 1<<20 上限 + if err != utils.ErrRandInvalidLength { + t.Errorf("RandStringSecure(too large) err = %v, want ErrRandInvalidLength", err) + } + _, err = utils.RandDigitSecure(1 << 21) + if err != utils.ErrRandInvalidLength { + t.Errorf("RandDigitSecure(too large) err = %v, want ErrRandInvalidLength", err) + } +} + +// 回归 H1：RandIntSecure 范围正确、min==max、max= 100 { + t.Errorf("RandIntSecure(1,100) = %d, out of range", n) + } + } + + // min == max + n, err := utils.RandIntSecure(5, 5) + if err != nil || n != 5 { + t.Errorf("RandIntSecure(5,5) = %d, err=%v, want 5", n, err) + } + + // max < min 自动交换 + n, err = utils.RandIntSecure(100, 1) + if err != nil { + t.Fatalf("RandIntSecure(100,1) err: %v", err) + } + if n < 1 || n >= 100 { + t.Errorf("RandIntSecure(100,1) = %d, should swap to [1,100)", n) + } +} + +// 回归 H1：RandInt64Secure 唯一性——crypto/rand 在大空间内分布均匀、不可预测。 +// [0, 1<<40) 取 1000 个，生日攻击重复概率 ~0.0000005，crypto/rand 应无重复。 +func TestRandInt64SecureUniqueness(t *testing.T) { + seen := make(map[int64]bool, 1000) + for i := 0; i < 1000; i++ { + n, err := utils.RandInt64Secure(0, 1<<40) + if err != nil { + t.Fatalf("RandInt64Secure err: %v", err) + } + if seen[n] { + t.Fatalf("RandInt64Secure duplicate at i=%d: %d (H1: crypto/rand must be unique in large range)", i, n) + } + seen[n] = true + } +} + +// 回归 H1：RandInt64Secure 范围正确、min==max、max= 1000000 { + t.Errorf("RandInt64Secure(0,1e6) = %d, out of range", n) + } + } + + // min == max + n, err := utils.RandInt64Secure(7, 7) + if err != nil || n != 7 { + t.Errorf("RandInt64Secure(7,7) = %d, err=%v, want 7", n, err) + } + + // max < min 自动交换 + n, err = utils.RandInt64Secure(1000000, 0) + if err != nil { + t.Fatalf("RandInt64Secure(1e6,0) err: %v", err) + } + if n < 0 || n >= 1000000 { + t.Errorf("RandInt64Secure(1e6,0) = %d, should swap to [0,1e6)", n) + } +} + +// ===== Benchmarks ===== + +func BenchmarkRandStringSecure(b *testing.B) { + for i := 0; i < b.N; i++ { + _, _ = utils.RandStringSecure(16) + } +} + +func BenchmarkRandDigitSecure(b *testing.B) { + for i := 0; i < b.N; i++ { + _, _ = utils.RandDigitSecure(6) + } +} + +func BenchmarkMD5(b *testing.B) { + for i := 0; i < b.N; i++ { + utils.MD5("hello world") + } +} + +func BenchmarkSHA256(b *testing.B) { + for i := 0; i < b.N; i++ { + utils.SHA256("hello world") + } +} + +func BenchmarkUUID(b *testing.B) { + for i := 0; i < b.N; i++ { + utils.UUID() + } +} + +func BenchmarkStrLen(b *testing.B) { + s := "hello世界测试字符串" + for i := 0; i < b.N; i++ { + utils.StrLen(s) + } +} + +func BenchmarkCalcPageCount(b *testing.B) { + for i := 0; i < b.N; i++ { + utils.CalcPageCount(10000, 20) + } +} diff --git a/utils/uuid.go b/utils/uuid.go new file mode 100644 index 0000000..8bb0cfe --- /dev/null +++ b/utils/uuid.go @@ -0,0 +1,28 @@ +package utils + +import ( + "strings" + + "github.com/google/uuid" +) + +// UUID 生成 UUID v4 字符串 +func UUID() string { + return uuid.New().String() +} + +// UUIDShort 生成短 UUID（无横线，32 个十六进制字符） +func UUIDShort() string { + return strings.ReplaceAll(uuid.New().String(), "-", "") +} + +// UUIDParse 解析 UUID 字符串 +func UUIDParse(s string) (uuid.UUID, error) { + return uuid.Parse(s) +} + +// UUIDValid 检查 UUID 字符串是否有效 +func UUIDValid(s string) bool { + _, err := uuid.Parse(s) + return err == nil +} diff --git a/utils/validator.go b/utils/validator.go new file mode 100644 index 0000000..0287316 --- /dev/null +++ b/utils/validator.go @@ -0,0 +1,120 @@ +package utils + +import ( + "regexp" +) + +// L-B 修复：正则预编译到包级变量，避免 IsPhone/IsEmail/IsIPv4/IsIDCard 每次调用 +// regexp.MatchString 重编译（高 QPS 下浪费 CPU）。零行为变化。 +var ( + phoneRE = regexp.MustCompile(`^1[3-9]\d{9}$`) + emailRE = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`) + ipv4RE = regexp.MustCompile(`^(\d{1,3}\.){3}\d{1,3}$`) + idCardRE = regexp.MustCompile(`^\d{6}(19|20)\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])\d{3}[\dXx]$`) +) + +// IsPhone 检查是否为有效的中国大陆手机号 +// 注意: 正则基于当前号段，新号段开放时需更新 +func IsPhone(phone string) bool { + return phoneRE.MatchString(phone) +} + +// IsEmail 检查是否为有效的邮箱地址 +func IsEmail(email string) bool { + return emailRE.MatchString(email) +} + +// IsIPv4 检查是否为有效的 IPv4 地址 +func IsIPv4(ip string) bool { + if !ipv4RE.MatchString(ip) { + return false + } + // 验证每个段在 0-255 范围内 + parts := splitByDot(ip) + for _, part := range parts { + n := ToInt(part) + if n < 0 || n > 255 { + return false + } + } + return true +} + +// IsIDCard 检查是否为有效的中国身份证号（18位） +// 注意: 仅校验格式，不校验校验位 +func IsIDCard(id string) bool { + return idCardRE.MatchString(id) +} + +// IsChinese 检查字符串是否非空且全部为中文字符（CJK 基本区 U+4E00..U+9FFF）。空串返回 false。 +func IsChinese(s string) bool { + for _, r := range s { + if r < 0x4E00 || r > 0x9FFF { + return false + } + } + return len(s) > 0 +} + +// HasChinese 检查字符串是否包含中文字符 +func HasChinese(s string) bool { + for _, r := range s { + if r >= 0x4E00 && r <= 0x9FFF { + return true + } + } + return false +} + +// IsNumeric 检查字符串是否全部为数字 +func IsNumeric(s string) bool { + if len(s) == 0 { + return false + } + for _, r := range s { + if r < '0' || r > '9' { + return false + } + } + return true +} + +// IsAlpha 检查字符串是否全部为字母 +func IsAlpha(s string) bool { + if len(s) == 0 { + return false + } + for _, r := range s { + if (r < 'a' || r > 'z') && (r < 'A' || r > 'Z') { + return false + } + } + return true +} + +// IsAlphanumeric 检查字符串是否全部为字母或数字 +func IsAlphanumeric(s string) bool { + if len(s) == 0 { + return false + } + for _, r := range s { + if (r < 'a' || r > 'z') && (r < 'A' || r > 'Z') && (r < '0' || r > '9') { + return false + } + } + return true +} + +// 内部函数 +func splitByDot(s string) []string { + var result []string + start := 0 + for i := 0; i < len(s); i++ { + if s[i] == '.' { + result = append(result, s[start:i]) + start = i + 1 + } + } + result = append(result, s[start:]) + return result +} diff --git a/validation/hash.go b/validation/hash.go new file mode 100644 index 0000000..274a794 --- /dev/null +++ b/validation/hash.go @@ -0,0 +1,82 @@ +package validation + +import ( + "golang.org/x/crypto/bcrypt" +) + +// defaultCost 是框架默认 bcrypt cost。 +const defaultCost = 12 + +// normalizeHashCost 将 bcrypt cost 归一化到 bcrypt 支持范围内。 +func normalizeHashCost(cost int) int { + if cost < bcrypt.MinCost { + return bcrypt.MinCost + } + if cost > bcrypt.MaxCost { + return bcrypt.MaxCost + } + return cost +} + +// normalizeUpgradeTargetCost 归一化升级目标 cost，异常值回退到框架默认值。 +func normalizeUpgradeTargetCost(cost int) int { + if cost <= 0 || cost > bcrypt.MaxCost { + return defaultCost + } + return normalizeHashCost(cost) +} + +// HashPassword 使用框架默认 cost 哈希明文密码。 +func HashPassword(password string) (string, error) { + return HashPasswordWithCost(password, defaultCost) +} + +// HashPasswordWithCost 使用指定 cost 哈希明文密码。 +// +// 低于 bcrypt.MinCost 的 cost 会提升到 bcrypt.MinCost，高于 bcrypt.MaxCost +// 的 cost 会降到 bcrypt.MaxCost。 +func HashPasswordWithCost(password string, cost int) (string, error) { + cost = normalizeHashCost(cost) + + bytes, err := bcrypt.GenerateFromPassword([]byte(password), cost) + if err != nil { + return "", err + } + return string(bytes), nil +} + +// CheckPassword 校验 hashedPassword 是否匹配明文密码。 +func CheckPassword(hashedPassword, password string) bool { + err := bcrypt.CompareHashAndPassword([]byte(hashedPassword), []byte(password)) + return err == nil +} + +// CheckPasswordAndUpgrade 校验密码，并在存量 hash 的 cost 低于归一化后的目标 cost 时重新哈希。 +func CheckPasswordAndUpgrade(hashedPassword, password string, targetCost int) (match bool, needUpgrade bool, newHash string, err error) { + targetCost = normalizeUpgradeTargetCost(targetCost) + + err = bcrypt.CompareHashAndPassword([]byte(hashedPassword), []byte(password)) + if err != nil { + return false, false, "", err + } + + cost, err := bcrypt.Cost([]byte(hashedPassword)) + if err != nil { + return true, false, "", nil + } + + if cost < targetCost { + newHash, err = HashPasswordWithCost(password, targetCost) + if err != nil { + return true, false, "", err + } + return true, true, newHash, nil + } + + return true, false, "", nil +} + +// GetPasswordCost 返回 hashedPassword 中编码的 bcrypt cost。 +func GetPasswordCost(hashedPassword string) (int, error) { + return bcrypt.Cost([]byte(hashedPassword)) +} diff --git a/validation/password.go b/validation/password.go new file mode 100644 index 0000000..6576aa4 --- /dev/null +++ b/validation/password.go @@ -0,0 +1,89 @@ +package validation + +import ( + "strconv" + "unicode" +) + +// PasswordConfig 密码验证配置 +type PasswordConfig struct { + MinLength int // 最小长度 + MaxLength int // 最大长度 + RequireUpper bool // 需要大写字母 + RequireLower bool // 需要小写字母 + RequireDigit bool // 需要数字 + RequireSpecial bool // 需要特殊字符 +} + +// DefaultPasswordConfig 默认密码配置。 +// +// P1 #17：MaxLength 由 128 收敛到 72（字节）。bcrypt 在 72 字节处静默截断—— +// 若允许更长密码，两个前 72 字节相同的不同密码会被视为同一密码通过认证。 +// length 用 len()（字节）度量，与 bcrypt 的字节截断口径一致。需支持超长密码时， +// 应在哈希前先做 SHA-256 预哈希再交给 bcrypt，而非放宽此上限。 +var DefaultPasswordConfig = PasswordConfig{ + MinLength: 8, // 最少8位 + MaxLength: 72, // 最多72字节（bcrypt 截断边界，见上） + RequireUpper: true, + RequireLower: true, + RequireDigit: true, + RequireSpecial: false, +} + +// ValidatePassword 验证密码强度 +// 返回：是否有效，错误信息 +func ValidatePassword(password string) (bool, string) { + return ValidatePasswordWithConfig(password, DefaultPasswordConfig) +} + +// ValidatePasswordWithConfig 使用指定配置验证密码强度 +func ValidatePasswordWithConfig(password string, config PasswordConfig) (bool, string) { + length := len(password) + + // 检查最小长度 + if length < config.MinLength { + return false, "密码长度不能少于" + strconv.Itoa(config.MinLength) + "位" + } + + // 检查最大长度 + if length > config.MaxLength { + return false, "密码长度不能超过" + strconv.Itoa(config.MaxLength) + "位" + } + + var hasUpper, hasLower, hasDigit, hasSpecial bool + + for _, char := range password { + switch { + case unicode.IsUpper(char): + hasUpper = true + case unicode.IsLower(char): + hasLower = true + case unicode.IsDigit(char): + hasDigit = true + case unicode.IsPunct(char) || unicode.IsSymbol(char): + hasSpecial = true + } + } + + // 检查大写字母 + if config.RequireUpper && !hasUpper { + return false, "密码必须包含大写字母" + } + + // 检查小写字母 + if config.RequireLower && !hasLower { + return false, "密码必须包含小写字母" + } + + // 检查数字 + if config.RequireDigit && !hasDigit { + return false, "密码必须包含数字" + } + + // 检查特殊字符 + if config.RequireSpecial && !hasSpecial { + return false, "密码必须包含特殊字符" + } + + return true, "" +} diff --git a/validation/validation_test.go b/validation/validation_test.go new file mode 100644 index 0000000..4b6a8b3 --- /dev/null +++ b/validation/validation_test.go @@ -0,0 +1,461 @@ +package validation_test + +import ( + "testing" + + "github.com/EthanCodeCraft/xlgo-core/validation" + "golang.org/x/crypto/bcrypt" +) + +// ===== Password Tests ===== + +func TestValidatePassword(t *testing.T) { + tests := []struct { + password string + valid bool + msg string + }{ + {"Abc12345", true, ""}, // 有效 + {"abc12345", false, "密码必须包含大写字母"}, // 缺大写 + {"ABC12345", false, "密码必须包含小写字母"}, // 缺小写 + {"Abcdefgh", false, "密码必须包含数字"}, // 缺数字 + {"Abc123", false, "密码长度不能少于8位"}, // 太短 + {"", false, "密码长度不能少于8位"}, // 空 + } + + for _, tt := range tests { + valid, msg := validation.ValidatePassword(tt.password) + if valid != tt.valid { + t.Errorf("ValidatePassword(%s) valid = %v, want %v", tt.password, valid, tt.valid) + } + if !valid && msg != tt.msg { + t.Errorf("ValidatePassword(%s) msg = %s, want %s", tt.password, msg, tt.msg) + } + } +} + +func TestValidatePasswordWithConfig(t *testing.T) { + // 自定义配置：不要求特殊字符 + config := validation.PasswordConfig{ + MinLength: 6, + MaxLength: 20, + RequireUpper: false, + RequireLower: true, + RequireDigit: true, + RequireSpecial: false, + } + + valid, msg := validation.ValidatePasswordWithConfig("abc123", config) + if !valid { + t.Errorf("ValidatePasswordWithConfig should be valid: %s", msg) + } + + // 要求特殊字符 + config2 := validation.PasswordConfig{ + MinLength: 8, + MaxLength: 20, + RequireUpper: true, + RequireLower: true, + RequireDigit: true, + RequireSpecial: true, + } + + valid2, msg2 := validation.ValidatePasswordWithConfig("Abc12345", config2) + if valid2 { + t.Error("Should require special character") + } + if msg2 != "密码必须包含特殊字符" { + t.Errorf("msg = %s, want '密码必须包含特殊字符'", msg2) + } + + // 包含特殊字符 + valid3, msg3 := validation.ValidatePasswordWithConfig("Abc123!@#", config2) + if !valid3 { + t.Errorf("Should be valid: %s", msg3) + } +} + +func TestDefaultPasswordConfig(t *testing.T) { + cfg := validation.DefaultPasswordConfig + if cfg.MinLength != 8 { + t.Errorf("MinLength = %d, want 8", cfg.MinLength) + } + if cfg.MaxLength != 72 { + t.Errorf("MaxLength = %d, want 72 (P1 #17: bcrypt 72-byte truncation boundary)", cfg.MaxLength) + } + if !cfg.RequireUpper || !cfg.RequireLower || !cfg.RequireDigit { + t.Error("Default config should require upper, lower, digit") + } +} + +// ===== Hash Password Tests ===== + +func TestHashPassword(t *testing.T) { + password := "testPassword123" + + hash, err := validation.HashPassword(password) + if err != nil { + t.Fatalf("HashPassword error: %v", err) + } + + // 验证 hash 不等于原密码 + if hash == password { + t.Error("Hash should not equal original password") + } + + // 验证 hash 非空 + if hash == "" { + t.Error("Hash should not be empty") + } + + // 验证可以匹配 + if !validation.CheckPassword(hash, password) { + t.Error("CheckPassword should return true for correct password") + } + + // 验证错误密码不匹配 + if validation.CheckPassword(hash, "wrongPassword") { + t.Error("CheckPassword should return false for wrong password") + } +} + +func TestHashPasswordWithCost(t *testing.T) { + password := "testPassword123" + + // 测试不同 cost + hash, err := validation.HashPasswordWithCost(password, 10) + if err != nil { + t.Fatalf("HashPasswordWithCost error: %v", err) + } + + cost, err := validation.GetPasswordCost(hash) + if err != nil { + t.Fatalf("GetPasswordCost error: %v", err) + } + if cost != 10 { + t.Errorf("Cost = %d, want 10", cost) + } + + // 测试 cost 边界 + hash2, err := validation.HashPasswordWithCost(password, 3) // 低于 MinCost + if err != nil { + t.Fatalf("HashPasswordWithCost with low cost error: %v", err) + } + cost2, _ := validation.GetPasswordCost(hash2) + if cost2 < bcrypt.MinCost { + t.Errorf("Cost should be at least MinCost") + } +} + +func TestCheckPasswordAndUpgrade(t *testing.T) { + password := "testPassword123" + + // 使用低 cost 创建 hash + hash, _ := validation.HashPasswordWithCost(password, 4) + + // 检查并尝试升级 + match, needUpgrade, newHash, err := validation.CheckPasswordAndUpgrade(hash, password, 12) + if err != nil { + t.Fatalf("CheckPasswordAndUpgrade error: %v", err) + } + + if !match { + t.Error("Password should match") + } + + if !needUpgrade { + t.Error("Should need upgrade (cost 4 -> 12)") + } + + if newHash == "" { + t.Error("New hash should be provided") + } + + // 验证新 hash 可用 + if !validation.CheckPassword(newHash, password) { + t.Error("New hash should work") + } + + // 使用高 cost，不需要升级 + hash2, _ := validation.HashPasswordWithCost(password, 12) + match2, needUpgrade2, _, _ := validation.CheckPasswordAndUpgrade(hash2, password, 12) + if !match2 { + t.Error("Password should match") + } + if needUpgrade2 { + t.Error("Should not need upgrade") + } + + // 错误密码 + match3, _, _, _ := validation.CheckPasswordAndUpgrade(hash, "wrongPassword", 12) + if match3 { + t.Error("Wrong password should not match") + } +} + +func TestCheckPasswordAndUpgradeNormalizesInvalidTargetCost(t *testing.T) { + password := "testPassword123" + hash, err := validation.HashPasswordWithCost(password, 12) + if err != nil { + t.Fatalf("HashPasswordWithCost: %v", err) + } + + match, needUpgrade, newHash, err := validation.CheckPasswordAndUpgrade(hash, password, bcrypt.MaxCost+1) + if err != nil { + t.Fatalf("CheckPasswordAndUpgrade with high target cost: %v", err) + } + if !match { + t.Fatal("Password should match") + } + if needUpgrade || newHash != "" { + t.Fatalf("invalid high target cost should normalize to default and avoid upgrade, needUpgrade=%v newHash=%q", needUpgrade, newHash) + } +} + +func TestGetPasswordCost(t *testing.T) { + password := "testPassword123" + hash, _ := validation.HashPasswordWithCost(password, 12) + + cost, err := validation.GetPasswordCost(hash) + if err != nil { + t.Fatalf("GetPasswordCost error: %v", err) + } + if cost != 12 { + t.Errorf("Cost = %d, want 12", cost) + } + + // 无效 hash + _, err = validation.GetPasswordCost("invalidHash") + if err == nil { + t.Error("GetPasswordCost should fail with invalid hash") + } +} + +// ===== Validation Errors Tests ===== + +func TestValidationErrors(t *testing.T) { + errors := validation.ValidationErrors{ + {Field: "name", Label: "姓名", Message: "必填"}, + {Field: "email", Label: "邮箱", Message: "格式错误"}, + } + + // Error 方法 + errStr := errors.Error() + if errStr != "姓名: 必填; 邮箱: 格式错误" { + t.Errorf("Error() = %s", errStr) + } + + // ToMap 方法 + m := errors.ToMap() + if m["name"] != "必填" { + t.Error("ToMap failed") + } + + // ToLabelMap 方法 + lm := errors.ToLabelMap() + if lm["姓名"] != "必填" { + t.Error("ToLabelMap failed") + } + + // First 方法 + first := errors.First() + if first.Field != "name" { + t.Error("First failed") + } + + // FirstMessage 方法 + msg := errors.FirstMessage() + if msg != "必填" { + t.Errorf("FirstMessage = %s", msg) + } + + // 空 errors + emptyErrors := validation.ValidationErrors{} + if emptyErrors.First() != nil { + t.Error("Empty First should return nil") + } + if emptyErrors.FirstMessage() != "" { + t.Error("Empty FirstMessage should return empty") + } +} + +// ===== Struct Validation Tests ===== + +type TestUser struct { + Name string `json:"name" label:"姓名" binding:"required" msg_required:"姓名不能为空"` + Email string `json:"email" label:"邮箱" binding:"required,email" msg_required:"邮箱不能为空" msg_email:"邮箱格式不正确"` + Age int `json:"age" label:"年龄" binding:"gte=0,lte=150"` + Password string `json:"password" binding:"min=8" msg_min:"密码至少8位"` +} + +func TestValidateStruct(t *testing.T) { + validation.InitValidator() + + // 有效数据 + validUser := TestUser{ + Name: "张三", + Email: "test@example.com", + Age: 25, + Password: "password123", + } + + errors := validation.ValidateStruct(validUser) + if errors != nil { + t.Errorf("Valid struct should have no errors: %v", errors) + } + + // 无效数据 + invalidUser := TestUser{ + Name: "", + Email: "invalid-email", + Age: 200, + Password: "short", + } + + errors2 := validation.ValidateStruct(invalidUser) + if errors2 == nil { + t.Error("Invalid struct should have errors") + } + + // 检查错误数量 + if len(errors2) < 3 { + t.Errorf("Should have at least 3 errors, got %d", len(errors2)) + } + + // 检查自定义消息 + firstMsg := errors2.FirstMessage() + if firstMsg != "姓名不能为空" { + t.Errorf("FirstMessage = %s, want '姓名不能为空'", firstMsg) + } +} + +func TestValidateStructNil(t *testing.T) { + if errors := validation.ValidateStruct(nil); errors != nil { + t.Fatalf("ValidateStruct(nil) = %v, want nil", errors) + } + + // 空结构体 + emptyUser := TestUser{} + errors := validation.ValidateStruct(emptyUser) + if errors == nil { + t.Error("Empty struct should have errors") + } +} + +type TestPhone struct { + Phone string `json:"phone" binding:"phone" msg_phone:"手机号格式不正确"` +} + +func TestValidatePhone(t *testing.T) { + validation.InitValidator() + + // 有效手机号 + valid := TestPhone{Phone: "13812345678"} + errors := validation.ValidateStruct(valid) + if errors != nil { + t.Errorf("Valid phone should pass: %v", errors) + } + + // 无效手机号 - 长度错误 + invalidLen := TestPhone{Phone: "1234567"} + errors2 := validation.ValidateStruct(invalidLen) + if errors2 == nil { + t.Error("Invalid phone length should fail") + } + + // 无效手机号 - 不以1开头 + invalidPrefix := TestPhone{Phone: "23812345678"} + errors3 := validation.ValidateStruct(invalidPrefix) + if errors3 == nil { + t.Error("Phone not starting with 1 should fail") + } + + // P1 #17：长度合规、以 1 开头但含非数字字符必须拒绝（原实现会误通过）。 + invalidNonDigit := TestPhone{Phone: "1abcdefghij"} + if errs := validation.ValidateStruct(invalidNonDigit); errs == nil { + t.Error("Phone with non-digit chars should fail (P1 #17)") + } +} + +type TestUsername struct { + Username string `json:"username" binding:"username" msg_username:"用户名格式不正确"` +} + +func TestValidateUsername(t *testing.T) { + validation.InitValidator() + + tests := []struct { + username string + valid bool + }{ + {"abc123", true}, // 有效 + {"Abc123", true}, // 有效（大写开头） + {"user_name", true}, // 有效（包含下划线） + {"123abc", false}, // 无效（数字开头） + {"ab", false}, // 无效（太短） + {"a!bc", false}, // 无效（特殊字符） + } + + for _, tt := range tests { + u := TestUsername{Username: tt.username} + errors := validation.ValidateStruct(u) + valid := errors == nil + if valid != tt.valid { + t.Errorf("Username %s: valid=%v, want %v", tt.username, valid, tt.valid) + } + } +} + +// TestIDCardChecksum_M5：18 位身份证须校验校验位（修复前仅查长度+格式）。 +func TestIDCardChecksum_M5(t *testing.T) { + validation.InitValidator() + + type TestIDCard struct { + ID string `json:"id" binding:"idcard"` + } + tests := []struct { + id string + valid bool + }{ + {"11010519491231002X", true}, // 合法（校验位正确） + {"110101199003078478", true}, // 合法（校验位正确） + {"110101199003078475", false}, // 校验位错误（末位改坏） + {"11010119900307847X", false}, // 18 位但校验位错 + {"123456789012345", true}, // 15 位旧号段仅查格式 + {"123456789012345678", false}, // 18 位但校验位错 + {"123", false}, // 长度不符 + } + for _, tt := range tests { + u := TestIDCard{ID: tt.id} + errs := validation.ValidateStruct(u) + valid := errs == nil + if valid != tt.valid { + t.Errorf("IDCard %s: valid=%v, want %v", tt.id, valid, tt.valid) + } + } +} + +// ===== Benchmarks ===== + +func BenchmarkHashPassword(b *testing.B) { + password := "testPassword123" + for i := 0; i < b.N; i++ { + validation.HashPassword(password) + } +} + +func BenchmarkCheckPassword(b *testing.B) { + password := "testPassword123" + hash, _ := validation.HashPassword(password) + b.ResetTimer() + for i := 0; i < b.N; i++ { + validation.CheckPassword(hash, password) + } +} + +func BenchmarkValidatePassword(b *testing.B) { + password := "TestPassword123" + for i := 0; i < b.N; i++ { + validation.ValidatePassword(password) + } +} diff --git a/validation/validator.go b/validation/validator.go new file mode 100644 index 0000000..c0ecfa9 --- /dev/null +++ b/validation/validator.go @@ -0,0 +1,457 @@ +package validation + +import ( + "fmt" + "reflect" + "strings" + "sync/atomic" + + "github.com/gin-gonic/gin" + "github.com/gin-gonic/gin/binding" + "github.com/go-playground/validator/v10" +) + +// Validator 全局验证器实例。 +// +// H-13 修复：改用 atomic.Pointer 保护读写，消除原裸指针（InitValidator 无锁写、 +// ValidateStruct 无锁读）在运行期热重载/并发校验时的数据竞争。类型由 *validator.Validate +// 变更为 atomic.Pointer[validator.Validate]（breaking：下游若直接读 validation.Validator.Struct +// 需改用 ValidateStruct，或 validation.Validator.Load().Struct）。 +var Validator atomic.Pointer[validator.Validate] + +// ValidationError 验证错误 +type ValidationError struct { + Field string `json:"field"` // 字段名（使用 label 或 json tag） + Label string `json:"label"` // 字段中文名（用于显示） + Message string `json:"message"` // 错误消息 +} + +// ValidationErrors 验证错误列表 +type ValidationErrors []ValidationError + +// Error 实现 error 接口 +func (ve ValidationErrors) Error() string { + var msgs []string + for _, e := range ve { + if e.Label != "" { + msgs = append(msgs, e.Label+": "+e.Message) + } else { + msgs = append(msgs, e.Field+": "+e.Message) + } + } + return strings.Join(msgs, "; ") +} + +// ToMap 转换为 map +func (ve ValidationErrors) ToMap() map[string]string { + m := make(map[string]string) + for _, e := range ve { + m[e.Field] = e.Message + } + return m +} + +// ToLabelMap 转换为带标签的 map +func (ve ValidationErrors) ToLabelMap() map[string]string { + m := make(map[string]string) + for _, e := range ve { + if e.Label != "" { + m[e.Label] = e.Message + } else { + m[e.Field] = e.Message + } + } + return m +} + +// First 获取第一个错误 +func (ve ValidationErrors) First() *ValidationError { + if len(ve) == 0 { + return nil + } + return &ve[0] +} + +// FirstMessage 获取第一个错误消息 +func (ve ValidationErrors) FirstMessage() string { + if len(ve) == 0 { + return "" + } + return ve[0].Message +} + +// InitValidator 初始化验证器 +func InitValidator() { + if v, ok := binding.Validator.Engine().(*validator.Validate); ok { + // 注册自定义标签名函数（优先使用 label，其次 json） + v.RegisterTagNameFunc(func(fld reflect.StructField) string { + // 优先使用 label tag 作为字段显示名 + label := fld.Tag.Get("label") + if label != "" { + return label + } + + // 其次使用 json tag + name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0] + if name == "-" { + return "" + } + return name + }) + + // 注册自定义验证规则（先注册再 Store，避免并发 ValidateStruct 拿到 + // "已 Store 但自定义规则未注册完"的 validator） + registerCustomValidations(v) + + // 全部配置完成后再发布，确保 Load 得到的 validator 永远是完整的 + Validator.Store(v) + } +} + +// registerCustomValidations 注册自定义验证规则。 +// +// P1 #18：每个 RegisterValidation 的错误都必须检查——注册失败会导致该 tag 静默不存在、 +// 所有输入被视为通过（password/idcard 等 fail-open 安全漏洞）。用 must 包装，在 init +// 期以明确信息 panic（配置类错误应启动即暴露，而非运行期静默放行）。 +func registerCustomValidations(v *validator.Validate) { + must := func(tag string, fn validator.Func) { + if err := v.RegisterValidation(tag, fn); err != nil { + panic(fmt.Sprintf("validation: 注册校验规则 %q 失败: %v", tag, err)) + } + } + + // 密码强度验证 + must("password", func(fl validator.FieldLevel) bool { + password := fl.Field().String() + valid, _ := ValidatePassword(password) + return valid + }) + + // 手机号验证（中国大陆） + must("phone", func(fl validator.FieldLevel) bool { + phone := fl.Field().String() + if len(phone) != 11 || !strings.HasPrefix(phone, "1") { + return false + } + // P1 #17：要求全数字——原实现仅查长度+前缀，"1abcdefghij" 这类会误通过。 + for i := 0; i < len(phone); i++ { + if phone[i] < '0' || phone[i] > '9' { + return false + } + } + return true + }) + + // 用户名验证（字母开头，允许字母数字下划线） + must("username", func(fl validator.FieldLevel) bool { + username := fl.Field().String() + if len(username) < 3 || len(username) > 20 { + return false + } + // 首字符按 rune 取，避免非 ASCII 首字节误判（M5：原 rune(username[0]) 取字节）。 + runes := []rune(username) + if len(runes) == 0 || !isLetter(runes[0]) { + return false + } + for _, r := range runes { + if !isLetter(r) && !isDigit(r) && r != '_' { + return false + } + } + return true + }) + + // 手机号严格验证（验证运营商号段） + must("phone_strict", func(fl validator.FieldLevel) bool { + phone := fl.Field().String() + if len(phone) != 11 { + return false + } + if !strings.HasPrefix(phone, "1") { + return false + } + // 检查号段 + prefix := phone[:3] + validPrefixes := []string{ + "130", "131", "132", "133", "134", "135", "136", "137", "138", "139", + "145", "146", "147", "148", "149", + "150", "151", "152", "153", "155", "156", "157", "158", "159", + "166", "167", + "170", "171", "172", "173", "174", "175", "176", "177", "178", + "180", "181", "182", "183", "184", "185", "186", "187", "188", "189", + "191", "198", "199", + } + for _, p := range validPrefixes { + if prefix == p { + return true + } + } + return false + }) + + // 身份证号验证（18 位带校验位；15 位仅格式，向后兼容旧号段）。 + must("idcard", func(fl validator.FieldLevel) bool { + id := fl.Field().String() + if len(id) != 18 && len(id) != 15 { + return false + } + // 基本格式：前 17 位（18 位号）或全部（15 位号）须为数字，18 位号末位可为 X。 + for i, c := range id { + if i == len(id)-1 && len(id) == 18 { + if !isDigit(c) && c != 'X' && c != 'x' { + return false + } + } else { + if !isDigit(c) { + return false + } + } + } + // 18 位号校验校验位（M5：原仅查长度+格式，无校验位可被任意构造通过）。 + if len(id) == 18 { + if !validateIDCardChecksum(id) { + return false + } + } + return true + }) +} + +func isLetter(r rune) bool { + return (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') +} + +func isDigit(r rune) bool { + return r >= '0' && r <= '9' +} + +// validateIDCardChecksum 校验 18 位身份证校验位（GB 11643-1999，M5）。 +// 前 17 位按权重 [7,9,10,5,8,4,2,1,6,3,7,9,10,5,8,4,2] 加权求和 mod 11， +// 对照码表 [1,0,X,9,8,7,6,5,4,3,2] 得期望末位。 +func validateIDCardChecksum(id string) bool { + weights := [17]int{7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2} + checkCodes := [11]byte{'1', '0', 'X', '9', '8', '7', '6', '5', '4', '3', '2'} + sum := 0 + for i := 0; i < 17; i++ { + c := id[i] + if c < '0' || c > '9' { + return false + } + sum += int(c-'0') * weights[i] + } + expected := checkCodes[sum%11] + last := id[17] + // 末位 X 大小写不敏感 + if last == 'x' { + last = 'X' + } + return last == expected +} + +// ValidateStruct 验证结构体 +func ValidateStruct(s any) ValidationErrors { + if s == nil { + return nil + } + + v := Validator.Load() + if v == nil { + InitValidator() + v = Validator.Load() + } + + err := v.Struct(s) + if err == nil { + return nil + } + + return parseValidationErrors(err, s) +} + +// parseValidationErrors 解析验证错误（支持自定义错误消息） +func parseValidationErrors(err error, s any) ValidationErrors { + var errors ValidationErrors + + if validationErrors, ok := err.(validator.ValidationErrors); ok { + for _, e := range validationErrors { + fieldName := e.Field() + label := fieldName // Field() 返回的是 label 或 json tag + + // 尝试获取原始字段名和自定义错误消息 + if s != nil { + t := reflect.TypeOf(s) + if t.Kind() == reflect.Ptr { + t = t.Elem() + } + if t.Kind() == reflect.Struct { + // 获取原始字段名 + originalField := getOriginalFieldName(t, e.StructField()) + if originalField != "" { + fieldName = originalField + } + + // 获取自定义错误消息 + field, found := t.FieldByName(e.StructField()) + if found { + customMsg := getCustomErrorMessage(field, e.Tag()) + if customMsg != "" { + errors = append(errors, ValidationError{ + Field: fieldName, + Label: label, + Message: customMsg, + }) + continue + } + } + } + } + + errors = append(errors, ValidationError{ + Field: fieldName, + Label: label, + Message: getErrorMessage(e), + }) + } + } + + return errors +} + +// getOriginalFieldName 获取原始字段名（从 json tag） +func getOriginalFieldName(t reflect.Type, structField string) string { + field, found := t.FieldByName(structField) + if !found { + return "" + } + + jsonTag := field.Tag.Get("json") + if jsonTag == "" || jsonTag == "-" { + return structField + } + + name := strings.SplitN(jsonTag, ",", 2)[0] + if name == "" { + return structField + } + return name +} + +// getCustomErrorMessage 获取自定义错误消息 +// 支持格式： +// - error:"自定义错误消息" +// - msg_required:"必填项" (针对特定验证规则) +// - msg_min:"最少5个字符" +func getCustomErrorMessage(field reflect.StructField, tag string) string { + // 优先查找特定规则的错误消息 + specificTag := fmt.Sprintf("msg_%s", tag) + msg := field.Tag.Get(specificTag) + if msg != "" { + return msg + } + + // 其次查找通用错误消息 + msg = field.Tag.Get("error") + if msg != "" { + return msg + } + + // 最后查找 msg tag + msg = field.Tag.Get("msg") + if msg != "" { + return msg + } + + return "" +} + +// getErrorMessage 获取默认验证错误消息 +func getErrorMessage(e validator.FieldError) string { + switch e.Tag() { + case "required": + return "此字段为必填项" + case "email": + return "邮箱格式不正确" + case "min": + return fmt.Sprintf("长度不能少于 %s 个字符", e.Param()) + case "max": + return fmt.Sprintf("长度不能超过 %s 个字符", e.Param()) + case "len": + return fmt.Sprintf("长度必须为 %s 个字符", e.Param()) + case "gte": + return fmt.Sprintf("必须大于或等于 %s", e.Param()) + case "lte": + return fmt.Sprintf("必须小于或等于 %s", e.Param()) + case "gt": + return fmt.Sprintf("必须大于 %s", e.Param()) + case "lt": + return fmt.Sprintf("必须小于 %s", e.Param()) + case "eq": + return fmt.Sprintf("必须等于 %s", e.Param()) + case "ne": + return fmt.Sprintf("不能等于 %s", e.Param()) + case "oneof": + return fmt.Sprintf("必须是以下值之一: %s", e.Param()) + case "url": + return "URL 格式不正确" + case "uri": + return "URI 格式不正确" + case "uuid": + return "UUID 格式不正确" + case "alphanum": + return "只能包含字母和数字" + case "alpha": + return "只能包含字母" + case "numeric": + return "必须是数字" + case "password": + return "密码强度不足，需包含大小写字母和数字，至少8位" + case "phone": + return "手机号格式不正确" + case "phone_strict": + return "手机号无效，请输入正确的手机号" + case "username": + return "用户名必须以字母开头，只能包含字母、数字和下划线，长度3-20" + case "idcard": + return "身份证号格式不正确" + default: + return fmt.Sprintf("验证失败: %s", e.Tag()) + } +} + +// BindAndValidate 绑定并验证请求 +func BindAndValidate(c *gin.Context, req any) ValidationErrors { + if err := c.ShouldBind(req); err != nil { + return parseValidationErrors(err, req) + } + return ValidateStruct(req) +} + +// ShouldBindAndValidate 绑定并验证请求，返回是否成功 +func ShouldBindAndValidate(c *gin.Context, req any) (ValidationErrors, bool) { + errors := BindAndValidate(c, req) + return errors, len(errors) == 0 +} + +// BindJSON 绑定 JSON 并验证 +func BindJSON(c *gin.Context, req any) ValidationErrors { + if err := c.ShouldBindJSON(req); err != nil { + return parseValidationErrors(err, req) + } + return ValidateStruct(req) +} + +// BindQuery 绑定 Query 并验证 +func BindQuery(c *gin.Context, req any) ValidationErrors { + if err := c.ShouldBindQuery(req); err != nil { + return parseValidationErrors(err, req) + } + return ValidateStruct(req) +} + +// BindForm 绑定 Form 并验证 +func BindForm(c *gin.Context, req any) ValidationErrors { + if err := c.ShouldBind(req); err != nil { + return parseValidationErrors(err, req) + } + return ValidateStruct(req) +} diff --git a/ws/ws.go b/ws/ws.go new file mode 100644 index 0000000..3a9c53a --- /dev/null +++ b/ws/ws.go @@ -0,0 +1,607 @@ +package ws + +import ( + "encoding/json" + "errors" + "net/http" + "net/url" + "strings" + "sync" + "sync/atomic" + "time" + + "github.com/gin-gonic/gin" + "github.com/gorilla/websocket" +) + +// WebSocket 配置。 +// +// CheckOrigin 默认采用同源校验（C7/CSWSH 修复）：仅当请求 Origin 为空（非浏览器客户端） +// 或与请求 Host 同源时放行，拒绝跨域 WebSocket 连接，防 Cross-Site WebSocket Hijacking。 +// 需要允许多个可信 Origin 的场景，用 SetCheckOrigin 注入自定义校验，或用 AllowOrigins。 +var upgrader = websocket.Upgrader{ + ReadBufferSize: 1024, + WriteBufferSize: 1024, + CheckOrigin: currentCheckOrigin, +} + +var checkOriginValue atomic.Value // stores func(*http.Request) bool + +func currentCheckOrigin(r *http.Request) bool { + if fn, ok := checkOriginValue.Load().(func(*http.Request) bool); ok && fn != nil { + return fn(r) + } + return sameOriginCheck(r) +} + +// sameOriginCheck 同源校验：Origin 为空（非浏览器/服务器内部）放行；否则要求 Origin 的 +// host:port 与请求 Host 一致。防 CSWSH（C7）。 +func sameOriginCheck(r *http.Request) bool { + origin := r.Header.Get("Origin") + if origin == "" { + // 非浏览器客户端（如 curl/服务端拨号）不带 Origin，放行。 + return true + } + u, err := url.Parse(origin) + if err != nil { + return false + } + if u.Scheme == "" || u.Host == "" { + return false + } + return strings.EqualFold(u.Scheme, requestScheme(r)) && strings.EqualFold(u.Host, r.Host) +} + +func requestScheme(r *http.Request) string { + if r.URL != nil && r.URL.Scheme != "" { + return r.URL.Scheme + } + if r.TLS != nil { + return "https" + } + return "http" +} + +// AllowOrigins 返回一个 CheckOrigin 函数，仅放行给定 Origin 列表（含 scheme+host[:port]）。 +// 用于多可信域名场景。传入空切片等价于拒绝所有带 Origin 的浏览器连接。 +func AllowOrigins(origins ...string) func(r *http.Request) bool { + allowed := make(map[string]bool, len(origins)) + for _, o := range origins { + allowed[o] = true + } + return func(r *http.Request) bool { + origin := r.Header.Get("Origin") + if origin == "" { + return true // 非浏览器客户端放行 + } + return allowed[origin] + } +} + +// 读写超时常量（C2c：防半开连接 goroutine 泄漏）。ping 周期须 < pongWait。 +const ( + // pongWait 等待对端 pong 的最长时间；超时即判定连接半开、关闭。 + pongWait = 60 * time.Second + // pingPeriod ping 发送周期，须 < pongWait 以留出重置读 deadline 的余量。 + pingPeriod = (pongWait * 9) / 10 + // writeWait 单次写操作超时。 + writeWait = 10 * time.Second +) + +// MessageType 消息类型 +type MessageType string + +const ( + TypeText MessageType = "text" // 文本消息 + TypeBinary MessageType = "binary" // 二进制消息 + TypePing MessageType = "ping" // 心跳 ping + TypePong MessageType = "pong" // 心跳 pong + TypeClose MessageType = "close" // 关闭消息 +) + +// Message WebSocket 消息 +type Message struct { + Type MessageType `json:"type"` + Content any `json:"content"` +} + +// Connection WebSocket 连接 +type Connection struct { + conn *websocket.Conn + send chan []byte + closeChan chan struct{} + once sync.Once + mu sync.Mutex +} + +// NewConnection 创建 WebSocket 连接 +func NewConnection(conn *websocket.Conn) *Connection { + return &Connection{ + conn: conn, + send: make(chan []byte, 256), + closeChan: make(chan struct{}), + } +} + +// ErrSendBufferFull 发送缓冲已满（消费者跟不上）。非阻塞投递策略下返回此错误， +// 调用方可决定重试或关闭连接。避免慢消费者阻塞发送方（含 Hub 广播持锁场景）。 +var ErrSendBufferFull = errors.New("websocket send buffer full") + +// Send 非阻塞发送消息。不直接写底层 conn，而是投递到 send channel 由 writePump 统一写出。 +// +// 并发安全说明（C2b 修复）：Close() 仅 close closeChan，不再 close send channel， +// 因此 select 选中 send 分支也只是向未关闭 channel 投递（不会 panic）。 +// +// 非阻塞策略（C2a-residual 修复）：投递用 default 分支，缓冲满立即返回 ErrSendBufferFull， +// 而非阻塞等待。这避免 Hub 广播持锁期间因慢消费者/已死连接（writePump 退出但 closeChan +// 未关、send 缓冲满）阻塞最长 pongWait，导致整个 Hub stall。调用方对缓冲满可重试或关闭连接。 +func (c *Connection) Send(data []byte) error { + // 快速路径：连接已关闭则立即失败。 + if c.IsClosed() { + return errors.New("connection closed") + } + select { + case c.send <- data: + return nil + default: + // 缓冲满。再检查一次 closeChan，避免对刚关闭的连接报"缓冲满"而非"已关闭"。 + select { + case <-c.closeChan: + return errors.New("connection closed") + default: + return ErrSendBufferFull + } + } +} + +// SendJSON 发送 JSON 消息 +func (c *Connection) SendJSON(v any) error { + data, err := json.Marshal(v) + if err != nil { + return err + } + return c.Send(data) +} + +// SendText 发送文本消息 +func (c *Connection) SendText(text string) error { + return c.SendJSON(Message{Type: TypeText, Content: text}) +} + +// Close 关闭连接。仅 close closeChan 作关闭信号，不 close send channel（C2b 修复）， +// 避免 Close 与并发 Send 之间的 send-on-closed panic。send channel 由 GC 回收。 +func (c *Connection) Close() { + c.once.Do(func() { + close(c.closeChan) + // #nosec G104 -- 关闭底层连接的错误无意义（重复关闭返错属正常），忽略 + if c.conn != nil { + _ = c.conn.Close() + } + }) +} + +// IsClosed 检查连接是否已关闭 +func (c *Connection) IsClosed() bool { + select { + case <-c.closeChan: + return true + default: + return false + } +} + +// SetReadDeadline 设置读取超时 +func (c *Connection) SetReadDeadline(t time.Time) error { + return c.conn.SetReadDeadline(t) +} + +// SetWriteDeadline 设置写入超时 +func (c *Connection) SetWriteDeadline(t time.Time) error { + return c.conn.SetWriteDeadline(t) +} + +// Handler WebSocket 处理器接口 +type Handler interface { + OnConnect(conn *Connection) + OnMessage(conn *Connection, message []byte) + OnClose(conn *Connection) + OnError(conn *Connection, err error) +} + +// HandlerFunc 处理函数类型 +type HandlerFunc func(conn *Connection, message []byte) + +// DefaultHandler 默认处理器 +type DefaultHandler struct { + OnConnectFunc func(conn *Connection) + OnMessageFunc func(conn *Connection, message []byte) + OnCloseFunc func(conn *Connection) + OnErrorFunc func(conn *Connection, err error) +} + +func (h *DefaultHandler) OnConnect(conn *Connection) { + if h.OnConnectFunc != nil { + h.OnConnectFunc(conn) + } +} + +func (h *DefaultHandler) OnMessage(conn *Connection, message []byte) { + if h.OnMessageFunc != nil { + h.OnMessageFunc(conn, message) + } +} + +func (h *DefaultHandler) OnClose(conn *Connection) { + if h.OnCloseFunc != nil { + h.OnCloseFunc(conn) + } +} + +func (h *DefaultHandler) OnError(conn *Connection, err error) { + if h.OnErrorFunc != nil { + h.OnErrorFunc(conn, err) + } +} + +// Upgrade 升级 HTTP 连接为 WebSocket +func Upgrade(c *gin.Context) (*Connection, error) { + conn, err := upgrader.Upgrade(c.Writer, c.Request, nil) + if err != nil { + return nil, err + } + return NewConnection(conn), nil +} + +// Handle WebSocket 处理中间件 +func Handle(handler Handler) gin.HandlerFunc { + if handler == nil { + handler = &DefaultHandler{} + } + return func(c *gin.Context) { + conn, err := Upgrade(c) + if err != nil { + return + } + defer conn.Close() + + // 触发连接事件 + handler.OnConnect(conn) + + // 读循环前置：设置初始读 deadline 与 pong handler（C2c：防半开连接永久阻塞）。 + // 每收到 pong 重置读 deadline；超时未收到 pong 则 ReadMessage 返回错误退出。 + _ = conn.conn.SetReadDeadline(time.Now().Add(pongWait)) + conn.conn.SetPongHandler(func(string) error { + _ = conn.conn.SetReadDeadline(time.Now().Add(pongWait)) + return nil + }) + + // 启动写入协程 + go writePump(conn) + + // 读取消息 + for { + _, message, err := conn.conn.ReadMessage() + if err != nil { + if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseAbnormalClosure) { + handler.OnError(conn, err) + } + handler.OnClose(conn) + break + } + handler.OnMessage(conn, message) + } + } +} + +// writePump 写入泵。每次写前设置写超时，按 pingPeriod 周期发 ping（须 < pongWait）。 +// 写失败时主动 Close 连接，触发 closeChan 关闭 → 读循环 ReadMessage 因底层 conn 关闭 +// 返回错误而退出，避免半开连接残留最长 pongWait 才回收（C2c 残留优化）。 +func writePump(conn *Connection) { + ticker := time.NewTicker(pingPeriod) + defer ticker.Stop() + + for { + select { + case <-conn.closeChan: + return + case message, ok := <-conn.send: + // send channel 不再被 Close（C2b 修复），ok 永远为 true； + // 此分支保留 ok 检查仅为兼容历史与防御。 + if !ok { + _ = conn.conn.WriteControl(websocket.CloseMessage, []byte{}, time.Now().Add(writeWait)) + conn.Close() + return + } + conn.mu.Lock() + _ = conn.conn.SetWriteDeadline(time.Now().Add(writeWait)) + err := conn.conn.WriteMessage(websocket.TextMessage, message) + conn.mu.Unlock() + if err != nil { + conn.Close() + return + } + case <-ticker.C: + conn.mu.Lock() + _ = conn.conn.SetWriteDeadline(time.Now().Add(writeWait)) + err := conn.conn.WriteMessage(websocket.PingMessage, nil) + conn.mu.Unlock() + if err != nil { + conn.Close() + return + } + } + } +} + +// HandleFunc 使用函数处理 WebSocket +func HandleFunc(fn HandlerFunc) gin.HandlerFunc { + return Handle(&DefaultHandler{ + OnMessageFunc: fn, + }) +} + +// SetCheckOrigin 设置 Origin 检查函数。传 nil 会恢复默认同源校验。 +// 运行期并发调用安全：upgrader 持有固定 wrapper，实际检查函数经 atomic.Value 切换。 +func SetCheckOrigin(fn func(r *http.Request) bool) { + if fn == nil { + fn = sameOriginCheck + } + checkOriginValue.Store(fn) +} + +var ( + // ErrHubNotRunning 在 Hub 未启动 Run 即调用 Try* 方法时返回。 + ErrHubNotRunning = errors.New("websocket hub not running") + // ErrHubStopped 在 Hub 已 Stop 后调用 Try* 方法时返回。 + ErrHubStopped = errors.New("websocket hub stopped") + // ErrHubQueueFull 在 register/unregister/broadcast channel 缓冲满时返回。 + ErrHubQueueFull = errors.New("websocket hub queue full") + // ErrNilConnection 在向 Hub 注册/注销 nil 连接时返回。 + ErrNilConnection = errors.New("websocket connection is nil") +) + +// Hub 连接管理中心（用于广播）。 +// W1 修复：添加 stop channel + Stop() 方法，支持优雅退出。 +type Hub struct { + connections map[*Connection]bool + register chan *Connection + unregister chan *Connection + broadcast chan []byte + mu sync.RWMutex + lifecycleMu sync.RWMutex + stop chan struct{} + stopOnce sync.Once // H-8: 保证 close(stop) 仅一次，并发 Stop 不 double-close panic + runOnce sync.Once // H-9: 保证 Run 仅执行一次 + runStarted atomic.Bool // H-9: 标记 Run 是否已启动，Stop 据此决定是否等待 + stopped atomic.Bool + runDone chan struct{} // H-9: Run 退出时 close，替代 WaitGroup 避免 Add/Wait 竞态 +} + +// NewHub 创建 Hub +func NewHub() *Hub { + return &Hub{ + connections: make(map[*Connection]bool), + register: make(chan *Connection, 256), + unregister: make(chan *Connection, 256), + broadcast: make(chan []byte, 256), + stop: make(chan struct{}), + runDone: make(chan struct{}), + } +} + +// Run 运行 Hub。消费 register/unregister/broadcast/stop 四个 channel。 +// +// W1 修复：新增 stop 退出分支，Stop() 方法 close(stop) 通知退出。 +// 死锁修复（C2a）：广播分支不再向自身 unregister channel 回环。 +// +// H-9 修复：用 runOnce 守卫 Run 仅执行一次；用 runDone channel 替代 WaitGroup。 +// 原实现 wg.Add(1) 在 Run 内、wg.Wait() 在 Stop 内，二者并发时违反 WaitGroup +// "Add(正delta且计数器为0) 必须 happens-before Wait" 的约束，-race 必采。 +// 改为 Run 启动时 Store runStarted=true 并在退出时 close(runDone)；Stop 仅在 +// runStarted 为 true 时 <-runDone 等待，未启动则直接返回，无竞态。 +func (h *Hub) Run() { + h.runOnce.Do(func() { + h.runStarted.Store(true) + defer close(h.runDone) + for { + select { + case <-h.stop: + h.drainPending() + h.closeAll() + return + + case conn := <-h.register: + if conn == nil { + continue + } + h.mu.Lock() + h.connections[conn] = true + h.mu.Unlock() + + case conn := <-h.unregister: + if conn == nil { + continue + } + h.mu.Lock() + if _, ok := h.connections[conn]; ok { + delete(h.connections, conn) + conn.Close() + } + h.mu.Unlock() + + case message := <-h.broadcast: + // 持写锁单次遍历，失败的连接行内移除并关闭，不回环 unregister channel（C2a 修复）。 + h.mu.Lock() + for conn := range h.connections { + if err := conn.Send(message); err != nil { + delete(h.connections, conn) + conn.Close() + } + } + h.mu.Unlock() + } + } + }) +} + +func (h *Hub) drainPending() { + for { + select { + case conn := <-h.register: + if conn != nil { + conn.Close() + } + case conn := <-h.unregister: + if conn != nil { + conn.Close() + } + case <-h.broadcast: + default: + return + } + } +} + +func (h *Hub) closeAll() { + h.mu.Lock() + defer h.mu.Unlock() + for conn := range h.connections { + delete(h.connections, conn) + conn.Close() + } +} + +// Stop 停止 Hub（W1 修复：优雅退出机制）。 +// close(stop) 通知 Run() 退出；若 Run 已启动则等待其完全结束（<-runDone）。 +// +// H-8 修复：用 stopOnce 保证 close(stop) 仅执行一次。原实现 select{<-stop/default:close(stop)} +// 在并发 Stop 时两个调用方都可能走 default 分支同时 close → double-close panic； +// 原注释声称的"stopped 标志保护"实际不存在（文档撒谎）。stopOnce 彻底消除该竞态。 +// +// H-9 修复：仅在 runStarted 为 true 时等待 runDone；Run 未启动时直接返回， +// 避免 WaitGroup Add/Wait 竞态，且 Stop 先于 Run 调用后误再调 Run 也不会 panic。 +// 幂等：重复/并发调用安全。 +// Stop discards pending broadcast messages instead of guaranteeing delivery; +// it is a shutdown boundary. Pending register/unregister entries are drained +// and all live connections are closed before Stop returns. +func (h *Hub) Stop() { + h.stopOnce.Do(func() { + h.lifecycleMu.Lock() + defer h.lifecycleMu.Unlock() + h.stopped.Store(true) + close(h.stop) + if !h.runStarted.Load() { + h.drainPending() + h.closeAll() + } + }) + if h.runStarted.Load() { + <-h.runDone + } +} + +func (h *Hub) enqueueRegister(conn *Connection, requireStarted bool) error { + if conn == nil { + return ErrNilConnection + } + h.lifecycleMu.RLock() + defer h.lifecycleMu.RUnlock() + if h.stopped.Load() { + conn.Close() + return ErrHubStopped + } + if requireStarted && !h.runStarted.Load() { + conn.Close() + return ErrHubNotRunning + } + select { + case h.register <- conn: + return nil + default: + conn.Close() + return ErrHubQueueFull + } +} + +// Register 注册连接。调用兼容旧 API：失败时关闭连接并直接返回。 +func (h *Hub) Register(conn *Connection) { + _ = h.enqueueRegister(conn, false) +} + +// TryRegister 注册连接并返回失败原因。Hub 未 Run、已 Stop 或队列满时立即返回错误。 +func (h *Hub) TryRegister(conn *Connection) error { + return h.enqueueRegister(conn, true) +} + +func (h *Hub) enqueueUnregister(conn *Connection, requireStarted bool) error { + if conn == nil { + return ErrNilConnection + } + h.lifecycleMu.RLock() + defer h.lifecycleMu.RUnlock() + if h.stopped.Load() { + return ErrHubStopped + } + if requireStarted && !h.runStarted.Load() { + return ErrHubNotRunning + } + select { + case h.unregister <- conn: + return nil + default: + return ErrHubQueueFull + } +} + +// Unregister 注销连接。调用兼容旧 API：失败时直接返回。 +func (h *Hub) Unregister(conn *Connection) { + _ = h.enqueueUnregister(conn, false) +} + +// TryUnregister 注销连接并返回失败原因。 +func (h *Hub) TryUnregister(conn *Connection) error { + return h.enqueueUnregister(conn, true) +} + +func (h *Hub) enqueueBroadcast(message []byte, requireStarted bool) error { + h.lifecycleMu.RLock() + defer h.lifecycleMu.RUnlock() + if h.stopped.Load() { + return ErrHubStopped + } + if requireStarted && !h.runStarted.Load() { + return ErrHubNotRunning + } + select { + case h.broadcast <- message: + return nil + default: + return ErrHubQueueFull + } +} + +// Broadcast 广播消息。调用兼容旧 API：失败时直接返回。 +func (h *Hub) Broadcast(message []byte) { + _ = h.enqueueBroadcast(message, false) +} + +// TryBroadcast 广播消息并返回失败原因。 +func (h *Hub) TryBroadcast(message []byte) error { + return h.enqueueBroadcast(message, true) +} + +// BroadcastJSON 广播 JSON 消息 +func (h *Hub) BroadcastJSON(v any) error { + data, err := json.Marshal(v) + if err != nil { + return err + } + return h.TryBroadcast(data) +} + +// Count 获取连接数 +func (h *Hub) Count() int { + h.mu.RLock() + defer h.mu.RUnlock() + return len(h.connections) +} diff --git a/ws/ws_concurrency_test.go b/ws/ws_concurrency_test.go new file mode 100644 index 0000000..6502893 --- /dev/null +++ b/ws/ws_concurrency_test.go @@ -0,0 +1,414 @@ +package ws_test + +import ( + "encoding/json" + "errors" + "net/http" + "net/http/httptest" + "strings" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/EthanCodeCraft/xlgo-core/ws" + "github.com/gin-gonic/gin" + "github.com/gorilla/websocket" +) + +func init() { + gin.SetMode(gin.TestMode) +} + +// newWSTestServer 启动一个带 ws.Handle 的 httptest server，返回 server 与 dialer。 +// handler 可为 nil（用默认空处理器）。 +func newWSTestServer(t *testing.T, handler ws.Handler) (*httptest.Server, *websocket.Dialer) { + t.Helper() + r := gin.New() + if handler == nil { + handler = &ws.DefaultHandler{} + } + r.GET("/ws", ws.Handle(handler)) + srv := httptest.NewServer(r) + t.Cleanup(srv.Close) + dialer := &websocket.Dialer{HandshakeTimeout: 2 * time.Second} + return srv, dialer +} + +func wsURL(srv *httptest.Server) string { + return "ws" + strings.TrimPrefix(srv.URL, "http") + "/ws" +} + +// dial 连接并返回客户端 conn。 +func dial(t *testing.T, srv *httptest.Server, dialer *websocket.Dialer) *websocket.Conn { + t.Helper() + c, _, err := dialer.Dial(wsURL(srv), nil) + if err != nil { + t.Fatalf("dial: %v", err) + } + t.Cleanup(func() { c.Close() }) + return c +} + +// ===== C2b：Close 与并发 Send 不 panic ===== + +// 回归 C2b：并发 Close 与 Send 不能 send-on-closed panic。 +// 旧实现 Close 同时 close(c.send)，并发 Send 的 select 伪随机选中 send 分支即 panic。 +func TestConnectionCloseConcurrentSendNoPanic(t *testing.T) { + srv, dialer := newWSTestServer(t, nil) + client := dial(t, srv, dialer) + + // 服务端 conn 经 Handle 持有；通过 Hub 注册拿到服务端 Connection。 + hub := ws.NewHub() + go hub.Run() + t.Cleanup(func() { /* Hub.Run 无退出，靠进程结束 */ }) + + // 用 HandleFunc 包装拿到服务端 Connection。 + var srvConn *ws.Connection + var got atomic.Value // *ws.Connection + r := gin.New() + r.GET("/ws", ws.HandleFunc(func(conn *ws.Connection, message []byte) { + got.Store(conn) + })) + srv2 := httptest.NewServer(r) + t.Cleanup(srv2.Close) + c2, _, err := dialer.Dial("ws"+strings.TrimPrefix(srv2.URL, "http")+"/ws", nil) + if err != nil { + t.Fatalf("dial: %v", err) + } + defer c2.Close() + _ = client + + // 发一条消息触发服务端 OnMessage，拿到 srvConn。 + if err := c2.WriteMessage(websocket.TextMessage, []byte("hi")); err != nil { + t.Fatalf("write: %v", err) + } + // 等待服务端拿到连接。 + deadline := time.Now().Add(2 * time.Second) + for time.Now().Before(deadline) { + if v := got.Load(); v != nil { + srvConn = v.(*ws.Connection) + break + } + time.Sleep(5 * time.Millisecond) + } + if srvConn == nil { + t.Fatal("timeout waiting for server-side Connection") + } + + // 并发：一个 goroutine 反复 Send，主 goroutine Close。 + var panicked atomic.Value + var wg sync.WaitGroup + wg.Add(1) + go func() { + defer wg.Done() + defer func() { + if r := recover(); r != nil { + panicked.Store(r) + } + }() + for i := 0; i < 2000; i++ { + // Send 在 Close 后会返回 error，正常；不应 panic。 + _ = srvConn.Send([]byte("x")) + } + }() + + // 给 Send 一点启动时间再 Close，制造最大竞态窗口。 + time.Sleep(2 * time.Millisecond) + srvConn.Close() + wg.Wait() + + if p := panicked.Load(); p != nil { + t.Fatalf("concurrent Close/Send panicked (C2b send-on-closed): %v", p) + } +} + +// 回归 C2b：Close 后 Send 返回 error 而非 panic。 +func TestSendAfterCloseReturnsError(t *testing.T) { + srv, dialer := newWSTestServer(t, nil) + c := dial(t, srv, dialer) + defer c.Close() + + // 通过 HandleFunc 拿服务端 conn。 + var got atomic.Value + r := gin.New() + r.GET("/ws", ws.HandleFunc(func(conn *ws.Connection, message []byte) { + got.Store(conn) + })) + srv2 := httptest.NewServer(r) + t.Cleanup(srv2.Close) + c2, _, err := dialer.Dial("ws"+strings.TrimPrefix(srv2.URL, "http")+"/ws", nil) + if err != nil { + t.Fatalf("dial: %v", err) + } + defer c2.Close() + if err := c2.WriteMessage(websocket.TextMessage, []byte("hi")); err != nil { + t.Fatalf("write: %v", err) + } + deadline := time.Now().Add(2 * time.Second) + var srvConn *ws.Connection + for time.Now().Before(deadline) { + if v := got.Load(); v != nil { + srvConn = v.(*ws.Connection) + break + } + time.Sleep(5 * time.Millisecond) + } + if srvConn == nil { + t.Fatal("timeout") + } + srvConn.Close() + // Close 后 Send 必须返回 error（非 panic）。 + if err := srvConn.Send([]byte("after-close")); err == nil { + t.Error("Send after Close should return error, got nil") + } +} + +// ===== C2a：Hub 广播不死锁 ===== + +// 回归 C2a：向含"已关闭"连接的 Hub 广播不能死锁，且失败连接被行内移除。 +// 旧实现：broadcast 中 conn.Send 失败 → h.unregister <- conn（向自己发，无消费者）→ 永久阻塞。 +// 这里直接 Close 服务端连接（closeChan 关闭），使 Send 走 closeChan 分支返回 error， +// 触发 Hub 行内 delete + Close。 +func TestHubBroadcastDeadConnectionNoDeadlock(t *testing.T) { + hub := ws.NewHub() + go hub.Run() + + var got atomic.Value + r := gin.New() + r.GET("/ws", ws.HandleFunc(func(conn *ws.Connection, message []byte) { + got.Store(conn) + })) + srv2 := httptest.NewServer(r) + t.Cleanup(srv2.Close) + dialer := &websocket.Dialer{HandshakeTimeout: 2 * time.Second} + c2, _, err := dialer.Dial("ws"+strings.TrimPrefix(srv2.URL, "http")+"/ws", nil) + if err != nil { + t.Fatalf("dial: %v", err) + } + defer c2.Close() + if err := c2.WriteMessage(websocket.TextMessage, []byte("hi")); err != nil { + t.Fatalf("write: %v", err) + } + deadline := time.Now().Add(2 * time.Second) + var srvConn *ws.Connection + for time.Now().Before(deadline) { + if v := got.Load(); v != nil { + srvConn = v.(*ws.Connection) + break + } + time.Sleep(5 * time.Millisecond) + } + if srvConn == nil { + t.Fatal("timeout") + } + + hub.Register(srvConn) + deadline = time.Now().Add(time.Second) + for time.Now().Before(deadline) { + if hub.Count() == 1 { + break + } + time.Sleep(5 * time.Millisecond) + } + if hub.Count() != 1 { + t.Fatalf("Hub Count = %d, want 1", hub.Count()) + } + + // 直接关闭服务端连接（closeChan 关闭），使后续 Send 返回 error。 + srvConn.Close() + // 给 closeChan 关闭传播一点时间。 + time.Sleep(20 * time.Millisecond) + + // 广播必须在超时内返回（不阻塞 Hub），且失败连接被行内移除。 + done := make(chan struct{}) + go func() { + hub.Broadcast([]byte("should-not-deadlock")) + close(done) + }() + select { + case <-done: + case <-time.After(3 * time.Second): + t.Fatal("Hub.Broadcast deadlocked (C2a: unregister self-send loop)") + } + // 等待 Hub 内部清理失败的连接。 + deadline = time.Now().Add(2 * time.Second) + for time.Now().Before(deadline) { + if hub.Count() == 0 { + break + } + time.Sleep(10 * time.Millisecond) + } + if hub.Count() != 0 { + t.Errorf("Hub Count = %d, want 0 (failed conn should be removed inline)", hub.Count()) + } +} + +// 回归 C2a/C2b：Hub 广播到正常连接，客户端能收到。 +func TestHubBroadcastReachesClients(t *testing.T) { + hub := ws.NewHub() + go hub.Run() + + // 用带 Hub 注册的 handler。 + handler := &ws.DefaultHandler{ + OnConnectFunc: func(conn *ws.Connection) { + hub.Register(conn) + }, + } + srv, dialer := newWSTestServer(t, handler) + + // 两个客户端。 + c1 := dial(t, srv, dialer) + c2 := dial(t, srv, dialer) + defer c1.Close() + defer c2.Close() + + // 等待两个连接注册。 + deadline := time.Now().Add(2 * time.Second) + for time.Now().Before(deadline) && hub.Count() < 2 { + time.Sleep(10 * time.Millisecond) + } + if hub.Count() != 2 { + t.Fatalf("Hub Count = %d, want 2", hub.Count()) + } + + // 广播 JSON。 + if err := hub.BroadcastJSON(map[string]string{"msg": "hello"}); err != nil { + t.Fatalf("BroadcastJSON: %v", err) + } + + // 两个客户端都应收到。 + for i, c := range []*websocket.Conn{c1, c2} { + c.SetReadDeadline(time.Now().Add(2 * time.Second)) + _, msg, err := c.ReadMessage() + if err != nil { + t.Fatalf("client %d read: %v", i, err) + } + var m map[string]string + if err := json.Unmarshal(msg, &m); err != nil { + t.Fatalf("client %d unmarshal %q: %v", i, string(msg), err) + } + if m["msg"] != "hello" { + t.Errorf("client %d got %q, want hello", i, m["msg"]) + } + } +} + +// 回归 C2a-residual：Send 非阻塞——缓冲满立即返回 ErrSendBufferFull 而非阻塞等待。 +// 旧实现（阻塞 select）在 writePump 退出但 closeChan 未关、send 缓冲满时会阻塞最长 pongWait， +// 导致 Hub 广播持写锁期间 stall。非阻塞投递保证持锁期间永不阻塞。 +// 用 internal test（ws_send_internal_test.go）直接测私有 send channel，此处仅验证公开行为： +// 连接 Close 后，Send 立即返回（不阻塞）。 +func TestSendNonBlockingOnClosed(t *testing.T) { + var got atomic.Value + r := gin.New() + r.GET("/ws", ws.HandleFunc(func(conn *ws.Connection, message []byte) { + got.Store(conn) + })) + srv := httptest.NewServer(r) + t.Cleanup(srv.Close) + dialer := &websocket.Dialer{HandshakeTimeout: 2 * time.Second} + c, _, err := dialer.Dial("ws"+strings.TrimPrefix(srv.URL, "http")+"/ws", nil) + if err != nil { + t.Fatalf("dial: %v", err) + } + defer c.Close() + if err := c.WriteMessage(websocket.TextMessage, []byte("hi")); err != nil { + t.Fatalf("write: %v", err) + } + deadline := time.Now().Add(2 * time.Second) + var srvConn *ws.Connection + for time.Now().Before(deadline) { + if v := got.Load(); v != nil { + srvConn = v.(*ws.Connection) + break + } + time.Sleep(5 * time.Millisecond) + } + if srvConn == nil { + t.Fatal("timeout") + } + srvConn.Close() + + // Close 后连续 Send 必须立即返回 error，不阻塞。 + done := make(chan struct{}) + go func() { + defer close(done) + for i := 0; i < 1000; i++ { + _ = srvConn.Send([]byte("x")) + } + }() + select { + case <-done: + case <-time.After(3 * time.Second): + t.Fatal("Send after Close blocked (should be non-blocking)") + } +} + +// ===== C2c：半开连接超时退出（不永久泄漏 goroutine）===== + +// 回归 C2c：客户端断开后，服务端读循环应在 pongWait 超时内退出（非永久阻塞）。 +// 用短超时配置不便（常量包级），此处用真实连接断开 + 有限等待验证 OnClose 被调用。 +func TestHalfOpenConnectionExitsOnClose(t *testing.T) { + var closed atomic.Int32 + handler := &ws.DefaultHandler{ + OnCloseFunc: func(conn *ws.Connection) { + closed.Add(1) + }, + } + srv, dialer := newWSTestServer(t, handler) + c := dial(t, srv, dialer) + + // 客户端主动关闭（发 close 帧）。 + c.Close() + + // 服务端应在有限时间内 OnClose。pongWait=60s 太长，但客户端发的是正常 close， + // ReadMessage 立即返回 close 错误，OnClose 应很快触发。 + deadline := time.Now().Add(2 * time.Second) + for time.Now().Before(deadline) { + if closed.Load() > 0 { + return + } + time.Sleep(10 * time.Millisecond) + } + t.Errorf("OnClose not called within timeout (C2c: read loop should exit on client close), closed=%d", closed.Load()) +} + +// ===== 辅助：验证 errors 导入被使用 ===== +var _ = errors.New +var _ = http.StatusOK + +// TestHubStopConcurrentNoPanic H-8 回归：并发 Stop 不应 double-close panic。 +// 修复前 Stop 用 select{<-stop/default:close(stop)}，两个 goroutine 都走 default +// 同时 close → panic。修复后 stopOnce 保证 close 仅一次。 +func TestHubStopConcurrentNoPanic(t *testing.T) { + hub := ws.NewHub() + go hub.Run() + + var wg sync.WaitGroup + for i := 0; i < 10; i++ { + wg.Add(1) + go func() { + defer wg.Done() + hub.Stop() // 并发 Stop + }() + } + wg.Wait() + + // 再调一次 Stop（已 stop）也应安全返回 + hub.Stop() +} + +// TestHubStopBeforeRunNoPanic H-9 回归：Stop 先于 Run 调用，随后 Run 不应 +// 触发 wg 负计数 panic。 +func TestHubStopBeforeRunNoPanic(t *testing.T) { + hub := ws.NewHub() + hub.Stop() // Run 尚未启动，Wait 立即返回 + + // 之后启动 Run（实际场景是误用），应安全退出而非 panic + go hub.Run() + // 给 Run 一点时间观察到 stop 已 close 并退出 + time.Sleep(50 * time.Millisecond) + // 再次 Stop 确保 wg 归零（Run 的 runOnce 已执行，wg.Add/Done 配对） + hub.Stop() +} diff --git a/ws/ws_m11_internal_test.go b/ws/ws_m11_internal_test.go new file mode 100644 index 0000000..3726b12 --- /dev/null +++ b/ws/ws_m11_internal_test.go @@ -0,0 +1,199 @@ +package ws + +import ( + "errors" + "net/http" + "net/http/httptest" + "strings" + "sync" + "testing" + "time" + + "github.com/gin-gonic/gin" + "github.com/gorilla/websocket" +) + +func TestM11SetCheckOriginConcurrentWithUpgradeNoRace(t *testing.T) { + SetCheckOrigin(nil) + t.Cleanup(func() { SetCheckOrigin(nil) }) + + gin.SetMode(gin.TestMode) + r := gin.New() + r.GET("/ws", Handle(nil)) + srv := httptest.NewServer(r) + t.Cleanup(srv.Close) + + done := make(chan struct{}) + var wg sync.WaitGroup + wg.Add(1) + go func() { + defer wg.Done() + allowA := func(*http.Request) bool { return true } + allowB := func(*http.Request) bool { return true } + for { + select { + case <-done: + return + default: + SetCheckOrigin(allowA) + SetCheckOrigin(allowB) + } + } + }() + + dialer := &websocket.Dialer{HandshakeTimeout: 2 * time.Second} + url := "ws" + strings.TrimPrefix(srv.URL, "http") + "/ws" + for i := 0; i < 50; i++ { + conn, _, err := dialer.Dial(url, nil) + if err != nil { + t.Fatalf("dial[%d]: %v", i, err) + } + _ = conn.Close() + } + close(done) + wg.Wait() +} + +func TestM11HandleNilUsesDefaultHandler(t *testing.T) { + SetCheckOrigin(func(*http.Request) bool { return true }) + t.Cleanup(func() { SetCheckOrigin(nil) }) + + gin.SetMode(gin.TestMode) + r := gin.New() + r.GET("/ws", Handle(nil)) + srv := httptest.NewServer(r) + t.Cleanup(srv.Close) + + conn, _, err := websocket.DefaultDialer.Dial("ws"+strings.TrimPrefix(srv.URL, "http")+"/ws", nil) + if err != nil { + t.Fatalf("dial Handle(nil): %v", err) + } + _ = conn.Close() +} + +func TestM11HubNotRunFastFail(t *testing.T) { + hub := NewHub() + conn := NewConnection(nil) + + if err := hub.TryRegister(conn); !errors.Is(err, ErrHubNotRunning) { + t.Fatalf("TryRegister before Run error = %v, want ErrHubNotRunning", err) + } + if !conn.IsClosed() { + t.Fatal("TryRegister before Run should close rejected connection") + } + if err := hub.TryUnregister(NewConnection(nil)); !errors.Is(err, ErrHubNotRunning) { + t.Fatalf("TryUnregister before Run error = %v, want ErrHubNotRunning", err) + } + if err := hub.TryBroadcast([]byte("x")); !errors.Is(err, ErrHubNotRunning) { + t.Fatalf("TryBroadcast before Run error = %v, want ErrHubNotRunning", err) + } + if err := hub.BroadcastJSON(map[string]string{"x": "y"}); !errors.Is(err, ErrHubNotRunning) { + t.Fatalf("BroadcastJSON before Run error = %v, want ErrHubNotRunning", err) + } +} + +func TestM11PublicRegisterToleratesRunStartupWindow(t *testing.T) { + hub := NewHub() + conn := NewConnection(nil) + + hub.Register(conn) + go hub.Run() + t.Cleanup(hub.Stop) + + deadline := time.Now().Add(time.Second) + for time.Now().Before(deadline) { + if hub.Count() == 1 { + if conn.IsClosed() { + t.Fatal("public Register should not close connection during Run startup window") + } + return + } + time.Sleep(time.Millisecond) + } + t.Fatalf("Hub Count = %d, want 1", hub.Count()) +} + +func TestM11HubStopDrainsAndCloses(t *testing.T) { + hub := NewHub() + go hub.Run() + for !hub.runStarted.Load() { + time.Sleep(time.Millisecond) + } + + conn := NewConnection(nil) + hub.register <- conn + hub.broadcast <- []byte("discarded") + hub.Stop() + + if !conn.IsClosed() { + t.Fatal("Stop should close pending registered connection") + } + if got := hub.Count(); got != 0 { + t.Fatalf("Hub Count after Stop = %d, want 0", got) + } + if got := len(hub.register); got != 0 { + t.Fatalf("register queue length after Stop = %d, want 0", got) + } + if got := len(hub.broadcast); got != 0 { + t.Fatalf("broadcast queue length after Stop = %d, want 0", got) + } + if err := hub.TryRegister(NewConnection(nil)); !errors.Is(err, ErrHubStopped) { + t.Fatalf("TryRegister after Stop error = %v, want ErrHubStopped", err) + } + if err := hub.TryBroadcast([]byte("x")); !errors.Is(err, ErrHubStopped) { + t.Fatalf("TryBroadcast after Stop error = %v, want ErrHubStopped", err) + } +} + +func TestM11HubStopConcurrentTryRegisterClosesAll(t *testing.T) { + hub := NewHub() + go hub.Run() + for !hub.runStarted.Load() { + time.Sleep(time.Millisecond) + } + + var connsMu sync.Mutex + var conns []*Connection + var wg sync.WaitGroup + for i := 0; i < 200; i++ { + wg.Add(1) + go func() { + defer wg.Done() + conn := NewConnection(nil) + connsMu.Lock() + conns = append(conns, conn) + connsMu.Unlock() + _ = hub.TryRegister(conn) + }() + } + time.Sleep(time.Millisecond) + hub.Stop() + wg.Wait() + + connsMu.Lock() + defer connsMu.Unlock() + for i, conn := range conns { + if !conn.IsClosed() { + t.Fatalf("connection %d left open after concurrent Stop/TryRegister", i) + } + } + if got := hub.Count(); got != 0 { + t.Fatalf("Hub Count after concurrent Stop/TryRegister = %d, want 0", got) + } + if got := len(hub.register); got != 0 { + t.Fatalf("register queue length after concurrent Stop/TryRegister = %d, want 0", got) + } +} + +func TestM11HubNilGuards(t *testing.T) { + hub := NewHub() + go hub.Run() + t.Cleanup(hub.Stop) + + if err := hub.TryRegister(nil); !errors.Is(err, ErrNilConnection) { + t.Fatalf("TryRegister(nil) error = %v, want ErrNilConnection", err) + } + if err := hub.TryUnregister(nil); !errors.Is(err, ErrNilConnection) { + t.Fatalf("TryUnregister(nil) error = %v, want ErrNilConnection", err) + } +} diff --git a/ws/ws_origin_internal_test.go b/ws/ws_origin_internal_test.go new file mode 100644 index 0000000..bea5cb1 --- /dev/null +++ b/ws/ws_origin_internal_test.go @@ -0,0 +1,77 @@ +package ws + +import ( + "crypto/tls" + "net/http" + "net/http/httptest" + "testing" +) + +// TestSameOriginCheck_C7 验证默认 CheckOrigin 同源校验（防 CSWSH）： +// 空 Origin 放行（非浏览器）、同源放行、跨域拒绝。 +func TestSameOriginCheck_C7(t *testing.T) { + cases := []struct { + name string + origin string + host string + want bool + }{ + {"empty origin (non-browser)", "", "example.com", true}, + {"same origin", "http://example.com", "example.com", true}, + {"scheme mismatch", "https://example.com", "example.com", false}, + {"cross origin", "https://evil.com", "example.com", false}, + {"origin with port same", "http://example.com:8080", "example.com:8080", true}, + {"origin with port diff", "http://example.com:8080", "example.com:9090", false}, + {"malformed origin", "://bad", "example.com", false}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + req := httptest.NewRequest(http.MethodGet, "/", nil) + if tc.origin != "" { + req.Header.Set("Origin", tc.origin) + } + req.Host = tc.host + got := sameOriginCheck(req) + if got != tc.want { + t.Errorf("sameOriginCheck origin=%q host=%q = %v, want %v", tc.origin, tc.host, got, tc.want) + } + }) + } +} + +func TestSameOriginCheckHTTPS_C7(t *testing.T) { + req := httptest.NewRequest(http.MethodGet, "https://example.com/ws", nil) + req.TLS = &tls.ConnectionState{} + req.Header.Set("Origin", "https://example.com") + if !sameOriginCheck(req) { + t.Fatal("sameOriginCheck should allow matching https origin for TLS request") + } + req.Header.Set("Origin", "http://example.com") + if sameOriginCheck(req) { + t.Fatal("sameOriginCheck should reject origin with mismatched scheme") + } +} + +// TestAllowOrigins_C7：AllowOrigins 仅放行白名单 Origin。 +func TestAllowOrigins_C7(t *testing.T) { + check := AllowOrigins("https://a.com", "https://b.com") + cases := []struct { + origin string + want bool + }{ + {"", true}, // 非浏览器放行 + {"https://a.com", true}, // 白名单 + {"https://b.com", true}, // 白名单 + {"https://evil.com", false}, + {"http://a.com", false}, // scheme 不符 + } + for _, tc := range cases { + req := httptest.NewRequest(http.MethodGet, "/", nil) + if tc.origin != "" { + req.Header.Set("Origin", tc.origin) + } + if got := check(req); got != tc.want { + t.Errorf("AllowOrigins origin=%q = %v, want %v", tc.origin, got, tc.want) + } + } +} diff --git a/ws/ws_send_internal_test.go b/ws/ws_send_internal_test.go new file mode 100644 index 0000000..084a440 --- /dev/null +++ b/ws/ws_send_internal_test.go @@ -0,0 +1,86 @@ +package ws + +import ( + "errors" + "net/http" + "net/http/httptest" + "strings" + "sync" + "testing" + "time" + + "github.com/gorilla/websocket" +) + +// 回归 C2a-residual：Send 非阻塞——send 缓冲满后立即返回 ErrSendBufferFull， +// 不阻塞调用方。旧实现（阻塞 select + 缓冲满）会阻塞，Hub 广播持写锁期间 stall。 +// +// 用 internal test 直接构造 Connection（绕过 Handle），不启动 writePump 消费 send， +// 填满缓冲后 Send 必须立即返回 ErrSendBufferFull。 +func TestSendNonBlockingBufferFullInternal(t *testing.T) { + // 建一对真实 websocket conn 作为底层。 + var srvConn *websocket.Conn + var mu sync.Mutex + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + u := websocket.Upgrader{CheckOrigin: func(*http.Request) bool { return true }} + c, err := u.Upgrade(w, r, nil) + if err != nil { + return + } + mu.Lock() + srvConn = c + mu.Unlock() + // 阻塞读保持连接存活。 + for { + if _, _, err := c.ReadMessage(); err != nil { + return + } + } + })) + defer srv.Close() + dialer := &websocket.Dialer{HandshakeTimeout: 2 * time.Second} + client, _, err := dialer.Dial("ws"+strings.TrimPrefix(srv.URL, "http")+"/", nil) + if err != nil { + t.Fatalf("dial: %v", err) + } + defer client.Close() + + // 等待服务端 conn 就绪。 + deadline := time.Now().Add(2 * time.Second) + for time.Now().Before(deadline) { + mu.Lock() + if srvConn != nil { + mu.Unlock() + break + } + mu.Unlock() + time.Sleep(5 * time.Millisecond) + } + if srvConn == nil { + t.Fatal("server-side conn not ready") + } + defer srvConn.Close() + + conn := NewConnection(srvConn) + defer conn.Close() + + // 不启动 writePump，send 无消费者。填满缓冲（256）。 + for i := 0; i < 256; i++ { + if err := conn.Send([]byte("x")); err != nil { + t.Fatalf("filling buffer[%d] err = %v", i, err) + } + } + // 第 257 个必须立即返回 ErrSendBufferFull（非阻塞）。 + done := make(chan error, 1) + go func() { + done <- conn.Send([]byte("overflow")) + }() + select { + case err := <-done: + if !errors.Is(err, ErrSendBufferFull) { + t.Errorf("overflow Send err = %v, want ErrSendBufferFull", err) + } + case <-time.After(2 * time.Second): + t.Fatal("Send on full buffer blocked (should be non-blocking)") + } +} diff --git a/ws/ws_test.go b/ws/ws_test.go new file mode 100644 index 0000000..32ba196 --- /dev/null +++ b/ws/ws_test.go @@ -0,0 +1,135 @@ +package ws_test + +import ( + "errors" + "testing" + "time" + + "github.com/EthanCodeCraft/xlgo-core/ws" +) + +func TestMessageType(t *testing.T) { + if ws.TypeText != "text" { + t.Errorf("TypeText = %s, want text", ws.TypeText) + } + if ws.TypeBinary != "binary" { + t.Errorf("TypeBinary = %s, want binary", ws.TypeBinary) + } + if ws.TypePing != "ping" { + t.Errorf("TypePing = %s, want ping", ws.TypePing) + } + if ws.TypePong != "pong" { + t.Errorf("TypePong = %s, want pong", ws.TypePong) + } + if ws.TypeClose != "close" { + t.Errorf("TypeClose = %s, want close", ws.TypeClose) + } +} + +func TestMessage(t *testing.T) { + msg := ws.Message{ + Type: ws.TypeText, + Content: "hello world", + } + + if msg.Type != ws.TypeText { + t.Error("Message Type failed") + } + if msg.Content != "hello world" { + t.Error("Message Content failed") + } +} + +func TestNewConnection(t *testing.T) { + // NewConnection 需要 websocket.Conn，无法直接测试 + // 仅验证结构体定义存在 +} + +func TestNewHub(t *testing.T) { + hub := ws.NewHub() + if hub == nil { + t.Error("NewHub should not return nil") + } +} + +func TestHubCount(t *testing.T) { + hub := ws.NewHub() + + // 无连接时计数应为 0 + count := hub.Count() + if count != 0 { + t.Errorf("Hub Count = %d, want 0", count) + } +} + +func TestHubBroadcast(t *testing.T) { + hub := ws.NewHub() + + // 广播消息（无连接时也应正常） + if err := hub.TryBroadcast([]byte("test message")); err == nil { + t.Error("TryBroadcast on a hub that has not Run should fail fast") + } +} + +func TestHubBroadcastJSON(t *testing.T) { + hub := ws.NewHub() + go hub.Run() + t.Cleanup(hub.Stop) + + deadline := time.Now().Add(time.Second) + for { + err := hub.BroadcastJSON(map[string]string{"key": "value"}) + if err == nil { + return + } + if !errors.Is(err, ws.ErrHubNotRunning) || time.Now().After(deadline) { + t.Errorf("BroadcastJSON error: %v", err) + return + } + time.Sleep(time.Millisecond) + } +} + +func TestDefaultHandler(t *testing.T) { + handler := ws.DefaultHandler{} + + // 测试空处理器不会 panic + handler.OnConnect(nil) + handler.OnMessage(nil, nil) + handler.OnClose(nil) + handler.OnError(nil, nil) +} + +func TestDefaultHandlerWithFuncs(t *testing.T) { + connectCalled := false + messageCalled := false + + handler := ws.DefaultHandler{ + OnConnectFunc: func(conn *ws.Connection) { + connectCalled = true + }, + OnMessageFunc: func(conn *ws.Connection, message []byte) { + messageCalled = true + }, + } + + handler.OnConnect(nil) + handler.OnMessage(nil, nil) + + if !connectCalled { + t.Error("OnConnectFunc should be called") + } + if !messageCalled { + t.Error("OnMessageFunc should be called") + } +} + +func TestHandlerFunc(t *testing.T) { + var handlerFunc ws.HandlerFunc = func(conn *ws.Connection, message []byte) { + // 处理消息 + } + + if handlerFunc == nil { + t.Error("HandlerFunc should not be nil") + } +}