# 4.1 整体架构概览

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

## 总体拓扑

```text
┌─────────────────────────────────────────────┐
│  浏览器（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 请求处理链路](/zh/architecture/request-flow.html)。

## 代码域划分

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

## 下一步

→ [4.2 请求处理链路](/zh/architecture/request-flow.html)