4.1 整体架构概览

概述

EasyGoAdmin 是前后端分离的多层架构：Vue3 单页应用通过统一信封与 Gin 后端交互，后端按"契约 → 接口 → 业务 → 数据"四件套分层，横切能力（认证、租户、日志、限流）全部收敛在中间件与全局钩子。

总体拓扑

┌─────────────────────────────────────────────┐
│  浏览器（Vue3 + ElementPlus 单页应用）        │
│  api 封装 · 动态菜单路由 · Pinia · v-permission│
└────────────────────┬────────────────────────┘
                     │ /api/**（统一 JSON 信封）
┌────────────────────▼────────────────────────┐
│  Gin HTTP 层                                 │
│  中间件链：trace→CORS→metrics→response→      │
│  ratelimit→demo→JWT→tenant→authz→op_log      │
│           │                                  │
│  router.Bind 反射注册（RouteSpec 表即路由）    │
└────────────────────┬────────────────────────┘
                     │ 签名固定的方法调用
┌────────────────────▼────────────────────────┐
│  四件套业务层                                 │
│  handler（极薄委托）→ service（ModuleSpec     │
│  声明 + 手写逻辑）→ repository（Ctx 入口）     │
│  dto（契约与校验标签）                         │
└────────────────────┬────────────────────────┘
                     │ GORM（全局钩子盖章 + Scope 注入）
┌────────────────────▼────────────────────────┐
│  数据层：MySQL / PostgreSQL / SQL Server /    │
│  SQLite / Oracle（+ Redis 缓存，失败降级内存） │
└─────────────────────────────────────────────┘

设计原则

原则	落点
一处声明，多处生效	RouteSpec 同源驱动注册/权限/日志/公开/OpenAPI；ModuleSpec 声明驱动查询/输出/写入
红线在入口执行，不靠自觉	软删过滤与租户隔离在 Ctx(ctx) 注入；物理删除被钩子拦截；审计字段钩子补齐
薄接口层，厚业务层	handler 只委托；规则在 service；数据在 repository
契约稳定	dto json 标签名即 API 字段名，前后端与生成器共同依赖
fail-fast + 优雅降级	配置非法拒绝启动；Redis 缺失降级内存；接线缺失告警降级（WireCheck）
合法逃生舱	写不进声明的复杂逻辑手写方法，不硬塞框架

请求的一生（简版）

1. 中间件链逐层处理（追踪、跨域、指标、响应包裹、限流、演示、认证、租户、鉴权、日志采集）
2. router.Bind 包装函数按 path > body > query 绑定参数并校验
3. handler 委托 service；service 经 ModuleSpec / 手写逻辑完成业务
4. repository.Ctx 在 SQL 构建前注入红线条件
5. 结果回到 response 中间件统一封装信封返回；操作日志异步落库

逐层展开见 4.2 请求处理链路。

代码域划分

域	位置	职责边界
装配	internal/server、cmd/api	启动序列、优雅关闭
HTTP	internal/router、internal/middleware	路由注册与横切处理
业务	internal/handler/service/repository/model/dto	四件套
基础设施	utility/*	无业务语义的通用能力
后台任务	internal/task	定时任务（init 自注册）
前端	ui/*	独立工程，经信封对接

下一步

→ 4.2 请求处理链路