Skip to content

v1.0.3

Choose a tag to compare

View all tags
@EthanCodeCraft EthanCodeCraft released this 22 Jun 14:17
v1.0.3
dcfd24b

v1.0.3 — Bug Fix Release

定位：bug fix release。收口 v1.0.2 引入的破坏性清理，并修复 4 个轻量 bug + 依赖复查 + 版本号治理 + 文档对齐。

完整变更说明见 CHANGELOG.md。

⚠️ Breaking Changes（升级前必读）

1. 错误码体系重构（response 包）

修复 CodeSuccess 与 CodeInvalidParams 撞码的生产级 bug（两者都等于 1，导致业务错误响应被前端误判为成功）。

常量 旧值 新值
response.CodeSuccess 1 0
response.CodeFail 0 1

移除：response.CodeInvalidParams、response.ErrInvalidParams

迁移：

// ❌ 旧（编译失败）
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 阶段直接报错。

2. 清理 v1.0.2 兼容别名（database 包）

// ❌ 移除
database.InitMySQL(cfg)
database.InitMySQLWithReplicas(cfg, replicas)
(*Manager).InitMySQL / InitMySQLWithReplicas

// ✅ 改用（驱动由 cfg.Database.Driver 决定）
database.InitDB(cfg)
database.InitDBWithReplicas(cfg, replicas)

3. CORS 中间件行为收紧（Security 修复）

Access-Control-Allow-Credentials 不再永远是 true。如果你之前依赖"默认允许凭证"的隐式行为，需显式启用：

cors:
  allowed_origins: ["https://your-frontend.example"]
  allow_credentials: true

🐛 Fixed

  • JWT JTI 生成忽略 rand.Read 错误（jwt）— generateJTI() 改为 (string, error)，GenerateToken / GenerateTokenWithCustomExpiry 传播错误
  • QueryBuilder.Page 统计行数被残留 Limit 截断（repository）— countDB 加 .Limit(-1).Offset(-1) 清除残留分页条件
  • OSS / 本地存储文件名冲突（storage）— 新增 uniqueFilename(now, ext)（<unixNano>-<8字节crypto/rand hex>.<ext>），4 处上传路径统一改用
  • 数据库重试策略对不可恢复错误无效（database）— 新增 isTransientDBError，Access denied / Unknown database / invalid DSN / unknown driver 等首次出现即返回，不再无意义重试 5 次

🔒 Security

CORS 中间件按 W3C 规范修复：

  1. Access-Control-Allow-Credentials 只在显式启用且 Origin 非 * 时才发送
  2. * + credentials: true 场景回显具体 Origin（避免被浏览器拒绝）
  3. 自动加 Vary: Origin，防止 CDN/网关缓存串扰
  4. 非白名单 Origin 不再被回显

📦 Dependencies

  • go mod tidy 补全 postgres 方言传递依赖：jackc/pgx 家族、golang.org/x/sync；gorm.io/driver/postgres 提升为直接依赖

  • 安全补丁升级（无 API 变更）：

    依赖 旧 新
    golang.org/x/crypto v0.49.0 v0.53.0
    golang-jwt/jwt/v5 v5.2.1 v5.3.1
    gorilla/websocket v1.5.1 v1.5.3

  • 暂缓升级（留待 v1.0.4 / v1.1）：gin v1.9→v1.12、validator v10.19→v10.30、gorm v1.25→v1.31、aliyun-oss-go-sdk v2→v3（major 破坏性）等

🗑️ Removed

  • 死代码 database.DBResolver（BeforeQuery 从未注册到 GORM callback chain）。需要 callback 级自动读写分离请接入官方 gorm.io/plugin/dbresolver
  • 292 行"评分/理由"自夸注释（23 个文件）— AI 生成遗留，对外发布不专业

✨ Added

  • console 包显式 level 控制：SetLevel / WithLevel / LevelSilent，atomic.Int32 并发安全。console 是开发期彩色 stdout 工具，不写文件、不感知环境
  • 新增测试：jwt / repository / storage / database / router / middleware / app
  • 文档：新增 CHANGELOG.md、Version_v1.0.2_report.md；更新 README / GUIDE 顶部更新日志

🔄 Changed

  • 文件重命名 database/mysql.go → database/manager.go（导入路径无变化，公开 API 全部保留）
  • Logger 拆分三独立 core 修复 Tee 重复写入：Logger→app.log、APILog()→api.log、DBLog()→database.log，互不串扰。新增 logger.Close()，生产默认级别调整为 Info

    升级注意：日志目录会新增 logs/app.log，运维采集脚本如有需要请补上

  • 版本号常量化：app.go 新增 const Version 作为唯一版本号来源，CLI / 脚手架模板引用之，发版只需改一处

升级速查

  1. 全局替换前端 code === 1（成功）→ code === 0
  2. 移除 response.ErrInvalidParams / CodeInvalidParams 引用，改业务自定义
  3. database.InitMySQL* → database.InitDB*
  4. 检查 CORS 配置：若依赖凭证，显式设 allow_credentials: true
  5. 运维：日志采集补 logs/app.log
go get github.com/EthanCodeCraft/xlgo-core@v1.0.3
go mod tidy

Full Changelog: v1.0.1...v1.0.3

Assets 2
Loading