chore(git): 更新.gitignore以忽略新的本地文件

2025-11-30 08:33:17 +08:00
parent 4b4980820f
commit a4b6c5011e
58 changed files with 19353 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/配置管理/Redis配置.md
+++ b/.qoder/repowiki/zh/content/配置管理/Redis配置.md
@@ -0,0 +1,331 @@
+# Redis配置
+
+<cite>
+**本文引用的文件**
+- [pkg/redis/redis.go](file://pkg/redis/redis.go)
+- [pkg/redis/manager.go](file://pkg/redis/manager.go)
+- [pkg/config/config.go](file://pkg/config/config.go)
+- [pkg/config/manager.go](file://pkg/config/manager.go)
+- [cmd/server/main.go](file://cmd/server/main.go)
+- [internal/handler/auth_handler.go](file://internal/handler/auth_handler.go)
+- [internal/service/verification_service.go](file://internal/service/verification_service.go)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向CarrotSkin项目的开发者，系统性梳理Redis缓存系统的配置与使用方式，重点说明以下内容：
+- RedisConfig结构体中的各配置项（host、port、password、database、pool_size）的作用与默认值
+- pool_size参数对并发性能的影响机制
+- 如何通过REDIS_*环境变量动态覆盖配置
+- 结合RedisConfig结构体与连接初始化逻辑，给出多环境部署建议与连接池大小调优方法
+
+## 项目结构
+Redis配置与使用涉及如下关键模块：
+- 配置加载与默认值：pkg/config
+- Redis客户端封装与连接初始化：pkg/redis
+- 应用启动流程：cmd/server/main.go
+- 业务使用示例：internal/handler与internal/service
+
+```mermaid
+graph TB
+subgraph "配置层"
+CFG["pkg/config/config.go<br/>RedisConfig结构体与默认值"]
+CM["pkg/config/manager.go<br/>配置单例管理"]
+end
+subgraph "Redis层"
+RC["pkg/redis/redis.go<br/>Client封装与New初始化"]
+RM["pkg/redis/manager.go<br/>Init/GetClient/MustGetClient"]
+end
+subgraph "应用层"
+MAIN["cmd/server/main.go<br/>启动时初始化Redis"]
+AUTH["internal/handler/auth_handler.go<br/>使用MustGetClient()"]
+SVC["internal/service/verification_service.go<br/>验证码场景使用Redis"]
+end
+CFG --> CM
+CM --> MAIN
+MAIN --> RM
+RM --> RC
+AUTH --> RM
+SVC --> RC
+```
+
+图表来源
+- [pkg/config/config.go](file://pkg/config/config.go#L49-L56)
+- [pkg/config/manager.go](file://pkg/config/manager.go#L19-L46)
+- [pkg/redis/redis.go](file://pkg/redis/redis.go#L21-L52)
+- [pkg/redis/manager.go](file://pkg/redis/manager.go#L20-L46)
+- [cmd/server/main.go](file://cmd/server/main.go#L52-L61)
+- [internal/handler/auth_handler.go](file://internal/handler/auth_handler.go#L27-L33)
+- [internal/service/verification_service.go](file://internal/service/verification_service.go#L40-L77)
+
+章节来源
+- [pkg/config/config.go](file://pkg/config/config.go#L49-L56)
+- [pkg/config/manager.go](file://pkg/config/manager.go#L19-L46)
+- [pkg/redis/redis.go](file://pkg/redis/redis.go#L21-L52)
+- [pkg/redis/manager.go](file://pkg/redis/manager.go#L20-L46)
+- [cmd/server/main.go](file://cmd/server/main.go#L52-L61)
+- [internal/handler/auth_handler.go](file://internal/handler/auth_handler.go#L27-L33)
+- [internal/service/verification_service.go](file://internal/service/verification_service.go#L40-L77)
+
+## 核心组件
+- RedisConfig结构体
+  - 字段：host、port、password、database、pool_size
+  - 默认值：由配置加载器在未显式提供时设置
+- 配置加载与环境变量覆盖
+  - 默认值设置、环境变量前缀、映射与覆盖逻辑
+- Redis客户端封装与初始化
+  - Client封装、New初始化、Ping连通性校验、连接池大小
+  - 单例初始化与获取接口（Init/GetClient/MustGetClient）
+
+章节来源
+- [pkg/config/config.go](file://pkg/config/config.go#L49-L56)
+- [pkg/config/config.go](file://pkg/config/config.go#L135-L188)
+- [pkg/config/config.go](file://pkg/config/config.go#L190-L236)
+- [pkg/config/config.go](file://pkg/config/config.go#L238-L304)
+- [pkg/redis/redis.go](file://pkg/redis/redis.go#L21-L52)
+- [pkg/redis/manager.go](file://pkg/redis/manager.go#L20-L46)
+
+## 架构总览
+下图展示Redis配置与初始化在应用生命周期中的位置与交互。
+
+```mermaid
+sequenceDiagram
+participant Main as "main.go"
+participant CfgMgr as "config.Manager"
+participant Cfg as "config.Config"
+participant RedisMgr as "redis.Manager"
+participant RedisClient as "redis.Client"
+Main->>CfgMgr : Init()
+CfgMgr-->>Main : 配置实例
+Main->>RedisMgr : Init(RedisConfig, Logger)
+RedisMgr->>RedisClient : New(cfg, logger)
+RedisClient->>RedisClient : Ping()连通性校验
+RedisMgr-->>Main : 初始化完成
+Main-->>Main : 启动HTTP服务
+```
+
+图表来源
+- [cmd/server/main.go](file://cmd/server/main.go#L27-L61)
+- [pkg/config/manager.go](file://pkg/config/manager.go#L19-L46)
+- [pkg/config/config.go](file://pkg/config/config.go#L108-L133)
+- [pkg/redis/manager.go](file://pkg/redis/manager.go#L20-L46)
+- [pkg/redis/redis.go](file://pkg/redis/redis.go#L21-L52)
+
+## 详细组件分析
+
+### RedisConfig结构体与默认值
+- 字段定义与含义
+  - host：Redis服务器地址，默认值由配置加载器设置
+  - port：Redis服务器端口，默认值由配置加载器设置
+  - password：Redis认证密码，默认值由配置加载器设置
+  - database：Redis数据库索引，默认值由配置加载器设置
+  - pool_size：Redis连接池大小，默认值由配置加载器设置
+- 默认值来源
+  - 配置加载器在未显式提供时设置默认值，确保应用在最小配置下仍可运行
+- 环境变量映射
+  - REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_DATABASE
+  - REDIS_POOL_SIZE用于覆盖连接池大小
+
+章节来源
+- [pkg/config/config.go](file://pkg/config/config.go#L49-L56)
+- [pkg/config/config.go](file://pkg/config/config.go#L135-L188)
+- [pkg/config/config.go](file://pkg/config/config.go#L190-L236)
+- [pkg/config/config.go](file://pkg/config/config.go#L238-L304)
+
+### 连接初始化与Ping校验
+- 初始化流程
+  - 通过redis.NewClient创建客户端，使用RedisConfig中的host/port/password/database/pool_size
+  - 使用Ping进行连通性校验，失败则返回错误
+  - 初始化成功后记录日志，包含host/port/database
+- 并发与线程安全
+  - Redis初始化采用once.Do保证全局仅初始化一次
+  - GetClient/MustGetClient提供线程安全的获取方式
+
+```mermaid
+flowchart TD
+Start(["进入Init(cfg, logger)"]) --> Once["once.Do执行"]
+Once --> NewClient["创建redis.Client(options)"]
+NewClient --> Ping["Ping()连通性校验"]
+Ping --> Ok{"Ping成功？"}
+Ok --> |否| Err["返回错误"]
+Ok --> |是| Log["记录连接成功日志"]
+Log --> Done(["返回Client实例"])
+Err --> Done
+```
+
+图表来源
+- [pkg/redis/manager.go](file://pkg/redis/manager.go#L20-L46)
+- [pkg/redis/redis.go](file://pkg/redis/redis.go#L21-L52)
+
+章节来源
+- [pkg/redis/manager.go](file://pkg/redis/manager.go#L20-L46)
+- [pkg/redis/redis.go](file://pkg/redis/redis.go#L21-L52)
+
+### 环境变量动态覆盖机制
+- 环境变量前缀与映射
+  - 配置加载器设置环境变量前缀为CARROTSKIN，并将redis.*字段绑定到REDIS_*环境变量
+- 动态覆盖逻辑
+  - 在解析默认值与环境变量后，额外处理REDIS_POOL_SIZE以覆盖连接池大小
+- 使用建议
+  - 开发环境可使用较小pool_size；生产环境根据QPS与并发峰值评估后设置
+
+章节来源
+- [pkg/config/config.go](file://pkg/config/config.go#L108-L133)
+- [pkg/config/config.go](file://pkg/config/config.go#L190-L236)
+- [pkg/config/config.go](file://pkg/config/config.go#L238-L304)
+
+### 业务使用示例
+- 验证码场景
+  - 发送验证码前检查频率限制键是否存在
+  - 将验证码写入Redis并设置过期时间
+  - 发送邮件失败时删除验证码键
+- 登录/注册/重置密码
+  - Handler层通过MustGetClient()获取Redis客户端
+  - Service层调用Redis进行验证码校验与清理
+
+```mermaid
+sequenceDiagram
+participant H as "auth_handler"
+participant S as "verification_service"
+participant R as "redis.Client"
+H->>R : MustGetClient()
+H->>S : SendVerificationCode(ctx, R, emailService, email, type)
+S->>R : Exists(rateLimitKey)
+alt 存在频率限制
+S-->>H : 返回“发送过于频繁”
+else 无频率限制
+S->>R : Set(codeKey, code, expiration)
+S->>R : Set(rateLimitKey, "1", rateLimit)
+S-->>H : 发送成功
+end
+```
+
+图表来源
+- [internal/handler/auth_handler.go](file://internal/handler/auth_handler.go#L27-L33)
+- [internal/service/verification_service.go](file://internal/service/verification_service.go#L40-L77)
+- [pkg/redis/manager.go](file://pkg/redis/manager.go#L31-L46)
+
+章节来源
+- [internal/handler/auth_handler.go](file://internal/handler/auth_handler.go#L27-L33)
+- [internal/service/verification_service.go](file://internal/service/verification_service.go#L40-L77)
+
+## 依赖关系分析
+- 配置到Redis的依赖链
+  - config.Manager -> config.Config -> redis.Manager -> redis.Client
+- 启动阶段依赖
+  - main.go在启动时顺序初始化配置、日志、数据库、JWT、Redis、对象存储、邮件服务
+- 业务依赖
+  - Handler与Service通过redis.Manager提供的单例接口使用Redis
+
+```mermaid
+graph LR
+CFG["config.Config"] --> RM["redis.Manager"]
+RM --> RC["redis.Client"]
+MAIN["cmd/server/main.go"] --> RM
+AUTH["internal/handler/auth_handler.go"] --> RM
+SVC["internal/service/verification_service.go"] --> RC
+```
+
+图表来源
+- [cmd/server/main.go](file://cmd/server/main.go#L27-L61)
+- [pkg/config/manager.go](file://pkg/config/manager.go#L19-L46)
+- [pkg/redis/manager.go](file://pkg/redis/manager.go#L20-L46)
+- [internal/handler/auth_handler.go](file://internal/handler/auth_handler.go#L27-L33)
+- [internal/service/verification_service.go](file://internal/service/verification_service.go#L40-L77)
+
+章节来源
+- [cmd/server/main.go](file://cmd/server/main.go#L27-L61)
+- [pkg/config/manager.go](file://pkg/config/manager.go#L19-L46)
+- [pkg/redis/manager.go](file://pkg/redis/manager.go#L20-L46)
+- [internal/handler/auth_handler.go](file://internal/handler/auth_handler.go#L27-L33)
+- [internal/service/verification_service.go](file://internal/service/verification_service.go#L40-L77)
+
+## 性能考量
+- pool_size对并发性能的影响机制
+  - 连接池大小决定同时可用的底层TCP连接数
+  - 在高并发场景下，若pool_size过小，可能出现连接争用与等待，导致延迟上升
+  - 若pool_size过大，会增加Redis端的连接管理开销与资源占用
+- 调优建议
+  - 基准测试：在预生产环境模拟峰值QPS，逐步提升pool_size并观察延迟与错误率
+  - 观察指标：监控Redis连接数、等待队列长度、命令执行延迟
+  - 平衡策略：在满足延迟目标的前提下，尽量保持pool_size适中，避免过度放大
+- 与业务场景的匹配
+  - 验证码发送/校验属于短时高频写入场景，适度增大pool_size有助于降低写入抖动
+  - 读多写少的场景可结合Pipeline/TxPipeline减少RTT，进一步提升吞吐
+
+[本节为通用性能讨论，不直接分析具体文件]
+
+## 故障排查指南
+- 初始化失败
+  - 症状：启动时报Redis连接失败
+  - 排查要点：确认REDIS_HOST/REDIS_PORT/REDIS_PASSWORD/REDIS_DATABASE是否正确；检查网络连通性；确认Redis服务状态
+  - 参考实现：初始化时进行Ping校验，失败返回错误
+- 未初始化即使用
+  - 症状：调用MustGetClient()时panic或GetClient()返回错误
+  - 排查要点：确保在main中先调用redis.Init()，再启动HTTP服务
+- 频繁超时或错误
+  - 症状：业务调用Redis出现超时或错误
+  - 排查要点：检查pool_size是否过小；确认Redis资源瓶颈；优化业务逻辑减少阻塞操作
+- 验证码发送过于频繁
+  - 症状：提示发送过于频繁
+  - 排查要点：检查频率限制键是否存在且未过期；确认业务逻辑正确清理
+
+章节来源
+- [pkg/redis/redis.go](file://pkg/redis/redis.go#L21-L52)
+- [pkg/redis/manager.go](file://pkg/redis/manager.go#L31-L46)
+- [cmd/server/main.go](file://cmd/server/main.go#L52-L61)
+- [internal/service/verification_service.go](file://internal/service/verification_service.go#L40-L77)
+
+## 结论
+- RedisConfig提供了简洁明确的配置项，配合默认值与环境变量覆盖，可在多环境中快速部署
+- pool_size直接影响并发性能，应结合业务负载与Redis资源进行调优
+- 通过once.Do保证Redis客户端单例初始化，配合MustGetClient/GetClient简化了业务侧使用
+- 建议在生产环境启用合理的pool_size，并持续监控连接池利用率与延迟指标
+
+[本节为总结性内容，不直接分析具体文件]
+
+## 附录
+
+### 配置项与默认值对照表
+- host：Redis主机地址，默认值由配置加载器设置
+- port：Redis端口，默认值由配置加载器设置
+- password：Redis认证密码，默认值由配置加载器设置
+- database：Redis数据库索引，默认值由配置加载器设置
+- pool_size：Redis连接池大小，默认值由配置加载器设置
+
+章节来源
+- [pkg/config/config.go](file://pkg/config/config.go#L49-L56)
+- [pkg/config/config.go](file://pkg/config/config.go#L135-L188)
+
+### 环境变量覆盖清单
+- REDIS_HOST：覆盖host
+- REDIS_PORT：覆盖port
+- REDIS_PASSWORD：覆盖password
+- REDIS_DATABASE：覆盖database
+- REDIS_POOL_SIZE：覆盖pool_size
+
+章节来源
+- [pkg/config/config.go](file://pkg/config/config.go#L190-L236)
+- [pkg/config/config.go](file://pkg/config/config.go#L238-L304)
+
+### 多环境部署建议
+- 开发环境
+  - 使用较小pool_size（如默认值），便于本地调试
+  - 通过REDIS_*环境变量快速切换Redis实例
+- 预生产/生产环境
+  - 基于基准测试确定pool_size，结合监控指标持续优化
+  - 使用独立database索引隔离不同环境数据
+  - 对password进行严格管理，避免明文配置
+
+[本节为通用建议，不直接分析具体文件]