三、整体架构
本章将介绍 Kratos 的整体架构，帮助读者建立对框架的整体认知。
3.1 架构总览
3.1.1 分层架构图
┌─────────────────────────────────────────────────────────────────────────┐
│ Kratos 架构 │
└─────────────────────────────────────────────────────────────────────────┘
用户代码
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Application 层 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ kratos.New() │ │
│ │ │ │
│ │ 1. 创建 App │ │
│ │ 2. 应用配置 (Option) │ │
│ │ 3. 构建服务 (build) │ │
│ │ 4. 启动服务 (Run) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Server 层 │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ HTTP Server │ │ gRPC Server │ │
│ │ │ │ │ │
│ │ - 路由 (Router) │ │ - 服务注册 │ │
│ │ - 中间件 │ │ - 拦截器 │ │
│ │ - 处理器 │ │ - 流处理 │ │
│ │ - 适配器 │ │ - 适配器 │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Middleware 层 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Recovery │ │ Logging │ │ Tracing │ │ Validate │ │
│ │ 错误恢复 │ │ 日志 │ │ 链路追踪 │ │ 验证 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Metrics │ │ CORS │ │ RateLim │ │
│ │ 指标 │ │ 跨域 │ │ 限流 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Transport 层 │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ HTTP 传输 │ │ gRPC 传输 │ │
│ │ │ │ │ │
│ │ - net/http │ │ - grpc/grpc │ │
│ │ - 路由匹配 │ │ - 协议转换 │ │
│ │ - 请求解析 │ │ - 流处理 │ │
│ │ - 响应编码 │ │ - 编解码 │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 支撑层 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Registry │ │ Selector │ │ Breaker │ │ Config │ │
│ │ 服务注册 │ │ 负载均衡 │ │ 熔断 │ │ 配置 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Log │ │ Errors │ │ Wire │ │
│ │ 日志 │ │ 错误 │ │ 依赖注入 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘3.1.2 请求处理流程
HTTP/gRPC 请求
│
▼
┌──────────────────┐
│ Transport Layer │ 传输层：接收请求、解析数据
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Middleware Layer │ 中间件层：日志、认证、限流等
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Server Layer │ 服务层：路由匹配、处理器调用
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Business Logic │ 业务层：具体业务逻辑
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Data Layer │ 数据层：数据库、缓存操作
└────────┬─────────┘
│
▼
响应返回3.2 核心数据结构
3.2.1 App 结构体
go
// kratos/app.go
type App struct {
// 上下文，用于通知退出
ctx context.Context
// 取消函数
cancel context.CancelFunc
// 配置选项
opts *options
// 等待组，用于等待所有服务退出
wg sync.WaitGroup
// 互斥锁
mu sync.RWMutex
}
// options 包含所有可配置项
type options struct {
// 服务器列表（HTTP、gRPC）
servers []Server
// 日志
logger log.Logger
// 名称
name string
// 版本
version string
// 元数据
metadata map[string]string
// 信号通道
sigCh chan os.Signal
}图解 App 结构：
┌─────────────────────────────────────────┐
│ App 结构 │
├─────────────────────────────────────────┤
│ │
│ ctx: context.Context ───┐ │
│ │ │
│ cancel: func() ──────────┼──▶ 退出控制 │
│ │ │
│ opts: *options ──────────┼──┐ │
│ │ │ │
│ wg: sync.WaitGroup ──────┼──┤ 同步控制 │
│ │ │ │
│ mu: sync.RWMutex ────────┴──┴── 锁 │
│ │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ options 结构 │
├─────────────────────────────────────────┤
│ │
│ servers: []Server ──→ [HTTP, gRPC] │
│ logger: log.Logger │
│ name: "my-app" │
│ version: "v1.0.0" │
│ metadata: map[string]string │
│ │
└─────────────────────────────────────────┘3.2.2 Server 接口
go
// server.go
type Server interface {
// Start 启动服务
// 启动监听，开始接受请求
Start() error
// Stop 停止服务
// 立即停止服务
Stop() error
// GracefulStop 优雅停止
// 等待正在处理的请求完成后停止
GracefulStop() error
}Server 实现类：
Server 接口
│
├── HTTPServer (HTTP 服务)
│ │
│ ├── network: "tcp"
│ ├── address: ":8080"
│ ├── timeout: 1s
│ ├── router: *Router
│ └── middlewares: []Middleware
│
└── GRPCServer (gRPC 服务)
│
├── network: "tcp"
├── address: ":50051"
├── timeout: 1s
├── server: *grpc.Server
└── unaryInterceptors: []grpc.UnaryServerInterceptor3.2.3 Context 结构
go
// context.go
type Context struct {
// 请求
Request *http.Request
ResponseWriter http.ResponseWriter
// 路径参数
params Params
// 请求路径
path string
// 方法
method string
// 原始数据
data map[string]interface{}
// 错误
err error
// 链路追踪
traceInfo *TraceInfo
}Context 生命周期：
请求到达
│
▼
┌───────────────────┐
│ NewContext() │ 创建 Context
└───────────────────┘
│
├── 设置 Request/Response
├── 设置 Path/Method
│
▼
┌───────────────────┐
│ 执行中间件链 │ 使用 Context 传递数据
└───────────────────┘
│
├── c.Set("key", value) // 设置值
├── c.Get("key") // 获取值
├── c.Param("id") // 获取路径参数
├── c.Query("name") // 获取查询参数
├── c.Body() // 获取请求体
│
▼
┌───────────────────┐
│ 返回响应 │ 使用 Context 返回
└───────────────────┘
│
├── c.JSON(200, data) // JSON 响应
├── c.String(200, "ok") // 字符串响应
├── c.Error(err) // 错误响应
│
▼
请求结束，Context 销毁3.3 模块关系
3.3.1 模块依赖图
┌─────────────────────────────────────────────────────────────┐
│ 模块依赖关系 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 用户代码 │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ App │ ◄── 依赖 ──► options │
│ └───────┬───────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌───────────────┐ │
│ │ │ Server │ ◄── 依赖 ──► Middleware │
│ │ └───────┬───────┘ │
│ │ │ │ │
│ │ │ ▼ │
│ │ │ ┌───────────────┐ │
│ │ │ │ Router │ ◄── 依赖 ──► Middleware │
│ │ │ └───────┬───────┘ │
│ │ │ │ │ │
│ │ │ │ ▼ │
│ │ │ │ ┌───────────────┐ │
│ │ │ │ │ Handler │ ◄── 依赖 ──► Logic │
│ │ │ │ └───────────────┘ │
│ │ │ │ │
│ │ ▼ ▼ │
│ │ ┌───────────────┐ │
│ │ │ Transport │ ◄── 依赖 ──► net/http, grpc │
│ │ └───────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ 支撑层 │ Registry, Selector, Breaker, Config │
│ └───────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘3.3.2 数据流图
┌─────────────────────────────────────────────────────────────┐
│ 完整数据流 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 启动阶段 │
│ ┌──────────┐ │
│ │ kratos.New() │ │
│ └─────┬──────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ app.build() │ ──► 启动 HTTP/gRPC Server │
│ └─────┬──────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ app.Run() │ ──► 等待信号、优雅关闭 │
│ └──────────┘ │
│ │
│ 2. 请求阶段 │
│ ┌──────────┐ │
│ │ 请求进入 │ │
│ └─────┬──────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ Transport │ ──► 解析请求、路由匹配 │
│ └─────┬──────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ Middleware│ ──► 日志、认证、限流 │
│ └─────┬──────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ Router │ ──► 找到对应的 Handler │
│ └─────┬──────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ Handler │ ──► 调用业务逻辑 │
│ └─────┬──────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ Logic │ ──► 访问数据库、缓存 │
│ └─────┬──────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ 响应返回 │ │
│ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘3.4 目录结构
3.4.1 Kratos 源码目录
kratos/
├── cmd/ # 入口和工具
│ ├── kratos/ # 主程序
│ │ └── main.go
│ └── goctl/ # 代码生成工具
│ └── main.go
│
├── contrib/ # 第三方集成
│ ├── config/ # 配置中心 (Apollo, etcd, nacos)
│ ├── registry/ # 服务注册 (Consul, etcd, kubernetes)
│ ├── tracing/ # 链路追踪 (OpenTelemetry, Jaeger)
│ └── metrics/ # 监控 (Prometheus)
│
├── errors/ # 错误处理
│ └── errors.go
│
├── examples/ # 示例代码
│ ├── http/
│ ├── grpc/
│ └── middleware/
│
├── log/ # 日志
│ └── log.go
│
├── metadata/ # 元数据
│ └── metadata.go
│
├── middleware/ # 中间件
│ ├── recovery/ # 错误恢复
│ ├── logging/ # 日志
│ ├── tracing/ # 链路追踪
│ ├── validate/ # 参数验证
│ └── ... (更多中间件)
│
├── registry/ # 服务注册发现
│ ├── consul/
│ ├── etcd/
│ └── kubernetes/
│
├── router/ # 路由
│ └── router.go
│
├── selector/ # 负载均衡
│ ├── random/
│ ├── roundrobin/
│ └── weighted/
│
├── transport/ # 传输层
│ ├── grpc/
│ │ ├── server.go
│ │ ├── client.go
│ │ └── ...
│ └── http/
│ ├── server.go
│ ├── client.go
│ └── ...
│
├── util/ # 工具函数
│ ├── context/
│ ├── reflect/
│ └── ...
│
├── version/ # 版本信息
│ └── version.go
│
└── wire/ # 依赖注入
└── wire.go3.4.2 典型项目结构
myapp/
├── api/ # Protobuf 定义
│ └── user/
│ └── v1/
│ ├── user.proto
│ └── user.pb.go
│
├── cmd/ # 入口
│ └── user-api/
│ └── main.go
│
├── configs/ # 配置文件
│ └── user-api.yaml
│
├── internal/ # 内部包
│ ├── config/ # 配置定义
│ │ └── config.go
│ ├── handler/ # HTTP 处理
│ │ ├── user.go
│ │ └── routes.go
│ ├── logic/ # 业务逻辑
│ │ └── user.go
│ ├── model/ # 数据模型
│ │ └── user.go
│ ├── server/ # 服务器配置
│ │ └── server.go
│ ├── service/ # 服务实现
│ │ └── user.go
│ ├── svc/ # 服务上下文
│ │ └── service.go
│ └── types/ # 类型定义
│ └── types.go
│
├── third_party/ # 第三方 proto
│ └── google/
│
├── go.mod
└── go.sum3.5 本章小结
┌─────────────────────────────────────────────────────────────┐
│ 本章总结 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ✓ Kratos 采用分层架构 │
│ └── Application → Server → Middleware → Transport │
│ │
│ ✓ 核心数据结构：App、Server、Context │
│ │
│ ✓ 模块之间通过接口解耦 │
│ │
│ ✓ 典型的项目结构便于团队协作 │
│ │
└─────────────────────────────────────────────────────────────┘下章预告
下一章我们将学习启动流程详解，深入分析 Kratos 是如何启动的。
敬请期待！