frostbyte_neo/xlgo-core
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity
44 Commits 1 Branch 8 Tags
main
Commit Graph

9 Commits

Author SHA1 Message Date
杭州明婳科技 905cf7db4f Merge branch 'refactor/consolidate-failable-apis' 2026-07-12 22:23:41 +08:00
杭州明婳科技 9e11f8f007 refactor: 同义可失败 API 收敛（cache/jwt/storage/ratelimit breaking change） 
按"同一能力只保留一个主入口、框架不替上层吞错、安全路径默认 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/cache.Exists（带 error）；GetWithPrefix 改为 (bool,error)

jwt:
- TokenBlacklist.IsBlacklisted 改为 (bool, error)，删除 IsBlacklistedE
- IsTokenRevoked 改为 (bool, error)
- ParseToken 默认从 fail-open 改为 fail-closed：黑名单后端不可检查时返回
  ErrBlacklistUnavailable 拒绝该 Token（无 Redis 部署不再支持可靠撤销）
- 删除 ParseTokenFailClosed（主 API 已 fail-closed）
- 保留 ParseTokenWithBlacklistPolicy + BlacklistPolicy/BlacklistFailOpen/BlacklistFailClosed
  供显式 fail-open（仅无 Redis 或低安全场景）

storage:
- Storage.Exists 改为 (bool, error)：存在 (true,nil)、不存在 (false,nil)、
  未初始化/路径非法/穿越/后端错误返回 (false,err)
- LocalStorage.Exists 区分 os.IsNotExist 与其他 Stat 错误
- OSSStorage.Exists 区分 OSS 404/NoSuchKey 与鉴权/网络错误
- 包级 storage.Exists 同步签名，未初始化返回 ErrStorageNotInitialized
- 新增 ErrReadTooLarge：Local/OSSStorage.Get 读取超 maxReadBytes 上限原误用
  ErrInvalidPath（语义不贴切），改为 ErrReadTooLarge

ratelimit:
- NewRedisRateLimiter 加 opts ...RedisRateLimiterOption，新增 WithFailClosed(bool)
  替代原 NewRedisRateLimiterFailClosed
- RedisRateLimit/CustomRedisRateLimit/RedisRateLimitWithIdentifier 同步加 opts 参数
- 删除 NewRedisRateLimiterFailClosed/RedisRateLimitFailClosed/CustomRedisRateLimitFailClosed
- UploadRedisRateLimit 由 fail-open 改为 fail-closed（资源敏感操作，Redis 故障时拒绝）

测试与文档:
- cache_m10_internal_test.go 重写 4 个 M10 测试为 Get/Exists 契约测试，新增 mock 编译覆盖
- jwt_test.go 改 4 处；jwt_c9c_internal_test.go 改 IsTokenRevoked 2-value
- examples/full/main_test.go 加 miniredis 注入（ParseToken fail-closed 后认证需 Redis）
- middleware_test.go 改 5 处 FailClosed 调用为 WithFailClosed(true)；auth_test.go 加 Redis
- storage 测试改 6 处 Exists/Get 断言为新签名/错误类型
- README/GUIDE 同步示例为新签名；CHANGELOG 新增 Breaking 升级说明与迁移示例

验证：go build / go vet / go test -race -count=1 ./... 全绿。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-07-12 22:22:10 +08:00
杭州明婳科技 ffcb1a77b9 docs: 注释/文档一致性审查修复（A/B/C 三档共 23 项） 
对 60 个非测试源文件做文档/注释/代码一致性审查，修复 23 项。全部为注释/文档
改动 + 1 处死代码删除，无运行逻辑变更，无 breaking change。

A 档·实质错误（10 项，会误导下游）：
- app.go: closeResources 三连契约注释统一修正--failAfterInit 走
  rollbackReplacedResources 不走 closeResources，closeResources 仅供 doShutdown 复用
- database/manager.go: RandomPicker 注释从过时的 rand.Intn/issue 54899 改为 crypto/rand
- model/base.go: datetime(0) 与“亚秒精度”矛盾，改为 datetime(6)
- cache/keybuilder.go: 三处示例下划线分隔符改为冒号（与默认分隔符 : 一致）
- repository/repository.go: Delete 接口注释从绝对“软删除”改为条件性；
  UpdateFields 示例移除把字段名当 WHERE 条件的误用写法
- middleware/csrf.go: CSRFToken 注释从“用于 API 模式”改为 Cookie/双重提交模式说明
- examples/full/main.go: POST /users 补上“需 Authorization”标注；删除 _ = app 死代码
- utils/random.go: RandInt/RandInt64 补 min==max 边界说明（对齐 RandIntSecure 写法）

B 档·导出符号注释缺失/不完整（6 项）：
- ws/ws.go: 5 个 Type* 常量、4 个 Err* 变量补注释
- console/console.go: 5 个 Level 常量补注释
- jwt/jwt.go: 2 个 Blacklist 常量补注释
- router/router.go: 包级 GroupWithMiddlewareGroup 补注释
- middleware/ratelimit.go: NewRateLimiter 补 panic 条件与 Stop 生命周期说明

C 档·描述不完整（7 项）：
- utils/strings.go Substr、convert.go CalcPageCount/CalcOffset、datetime.go
  StartOfMonth/EndOfMonth、file.go CopyFile、validator.go IsChinese、crypto.go HashFile
  补全边界/默认行为/返回值语义
- response/error.go: WithDetail 补 nil 接收者行为说明

验证：go build / go vet / go test -race 全绿。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-07-12 18:47:12 +08:00
杭州明婳科技 2529b0a074 fix database lifecycle cancellation 2026-07-08 21:25:18 +08:00
杭州明婳科技 4ccbbfbf1b fix full example login password flow 2026-07-08 19:36:43 +08:00
杭州明婳科技 56352fdd81 fix: harden framework lifecycle and middleware safety 2026-07-07 00:19:19 +08:00
杭州明婳科技 18e4f7e891 fix: ServerConfig 加 Host 字段 + 面向用户文案统一中文 
- ServerConfig 新增 Host 字段：空=监听所有接口(兼容)，设值=绑定指定地址
  (127.0.0.1 仅本机 / 内网IP 绑定指定网卡)，避免生产暴露 0.0.0.0
- app.go 启动地址改 host:port，日志区分"所有接口"/指定地址
- 面向用户/调用的文案统一中文：
  - middleware/recover.go: "Panic recovered"→"panic 已恢复"，"Panic: %v"→"服务器内部错误: %v"
  - middleware/logger.go: 5 处日志消息改中文
  - middleware/metrics.go: 3 个 Prometheus Help 改中文
  - app.go/database/manager.go/logger.go: 英文 error 改中文
- 保留英文：JSON 协议字段名、Prometheus metric Name、MySQL 错误串匹配、技术专有名词
- CLI 模板与 example 配置加 host 注释

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-06-23 23:12:40 +08:00
杭州明婳科技 0c9f256dfc feat(v1.1.0): HA & Manager 化 
对应体检报告 #10-#24，一次性完成 v1.1.0 全部 13 项：

- #10 storage/cache/redis/jwt/logger 五组件 Manager 化（XxxManager + DefaultXxx + SetDefaultXxxManager，包级 facade 保留兼容）
- #11 删除 wire 包 + 清理 StartServerWithPort/GracefulShutdown 双轨
- #12 Lifecycle Hooks（OnInit/OnStart/OnReady/OnStop）
- #13 Server 参数配置化（timeout/TLS/unix_socket/response_mode）
- #14 JWTConfig.Expire 改 time.Duration + 删 AppConfig.TokenExpire
- #15 response Mode 开关（ModeBusiness/ModeREST）
- #16 Config.Validate 启动期校验
- #17 livez/readyz 探针路由
- #18 Prometheus metrics 中间件 + /metrics
- #19 请求级 Timeout 中间件
- #21 主库探活 + replica 健康剔除
- #22 App.Go + in-flight goroutine 管理
- #24 RequestID 默认装入 + #23 核对

Breaking：删 wire、删 TokenExpire、JWTConfig.Expire 类型变更、删双轨函数。
详见 CHANGELOG 升级说明。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-06-23 10:41:05 +08:00
杭州明婳科技 deb3cc71bf feat(v1.0.4): DX & Docs 改进 
按报告 v1.0.4 路线图完成 5 项开发体验与文档改进：

#25 模块路径文档改进：
- 保留 -core 后缀（xlgo 是多产品系列：xlgo-core/xlgo-orm/xlgo-ai）
- README 快速开始补完整 import 示例 + 新增「模块路径与包名」小节
- CLAUDE.md Import Path Note 措辞明确化

#27 Without* Option 定位文档化：
- 调研确认 Without* 有真实用例（测试覆盖 + NewFullStack 后排除单项）
- 不删不标 Deprecated，在 app.go 注释 + README 说明其定位

#28 CLI 多模板：
- xlgo new --template minimal/api/fullstack
- minimal 轻量HTTP无依赖，api 标准业务分层（默认），fullstack 全组件
- 三模板实测生成正确

#29 examples/ 目录：
- examples/minimal（50行可跑，无外部依赖）
- examples/full（mysql+redis+jwt+user CRUD）
- examples/README.md

#30 文档结构：
- Version_*.md + report.md 移到 docs/plans/（v2.0-review.md）
- 新增 docs/README.md 索引
- CHANGELOG/GUIDE 留根目录（按惯例）
- .gitignore 整理

build/vet/test + examples 编译全绿。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-06-22 23:21:59 +08:00