pkg/ 是可复用公共库的集合，对应 Java 侧的 ruoyi-common-*。所有包都不允许反向 import internal（少数例外靠回调反向注册，如 oplog 的 Recorder、audit 的审计身份）。下面按职责列出每个包的参考页。
| 包 | 职责 | 参考页 |
|---|---|---|
| response | 统一 HTTP 响应结构与快捷构造 | /pkg-reference/response-errs |
| errs | 业务异常类型，供 handler c.Error 登记 | /pkg-reference/response-errs |
| config | viper 加载并合并多 yaml 配置 | /pkg-reference/config-database-redis |
| database | MySQL + GORM 初始化、连接池、审计回调 | /pkg-reference/config-database-redis |
| redis | go-redis v9 客户端初始化 | /pkg-reference/config-database-redis |
| cache | 通用 Redis 缓存助手（group:key + singleflight） | /pkg-reference/config-database-redis |
| middleware | 全局 Gin 中间件（CORS/TraceID/I18n/Recover 等） | /pkg-reference/middleware |
| satoken | sa-token-go 鉴权初始化 + loginhelper 登录态存取 | /pkg-reference/satoken |
| oplog | 操作日志注解（装饰器），落库走 Recorder 回调 | /pkg-reference/oplog |
| excel | 结构体 tag 驱动的 xlsx 导出 | /pkg-reference/excel-tree |
| tree | 树形结构构建（复刻 hutool Tree 扁平 JSON） | /pkg-reference/excel-tree |
| oss | S3 兼容对象存储客户端工厂 | /pkg-reference/oss |
| push | SSE / WebSocket 消息推送端点 | /pkg-reference/push |
| captcha | 图形验证码生成（出题画图写 Redis） | /pkg-reference/captcha-encrypt |
| encrypt | AES/RSA 原语 + 接口加解密注解层 | /pkg-reference/captcha-encrypt |
| social | 三方账号 OAuth2 授权登录 | /pkg-reference/social |
| jsonx | 全局 JSON codec，超大 int64 自动转字符串 | /pkg-reference/jsonx-snowflake |
| snowflake | 雪花 ID 生成器 | /pkg-reference/jsonx-snowflake |
| constant | 通用常量（缓存组名、TTL、Redis key 前缀等） | /pkg-reference/jsonx-snowflake |
| enum | 带附加字段的枚举（BusinessType/OperatorType 等） | /pkg-reference/jsonx-snowflake |
| model | 跨模块领域模型（LoginUser） | /pkg-reference/jsonx-snowflake |
| repository | GORM 数据访问公共设施（分页/逻辑删除/审计） | /pkg-reference/repository |
| ratelimiter | 滑动窗口 ZSET + Lua 原子限流注解 | /pkg-reference/ratelimiter-repeatsubmit |
| repeatsubmit | SETNX 抢锁防重复提交注解 | /pkg-reference/ratelimiter-repeatsubmit |
| bcrypt | bcrypt 密码哈希 | /pkg-reference/misc |
| 纯文本单收件人邮件发送 | /pkg-reference/misc | |
| sms | 短信发送（Sender 接口，内置阿里云） | /pkg-reference/misc |
| ip | 从 HTTP 请求识别客户端 IP | /pkg-reference/misc |
| useragent | 解析 User-Agent | /pkg-reference/misc |
| strutil | 字符串工具（首字母大写、http 链接判定） | /pkg-reference/misc |
| i18n | 国际化词条与渲染（BCP 47 语言标记） | /pkg-reference/misc |