Aevons Framework

aevons-framework 是 Aevons 微服务体系的公共 Go 框架，负责统一配置加载、应用装配、数据库与 Redis 初始化、Consul 注册发现、Gin 中间件、统一响应、认证上下文和基础 CRUD 能力。

当前模块名：

github.com/calmlax/aevons-framework

当前要求：

• Go 1.25.0+

框架目标

• 统一各服务的启动方式
• 统一基础依赖初始化方式
• 统一 HTTP 响应格式
• 统一认证与权限中间件
• 统一健康检查与 OpenAPI 暴露
• 统一 Consul 服务注册与发现
• 统一 Repository / Service / Handler 的基础 CRUD 模式

目录说明

aevons-framework/
├── auth/
│   ├── context/
│   ├── errors/
│   ├── model/
│   ├── notifier/
│   └── store/
├── config/
├── consts/
├── core/
│   ├── base/
│   ├── consul/
│   └── server/
├── db/
├── errors/
├── grpcx/
├── middleware/
├── redis/
├── response/
├── utils/
├── xjson/
└── xlog/

主要模块职责：

• config/
  • 统一读取 config.yaml 和 config.{env}.yaml
  • 提供 server、consul、db、redis、auth、cors、xss、webauthn、gen 等配置结构
• core/app.go
  • 提供 core.App
  • 作为装配层上下文，统一承载 Config、Redis、DB
• core/server/
  • 注册通用健康检查 /health
  • 注册 OpenAPI 文档 /api/swagger.json
• core/consul/
  • 提供 Consul 注册、注销、健康等待、服务发现能力
  • 支持解析 grpc_port
• core/base/
  • 提供通用 BaseRepository、BaseService、BaseHandler
  • 统一列表、分页、详情、创建、更新、删除等基础流程
• db/
  • 初始化 GORM
  • 统一连接池配置
  • 注册模型回调
• redis/
  • 初始化 Redis
  • 支持 standalone、sentinel、cluster
  • 提供常用 KV / JSON / Hash / List / Set / ZSet 辅助方法
• middleware/
  • 请求日志
  • Request ID
  • CORS
  • XSS
  • Bearer Token 认证
  • 权限 / 角色校验
• auth/
  • 认证领域统一入口，保持对外兼容
  • 顶层保留 LoginUser、TokenStore、GetCurrentUser、NewRedisTokenStore 等对外 API
  • 内部已经拆为：
    • auth/model
    • auth/store
    • auth/context
    • auth/notifier
    • auth/errors
• response/
  • 统一返回：
    • response.Success
    • response.Fail
    • response.FailBy
• errors/
  • 统一错误码与错误定义
• grpcx/
  • gRPC 服务和客户端公共封装
• xjson/
  • 自定义 Gin JSON 绑定与编码初始化
• xlog/
  • 统一日志输出辅助
• consts/
  • 公共常量定义
• utils/
  • 字符串、结构体转换、校验辅助等通用工具

配置加载

配置通过 config/config.go 加载：

cfg, err := config.Load("configs", "development")

加载规则：

• 先加载 config.yaml
• 再按环境叠加 config.{env}.yaml
• env 通常来自 APP_ENV

典型配置结构：

server:
  name: auth-service
  host: 0.0.0.0
  port: 10701
  grpc_port: 10801
  env: development
  mode: debug

consul:
  enabled: true
  address: http://127.0.0.1:8500

db:
  driver: mysql
  dsn: root:123456@tcp(127.0.0.1:3306)/aevo_db?charset=utf8mb4&parseTime=True&loc=Asia%2FShanghai

redis:
  mode: standalone
  address: 127.0.0.1:6379

cors:
  enabled: true
  allowed_origins:
    - "*"

xss:
  enabled: true

标准启动方式

当前各服务推荐的标准启动流程：

1. config.Load
2. db.Init
3. redis.Init
4. core.NewApp
5. router.Setup(app)
6. http.Server
7. consul.NewManaged(...).Register(...)
8. 优雅关闭时 Deregister + Shutdown + redis.Close + db.Close

最小示例：

cfg, err := config.Load("configs", "development")
if err != nil {
    panic(err)
}

gdb, err := db.Init(&cfg)
if err != nil {
    panic(err)
}

redisClient, err := redis.Init(&cfg)
if err != nil {
    panic(err)
}

app := core.NewApp(&cfg, redisClient, gdb)
engine, err := router.Setup(app)
if err != nil {
    panic(err)
}

HTTP 通用能力

推荐在 Gin 服务里统一接入这些中间件：

• middleware.Logger()
• gin.Recovery()
• middleware.RequestID()
• middleware.CORS(...)
• middleware.XSSMiddleware(cfg)
• middleware.AuthMiddleware(...)

通用路由：

• /health
• /api/swagger.json

对应实现：

• core/server/server.go

认证与权限

当前框架的认证方式不是本地 JWT 验签，而是基于 Bearer Token + Redis Token Store。

认证中间件：

• middleware/auth.go

能力包括：

• 从 Authorization: Bearer ... 提取 token
• 从 Redis 读取 LoginUser
• 注入 Gin Context 和标准 context.Context
• 支持排除路径 auth.excludes
• 支持：
  • HasPermission
  • HasAnyPermission
  • HasRole
  • HasAnyRole

当前用户读取：

• auth/context.GetCurrentUser(ctx)
• auth/context.GetCurrentUserId(ctx)
• auth/context.GetCurrentRoleIds(ctx)
• auth/context.GetCurrentPermissions(ctx)

统一响应

框架统一 JSON 返回格式：

{
  "code": 0,
  "message": "success",
  "args": null,
  "data": {}
}

常用方法：

response.Success(c, data)
response.Fail(c, 400, 4001, "err.sys.bad_request")
response.FailBy(c, apperr.ErrInvalidBody)
response.FailServerError(c, "err.sys.server_error")

对应实现：

• response/response.go

数据库与基础 CRUD

数据库初始化：

• db/db.go

能力：

• MySQL / PostgreSQL 驱动切换
• 连接池设置
• 启动时 Ping
• 全局 DB 关闭

基础 CRUD：

• core/base/BaseRepository
• core/base/BaseService
• core/base/BaseHandler

适合快速构建：

• 列表
• 分页
• 详情
• 创建
• 更新
• 删除

Consul 注册发现

Consul 能力在：

• core/consul/consul.go

提供：

• Registry
• Managed
• Register
• Deregister
• Discover

特性：

• 注册前等待 /health 就绪
• 自动注册 HTTP 健康检查
• 支持把 grpc_port 写入 Service.Meta
• 发现时可解析 HTTP / gRPC 端口

Redis 能力

Redis 在：

• redis/redis.go

支持模式：

• standalone
• sentinel
• cluster

并提供常用方法封装：

• Set / Get / Del / Exists / Expire / TTL
• SetJSON / GetJSON
• HSet / HGet / HGetAll / HDel
• LPush / RPush / LPop / RPop
• SAdd / SMembers / SIsMember
• ZAdd / ZRange / ZScore

OpenAPI / Swagger

框架默认暴露：

• /api/swagger.json

加载顺序：

1. 优先 swaggo/swag 的 ReadDoc()
2. 兜底读取本地 api/swagger.json

这意味着各服务只要：

• 在 cmd/server/main.go 顶部补 Swagger 注释
• 生成 api/swagger.json

就能被框架统一暴露出去。

使用建议

• 这个框架更适合“服务模板统一”的场景，而不是做超重型平台抽象
• core.App 建议只停留在装配层，不要在业务层到处传
• 业务校验优先放在各服务自己的 handler / service 中，不要把业务逻辑塞进基础框架
• 公共能力进入框架前，先确认至少有两个以上服务会复用

当前适配状态

当前 aevons-cloud 中已经按这套方式适配的服务包括：

• auth-service
• system-service
• log-service
• gateway/console
• gen-service
• job-service

开发说明

如果本地项目使用 replace：

replace github.com/calmlax/aevons-framework => ../../aevons-framework

那么修改 aevons-framework 后，业务服务会直接引用当前工作区代码。